Developers Writing a plugin

Answers and context

What run(args, context) is given, what it can send back to Discord, and the helpers that come with BedrockRelay.

What run() returns

run() executes on the next game tick, where you can read and change the world freely. It may be async. Return, or resolve to, any of:

A string, shown as a message. Discord markdown works.
{ message }, { embed }, or both. embed is a Discord embed, below.
Nothing, and the answer is "Done."

The answer is shown only to the person who asked, unless the command is public. On its way, BedrockRelay removes Minecraft § colour codes, defuses @everyone, @here and role mentions, and keeps everything within Discord's limits.

Embeds

These embed fields are used; anything else is left out.

Field	Notes
`title`, `description`	Up to 256 and 4,096 characters.
`url`	Makes the title a link. `https` only.
`color`	A number, like `0x57f287`.
`author`	`{ name, icon_url }`, or `{ name, player }` for a player's head as the icon.
`fields`	Up to 25 of `{ name, value, inline }`. A value is cut at 1,024 characters.
`footer`	`{ text }`.
`thumbnail`	`{ url }`, or `{ player: "Steve" }` for that player's head.
`image`	`{ url }`, or a picture you draw.

Image links must be https. Use { player } for heads rather than a link of your own: BedrockRelay knows every player's skin, and your plugin doesn't know BedrockRelay's address.

Pictures you draw

A plugin can draw a picture, such as a map, and BedrockRelay turns it into an image. Put it in the embed as image: { pixels: { width, height, palette, data, markers } }:

width and height: up to 256 each.
palette: up to 256 colours as "#rrggbb", or "" for transparent.
data: base64, one palette index per pixel, row by row from the top left.
markers (optional, up to 10): [{ x, y, player }], that player's head drawn centred on that pixel.

BedrockRelay scales it to about 512 pixels across and attaches it to the reply. The Map plugin in the catalog is a worked example. Pictures work in command replies, not yet in live boards or posts. Pack v0.4.0.

Errors

Throw an Error and its message is shown to the person, so make it helpful: throw new Error("That player has never joined."). On a dedicated server it's also written to the content log.

If the world doesn't answer within about 12 seconds, the person is told it's offline. Nothing is sent after that, even if your run() finishes later.

The context

The second argument tells you about the request. Access has already been checked: if run() is called, the person is allowed.

Field	Description
`requestedBy`	The Discord display name of whoever ran the command, for your information only. Don't use it to decide who may do what.
`linkedPlayer`	Their Minecraft name if they've linked their account with `/relay link`, otherwise `null`. Use it so people can leave out their own name: `const name = args.player ?? context.linkedPlayer`. Pack v0.4.0.
`live`	`true` when a live board is refreshing itself. Nobody asked, so `requestedBy` is `"BedrockRelay"` and `linkedPlayer` is `null`.

Helpers

Import these from "../relay/api.js". They work the same on a dedicated server and a Realm. Everything else is the normal @minecraft/server API.

Helper	Does
`findPlayer(name)`	An online player by name, ignoring case, or `undefined`. Never BedrockRelay's own bot on a Realm.
`prettyName(typeId)`	`"minecraft:diamond_sword"` → `"Diamond Sword"`.
`postToDiscord(post)`	Posts at any time, not only in reply to a command. See Posting to Discord.

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

Read the help