カスタムスクリプト

カスタムスクリプト機能は、discord-mcbeの機能をJavaScript/TypeScriptで拡張するための仕組みです。Botの起動時にスクリプトを読み込み、イベントを受け取ったり、ワールドやプレイヤーを操作できます。

起動時にconfig.jsonのscript.entryで指定したファイルが読み込まれ、default exportした関数が呼び出されます。関数の引数には、discord-mcbe本体のApplicationインスタンスが渡されます。

最小構成

JavaScript/TypeScriptの両方に対応しています。

TypeScript
JavaScript

import type { Application } from '@discord-mcbe/server';

export default function main(app: Application) {
  app.logger.info('Custom script loaded');
}

/**
 * @param {import('@discord-mcbe/server').Application} app
 */
export default function main(app) {
  app.logger.info('Custom script loaded');
}

BDS接続を認証する (任意)

BDSのserver-net接続は、初期状態では認証されません。Bearer認証を使う場合は、.envへ任意のトークンを追加し、カスタムスクリプトから認証処理を設定します。

BRIDGE_TOKEN=トークン

import { bearerAuth, type Application } from '@discord-mcbe/server';

export default function main(app: Application) {
  const token = process.env.BRIDGE_TOKEN;
  if (!token) throw new Error('BRIDGE_TOKEN is not set');

  app.minecraft.script.setAuthenticator(bearerAuth(token));
}

BDS側のvariables.jsonにも同じトークンを設定します。

{
  "BRIDGE_URL": "ws://localhost:23191",
  "BRIDGE_TOKEN": "トークン"
}

独自の認証を使う場合は、setAuthenticatorへリクエストを受け取る関数を渡してください。関数はbooleanまたはPromise<boolean>を返します。認証に失敗した接続は、ワールドセッションが作られる前に拒否されます。

import type { Application } from '@discord-mcbe/server';

export default function main(app: Application) {
  app.on('worldConnect', async (event) => {
    app.logger.info('Connected:', event.world.name);
    await event.world.sendMessage('§aDiscord bridge connected');
  });

  app.on('playerJoin', async (event) => {
    const location = await event.player.getLocation();
    app.logger.info(
      `${event.player.name}がログインしました。座標: [${location.x}, ${location.y}, ${location.z}]`,
    );
  });

  app.on('minecraftMessage', (event) => {
    app.logger.info('Chat:', event.world.name, event.sender.name, event.message);
  });
}

/**
 * @param {import('@discord-mcbe/server').Application} app
 */
export default function main(app) {
  app.on('worldConnect', async (event) => {
    app.logger.info('Connected:', event.world.name);
    await event.world.sendMessage('§aDiscord bridge connected');
  });

  app.on('playerJoin', async (event) => {
    const location = await event.player.getLocation();
    app.logger.info(
      `${event.player.name}がログインしました。座標: [${location.x}, ${location.y}, ${location.z}]`,
    );
  });

  app.on('minecraftMessage', (event) => {
    app.logger.info('Chat:', event.world.name, event.sender.name, event.message);
  });
}

主なイベントは次のとおりです。詳しくはAPIリファレンスを参照してください。

イベント	主な値	タイミング
`startup`	`app`	Bot、接続サーバー、スクリプトが起動したあと
`discordReady`	`client`	Discordへのログインが完了したとき
`discordMessage`	`message`	対象チャンネルでユーザーのメッセージを受信したとき
`discordSend`	`channel`, `message`	discord-mcbeがDiscordへ送信する直前
`worldConnect`	`world`	ワールドの初期化が完了したとき
`worldDisconnect`	`world`	ワールドのセッションが終了したとき
`minecraftMessage`	`world`, `sender`, `message`	Minecraftのチャットを受信したとき
`playerJoin` / `playerLeave`	`world`, `player`	プレイヤーが参加・退出したとき

ワールドを操作する

TypeScript
JavaScript

import type { Application } from '@discord-mcbe/server';

export default function main(app: Application) {
  app.on('worldConnect', async ({ world }) => {
    const result = await world.runCommand('weather clear');
    const tps = await world.getTPS();

    app.logger.info(world.name, result, 'TPS:', tps);
  });
}

/**
 * @param {import('@discord-mcbe/server').Application} app
 */
export default function main(app) {
  app.on('worldConnect', async ({ world }) => {
    const result = await world.runCommand('weather clear');
    const tps = await world.getTPS();

    app.logger.info(world.name, result, 'TPS:', tps);
  });
}

ScriptWorldからメッセージ送信、コマンド、TPS、Script Event、プレイヤー、スコアボードを操作できます。ScriptPlayerでは個別メッセージ、座標・ディメンション・ゲームモード取得、ゲームモード変更、キック、画面表示を扱えます。

全メソッドと型はAPIリファレンスを参照してください。

依存パッケージを追加する

カスタムスクリプトでは、npmで公開されているパッケージを自由に利用できます。ランチャーと同じディレクトリにあるpackage.jsonへ、使いたいパッケージを追加してください。パッケージマネージャーはnpm、pnpm、Bunなどから自由に選べます。

追加したパッケージは、scripts/内のファイルから通常どおりimportできます。@discord-mcbe/serverと@discord-mcbe/sharedはdiscord-mcbe本体が提供するため、別途インストールする必要はありません。