WebSocket 接口

契约：bedd.asyncapi.yaml（spec/，AsyncAPI 3.0；Studio）。

连接

发现文件 %LOCALAPPDATA%\BeDD\run\<pid>.json（根目录 BEDD_HOME），监听期间存在；跳过已退出的 pid。 BeDD.exe ps --json 列出相同内容。

{"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（其 WebSocket 不设请求头）：

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(); };

请求与回复

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

• id：任意 JSON 值，原样返回。失败：{id, ok:false, error, code?, key?}；按 code 判断（错误）。
• 每条连接按顺序处理；并行请求用多条连接。
• 探测：不带参数发送操作（bedboo 操作此时只读）：unknown op = 不存在，disabled = 已关闭，ok = 可用。

选择模式

先 bedboo 操作，再 ui，最后 input 操作（原因）。ping 列出它们：

{"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 操作

配置键为 false → disabled。实现。

* 指 ≥20 tick/s 时；更慢时默认值按 tick 间隔 / 50 ms 放大（不超过上限）。not_in_level：20 个 tick 间隔（≥1 s）内 没有客户端 tick。

stack：通过客户端发送物品堆请求

• buf：一个 item_stack_request 数据包（id 147）；其他 id 或无法解析的字节：bad_args。
• 每个请求分配一个客户端 id：奇数、负数，从 -0x40000001 递减。引用调用方 id 的 stack id 会被改写（本请求和此前 最近 256 个）。map 的键：字符串形式的调用方 id。
• item_stack_response（tap）可能早于回复到达：先保留。
• 无客户端预测。请求被接受：客户端发送 inventory_transaction {type: inventory_mismatch}，服务器重发背包。被拒绝： 无变化。
• 必须打开所需界面（背包、箱子）：action inventory、key E 或使用方块。

timescale：游戏速度

本游戏托管的世界（单人、局域网主机）的速度：客户端与本地服务端一起调整。请求（scale、paused）在两侧都以该速度 运行后回复探测内容；探测还含 local、inLevel。

离开世界重置为 1；进入世界应用 timeScale（1）。错误：not_in_level、remote（不在本机托管）、server_led（由 BeDD 服务端设置：到那边改）、timeout（之后仍会生效）、refused、bad_args。BeDD 服务端在变更时和玩家加入时发送 level_event 3007（SimTimeScale，pos 0,0,0，data = float 位模式按 int32，0 = 暂停）；客户端跟随（0 暂停，保留 scale）。

谁发什么（bedboo 传输 bedd）

所有服务端方向数据包由客户端发送。bedboo 的 lib/bedd/authority.js 丢弃客户端自有的数据包，把其他数据包映射到操作 （input、look、slot、button、action、settings、stack、join、key ESC），用 send 发送 text 和 command_request （后备：T/SLASH、text、ENTER），通过 ui 操作离开床和告示牌编辑界面，其他 sendAllow 中的 id 用 send 原样发送， 其余抛出 ERR_BEDD_UNSUPPORTED（BeddUnsupportedError）。

ui 操作

ui 把界面读成带 ref 的文本并对 ref 执行动作；oreui 返回原始 Ore UI DOM；mouse 可带 ref。配置键 ui 控制这三者。 字段、回复和错误：UI 树。

input 操作

无配置键。游戏线程派发输入后回复（timeoutMs 5000）。

系统操作

错误

无 code：未知操作、不是 JSON 对象、输入未及时派发、名称无效（key、button）。

多个客户端

窗口输入类操作在各连接间串行；ping、state、manager、close、tap、world、look、input、settings、send、stack、 timescale、join、screenshot、oreui 和 ui 读取不串行。断开时：

模组中的每连接状态：代码规范。

安全

能读发现文件的人（该用户的进程）都能驱动游戏。令牌按常数时间比较。

• send：以已登录玩家身份发包，限于 sendAllow（默认 9 text、77 command_request、78 command_block_update、97 book_edit）。id 1、30、144、147 始终拒绝。 只为自己的服务器放宽。
• sendAllow: "*"：除客户端自己发送的数据包外全部允许，排除：1 login、4 握手、8 资源包应答、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 客户端缓存、144、147、152 emote_list、175 subchunk_request、193 request_network_settings、312 serverbound_loading_screen。其他包可能让客户端和服务器的状态对不上（不是客户端自己发的）。
• stack：在任何服务器上移动、合成、丢弃和销毁玩家的物品。
• tap：整个会话。

关闭不需要的 allowSend、allowStack、tap；不要分享令牌。

服务端目标

--target_type=server（构建）在装有 LeviLamina 的 BDS 中运行：同样的 WebSocket， kind:"server"，其他操作回复 unknown op。

变更时及每个玩家生成时广播 level_event 3007（见上）。tps.server 可能滞后于 ticksPerSecond。错误：not_in_level、 bad_args、timeout。