Home › Wiki › Your village

Your village

Hired NPCs that guard, gather and build for you, paid by the hour, capped on purpose, and only ever awake while someone is nearby.

What the village actually is

The village is a set of hired NPCs that live in the world with you. They are plain data-driven mobs, not chat bots and not an AI of any kind. Each one is a record with an owner, a home, a level, an upkeep balance and a job assignment. Vanilla mob AI is stripped from all of them, so nothing breeds, panics, drifts profession, walks through a portal or picks its own fight. What they do instead is exactly the role logic described in these articles.

There are eight roles. The guard is always a faction NPC, hired from the treasury and posted on your own claims. The other seven are workers: the builder, miner, farmer, hauler, forager, lumberjack and restocker. Workers are personal, owned by you, but tagged to your faction if you have one, which is what lets faction buffs and faction officers reach them.

Everything runs through one command, /npc, with /village as an alias. /npc hire, /npc list and /npc manage open the GUI hub; /npc assign does the linking; /npc help opens a help screen whose numbers are read live from the server config, so the guide cannot drift away from the prices. Right-clicking one of your own NPCs opens the same management screen. Every assignment is a typed command, and the GUI prints the exact line, so the whole system is usable from Bedrock without a keyboard shortcut in sight.

Hiring, and what it costs every hour

Every hire and every upgrade costs two things: coins, and Rift Ore Fragments. Fragments drop from rift mobs, so the village is fed by the same loop that feeds the forge. The charge order is coins first, then fragments, with a rollback: if the fragment consume comes up short at the last moment, the coins are refunded. There is no half-paid hire.

Upgrading an NPC raises its per-burst budget and its daily cap. Both the coin cost and the fragment cost scale by a factor of 1.6 per level already held, so the fourth level is roughly four times the first.

Upkeep is charged hourly and the first hour is free at hire. Personal workers are paid from the owner's balance; guards and faction-tagged NPCs are paid from the faction treasury. If your profession matches the role, the coin half of the hire is discounted by 4 percent per profession rank, counted as rank plus one, so a high-rank Miner pays noticeably less for a miner. The mapping is deliberately sparse: Miner to miner, Trader to hauler and restocker, Toolsmith to builder. Guard and farmer have no matching profession and get no discount.

An NPC that cannot be paid does not disappear. It goes dormant: frozen where it stands, with a loud "(unpaid)" suffix on its nameplate and a status line telling you to use Pay Upkeep to revive it. Top the balance up from the detail screen and it wakes. Nothing is lost, no records are deleted, and the carried inventory stays with it.

The caps, and how far they move

Three limits stack, and the smallest one wins. The server-wide ceiling is 60 live NPCs, and no purchase of any kind raises it. It exists to keep the worst case small and the tick budget honest.

The per-player cap is a personal safety limit, so the buff that lifts it is bought by you and follows you rather than your faction. It runs seven tiers of two slots each, which takes six to twenty and no further: the code clamps the result against both the twenty and the global sixty, whatever the tiers say.

The worker cap is shared across a faction, which is the same shape Garrison and Overseer already use. Twelve workers is the base figure and Workforce raises it by two per tier. Guards sit on their own axis: the cap is the greater of two and one per faction member, plus whatever Garrison adds, and Garrison also adds 4 percent guard damage per tier.

Awake only when you are there

An NPC acts only while an online player is near it or near its worksite. By default "near" means render distance, the world's view distance in blocks plus a chunk of margin, so an NPC works wherever it is actually being rendered. The server can be switched to a fixed 48-block column instead. When nobody is watching, the NPC's target is dropped, its pathfinding stops, and it stands frozen at no cost. A village nobody is visiting is not a performance problem, which is the whole reason the caps can be as generous as they are.

On top of presence there is a working day. The default is day: workers work in daylight and clock off at night. It can also be set to any, to night, or to a fixed window of world time, and the setting fails open, so a mistake means "always working" rather than "never working". Off hours do not mean standing still. The worker walks home, claims a bed and sleeps until the window reopens or a job appears.

Beds are assigned, not improvised. A worker takes the nearest usable bed head within 5 blocks of its home, and that bed is then reserved: no second NPC will ever claim it, and the reservations are rebuilt from the saved records on every boot. A worker with no bed in range simply does not sleep, which is a quiet degrade rather than a failure. A sleeping NPC is genuinely motionless, and it is woken before any teardown so its bed frees up properly.

With no job step to do and nothing to sleep for, a worker strolls inside a tether around its home, roughly ten blocks by default, and looks at the nearest player. It never leaves the tether, and the instant a real job step exists it drops the idling and goes to work.

Linked chests: up to 64 per NPC

A worker that needs storage does not get one chest. It gets an ordered set of up to 64 containers, with a primary at the front. A double chest counts as a single entry no matter which half you looked at when you linked it, so the ceiling is 64 double chests, roughly 3,456 slots.

Chests, trapped chests and barrels can be linked. Shulker boxes cannot, and that is deliberate: a linked shulker box walks away in somebody's inventory and the link rots silently.

Note the semantics: the bare chest verb adds. To replace the whole set, clear first and then link again. Both the reply and the help screen say so every time. There is also a paginated chest screen inside the management GUI with per-card unlink and make-primary, and clicks there resolve against the drawn snapshot, so an unlink happening at the same moment cannot make your click land on the wrong entry.

Fetching and depositing walk the set nearest first, and the whole chain is scanned once per pass rather than once per material. Two rules keep this from becoming a teleport: a worker only ever pulls from the container it is standing at, and material sitting in a different chest is a separate trip. Protection rights on both halves of every double chest are re-checked at work time, on every single burst, not just when you first linked it.

Chunks that are not loaded are shown as exactly that. The screen marks such a container as paused rather than pretending it is empty, so you can see why a chest is idle instead of concluding the NPC is broken. Nothing in the village ever force-loads a chunk to read a chest. If you break a linked container, the dangling entry is cleaned up on the next real write to the record; reads never quietly rewrite anything.

Getting there on foot

Village NPCs walk. An early version of the system snapped them to their worksite beyond sixteen blocks and the pathing was cosmetic; that is gone. A work burst now runs only once the NPC has genuinely arrived, and there is no teleport shortcut to a job or a chest.

Arrival is measured differently depending on what is being reached, because one metric cannot serve both cases honestly.

The ray trace is the part that matters. Horizontal-only arrival once let a worker stand on a floor and pull items out of a chest directly beneath it. Now the NPC must be able to see the container it is reaching into, in a straight line, from where it stands. That is what makes "it walked to the chest" a fact rather than a claim.

Along the way, closed wooden doors and fence gates on the next couple of path nodes are opened, tracked, and shut again once the NPC is more than 2.5 blocks past. Only doors the NPC itself opened are ever closed. Iron doors and iron gates are never touched. Doors are closed on every teardown, and any that were still pending are closed when the chunk next loads, so nothing is left hanging open overnight.

When a walk genuinely fails, you get told. After three fruitless repaths, a worker within about twelve blocks of the target settles for "close enough", faces the target and works from there, which is the honest answer for a miner standing on solid stone. Beyond that range it gives up gracefully: a throttled message to the owner saying it cannot reach its worksite and to clear a path or re-assign, a walk home, a back-off of about a minute, and then another attempt. The nameplate reads Blocked and the GUI status line says the same. There is no thrashing, no repath spam and no wandering off. A linked chest that is simply too far away gets a staged approach up to a fixed number of stages and then the same honest report, rather than an endless crawl.

Who is allowed to touch your NPCs

There is one authorisation check, and every route into the management screen passes through it. The command, the click in the list, the right-click on the mob itself and the return from any button all land on the same gate. That is the point: a single control point cannot be inconsistent with itself, which is how the earlier version leaked, when the right-click and the commands each had their own opinion.

The owner passes on ownership alone, before rank is even considered, so a regular member never loses control of a worker they paid for. Everyone else who right-clicks the NPC gets a read-only status line and nothing more: no GUI, no buttons, no assignment. Guards, being faction property, are hired, dismissed, upgraded and equipped at officer level and posted at claim level, and their posts and patrol waypoints can only be set on the faction's own claims.

Separately from all of that, an NPC never bypasses land protection. Every block an NPC breaks or places, and every container it opens, passes the same protection check a player would, evaluated at the moment of the action rather than at the moment of assignment. If your rights over a build site disappear mid-build, the builder pauses and reports it.

Paying for the work: materials, treasury, buffs

The materials screen lists everything a build still needs, biggest shortfall first, marked as stocked, short, or short but craftable. The figures are one reading of one scan of the linked chest chain plus the carried buffer, so what the screen says and what the builder actually consumes are the same number by construction.

The Buy all required button buys the entire remaining shortfall in one click and delivers it into the linked chest. Two things about it are worth knowing before you press it. First, materials with no market price are excluded and named in the reply rather than quietly handed over. Second, the button says who pays before you click, because the payer decision and the label are literally the same call:

• A faction member with withdraw rights pays from the treasury, at the untaxed base price, against the same daily withdrawal limit that /f withdraw uses. A single click cannot drain a treasury past that limit.
• Everyone else, including anyone in no faction, pays from their own wallet at the quoted, tax-inclusive price.

The charge happens before a single item is created, so a failed payment delivers nothing and a successful one always delivers. If the chest cannot hold the delivery, the purchase is refused before you are charged, with a message naming how many free slots are missing.

Hire and upgrade costs work the same way when you are in a faction: coins come from the treasury and fragments from the faction's fragment bank, topped up with /f fragments deposit and viewable with /f fragments. If the bank is short, the acting member's own fragments make up the difference. A player with no faction pays for everything personally, so solo play is never blocked.

All four are permanent purchases rather than timed effects, they are paid from the treasury, and the subsidy is applied both to the actual charge and to every cost readout, so the number on the card is the number you pay. Overseer is the only one with no ceiling; the cost curve is what stops you, not a tier limit.