npm : npm install amethystjs
yarn : yarn add amethystjs
pnpm : pnpm add amethystjs
With this powerful framework you can :
- Create commands
- Handle errors
- Create a precondition
- Use events
- Handle autocomplete interactions
- Wait for messages
- Wait for interactions
- Handle buttons
- Handle modals
- Make a control panel
- Set custom prefixes
- Wait a little time
- Paginate embeds
- log4js
See an example right here
Import the client
import { AmethystClient } from 'amethystjs';
const client = new AmethystClient({
// Discord.js client options
}, {
botName: "your bot's name", // Optionnal
botNameWorksAsPrefix: true, // Wether if we can use the bot's name as prefix - optionnal
commandsFolder: './yourCommandsFolder', // Optionnal
eventsFolder: './yourEventsFolder', // Optionnal
prefix: "bot's prefix", // Optionnal
strictPrefix: true, // Wether if the prefix must be exactly the same - optionnal
mentionWorksAsPrefix: true, // Wether if we can use the bot by mentionning it
token: "Your bot's token",
debug: false, // Enable debug mode (get a lot of messages in the console) - optionnal
defaultCooldownTime: 5, // Default cooldown time
preconditionsFolder: "./yourPreconditionsFolder", // Specify the preconditions folder - optionnal
autocompleteListenersFolder: "./autocompleteListenersFolder", // Specify the autocomplete folder - optionnal
buttonsFolder: './buttonsFolder', // Specify the button folder for button handlers - optionnal
customPrefixAndDefaultAvailable?: true, // Specify if the default prefix is usable when a custom prefix is set - optionnal
modalHandlersFolder: "./yourModalHandlersFolder", // Specify the modal handlers folder
debbugColors: 'none', // 'none' | 'icon' | 'line', defines if the debugger uses colors - optional
commandsArchitecture: 'simple', // 'simple' | 'double', if simple, the commands inside the commandsFolder will be read, if double, the commands inside the directories of the commandsFolder will be read
eventsArchitecture: 'simple' // 'simple' | 'double', if simple, the events inside the eventsFolder will be read, if double, the events inside the directories of the eventsFolder will be read
});
client.start({
// All are optionnal
loadCommands: true, // Load commands
loadEvents: true, // Load events
loadPreconditions: true, // Load preconditions
loadAutocompleteListeners: true, // Load autocomplete listeners
loadModals: true // Load modals handlers
});
const { AmethystClient } = require('amethystjs');
const client = new AmethystClient({
// Discord.js client options
}, {
botName: "your bot's name", // Optionnal
botNameWorksAsPrefix: true, // Wether if we can use the bot's name as prefix - optionnal
commandsFolder: './yourCommandsFolder', // Optionnal
eventsFolder: './yourEventsFolder', // Optionnal
prefix: "bot's prefix", // Optionnal
strictPrefix: true, // Wether if the prefix must be exactly the same - optionnal
mentionWorksAsPrefix: true, // Wether if we can use the bot by mentionning it
token: "Your bot's token",
debug: false, // Enable debug mode (get a lot of messages in the console) - optionnal
defaultCooldownTime: 5, // Default cooldown time
preconditionsFolder: "./yourPreconditionsFolder", // Specify the preconditions folder - optionnal
autocompleteListenersFolder: "./autocompleteListenersFolder", // Specify the autocomplete folder - optionnal
buttonsFolder: './buttonsFolder', // Specify the button folder for button handlers - optionnal
customPrefixAndDefaultAvailable?: true, // Specify if the default prefix is usable when a custom prefix is set - optionnal
modalHandlersFolder: "./yourModalHandlersFolder", // Specify the modal handlers folder
debbugColors: 'none', // 'none' | 'icon' | 'line', defines if the debugger uses colors - optional
commandsArchitecture: 'simple' // 'simple' | 'double', if simple, the commands inside the commandsFolder will be read, if double, the commands inside the directories of the commandsFolder will be read
eventsArchitecture: 'simple', // 'simple' | 'double', if simple, the events inside the eventsFolder will be read, if double, the events inside the directories of the eventsFolder will be read
commandLocalizationsUsedAsNames: true // Allows the localized names to be used as message command names
});
client.start({
// All are optionnal
loadCommands: true, // Load commands
loadEvents: true, // Load events
loadPreconditions: true, // Load preconditions
loadAutocompleteListeners: true // Load autocomplete listeners
});
Go in your commands folder, and create a new file.
The emplacement of the file depends of your architecture ( commandsArchitecture
, defined when creating the client )
If it is simple, it looks like this :
|_commands
|_info.ts/js
|_ban.ts/js
If you configured it to double, it looks like this :
|_commands
|_moderation
|_ban.ts/js
|_info.ts/js
Import AmethystCommand and exports it
import { AmethystCommand } from 'amethystjs';
export default new AmethystCommands({
name: 'command name', // Command name
description: "Description of the command", // Description - required
cooldown: 5, // Cooldown time
permissions: [ 'Administrator' ], // Permissions for the user - optionnal
clientPermissions: [ 'ManageChannels' ], // Permissions for the bot - optionnal
preconditions: [ ], // Preconditions for the command - optionnal
messageInputChannelTypes: [], // Channel types allowed for message input running - optionnal
aliases: ['alias 1', 'alias 2', '...'], // Command aliases - optionnal
messageInputDescription: "Description of the message command (optionnal)", // Message description - optionnal
userContextName: "name of the user context command", // Name of the user context command - optionnal
messageContextName: "Name of the message context command" // Name of the message context command - optionnal
})
.setMessageRun((options) => {
// Write code for message commands (optionnal)
})
.setChatInputRun((options) => {
// Write code for slash commands (optionnal)
}).setUserContextMenuRun((options) => {
// Write code for user context menu command (optionnal)
})
.setMessageContextMenuRun((options) => {
// Write code for message context menu command (optionnal)
})
const { Amethystcommand } = require('amethystjs');
module.exports = new AmethystCommands({
cooldown: 5, // Cooldown time
name: 'command name', // Command name
permissions: [ 'Administrator' ], // Permissions for the user - optionnal
clientPermissions: [ 'ManageChannels' ], // Permissions for the bot - optionnal
preconditions: [ ], // Preconditions for the command - optionnal
messageInputChannelTypes: [], // Channel types allowed for message input running - optionnal
aliases: ['alias 1', 'alias 2', '...'], // Command aliases - optionnal
description: "Description of the command", // Description - required
messageInputDescription: "Description of the message command (optionnal)", // Message description - optionnal
userContextName: "name of the user context command", // Name of the user context command - optionnal
messageContextName: "Name of the message context command" // Name of the message context command - optionnal
})
.setMessageRun((options) => {
// Write code for message commands (optionnal)
})
.setChatInputRun((options) => {
// Write code for slash commands (optionnal)
}).setUserContextMenuRun((options) => {
// Write code for user context menu command (optionnal)
})
.setMessageContextMenuRun((options) => {
// Write code for message context menu command (optionnal)
})
Use the commandDenied
event to handle command denietions
Use the commandError
event to handle command errors
Amethyst JS allows you to create your own preconditions (because it's fun 🙂)
First, import the Precondition from Amethyst
import { Precondition } from 'amethystjs';
export default new Precondition("Your precondition's name")
.setChatInputRun((options) => {
// Run your precondition here for slash commands
// You have to return something like this :
return {
ok: true,
message: 'Message in case of fail',
metadata: {/* some more datas */},
interaction: options.interaction,
type: 'chatInput'
}
})
.setMessageRun((options) => {
// Run your precondition here for message commands
// Return something like this
return {
ok: true,
message: "Message in case of fail",
metadata: { /* some extra datas */ },
type: 'message',
channelMessage: options.message
}
}).setModalRun((options) => {
// Run your modal precondition here
// Return something like so
return {
ok: true,
message: "Message in case of fail",
metadata: { /* some data here */ },
type: 'modal',
modal: options.modal
}
}).setUserContextMenuRun((options) => {
// Run your precondition for user context command here
// Return something like this
return {
ok: true,
message: "Message in case of fail",
metadata: { /* Some more datas */ },
type: 'userContextMenu',
contextMenu: options.interaction
}
}).setMessageContextMenuRun((options) => {
// Run your precondition for message context command here
// Return something like this
return {
ok: true,
message: "Message in case of fail",
metadata: { /* Some more datas */ },
type: 'messageContextMenu',
contextMenu: options.interaction
}
})
const { Precondition } = require('amethystjs');
module.exports = new Precondition("Your precondition's name")
.setChatInputRun((options) => {
// Run your precondition here for slash commands
// You have to return something like this :
return {
ok: true,
message: 'Message in case of fail',
metadata: {/* some more datas */},
interaction: options.interaction,
type: 'chatInput'
}
})
.setMessageRun((options) => {
// Run your precondition here for message commands
// Return something like this
return {
ok: true,
message: "Message in case of fail",
metadata: { /* some extra datas */ },
type: 'message',
channelMessage: options.message
}
})
.setButtonRun((options) => {
// Run your precondition here for button
// You have to return something like this :
return {
ok: true,
message: 'Message in case of fail',
metadata: {/* Some extra options */},
button: options.button,
type: 'button'
}
}).setModalRun((options) => {
// Run your modal precondition here
// Return something like so
return {
ok: true,
message: "Message in case of fail",
metadata: { /* some data here */ },
type: 'modal',
modal: options.modal
}
}).setUserContextMenuRun((options) => {
// Run your precondition for user context command here
// Return something like this
return {
ok: true,
message: "Message in case of fail",
metadata: { /* Some more datas */ },
type: 'userContextMenu',
contextMenu: options.interaction
}
}).setMessageContextMenuRun((options) => {
// Run your precondition for message context command here
// Return something like this
return {
ok: true,
message: "Message in case of fail",
metadata: { /* Some more datas */ },
type: 'messageContextMenu',
contextMenu: options.interaction
}
})
To use a custom precondition in a command, use it like so :
import yourPrecondition from 'your precondition file';
import { AmethystCommand } from 'amethystjs';
export default new AmethystCommand({
name: 'name',
preconditions: [ yourPrecondition ]
})
const precondition = require('your precondition file');
const { AmethystCommand } = require('amethystjs');
module.exports = new AmethystCommand({
name: 'name',
preconditions: [ precondition ]
});
Go in your events folder and add a new file
The emplacement of the file depends of your architecture ( eventsArchitecture
, defined when creating the client )
If it is simple, it looks like this :
|_events
|_ready.ts/js
|_commandDenied.ts/js
If you configured it to double, it looks like this :
|_events
|_bot
|_ready.ts/js
|_guildCreate.ts/js
|_users
|_commandDenied.ts/js
import { AmethystEvent } from 'amethystjs';
export default new AmethystEvent('eventName', (/* event options */) => {
// Run your event
})
const { AmethytsEvent } = require('amethystjs');
module.exports = new AmethystEvent('eventName',/* event options */ () => {
// Run your event
})
Amethyst JS adds events to the Discord Client. Here is the list of the events you can resiter via Events handler :
Event | When its activated | arguments list | Types |
---|---|---|---|
amethystDebug |
When the client debugs something | message | string |
commandDenied |
When a precondition stops a command | command, reason | commandDeniedPayload, deniedReason |
commandError |
When an error occurs | command, reason | commandDeniedPayload, errorReason |
buttonInteraction |
When a button is pressed | interaction, message | ButtonInteraction, Message |
modalSubmit |
When a modal interaction is created | interaction | ModalSubmitInteraction |
buttonDenied |
When a button is stopped because of a precondition | button | buttonDenied |
selectMenuInteraction |
When any select menu is interacted | selector | AnySelectMenuInteraction |
stringSelectInteraction |
When a string select menu is interacted | selector | StringSelectMenuInteraction |
roleSelectMenuInteraction |
When a role select menu is interacted | selector | RoleSelectMenuInteraction |
userSelectInteraction |
When an user select menu is interacted | selector | UserSelectMenuInteraction |
channelSelectInteraction |
When a channel select menu is interacted | selector | ChannelSelectMenuInteraction |
mentionableSelectInteraction |
When a mentionable select menu is interacted | selector | MentionableSelectMenuInteraction |
modalRejected |
When a modal is stopped because of a precondition | reason | ModalDenied |
Autocomplete listeners are things that replies to an autocomplete interaction (interaction options with a lot of choices)
Go in your autocomplete listeners and create a new file
import { AutocompleteListener } from 'amethystjs';
export default new AutocompleteListener({
commandName: [ { commandName: 'command name here' }, { commandName: 'another command name here', optionName: 'optionnal option name in the command here' } ],
run: (options) => {
// Make your choice here are return :
return [ {name: 'Name', value: 'value', nameLocalizations: {} } ]
}
});
const { AutocompleteListener } = require('amethystjs');
module.exports = new AutocompleteListener({
commandName: [ { commandName: 'command name here' }, { commandName: 'another command name here', optionName: 'optionnal option name in the command here' } ],
run: (options) => {
// Make your choice here are return :
return [ {name: 'Name', value: 'value', nameLocalizations: {} } ]
}
});
As you've maybe noticed, commandName
is an array containing a commandName and a potential optionName.
It means that the autocomplete will be applied to every command with the name included in the array, and if optionName is specified, it will also check if the option name correspond to the one specified.
Amethyst JS can handle button interactions for you.
Go to your buttons folder and create a new file
import { ButtonHandler } from 'amethystjs';
export default new ButtonHandler({
customId: 'buttonCustomId',
permissions: ['Permissions required for the user'],
clientPermissions: ["Permissions required for the client"],
identifiers: [ 'optionnal array of more button custom identifiers' ]
})
.setRun((options) => {
// Execute your code here
})
const { ButtonHandler } = require('amethystjs');
module.exports = new ButtonHandler({
customId: 'buttonCustomId',
permissions: ['Permissions required for the user'],
clientPermissions: ["Permissions required for the client"],
identifiers: [ 'optionnal array of more button custom identifiers' ]
})
.setRun((options) => {
// Execute your code here
})
If you specify permissions, you have to handle it in case of error.
The customId and identifiers propreties are button custom ID
To handle it, create a new event and record for the buttonDenied
event.
You can wait for messages using amethyst JS.
You'll use waitForMessage()
function.
import { waitForMessage } from 'amethystjs';
// Important : this works only in an async function
// For exemple, I'll do a simple client.on('messageCreate') to show you how to use it
client.on('messageCreate', async(message) => {
if (message.content === '!ping') {
await message.channel.send(`Would you like me to reply ?\nReply by \`yes\` or \`no\``);
const reply = await waitForMessage({
user: message.author,
whoCanReact: 'useronly',
channel: message.channel,
time: 120000
});
if (!reply) message.channel.send(`You haven't replied :/`);
if (reply.content === 'yes') message.reply("Pong !");
}
})
const { waitForMessage } = require('amethystjs');
// Important : this works only in an async function
// For exemple, I'll do a simple client.on('messageCreate') to show you how to use it
client.on('messageCreate', async(message) => {
if (message.content === '!ping') {
await message.channel.send(`Would you like me to reply ?\nReply by \`yes\` or \`no\``);
const reply = await waitForMessage({
user: message.author,
whoCanReact: 'useronly',
channel: message.channel,
time: 120000
});
if (!reply) message.channel.send(`You haven't replied :/`);
if (reply.content === 'yes') message.reply("Pong !");
}
})
Amethyst JS allows you to wait for interaction responses, like a select menu or a button click
import { waitForInteraction } from 'amethystjs';
import { ButtonBuilder, ActionRowBuilder, componentType, Message } from 'discord.js';
// This function works only in an async function.
// Here i'm gonna show you in a very simple async function.
// In this exemple, interaction is already defined
(async() => {
const msg = await interaction.reply({
message: "Yes or no",
components: [ new ActionRowBuilder({
components: [
new ButtonBuilder({ label: 'Yes', style: ButtonStyle.Success, customId: 'yes' }),
new ButtonBuilder({ label: 'No', style: ButtonStyle.Danger, customId: 'no' })
]
}) as ActionRowBuilder<ButtonBuilder>]
}) as Message<true>;
const reply = await waitForInteraction({
message: msg,
time: 120000,
whoCanReact = 'useronly',
user: interaction.user,
componentType: componentType.Button
});
if (!reply || reply.customId === 'no') return interaction.editReply("Ok, no");
interaction.editReply("Yes !");
})()
const { waitForInteraction } = require('amethystjs');
const { ActionRowBuilder, ButtonBuilder, componentType } = require('discord.js');
// This function works only in an async function.
// Here i'm gonna show you in a very simple async function.
// In this exemple, interaction is already defined
(async() => {
const msg = await interaction.reply({
message: "Yes or no",
components: [ new ActionRowBuilder({
components: [
new ButtonBuilder({ label: 'Yes', style: ButtonStyle.Success, customId: 'yes' }),
new ButtonBuilder({ label: 'No', style: ButtonStyle.Danger, customId: 'no' })
]
}) ]
})
const reply = await waitForInteraction({
message: msg,
time: 120000,
whoCanReact = 'useronly',
user: interaction.user,
componentType: componentType.Button
});
if (!reply || reply.customId === 'no') return interaction.editReply("Ok, no");
interaction.editReply("Yes !");
})()
The Amethyst client has a prefixesManager
proprety that allows you to set different prefixes for different servers
Here is the summary of the prefixes manager
Proprety | Type |
---|---|
setPrefix |
Method |
getPrefix |
Method |
samePrefix |
Method |
list |
Proprety |
json |
Proprety |
Set a prefix for a server.
const prefixes = [
{ guildId: '1324', prefix: '!' },
{ guildId: '4321', prefix: '!!' },
{ guildId: '1324', prefix: '??' }
];
for (const data of prefixes) {
client.prefixesManager.setPrefix({
guildId: data.guildId,
prefix: data.prefix
});
}
Get the custom prefix of a server.
Returns default prefix if the server has no custom prefix
client.prefixesManager.getPrefix('guild ID')
Return all the servers with the same prefix
The method returns an array of objects with 2 propreties :
{
guildId: string;
prefix: string
}
client.prefixesManager.samePrefix('!')
You can get the prefixes data to manage it if you want.
This method will return a map. If you want to get it as an array, use json method instead
The map has 2 propreties :
Map<
string, // Corresponding to the guild ID
string // Corresponding to the prefix
>
client.prefixesManager.list;
You can get the prefixes data to manage it if you want.
This method will return an array. Use map method to get it as a map if you need.
The array has 2 propreties :
{
guildId: string;
prefix: string;
}[];
client.prefixesManager.json;
You can wait for a certain time before executing something else with Amethyst JS. Here is how to use the wait method
// Import wait
import { wait } from 'amethystjs'
// Use it in an async function, it wont work otherwise
(async() => {
await wait(1000); // Wait 1s
await wait(1, 's'); // Wait 1s
await wait(1, 'm'); // Wait 1 minute
})();
// Import wait
const { wait } = require('amethystjs');
// Use it in an async function, it wont work otherwise
(async() => {
await wait(1000); // Wait 1s
await wait(1, 's'); // Wait 1s
await wait(1, 'm'); // Wait 1m
})()
You can use modal handlers with Amethyst JS, it can handle modals trought an object inside the modals handler folder
import { ModalHandler } from 'amethystjs';
export default new ModalHandler({
modalId: ['identifiers of modals to be handled'],
name: "Name of the handler"
}).setRun((opts) => {
opts.modal;
opts.user;
});
const { ModalHandler } = require('amethystjs');
module.exports = new ModalHandler({
modalId: ['identifiers of modals to be handled'],
name: "Name of the handler"
}).setRun((opts) => {
opts.modal;
opts.user;
});
You can make a control panel for your bot
You need to have the client created
Here's how to create a control panel
import { AmethystClient, ControlPanel } from 'amethystjs';
import rebootHandler from './buttons/reboot';
import const { panelEmbed } from './contents/embeds';
const client = new AmethystClient({
intents: ['Guilds']
}, {
token: 'token',
debug: true,
buttonsFolder: './dist/buttons'
})
client.start({}) // You can start it after the panel is created if you want
const panel = new ControlPanel({
client: client,
channelID: 'Id of the channel where the panel will be',
deleteMessages: true, // Delete the other messages in the channel - optional
pin: true, // Pin the panel - optional
content: {
content: "Control panel",
embeds: [panelEmbed]
} // Content of the message - optional
});
const { AmethystClient, ControlPanel } = require('amethystjs');
const { panelEmbed } = require('./contents/embeds');
const client = new AmethystClient({
intents: ['Guilds']
}, {
token: 'token',
debug: true,
buttonsFolder: './dist/buttons'
})
client.start({}) // You can start it after the panel is created if you want
const panel = new ControlPanel({
client: client,
channelID: 'Id of the channel where the panel will be',
deleteMessages: true, // Delete the other messages in the channel - optional
pin: true, // Pin the panel - optional
content: {
content: "Control panel",
embeds: [panelEmbed]
} // Content of the message - optional
});
Now you surely want to register your buttons
import rebootHandler from './buttons/reboot';
panel.registerButton({
label: 'Disconnect voice',
handler: 'panel.disconnect', // Use the handler that handles 'panel.disconnect'
style: 'Primary'
})
.registerButton({
label: 'Reboot',
style: 'Danger',
handler: rebootHandler // Use the imported handler
})
const rebootHandler = require('./buttons/reboot');
panel.registerButton({
label: 'Disconnect voice',
handler: 'panel.disconnect', // Use the handler that handles 'panel.disconnect'
style: 'Primary'
})
.registerButton({
label: 'Reboot',
style: 'Danger',
handler: rebootHandler // Use the imported handler
})
Once it's done, don't forget to start the panel with panel.start()
method
Amethyst JS allows you to log things in a log file with log4js
This object has two methods
The trace()
method allows you to write something in the log file
const { log4js } = require('amethystjs');
log4js.trace("Something just happened");
The config()
method configs log4js.
For now, you can config :
- Trigger the time displaying
- Time displaying format
- log file
- Add a
onLog
event - Object indentation
const { log4js } = require('amethystjs');
log4js.config('displayTime', true);
log4js.config('onLog', (message) => {
console.log(`Log4JS traced something`)
})
log4js.config('file', 'logs.txt')
log4js.config('objectIndentation', 1)
log4js.config('displayTimeFormat', (time) => `[${time.getDay()}/${time.getMonth()}/${time.getFullYear()}:${time.getHours()}:${time.getMinutes()}:${time.getSeconds()}]`)
The Greensky's paginator under the name of AmethystPaginator
. The method is the exact same than the package.
Here are some repositories that use Amethyst JS :
- Lofi Girl by Greensky (Amethyst JS v1.7.1)
- Draver Bot by Draver Industries (Amethyst JS v1.7.2)
Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the documentation.