Home › Wiki › NPC Roles

NPC Roles

The eight village NPC roles: what each one does, the checks it passes before it touches a block, and the daily limit it works to.

The rules every role shares

There are eight roles. The Guard is a faction NPC, hired from the treasury and posted only on your own claims. The other seven are workers: Builder, Miner, Farmer, Hauler, Forager, Lumberjack and Restocker. Every one of them is a plain data-driven mob with its vanilla AI stripped, steered by the plugin and by nothing else.

They only work while you are there

An NPC acts when an online player is within render distance of it or its worksite. Otherwise its target is dropped, its pathfinding stops, and it stands frozen at zero cost. An NPC parked in an empty corner of the world does nothing at all, and this is deliberate: it is what keeps a full village off the tick budget.

Upkeep, caps and levels

• Upkeep is charged hourly in coins, from the faction treasury when the owner has a faction and from the owner's balance otherwise. The first hour at hire is free. Unpaid means dormant: frozen, with (unpaid) on the nameplate, until you top it up.
• Caps. 60 live NPCs on the server is a hard ceiling nothing can exceed. 6 per player, raisable to 20 through a personal buff. 12 workers per faction, raisable by the faction Workforce buff. The guard cap is separate: max(2, 1 per member) plus the Garrison buff.
• Levels run to 5. An upgrade costs coins and Rift Ore Fragments at 1.6 times the previous level. Work budgets scale with level and with the faction Overseer buff, which adds 20 percent per tier to both the per-burst budget and the daily cap.

Protection is re-checked at work time

Every block an NPC breaks or places, and every container it opens, passes the same composed gate: a dungeon world is refused, a non-global WorldGuard region is refused, unclaimed ground is allowed, your own faction's claim is allowed, and everything else is refused. The check runs when the work happens, not when you gave the order, so rights lost mid-job stop the job.

No worker touches a container it is not standing at

Workers carry a persisted buffer. The Builder fetches into it by walking to the chest; the Miner, Farmer, Forager and Lumberjack fill it and then walk a deposit trip. A chest errand demands strict arrival: none of the "close enough" shortcuts that apply to ordinary travel apply to a chest. The Hauler is the one documented exception, and it still walks both legs.

Daily limits

Every worker has a daily output cap. It is persisted, and it rolls over on the UTC day boundary. When a cap is spent the NPC says so on its card rather than stalling silently.

Who can manage one

The owner always can. Faction MOD rank and above can open the management GUI. Faction ELDER rank and above can assign posts, patrols and worksites by command. Everyone else gets a read-only status line when they right-click, from every route: the command, the list, the GUI and the right-click itself all run the same check.

Guard

Guards are faction property. They are hired from the treasury, they can only be posted on the faction's own claims, and a member of MOD rank or above hires, dismisses, upgrades and equips them. They are the only role that produces nothing and the only role that fights.

Post duty or patrol

A guard either holds a post or walks a patrol. A patrol takes up to 8 waypoints, walked in order, and every waypoint must sit within 50 blocks of the post. Waypoints outside that radius are rejected when you add them and pruned if you later move the post.

The post is the guard's home: idling, returning and respawning all key off it. A posted guard keeps a tight leash of 24 blocks and walks home the moment it is dragged beyond that. A patrolling guard's effective leash widens to cover its patrol radius plus its detection radius, so a legitimate 50-block route is never cut short halfway round. Both rules together are what stops guards being walked around as a mobile army.

Who a guard may hurt

Only a player, and only one that passes every part of the test. The check is enforced three times over: in the acquisition scan, again as a validator on the targeting event, and a final time on the damage event itself.

• online, in a fighting gamemode, and not vanished;
• not a member of the owning faction and not an active ally;
• hostile, meaning either a member of a faction at active war, or on the faction's 30 second aggro memory, which is fed by attacks on the faction's guards and workers and by PvP against members inside the claim;
• standing inside the owning faction's claim, or within leash of the post.

That leaves members, allies, pets, workers and other NPCs permanently safe. The neutrality runs both ways: nothing can target an NPC either, and non-player damage to an NPC is cancelled, so a frozen worker cannot be killed by ambience. Villagers stand calm beside zombie guards because no villager can start a movement of its own in the first place.

Hostile mobs in the claim

Defending the claim against hostile mobs is also the guard's job, on a bounded slow-pass scan around a detection radius of 12 blocks. Creepers are the awkward case, because a creeper that has acquired a guard will swell and detonate on it, and the blast would damage the claim. So a creeper that primes while targeting a guard, or while standing within its own blast radius of one, has the blast cancelled and is disarmed: the fuse resets, and the guard finishes it in melee. An ordinary creeper explosion away from any guard behaves exactly as it always did.

Equipment, damage and death

A guard has five equipment slots. What you put in renders on the mob and counts toward its combat stats through ordinary mob equipment mechanics, with every drop chance set to zero. Level scales the rest: 30 base health plus 10 per level, 4.0 base damage plus 1.0 per level, and the Garrison buff adds 4 percent damage per tier on top.

A guard that dies drops nothing. No gear, no items, no experience, cleared at the last possible moment as a backstop. It then respawns at its post after 120 seconds. Your armour is not lost when a guard falls, and killing one is not a way to farm it. A server can switch respawning off, in which case a dead guard has to be re-hired instead.

Builder

The Builder is the largest role by some distance and has its own article. This is the shape of it.

You link a container with /npc assign <id> chest, point it at a schematic with /npc assign <id> build <name>, and the footprint renders as a dust outline until you commit with /npc assign <id> confirm. From then it places blocks bottom-up, four per burst at base, every 40 ticks, charging exactly one placement item per placed block from the linked chests. A block that is already the right material advances progress for free.

It never pulls from a chest at range. When it runs out of a material it either walks a real fetch trip, if the chest has it, or goes to MISSING and sends you a throttled report naming the material. It erects scaffolding to reach height and tears it down again on every teardown path. Cancelling a build keeps the blocks already placed and refunds nothing.

The full account of schematics, the material GUI, the crafting fallback and the scaffold lift lives in the Builder article.

Miner

You give the Miner a region centre and a deposit chest. It works a bounded box around that centre: radius 8 by depth 8, and it never leaves it. The region is fixed, which is what makes the rest of the design work.

The scan is a rolling cursor, not a sweep

It never scans the whole volume. A persisted cursor walks the box, and each work step examines at most 128 positions before stopping and picking up again next burst. A full pass of the region therefore takes about twenty bursts. That is the cost ceiling of a Miner, and it does not change with how much ore is in the ground.

What it will and will not mine

Only whitelisted terrain and common ores, and never the rare-material set: diamond, emerald and ancient debris are excluded by the same shared list the buff system uses. Diamonds and netherite cannot be automated. Drops are computed as though the NPC swung a virtual iron pickaxe, so fortune effects and player traits do not apply.

Deposits

It collects into its carry buffer and then walks a deposit trip to the linked chest. If the chest is full it does not drop the load: it keeps it, parks at the chest and backs off for 60 seconds. A partial load is always deposited eventually, including when the region has gone dry or the daily cap is spent.

Farmer

The Farmer works a field around an assigned centre, harvesting ripe crops and replanting them in the same write, so a harvested plot is never left as bare farmland for a tick.

The field

The default field radius is 8, which is 867 block positions in the scanned volume. The clamp allows up to 16, which is 3,267 positions. That is the honest cost of a wide field: the bone meal pass in particular walks the whole box every burst rather than using a rolling cursor, and a barren or fully-grown field never exits it early. A radius of 8 is the tuned default for a reason.

Vanilla crops are wheat, carrots, potatoes, beetroot and nether wart, taken at maximum age.

Hemp and cannabis, on registered fields only

The Farmer also harvests hemp and cannabis, through exactly the same harvest funnel a player's own harvest uses. There is one crop-harvest implementation on the server and the NPC does not get a second one.

It will only touch a registered plot. A plot registers itself when you plant it with a Blacklight seed. Fields that predate the registry are invisible to the Farmer, which reads from the outside as the feature simply not working. /farm adopt [radius] is the fix: it registers the crop hosts around you, radius 8 by default and clamped 1 to 16, spanning four blocks up and down. It skips unloaded chunks, skips plots already registered, checks your rights per block, and reports what it adopted, what was already registered and what it skipped.

The load-bearing rule is that the host must be standing on farmland. A world-generated berry bush never grows on tilled soil, so the test admits real farm plots and excludes wild plants without having to trust anyone's intent. The cost is real and stated plainly: hemp planted on grass, dirt or podzol cannot be adopted and has to be replanted on tilled soil. Automation never adopts a plot; only a deliberate human command does.

An NPC harvest yields base drops only. No Fiber Hands, no Master Curer, no crop yield buff, and no farming experience or coins. The Farmer is a throughput device, not a multiplier: player progression rewards stay attached to players.

Bone meal

The bone meal pass runs after the harvest sweep in every burst, so a crop that is ready is always harvested before any meal is spent on it. It applies 3 bone meal per pass by default, adjustable from 0 to 16 where 0 turns the pass off, and scans at most 512 positions.

• The candidate set is exactly the harvest candidate set minus anything already mature, so it never fertilises a wild bush or random foliage.
• It uses the vanilla application, which means the cannabis growth cap still fires and a pitcher crop can never be pushed past its single-block stage.
• Meal is debited only when the game actually accepted the application. A refused application costs you nothing.
• Restocking takes bone meal from the chest first, and otherwise converts bones at the vanilla ratios: one bone gives 3, one bone block gives 9.

Hauler

The Hauler is the simplest role and the cheapest. It shuttles between two links: a pickup chest, assigned with /npc assign <id> source, and a delivery chest, assigned with /npc assign <id> dest. Until both are set it says which one is missing, with the exact command to fix it.

Each burst moves up to 16 items, every 100 ticks. It walks both legs of the ferry: there is no teleport anywhere in the movement system, and a Hauler that cannot reach one end reports it rather than reaching through a wall. It is the one documented exception to the standing-at-the-container rule, in that the items move atomically at pickup, but the walk itself is real in both directions.

The important detail is what counts. The daily total is incremented by what the destination actually accepted, not by what was picked up. A destination chest that is full accepts nothing, so nothing is counted and nothing is lost; the Hauler names the container that is blocking it instead of going quiet.

Forager

The Forager is a builder's assistant. You link it with /npc assign <id> builder <builderId>, and from then on it works to that builder's open demand and nothing else.

It gathers what the build is short, and stops

Every burst it reads what the linked builder still needs. If the builder needs nothing, or there is no builder, the Forager does nothing. It does not gather speculatively against a future build.

The demand accounting is worth knowing about, because it is what makes the stopping work. It accumulates raw demand across every needed material first and only then decides what to fetch, so a material that is needed both directly and as an ingredient is not counted twice and does not send the Forager gathering to its daily cap for a build that wanted sixteen. A material that nothing on the whitelist drops, a combat drop like string, is skipped honestly rather than pretended at: a Forager that promised string would leave the builder waiting on a delivery that could never come.

Two modes: gentle by default

The default is conjure-only, and it breaks no blocks at all. On its first tick it swings, shows a searching particle and starts a timer; after 20 seconds it materialises one wanted material into its carry and re-arms the timer. It is bounded by exactly three things: the demand set, the daily cap, and how much room is left in the carry. It produces blocks and never coins, and you are paying its upkeep the whole time, so it is a paid convenience rather than an open faucet.

natural-only is the physical harvest. Every block it breaks passes six filters, applied per block at work time and never skipped or cached: whitelist, rare-material set, demand, infrastructure, scope, and the protection gate. That last check is re-run on every node of a tree fell, because a connected mass of logs can cross a claim boundary and only a per-node check catches it. Containers and item-holding blocks are excluded by class rather than by a material list, so copper chests, shelves, beehives, campfires and suspicious sand are all invisible to it.

Whole trees or nothing

A fell is atomic. The Forager enumerates the connected log mass first, and if it is larger than tree-chop-max, 24 by default and adjustable from 1 to 96, it refuses the whole tree. Nothing is half-felled. That single rule is what separates an oak from a log cabin, and it is why a dark oak or a large jungle tree is left standing at the default: both exceed 24 logs.

Roaming and deposits

It roams from its home within a forage radius of 64 blocks, adjustable from 16 to 128, and the leash is measured from home rather than from the mob. Within that it works a fixed box of 2,601 positions, scanning at most 128 per burst, and only moves the box once the box is swept dry. It deposits standing at the builder's chest, which is resolved live per errand, so a builder dismissed or re-linked mid-trip degrades cleanly instead of leaving the Forager walking to a chest that belongs to nobody. Dismissing the builder unlinks the Forager.

The gather whitelist is 26 natural materials: the 9 natural logs, 7 stones, sand, gravel, dirt, clay, bamboo, sugar cane and cactus. Ores are excluded and stay the Miner's job.

Lumberjack

Where the Forager works to a builder's demand, the Lumberjack is autonomous. It roams its own radius, fells mature natural trees, replants them and banks the yield in its own chest. It is a renewable forestry role, not an assistant.

It searches wide and fells narrow

The search radius is 64 blocks, adjustable from 8 to 128, and up to 256 positions are examined per burst. That wide number is a targeting range, not a felling range. The near box around the mob is tried first and felled as usual; if it is empty, the search looks outward, sets the distant tree as the work target and returns. Travel covers the distance, and the next burst fells the tree from the near box, standing next to it. Nothing is broken at 64 blocks: the world does not change around a worker that never moved.

The outward search is a deterministic nearest-first spiral of columns around home, with the cursor persisted, so consecutive bursts continue outward instead of re-walking the same empty inner ring. The roam radius, 96 by default, is never allowed to be shorter than the search radius, because a tree the scan accepts and the roam then refuses would be refused forever.

Grief protection is inherited, not rewritten

The Lumberjack adds no new block-breaking logic to the fell. It calls the Forager's fell directly, and so it carries the whole composition: natural overworld logs only, the rooted-and-leafed tree shape check, the whole-or-nothing mass rule that separates an oak from a cabin, and a protection re-check on every node. Copying that code rather than sharing it is exactly how the two would have drifted apart.

The canopy strip, and why the replant is paid for

After a fell it takes down the canopy, and the rule is narrow enough to be worth stating: it only removes leaves that are not persistent, which is the game's own marker for leaves a player placed, and only those the fell actually orphaned. A leaf with a surviving log within 6 blocks belongs to a tree that is still standing and is left completely alone. Everything it takes is what vanilla would have decayed away anyway, so the strip is a yield change rather than a world change. It is bounded to 5 blocks horizontally, 16 up and 2 down, 128 leaves per burst, and it stops the moment the carry is full rather than destroying what it cannot bank.

The strip exists because the replant is paid for. The Lumberjack banks every sapling its trees drop, so conjuring a free sapling on top of that would make it a sapling duplicator. Instead the replant takes a sapling out of the NPC's own carry, and when there is none it leaves the ground clear. Without the canopy strip no sapling could ever reach the carry, and the role would have been a pure deforester.

Two budgets, not one

Every block a worker breaks is charged to some budget, and leaves are not free. The Lumberjack keeps two separate daily accounts: 3,840 logs and 30,720 leaf blocks. Both roll off one shared day stamp, so they can never drift apart across a restart and freeze one budget at yesterday's number. Both are pre-clamped, so the last fell of the day cannot overshoot. The NPC card reports the log cap normally and names the leaf budget only when the leaf budget is what is actually blocking it.

Restocker

The Restocker keeps a regional shop's stock topped up. It takes two links: /npc assign <id> shop while looking at the shop's chest, which is validated as a real shop you own or manage, and /npc assign <id> chest for the supply chest it draws from.

It never touches money

All it does is move items into a listing's stock. Players still buy from the shop and pay the owner exactly as they did before, and the Restocker takes no cut, sets no price and holds no balance. The rule that no money moves without a player action is untouched by this role.

It walks both ways, and items are conserved

The Restocker is a two-leg ferry with a carry buffer and strict arrival on both legs. It works out which leg it is on from its own carry: if the carry can top up a listing it walks to the shop chest, otherwise it walks to the supply chest. Fetching happens standing at the supply chest and stocking happens standing at the shop chest.

The accounting is exact. The source loses N and the shop's stock gains N. Nothing is minted, and the carry is decremented by precisely what the shop accepted, so a listing that only had room for part of a load cannot leave the carry and the stock disagreeing.

Ordinary offers only

Only plain listings are refilled. A listing selling a custom item is never restocked, because a plain source item could otherwise mint stock for an offer it does not match. This is the flagged limitation of the role: if your shop sells forged gear or Blacklight items, the Restocker will not help with those listings.

When it stops

It goes idle, cleanly and quietly, when the shop is full, when its daily cap of 9,216 items is spent, or when no shop is linked. Shop ownership and the protection gate are both re-checked at work time rather than at assign time, so losing rights to the shop stops the restocking. On dismissal its carry drains back into the supply chest.