Przejdź do treści
VORQUL
VorqulBOT / Platforma

System wtyczek

Modularny bot, który wymaga forka rdzenia, żeby dodać jedną komendę, nie jest modularny. System wtyczek istnieje po to, żeby logika specyficzna dla serwera zostawała specyficzna dla serwera.

VorqulBOT obsługuje wtyczki, które wystarczy wrzucić do folderu. Wtyczka to folder w plugins/ z plikiem manifest.json i plikiem wejściowym JavaScript (.js lub .mjs, nigdy .ts), który domyślnie eksportuje obiekt z własnymi komendami, zdarzeniami oraz opcjonalnymi hookami onLoad i onUnload. Wtyczki ładują się przy starcie, zanim bot się zaloguje, więc ich komendy rejestrują się w Discordzie razem z wbudowanymi i nie wymagają żadnych zmian w rdzeniu bota.

Język
JavaScript (ESM), TypeScript kompilujesz sam
Manifest
manifest.json
Punkt wejścia
.js lub .mjs, domyślnie eksportowany obiekt
Ładowanie
Przy starcie, przed zalogowaniem

Budowa wtyczki

Manifest ma sześć pól: name, version, author, description, main i enabled. Plik wskazany w main musi być plikiem .js lub .mjs w folderze wtyczki. Punkt wejścia .ts jest odrzucany, bo bot uruchamia skompilowany JavaScript. Jeśli wolisz TypeScript, skompiluj go do .js przed wdrożeniem.

Plik wejściowy domyślnie eksportuje jeden obiekt. Wszystko poza name jest opcjonalne, więc wtyczka może dodawać same komendy, same zdarzenia albo żadne z nich. Wtyczka z jedną komendą to manifest, plik index i jedna definicja komendy, a loader znajdzie ją w folderze plugins przy starcie.

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 dostaje wtyczka

onLoad i onUnload dostają kontekst wtyczki, a nie sam klient. Zawiera on klienta discord.js, helper embedów używany w reszcie bota, logger z własną przestrzenią nazw oraz funkcję tłumaczeń t(key, guildId), dzięki której wtyczka obsłuży wszystkie dziewięć języków interfejsu bez własnego i18n.

Ma też prywatny katalog danych oraz helpery readData i writeData, więc wtyczka, która musi zapamiętać licznik albo listę, nie potrzebuje własnej bazy ani sięgania do magazynu bota. Nie importuj niczego z src/ ani dist/. Te ścieżki różnią się między developmentem a wdrożonym buildem, a obiekt kontekstu istnieje po to, żebyś nigdy tego nie potrzebował.

  • client: klient discord.js
  • embed: ten sam helper embedów, którego używa rdzeń
  • logger: info, warn, error i debug, z przestrzenią nazw wtyczki
  • t(key, guildId, vars): przetłumaczone teksty
  • dataDir, readData, writeData: prywatny magazyn wtyczki

Wspólny rejestr modułów

Bot i panel czytają jeden rejestr modułów, czyli 44 klucze w src/shared/moduleRegistry.ts. Dzięki temu przełącznik nie może istnieć w panelu, jeśli bot go nie respektuje.

To szczegół, który chroni obie połowy przed rozjechaniem się w czasie, a to typowa bolączka botów z osobnym interfejsem webowym.

Ładowanie i wyładowywanie

Wtyczki ładują się przy starcie, w kolejności alfabetycznej folderów, zanim bot się zaloguje. Zły manifest jest pomijany z ostrzeżeniem, a pozostałe wtyczki nadal się ładują. Przy zamknięciu lub wyładowaniu uruchamia się onUnload, a listenery i komendy wtyczki są usuwane. Przeładowanie importuje plik ponownie ze świeżym kluczem cache, więc łapie twoje zmiany i nie zostawia zdublowanych listenerów.

Wtyczka może też być dostarczona jako wyłączona: ustaw enabled na false w manifeście, a loader pominie ją, dopóki nie zdecydujesz inaczej. Dołączona sample_plugin jest tak dostarczana celowo. Dodanie lub usunięcie komendy wymaga restartu, zanim Discord zobaczy zmianę.

Pojęcia na tej stronie

Rejestr modułów Podpis webhooka Hostowane samodzielnie

Najczęstsze pytania

Powiązane strony