Skip to content

Add-on integration

discord-mcbe supports integration with other add-ons. Other add-ons can send messages to Discord through discord-mcbe, and show chat they handle themselves on Discord.

Use one of the libraries below. Both offer the same features and exchange the same data.

Use only one of them in an add-on. Follow the instructions from each library to add it to the add-on.

To disable this feature, set bot.allow_addon_messages to false in config.json. Other add-ons can still detect whether discord-mcbe is installed and connected.

No setup is needed. discord-mcbe uses channels that start with dmc:.

The response from dmc:ping is true when connected and false when discord-mcbe is installed but disconnected. If there is no response within 20 ticks, discord-mcbe is not installed. Perform this check only once at startup.

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),
]);
}

Send a message in the Discord Create Message API format to send it to Discord.

Send a JSON string containing source, the name of the sending add-on, and message to dmc:send_message.

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: 'This message is sent from another add-on',
});

In message, you can use Create Message API fields that can be represented as JSON, such as embeds. Transferring attachment data is not supported.

discord-mcbe cannot receive chat when another add-on cancels it in world.beforeEvents.chatSend and sends it again in its own format. Such an add-on can report chat to discord-mcbe with the steps below. Reported chat is handled like regular chat and appears in the console and on Discord.

Call dmc:register once at startup. If there is no response within 20 ticks, discord-mcbe is not installed.

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);
}
Field Description
source Name of the add-on. Use the same value in later notifications. Set only on MCBE-IPC
protocol Version of the format described on this page. Currently 1
features Features to use. Specify minecraft_chat to report chat

features in the response lists the requested features that discord-mcbe accepted. connected is the connection state at the time of the response.

Once minecraft_chat is registered, discord-mcbe stops relaying chat by itself and sends only the chat reported by the add-on to Discord.

Report each chat message that should appear on Discord. The add-on decides which chat to report, for example only global chat.

Send 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] ' },
}),
);
}
Field Description
source The add-on name used at registration. Set only on MCBE-IPC
playerId Player.id of the player who sent the chat
message Message body without decoration
formatting Text placed around the sender name and the message. Can be omitted

formatting accepts the four fields below. Each one is optional and must be a string.

Field Position
namePrefix Before the sender name
nameSuffix After the sender name
messagePrefix Before the message
messageSuffix After the message
  • Notifications from an add-on that has not registered, or for a player who is not online, are ignored.
  • Notifications are ignored while discord-mcbe is disconnected. There is no need to check the connection state before sending.
  • When formatting is omitted, values such as Player.chatNamePrefix are not applied automatically. Read them in the add-on and pass them if needed.
  • message in beforeEvents.chatSend already contains Player.chatMessagePrefix. Do not set messagePrefix when sending that message as is.
  • When bot.allow_addon_messages is false, reported chat is not sent to Discord.

discord-mcbe shows chat from Discord to everyone in the world. If the add-on should decide who sees it, for example to honor a chat mute setting, add discord_chat to features when registering.

Once discord_chat is registered, discord-mcbe stops displaying chat from Discord and passes it to the add-on. The add-on is responsible for displaying it.

It arrives on dmc:discord_chat as a JSON string.

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()) {
// The add-on decides which players do not see it
if (player.hasTag('mute_discord')) continue;
player.sendMessage(text);
}
});
Field Description
text Ready-to-display text. It reflects translation_overrides
message The Discord message text was built from

message is the discord.js Message reduced to the fields a script in the game can use. Use it to match the sender with account linking done by the add-on, or to display the chat in your own format.

{
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,
}
Field Description
content Text after the message filters, with mentions replaced by names. Empty when only files were sent
author.id Discord user ID
author.bot Always false for the sender, since chat from bots is not relayed. Can be true in referencedMessage
member Display name and roles in the server. null when the replied-to author is a webhook or has left the server
member.roles Ordered from the highest role. @everyone is not included
attachments File name and media type of each attachment. contentType is a value such as image/png, or null when unknown
mentions Mentioned users and roles. Entries of users have the same shape as author. A reply that pings also puts the replied-to user in users. everyone tells whether @everyone or @here was used
referencedMessage The message being replied to, or null. Its content is filtered and shortened
  • Only chat from Discord is passed. Other messages, such as the connection notice, are still displayed by discord-mcbe.
  • Each Discord message produces one notification. When a message has both text and attachments, text has two lines.
  • The notification reaches every add-on in the world. If an add-on should not receive user IDs or roles, set bot.allow_addon_messages to false.
  • Register discord_chat from only one add-on per world. If several add-ons register it, each one displays the chat.
  • When bot.allow_addon_messages is false, the registration is ignored and discord-mcbe shows the chat to everyone.
  • If features in the response does not include discord_chat, the installed discord-mcbe does not support this feature. It then shows the chat to everyone as before.

Add-ons are notified when the connection to the server starts and when it ends. Neither notification carries data.

dmc:connect and dmc:disconnect are emitted.

import { IPC, PROTO } from 'mcbe-ipc';
IPC.on('dmc:connect', PROTO.Void, () => {
// The connection to discord-mcbe has started
});
IPC.on('dmc:disconnect', PROTO.Void, () => {
// The connection to discord-mcbe has ended
});

Add-ons built with a bundler can use the name constants, payload types, and validation functions from the @discord-mcbe/shared npm package. What both libraries use is exported as is, and what only one of them uses is grouped under AddonIpc and 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));
Export Description
AddonFeature Feature names such as minecraft_chat
AddonRegisterRequest / AddonRegisterResponse Types of the registration request and response
AddonChatSend / AddonSendMessage Types of reported chat and of a message for Discord
AddonDiscordChat / AddonDiscordMessage Types of chat from Discord and its message
safeParseAddonRegisterResponse / safeParseAddonDiscordChat Validate the registration response and chat from Discord
AddonIpc.Channel MCBE-IPC channel names such as dmc:register
AddonIpc.RegisterRequest / AddonIpc.ChatSend / AddonIpc.SendMessage MCBE-IPC payload types, which add source
AddonSync.NODE_ID Node ID of discord-mcbe on @bedrock-core/sync
AddonSync.Method / AddonSync.Event / AddonSync.StateKey Names of the RPC methods, events and state keys on @bedrock-core/sync
AddonSync.Rpc Type of the RPC on @bedrock-core/sync