生態插件

為 mineflayer 編寫的插件可以通過 bot.loadPlugin() 原樣加載。常用插件已在 bedboo 工作區中固定版本，它們少數幾處基於 Java 版的假設（Java 的 entity_status 數據包、Java 的附魔 NBT……）由 patches/mineflayer-*.patch 中的小型 pnpm 補丁修復。 只使用 mineflayer 公開 API 的插件不需要任何處理。

pnpm-workspace.yaml 中的 overrides 固定了打過補丁的版本，因此每個包（包括插件之間的相互依賴）加載的都是同一份打過補丁的副本。 在工作區之外請應用相同的補丁（pnpm patch / patch-package）：不打補丁時，auto-eat 會一直等待一個永遠不會到來的 Java entity_status，pathfinder 會挖穿門，還會因為重新居中而與服務器來回拉扯。每個補丁改了什麼、為什麼改： 生態插件補丁。

加載

const bedboo = require('bedboo')
const { pathfinder, Movements, goals } = require('mineflayer-pathfinder')

const bot = bedboo.createBot({ host, port, username })
bot.loadPlugin(pathfinder)
bot.loadPlugin(require('mineflayer-pvp').plugin) // 需要先加载 pathfinder
bot.loadPlugin(require('mineflayer-collectblock').plugin) // 会在下一 tick 自行加载 pathfinder 和 tool
bot.loadPlugin(require('mineflayer-armor-manager'))
const { loader: autoEat } = await import('mineflayer-auto-eat') // 仅支持 ESM
bot.loadPlugin(autoEat)

移植到基岩版的 mineflayer 示例位於庫的 examples/ 目錄中（插件示例：pathfinder/gps.js、collectblock.js、 guard.js、auto-eat.js）。

mineflayer-pathfinder

基岩版上推薦的 Movements 設置：

const moves = new Movements(bot)
moves.canOpenDoors = true // 木门（所有木材、铜门）和栅栏门会被打开而不是挖掉（已打补丁）
moves.allowSprinting = true // 默认值
moves.allowParkour = true // 默认值：1–3 格的间隙（已验证 2 格间隙）
moves.allow1by1towers = true // 默认值：用搭建用方块垫高（泥土、圆石；可在
// moves.scafoldingBlocks 中添加更多 ID，例如 bot.registry.itemsByName.netherrack.id）
moves.canDig = true // 默认值；挖掘代价按基岩版挖掘速度计算（状态效果、附魔）
bot.pathfinder.setMovements(moves)
bot.pathfinder.thinkTimeout = 20000 // 推荐值（上游为 5000 ms）：见下文

• thinkTimeout：主世界區塊的高度範圍是 y -64..319，在自然地形上搜索會訪問大量節點；在負載較高的主機上，幾格之外的簡單目標 也可能超過默認的 5 秒，此時 goto 會以 Timeout: Took to long to decide path to goal! 拒絕。搜索很快時，調大它沒有任何代價。

• 放置失敗永遠不會讓路徑卡住（已打補丁；上游 2.4.5 在以下每種情況下都會卡住）：

  • 搭建方塊的 bot.equip 被拒絕時，會釋放 pathfinder 的裝備鎖；
  • 被拒絕的放置會重試一次，之後在針對當前目標的後續搜索中避開該格（bot.pathfinder.refusedPlacements， maxPlaceRetries = 1）：路徑會繞道，或者目標無路可達；連續 maxPlaceFailures（6）次放置失敗後，goto 以 NoPath 拒絕（"… placements failed in a row"）。用同一個目標對象重試會保留被拒絕的格子；新目標則重新開始；
  • 放置或點擊門耗時超過 bot.pathfinder.placeTimeout（10 秒）視為失敗；
  • 放置尚未完成時調用 stop()，會在下一 tick 結束（其遲到的結果會被忽略）；
  • 失敗後機器人會從探身出去的邊緣退回，而從邊緣開始的搜索會以機器人腳下的方塊為起點。

  path_reset 的原因：equip_error、place_error、use_error、place_timeout、stop。

• 名稱使用基岩版名稱；流動的水 / 岩漿、含水的植物和含水方塊都視為液體。

• 執行器的 fullStop() 不再在客戶端重新居中機器人（BDS 會把它糾正回去）；機器人停下時，最多偶爾出現約 0.24 格的服務端糾正。

• 未處理（與上游相同）：活板門、鐵門（canDig 時會被挖掉）、藤蔓（不可攀爬）、基岩版的腳手架方塊、真正意義上的游泳 （機器人通過跳躍漂浮來渡水）。

• 空閒時調用 bot.pathfinder.stop() 不做任何事，目標不可達時 goto() 以 NoPath 拒絕（從上游 master 回移）。 GoalFollow 在機器人被擊退時會重新規劃。

• 門：BDS 只打開門的下半部分；bedboo 讓上半部分採用打開後門扇的形狀，因此機器人能從它打開的門原路走回 （門的上下兩半）。

• 在基岩版上，只要按住 forward，疾跑就會持續：pathfinder 鬆開疾跑控制並不會讓機器人減速，直到它停下為止 （粘滯疾跑）。

• 經驗球、投擲出的藥水、三叉戟、煙花火箭和其他彈射物均可穿過。

mineflayer-pvp

• 盾牌：在基岩版上 activateItem(true) 通過潛行舉起盾牌，因此持盾時機器人在兩次攻擊之間以潛行速度移動；pathfinder 的 clearControlStates() 不會放下盾牌（只有 deactivateItem() 會）；正在點燃的苦力怕（基岩版的 ignited 標誌）會讓 pvp 舉起盾牌（已打補丁）。
• 遠程生物（骷髏、流浪者、掠奪者）會後退：請設置 bot.pvp.followRange = 1，否則機器人可能停在 4 格之外，超出 3.5 格的攻擊距離 （這也是上游在 Java 版上的行為）。
• 基岩版沒有攻擊冷卻；pvp 按 Java 版冷卻計時，只是攻擊得比實際可能的略慢一些。

mineflayer-auto-eat

ESM：const { loader } = await import('mineflayer-auto-eat')。通過 bot.autoEat.setOpts({ minHunger, priority, bannedFood })、enableAuto() / disableAuto() 配置，bot.autoEat 上有 eatStart / eatFinish / eatFail 事件。進食在基岩版的 completed_using_item 時完成（已打補丁）。和平難度下飢餓值永遠不會下降。修復了上游的兩個 bug：裝備失敗 不再讓插件永遠處於“進食中”狀態；在 strictErrors（默認）下，eat() 拒絕之前也會發出 eatFail。

mineflayer-collectblock、-tool、-armor-manager

• collectblock：在背包中有工具和搭建用方塊的情況下調用 collect(blocks)；背包滿時會使用 chestLocations（箱子方塊的 Vec3）。回調形式 collect(target, cb) 可用（已打補丁）；cancelTask() 會在當前步驟完成後結束任務（已打補丁）。
• tool：沒有任何物品能採集該方塊時，equipForBlock(block, { requireHarvest }) 以 NoItem 拒絕；使用 getFromChest 但沒有箱子時同樣如此（已打補丁：上游會無限遞歸直至內存耗盡）。
• armor-manager：拾取的盔甲、盾牌和不死圖騰會逐件穿戴（已打補丁）；equipAll()。