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.embedis 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. 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 } }:
widthandheight: 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,heightandmarkers: as for colours.palette: up to 256 entries, each a block id like"minecraft:oak_log"(block.typeIdas 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:- the palette index;
- where on the block's face:
u * 16 + v, withuacross andvdown, each 0 to 15 (one of the texture's 16 × 16 texels); - the face and how brightly it's lit:
face * 32 + light, withface0 to 5 for up, down, north, south, east, west, andlight0 (black) to 31 (the texture as it is).
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 indata. 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.
| 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