WebSocket API

Contract: bedd.asyncapi.yaml (spec/, AsyncAPI 3.0; Studio).

Connecting

Discovery file %LOCALAPPDATA%\BeDD\run\<pid>.json (root BEDD_HOME), present while listening; skip dead pids. BeDD.exe ps --json lists the same.

{"protocol": 2, "kind": "client", "pid": 23116, "url": "ws://127.0.0.1:53021/v1", "token": "9c1f…(64 hex)",
 "instance": "MyInstance-2", "instanceDir": "…\\instances\\MyInstance-2", "label": "smoke test", "modVersion": "0.4.0", "startedAt": "2026-11-13T09:41:07Z"}

Node.js 24 (its WebSocket sets no headers):

import { readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
const dir = join(process.env.BEDD_HOME ?? join(process.env.LOCALAPPDATA, 'BeDD'), 'run');
const game = readdirSync(dir).map((f) => JSON.parse(readFileSync(join(dir, f), 'utf8')))
  .find((e) => e.kind === 'client'); // and its pid alive
const ws = new WebSocket(`${game.url}?token=${game.token}`);
ws.onopen = () => ws.send(JSON.stringify({ id: 1, op: 'world' }));
ws.onmessage = (e) => { console.log(JSON.parse(e.data)); ws.close(); };

Requests and replies

{"id": 7, "op": "look", "yaw": 90, "pitch": 0}
{"id": 7, "ok": true, "yaw": 90, "pitch": 0, "tick": 5182, "turns": 1}

• id: any JSON value, echoed. Failure: {id, ok:false, error, code?, key?}; match code (Errors).
• Each connection is served in order; use more connections for parallel requests.
• Probe: an op without arguments (read-only for bedboo ops): unknown op = absent, disabled = off, ok = present.

Choosing a mode

bedboo ops first, then ui, then input ops (why). ping lists them:

{"ok": true, "protocol": 2, "pid": 23116, "kind": "client", "defaultMode": "bedboo",
 "modes": {"bedboo": ["world","look","input","slot","action","button","settings","send","stack","timescale","join","tap"],
           "ui": ["ui","oreui"], "input": ["key","text","mouse","raw","release","flush","focus","window","screenshot"]},
 "hwnd": 4589122, "managed": true, "client": {"w": 1280, "h": 720}, "cursor": {"x": 640, "y": 360}, "realForeground": false}

bedboo ops

Config key false → disabled. Implementation.

* At ≥20 ticks/s; slower, defaults scale by tick interval / 50 ms (up to the max). not_in_level: no client tick within 20 tick intervals (≥1 s).

stack: item stack requests through the client

• buf: one item_stack_request packet (id 147); other ids or unreadable bytes: bad_args.
• Each request gets a client id: odd, negative, down from -0x40000001. Stack ids naming caller ids are renamed (own and the last 256 earlier). map keys: caller ids as strings.
• The item_stack_response (tap) may precede the reply: hold it.
• No client prediction. Accepted request: the client sends inventory_transaction {type: inventory_mismatch}, the server resends the inventory. Rejected: nothing changes.
• The needed screen (inventory, chest) must be open: action inventory, key E, or use the block.

timescale: game speed

Speed of a world this game hosts (singleplayer, LAN host): client and local server together. A request (scale, paused) replies the probe once both sides run at it; probe also has local, inLevel.

Leaving a world resets to 1; entering applies timeScale (1). Errors: not_in_level, remote (not hosted here), server_led (a BeDD server sets it: change it there), timeout (still applies later), refused, bad_args. A BeDD server sends level_event 3007 (SimTimeScale, pos 0,0,0, data = float bits as int32, 0 = paused) on change and on join; the client follows (0 pauses, keeping the scale).

Who sends what (bedboo transport bedd)

The client sends every serverbound packet. bedboo's lib/bedd/authority.js drops client-owned packets, maps others to ops (input, look, slot, button, action, settings, stack, join, key ESC), sends text and command_request with send (fallback T/SLASH, text, ENTER), works Leave Bed and the sign editor through ui, sends other sendAllow ids as is with send, and throws ERR_BEDD_UNSUPPORTED (BeddUnsupportedError) for the rest.

ui ops

ui reads the screens as text with refs and acts on a ref; oreui returns the raw Ore UI DOM; mouse takes a ref. Config key ui covers all three. Fields, replies and errors: UI tree.

input ops

No config key. Reply after the game thread dispatched the input (timeoutMs 5000).

System ops

Errors

No code: unknown op, not a JSON object, input not dispatched in time, invalid names (key, button).

Several clients

Window-input ops are serialized across connections; ping, state, manager, close, tap, world, look, input, settings, send, stack, timescale, join, screenshot, oreui and ui reads are not. On disconnect:

Per-connection state in the mod: code rules.

Security

Anyone who can read the discovery file (the user's processes) can drive the game. Token compared in constant time.

• send: packets as the signed-in player, within sendAllow (default 9 text, 77 command_request, 78 command_block_update, 97 book_edit). Ids 1, 30, 144, 147 are always refused. Widen only for your own server.
• sendAllow: "*": every id but the ones the client sends itself: 1 login, 4 handshake, 8 resource pack response, 23 tick_sync, 30, 44 animate, 45 respawn, 75 show_credits, 93 player_skin, 94 subclient_login, 113 set_local_player_as_initialized, 115 network_stack_latency, 129/135 client cache, 144, 147, 152 emote_list, 175 subchunk_request, 193 request_network_settings, 312 serverbound_loading_screen. Others may desync the client from the server (it did not make them).
• stack: moves, crafts, drops and destroys the player's items on any server.
• tap: the whole session.

Turn off unneeded allowSend, allowStack, tap; never share a token.

Server target

--target_type=server (Building) runs in BDS with LeviLamina: same WebSocket, kind:"server", other ops unknown op.

It broadcasts level_event 3007 (above) on change and to each spawned player. tps.server may trail ticksPerSecond. Errors: not_in_level, bad_args, timeout.