VillagerWarden

Villager trading halls without the lag - and without breaking trading.

Automatic. No name tags, no special blocks, no commands for players to learn. Free, no dependencies, no telemetry.

---

Why trading halls lag

A villager locked in a 1×1 cell cannot go anywhere. Its brain does not know that. Every tick it looks for paths, beds, job sites, meeting points and other villagers to gossip with. A hall of 200 villagers keeps the server busy doing nothing useful.

What VillagerWarden does

It pauses the brain of villagers that are locked in - and does their work for them by the vanilla rules:

• Restocking happens the way a vanilla villager does it: at its job site, during work hours, at most twice a day, at least 2400 ticks apart. Demand and prices are updated exactly as in vanilla, through the server's own restock - so popular trades still get more expensive. A hall of "optimized" villagers does not become an endless source of cheap deals.
• Trading wakes the villager up. While you trade, and for three seconds after, its brain runs as usual: it looks at you, and the game itself levels it up, unlocks new trades and counts every trade toward your reputation. Nothing is reimplemented, so nothing can drift from vanilla.

Measured on a test server - 200 villagers in 1×1 cells, active as if a player stood in the hall, two alternating 60-second runs each way:

	Average tick
Brains running	8.6 ms
Brains paused	0.9 ms

That is 90% of the tick. Villagers are the most expensive mob in the game - about 40 µs each, every tick.

Who gets paused - automatically

Only a villager that:

• has a profession and has traded at least once. Villagers that never traded keep their brain, so you can still reroll their trades by breaking and replacing the job site;
• is locked in: sits in a minecart or boat, or can reach only a few blocks on foot. The check walks the cell the way vanilla pathfinding does - stepping up one block, dropping down up to three;
• has a job site next to it. A villager that lost its workstation keeps its brain until it claims a new one;
• has no bed. Iron golem farms and breeders need their villagers' brains, so they are never touched;
• is an adult, awake and not in water.

Break a wall of the cell and the villager wakes up on the next tick. Put it back and it is paused again.

Players can look at any villager and run /villagerwarden check to see whether it is optimized, and if not, exactly why.

When the automation guesses wrong

No automatic rule fits every custom build. Admins can override it for the villagers around them:

• /villagerwarden optimize <radius> - always pause these villagers, even if they are not locked in. Sleeping villagers, babies and villagers in water are still left alone.
• /villagerwarden exclude <radius> - never touch these villagers.
• /villagerwarden auto <radius> - back to automatic.

The choice is stored on the villager and survives restarts. From the console or a command block, add the world and coordinates: /villagerwarden exclude 5 world 120 64 -40.

Nothing is left in your world

Pausing a mob's brain is stored in its save data. The common approach - switching the villager's AI off and leaving it that way - means that once such a plugin is removed, your hall stays frozen. VillagerWarden gives every villager its brain back before a chunk unloads and when the server stops, and pauses it again when it loads.

Verified: stop the server, remove the plugin, start again - every villager is a normal villager, with its level, trades and job site intact.

Villagers frozen by other plugins (NPCs) are never touched - VillagerWarden only ever releases the ones it paused itself.

Commands

Command	Permission	What it does
/villagerwarden check	villagerwarden.check (everyone)	Is the villager you look at optimized, and if not, why
/villagerwarden status	villagerwarden.admin	How many villagers are optimized, restocks and level-ups done
/villagerwarden optimize|exclude|auto <radius>	villagerwarden.admin	Override the automatic choice for villagers around you
/villagerwarden release	villagerwarden.admin	Release every villager and pause - before removing the plugin
/villagerwarden reload	villagerwarden.admin	Apply config changes

Alias /vw.

Configuration

enabled: true
# Worlds to work in. Empty = all worlds.
worlds: []
# A villager that can reach this many blocks or fewer counts as locked in.
max-cell-size: 6
check-interval-seconds: 10
# Restock trades for paused villagers by the vanilla rules.
restock: true
# Wake a paused villager while a player trades with it and for three seconds after.
wake-while-trading: true
# Leave villagers with beds alone - golem farms and breeders need them.
skip-villagers-with-beds: true

Every message is in the config. English and Russian - config-ru.yml lands next to your config on first start.

What changes while a villager is paused

Honesty about the trade-offs:

• It does not sleep, gossip or panic. Reputation from curing or hitting it decays more slowly.
• It does not summon iron golems - which is why villagers with beds are never paused.

Requirements

• Paper or Purpur 1.21.4 - 1.21.11 and 26.1 - 26.2 - one jar for all of them
• Java 21 or newer
• No dependencies. Not Folia-compatible yet.

Support

Bug reports are welcome and get priority over feature requests. A report with your config, /villagerwarden status and what /villagerwarden check says about the villager in question gets fixed fastest.