Preskočiť na obsah
VORQUL
VorqulBOT / Platforma

Systém pluginov

Modulárny bot, ktorý si na pridanie jedného príkazu vyžaduje forknúť jadro, nie je modulárny. Systém plugin-ov existuje preto, aby logika špecifická pre tvoj server zostala len na tvojom serveri.

VorqulBOT podporuje plugin-y, ktoré stačí vložiť do priečinka. Plugin je priečinok v plugins/ s manifestom manifest.json a JavaScriptovým vstupným súborom (.js alebo .mjs, nikdy .ts), ktorý cez default export vracia objekt s vlastnými príkazmi, udalosťami a voliteľnými hookmi onLoad a onUnload. Plugin-y sa načítajú pri štarte, ešte pred prihlásením bota, takže ich príkazy sa registrujú v Discorde spolu s vstavanými a nevyžadujú žiadnu úpravu jadra bota.

Jazyk
JavaScript (ESM), TypeScript si skompiluj sám
Manifest
manifest.json
Vstupný bod
.js alebo .mjs, objekt cez default export
Načítanie
Pri štarte, pred prihlásením

Anatómia plugin-u

Manifest má šesť polí: name, version, author, description, main a enabled. Súbor uvedený v main musí byť .js alebo .mjs a musí ležať v priečinku plugin-u. Vstupný bod .ts sa odmietne, pretože bot spúšťa skompilovaný JavaScript. Ak preferuješ TypeScript, skompiluj ho do .js ešte pred nasadením.

Vstupný súbor cez default export vracia jeden objekt. Okrem name je všetko voliteľné, takže plugin môže pridávať len príkazy, len udalosti, alebo ani jedno. Plugin s jedným príkazom tvorí manifest, indexový súbor a jedna definícia príkazu. Loader ho pri štarte nájde v priečinku 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: () => {}
};

Čo plugin dostane

onLoad a onUnload dostanú kontext plugin-u, nie holého klienta. Obsahuje klienta discord.js, pomocníka pre embedy, ktorý používa zvyšok bota, logger s vlastným menným priestorom a prekladovú funkciu t(key, guildId), takže plugin vie hovoriť všetkými deviatimi jazykmi rozhrania a nemusí nosiť vlastné i18n.

Obsahuje aj súkromný dátový priečinok a pomocníkov readData a writeData. Plugin, ktorý si potrebuje zapamätať počítadlo alebo zoznam, tak nemusí mať vlastnú databázu ani siahať do úložiska bota. Nič neimportuj zo src/ ani z dist/. Tieto cesty sa líšia medzi vývojom a nasadeným buildom a objekt kontextu existuje práve preto, aby si to nikdy nepotreboval.

  • client: klient discord.js
  • embed: ten istý pomocník pre embedy, aký používa jadro
  • logger: info, warn, error a debug, s menným priestorom plugin-u
  • t(key, guildId, vars): preložené reťazce
  • dataDir, readData, writeData: súkromné úložisko plugin-u

Spoločný register modulov

Bot a dashboard čítajú jeden register modulov, 44 kľúčov v src/shared/moduleRegistry.ts. Prepínač teda nemôže existovať v dashboarde bez toho, aby ho bot rešpektoval.

Práve tento detail bráni tomu, aby sa obe polovice časom rozišli, čo je bežný problém botov s oddeleným webovým rozhraním.

Načítanie a vyloženie

Plugin-y sa načítavajú pri štarte v abecednom poradí priečinkov, ešte pred prihlásením bota. Chybný manifest sa preskočí s upozornením a ostatné plugin-y sa načítajú ďalej. Pri vypnutí alebo vyložení sa spustí onUnload a odstránia sa listenery a príkazy plugin-u. Opätovné načítanie importuje súbor s novým kľúčom cache, takže zachytí tvoje úpravy a nenechá po sebe duplicitné listenery.

Plugin môže byť aj dodaný vypnutý: nastav enabled na false v manifeste a loader ho preskočí, kým nepovieš inak. Priložený sample_plugin je takto dodávaný zámerne. Po pridaní alebo odobratí príkazu treba reštart, aby zmenu videl Discord.

Pojmy na tejto stránke

Register modulov Podpis webhooku Self-hosted

Často kladené otázky

Súvisiace stránky