コンテンツにスキップ

他のアドオンとの連携機能

discord-mcbeには、他のアドオンとの連携機能があります。 他のアドオンからdiscord-mcbeを経由してDiscordへメッセージを送信したり、アドオンが処理したチャットをDiscordへ表示したりできます。

連携には、次のどちらかのライブラリを使います。できることと、やりとりするデータの内容は同じです。

1つのアドオンでは、どちらか一方だけを使ってください。ライブラリの導入方法は、それぞれの配布元の説明に従ってください。

この機能を無効にするには、config.jsonのbot.allow_addon_messagesをfalseにします。無効にしても、導入と接続状態の確認には応答します。

準備は要りません。discord-mcbeはdmc:で始まるチャンネルを使います。

discord-mcbeが導入されているか確認する

Section titled “discord-mcbeが導入されているか確認する”

dmc:pingの応答は、trueなら接続中、falseなら導入済みですが未接続です。20tick以内に応答がなければ、discord-mcbeは導入されていません。この確認は起動時に一度だけ行ってください。

import { system } from '@minecraft/server';
import { IPC, PROTO } from 'mcbe-ipc';
export function getDiscordMcbeStatus(): Promise<boolean | undefined> {
return Promise.race([
IPC.invoke('dmc:ping', PROTO.Void, undefined, PROTO.Boolean),
system.waitTicks(20).then(() => undefined),
]);
}

Discord Create Message API形式のmessageを送ると、Discordへメッセージが送信されます。

dmc:send_messageへ、送信元のアドオン名sourceとmessageを含むobjectをJSON文字列として送ります。

import { IPC, PROTO } from 'mcbe-ipc';
function sendDiscordMessage(source: string, message: Record<string, unknown>) {
IPC.send('dmc:send_message', PROTO.String, JSON.stringify({ source, message }));
}
sendDiscordMessage('example-addon', {
content: 'このメッセージは別のアドオンから送信しています',
});

messageではembedsなど、JSONで表現できるCreate Message APIのフィールドも利用できます。添付ファイル本体の転送には対応していません。

チャットを処理するアドオンと連携する

Section titled “チャットを処理するアドオンと連携する”

world.beforeEvents.chatSendでチャットをキャンセルし、独自の形式で送り直すアドオンを導入していると、discord-mcbeはチャットを受け取れません。そのようなアドオンは、次の手順でチャットをdiscord-mcbeへ通知できます。通知されたチャットは通常のチャットと同じように扱われ、コンソールとDiscordに表示されます。

dmc:registerを起動時に一度だけ呼び出します。20tick以内に応答がなければ、discord-mcbeは導入されていません。

import { system } from '@minecraft/server';
import { IPC, PROTO } from 'mcbe-ipc';
interface RegisterResponse {
protocol: number;
connected: boolean;
features: string[];
}
export async function registerToDiscordMcbe(source: string): Promise<RegisterResponse | undefined> {
const response = await Promise.race([
IPC.invoke(
'dmc:register',
PROTO.String,
JSON.stringify({ source, protocol: 1, features: ['minecraft_chat'] }),
PROTO.String,
),
system.waitTicks(20).then(() => undefined),
]);
return response === undefined ? undefined : (JSON.parse(response) as RegisterResponse);
}
フィールド 説明
source アドオン名。以降の通知でも同じ値を使います。MCBE-IPCでだけ指定します
protocol このページで説明している形式のバージョン。現在は1
features 利用する機能。チャットを通知する場合はminecraft_chatを指定します

応答のfeaturesには、要求した機能のうちdiscord-mcbeが受け付けたものが入ります。connectedは応答時点の接続状態です。

minecraft_chatを登録すると、discord-mcbeは自身によるチャットの中継を止め、アドオンからの通知だけをDiscordへ送ります。

Discordへ表示したいチャットごとに通知します。全体チャットだけを通知するなど、どのチャットを通知するかはアドオン側で決めてください。

dmc:on_chat_sendを送信します。

import type { Player } from '@minecraft/server';
import { IPC, PROTO } from 'mcbe-ipc';
function notifyChat(source: string, player: Player, message: string) {
IPC.send(
'dmc:on_chat_send',
PROTO.String,
JSON.stringify({
source,
playerId: player.id,
message,
formatting: { namePrefix: '[Team A] ' },
}),
);
}
フィールド 説明
source 登録時と同じアドオン名。MCBE-IPCでだけ指定します
playerId 発言したプレイヤーのPlayer.id
message 装飾を含まない本文
formatting 送信者名と本文の前後に付ける文字列。省略できます

formattingには次の4つを指定できます。いずれも省略でき、文字列のみ指定できます。

フィールド 表示位置
namePrefix 送信者名の前
nameSuffix 送信者名の後
messagePrefix 本文の前
messageSuffix 本文の後
  • 登録していないアドオンからの通知と、オンラインでないプレイヤーの通知は無視されます。
  • discord-mcbeが未接続のときの通知は無視されます。接続状態を確認してから送る必要はありません。
  • formattingを省略した場合、Player.chatNamePrefixなどの値は自動では使われません。使いたい場合は、アドオン側で読み取って指定してください。
  • beforeEvents.chatSendのmessageにはPlayer.chatMessagePrefixがすでに含まれています。そのmessageをそのまま送る場合は、messagePrefixを指定しないでください。
  • bot.allow_addon_messagesがfalseのとき、通知されたチャットはDiscordへ送信されません。

discord-mcbeは、Discordから届いたチャットをワールドの全員に表示します。チャットのミュートなど、表示する相手をアドオン側で決めたい場合は、登録のfeaturesにdiscord_chatを加えます。

discord_chatを登録すると、discord-mcbeはDiscordのチャットを自分では表示せず、アドオンへ渡します。表示はアドオンが行ってください。

dmc:discord_chatで、JSON文字列として届きます。

import { world } from '@minecraft/server';
import { IPC, PROTO } from 'mcbe-ipc';
IPC.on('dmc:discord_chat', PROTO.String, (json) => {
const { text } = JSON.parse(json) as { text: string };
for (const player of world.getPlayers()) {
// 表示しないプレイヤーをアドオン側で決める
if (player.hasTag('mute_discord')) continue;
player.sendMessage(text);
}
});
フィールド 説明
text そのまま表示できる文字列。translation_overridesの内容が反映されます
message 元になったDiscordのメッセージ

messageは、discord.jsのMessageからゲーム内で使える項目だけを残した形です。送信者をアドオン側のアカウント連携と結びつけたり、独自の形式で表示したりするときに使います。

{
id: string,
channelId: string,
content: string,
author: { id: string, username: string, displayName: string, bot: boolean },
member: { displayName: string, roles: { id: string, name: string }[] } | null,
attachments: { name: string, contentType: string | null }[],
mentions: { users: author[], roles: { id: string, name: string }[], everyone: boolean },
referencedMessage: { id, content, author, member } | null,
}
フィールド 説明
content フィルターを通した本文。メンションは名前に置き換わっています。添付ファイルだけなら空文字列です
author.id DiscordのユーザーID
author.bot 送信者では常にfalseです(Botの発言は中継されません)。返信先ではtrueになることがあります
member サーバー内での表示名とロール。返信先がWebhookや退出済みのユーザーのときはnullです
member.roles 上位のロールから順に並びます。@everyoneは含みません
attachments 添付ファイルのファイル名と種類。contentTypeはimage/pngなどで、不明なときはnullです
mentions メンションされたユーザーとロール。usersの要素はauthorと同じ形です。通知付きの返信では、返信先のユーザーもusersに入ります。everyoneは@everyoneか@hereが使われたかどうか
referencedMessage 返信先のメッセージ。返信でなければnullです。contentはフィルターを通し、長さを切り詰めた本文
  • 対象はDiscordから届いたチャットだけです。接続時の通知などは、これまでどおりdiscord-mcbeが表示します。
  • Discordのメッセージ1件につき、通知は1回です。本文と添付ファイルの両方があるメッセージでは、textが2行になります。
  • この通知は同じワールドの全アドオンに届きます。ユーザーIDやロールを渡したくないアドオンがある場合は、bot.allow_addon_messagesをfalseにしてください。
  • discord_chatを登録するアドオンは、1つのワールドに1つだけにしてください。複数のアドオンが登録すると、それぞれが表示して重複します。
  • bot.allow_addon_messagesがfalseのときは登録が無視され、discord-mcbeが全員に表示します。
  • 応答のfeaturesにdiscord_chatが含まれない場合、導入されているdiscord-mcbeはこの機能に対応していません。その場合もdiscord-mcbeが全員に表示します。

サーバーへの接続が始まったときと、切断されたときに通知されます。どちらもデータはありません。

dmc:connectとdmc:disconnectが発火します。

import { IPC, PROTO } from 'mcbe-ipc';
IPC.on('dmc:connect', PROTO.Void, () => {
// discord-mcbeへの接続が開始された
});
IPC.on('dmc:disconnect', PROTO.Void, () => {
// discord-mcbeから切断された
});

バンドラーを使っているアドオンは、npmパッケージ@discord-mcbe/sharedから名前の定数、ペイロードの型と検証関数を利用できます。どちらのライブラリでも使うものはそのまま、片方だけで使うものはAddonIpcとAddonSyncにまとまっています。

import { IPC, PROTO } from 'mcbe-ipc';
import { AddonIpc } from '@discord-mcbe/shared';
const payload: AddonIpc.ChatSend = {
source: 'example-addon',
playerId: player.id,
message: 'hello',
};
IPC.send(AddonIpc.Channel.ChatSend, PROTO.String, JSON.stringify(payload));
エクスポート 内容
AddonFeature 機能名(minecraft_chatなど)
AddonRegisterRequest / AddonRegisterResponse 登録の要求と応答の型
AddonChatSend / AddonSendMessage チャットの通知と、Discordへ送るメッセージの型
AddonDiscordChat / AddonDiscordMessage Discordのチャットと、そのmessageの型
safeParseAddonRegisterResponse / safeParseAddonDiscordChat 登録の応答と、Discordのチャットを検証する関数
AddonIpc.Channel MCBE-IPCのチャンネル名(dmc:registerなど)
AddonIpc.RegisterRequest / AddonIpc.ChatSend / AddonIpc.SendMessage MCBE-IPCのペイロードの型。sourceが加わります
AddonSync.NODE_ID @bedrock-core/syncでのdiscord-mcbeのノードID
AddonSync.Method / AddonSync.Event / AddonSync.StateKey @bedrock-core/syncのRPC、イベント、状態の名前
AddonSync.Rpc @bedrock-core/syncのRPCの型