amethystjs
v1.7.5
Published
A complete framework for Discordjs v14
Downloads
163
Maintainers
Readme
Installation
npm : npm install amethystjs
yarn : yarn add amethystjs
pnpm : pnpm add amethystjs
Features
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
Create Amythyst Client
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
});
Create a command
Go in your commands folder, and create a new file.
Architecture
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
Command creation
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)
})
Handle errors
Use the commandDenied
event to handle command denietions
Use the commandError
event to handle command errors
Record your own preconditions
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 ]
});
Registering events
Go in your events folder and add a new file
Architecture of events
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
})
Events list
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
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.
Button handler
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.
Wait for messages
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 !");
}
})
Wait for interactions
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 !");
})()
Register custom prefixes
The Amethyst client has a prefixesManager
proprety that allows you to set different prefixes for different servers
:warning: Important The client does not save the prefixes, you have to use a database to save it for your bot. The manager register prefixes only to use it with Amethyst client
Summary
Here is the summary of the prefixes manager
| Proprety | Type |
|----------|------|
| setPrefix
| Method |
| getPrefix
| Method |
| samePrefix
| Method |
| list
| Proprety |
| json
| Proprety |
setPrefix
Set a prefix for a server.
:warning: Use it when you load your bot, in a ready event, for example.
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
});
}
getPrefix
Get the custom prefix of a server.
Returns default prefix if the server has no custom prefix
client.prefixesManager.getPrefix('guild ID')
Same prefix
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('!')
prefixes list
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;
Prefixes json
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;
Wait
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
})()
Modal Handlers
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;
});
Make a control panel
You can make a control panel for your bot
You need to have the client created
Creation
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
});
Register a button
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
Log4JS
Amethyst JS allows you to log things in a log file with log4js
This object has two methods
Trace
The trace()
method allows you to write something in the log file
const { log4js } = require('amethystjs');
log4js.trace("Something just happened");
Config
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()}]`)
Paginator
The Greensky's paginator under the name of AmethystPaginator
. The method is the exact same than the package.
Examples
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)
Contributing
Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the documentation.