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。