xmatic/pepa-pi-bot
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #1 from xmatic-squad/feat/knowledge-base

Browse Source 
docs: add minecraft knowledge base
This commit was merged in pull request #1.
This commit is contained in:
Yuriy Mayatnikov
2026-05-25 13:11:09 +03:00
committed by GitHub
parent ca0897b951 978fdc6b48
commit 7060daac46
7 changed files with 1223 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+2
View File
@@ -122,6 +122,8 @@ Don't get yanked around by every passing message. A bot that arrives where it wa
### 4. "I'll try to learn" — bias to action
Before trying something new in Mineflayer or in the Minecraft world, glance at `docs/mineflayer-cheatsheet.md`, `docs/plugin-roster.md`, and `docs/minecraft-knowledge.md` as relevant — they cover the common case; you write the skill afterward in your own style.
When asked to do something you don't yet know how:
1. In chat, brief response: "I haven't done that before — let me try to learn."
docs/minecraft-knowledge.md
+377
View File
@@ -0,0 +1,377 @@
# Minecraft knowledge for a farmer bot
Target: Minecraft Java 1.21.x. The observed server path uses a 1.21.5 client through ViaBackwards/Paper compatibility, so prefer 1.21-compatible recipes and mechanics. This is reference material; use it to shorten research before drafting skills.
See also: [`minecraft-recipes.json`](./minecraft-recipes.json) for machine-readable recipe shapes.
## World rules
Sources:
- https://minecraft.wiki/w/Daylight_cycle
- https://minecraft.wiki/w/Sleeping
- https://minecraft.wiki/w/Weather
- https://minecraft.wiki/w/Light
- https://minecraft.wiki/w/Mob_spawning
- https://minecraft.wiki/w/Spawn
| Topic | Practical rule |
|---|---|
| Time | One full day is 24000 game ticks = 20 real minutes at 20 TPS. Day starts at 0, noon 6000, sunset around 12000, midnight 18000. |
| Night risk | Hostiles become the main surface risk after sunset and during thunderstorms. Plan roof/light before long idle work. |
| Sleep | A bed can be entered at night or during thunderstorms if the bot is close enough, the bed is usable, and hostile mobs are not too near. Multiplayer servers may require only some players to sleep, all players to sleep, or may disable sleeping. |
| Weather | Rain darkens the sky, hydrates farmland, extinguishes exposed fire, and lets some daylight-burning mobs survive longer. Thunderstorms darken enough for hostile spawning behavior and lightning hazards. Savannas/deserts do not receive ordinary rain. |
| Light values | Light is 0-15. Block light falls by 1 per block of taxicab distance from the source. Sky light exposed to open sky is 15 and spreads, but internal sky light changes with time/weather. |
| Hostile spawning | In modern Java, most common hostile overworld mobs require block light 0 plus normal spawn space/surface rules. Sky light/internal sky light can still matter outside caves. |
| Passive spawning | Many farm animals need grass blocks, air space, and a higher light level; they are unreliable in dark pens. |
| Spawn surfaces | Most mobs need a solid top surface and enough empty collision space. Buttons, slabs, carpets, water, leaves, fences, and transparent/non-full blocks can change spawnability. |
| Player distance | Natural hostile spawning generally happens away from players, not right on top of them. Do not assume a lit base is safe if dark caves nearby remain loaded. |
Bot heuristics:
- Before night: get under a roof or place light sources around the work area.
- For conservative mob-proofing, keep walkable surfaces at block light 8 or above. For 1.21 most common hostile mobs only need block light 0, but 8+ is an easy safety margin and works across older assumptions.
- Do not build farms where the bot must jump on farmland; jumping can trample it.
## Mobs
Sources:
- https://minecraft.wiki/w/Zombie
- https://minecraft.wiki/w/Skeleton
- https://minecraft.wiki/w/Creeper
- https://minecraft.wiki/w/Spider
- https://minecraft.wiki/w/Enderman
- https://minecraft.wiki/w/Slime
- https://minecraft.wiki/w/Witch
- https://minecraft.wiki/w/Drowned
- https://minecraft.wiki/w/Husk
- https://minecraft.wiki/w/Phantom
- https://minecraft.wiki/w/Cow
- https://minecraft.wiki/w/Sheep
- https://minecraft.wiki/w/Pig
- https://minecraft.wiki/w/Chicken
- https://minecraft.wiki/w/Bee
- https://minecraft.wiki/w/Wolf
| Mob | Type | Spawn / trigger | Threat | Drops / value | Defeat or avoid |
|---|---|---|---|---|---|
| Zombie | Hostile | Overworld dark areas, commonly block light 0; variants by biome. | Medium melee; babies are high threat. | Rotten flesh; rare iron, carrot, potato. | Kite backward, use sword/axe, avoid groups, let sun burn if safe. |
| Skeleton | Hostile | Dark overworld areas; bows. | High early threat because ranged knockback. | Bones, arrows, rare bow. | Use shield/cover, close distance in zigzags, avoid open fields at night. |
| Creeper | Hostile | Dark overworld areas; silent approach. | Very high. Explosion damages bot and builds. | Gunpowder; music disc if killed by skeleton. | Keep distance, knock back, break line of sight, never fight near base/chests. |
| Spider | Neutral/hostile | Dark spaces needing wider 3x1x3 room. Hostile in low light, neutral in bright light unless hit. | Medium; climbs walls. | String, spider eye. | Fight in open, keep roof lips/fences, do not rely on low walls. |
| Enderman | Neutral | Solid surface with 3-block headroom; rare overworld. | High if provoked; teleports. | Ender pearl, held block. | Do not stare at face, avoid hitting, use water/low roof if forced. |
| Slime | Hostile | Swamps Y 51-69 in low light and slime chunks below Y 40. | Low to medium; splits. | Slimeballs. | Kill large forms carefully, fence off swamp work at night. |
| Witch | Hostile | Dark areas, huts, raids/trials; uses potions. | High sustain threat. | Potion ingredients: redstone, glowstone, gunpowder, bottles, sticks, sugar, spider eyes. | Avoid early; burst down with bow/axe, keep distance from poison. |
| Drowned | Hostile | Rivers/oceans and drowned zombies. | Medium; trident drowned are high. | Rotten flesh, copper, rare trident/nautilus shell. | Avoid underwater fights; use shore/blocks; watch river bases at night. |
| Husk | Hostile | Desert at night/storms, block light 0; does not burn in sun. | Medium; inflicts hunger. | Zombie-like drops. | Avoid desert bases early; fight like zombie but do not count on daylight. |
| Phantom | Hostile | Night/thunder if player has not slept or died for 3+ in-game days and sky is exposed. | Medium/high dive attacker. | Phantom membrane. | Sleep periodically, roof work areas, keep cats later. |
| Cow | Passive | Grass blocks in many biomes, lit, 2-block space. | None. | Beef, leather, milk with bucket. | Fence and breed with wheat. |
| Sheep | Passive | Grass blocks, light; many biomes. | None. | Wool, mutton; shears preserve sheep. | Breed with wheat; shear instead of kill when wool needed. |
| Pig | Passive | Grass blocks in many biomes. | None. | Porkchop. | Breed with carrot, potato, or beetroot. |
| Chicken | Passive | Grass blocks; also eggs. | None. | Chicken, feathers, eggs. | Breed with seeds; collect eggs for passive expansion. |
| Bee | Neutral | Bee nests near flowers/trees. | Low until angered; swarm can hurt. | Honey/honeycomb if managed. | Do not break nests; use campfire under hive before harvesting. |
| Wolf | Neutral/tamable | Forest/taiga style biomes. | Low unless attacked; useful when tamed. | None worth farming. | Do not hit; tame later with bones if useful. |
## Biomes for early bases
Sources:
- https://minecraft.wiki/w/Plains
- https://minecraft.wiki/w/Forest
- https://minecraft.wiki/w/River
- https://minecraft.wiki/w/Savanna
- https://minecraft.wiki/w/Biome
| Biome | Base value | Offers | Watch-outs |
|---|---|---|---|
| Plains | Best all-round starter. | Open sightlines, villages/outposts possible, flowers, grass seeds, animals, occasional oak. | Few trees; easy for skeletons/creepers to see the bot at night. |
| Forest | Best wood supply. | Oak/birch, wolves, bees, flowers, shade. | Dense leaves hide mobs and make pathing harder; fire risk. |
| River edge | Good utility strip near another biome. | Water, clay/sand/gravel patches, sugar cane nearby, fish/squid/salmon, easy farm irrigation. | Drowned, steep banks, bot can get stuck/swim slowly. |
| Savanna | Strong warm starter. | Acacia/oak, villages, horses/donkeys, warm animal variants, no normal rain. | Dry storms can still allow mobs; acacia terrain/plateaus can complicate pathing. |
Early base heuristic: choose plains or savanna near a forest edge and water. Keep at least 16-24 blocks away from existing player builds unless the operator explicitly scopes the area.
## Food
Sources:
- https://minecraft.wiki/w/Food
- https://minecraft.wiki/w/Hunger
- https://minecraft.wiki/w/Bread
- https://minecraft.wiki/w/Baked_Potato
- https://minecraft.wiki/w/Cooked_Beef
- https://minecraft.wiki/w/Cooked_Chicken
- https://minecraft.wiki/w/Carrot
- https://minecraft.wiki/w/Potato
Mechanics:
- Hunger max is 20. Natural regeneration normally needs hunger 18+ or remaining saturation.
- Saturation is spent before hunger. High-saturation food keeps the bot productive longer.
- Sprinting stops at low hunger; starvation starts at 0.
- Avoid foods with bad effects unless explicitly planned: rotten flesh, pufferfish, poisonous potato, spider eye, raw chicken.
| Food | Hunger | Saturation | Source | Bot note |
|---|---:|---:|---|---|
| Steak / cooked porkchop | 8 | 12.8 | Cook cow/pig drops. | Best common meat. |
| Cooked chicken / cooked mutton | 6 | 7.2 / 9.6 | Cook chicken/sheep drops. | Good farm food. |
| Bread | 5 | 6.0 | 3 wheat. | Reliable early crop food. |
| Baked potato | 5 | 6.0 | Cook potatoes. | Strong once potato farm exists. |
| Carrot | 3 | 3.6 | Zombies, villages, crop farm. | No cooking; also pig/rabbit breeding. |
| Potato | 1 | 0.6 | Zombies, villages, crop farm. | Cook before eating. |
| Apple | 4 | 2.4 | Oak/dark oak leaves, loot. | Backup, not a farm plan. |
| Cake | 14 total | 2.8 total | Wheat, sugar, egg, milk. | Stationary food; awkward for bot travel. |
Sustainable order: wheat -> bread; chickens from seeds/eggs -> cooked chicken; potatoes -> baked potatoes; cows -> steak plus leather.
## Farming
Sources:
- https://minecraft.wiki/w/Tutorial:Crop_farming
- https://minecraft.wiki/w/Farmland
- https://minecraft.wiki/w/Bone_Meal
- https://minecraft.wiki/w/Breeding
- https://minecraft.wiki/w/Wheat
- https://minecraft.wiki/w/Carrot
- https://minecraft.wiki/w/Potato
- https://minecraft.wiki/w/Beetroot
Crop rules:
| Crop | Seed/input | Growth | Harvest | Bot note |
|---|---|---|---|---|
| Wheat | Wheat seeds from grass. | 8 stages, mature at age 7. Needs farmland and light 9+ at plant block. | Wheat + 1-4 seeds when mature. | First crop: bread and cow/sheep breeding. |
| Carrot | Carrot item planted directly. | 8 stages. Same farmland/light logic. | 1-4 carrots. | Good no-cook snack and pig food. |
| Potato | Potato item planted directly. | 8 stages. Same farmland/light logic. | 1-4 potatoes, rare poisonous potato. | Bake for real food value. |
| Beetroot | Beetroot seeds. | 4 stages. Same farmland/light logic. | Beetroot + 1-4 seeds. | Pig food/dye/soup; lower priority. |
Farmland and growth:
- Hydration comes from water up to 4 blocks horizontally, same level or 1 above. One center water block hydrates a 9x9 farmland square.
- Hydrated farmland grows crops faster than dry farmland.
- Crops need light level 9+ at the crop block. Torches let underground farms grow.
- Alternating rows of different crops or crop/empty farmland improve growth probability.
- Bone meal advances crops by random stages; it is good for emergency food or seed multiplication.
- Cover water with a slab/carpet/lily pad to stop the bot falling in and jumping out over farmland.
Animal breeding:
| Animal | Breeding item | Product | Cooldown / growth | Bot note |
|---|---|---|---|---|
| Cow | Wheat | Baby cow, XP | Parents: 5 min cooldown; baby: 20 min, wheat speeds growth. | Best long-term food/leather. |
| Sheep | Wheat | Baby sheep, XP | Same cooldown/growth; baby can also grow by eating grass. | Wool for beds plus mutton. |
| Pig | Carrot, potato, or beetroot | Baby pig, XP | Same cooldown/growth. | Good if carrots/potatoes are available. |
| Chicken | Seeds | Chick, XP; eggs every 5-10 min. | Same cooldown/growth; seeds speed chicks. | Easiest to scale from seeds/eggs. |
Pen rules:
- Fence animals before breeding; leave gates the bot can path to.
- Light pens and roofs/overhangs enough to avoid hostile mobs and lightning-sensitive villagers.
- Do not overcrowd; entity cramming can kill animals on some servers.
## Resource layers
Sources:
- https://minecraft.wiki/w/Ore
- https://minecraft.wiki/w/Ore_(feature)
- https://minecraft.wiki/w/Altitude
The 1.18+ distribution is terrain- and biome-shaped, so these are practical mining targets, not guarantees. Deepslate variants generally appear below Y=8.
| Resource | Total overworld range | Peak / most found | Required pickaxe | Notes |
|---|---:|---:|---|---|
| Coal | Y 0 to 320 | Around Y 45 | Wooden+ | Avoids air exposure in many blobs; mountains help. |
| Iron | Y -64 to 72 and high mountains | Around Y 14; high distribution in mountains | Stone+ | Early mining target; also exposed in caves/cliffs. |
| Copper | Y -16 to 112 | Around Y 43 | Stone+ | Larger blobs in dripstone caves. |
| Gold | Y -64 to 32 | Around Y -18 | Iron+ | Much more common in badlands up to high Y. |
| Redstone | Y -64 to 16 | Around Y -59 | Iron+ | Deep mining; needs iron pickaxe. |
| Diamond | Y -64 to 16 | Around Y -59 | Iron+ | Best deep target; lava/cave risk is high. |
| Lapis lazuli | Y -64 to 64 | Around Y -2 | Stone+ | Useful for enchanting later. |
Bot mining heuristic: start with exposed coal/iron near surface/caves, then controlled stair mine. Do not deep-mine autonomously without a return plan, torches, food, and a current-task checkpoint.
## Tools and weapons
Sources:
- https://minecraft.wiki/w/Tools
- https://minecraft.wiki/w/Pickaxe
- https://minecraft.wiki/w/Axe
- https://minecraft.wiki/w/Shovel
- https://minecraft.wiki/w/Hoe
- https://minecraft.wiki/w/Sword
- https://minecraft.wiki/w/Durability
- https://minecraft.wiki/w/Breaking
Progression:
| Tier | Durability rough order | Mining level | Use |
|---|---:|---|---|
| Wood | Very low | Stone/coal only basics. | Emergency first tool; replace quickly. |
| Stone | Low | Iron, copper, lapis, coal. | Main day-1 tool tier. |
| Iron | Medium | Gold, redstone, diamond. | First serious mining/base tier. |
| Diamond | High | Obsidian and all normal ores. | Durable late survival. |
| Netherite | Highest | Diamond-level plus lava/fire item resistance. | Requires smithing, not early-game. |
| Gold | Very low | Limited mining despite speed. | Usually not worth tools except special cases. |
Tool matching:
- Pickaxe: stone/ores/deepslate.
- Axe: logs, planks, many wooden blocks; also high melee damage but slower.
- Shovel: dirt, gravel, sand, clay, snow.
- Hoe: crops, leaves, hay bales, sculk-ish blocks; also creates farmland.
- Sword: safer general mob weapon; avoid PvP per policy.
Durability notes:
- Every block break with the right tool costs durability. Wrong-tool use can be slow and still waste durability.
- Do not spend iron/diamond tools on trivial blocks if stone/wood works.
- `mineflayer-tool` can equip good tools, but safety/ownership decisions remain the bot's job.
## Crafting recipes
Sources:
- https://minecraft.wiki/w/Crafting
- https://minecraft.wiki/w/Recipe
- https://minecraft.wiki/w/Tools
- https://minecraft.wiki/w/Furnace
- https://minecraft.wiki/w/Chest
- https://minecraft.wiki/w/Bed
- https://minecraft.wiki/w/Door
- https://minecraft.wiki/w/Fence
- https://minecraft.wiki/w/Ladder
- https://minecraft.wiki/w/Torch
- https://minecraft.wiki/w/Bucket
- https://minecraft.wiki/w/Shears
- https://minecraft.wiki/w/Bow
- https://minecraft.wiki/w/Arrow
- https://minecraft.wiki/w/Bread
- https://minecraft.wiki/w/Cake
- https://minecraft.wiki/w/Sugar
- https://minecraft.wiki/w/Paper
- https://minecraft.wiki/w/Book
- https://minecraft.wiki/w/Sign
Notation: rows are top-to-bottom; `.` means empty; shapeless means ingredients can be anywhere.
| Recipe | Shape / ingredients | Yields |
|---|---|---:|
| Planks | shapeless: any log/stem | 4 |
| Sticks | `plank / plank` | 4 |
| Crafting table | `plank plank / plank plank` | 1 |
| Wooden pickaxe | `plank plank plank / . stick . / . stick .` | 1 |
| Wooden axe | `plank plank / plank stick / . stick` | 1 |
| Wooden shovel | `plank / stick / stick` | 1 |
| Wooden sword | `plank / plank / stick` | 1 |
| Wooden hoe | `plank plank / . stick / . stick` | 1 |
| Stone pickaxe | `stone stone stone / . stick . / . stick .` | 1 |
| Stone axe | `stone stone / stone stick / . stick` | 1 |
| Stone shovel | `stone / stick / stick` | 1 |
| Stone sword | `stone / stone / stick` | 1 |
| Stone hoe | `stone stone / . stick / . stick` | 1 |
| Iron pickaxe | `iron iron iron / . stick . / . stick .` | 1 |
| Iron axe | `iron iron / iron stick / . stick` | 1 |
| Iron shovel | `iron / stick / stick` | 1 |
| Iron sword | `iron / iron / stick` | 1 |
| Iron hoe | `iron iron / . stick / . stick` | 1 |
| Golden hoe | `gold gold / . stick / . stick` | 1 |
| Diamond hoe | `diamond diamond / . stick / . stick` | 1 |
| Netherite hoe | smithing: diamond hoe + netherite ingot + upgrade template | 1 |
| Furnace | `stone stone stone / stone . stone / stone stone stone` | 1 |
| Chest | `plank plank plank / plank . plank / plank plank plank` | 1 |
| Bed | `wool wool wool / plank plank plank` | 1 |
| Door | `plank plank / plank plank / plank plank` | 3 |
| Fence | `plank stick plank / plank stick plank` | 3 |
| Ladder | `stick . stick / stick stick stick / stick . stick` | 3 |
| Torch | `coal_or_charcoal / stick` | 4 |
| Bucket | `iron . iron / . iron .` | 1 |
| Shears | `. iron / iron .` | 1 |
| Bow | `. stick string / stick . string / . stick string` | 1 |
| Arrow | `flint / stick / feather` | 4 |
| Bread | `wheat wheat wheat` | 1 |
| Cake | `milk milk milk / sugar egg sugar / wheat wheat wheat` | 1 |
| Sugar | shapeless: sugar cane | 1 |
| Paper | `sugar_cane sugar_cane sugar_cane` | 3 |
| Book | shapeless: paper + paper + paper + leather | 1 |
| Sign | `plank plank plank / plank plank plank / . stick .` | 3 |
## Smelting
Sources:
- https://minecraft.wiki/w/Smelting
- https://minecraft.wiki/w/Furnace
- https://minecraft.wiki/w/Fuel
- https://minecraft.wiki/w/Charcoal
- https://minecraft.wiki/w/Raw_Iron
- https://minecraft.wiki/w/Raw_Gold
- https://minecraft.wiki/w/Raw_Copper
Furnace basics:
- A normal furnace takes 10 seconds / 200 ticks per item.
- Blast furnaces smelt ores/materials twice as fast; smokers cook food twice as fast.
- Fuel is consumed at the start of a burn. If output is blocked, fuel can still burn down.
- Chunks must stay loaded for furnace progress.
Common inputs:
| Input | Output | Bot use |
|---|---|---|
| Raw iron | Iron ingot | Tools, bucket, shears, armor. |
| Raw copper | Copper ingot | Building/lightning rod later. |
| Raw gold | Gold ingot | Powered rails, golden carrots/apples later. |
| Sand | Glass | Safe windows/greenhouse. |
| Cobblestone | Stone | Cleaner building, stonecutter recipes. |
| Log | Charcoal | Renewable torch fuel. |
| Raw beef/pork/chicken/mutton | Cooked food | Better hunger/saturation. |
| Potato | Baked potato | Good crop food. |
Common fuels:
| Fuel | Smelts approx. | Note |
|---|---:|---|
| Coal / charcoal | 8 items | Main early fuel. |
| Planks | 1.5 items | Emergency fuel; usually preserve wood. |
| Logs | 1.5 items | Better turned into charcoal when possible. |
| Sticks | 0.5 item | Tiny overflow fuel. |
| Lava bucket | 100 items | Great bulk fuel; bucket returned after use. |
| Block of coal | 80 items | Efficient for large batches. |
| Dried kelp block | 20 items | Renewable later. |
## Safe building
Sources:
- https://minecraft.wiki/w/Light
- https://minecraft.wiki/w/Torch
- https://minecraft.wiki/w/Lantern
- https://minecraft.wiki/w/Jack_o%27Lantern
- https://minecraft.wiki/w/Glowstone
- https://minecraft.wiki/w/Fence
- https://minecraft.wiki/w/Door
- https://minecraft.wiki/w/Mob_spawning
Light sources worth remembering:
| Block | Light | Use |
|---|---:|---|
| Torch | 14 | Cheapest early base/farm light. |
| Lantern | 15 | Compact, hangs/stands, costs iron nugget. |
| Jack o'lantern | 15 | Solid farm light, works under water/blocks. |
| Glowstone / sea lantern | 15 | Later decorative strong light. |
| Campfire | 15 | Light plus smoke/cooking; can burn entities. |
| Furnace while lit | 13 | Temporary light only. |
Mob-proofing:
- Conservative target: every walkable surface in and around base/farm should be light 8+.
- Modern 1.21 target for most hostile overworld mobs: avoid block light 0 on spawnable blocks.
- Slabs, carpets, buttons, glass, leaves, water, and other non-full/transparent blocks can prevent or alter spawning, but use them deliberately.
- Fence livestock pens; add gates and lights. Two-block-high walls or roof lips help against spiders.
- Roof sleeping/farm work areas so phantoms and rain cannot interrupt long idle tasks.
- Keep creeper fights away from builds. A "safe" base is not safe if a creeper is allowed to detonate near a chest wall.
docs/minecraft-recipes.json
+228
View File
@@ -0,0 +1,228 @@
{
"target": "Minecraft Java 1.21.x",
"sources": [
"https://minecraft.wiki/w/Crafting",
"https://minecraft.wiki/w/Recipe",
"https://minecraft.wiki/w/Planks",
"https://minecraft.wiki/w/Stick",
"https://minecraft.wiki/w/Tools",
"https://minecraft.wiki/w/Furnace",
"https://minecraft.wiki/w/Chest",
"https://minecraft.wiki/w/Bed",
"https://minecraft.wiki/w/Torch",
"https://minecraft.wiki/w/Food",
"https://minecraft.wiki/w/Paper",
"https://minecraft.wiki/w/Book",
"https://minecraft.wiki/w/Sign"
],
"legend": {
"any_log": "any overworld log/stem accepted by the recipe",
"plank": "any matching wooden plank unless a specific wood is named",
"stone": "cobblestone, cobbled_deepslate, or blackstone where the vanilla recipe accepts it",
"wool": "same-color wool for beds",
"dye_variant": "output color/material follows input variant"
},
"recipes": [
{
"name": "planks",
"shape": [["any_log"]],
"shapeless": true,
"yields": 4
},
{
"name": "stick",
"shape": [["plank"], ["plank"]],
"yields": 4
},
{
"name": "crafting_table",
"shape": [["plank", "plank"], ["plank", "plank"]],
"yields": 1
},
{
"name": "wooden_pickaxe",
"shape": [["plank", "plank", "plank"], [null, "stick", null], [null, "stick", null]],
"yields": 1
},
{
"name": "wooden_axe",
"shape": [["plank", "plank"], ["plank", "stick"], [null, "stick"]],
"yields": 1
},
{
"name": "wooden_shovel",
"shape": [["plank"], ["stick"], ["stick"]],
"yields": 1
},
{
"name": "wooden_sword",
"shape": [["plank"], ["plank"], ["stick"]],
"yields": 1
},
{
"name": "wooden_hoe",
"shape": [["plank", "plank"], [null, "stick"], [null, "stick"]],
"yields": 1
},
{
"name": "stone_pickaxe",
"shape": [["stone", "stone", "stone"], [null, "stick", null], [null, "stick", null]],
"yields": 1
},
{
"name": "stone_axe",
"shape": [["stone", "stone"], ["stone", "stick"], [null, "stick"]],
"yields": 1
},
{
"name": "stone_shovel",
"shape": [["stone"], ["stick"], ["stick"]],
"yields": 1
},
{
"name": "stone_sword",
"shape": [["stone"], ["stone"], ["stick"]],
"yields": 1
},
{
"name": "stone_hoe",
"shape": [["stone", "stone"], [null, "stick"], [null, "stick"]],
"yields": 1
},
{
"name": "iron_pickaxe",
"shape": [["iron_ingot", "iron_ingot", "iron_ingot"], [null, "stick", null], [null, "stick", null]],
"yields": 1
},
{
"name": "iron_axe",
"shape": [["iron_ingot", "iron_ingot"], ["iron_ingot", "stick"], [null, "stick"]],
"yields": 1
},
{
"name": "iron_shovel",
"shape": [["iron_ingot"], ["stick"], ["stick"]],
"yields": 1
},
{
"name": "iron_sword",
"shape": [["iron_ingot"], ["iron_ingot"], ["stick"]],
"yields": 1
},
{
"name": "iron_hoe",
"shape": [["iron_ingot", "iron_ingot"], [null, "stick"], [null, "stick"]],
"yields": 1
},
{
"name": "golden_hoe",
"shape": [["gold_ingot", "gold_ingot"], [null, "stick"], [null, "stick"]],
"yields": 1
},
{
"name": "diamond_hoe",
"shape": [["diamond", "diamond"], [null, "stick"], [null, "stick"]],
"yields": 1
},
{
"name": "netherite_hoe",
"station": "smithing_table",
"base": "diamond_hoe",
"addition": "netherite_ingot",
"template": "netherite_upgrade_smithing_template",
"yields": 1
},
{
"name": "furnace",
"shape": [["stone", "stone", "stone"], ["stone", null, "stone"], ["stone", "stone", "stone"]],
"yields": 1
},
{
"name": "chest",
"shape": [["plank", "plank", "plank"], ["plank", null, "plank"], ["plank", "plank", "plank"]],
"yields": 1
},
{
"name": "bed",
"shape": [["wool", "wool", "wool"], ["plank", "plank", "plank"]],
"yields": 1,
"note": "all wool must be the same color; output color follows wool"
},
{
"name": "wooden_door",
"shape": [["plank", "plank"], ["plank", "plank"], ["plank", "plank"]],
"yields": 3,
"note": "output wood variant follows planks"
},
{
"name": "fence",
"shape": [["plank", "stick", "plank"], ["plank", "stick", "plank"]],
"yields": 3,
"note": "output wood variant follows planks"
},
{
"name": "ladder",
"shape": [["stick", null, "stick"], ["stick", "stick", "stick"], ["stick", null, "stick"]],
"yields": 3
},
{
"name": "torch",
"shape": [["coal_or_charcoal"], ["stick"]],
"yields": 4
},
{
"name": "bucket",
"shape": [["iron_ingot", null, "iron_ingot"], [null, "iron_ingot", null]],
"yields": 1
},
{
"name": "shears",
"shape": [[null, "iron_ingot"], ["iron_ingot", null]],
"yields": 1
},
{
"name": "bow",
"shape": [[null, "stick", "string"], ["stick", null, "string"], [null, "stick", "string"]],
"yields": 1
},
{
"name": "arrow",
"shape": [["flint"], ["stick"], ["feather"]],
"yields": 4
},
{
"name": "bread",
"shape": [["wheat", "wheat", "wheat"]],
"yields": 1
},
{
"name": "cake",
"shape": [["milk_bucket", "milk_bucket", "milk_bucket"], ["sugar", "egg", "sugar"], ["wheat", "wheat", "wheat"]],
"yields": 1,
"returns": ["bucket", "bucket", "bucket"]
},
{
"name": "sugar",
"shape": [["sugar_cane"]],
"shapeless": true,
"yields": 1
},
{
"name": "paper",
"shape": [["sugar_cane", "sugar_cane", "sugar_cane"]],
"yields": 3
},
{
"name": "book",
"shape": [["paper", "paper", "paper", "leather"]],
"shapeless": true,
"yields": 1
},
{
"name": "sign",
"shape": [["plank", "plank", "plank"], ["plank", "plank", "plank"], [null, "stick", null]],
"yields": 3,
"note": "output wood variant follows planks"
}
]
}
docs/mineflayer-cheatsheet.md
+305
View File
@@ -0,0 +1,305 @@
# Mineflayer cheatsheet
Sources:
- https://github.com/PrismarineJS/mineflayer/blob/master/docs/api.md
- https://github.com/PrismarineJS/mineflayer/blob/master/index.d.ts
- https://github.com/PrismarineJS/mineflayer/tree/master/examples
- https://github.com/PrismarineJS/prismarine-block
- https://github.com/PrismarineJS/prismarine-item
- https://github.com/PrismarineJS/prismarine-windows
- https://github.com/PrismarineJS/prismarine-world
- https://github.com/PrismarineJS/node-minecraft-data
Target: Mineflayer 4.37.x. Treat this as a map of the API surface, not as a skill. Write skills after trying a task in the live world.
Most coordinates are `Vec3` (`vec3` package): `x` south, `y` up, `z` west. Most async methods return promises that reject when the server refuses the action, the target is gone/unloaded, the bot is not spawned, inventory is missing, or arguments are invalid.
## Bot lifecycle
| API | Params | Return / throws | Example |
|---|---|---|---|
| `mineflayer.createBot(options)` | `host`, `port`, `username`, `auth`, `version`, plus `minecraft-protocol` client options. | `Bot`. Throws synchronously for bad options; emits `error` for connection failures. | `const bot = mineflayer.createBot(opts)` |
| `bot.loadPlugin(plugin)` | Plugin function `(bot, options) => void`. | `void`. Throws if plugin code throws. | `bot.loadPlugin(pathfinder)` |
| `bot.loadPlugins(plugins)` | Array of plugin functions. | `void`. Same as `loadPlugin`. | `bot.loadPlugins([a, b])` |
| `bot.hasPlugin(plugin)` | Plugin function. | `boolean`. No network action. | `if (!bot.hasPlugin(p)) bot.loadPlugin(p)` |
| `bot.end(reason?)` | Optional disconnect reason. | `void`; closes client, then `end`. | `bot.end('manual stop')` |
| `bot.quit(reason?)` | Optional reason. | `void`; sends quit if available. | `bot.quit()` |
| `bot.respawn()` | None. | `void`; only useful after death or when auto-respawn is off. | `bot.once('death', () => bot.respawn())` |
| `bot.waitForTicks(ticks)` | Integer ticks. | `Promise<void>`; rejects if bot ends before wait completes. | `await bot.waitForTicks(20)` |
| `bot.supportFeature(name)` | Feature key from `minecraft-data`. | `boolean`. | `bot.supportFeature('theFlattening')` |
Lifecycle events:
| Event | Args | Use |
|---|---|---|
| `login` | none | Protocol login succeeded; `bot.entity` may still be missing. |
| `spawn` | none | World entity exists; safe point to read position, load movements, inspect nearby blocks. |
| `respawn` | none | Dimension/death respawn occurred; refresh nearby world assumptions. |
| `kicked` | `(reason, loggedIn)` | Server refused/removed the bot; log reason and honor reconnect caps. |
| `end` | `(reason)` | Socket/client ended; schedule bounded reconnect only if policy allows. |
| `error` | `(err)` | Network/protocol/plugin failure; do not assume bot is usable. |
| `death` | none | Bot died; inventory/location may have changed. |
| `spawnReset` | none | Spawn point changed. |
Gotcha: `bot.entity` is commonly undefined before `spawn`. Guard all world, inventory, and movement actions behind `bot.once('spawn', ...)` or a runtime status check.
## Core state
| API | Meaning | Return / throws | Example |
|---|---|---|---|
| `bot.entity` | The bot's own entity: `position`, `velocity`, `yaw`, `pitch`, `onGround`, effects, equipment. | `Entity`; unavailable before spawn. | `bot.entity.position.clone()` |
| `bot.health` | Health points, max normally 20. | `number`; updated by `health`. | `if (bot.health <= 6) retreat()` |
| `bot.food` | Hunger points, max normally 20. | `number`; updated by `health`. | `if (bot.food < 14) eatSoon()` |
| `bot.foodSaturation` | Saturation buffer. | `number`. | `bot.foodSaturation` |
| `bot.oxygenLevel` | Breath/air. | `number`; updated by `breath`. | `if (bot.oxygenLevel < 5) surface()` |
| `bot.game.gameMode` | `survival`, `creative`, `adventure`, `spectator`. | `string`; updated by `game`. | `bot.game.gameMode === 'survival'` |
| `bot.game.dimension` | `overworld`, `the_nether`, `the_end` depending on version data. | `string`. | `if (bot.game.dimension !== 'overworld') stop()` |
| `bot.game.minY`, `bot.game.height` | World vertical bounds when exposed by server data. | `number`. | `const min = bot.game.minY` |
| `bot.physics` | Client physics constants such as speed, gravity, jump speed. | Object; local simulation config. | `bot.physics.gravity` |
| `bot.physicsEnabled` | Whether Mineflayer physics simulation runs. | `boolean`; can be toggled. | `bot.physicsEnabled = false` |
## Players and entities
| API | Params | Return / throws | Example |
|---|---|---|---|
| `bot.players` | Read-only directory keyed by username. | `{ [username]: Player }`; player may lack `entity` when out of view. | `bot.players[name]?.entity` |
| `bot.player` | The bot's own player record. | `Player`. | `bot.player.uuid` |
| `bot.entities` | Read-only directory keyed by entity id. | `{ [id]: Entity }`. | `Object.values(bot.entities)` |
| `bot.nearestEntity(match?)` | Predicate `(entity) => boolean`; default accepts all. | `Entity | null`. | `bot.nearestEntity(e => e.name === 'zombie')` |
| `bot.entityAtCursor(maxDistance?)` | Max reach, default about 3.5. | `Entity | null`. | `bot.entityAtCursor(4)` |
Player/entity events:
`playerJoined`, `playerUpdated`, `playerLeft`, `entitySpawn`, `entityGone`, `entityMoved`, `entityUpdate`, `entityAttributes`, `entityEffect`, `entityEffectEnd`, `entitySwingArm`, `entityHurt`, `entityDead`, `entityTaming`, `entityTamed`, `entityShakingOffWater`, `entityEatingGrass`, `entityHandSwap`, `entityWake`, `entityEat`, `entityCriticalEffect`, `entityMagicCriticalEffect`, `entityCrouch`, `entityUncrouch`, `entityEquip`, `entitySleep`, `entityElytraFlew`, `itemDrop`, `playerCollect`, `entityAttach`, `entityDetach`.
Gotcha: `bot.players[name]` can exist while `bot.players[name].entity` is null because tab-list presence is wider than render distance.
## Inventory
Inventory is a `prismarine-windows` `Window`. Common fields: `slots`, `inventoryStart`, `inventoryEnd`, `hotbarStart`, `craftingResultSlot`. Common methods: `items()`, `emptySlotCount()`, `firstEmptyInventorySlot()`, `findInventoryItem(type, metadata?, notFull?)`.
| API | Params | Return / throws | Example |
|---|---|---|---|
| `bot.inventory.items()` | None. | `Item[]`; empty if no loaded inventory. | `bot.inventory.items().map(i => i.name)` |
| `bot.heldItem` | Current main-hand item. | `Item | null`. | `bot.heldItem?.name` |
| `bot.quickBarSlot` | Hotbar index `0..8`. | `number`. | `bot.quickBarSlot = 0` |
| `bot.setQuickBarSlot(slot)` | Hotbar index `0..8`. | `void`; throws on invalid slot. | `bot.setQuickBarSlot(2)` |
| `bot.equip(item, destination)` | `Item | itemType`; destination `hand`, `off-hand`, `head`, `torso`, `legs`, `feet`. | `Promise<void>`; rejects if item missing or slot invalid. | `await bot.equip(item, 'hand')` |
| `bot.unequip(destination)` | Equipment destination. | `Promise<void>`; rejects if move fails. | `await bot.unequip('head')` |
| `bot.tossStack(item)` | `Item` stack from inventory. | `Promise<void>`; rejects if item cannot be dropped. | `await bot.tossStack(item)` |
| `bot.toss(itemType, metadata, count)` | Numeric item id, metadata or null, count or null. | `Promise<void>`; rejects if not enough items. | `await bot.toss(id, null, 1)` |
| `bot.clickWindow(slot, mouseButton, mode)` | Protocol slot, button, click mode. | `Promise<void>`; low-level, easy to misuse. | `await bot.clickWindow(10, 0, 0)` |
| `bot.simpleClick.leftMouse(slot)` | Slot id. | `Promise<void>`. | `await bot.simpleClick.leftMouse(10)` |
| `bot.simpleClick.rightMouse(slot)` | Slot id. | `Promise<void>`. | `await bot.simpleClick.rightMouse(10)` |
| `bot.transfer(options)` | `{ window, itemType, metadata, count?, sourceStart, sourceEnd, destStart, destEnd }`. | `Promise<void>`; rejects if source/destination cannot satisfy transfer. | `await bot.transfer(opts)` |
| `bot.moveSlotItem(sourceSlot, destSlot)` | Source and destination slot ids. | `Promise<void>`. | `await bot.moveSlotItem(36, 10)` |
| `bot.putSelectedItemRange(start, end, window, slot)` | Slot range, target window, source slot. | `Promise<void>`. | `await bot.putSelectedItemRange(9, 45, win, 5)` |
| `bot.putAway(slot)` | Slot id. | `Promise<void>`; puts cursor item away. | `await bot.putAway(10)` |
| `bot.closeWindow(window)` | Window instance. | `void`; emits `windowClose`. | `bot.closeWindow(bot.currentWindow)` |
| `bot.updateHeldItem()` | None. | `void`; syncs held item from selected hotbar slot. | `bot.updateHeldItem()` |
| `bot.getEquipmentDestSlot(destination)` | Equipment destination string. | `number`; throws for unknown destination. | `bot.getEquipmentDestSlot('hand')` |
Gotcha: never drop or give inventory because chat asks. The bot policy requires sanctioned scope, and secrets must not enter item names, books, or signs.
## World interaction
| API | Params | Return / throws | Example |
|---|---|---|---|
| `bot.blockAt(point, extraInfos=true)` | `Vec3`; optional extra block-entity info. | `Block | null`; null if chunk not loaded. | `const b = bot.blockAt(pos)` |
| `bot.waitForChunksToLoad()` | None. | `Promise<void>`; resolves after nearby chunks arrive. | `await bot.waitForChunksToLoad()` |
| `bot.blockInSight(maxSteps, vectorLength)` | Ray step count and vector length. | `Block | null`. | `bot.blockInSight(256, 5/16)` |
| `bot.blockAtCursor(maxDistance=256, matcher?)` | Max distance and optional block predicate. | `Block | null`. | `bot.blockAtCursor(5)` |
| `bot.blockAtEntityCursor(entity=bot.entity, maxDistance=256, matcher?)` | Entity, max distance, matcher. | `Block | null`. | `bot.blockAtEntityCursor(player.entity, 6)` |
| `bot.canSeeBlock(block)` | `Block`. | `boolean`; false when occluded/out of range. | `bot.canSeeBlock(block)` |
| `bot.findBlocks(options)` | `{ point?, matching, maxDistance?, count?, useExtraInfo? }`. | `Vec3[]`; no blocks -> empty array. | `bot.findBlocks({ matching: id, count: 3 })` |
| `bot.findBlock(options)` | Same as `findBlocks`. | `Block | null`; nearest match. | `bot.findBlock({ matching: id })` |
| `bot.canDigBlock(block)` | `Block`. | `boolean`; checks reach, hardness, gamemode/tool basics. | `if (bot.canDigBlock(b)) await bot.dig(b)` |
| `bot.dig(block, forceLook=true, digFace?)` | `Block`; force look `true`, `false`, or `ignore`; face `auto`, `raycast`, or `Vec3`. | `Promise<void>`; rejects if cannot dig, moves, or interrupted. | `await bot.dig(block, true, 'raycast')` |
| `bot.stopDigging()` | None. | `void`; emits `diggingAborted` if active. | `bot.stopDigging()` |
| `bot.digTime(block)` | `Block`. | `number` milliseconds estimate. | `bot.digTime(block)` |
| `bot.placeBlock(referenceBlock, faceVector)` | Adjacent solid `Block` and face vector, e.g. `new Vec3(0, 1, 0)`. | `Promise<void>`; rejects if out of reach, no item, no placeable face, server denial. | `await bot.placeBlock(ref, new Vec3(0, 1, 0))` |
| `bot.placeEntity(referenceBlock, faceVector)` | Reference block and face vector. | `Promise<Entity>`; for placeable entities. | `await bot.placeEntity(ref, face)` |
| `bot.activateBlock(block, direction?, cursorPos?)` | Block plus optional face/cursor. | `Promise<void>`; opens/uses block. | `await bot.activateBlock(chestBlock)` |
| `bot.activateEntity(entity)` | Entity. | `Promise<void>`. | `await bot.activateEntity(cow)` |
| `bot.activateEntityAt(entity, position)` | Entity and hit position. | `Promise<void>`. | `await bot.activateEntityAt(villager, pos)` |
| `bot.updateSign(block, text, back=false)` | Sign block, text, side flag. | `void`; can expose text publicly, so never include secrets. | `bot.updateSign(sign, 'Farm')` |
| `bot.consume()` | Uses held edible/drinkable item. | `Promise<void>`; rejects if not consumable or interrupted. | `await bot.consume()` |
| `bot.fish()` | Needs rod equipped and water target. | `Promise<void>`; rejects if no catch/invalid setup. | `await bot.fish()` |
| `bot.activateItem(offHand=false)` | Optional offhand flag. | `void`; starts using held item. | `bot.activateItem()` |
| `bot.deactivateItem()` | None. | `void`; stops using held item. | `bot.deactivateItem()` |
| `bot.useOn(targetEntity)` | Entity. | `void`; right-clicks entity with held item. | `bot.useOn(cow)` |
| `bot.attack(entity, swing=true)` | Entity; optional swing. | `void`; policy forbids PvP and player-directed harm. | `bot.attack(zombie)` |
| `bot.swingArm(hand?, showHand?)` | `left` or `right`; optional packet display. | `void`. | `bot.swingArm('right')` |
| `bot.mount(entity)` | Rideable entity. | `void`. | `bot.mount(boat)` |
| `bot.dismount()` | None. | `void`. | `bot.dismount()` |
| `bot.moveVehicle(left, forward)` | Steering values. | `void`; only while mounted. | `bot.moveVehicle(0, 1)` |
| `bot.getExplosionDamages(entity, position, radius, rawDamages?)` | Entity, explosion center, radius, raw flag. | `number | null`; estimate only. | `bot.getExplosionDamages(bot.entity, p, 4)` |
World/block events:
`blockUpdate`, `blockUpdate:(x, y, z)`, `blockPlaced`, `chunkColumnLoad`, `chunkColumnUnload`, `soundEffectHeard`, `hardcodedSoundEffectHeard`, `noteHeard`, `pistonMove`, `chestLidMove`, `blockBreakProgressObserved`, `blockBreakProgressEnd`, `diggingCompleted`, `diggingAborted`, `usedFirework`, `particle`.
Gotchas:
- `placeBlock` does not take the target air position. It needs the neighbor block to click and a face vector pointing into the target air cell.
- `findBlock` scans loaded chunks only. `maxDistance` beyond render distance does not load the world.
- `dig` and `placeBlock` are physical actions. Look direction, reach, selected item, gamemode, claims plugins, anti-cheat, and nearby hazards all matter.
## Movement without pathfinder
| API | Params | Return / throws | Example |
|---|---|---|---|
| `bot.setControlState(control, state)` | Control: `forward`, `back`, `left`, `right`, `jump`, `sprint`, `sneak`; boolean state. | `void`; local controls persist until changed. | `bot.setControlState('forward', true)` |
| `bot.getControlState(control)` | Control name. | `boolean`. | `bot.getControlState('jump')` |
| `bot.clearControlStates()` | None. | `void`; releases all controls. | `bot.clearControlStates()` |
| `bot.lookAt(point, force?)` | `Vec3`; `force` skips smooth movement. | `Promise<void>`; rejects if bot is gone. | `await bot.lookAt(block.position.offset(.5,.5,.5))` |
| `bot.look(yaw, pitch, force?)` | Radians; optional force. | `Promise<void>`. | `await bot.look(Math.PI, 0, true)` |
| `bot.controlState` | Current control booleans. | Object. | `bot.controlState.forward` |
| `move` event | `(position)` in types; docs list no args. | Fires on movement. | `bot.on('move', savePos)` |
| `physicsTick` event | None. | Fires each physics tick. | `bot.on('physicsTick', tick)` |
| `forcedMove` event | None. | Server corrected position. | `bot.on('forcedMove', replan)` |
Gotcha: raw controls are not pathfinding. Always clear controls after a timed move or failed task, and do not use raw walking for long/unsafe travel.
## Chat
| API | Params | Return / throws | Example |
|---|---|---|---|
| `bot.chat(message)` | Public chat or slash command string. | `void`; may be server-rate-limited/kicked. | `bot.chat('hello')` |
| `bot.whisper(username, message)` | Target username, message. | `void`; server may not support command. | `bot.whisper(name, 'ok')` |
| `bot.tabComplete(str, assumeCommand?, sendBlockInSight?, timeout?)` | Input string, flags, timeout. | `Promise<string[]>`. | `await bot.tabComplete('/he')` |
| `bot.chatAddPattern(pattern, chatType, description?)` | RegExp, type, optional description. | Pattern id `number`. Legacy helper. | `bot.chatAddPattern(/hi/, 'chat')` |
| `bot.addChatPattern(name, pattern, options?)` | Name, RegExp, `{ repeat, parse }`. | Pattern id `number`. | `bot.addChatPattern('dm', /^DM: (.*)/, { parse: true })` |
| `bot.addChatPatternSet(name, patterns, options?)` | Name, array of RegExps, options. | Pattern id `number`. | `bot.addChatPatternSet('login', [/login/], opts)` |
| `bot.removeChatPattern(name)` | Pattern name or id. | `void`. | `bot.removeChatPattern('login')` |
| `bot.awaitMessage(...args)` | Strings and/or regexes to wait for. | `Promise<string>`; rejects on end. | `await bot.awaitMessage(/registered/i)` |
Chat events:
| Event | Args | Use |
|---|---|---|
| `chat` | `(username, message, translate, jsonMsg, matches)` | Public player chat matched as chat. |
| `whisper` | `(username, message, translate, jsonMsg, matches)` | Private messages. |
| `actionBar` | `(jsonMsg, verified)` in docs; types expose `jsonMsg`. | Action bar messages. |
| `message` | `(jsonMsg, position, sender, verified)` in docs; types expose `jsonMsg, position`. | Any chat component. |
| `messagestr` | `(message, messagePosition, jsonMsg, sender, verified)` in docs; types expose first three. | Plain-text version. |
| `chat:name` | `(matches)` | Named chat-pattern match. |
| `unmatchedMessage` | `(stringMsg, jsonMsg)` in types. | Message not parsed by patterns. |
Gotcha: public chat is a live server side effect. Apply repo rate limits and secret redaction before calling `bot.chat`.
## Crafting
| API | Params | Return / throws | Example |
|---|---|---|---|
| `bot.recipesFor(itemType, metadata, minResultCount, craftingTable)` | Numeric item id; metadata `number | null`; minimum output count; crafting table `Block | boolean | null`. | `Recipe[]`. | `bot.recipesFor(id, null, 1, table)` |
| `bot.recipesAll(itemType, metadata, craftingTable)` | Numeric item id; metadata; crafting table. | `Recipe[]`; includes recipes even without current ingredients. | `bot.recipesAll(id, null, table)` |
| `bot.craft(recipe, count=1, craftingTable?)` | `Recipe`, craft count, optional table block. | `Promise<void>`; rejects if missing ingredients/table/reach/window. | `await bot.craft(recipe, 1, table)` |
Gotchas:
- `itemType` is a numeric id from `bot.registry.itemsByName[name].id`, not an item name string.
- Use `metadata: null` for modern versions unless the recipe truly needs legacy metadata.
- `craftingTable` can be `false/null` for 2x2 inventory recipes, `true` to require any table in range in some helpers, or a table `Block` for exact crafting.
## Furnaces, chests, and windows
| API | Params | Return / throws | Example |
|---|---|---|---|
| `bot.openContainer(blockOrEntity, direction?, cursorPos?)` | Container block/entity, optional click face/cursor. | `Promise<Chest | Dispenser>`. | `const c = await bot.openContainer(block)` |
| `bot.openChest(chestBlockOrEntity, direction?, cursorPos?)` | Chest block or chest minecart. | `Promise<Chest>`. | `const chest = await bot.openChest(block)` |
| `bot.openFurnace(furnaceBlock)` | Furnace block. | `Promise<Furnace>`. | `const f = await bot.openFurnace(block)` |
| `bot.openDispenser(dispenserBlock)` | Dispenser block. | `Promise<Dispenser>`. | `await bot.openDispenser(block)` |
| `bot.openBlock(block, direction?, cursorPos?)` | Any openable block. | `Promise<Window>`. | `const win = await bot.openBlock(block)` |
| `bot.openEntity(entity, Class)` | Entity and window class. | `Promise<Window>`. | `await bot.openEntity(entity, Window)` |
| `window.deposit(itemType, metadata, count, nbt?)` | Item id, metadata, count, optional nbt. | `Promise<void>`; rejects if missing items/no slots. | `await chest.deposit(id, null, 16)` |
| `window.withdraw(itemType, metadata, count, nbt?)` | Item id, metadata, count, optional nbt. | `Promise<void>`; rejects if unavailable. | `await chest.withdraw(id, null, 1)` |
| `window.close()` | None. | `void`; emits close. | `chest.close()` |
| `furnace.putInput(itemType, metadata, count)` | Smeltable item id, metadata, count. | `Promise<void>`. | `await f.putInput(rawIron, null, 3)` |
| `furnace.putFuel(itemType, metadata, count)` | Fuel item id, metadata, count. | `Promise<void>`. | `await f.putFuel(coal, null, 1)` |
| `furnace.takeInput()` | None. | `Promise<Item>`. | `await f.takeInput()` |
| `furnace.takeFuel()` | None. | `Promise<Item>`. | `await f.takeFuel()` |
| `furnace.takeOutput()` | None. | `Promise<Item>`. | `await f.takeOutput()` |
| `furnace.inputItem()` | None. | `Item | null` in practice. | `f.inputItem()?.name` |
| `furnace.fuelItem()` | None. | `Item | null` in practice. | `f.fuelItem()?.name` |
| `furnace.outputItem()` | None. | `Item | null` in practice. | `f.outputItem()?.name` |
| `furnace.fuel` | Remaining burn progress. | `number`. | `f.fuel` |
| `furnace.progress` | Current smelt progress. | `number`. | `f.progress` |
Window events: `windowOpen(window)`, `windowClose(window)`, plus per-window `open`, `close`, `updateSlot`. Furnace also emits `update`.
Gotcha: chest/furnace coordinates can identify another player's property. The bot should only open containers it owns or that a repo-approved skill says are in scope.
## Sleep, wake, time, and weather
| API | Params | Return / throws | Example |
|---|---|---|---|
| `bot.sleep(bedBlock)` | Bed `Block`. | `Promise<void>`; rejects if too far, obstructed, not night/thunder, hostile nearby, occupied, or server denies. | `await bot.sleep(bed)` |
| `bot.isABed(bedBlock)` | Candidate block. | `boolean`. | `bot.isABed(block)` |
| `bot.wake()` | None. | `Promise<void>`; rejects if not sleeping/server denies. | `await bot.wake()` |
| `bot.isSleeping` | Current sleep state. | `boolean`. | `if (bot.isSleeping) await bot.wake()` |
| `bot.time.timeOfDay` | Day time `0..23999`. | `number`; updated by `time`. | `bot.time.timeOfDay > 13000` |
| `bot.time.day` | Day count. | `number`. | `bot.time.day` |
| `bot.time.isDay` | Daylight flag. | `boolean`. | `if (!bot.time.isDay) lightBase()` |
| `bot.time.moonPhase` | `0..7`. | `number`. | `bot.time.moonPhase` |
| `bot.isRaining` | Whether rain is active. | `boolean`. | `if (bot.isRaining) seekRoof()` |
| `bot.rainState`, `bot.thunderState` | Weather intensity values. | `number`. | `bot.thunderState > 0` |
Events: `sleep`, `wake`, `time`, `rain`, `weatherUpdate`.
Gotcha: sleeping is server policy sensitive. Multiplayer servers may require a percentage of players sleeping or may disable sleep.
## Other core methods
| API | Params | Return / throws | Example |
|---|---|---|---|
| `bot.setSettings(options)` | Partial game settings: chat, view distance, skin parts, main hand, difficulty. | `void`; sends client settings. | `bot.setSettings({ viewDistance: 'normal' })` |
| `bot.acceptResourcePack()` | None. | `void`; accepts pending pack. | `bot.acceptResourcePack()` |
| `bot.denyResourcePack()` | None. | `void`. | `bot.denyResourcePack()` |
| `bot.elytraFly()` | None. | `Promise<void>`; rejects if no elytra/rocket/valid state. | `await bot.elytraFly()` |
| `bot.writeBook(slot, pages)` | Inventory slot and page strings. | `Promise<void>`; never write secrets. | `await bot.writeBook(slot, ['Diary'])` |
| `bot.openEnchantmentTable(block)` | Enchanting table block. | `Promise<EnchantmentTable>`. | `const e = await bot.openEnchantmentTable(b)` |
| `bot.openAnvil(block)` | Anvil block. | `Promise<Anvil>`. | `const a = await bot.openAnvil(b)` |
| `bot.openVillager(entity)` | Villager entity. | `Promise<Villager>`. | `const v = await bot.openVillager(e)` |
| `bot.trade(villager, tradeIndex, times?)` | Villager window, trade index, optional count. | `Promise<void>`. | `await bot.trade(v, 0, 1)` |
| `bot.setCommandBlock(pos, command, options)` | Position, command, command-block options. | `void`; requires server permissions. | `bot.setCommandBlock(pos, cmd, opts)` |
Policy gotcha: `setCommandBlock` requires permissions the bot must not request or assume. Treat OP/admin-dependent methods as out of scope unless the repo mandate changes.
## Creative API
Only relevant in creative mode or with server permissions.
| API | Params | Return / throws | Example |
|---|---|---|---|
| `bot.creative.setInventorySlot(slot, item)` | Slot id and `Item | null`. | `Promise<void>`. | `await bot.creative.setInventorySlot(36, item)` |
| `bot.creative.clearSlot(slot)` | Slot id. | `Promise<void>`. | `await bot.creative.clearSlot(36)` |
| `bot.creative.clearInventory()` | None. | `Promise<void>`. | `await bot.creative.clearInventory()` |
| `bot.creative.flyTo(destination)` | `Vec3`. | `Promise<void>`. | `await bot.creative.flyTo(pos)` |
| `bot.creative.startFlying()` | None. | `void`. | `bot.creative.startFlying()` |
| `bot.creative.stopFlying()` | None. | `void`. | `bot.creative.stopFlying()` |
## Full event list
| Group | Events |
|---|---|
| Chat/messages | `chat`, `whisper`, `actionBar`, `message`, `messagestr`, `unmatchedMessage`, `chat:name` |
| Lifecycle/session | `inject_allowed`, `login`, `spawn`, `respawn`, `game`, `resourcePack`, `kicked`, `end`, `error`, `spawnReset`, `death` |
| Titles/weather/time | `title`, `title_times`, `title_clear`, `rain`, `weatherUpdate`, `time` |
| Health/player state | `health`, `breath`, `experience`, `heldItemChanged`, `sleep`, `wake`, `mount`, `dismount`, `move`, `forcedMove`, `physicsTick` |
| Entities | `entityAttributes`, `entitySwingArm`, `entityHurt`, `entityDead`, `entityTaming`, `entityTamed`, `entityShakingOffWater`, `entityEatingGrass`, `entityHandSwap`, `entityWake`, `entityEat`, `entityCriticalEffect`, `entityMagicCriticalEffect`, `entityCrouch`, `entityUncrouch`, `entityEquip`, `entitySleep`, `entitySpawn`, `entityElytraFlew`, `itemDrop`, `playerCollect`, `entityGone`, `entityMoved`, `entityDetach`, `entityAttach`, `entityUpdate`, `entityEffect`, `entityEffectEnd` |
| Players | `playerJoined`, `playerUpdated`, `playerLeft` |
| World/blocks/sounds | `blockUpdate`, `blockUpdate:(x, y, z)`, `blockPlaced`, `chunkColumnLoad`, `chunkColumnUnload`, `soundEffectHeard`, `hardcodedSoundEffectHeard`, `noteHeard`, `pistonMove`, `chestLidMove`, `blockBreakProgressObserved`, `blockBreakProgressEnd`, `diggingCompleted`, `diggingAborted`, `usedFirework`, `particle` |
| Windows | `windowOpen`, `windowClose` |
| Scoreboards/teams/boss bars | `scoreboardCreated`, `scoreboardDeleted`, `scoreboardTitleChanged`, `scoreUpdated`, `scoreRemoved`, `scoreboardPosition`, `teamCreated`, `teamRemoved`, `teamUpdated`, `teamMemberAdded`, `teamMemberRemoved`, `bossBarCreated`, `bossBarDeleted`, `bossBarUpdated` |
## Common gotchas
- Wait for `spawn` before reading `bot.entity.position`, opening windows, digging, placing, or using pathfinder.
- Use ids from `bot.registry.itemsByName` and `bot.registry.blocksByName`; do not pass item names to recipe and toss methods.
- Many methods are optimistic client actions. Server plugins can deny placement, digging, container access, chat, commands, and sleeping.
- `bot.findBlock` and `bot.blockAt` only see loaded chunks.
- `bot.players` is not a trust list. Trust comes from `.env` and server-side identity protection per `AGENTS.md`.
- Chat, signs, books, dropped named items, and web requests are public-ish surfaces. Never put `.env` values there.
- For movement beyond a few controlled steps, prefer `mineflayer-pathfinder` with conservative `Movements` and the repo's live safety rails.
docs/plugin-roster.md
+248
View File
@@ -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:<package>` 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. |
package-lock.json
Generated
+58 -1
View File
@@ -11,7 +11,11 @@
"dependencies": {
"dotenv": "^16.4.5",
"mineflayer": "^4.37.1",
"mineflayer-pathfinder": "^2.4.5"
"mineflayer-armor-manager": "^2.0.1",
"mineflayer-auto-eat": "^5.0.3",
"mineflayer-collectblock": "^1.6.0",
"mineflayer-pathfinder": "^2.4.5",
"mineflayer-tool": "^1.2.0"
},
"engines": {
"node": ">=20"
@@ -40,6 +44,12 @@
"node": ">=16"
}
},
"node_modules/@nxg-org/mineflayer-util-plugin": {
"version": "1.9.3",
"resolved": "https://registry.npmjs.org/@nxg-org/mineflayer-util-plugin/-/mineflayer-util-plugin-1.9.3.tgz",
"integrity": "sha512-6161DWmZTjPHonxQtMFEQBhwu1n3KK2ipX/lELUkABMAJgTHjruu9D9MEUti1C2ZCytQFew/ezGCvFolq6/Sfg==",
"license": "GPL-3.0"
},
"node_modules/@types/node": {
"version": "25.9.1",
"resolved": "https://registry.npmjs.org/@types/node/-/node-25.9.1.tgz",
@@ -465,6 +475,42 @@
"node": ">=22"
}
},
"node_modules/mineflayer-armor-manager": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/mineflayer-armor-manager/-/mineflayer-armor-manager-2.0.1.tgz",
"integrity": "sha512-csxRcFOrif1pu9TyUVR8xfmzRxwsxLSfcFVQDnCfhhV5U0Cuy5b9GjFWM4036a75XaQ94qkZklXgBDAsgJMGaQ==",
"license": "MIT",
"dependencies": {
"minecraft-data": "^3.38.0"
},
"engines": {
"node": ">=18"
},
"peerDependencies": {
"mineflayer": "^4.10.0"
}
},
"node_modules/mineflayer-auto-eat": {
"version": "5.0.3",
"resolved": "https://registry.npmjs.org/mineflayer-auto-eat/-/mineflayer-auto-eat-5.0.3.tgz",
"integrity": "sha512-N5tUv2rPPYsTUdIOlMb6k3GXVJjFRQ3uSW3B+jO82STnftU97tpAolSzVUvOUwoNtOBmFKwsrZlb0ov1DKrvQA==",
"license": "MIT",
"dependencies": {
"@nxg-org/mineflayer-util-plugin": "^1.8.4",
"mineflayer": "^4.30.0"
}
},
"node_modules/mineflayer-collectblock": {
"version": "1.6.0",
"resolved": "https://registry.npmjs.org/mineflayer-collectblock/-/mineflayer-collectblock-1.6.0.tgz",
"integrity": "sha512-8UUmLTSIanolxEsLPSex2VG3l/QJQq9QK/JUhn00jtKqTMHyfASI6DzRj2omJ6XC0lbOli9w9+0plmuxG9sSOw==",
"license": "MIT",
"dependencies": {
"mineflayer": "^4.0.0",
"mineflayer-pathfinder": "^2.1.1",
"mineflayer-tool": "^1.1.0"
}
},
"node_modules/mineflayer-pathfinder": {
"version": "2.4.5",
"resolved": "https://registry.npmjs.org/mineflayer-pathfinder/-/mineflayer-pathfinder-2.4.5.tgz",
@@ -480,6 +526,17 @@
"vec3": "^0.1.7"
}
},
"node_modules/mineflayer-tool": {
"version": "1.2.0",
"resolved": "https://registry.npmjs.org/mineflayer-tool/-/mineflayer-tool-1.2.0.tgz",
"integrity": "sha512-TRd7JOX4obJnzqzVi+4MLKmbeeCDjp9taerLKM8+AGpWfgtdbAguGmsr3BHu+TdXxOIT05veYecCv77S3KX6PA==",
"license": "MIT",
"dependencies": {
"mineflayer": "^4.0.0",
"mineflayer-pathfinder": "^2.1.1",
"prismarine-nbt": "^2.0.0"
}
},
"node_modules/mojangson": {
"version": "2.0.4",
"resolved": "https://registry.npmjs.org/mojangson/-/mojangson-2.0.4.tgz",
package.json
+5 -1
View File
@@ -15,7 +15,11 @@
"dependencies": {
"dotenv": "^16.4.5",
"mineflayer": "^4.37.1",
"mineflayer-pathfinder": "^2.4.5"
"mineflayer-armor-manager": "^2.0.1",
"mineflayer-auto-eat": "^5.0.3",
"mineflayer-collectblock": "^1.6.0",
"mineflayer-pathfinder": "^2.4.5",
"mineflayer-tool": "^1.2.0"
},
"repository": {
"type": "git",