Перейти к содержимому
VORQUL
VorqulBOT / Платформа

Система плагинов

Модульный бот, которому для одной команды нужен форк ядра, не модульный. Система плагинов нужна, чтобы логика конкретного сервера оставалась логикой этого сервера.

VorqulBOT поддерживает плагины, которые достаточно положить в папку. Плагин - это папка внутри plugins/ с файлом manifest.json и JavaScript-файлом входа (.js или .mjs, но не .ts). Файл экспортирует по умолчанию объект со своими командами, событиями и необязательными хуками onLoad и onUnload. Плагины загружаются при запуске, до входа бота в Discord, поэтому их команды регистрируются в Discord вместе со встроенными. Менять ядро бота для этого не нужно.

Язык
JavaScript (ESM), TypeScript компилируйте сами
Манифест
manifest.json
Точка входа
.js или .mjs, объект экспортируется по умолчанию
Загрузка
При запуске, до входа в Discord

Устройство плагина

В манифесте шесть полей: name, version, author, description, main и enabled. Файл, указанный в main, должен быть .js или .mjs и лежать внутри папки плагина. Точка входа .ts отклоняется, потому что бот запускает скомпилированный JavaScript. Если вы пишете на TypeScript, скомпилируйте код в .js перед поставкой.

Файл входа экспортирует по умолчанию один объект. Всё, кроме name, необязательно, поэтому плагин может добавлять только команды, только события или ничего. Плагин с одной командой - это манифест, индексный файл и одно описание команды. Загрузчик подхватит его из папки 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: () => {}
};

Что получает плагин

onLoad и onUnload получают контекст плагина, а не голый клиент. В нём есть клиент discord.js, помощник для embed, которым пользуется остальной бот, логгер со своим пространством имён и функция перевода t(key, guildId). Так плагин может говорить на всех девяти языках интерфейса без собственного i18n.

В контексте также есть приватный каталог данных и помощники readData и writeData. Если плагину нужно помнить счётчик или список, ему не придётся тащить базу данных или лезть в хранилище бота. Не импортируйте ничего из src/ или dist/. Эти пути различаются в разработке и в развёрнутой сборке, а объект контекста нужен как раз для того, чтобы вам это не требовалось.

  • client: клиент discord.js
  • embed: тот же помощник для embed, что использует ядро
  • logger: info, warn, error и debug с пространством имён плагина
  • t(key, guildId, vars): переведённые строки
  • dataDir, readData, writeData: приватное хранилище плагина

Общий реестр модулей

Бот и панель управления читают один реестр модулей: 44 ключа в src/shared/moduleRegistry.ts. Поэтому переключатель не может появиться в панели, если бот его не поддерживает.

Именно эта деталь не даёт двум частям разойтись со временем. Для бота с отдельным веб-интерфейсом это обычная проблема.

Загрузка и выгрузка

Плагины загружаются при запуске, в алфавитном порядке папок, до входа бота в Discord. Плагин с неверным манифестом пропускается с предупреждением, остальные загружаются как обычно. При остановке или выгрузке вызывается onUnload, а слушатели и команды плагина удаляются. Перезагрузка заново импортирует файл с новым ключом кэша, поэтому ваши правки подхватываются и дублирующихся слушателей не остаётся.

Плагин можно поставлять и отключённым: укажите в манифесте enabled равным false, и загрузчик будет пропускать его, пока вы не скажете иначе. Входящий в комплект sample_plugin поставляется именно так, намеренно. Чтобы Discord увидел добавленную или удалённую команду, нужен перезапуск.

Термины на этой странице

Реестр модулей Подпись webhook Самостоятельное размещение

Частые вопросы

Связанные страницы