Saltar al contenido
VORQUL
VorqulBOT / Plataforma

Sistema de plugins

Un bot modular que obliga a bifurcar el núcleo para añadir un solo comando no es modular. El sistema de plugins existe para que la lógica propia de cada servidor se quede en ese servidor.

VorqulBOT admite plugins que se añaden sin tocar el núcleo. Un plugin es una carpeta dentro de plugins/ que contiene un manifest.json y un archivo de entrada JavaScript (.js o .mjs, nunca .ts) que exporta por defecto un objeto con sus propios comandos, eventos y, de forma opcional, los hooks onLoad y onUnload. Los plugins se cargan al arrancar, antes de que el bot inicie sesión, así que sus comandos se registran en Discord junto con los integrados y no hace falta modificar el núcleo del bot.

Lenguaje
JavaScript (ESM), compila TypeScript tú mismo
Manifiesto
manifest.json
Punto de entrada
.js o .mjs, objeto exportado por defecto
Carga
Al arrancar, antes del inicio de sesión

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

Registro de módulos compartido

El bot y el panel leen un único registro de módulos, las 44 claves de src/shared/moduleRegistry.ts. Eso significa que un interruptor no puede existir en el panel sin que el bot lo respete.

Este detalle evita que las dos mitades se vayan separando con el tiempo, que es el fallo habitual de un bot con una interfaz web aparte.

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.

Términos de esta página

Registro de módulos Firma de webhook Autoalojado

Preguntas frecuentes

Páginas relacionadas