Přeskočit na obsah
VORQUL
VorqulBOT / Platforma

Systém pluginů

Modulární bot, který kvůli jednomu příkazu vyžaduje forknout jádro, modulární není. Systém pluginů existuje proto, aby logika specifická pro server zůstala specifická pro server.

VorqulBOT podporuje zásuvné pluginy. Plugin je složka v plugins/ s manifestem manifest.json a vstupním souborem JavaScriptu (.js nebo .mjs, nikdy .ts), který pomocí default exportu vrací objekt s vlastními příkazy, událostmi a volitelnými hooky onLoad a onUnload. Pluginy se načítají při startu, ještě před přihlášením bota, takže se jejich příkazy zaregistrují na Discordu spolu s vestavěnými a nevyžadují žádnou úpravu jádra bota.

Jazyk
JavaScript (ESM), TypeScript si zkompilujete sami
Manifest
manifest.json
Vstupní bod
.js nebo .mjs, objekt exportovaný jako default
Načítá se
Při startu, před přihlášením

Anatomie pluginu

Manifest obsahuje šest polí: name, version, author, description, main a enabled. Soubor uvedený v main musí být .js nebo .mjs uvnitř složky pluginu. Vstupní bod v .ts se odmítne, protože bot spouští zkompilovaný JavaScript. Pokud dáváte přednost TypeScriptu, před nasazením ho zkompilujte do .js.

Vstupní soubor exportuje jeden objekt jako default. Všechno kromě name je volitelné, takže plugin může přidávat jen příkazy, jen události, nebo nic z toho. Plugin s jedním příkazem tvoří manifest, soubor index a jediná definice příkazu a loader si ho při startu vyzvedne ze složky plugins.

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: () => {}
};

Co plugin dostane k dispozici

onLoad a onUnload dostávají kontext pluginu, ne samotného klienta. Obsahuje klienta discord.js, pomocnou funkci pro embedy, kterou používá zbytek bota, logger s vlastním jmenným prostorem a překladovou funkci t(key, guildId), takže plugin umí všech devět jazyků rozhraní, aniž by musel dodávat vlastní i18n.

Obsahuje také soukromou datovou složku a pomocné funkce readData a writeData, takže plugin, který si potřebuje pamatovat počítadlo nebo seznam, nemusí přinášet databázi ani sahat do úložiště bota. Nic neimportujte ze src/ ani dist/. Tyto cesty se liší mezi vývojem a nasazeným buildem a objekt kontextu existuje právě proto, abyste to nikdy nepotřebovali.

  • client: klient discord.js
  • embed: stejná pomocná funkce pro embedy, jakou používá jádro
  • logger: info, warn, error a debug, s jmenným prostorem pluginu
  • t(key, guildId, vars): přeložené řetězce
  • dataDir, readData, writeData: soukromé úložiště pluginu

Sdílený registr modulů

Bot i dashboard čtou jeden registr modulů, 44 klíčů v src/shared/moduleRegistry.ts. To znamená, že přepínač nemůže existovat v dashboardu, aniž by ho bot respektoval.

Právě tento detail brání tomu, aby se obě poloviny postupem času rozcházely, což je obvyklý problém botů s odděleným webovým rozhraním.

Načítání a odebírání

Pluginy se načítají při startu, v abecedním pořadí složek, před přihlášením bota. Chybný manifest se přeskočí s varováním a ostatní pluginy se načtou dál. Při vypnutí nebo odebrání se spustí onUnload a posluchače i příkazy pluginu se odeberou. Znovunačtení importuje soubor s novým klíčem cache, takže se projeví vaše úpravy a nezůstanou po něm duplicitní posluchači.

Plugin lze také dodat vypnutý: nastavte v manifestu enabled na false a loader ho přeskočí, dokud neřeknete jinak. Přibalený sample_plugin je takto dodáván záměrně. Po přidání nebo odebrání příkazu je potřeba restart, aby změnu Discord uviděl.

Pojmy na této stránce

Registr modulů Podpis webhooku Na vlastním hostingu

Často kladené otázky

Související stránky