mcbot

A client-only Meteor addon for Minecraft Java 26.3: build open farms on a prepared flat foundation, harvest and replant crops, and travel to coordinates. Use it only on servers that permit automated clients. This is an early prototype; CI builds do not establish live-server or anti-cheat safety. Test attended with a dedicated bot account before leaving it running.

Install

Use Java 25, Fabric Loader 0.20.1+, and exactly three separate mod jars:

1. mcbot.
2. Meteor Client 26.3.
3. Meteor's Baritone fork, API Fabric 26.3 artifact.

Never add upstream/standalone Baritone or a second Baritone jar. Dependencies are not bundled. Verify the release's .sha256 file with sha256sum -c. For authenticated servers, use Prism Launcher; mcbot does not authenticate. The same wrapper supports headless operation on a local machine: scripts/prism-bot.sh run uses Xvfb when no display is present, after the one-time Prism login on a desktop/VNC display. See headless operation. Autostart permits up to three bounded retries per session (see below).

Quick start

Every farm is the 32×32 region of the four chunks around one shared chunk corner (X and Z divisible by 16), planted on its 30×30 inset. Stand on the corner block or a block directly beside it (within one block in X and Z) to save or build a farm. For an existing farm, save it, look at the deposit chest before deposit and the seed chest before restock, then start it:

.bot farm save field carrot
.bot farm deposit field
.bot farm restock field
.bot farm field
.bot status
.bot stop

For a new farm, prepare the foundation and supplies below, then run:

.bot preview netherwart
.bot build wart-field netherwart

Successful construction saves the profile and starts one normal farm job.

Farm requirements

All farms require a known multiplayer server, one dimension, a loaded, flat, single-crop plot, a closed inventory/container screen and an empty cursor. Singleplayer, terraces, trees, animals, crafting and terrain excavation are unsupported.

Crop argument	Planting item	Plot soil
wheat	Wheat seeds	Hydrated farmland, light 9+
carrot	Carrots	Hydrated farmland, light 9+
potato	Potatoes	Hydrated farmland, light 9+
beetroot	Beetroot seeds	Hydrated farmland, light 9+
netherwart or nether-wart	Nether wart	Soul sand; no water, light or hoe needed

Harvest an existing plot

• Every inset cell must be the crop's soil or, on hydrated farms, carpet-covered source water. Empty planting cells are allowed; other crops, damaged or dry soil and any other block are not. Keep the whole footprint loaded and unobstructed. Saving validates the plot; inventory requirements apply when starting.
• For normal farming, carry matching planting items (farm-seed-reserve, default 16) and two empty main inventory slots, or configure stocked restock/deposit chests to resolve shortages. One planting item per empty cell plus the reserve avoids extra supply trips.
• For normal farming, remove bone meal and other crops' planting items; keep all plantables out of the offhand. Harvest/replant needs no hoe. Farming never repairs soil.
• Carry separate food for carrot/potato farms and check AutoEat: planting stock is edible, and deposits move matching crop items even if you meant to keep them.
• Profiles saved by mcbot 0.3.0 or earlier are ignored with a warning and dropped by the next profile save; save those farms again.

Build an open farm

Prepare a 32×32, solid full-block, flat, fluid-free foundation with five clear air layers above it, all loaded and within world limits. The bot places only the missing pieces one block above the existing surface. It never clears blocks, replaces the foundation or repairs terrain. An existing site may contain only blocks from the same open-farm layout: planned soil/farmland, source water, white carpet, the target crop and air are the only accepted blocks, and any other block rejects the job before pathing starts. Run the same build command again to resume an interrupted build from its first missing piece; stand near the shared corner on the original foundation or an existing farm layer so the bot can identify the level. If only untilled dirt remains, keep the supply chest at the original level so the lower layer is unambiguous. Provide safe walking access between the foundation and storage. Hydrated builds need light 9+ and cannot run in the Nether.

Use one loaded double normal chest, both halves outside the region, within 16 blocks of its edge, at the original standing level or the new crop level. Look at it; otherwise the nearest eligible chest is selected. Supplies may be split between that chest and the main inventory. The remaining bill of materials is checked before the first placement; a fresh site needs the full table:

Build mode	Raw supplies	Starting inventory space
Wheat/carrot/potato/beetroot	1,008 dirt, 900 matching planting items (884 plants + 16 reserve), 16 water buckets, 16 white carpets, at least two supported hoes with ≥884 total remaining durability	8 empty slots
Nether wart	900 soul sand, 124 dirt for the ring, 916 wart (900 plants + 16 reserve)	4 empty slots

Supported hoes are stone, iron, diamond and netherite; two diamond hoes are a simple choice. A broken hoe falls back to another usable hoe or the supply chest. No pickaxe or mining supplies are needed.

From each standing spot the bot places, tills and plants every upcoming cell it can reach before walking on, one action per build-interval, aiming at the next cell while it works the current one. It visits the chest only when the inventory cannot start the next phase. A visit returns empty buckets, withdraws what the current phase needs, balanced across its materials, then what later phases need while whole stacks still fit. A last visit returns leftover build materials, never tools or planting stock.

The finished farm is verified before its profile replaces an existing one. Its supply chest becomes both deposit and restock. Failed builds leave partial placements in place and keep the previous profile unchanged. Rerun the same build command to validate and resume those placements; anything that no longer matches the layout must be corrected or cleared first.

Farming behavior and storage

Normal farming walks fixed lanes on every second crop row, edge to edge, alternating direction from the end nearest the bot. It stops just before ripe or empty cells it would otherwise pass and works everything in reach from there: each ripe crop is broken and its cell replanted on the same look, and initial gaps are planted in the same pass. It only takes crops level with or ahead of it in its lane, or in lanes it has yet to walk, so their drops land where it still walks, and it waits out vanilla's pickup delay after a nearby break. Work behind it waits for the next pass, which starts where the last one ended. Drops left after a pass, mostly scatter past the plot's far edge, are collected before waiting for growth; a persistent unreachable drop stops the job instead of being silently ignored. A crop the server keeps restoring is skipped after three attempts for that job. Harvests keep vanilla arm-swing packets, so block actions are not sent as noswing.

While a job runs, mcbot keeps the first-person camera under your control. Harvest, placement and pathing looks are applied to the server-facing rotation and the local view is restored before rendering, so you can look around freely in first person. Idle mcbot never touches the view.

farm-loop defaults to on: passes repeat back to back while anything is ripe, then the bot waits for growth. Disable it for one pass. Shortages, full storage, failed transfers, damaged/unloaded plots or unreachable work stop and deactivate the bot. Failed/interrupted jobs never auto-resume.

Farm chests must be normal chests within 64 blocks of the farm center, at crop level or one block below it. A full inventory pauses the pass for the deposit chest; the bot then starts a new pass from the nearest end. Deposits retain planting reserves and enough stock for remaining empty cells where space allows; restock aims to fill the remaining plot in one visit. Transfers use one vanilla stack click at a time and require reopened authoritative contents on both sides before withdrawn supplies are used. Unrelated items are never discarded. Avoid other inventory/pathing controllers. If another controller puts an item on the cursor, the bot stops and leaves that menu for you to resolve.

Food is a separate survival supply. When hunger reaches AutoEat's threshold and AutoEat has no usable food (offhand or hotbar), a farm with a restock chest walks there and tries to withdraw edible food before continuing. If the chest has none, the inventory cannot hold another stack, a farm without a restock chest or a toolmode job has no chests, or any other active job/idle state cannot eat, the bot makes a safety disconnect instead of starving. Only a farm restock chest is used; build supply chests are not food storage. Keep food in the hotbar; AutoEat's farming preset does not search the main inventory.

All-crop toolmode

For a server-provided tool that harvests a 3×3 square, automatically replants, and automatically sells the yield, put that tool in hotbar slot 1, then run any saved wheat, carrot, potato, beetroot or nether-wart profile with the opt-in suffix:

.bot farm wart-field toolmode

.farm wart-field toolmode is equivalent. Alternatively, enable Farming → toolmode for future farm starts. The setting defaults to off and is captured when the job starts; the suffix changes neither the profile nor the setting. Construction still hands off to a normal first pass.

• The 3×3 footprint is on the same crop Y, including all four diagonals. The plot is 100 disjoint tiles, walked on a fixed route of four straight passes that each reach three rows of tiles, alternating direction from the end nearest the bot. The bot swings at reachable tiles in every direction while walking and stops only when a tile it has not swung is about to leave reach. Intact tiles are swung whole; partial ones, regrowing or centered on irrigation, are finished with smaller swings that never cut into an intact tile.
• A pass takes the growth present when it starts. Tiles confirmed during a pass wait for the next one, so fast regrowth can neither hold the bot nor turn it back, and the next pass starts where the last one ended.
• Up to tool-swings swings (default 2) may await confirmation at once, always on separate tiles, so slow confirmations do not stall the walk. Each swing must leave every affected plot cell planted and every previously ripe cell young; client-predicted air never counts. An unconfirmed swing waits up to five seconds; a server-restored mature center gets at most three attempts. Missing replants, incomplete area harvesting or persistent unexpected scoped drops stop with TOOL_FAILED, never a fallback to planting, collection or storage trips. A one-pass job still confirms its last swings before finishing.
• There is no manual planting, pickup, seed restock or deposit. Seed reserves, chest waypoints and inventory fullness do not affect this mode. Selling is entirely the tool's responsibility; mcbot sends no sell commands and cannot verify the server's balance.
• Start with every soil cell already planted; fill gaps with normal farming first. Keep a loaded, clear one-block crop-layer margin, including diagonals, so an edge swing cannot affect anything outside the plot. For hydrated crops, carpet-covered source water inside the plot or its margin is allowed, but the water and cover must stay loaded and intact; these cells never become harvest targets. Startup errors identify the obstructed or unloaded cell, or the damaged irrigation.
• The first-slot tool stays selected, without Baritone tool or inventory swaps. Removing or breaking it, or changing its base item type, stops with TOOL_MISSING. Durability and server-updated lore/counters may change. The addon cannot identify a custom server ability from a vanilla item type, so it checks the resulting footprint instead of trusting item metadata.

farm-loop and the growth/idle timeouts still apply, as do server/dimension scope, exact reach/ray checks, survival interrupts and Stop/deactivation cleanup. A custom server tool's sale behavior cannot be validated offline.

Farm and build settings

Setting	Default	Effect
farm-seed-reserve	16	Planting items required before a pass; deposits keep at least this many.
farm-idle-timeout	30 s	Stop if the plot, drops, inventory and position stop changing for this long.
farm-loop	on	Repeat passes; off stops after one pass.
farm-growth-timeout	3,600 s	Stop if no crop becomes ripe for this long.
toolmode	off	Start farms in toolmode.
harvest-interval	1 tick	Ticks between crop breaks. A held vanilla attack breaks one crop per tick.
plant-interval	1 tick	Ticks between replants. A held vanilla use plants every 4 ticks.
tool-swings	2	Toolmode swings that may await confirmation at once (1–4).
build-interval	1 tick	Ticks between build placements, tilling and planting.

The interval and swing defaults are faster than held vanilla keys: one break and one replant per tick, and two tool swings in flight. Raise them if a server's anti-cheat objects.

Commands

Commands use Meteor's prefix (. by default). .mcbot aliases .bot; .farm aliases .bot farm. Dot-prefixed forms stay local even if Meteor's prefix changes. Names use 1–32 letters, digits, underscores or hyphens, excluding farm subcommands. Omitted crops always mean wheat. Chat completion lists saved farm names wherever an existing farm is named (farm <name>, info, deposit, restock, clear-deposit, clear-restock and remove); save accepts a new name.

.bot build <name> [crop]
.bot farm [name [toolmode]]
.bot farm save <name> [crop]
.bot farm deposit <name>
.bot farm restock <name>
.bot farm clear-deposit <name>
.bot farm clear-restock <name>
.bot farm list
.bot farm info <name>
.bot farm remove <name>
.bot preview [crop]
.bot preview clear
.bot goto <x> <y> <z>
.bot home
.bot friends add|remove <names...>
.bot friends list
.bot friends reload
.bot export [path]
.bot import <path>
.bot status
.bot stop

Bare .bot farm starts an unsaved wheat farm around the chunk corner here. .bot home arms faction-home flee for this server/dimension. Previews outline the farm and list a fresh build's bill of materials; they are not surveys or material checks. Their local outline lasts 60 seconds, works while inactive, and clears on world changes without touching pathing or blocks.

Survival and trusted players

While active, including idle, tracked non-friends trigger the default response: disconnect within threat-radius (128 by default). Detection does not need visibility or line of sight; invisible, spectator and creative players count because staff can still punish the account. It cannot detect players the server does not send. Low health also triggers safety handling. These measures do not guarantee survival.

• Flee is opt-in and requires .bot home armed for the current server and dimension. It sends /f home, then disconnects if no real teleport arrives in ten seconds. Small server corrections do not count as arrival; arming .bot home at the destination also verifies the landing. Check the server's actual destination and teleport restrictions first.
• Damage from a non-friend player always enters Fight, cancelling work. Combat uses a reversible conservative KillAura/bow preset, strict offhand totem and five-second attacker tracking grace. An intruder the aura cannot fight (spectator or creative) still triggers flee or disconnect. Carry suitable equipment and food; confirm allies are trusted. AutoEat/AutoTotem settings are leased and restored.
• A finished fight or successful flee leaves the bot idle but armed: it never resumes the interrupted job and still logs out for the next unknown player. Use .bot stop or deactivation to switch the safety watch off.
• Autostart allows up to three reconnects per client session. A safety disconnect disables immediate Meteor AutoReconnect; a normal network/server disconnect also defers to the same bounded budget. If autostart was preparing or running its job, each retry to the same verified server follows after 15 minutes for a threat or 60 seconds otherwise, and restarts that job as a fresh session. Low health, a /f home timeout, a fourth disconnect, a failed retry or another server leaves the bot offline; there is no unbounded retry loop.
• Add trusted usernames to config/mcbot/friends.txt before joining. Startup imports names after Meteor loads friends, only adding, never removing them. Meteor friends are global and name-based. Removing a friend in-game does not remove it from that file.
• While active, friend /tpa requests are auto-accepted with /tpaccept; non-friends and requests that would move the bot are ignored. Recognition uses common English server text. Disable tpa-accept if unwanted.

/f home and friend-gated /tpaccept are the only server commands. A sent command cannot be withdrawn. Stop, deactivation and world exit release jobs, input and leased settings; fight/flee never resume the interrupted farm.

Configuration, logs and development

.bot export creates an owner-only bundle of settings, friends and local mcbot configuration, not Prism credentials. Import writes a backup, then replaces those settings immediately. Profiles keep their original server/dimension scope. Bundles and logs contain coordinates; keep them private and out of Git.

Logs are in <game-dir>/logs/mcbot/mcbot.log; .bot status prints the path. Rotation keeps five 8 MiB archives. Ordinary logs show stages/results; detailed placement evidence stays in the file rather than flooding CI's console.

Run resource-bounded local validation before pushing: Java lint/build, unit/script tests and jar-boundary checks are explicitly allowed locally. The Forgejo build must also pass before merging. Real-client trials are attended work on a dedicated machine, not CI. Farm movement and pickup are covered by server-free sweep simulations with vanilla movement, reach and drop numbers; they are not live-server evidence.

• CI and runner operations
• Prism authentication and autostart
• Releases
• Agent development rules