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

  1. Open your world on the dashboard and go to its Plugins tab.
  2. Under Your own plugins, choose Upload a plugin and pick health.js. It's now a private plugin, listed for you alone.
  3. 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.
  4. 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.

  1. Put health.js in development_behavior_packs/BedrockRelay/scripts/plugins/.
  2. Add its name, without .js, to the list in scripts/plugins/index.js in the same folder: export default ["health"];
  3. Restart the Minecraft server. The console shows [BedrockRelay] plugin loaded: Health 1.0.0. If it doesn't, see Testing.
  4. Run /health in 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

Running a Minecraft world rather than building for one? The help covers everything from setup to troubleshooting.

Read the help