コンテンツへスキップ
VORQUL
VorqulBOT / プラットフォーム

プラグインシステム

コマンドを1つ追加するためにコアをフォークしなければならない Bot は、モジュール式とは言えません。プラグインの仕組みがあるのは、サーバー固有のロジックをサーバー側だけに留めるためです。

VorqulBOT はドロップイン方式のプラグインに対応しています。プラグインは plugins/ フォルダの中に置くフォルダで、manifest.json と JavaScript のエントリファイル(.js または .mjs。.ts は不可)を含みます。エントリファイルは、独自のコマンドとイベント、任意の onLoad / onUnload フックを持つオブジェクトを default export します。プラグインは Bot がログインする前の起動時に読み込まれるため、コマンドは組み込みコマンドと一緒に Discord に登録されます。Bot 本体を変更する必要はありません。

言語
JavaScript(ESM)。TypeScript は自分でコンパイルします
マニフェスト
manifest.json
エントリポイント
.js または .mjs、default export されたオブジェクト
読み込みタイミング
起動時、ログインの前

プラグインの構造

マニフェストには name、version、author、description、main、enabled の6つのフィールドがあります。main で指定するファイルは、プラグインフォルダ内の .js または .mjs ファイルでなければなりません。Bot はコンパイル済みの JavaScript を実行するため、.ts のエントリポイントは拒否されます。TypeScript を使う場合は、配布前に .js にコンパイルしてください。

エントリファイルは1つのオブジェクトを default export します。name 以外はすべて省略できるので、コマンドだけ、イベントだけ、あるいはどちらも持たないプラグインも作れます。コマンドを1つ追加するプラグインは、マニフェスト、インデックスファイル、コマンド定義が1つあれば足ります。ローダーは起動時に 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 は、素の client ではなくプラグインコンテキストを受け取ります。コンテキストには、discord.js の client、Bot の他の部分と共通の embed ヘルパー、名前空間付きのロガー、翻訳関数 t(key, guildId) が入っています。そのため、プラグインは独自の i18n を用意しなくても9つのインターフェース言語すべてに対応できます。

プラグイン専用のデータディレクトリと readData / writeData ヘルパーもあります。カウンターやリストを保存したいだけなら、データベースを用意したり Bot のストレージに触れたりする必要はありません。src/ や dist/ からは何もインポートしないでください。これらのパスは開発環境とデプロイ後のビルドで異なります。コンテキストオブジェクトがあるので、その必要はありません。

  • client: discord.js の client
  • embed: コアが使うものと同じ embed ヘルパー
  • logger: info、warn、error、debug。プラグインごとの名前空間付き
  • t(key, guildId, vars): 翻訳済みの文字列
  • dataDir、readData、writeData: プラグイン専用のストレージ

共有モジュールレジストリ

Bot とダッシュボードは、src/shared/moduleRegistry.ts にある44個のキーからなる1つのモジュールレジストリを共有して読み取ります。つまり、Bot が対応していないトグルがダッシュボードだけに存在することはありません。

Web UI が別にある Bot で起こりがちな「両者が少しずつずれていく」問題を防ぐのが、この仕組みです。

読み込みとアンロード

プラグインは Bot がログインする前の起動時に、フォルダ名のアルファベット順で読み込まれます。マニフェストに問題があるプラグインは警告を出してスキップされ、他のプラグインは通常どおり読み込まれます。シャットダウン時やアンロード時には onUnload が実行され、そのプラグインのリスナーとコマンドが削除されます。リロードではキャッシュキーを新しくしてファイルを再インポートするため、編集内容が反映され、リスナーが重複して残ることもありません。

プラグインを無効の状態で配布することもできます。マニフェストの enabled を false にすると、有効にするまでローダーはそのプラグインをスキップします。同梱の sample_plugin は、あえてこの状態で配布されています。コマンドを追加または削除した場合、Discord に反映させるには再起動が必要です。

このページの用語

モジュールレジストリ Webhook 署名 セルフホスト

よくある質問

関連ページ