Plugins on Realms

How it gets there

A Realm has no files you can reach. When an owner adds plugins to a Realm on the dashboard, BedrockRelay puts them inside the Realm pack and installs that: the Realm closes, the world is updated, and it opens again. Your plugin is loaded the same way as on a dedicated server, from scripts/plugins/ with the same ../relay/api.js helpers.

Plugins on a Realm need Realm pack v1.2.0. Every plugin field and context value on this site works there.

Saying where it runs

A plugin runs only where it says it does:

• In the catalog, "platforms": ["server", "realm"] in plugin.json. See plugin.json.
• For a private plugin, platforms: ["server", "realm"] in the definition itself.

Leave it out and the plugin is for dedicated servers only: the dashboard won't offer it for a Realm. Only add realm once the plugin has run on one.

Stable APIs only

On a dedicated server BedrockRelay runs with Beta APIs, so a plugin there can use experimental parts of the Script API. The Realm pack runs without them, on the stable @minecraft/server 2.10.0. A plugin that uses anything newer or experimental fails to load on a Realm and is skipped.

Check every class, method and event you use is in the stable API. Microsoft's Script API reference marks what's still in beta. Don't import any other module: @minecraft/server is the only one there.

Our bot is a player

On a Realm, BedrockRelay's bot is in the world as a player, in spectator far away in the End. findPlayer() never returns it, but world.getAllPlayers() and player events include it. It carries the tag bedrockrelay:bot, so leave it out of anything you count or list:

const BOT_TAG = "bedrockrelay:bot";
const players = world.getAllPlayers().filter((player) => !player.hasTag(BOT_TAG));

Do this on dedicated servers too: it costs nothing, and it keeps one file right for both.

Other differences

• Keep options short. Each request reaches the Realm as a command typed by our bot. One over about 500 characters, with all its options, is refused rather than cut off.
• Posts need the bot. postToDiscord goes by way of our bot, so a post made while it isn't in the Realm is lost.
• No console. You can't see a Realm's content log. A plugin that fails to load is skipped, and its commands never appear in Discord.
• Installing closes the Realm. Every install, update or removal of a plugin reinstalls the Realm pack, so owners notice each release. Batch your fixes.

Trying it on a Realm

Test on a dedicated server first, where you can see errors (see Testing). Then, on a Realm you own, upload the plugin as a private plugin with platforms: ["server", "realm"] and install it from the dashboard. Once it works there, it's ready to be marked for Realms in the catalog.