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.

FieldNotes
title, descriptionUp to 256 and 4,096 characters.
urlMakes the title a link. https only.
colorA number, like 0x57f287.
author{ name, icon_url }, or { name, player } for a player's head as the icon.
fieldsUp 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. There are two ways to describe one: colours, where you choose every pixel's colour, or blocks, where you say which block each pixel shows and BedrockRelay draws it with Minecraft's own textures.

Either way, BedrockRelay scales it to about 512 pixels across and attaches it to the reply. Pictures work in command replies, not yet in live boards or posts. Pack v0.4.0.

Colours

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.

The Map plugin in the catalog is a worked example.

Blocks

For a picture of the world, let BedrockRelay do the colouring: say what each pixel shows, and it's drawn with the game's own textures, so your plugin needs no colour table. Put it in the embed as image: { blocks: { width, height, palette, data, over, markers } }:

  • width, height and markers: as for colours.
  • palette: up to 256 entries, each a block id like "minecraft:oak_log" (block.typeId as it is), or a plain colour, "#rrggbb" or "#rrggbbaa", for anything that isn't a block, like the sky or a mob. "" is transparent.
  • data: base64, three bytes per pixel, row by row from the top left:
    1. the palette index;
    2. where on the block's face: u * 16 + v, with u across and v down, each 0 to 15 (one of the texture's 16 × 16 texels);
    3. the face and how brightly it's lit: face * 32 + light, with face 0 to 5 for up, down, north, south, east, west, and light 0 (black) to 31 (the texture as it is).
    For a plain colour, only the light is used.
  • over (optional): see-through things drawn on top, like glass, plants and rails, so what's behind shows through their gaps. Base64, five bytes each: the pixel's number (y * width + x) as two bytes, low byte first, then the same three bytes as in data. Up to 16,384, drawn in order, so list the farthest first.

A block BedrockRelay doesn't know, like one from an addon, is drawn grey. The face picks which of the block's textures is used, as the game's own resource pack gives them: a log's ends are its up and down faces, so for a log lying on its side, give the face as the log sees it. A few blocks use their up face for another look, like a curved or powered rail.

Where neighbouring pixels on the same face jump several texels apart, which happens far away, BedrockRelay draws a smoothed version of the texture, the way the game does, so distant ground reads as its colour rather than as noise.

Working out a pixel from a getBlockFromRay hit:

const FACES = ["Up", "Down", "North", "South", "East", "West"];
const t = (n) => Math.max(0, Math.min(15, Math.floor(n * 16)));
const p = hit.faceLocation; // 0 to 1 within the block
const uv = {
  Up: [p.x, p.z], Down: [p.x, 1 - p.z],
  North: [1 - p.x, 1 - p.y], South: [p.x, 1 - p.y],
  East: [1 - p.z, 1 - p.y], West: [p.z, 1 - p.y],
}[hit.face];
cells.set([indexOf(hit.block.typeId), t(uv[0]) * 16 + t(uv[1]), FACES.indexOf(hit.face) * 32 + 31], pixel * 3);

A 256 × 144 picture is about 150 KB of base64, which is fine. Keep the whole reply under 300 KB or so: it travels to BedrockRelay with the world's other events. The Paintings plugin in the catalog is a worked example, including how to cast tens of thousands of rays without slowing the server.

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 (30 for a command marked slow), 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.

FieldDescription
requestedByThe Discord display name of whoever ran the command, for your information only. Don't use it to decide who may do what.
linkedPlayerTheir 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.
livetrue 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.

HelperDoes
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