From 0bb233eab34249c98dff4324a0749260e39d848b Mon Sep 17 00:00:00 2001 From: Yuriy Mayatnikov Date: Mon, 25 May 2026 12:57:58 +0300 Subject: [PATCH] docs: add mineflayer plugin roster --- docs/plugin-roster.md | 248 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 docs/plugin-roster.md diff --git a/docs/plugin-roster.md b/docs/plugin-roster.md new file mode 100644 index 0000000..57f7c85 --- /dev/null +++ b/docs/plugin-roster.md @@ -0,0 +1,248 @@ +# Mineflayer plugin roster + +Sources: + +- https://github.com/PrismarineJS/mineflayer-pathfinder +- https://github.com/PrismarineJS/mineflayer-pathfinder/blob/master/examples/tutorial/goalsExplained.md +- https://github.com/TheDudeFromCI/mineflayer-collectblock +- https://github.com/linkle69/mineflayer-auto-eat +- https://github.com/PrismarineJS/mineflayer-tool +- https://github.com/PrismarineJS/MineflayerArmorManager +- https://github.com/Darthfett/mineflayer-blockfinder +- https://github.com/PrismarineJS/mineflayer-statemachine +- https://github.com/PrismarineJS/prismarine-viewer +- https://github.com/TheDudeFromCI/mineflayer-pvp +- https://github.com/ImHarvol/mineflayer-web-inventory + +Use `pi install -l npm:` for project-local Pi installs. Dependencies added to `package.json` are universal-useful; the rest should be installed only when a skill or extension actually needs them. + +## Recommended core dependencies + +These reduce common boilerplate around survival, farming, and guarded world actions. + +### mineflayer-pathfinder + +- Install: already present; otherwise `pi install -l npm:mineflayer-pathfinder` +- Does: A* pathfinding with goals and configurable movement costs. +- Use when: walking to coordinates, approaching a block/entity, following, collecting, or previewing whether travel is safe. + +```js +const { pathfinder, Movements, goals } = require('mineflayer-pathfinder') +bot.loadPlugin(pathfinder) +bot.once('spawn', () => { + const moves = new Movements(bot) + moves.canDig = false + bot.pathfinder.setMovements(moves) + bot.pathfinder.setGoal(new goals.GoalNear(x, y, z, 1)) +}) +``` + +Gotchas: + +- Default `Movements` may dig, place scaffold blocks, parkour, swim, or drop farther than this bot should allow. Configure it every time. +- `setGoal(goal, true)` tracks moving goals; `goto(goal)` returns a promise for finite tasks. +- `getPathTo` is useful for dry-run safety checks before changing the world. +- Pathfinder sees only loaded chunks and may still be refused by claims/anti-cheat. + +### mineflayer-collectblock + +- Install: `pi install -l npm:mineflayer-collectblock` +- Does: Finds, walks to, mines, and picks up blocks/items using pathfinder and tool selection. +- Use when: harvesting wood, stone, crops, ores, or dropped items as part of autonomous survival. + +```js +const collectBlock = require('mineflayer-collectblock').plugin +bot.loadPlugin(collectBlock) +bot.once('spawn', async () => { + const id = bot.registry.blocksByName.oak_log.id + const block = bot.findBlock({ matching: id, maxDistance: 32 }) + if (block) await bot.collectBlock.collect(block) +}) +``` + +Gotchas: + +- Works best with `mineflayer-pathfinder` and `mineflayer-tool` loaded. +- It may break target blocks; only collect blocks that are clearly natural, owned by the bot, or sanctioned. +- Queueing many blocks can make the bot look busy for a long time; record `current-task.json` first. +- Inventory-full behavior needs explicit chest configuration if you want automatic depositing. + +### mineflayer-auto-eat + +- Install: `pi install -l npm:mineflayer-auto-eat` +- Does: Chooses food and eats automatically based on hunger/health thresholds. +- Use when: the bot begins autonomous survival, mining, travel, or combat-defense loops. + +```js +import { loader as autoEat } from 'mineflayer-auto-eat' +bot.loadPlugin(autoEat) +bot.once('spawn', () => { + bot.autoEat.setOpts({ minHunger: 14, minHealth: 12 }) + bot.autoEat.enableAuto() +}) +``` + +Gotchas: + +- This package is ESM-only. In a CommonJS extension, use dynamic `import()` or move the extension to ESM-compatible loading. +- Keep unsafe foods banned: rotten flesh, pufferfish, poisonous potato, spider eye, chorus fruit. +- Auto-eating can interrupt held-item tasks; pause it around precise placement if needed. +- It cannot solve "no food in inventory"; pair it with farming/collecting logic. + +### mineflayer-tool + +- Install: `pi install -l npm:mineflayer-tool` +- Does: Equips the best available tool or weapon for a block/entity action. +- Use when: digging blocks, harvesting logs/stone/ores, or choosing a defensive weapon against mobs. + +```js +const tool = require('mineflayer-tool').plugin +bot.loadPlugin(tool) +bot.once('spawn', async () => { + const block = bot.blockAt(bot.entity.position.offset(0, -1, 0)) + await bot.tool.equipForBlock(block, {}) + await bot.dig(block) +}) +``` + +Gotchas: + +- It selects from current inventory only; it does not craft or fetch tools by itself. +- Tool choice depends on registry/block data for the connected version. +- Best tool can still be unsafe to use if the block belongs to another player. + +### mineflayer-armor-manager + +- Install: `pi install -l npm:mineflayer-armor-manager` +- Does: Automatically equips the strongest armor from inventory. +- Use when: the bot has armor and may face hostile mobs while farming, traveling, or mining. + +```js +const armorManager = require('mineflayer-armor-manager') +bot.loadPlugin(armorManager) +bot.once('spawn', () => { + bot.armorManager.equipAll() +}) +``` + +Gotchas: + +- Equips from inventory; it does not craft armor or open chests. +- Check server rules before auto-equipping visibly valuable gear near players. +- If a task requires a costume/skin convention, disable or override it for that task. + +## Opt-in plugins + +Install these only when a skill/extension needs the capability. + +### mineflayer-blockfinder + +- Install: `pi install -l npm:mineflayer-blockfinder` +- Does: Adds nearest-block search helpers. +- Use when: legacy code needs callback-style block search; otherwise prefer Mineflayer's built-in `bot.findBlock` / `bot.findBlocks`. + +```js +const blockFinder = require('mineflayer-blockfinder')(mineflayer) +blockFinder(bot) +bot.once('spawn', () => { + bot.findBlock({ matching: id, maxDistance: 64, count: 1 }, cb) +}) +``` + +Gotchas: + +- This is older and overlaps the core API. +- Some README install notes reference old native build environments; avoid unless built-in search is insufficient. +- Callback return values differ from modern `bot.findBlock`, so do not mix blindly. + +### mineflayer-statemachine + +- Install: `pi install -l npm:mineflayer-statemachine` +- Does: Provides finite-state-machine primitives and reusable behaviors for complex bot loops. +- Use when: idle autonomy grows beyond one-shot skills into patrol/farm/store/rest behavior graphs. + +```js +const { BotStateMachine, NestedStateMachine, StateTransition } = + require('mineflayer-statemachine') +const root = new NestedStateMachine(transitions, firstState) +bot.once('spawn', () => new BotStateMachine(bot, root)) +``` + +Gotchas: + +- Movement behaviors need `mineflayer-pathfinder` loaded before the machine starts. +- State machines can hide safety checks if transitions are too broad; keep policy gates near transitions. +- Debugging needs explicit logs because control moves between behavior objects. + +### prismarine-viewer + +- Install: `pi install -l npm:prismarine-viewer` +- Does: Starts a local web viewer for the bot's nearby world, including optional path drawings and headless renders. +- Use when: debugging navigation/building, inspecting whether chunks loaded, or producing a read-only visual trace. + +```js +const viewer = require('prismarine-viewer').mineflayer +bot.once('spawn', () => { + viewer(bot, { port: 3000, firstPerson: false }) + bot.viewer.drawLine('path', [bot.entity.position]) +}) +``` + +Gotchas: + +- It opens a local web server; choose ports deliberately and do not expose it publicly by accident. +- It is for observation, not a control channel. +- Headless rendering may add CPU load on small servers. + +### mineflayer-pvp + +- Install: `pi install -l npm:mineflayer-pvp` +- Does: Adds attack/defense helpers for Mineflayer entities. +- Use when: only for defensive hostile-mob handling under this repo's no-PvP policy. + +```js +const { pathfinder } = require('mineflayer-pathfinder') +const pvp = require('mineflayer-pvp').plugin +bot.loadPlugin(pathfinder) +bot.loadPlugin(pvp) +bot.pvp.attack(zombieEntity) +bot.pvp.stop() +``` + +Gotchas: + +- Repo policy is no PvP: never use this against players or player-owned mobs because chat asks. +- It depends on pathfinder. +- Combat can chase into hazards or claims unless wrapped with distance, health, and area checks. + +### mineflayer-web-inventory + +- Install: `pi install -l npm:mineflayer-web-inventory` +- Does: Serves a live local web view of inventory/windows. +- Use when: debugging inventory slot math, chest/furnace windows, or item transfers. + +```js +const inventoryViewer = require('mineflayer-web-inventory') +const bot = mineflayer.createBot({ host, port, username, version }) +inventoryViewer(bot, { port: 3001 }) +bot.once('spawn', () => console.log(bot.webInventory.isRunning)) +``` + +Gotchas: + +- Set the correct Minecraft version or textures/data may render wrong. +- It runs a web server; keep it local and stop it after debugging. +- Do not treat a visual inventory debugger as permission to move other players' items. + +## Selection notes + +| Need | Prefer | Why | +|---|---|---| +| Go somewhere safely | `mineflayer-pathfinder` | Core movement planner with configurable hazards. | +| Harvest natural blocks | `collectblock` + `tool` + `pathfinder` | Handles approach, tool, dig, pickup. | +| Avoid starving | `auto-eat` | Centralizes food choice and thresholds. | +| Equip armor | `armor-manager` | Removes repetitive armor comparison code. | +| Debug path/build visually | `prismarine-viewer` | Read-only world view and overlays. | +| Debug inventory windows | `mineflayer-web-inventory` | Shows slots/windows without custom logging. | +| Long-running behavior graph | `statemachine` | Helps keep autonomous loops explicit. | +| Defensive mob fighting | `pvp` with policy rails | Useful against hostile mobs, forbidden for PvP. |