Developers Writing a plugin
Your first plugin
A plugin is one JavaScript file that adds Discord commands to a Minecraft world. BedrockRelay does the Discord side; you write what happens in the game.
The file
A plugin default-exports a definition: who it is, and the Discord commands it adds, each with a run(). This one adds /health:
// health.js
import { findPlayer } from "../relay/api.js";
export default {
id: "health",
name: "Health",
version: "1.0.0",
description: "Check a player's health from Discord.",
platforms: ["server", "realm"],
commands: [
{
name: "health",
description: "Show a player's health",
options: [{ name: "player", type: "player", description: "The player's name", required: true }],
run({ player: name }) {
const player = findPlayer(name);
if (!player) return `**${name}** isn't online right now.`;
const health = player.getComponent("minecraft:health");
return { embed: { title: player.name, description: `❤ ${Math.ceil(health.currentValue)} / ${health.effectiveMax}` } };
},
},
],
};
Inside run() you have the whole Minecraft Script API, and a few helpers from ../relay/api.js. Whatever you return is the answer in Discord.
The same file runs on a Bedrock Dedicated Server and on a Realm. platforms says it may go on both; leave it out and it's for dedicated servers only. On a Realm, a plugin can use only the stable Script API, which everything above is. See Plugins on Realms.
Trying it
You need a Minecraft world of your own with BedrockRelay set up and connected to a Discord server: a Realm, or a Bedrock Dedicated Server.
From the dashboard, on a Realm or a server
- Open your world on the dashboard and go to its Plugins tab.
- Under Your own plugins, choose Upload a plugin and pick
health.js. It's now a private plugin, listed for you alone. - Install it on the world. A Realm closes while BedrockRelay updates its pack, and opens again by itself. A dedicated server gets the file over SFTP, and loads it when you next restart it.
- In a connected Discord server, run
/health. The plugin is switched on the first time the world reports it, and at first only Discord administrators can use it.
To try a change, raise version and choose Upload new version on its card, then update it on the world.
By hand, on a dedicated server
On a server whose files you can reach, copying the file in is quicker for trying one change after another. You need BedrockRelay pack v0.3.0 or newer.
- Put
health.jsindevelopment_behavior_packs/BedrockRelay/scripts/plugins/. - Add its name, without
.js, to the list inscripts/plugins/index.jsin the same folder:export default ["health"]; - Restart the Minecraft server. The console shows
[BedrockRelay] plugin loaded: Health 1.0.0. If it doesn't, see Testing. - Run
/healthin Discord, as above.
Updating the BedrockRelay pack never touches your files in scripts/plugins/, and keeps your entries in index.js.
A Realm has no files you can reach and no console, so the dashboard is the only way in, and you can't see why a plugin failed to load. If you have a dedicated server too, get a plugin working there first. See Testing.
Where next
- Plugin reference: every field, and the options a command can take.
- Answers and context: embeds, player heads, pictures, and who asked.
- Best practices: read these before you share a plugin with anyone.
Running a Minecraft world rather than building for one? The help covers everything from setup to troubleshooting.
Read the help