Minestructor 1.0.0

First public release, for Minecraft 26.1.2 and NeoForge 26.1.2.95 or newer.

This changelog is also a tour of how the mod works under the hood, for anyone who wants to know what the bot is actually doing and why it does things the way it does.

Requirements

All four are declared as required client-side dependencies, so a missing one shows NeoForge's missing-mods screen instead of a crash.

Ground rules the whole mod follows

These rules are behind most of the design decisions below.

• Legit interaction only. Every block is placed by looking at a visible face of a neighbouring block, within vanilla reach, from a spot a player could stand on, and right-clicking exactly where the crosshair is. Nothing is placed through walls, nothing is spawned, and the bot never teleports.
• No snapping camera. All turning is eased and capped per tick. The camera can be kept completely still while the bot still faces every block it works on. Nothing on screen flashes or jumps.
• Never in your way. The bot waits while you have chat or an inventory open, so nothing you are typing is lost. It never touches chests or items you haven't registered. Your own Baritone and game settings (auto-jump, sprint, pause on lost focus) are put back when it stops.
• No disguise. The mod does not try to hide from anti-cheat. Baritone's x-ray-style ore finder is labelled as such in the menu.
• Per world. Settings, bases, chests, farms and projects are stored per world and per server, in config/minestructor/worlds/<world>/. Nothing carries over between saves.

Core engine

One tick loop, isolated subsystems

Every client tick runs, in order: the world-change check, the hotkeys, the self-defence system, construction, survival jobs, project mode, the container watcher, and the outlines. Each subsystem runs in its own guard, so an exception in one is logged (rate-limited) and never stops the others.

Self-defence runs before every job, so when a threat appears, all work freezes in the same tick.

Controllers and jobs

Construction, survival tasks and project mode are three controllers that never run at the same time. Each piece of work is a small state machine (start, tick, cancel, a status line for the sidebar, a final message, and a list of problems shown in chat). Bigger jobs are built by nesting smaller ones. A mining trip, for example, runs a supply trip, a crafting job, a torch placer and a deposit trip.

Interruptions

When the defence system takes over, it suspends the running controller: workers stop, open containers close, Baritone is cancelled, eating stops. When it hands control back, it increments a counter, the "epoch". Every job remembers the epoch it last saw, and a change means "I was interrupted and may be somewhere else", so the job redoes its current step: it walks back to the chest, re-queues the tunnel segment, or puts the farm task back. Project mode reuses the same mechanism for eating breaks in the middle of outdoor tasks.

Baritone use

Baritone handles long-distance walking (goals to a block, near a block, to an XZ column), running away, clearing boxes of blocks, its schematic builder for simple runs of blocks, and the ore finder. Every wait on Baritone has a timeout and a "did we actually get there" check. While Minestructor works, Baritone runs with a profile that keeps its camera calm, uses only dirt for scaffolding, avoids hostile mobs by 8 blocks, and may not break chests, furnaces, crafting tables, beds, torches or fence gates.

Placing blocks legitimately

The placement planner

For every block, the planner looks for a spot to stand on and a face to click. A candidate is accepted only if:

1. looking straight at the hit point from the eye position produces exactly the wanted block state. This is checked by running the item's own placement code in simulation, so stairs, logs, slabs, doors, trapdoors and other orientation-dependent blocks come out right;
2. a ray from the eye hits exactly that block face, so the face is truly visible;
3. the hit point is within reach.

Properties that the world corrects by itself are ignored when comparing: stair corner shapes, fence, pane and wall connections, redstone connections, leaf distance, waterlogging, and whether a door, trapdoor or gate is open (that is set afterwards with a right-click).

The click guard

Right before every click, a final check confirms that the right item is in hand and that the block will land in the intended spot (using the game's own placement context). Clicks that would open a container instead of placing are refused. Toggling doors and trapdoors releases sneak first. If the check fails, the click doesn't happen and the planner tries another way.

Settling before clicking

The bot crouches and waits until it has stopped sliding (stairs, slabs and ice carry momentum) before it clicks, and re-aims if the last check says the result would come out wrong. Two wrong results on the same block and that block is set aside, so it never loops.

Construction

Analysis

Every enabled sub-region of the selected placement is compared with the world. Each block is sorted as placed, wrong (must be broken), still to place (regular blocks, or special blocks such as doors, beds, torches, signs, banners and heads), or in an unloaded chunk. The item for each block comes from Litematica's material cache. Stray blocks that sit inside the build where the schematic wants air are counted too, and removed.

Planning the whole build

Regular blocks are planned up front by a solver that simulates the build on a copy of the area. It uses the same movement model as the bot: walking, one-block steps up, drops of at most 3, ladders, doors, half blocks. Its rules:

• Never stranded. A block goes down only if the bot can still get home afterwards, on foot or by riding its own pillars back down.
• Never sealed in. No block closes the last open side of a gap that still has to be filled.
• Roughly bottom-up. Only blocks at most one layer above the lowest unfinished layer are placed, so walls rise evenly and every block has support.
• Nearest first, then the cheapest way to the next one. Everything in reach and in sight from the current spot goes down before the bot moves. Then it picks the cheapest spot for the next block, counting walking distance, the cost of building a pillar, and extra cost near deadly edges.
• Pillars come down by riding them down, as a player would, as soon as they aren't the way back from somewhere higher.

Small enclosed pockets with two or fewer open sides are left alone rather than filled with scaffolding that could never be removed.

Building

Baritone's builder places runs of regular blocks where that's quicker. The bot's own placer takes the special blocks, anything Baritone gets stuck on, and blocks that are about to be walled in. A trap detector watches for blocks whose finished surroundings will leave no open side and whose remaining open sides are about to be filled; those are placed immediately.

Access stairs

With Access stairs on, the bot builds one dirt staircase and walkways to reach high parts of the build, instead of dirt pillars all over the place.

Scaffolding cleanup

Every dirt block the bot places during a build is recorded, using the game's own right-click event, which also fires for Baritone's placements. Only those recorded positions are ever removed, so dirt that was there before the build, or that you placed yourself, is never touched.

The cleanup is planned in advance by a second solver with hard guarantees: it always leaves itself a way back to solid ground, works top-down through each structure, only plans walks and pillars that pay off immediately (so it can't loop), and plans again whenever the world doesn't behave as expected. Dirt the schematic itself needs is held back, so pillars never eat building material.

Materials and storage

In survival mode the bot fetches from storage chests you register by punching them (and optionally your base chests). It remembers what is in every chest whenever anyone opens it, plans from those totals, and re-plans from the real inventory after each trip. Stop if short checks up front whether everything needed exists across your inventory and chests.

Checking the result

After each round the bot audits the build: wrong blocks, blocks facing the wrong way, and extra blocks are taken out and placed again. A full block standing where the schematic has a double slab is accepted as correct.

Movement

• Careful walking. Inside and around builds, routes come from the same movement model as the solvers and are walked as waypoints at every height change and every 5 blocks, so Baritone can't wander off a roof edge on a route of its own. Sprinting is off while working. Ladders are climbed by hand, and pillars are built by hand: centred, crouched, looking straight down, placing dirt under the feet on each jump.
• Safety. Vanilla auto-jump is switched off while the bot works (it made the bot hop at random near edges) and put back afterwards. Falls of more than 2.5 blocks are logged with what the bot was doing.
• Smooth camera. All turning goes through an eased controller with a per-tick cap. Camera: Still keeps your view steady while the server still sees the bot looking at every block.
• Freecam (J). The camera flies free while the player carries on unchanged. Only rendering moves: the player's real position, rotation, crosshair target and every click stay untouched. Movement keys fly the camera and never reach the player, and transitions are eased. It can outline the player so you can see it through walls.
• Free mouse (K). The game stops holding the mouse and no screen opens, so nothing waits and the bot keeps working while you use other windows. "Pause on lost focus" is switched off while this is on and put back afterwards.

Survival tasks

Smelting

The bot picks the closest group of free furnaces, splits the items evenly between them (up to a stack each), prefers blast furnaces and smokers where they fit, uses the best fuel first (wood only if you allow it, and logs are turned into planks rather than burnt), works around busy furnaces, waits out the cook time, then collects and deposits. In project mode, long smelts are left cooking while the bot does other work, and the planner counts what the furnaces will produce so nothing is smelted twice.

Crafting

The bot knows every recipe from the start. Since Minecraft 1.21.2 the client is only told about recipes you have unlocked, so Minestructor reads the full recipe list from the game's data packs (vanilla and installed mods) on a background thread, and keeps a built-in table as a fallback for the first few seconds. A depth-first planner with backtracking works out the steps in between (logs into planks into sticks). Unlocked recipes are crafted with recipe-book clicks, batched. Locked ones are crafted by placing the ingredients in the grid by hand.

Farming

Farms are boxes, and each plot remembers which seed belongs on which soil, so replanting never mixes crops. Only ripe crops are harvested. Every farm type is handled correctly:

• sugar cane, bamboo and cactus are cut above the bottom block so they regrow;
• melons and pumpkins are harvested, never their stems;
• cocoa is picked when ripe and replanted on jungle logs;
• sweet berries and glow berries are picked without breaking the plant;
• torchflowers and pitcher plants are never harvested.

The right tool is used for each crop (a sword for bamboo, an axe for melons and pumpkins), and no tool is worn out on crops that break by hand. Trampled farmland is tilled again, and enough seed is kept back for every plot.

Mining

A mining trip fetches supplies, crafts a pickaxe and torches if needed, digs a staircase down, then strip-mines (a corridor with branch pairs every 3 blocks) or tunnels. Ores are mined only when they are both exposed and visible: no x-ray. It checks for fluid hazards, places torches wherever block light drops below 8, saves its progress after each segment, and comes home when the inventory is full, the pickaxe is gone, food is low, or time is up. The optional ore finder uses Baritone's x-ray-style mine process and is labelled as such.

Tree chopping

Trees are recognised by type from the game's registries: every vanilla tree, including big oaks, acacias, 2x2 jungle and dark oak trunks, mangroves with their roots, azaleas and nether fungi. Each tree is mapped with a flood fill of its connected logs, and the whole tree is taken before moving on.

The chopper decides instantly where to stand: under the tree if the logs are in sight from there, otherwise the nearest standable spot within reach that sees the lowest logs. It breaks leaves only when they actually block the view of a log. Saplings, apples and logs are picked up, saplings are replanted (four at once for trees that need a 2x2), and the wood goes to the base chests.

Gathering

Collects sand, gravel, flint, clay, dirt, pumpkins, sugar cane and similar from the surface: only blocks visible from the air in loaded chunks, never from inside your base, farms or the build site, and never within 3 blocks of a registered chest or workstation.

Running out of tools

Each outdoor task works out which tool kind its blocks wear out (axe, shovel or pickaxe). When none is left, the task wraps up and walks home, or stops on the spot if there is no base. This can be switched off per task.

Husbandry

Pens are found automatically: a flood fill from each animal over the ground it could walk on, bounded by fences, walls and gates. A space counts as a pen if it is enclosed (under 2,000 cells) and at least 6 of its edges are fences or walls. You can also mark pens by hand.

Each round, the bot scans every pen against your rules for each animal kind, fetches food, shears and buckets from the base chests once, then works through the tasks nearest-first:

• feeding pairs of adults (each animal at most every 5 minutes);
• milking and shearing;
• culling adults above your "up to" number, never young, named or leashed animals, never below your "keep" number, and always with an axe or bare hand so a sword sweep can't hit the neighbours;
• collecting drops and eggs.

It closes every gate it opened, optionally cooks the meat, deposits the haul, and waits for the next round. Wild-animal hunting never touches animals inside pens or the base, and always leaves two of each kind nearby.

Self-defence

Threat model

Only direct threats count: hostile mobs (neutral ones only once angry, endermen only when provoked) within 3 blocks, or in sight, coming for the bot, and able to reach it. The client can't see a mob's target, so "coming for the bot" is inferred from attack mode plus facing the player. A few kinds need their own rules:

• archers count from up to 24 blocks once they take aim;
• slimes and magma cubes never show the attack flag, so facing the bot within 8 blocks is enough;
• mounted mobs (a zombie on a zombie horse) and spear carriers have their own rules, and the rider is fought, not the mount;
• water mobs in the water are ignored while the bot is dry.

A mob that hurts the bot, or stands in its way for 2 seconds, is fought back too. Villagers, pets, named and leashed mobs never are.

Fight or flee by strength

Each nearby mob gets a weight in "zombies":

• a small slime counts 0.1, a big one 0.9;
• a skeleton counts 1.2 and a creeper 2;
• vindicators count 3, ravagers 5, and the warden and bosses 50.

The bot's capacity is your "Fight at most" setting, scaled up by gear (sword or axe tier, armour points, a shield) and down by low health. It fights while the total weight is within its capacity, and once it is fighting it allows a little more before giving up, so it doesn't flip-flop. While fleeing, it turns back to fight once the chasers drop below 80% of its capacity: slimes are slow, so it can outrun the big ones and finish off the rest. Running from a real crowd marks a 24-block danger zone that the other jobs avoid for 5 minutes. As a last resort it digs two blocks down, seals the hole, and waits until it is safe.

Combat

• Weapons: the best sword or axe is equipped. A shield anywhere in the inventory is swapped into the off hand.
• Projectiles: every arrow, trident, fireball, wither skull, spit and shulker bullet nearby is tracked along its straight-line flight, and the shield comes up when one will pass within 1.4 blocks in the next half second. Shields take 5 ticks to raise, so this leaves time.
• Hits: every hit is at full charge. With one mob in reach, it jumps as the charge nears full and hits on the way down for a critical hit. With several, it hits from the ground so a sword sweep catches them all. Sprinting is cancelled so hits can crit or sweep.
• Reach: reach is measured from the eyes to the target's hitbox, as the game does it, so wide mobs like big slimes are hit from where they can be.
• Footwork: movement comes from one steering vector. The target is kept just outside its own melee reach (about 0.83 blocks between hitboxes for most mobs, more for big slimes) but inside the bot's reach. Every other mob pushes the bot away from 2 blocks beyond its reach, harder the closer it gets, wherever it stands, beside or behind. With 3 or more mobs within 5 blocks it also backs away from their middle, so they string out and come one or two at a time. It only steps toward a target that isn't coming anyway and has nobody else in the way. No movement key is ever pressed toward a drop, lava, fire, magma, cactus, berry bushes, powder snow or campfires.
• Targets: the bot fights the mob that hurts most right now. The score combines how hard it hits, how soon it can hit (already in reach counts three times as much), how hurt it is (finish the nearly dead first), and a small cost for turning to face it, with a bonus for the current target so it doesn't flick between equal mobs. If the target is just out of reach but another mob is under the crosshair when the swing is ready, that mob is hit instead.
• Creepers: a quiet creeper is kept at a distance rather than chased: the bot holds about 3.1 blocks away, just outside the range where its fuse lights, but still within hitting reach, and backs off after each hit. A hissing creeper within 6.5 blocks makes getting away the priority, unless the bot carries a shield and is facing it, in which case it blocks the blast.
• Mounted mobs and spears: a spear reaches about as far as a sword, so instead of keeping its distance the bot closes in under it, and side-steps across the path of a charging mount.

Fight for me and Hunt hostile mobs

Fight for me forces the defence system on whatever the Mobs setting says, engages anything coming for you, and stops after 3 seconds of calm.

Hunt hostile mobs picks the nearest huntable mob within 32 blocks of where you started. It never targets neutral mobs, flyers it can't reach, bosses or the warden. It walks toward the mob and marks it so the defence system takes over once it's in sight within 16 blocks, then collects the drops afterwards. A mob it can't get closer to is skipped for a minute. Between targets it walks back to the starting spot and waits, eats when hungry, and rests below 6 hearts.

Project mode (early access)

Project mode plays survival on its own until a schematic is built. It needs only the placement and a base area; chests, a crafting table, a furnace, a bed and a shelter are made as it goes.

The decision loop

Whenever no task is running, it looks at the world afresh and starts exactly one task. In order of priority:

1. survive: wear better armour, deposit when the inventory is nearly full, keep food on hand, rest when hurt;
2. night: sleep in a bed, or retreat to the shelter and do only safe work, such as mining from the shelter or crafting at stations inside it;
3. collect finished smelting;
4. clear the build site of trees;
5. analyse the schematic;
6. plan everything together;
7. carry out the first ready step of the plan;
8. top up food from the world, and light the base;
9. build, when it's worthwhile.

After every task, the whole plan is made again, so nothing stale is acted on.

Planning

The planner works from a virtual stock (inventory, remembered base chests and worn gear). Each need takes from stock first, then tries, in order: crafting from stock, smelting from stock, a raw source, smelting from something obtainable, then other recipes. Strict all-or-nothing attempts come first. If none works, it plans leniently and lists what it can't get as "needs you".

Raw sources that need a better pickaxe plan that pickaxe first, which gives the natural progression from an empty inventory: wood, wooden pickaxe, cobblestone, stone tools, iron. Planning is depth- and step-limited so it never freezes the game.

Never looping, never stuck

The gain of every task is measured. A task that produces nothing twice is held for 5 minutes, and four times for 30 minutes; the planner then picks another way or reports the item. Deaths are handled by respawning and recovering the dropped items, and 3 deaths in 20 minutes pauses the project. Build rounds that place nothing three times in a row pause it too. Try again clears every hold.

Shelter, farms and expeditions

• Shelter: early on, the bot digs a small underground room under the base with a door, puts the first chest, crafting table and furnace in it, and starts its mine from the back wall, so nights aren't wasted.
• Farm: with no farm in the base, it tills a patch near water (pouring a source block if needed) and plants what seeds it has.
• Expeditions: items that don't exist near the base, such as cocoa beans, cactus, bamboo or red sand, trigger an expedition. The bot packs food, blocks, torches and a bed, explores a zigzag ring of waypoints around the base while scanning loaded chunks for exposed target blocks, digs in for the nights, remembers the places it finds, and turns home early when time or food runs short.

Respecting your world

The bot never gathers inside the base, the build site or farms, or near registered chests and workstations. It takes logs only from natural trees and blocks only from the visible surface, and never places torches on farms or in the build. New chests are never placed next to another chest, so no accidental double chests.

The medieval house designer

The Random house button designs a house on a background thread behind a loading bar. It makes 48 complete designs, scores each, and keeps the best.

Reading the ground

Before designing, it samples the ground around you: how far the terrain drops below your feet at each column in an 81 x 81 area. Foundations then reach down to the ground on slopes, and paths and plants only go where there is ground.

Massing

A design starts with a main hall (span 7 to 11, ridge along its length). It often adds a cross-gabled wing to the front or back, at one end or in the middle, sometimes a storey lower, and sometimes a lean-to on one end. Houses are 1 to 3 storeys of 4 to 5 blocks, on a raised foundation with steps up to the door and an optional flared plinth of stairs.

Walls and framing

Each storey's floor plan is the union of its volumes, and the walls are its outline. Straight wall runs get evenly spaced log posts every 4 to 5 blocks, with posts at every corner, a log plate or sill at each floor, and log joists in the floors that show as ceiling beams. Ground storeys are mixed stone (mossier near the ground) or timber on a stone course. Upper storeys may jetty out over the front and back on corbels. Walls come in 8 schemes, each freely paired with one of 5 roof schemes.

Roofs

Each volume gets a gable profile whose pitch is chosen so the roof is about as tall as the walls: 45 degrees, alternating, steep, or steep easing toward the top. Full blocks go under stairs wherever the roof rises two blocks in one step. Roofs have a full-block ridge, trim under the eaves and gable overhangs, knee walls, and timber-framed gables with a small window. A volume's roof is drawn only where it isn't inside another volume, and the valleys where roofs meet come out of the stair-shape pass.

Dormers are built separately: a 3-wide front in the wall plane with a two-high window, a 45-degree roof running back into the main slope, side walls down to the roof, and the main roof opened up behind the window.

Details and interior

Outside:

• windows in each wall panel, with per-window shutters (open trapdoors), sills, and flower pots or azalea window boxes;
• an optional bay window;
• a chimney up a free gable end, with a lit campfire on top and a hearth in the wall inside;
• a door with log jambs, a canopy and hanging lanterns;
• a path, a lantern post, bushes and flowers, and a woodpile.

Inside:

• a staircase with the floor cut for headroom and a rail around the opening;
• furniture along the walls, scaled to the room size;
• a table with chairs, beds with their heads to the wall, bookshelves where there's no window, carpets and hanging lanterns.

Final pass

A final pass sets every stair's corner shape by the game's own rule, and every fence, pane and wall's connections from its neighbours, so the schematic matches what the game would produce. The design is turned to face you, saved as a .litematic in schematics/minestructor/, placed so the spot in front of the steps is where you stood, and selected for building.

Data and logging

• Per-world data lives in config/minestructor/worlds/<world>/: settings, the base (bounds, chests and their remembered contents, workstations, farms, pens, the mine entrance and the shelter), storage chests, and the current project. Every change is written immediately. Files are parsed defensively: bad sections are skipped with a warning and unknown item ids are dropped.
• An activity journal (capped at 5 MB) records what the bot did, with a heartbeat line every minute during builds and projects. Attach it to bug reports.

Known limitations

• Project mode is early access. It is the most ambitious part of the mod and has had the least real-world testing in varied worlds. For the best results, have the materials the build needs in your chests before starting, watch the first sessions, and use Try again or N freely.
• Project mode can't obtain Nether or End blocks, mob-only loot (string, gunpowder, slime balls), fish, or anything needing silk touch or shears. These are listed as "needs you": put them in a base chest and resume.
• Locked recipes are crafted by hand in the grid, which servers with the doLimitedCrafting game rule refuse.
• Gathering and hunting only see loaded chunks within the search range of the base.
• Beds made by the bot are white (or the colour of the most plentiful wool), and armour is iron unless you supply diamond.
• The optional ore finder is x-ray-like. Use it only where that's allowed.
• Generated houses use some blocks that are harder to gather in survival (campfires, lanterns, beds, potted flowers).
• Automating your player may break the rules of some multiplayer servers. Check before using it there.