Anatomía de un plugin
El manifiesto tiene seis campos: name, version, author, description, main y enabled. El archivo indicado en main debe ser un .js o .mjs dentro de la carpeta del plugin. Un punto de entrada .ts se rechaza, porque el bot ejecuta JavaScript ya compilado. Si prefieres TypeScript, compílalo a .js antes de distribuirlo.
El archivo de entrada exporta por defecto un único objeto. Todo es opcional salvo name, así que un plugin puede añadir solo comandos, solo eventos o ninguna de las dos cosas. Un plugin que añade un comando son tres piezas: un manifiesto, un archivo index y una definición de comando. El cargador lo recoge de la carpeta plugins al arrancar.
plugins/
my_plugin/
manifest.json
index.js
// manifest.json
{
"name": "my_plugin",
"version": "1.0.0",
"author": "You",
"description": "What it does",
"main": "index.js",
"enabled": true
}
// index.js
import { SlashCommandBuilder } from 'discord.js';
let ctx;
export default {
name: 'my_plugin',
version: '1.0.0',
commands: [
{
data: new SlashCommandBuilder().setName('ping').setDescription('Reply with pong'),
category: 'plugin',
execute: async (interaction) => {
await interaction.reply({ embeds: [ctx.embed.success('Pong', 'Still here.')] });
}
}
],
events: [],
onLoad: (context) => { ctx = context; },
onUnload: () => {}
}; Lo que recibe un plugin
onLoad y onUnload reciben un contexto de plugin, no el cliente a secas. Incluye el cliente de discord.js, el helper de embeds que usa el resto del bot, un logger con su propio espacio de nombres y la función de traducción t(key, guildId), para que un plugin pueda hablar los nueve idiomas de la interfaz sin traer su propio i18n.
También incluye un directorio de datos privado y los helpers readData y writeData. Así, un plugin que necesite recordar un contador o una lista no tiene que traer una base de datos ni meterse en el almacenamiento del bot. No importes nada de src/ ni de dist/. Esas rutas cambian entre desarrollo y una compilación desplegada, y el objeto de contexto existe para que nunca lo necesites.
- client: el cliente de discord.js
- embed: el mismo helper de embeds que usa el núcleo
- logger: info, warn, error y debug, con el espacio de nombres del plugin
- t(key, guildId, vars): textos traducidos
- dataDir, readData, writeData: el almacenamiento privado del plugin
Carga y descarga
Los plugins se cargan al arrancar, en orden alfabético de carpeta, antes de que el bot inicie sesión. Un manifiesto incorrecto se omite con una advertencia y los demás plugins se cargan igualmente. Al apagar o descargar, se ejecuta onUnload y se eliminan los listeners y comandos del plugin. Una recarga vuelve a importar el archivo con una clave de caché nueva, así que recoge tus cambios sin dejar listeners duplicados.
Un plugin también puede venir desactivado: pon enabled en false en el manifiesto y el cargador lo omitirá hasta que digas lo contrario. El sample_plugin incluido viene así a propósito. Añadir o quitar un comando requiere un reinicio para que Discord vea el cambio.