他のアドオンとの連携機能
discord-mcbeには、他のアドオンとの連携機能があります。 他のアドオンからdiscord-mcbeを経由してDiscordへメッセージを送信したり、アドオンが処理したチャットをDiscordへ表示したりできます。
連携には、次のどちらかのライブラリを使います。できることと、やりとりするデータの内容は同じです。
1つのアドオンでは、どちらか一方だけを使ってください。ライブラリの導入方法は、それぞれの配布元の説明に従ってください。
この機能を無効にするには、config.jsonのbot.allow_addon_messagesをfalseにします。無効にしても、導入と接続状態の確認には応答します。
準備は要りません。discord-mcbeはdmc:で始まるチャンネルを使います。
ノードを作り、ワールドの読み込み後に起動します。以降の例では、ここで作ったsyncを使います。
import { world } from '@minecraft/server';import { createSync } from '@bedrock-core/sync';
export const sync = createSync({ id: 'example-addon', version: '1.0.0' });
world.afterEvents.worldLoad.subscribe(() => sync.start());discord-mcbeはdiscord-mcbeというIDのノードとして参加します。アドオンのノードのIDは、アドオン名としてdiscord-mcbeに伝わります。
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-mcbeが導入されていれば、ピアとして見つかります。サーバーに接続しているかどうかは、状態connectedで読めます。
sync.discovery.onPeerUp((peer) => { if (peer.id !== 'discord-mcbe') return; // discord-mcbeが導入されている});
// true: 接続中 / false: 未接続 / undefined: まだ見つかっていないconst connected = sync.state.get('discord-mcbe', 'connected');Discordへメッセージを送る
Section titled “Discordへメッセージを送る”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: 'このメッセージは別のアドオンから送信しています',});RPCのsendMessageを呼びます。応答は、サーバーへ渡したらtrue、discord-mcbeが未接続ならfalseです。
function sendDiscordMessage(message: Record<string, unknown>) { return sync.rpc.request('discord-mcbe', 'sendMessage', { message });}
void sendDiscordMessage({ content: 'このメッセージは別のアドオンから送信しています',});messageではembedsなど、JSONで表現できるCreate Message APIのフィールドも利用できます。添付ファイル本体の転送には対応していません。
チャットを処理するアドオンと連携する
Section titled “チャットを処理するアドオンと連携する”world.beforeEvents.chatSendでチャットをキャンセルし、独自の形式で送り直すアドオンを導入していると、discord-mcbeはチャットを受け取れません。そのようなアドオンは、次の手順でチャットをdiscord-mcbeへ通知できます。通知されたチャットは通常のチャットと同じように扱われ、コンソールとDiscordに表示されます。
1. 起動時に登録する
Section titled “1. 起動時に登録する”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);}discord-mcbeがピアとして見つかったら、RPCのregisterを呼びます。アドオンがワールドからいなくなると、登録は自動で解除されます。
interface RegisterResponse { protocol: number; connected: boolean; features: string[];}
sync.discovery.onPeerUp(async (peer) => { if (peer.id !== 'discord-mcbe') return; const response = (await sync.rpc.request('discord-mcbe', 'register', { protocol: 1, features: ['minecraft_chat'], })) as RegisterResponse;});| フィールド | 説明 |
|---|---|
source |
アドオン名。以降の通知でも同じ値を使います。MCBE-IPCでだけ指定します |
protocol |
このページで説明している形式のバージョン。現在は1 |
features |
利用する機能。チャットを通知する場合はminecraft_chatを指定します |
応答のfeaturesには、要求した機能のうちdiscord-mcbeが受け付けたものが入ります。connectedは応答時点の接続状態です。
minecraft_chatを登録すると、discord-mcbeは自身によるチャットの中継を止め、アドオンからの通知だけをDiscordへ送ります。
2. チャットを通知する
Section titled “2. チャットを通知する”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] ' }, }), );}RPCのchatSendを呼びます。応答は、サーバーへ渡したらtrue、渡さなかったらfalseです。
import type { Player } from '@minecraft/server';
function notifyChat(player: Player, message: string) { return sync.rpc.request('discord-mcbe', 'chatSend', { 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のチャットを表示する
Section titled “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); }});イベントdiscordChatで届きます。
import { world } from '@minecraft/server';
sync.events.on('discord-mcbe', 'discordChat', (payload) => { const { text } = payload 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が全員に表示します。
接続イベントを受け取る
Section titled “接続イベントを受け取る”サーバーへの接続が始まったときと、切断されたときに通知されます。どちらもデータはありません。
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から切断された});イベントconnectとdisconnectが発火します。現在の状態は、状態connectedでも読めます。
sync.events.on('discord-mcbe', 'connect', () => { // discord-mcbeへの接続が開始された});
sync.events.on('discord-mcbe', 'disconnect', () => { // discord-mcbeから切断された});型と定数を利用する
Section titled “型と定数を利用する”バンドラーを使っているアドオンは、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));import { AddonSync } from '@discord-mcbe/shared';
const dmc = sync.rpc.typed<AddonSync.Rpc>(AddonSync.NODE_ID);await dmc.chatSend({ playerId: player.id, message: 'hello' });| エクスポート | 内容 |
|---|---|
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の型 |