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:.
Create a node and start it once the world has loaded. The examples below use the sync created here.
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 joins as a node with the ID discord-mcbe. The ID of the add-on’s node is what discord-mcbe uses as the add-on name.
Check whether discord-mcbe is installed
Section titled “Check whether discord-mcbe is installed”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), ]);}When discord-mcbe is installed, it shows up as a peer. The connected state tells whether it is connected to its server.
sync.discovery.onPeerUp((peer) => { if (peer.id !== 'discord-mcbe') return; // discord-mcbe is installed});
// true: connected / false: disconnected / undefined: not found yetconst connected = sync.state.get('discord-mcbe', 'connected');Send a message to Discord
Section titled “Send a message to Discord”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',});Call the sendMessage RPC. It responds with true when the message was passed on to the server, and false while discord-mcbe is disconnected.
function sendDiscordMessage(message: Record<string, unknown>) { return sync.rpc.request('discord-mcbe', 'sendMessage', { message });}
void sendDiscordMessage({ 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.
Integrate an add-on that handles chat
Section titled “Integrate an add-on that handles chat”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.
1. Register at startup
Section titled “1. Register at startup”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);}Call the register RPC once discord-mcbe shows up as a peer. The registration is removed automatically when the add-on leaves the world.
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;});| 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.
2. Report chat
Section titled “2. Report chat”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] ' }, }), );}Call the chatSend RPC. It responds with true when the chat was passed on to the server, and false when it was not.
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] ' }, });}| 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
formattingis omitted, values such asPlayer.chatNamePrefixare not applied automatically. Read them in the add-on and pass them if needed. messageinbeforeEvents.chatSendalready containsPlayer.chatMessagePrefix. Do not setmessagePrefixwhen sending thatmessageas is.- When
bot.allow_addon_messagesisfalse, reported chat is not sent to Discord.
Display chat from Discord
Section titled “Display chat from 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); }});It arrives as the discordChat event.
import { world } from '@minecraft/server';
sync.events.on('discord-mcbe', 'discordChat', (payload) => { const { text } = payload 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,
texthas 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_messagestofalse. - Register
discord_chatfrom only one add-on per world. If several add-ons register it, each one displays the chat. - When
bot.allow_addon_messagesisfalse, the registration is ignored and discord-mcbe shows the chat to everyone. - If
featuresin the response does not includediscord_chat, the installed discord-mcbe does not support this feature. It then shows the chat to everyone as before.
Listen for connection events
Section titled “Listen for connection events”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});The connect and disconnect events are emitted. The current state can also be read from the connected state.
sync.events.on('discord-mcbe', 'connect', () => { // The connection to discord-mcbe has started});
sync.events.on('discord-mcbe', 'disconnect', () => { // The connection to discord-mcbe has ended});Use the types and constants
Section titled “Use the types and constants”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));import { AddonSync } from '@discord-mcbe/shared';
const dmc = sync.rpc.typed<AddonSync.Rpc>(AddonSync.NODE_ID);await dmc.chatSend({ playerId: player.id, message: 'hello' });| 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 |