Home › Wiki › The Builder

The Builder

The builder raises a schematic block by block, pays one material per block from your linked chests, and names exactly what is missing.

How a build starts

The builder is one of the village NPCs. Hiring one costs coins plus 12 Rift Ore Fragments, and it draws hourly upkeep from your balance like every other worker. If your job is Toolsmith, the coin half of the hire price is discounted. Only the owner, a faction moderator or above, or an admin can give it orders, and that includes opening its menu by right-clicking it: everyone else gets a read-only status line.

A build is set up in three moves. Link at least one container, name a schematic while standing where you want its corner, then confirm. Nothing is placed and nothing is charged until the confirm.

Once confirmed, the builder works one burst every 40 ticks, and only while a player is close enough for the site to be watched. A burst places up to 8 blocks by default, multiplied by the NPC's level and by the faction's Overseer buff. The block list is pre-sorted bottom-up (y, then x, then z), so a structure rises in layers rather than appearing in the order the file happens to store. Walking that list is capped at 256 steps per burst, which bounds a re-walk over a mostly finished build; it is not a cap on how many blocks get placed.

Cancelling a confirmed build stops the work and keeps every block already placed. There is no refund for what was already spent.

One material per block, counted

Every block the builder places is paid for out of the linked chests, and the charge is counted rather than estimated: one placement item per placed block. The charge is the item that would place that block, so a crop charges its seeds rather than the grown plant. Consumption edits the live inventory, so a chest you are looking at updates while you watch.

Skipped entries never enter the block list, the bill of materials, the shortfall readout or the progress denominator, so the numbers on the screen and the numbers the builder acts on are the same numbers.

When something runs out, the builder does not stand still. It moves to the MISSING state and sends the owner a report naming the material and the amount it is short by, throttled to one message per minute so a long build does not spam you. On confirm you get the whole shortfall list at once instead of learning it one material at a time. The management screen shows live progress as placed against total, plus the largest shortfalls, and distinguishes "short by N, the builder can craft this" from "short by N, no craft path".

Rights are re-checked at work time

An NPC never has more reach than the person who hired it. Every block mutation passes the same composed gate, in this order: admin bypass, then a dungeon veto, then a veto for any non-global WorldGuard region, then claim membership. The composition fails closed, so an answer it cannot determine is a refusal.

The important part is when the check runs. It is not only at assignment. Every single placement and every read of the linked chest re-pass the gate at work time, so rights that were valid when you typed confirm do not carry the build forward on their own.

If the owner loses those rights halfway through, the build does not silently stop or quietly finish. It moves to PAUSED and reports, and that happens on both branches: the one that lost placement rights and the one that lost access to the chest. The footprint corner check you get when you first name a schematic is a fast courtesy check on the outer corners only; the authoritative decision is the per-block gate, which is why a claim boundary running through the middle of a structure is caught properly.

The recipe planner

When the next block is not in the chest, the builder does not give up on it straight away. It works down a fixed ladder: what it is already carrying, then a fetch from the linked set or a reachable claim chest, then crafting the block itself, then the free technical case, and only then MISSING.

The crafting step is a bounded search. It starts at the block it needs and walks backwards through recipes toward raw materials, expanding only branches that lead to the thing it wants. A material already on the current path is never expanded again, which is what stops a block turning into nine items turning back into a block forever.

Batching is the difference between a builder that works and one that walks. Before it existed, a wall of stairs meant one craft, one placement, one empty inventory and one more round trip. Now a single trip to the bench covers many blocks. If the batch it planned turns out to be more than the chest actually stocked, the trip is degraded to what is there rather than thrown away, and if the size it asked for will not fit the carry, it retries at half the size rather than reporting a block it could have made one at a time.

Nothing happens at range. The two legs of a craft are separate errands with strict arrival: the builder walks to the chest and stands at it to take the ingredients, then walks to the bench and stands at it to make the block. There is no lenient "close enough" for either leg, and no material is ever pulled from a container the builder is not standing at. A linked table wins when it is reachable; otherwise the nearest reachable one is found and walked to in exactly the same way.

If a craft fails for want of ingredients, the builder escalates before it reports MISSING: it sweeps the loaded chunks of its faction's claims for either the finished block or its ingredients, on a widened leash, and walks to whatever it finds. Claimed chunks that nobody has loaded are not candidates, and an honestly absent material still ends at MISSING.

Getting up to the wall

A wall gets taller than the builder. The honest answer to that turned out to be a ramp, because the vanilla navigator has no concept of a climbable block: the air above a scaffolding column is not a node it can path to or stand on. A scaffolding staircase would inherit the same problem, so the ramp is built from solid blocks.

The shape is dictated by what the navigator can actually walk. A mob gets exactly one block of rise per horizontal step and needs real head clearance, so the ramp is one block up per one block along with two blocks of head room per tread, and each tread is pillared down to the ground so the whole thing is self-supporting terrain rather than a floating wedge.

• Exterior only. The ramp runs out from an outside face of the footprint and descends away from it. It is never rooted inside the structure.
• Inside a fixed band. No helper block may stand further than 5 blocks from the footprint's nearest edge, not its centre, so the structure is hugged rather than trailed across the landscape. The band is enforced when the ramp is planned, when a standing one is reused, and once more immediately before each block is written.
• Refused, never truncated. If the band, a chunk edge, an obstruction, missing footing or capacity blocks it, the ramp is declined outright. A half ramp is not a smaller ramp, it is a wedge with an unclimbable drop at the low end.
• Fall back to placing from the base. Where no ramp is possible, the builder places from ground level instead. A build never bricks for want of a way up.

Every helper block is tracked from the moment it is placed, and the tracking list is the only record of ownership. All of it comes down when the build completes, when it is cancelled, and when the NPC is dismissed or dies. Ownership is pinned to the material the structure started with rather than re-read from settings, because a setting changed mid-build would otherwise un-own everything standing and leave it there permanently.

The ghost preview

Between naming a schematic and confirming it, the structure is drawn where it would stand. These are client-side blocks: they are sent to the viewer's client only and no block in the world changes, so there is no entity to leak and nothing to clean up if the server stops mid-preview.

• Only authorised viewers see it, meaning the owner, faction moderators and above, and admins, and only within 48 blocks of the build origin. Nobody else sees anything.
• Large structures are thinned to at most 2,048 shown blocks by taking an even stride through the sorted block list. The gate on distance decides who sees the ghost; the stride decides which blocks are in it.
• Air is never faked, because a fake air block would hide real terrain.

rotate turns the whole thing in 90 degree steps and re-draws it. Directional blocks turn with it: stairs, doors, logs, signs, fences, walls, rails and chests all rotate correctly rather than staying stuck facing their saved direction. The bill of materials is identical in all four orientations, because rotating changes where blocks sit and which way they face, never what they are. Rotation is only allowed while the build is still a preview, which is exactly the state in which progress is guaranteed to be zero, so there is never a half-built structure to reconcile with a new orientation.

Cancelling a preview costs nothing at all: no blocks, no coins, no materials. You can re-issue the build at a different origin or a different rotation and preview again cleanly.

The ghost is reverted by re-sending the real block, and it is reverted on every exit: confirm, cancel, a re-issue that changes the schematic, rotation or origin, walking out of range, the chunk unloading, dismissal, logging out, and a server reload. A slow sweep keeps this true even for a build origin far from the NPC itself, where the NPC is not being ticked.

Schematics and composites

Schematics live in the server's schematics folder and are named by the file without its extension. Subfolders count as part of the name: a file at schematics/houses/small_hut.nbt is built with build houses/small_hut, and that same name is what tab completion and the browser screen show. Every read is guarded against path traversal, and the resolved file is checked to sit inside the schematics folder, so a name cannot climb out of it.

Composites. A .blbuild file is a short manifest listing parts, each naming another schematic with an offset and an optional rotation. It is compiled into one ordinary structure in its own coordinate space before anything downstream sees it, so progress, preview, shortfall, buying materials and whole-build rotation need no special handling. A manifest may not contain another manifest: nesting is one level, and that depth counter is also the cycle guard, so a manifest naming itself is refused. Where parts overlap, the last part wins, and the overlaps are counted and reported when you assign the build, in the form "3 parts, 41,208 blocks, 96 overlaps". A silent overlap is how a composite quietly builds the wrong thing. The bill of materials is recomputed from the merged result rather than summed from the parts, so an overwritten block is not still billed, and the volume limit is re-checked after every part instead of once at the end.

Volume. A schematic may be at most 262,144 blocks. That ceiling is a memory decision, not an arbitrary one: a 256 by 256 by 256 file of around 20 KB on disk expands to roughly 600 MB of records while it is being read, and the fix for that is streaming the parse, which has not been done.

Refusals name their reason. A schematic that cannot be built used to read back as "unknown schematic" whatever the actual cause, with the real diagnosis only in the console. It now says which of the seven causes applied, for example that its volume of 300,000 exceeds the limit of 262,144. A file written for a very different Minecraft version is refused too: if more than half its block states fail to resolve, the whole build is declined rather than placing the handful that did parse and leaving you rubble to clear by hand.

Paying for the materials

The materials screen lists every material still needed, largest shortfall first, and carries a single button that buys the whole outstanding shortfall at once. There is no per-material purchase and no quantity stepper: it is all or nothing.

Who pays is decided by one rule, and the same rule writes the label and takes the money, so the two cannot disagree. A player with the faction WITHDRAW permission, the same gate /f withdraw uses, pays from the faction treasury at the untaxed base price. Everyone else, including a plain member and anyone with no faction, pays from their own wallet at the tax-inclusive quote. The button says which of the two will happen before you click it, and the total it shows is the total you will actually be charged.

Whatever is bought is delivered into the builder's linked chest, with overflow dropped at the chest rather than lost. Treasury coins become building materials at a known location, never coins in someone's wallet. Materials with no market price are excluded from the purchase and reported, never quietly handed over for free.

By default, build materials do not count against your faction's daily withdraw allowance, so buying a wall does not wedge an unrelated /f withdraw later the same day. That exemption rests on three properties: the amount is always the computed shortfall of a real assigned schematic and never a number you typed, the rank gate is unchanged, and the delivery goes to the chest. Every purchase taken this way is written to the audit log with the faction, the actor, the NPC, the schematic and the amount.

Where the prices come from. Materials are priced from the same 1,219 entry base value table the rest of the economy reads, with diamond as the shared anchor at 100. Resolution is reference-first: a material that already had a price on the three step reference board keeps it, and everything else comes off the continuous table. That preserves what the builder used to charge, and it has one visible consequence worth knowing about, because one shortfall total then mixes a coarse board with a fine curve:

A raw material can therefore cost more than the thing crafted from it. It is a known trade-off of keeping old prices stable, and it is one of the reasons stocking the chest yourself is usually cheaper than buying the shortfall.