支持的版本

bedboo 支持從 1.26.42.1（2026 年 8 月 7 日）到 1.26.63.1（2026 年 11 月 6 日）的所有穩定版 Bedrock Dedicated Server（BDS）， 共 11 個版本，分屬 4 個協議族。 協議族是 minecraft-data / bedrock-protocol 的基岩版版本鍵，例如 '1.26.51'。同一協議族的所有 BDS 版本使用相同的網絡協議， 並共用一套遊戲數據（@bedboo/bedrock-data 的 data/<协议族>/）。bot.version 就是協議族。版本表位於 packages/bedboo/lib/bedrock/versions.js（FAMILIES）。某個協議族同時有 FAMILIES 條目且 @bedboo/bedrock-data 提供其數據時，該 協議族即視為已測試：它會出現在 testedVersions 中，createBot 也會接受它。

版本矩陣

在把一個協議族標記為已測試之前，表中的每個 BDS 版本都以原生方式啟動，並由一個機器人實際加入。機器人檢查了出生、方塊與物品、物品欄、 聊天、行走、挖掘與放置、實體以及命令樹。CI 對每個協議族各運行一次單元測試。本參考的其餘部分（基岩版差異 和 BDS 備忘）是在默認版本 BDS 1.26.51.1 上觀察得出的。各協議族頁面列出了該協議族的不同之處。

不支持預覽版、測試版以及早於 1.26.42.1 的版本。不在表中的 BDS 版本也可能使用這些協議之一，但 bedboo 未針對它做過檢查。

選擇版本

把服務器的版本傳給 createBot。協議族和具體的 BDS 版本都可以，兩者得到的機器人相同：

const bot = bedboo.createBot({
  host: '127.0.0.1',
  port: 19132,
  username: 'Bot',
  version: '1.26.62.1', // 或 '1.26.60'
  transport: 'nethernet' // BDS 1.26.51 及更新版本默认 transport=nethernet
})
bot.once('spawn', () => console.log(bot.version, bot.protocolVersion)) // 1.26.60 2225

• 默認值： 不傳 version，或傳 version: false 時，機器人使用 1.26.51。bedboo 不會檢測服務器的版本（默認不 ping 就直接加入， 因為關閉局域網可見性的 BDS 不響應 ping）。連接其他協議族的服務器時必須指定版本。
• 可接受的值： testedVersions 中的協議族、它的任一 BDS 版本，或者帶 bedrock_ 前綴的上述兩種寫法。其他任何值都會像 mineflayer 遇到不支持的版本時一樣拋出 Error，其 code 為 'ERR_BEDBOO_VERSION'，消息中列出支持的協議族和 BDS 版本。
• 協議族不匹配： BDS 會拒絕其他協議的登錄，機器人以客戶端版本過舊或服務器版本過舊為由被 kicked。
• 隨版本變化的內容： bot.version（協議族）、bot.protocolVersion、bot.majorVersion（'1.26'）、bot.registry （minecraft-data 的 bedrock_<协议族> 加上該協議族的 @bedboo/bedrock-data 補充層）和 bot.supportFeature(...)。 特性表按協議族取值，例如 1.26.60 上的 actionPacketsHaveHand 以及 defaultTransportIsNethernet。
• 模塊導出： testedVersions 按從舊到新的順序列出已測試的協議族（['1.26.40', '1.26.45', '1.26.51', '1.26.60']）。 oldestSupportedVersion 為 '1.26.40'，latestSupportedVersion 為 '1.26.60'。supportFeature(feature, version) 接受協議族、BDS 版本或不傳版本（1.26.51）。

各協議族之間的差異在於少量新增的方塊、物品和實體，部分數據包字段，命令參數類型的編號，以及默認傳輸層。bedboo 按協議族處理這些差異， 機器人的代碼無需改動。各協議族頁面列出了具體差異。

針對某個版本測試

單元測試默認使用 1.26.51。BEDBOO_VERSION 可以選擇其他協議族或 BDS 版本：

pnpm test                              # 1.26.51
BEDBOO_VERSION=1.26.60 pnpm test       # 协议族
BEDBOO_VERSION=1.26.44.3 pnpm test     # BDS 版本，映射到其协议族（1.26.40）

模擬對象、序列化器、註冊表和數據包錄製（packages/bedboo/test/fixtures/<协议族>/）都隨所選版本切換。需要該協議族尚無的錄製的 測試會被跳過，並打印原因。目前只有 1.26.51 有加入過程的錄製，因此在其他協議族上，加入回放測試會被跳過；這部分改由每個 BDS 版本的 實機加入來覆蓋。CI（.github/workflows/ci.yml）在其 bedrock 矩陣中為每個協議族各運行一次 lint、單元測試和類型檢查。手動運行該 工作流時可以傳入 version 參數。

添加版本

已知協議族的新 BDS 版本（協議相同）：把該版本加入 packages/bedboo/lib/bedrock/versions.js 中該協議族的 bds 列表，以及 packages/bedboo/test/version.js 的後備表。檢查它的加入數據與該協議族的數據一致，做法同 1.26.51 頁面 對 1.26.50.5 和 1.26.52.3 的比較。然後把該版本寫入上面的矩陣和該協議族的頁面，並更新其他寫有最新版本或支持範圍的地方： git grep -n '<之前最新的 BDS 版本>' 可以找到它們（README、package.json 描述、英文和 docs/zh/ 文檔）。

新的協議族：

1. minecraft-data 和 bedrock-protocol 必須認識該版本。升級它們（packages/*/package.json 以及 pnpm-workspace.yaml 的 overrides），必要時更新 patches/ 中的 pnpm 補丁。
2. @bedboo/bedrock-data：在 scripts/sources.js 中添加 PINS['<协议族>']，並運行 scripts/fetch-sources.js --version <协议族> --update-lock。把在運行中的 BDS 上觀察到的事實記錄到 scripts/probe/<协议族>.json，把數據表差異寫入 scripts/tables.js 的 VERSION_TABLES，然後運行 scripts/generate.js --version <协议族>。特性差異寫入 data/<协议族>/features.js。在 NOTICE.md 中列出數據來源。 其中的“Adding a data version”一節說明了每一步。
3. bedboo：在 lib/bedrock/versions.js 和 test/version.js 中添加一個 FAMILIES 條目（協議族、協議號、BDS 版本）。 該條目和數據都存在後，協議族即視為已測試。把協議與上一個協議族對比。線上格式的差異通過 data/<协议族>/features.js 中的特性 和 bot.supportFeature 處理。檢查命令參數類型 ID（lib/bedrock/commands.js 中的 VALUE_TYPE_KINDS_BY_VERSION）。
4. CI：把該協議族加入 .github/workflows/ci.yml 的 bedrock 矩陣。運行 BEDBOO_VERSION=<协议族> pnpm test，並用實機機器人 加入該協議族的每個 BDS 版本。
5. 文檔：添加 docs/reference/versions/<协议族>.md 頁面（英文和 docs/zh/），在 docs/docs.config.ts 的導航中加入它，並在上面的 矩陣中添加一行。與新 BDS 版本一樣，更新其他列出協議族和版本的地方（git grep -n '<之前最新的协议族>'）。