FrozenVillagers

FrozenVillagers cuts villager lag without changing how villagers play. It finds the villagers whose AI isn't doing anything useful, slows them down, and keeps trading, restocks and level ups working the vanilla way.

Why

On a busy survival server villagers are often the most expensive entities. Most of that time goes into two things:

• Searching for beds, jobs and bells they can't get. A villager without one looks for it every 1 to 2 seconds, forever. In a breeder's storage or a crowded village almost every search fails.
• The brain of villagers that can't move, like the ones locked in trading hall cells.

Turning the AI off fixes the cost but breaks the game: villagers stop restocking and levelling up, and if the wrong ones are frozen, iron farms stop making golems and breeders stop breeding. FrozenVillagers only touches the villagers that don't need their AI.

What it does

	Who	What changes
Trapped villagers	Locked in a 1x1 cell or a vehicle, with a job, traded at least once, no bed	Nothing visible: they couldn't move anyway
Surplus villagers	Jobless villagers without a bed, packed in a crowd	They move in short bursts
Staff freeze	Any villager staff picks with /fv freeze	It stands still
Birth limit (off by default)	Breeders with too much surplus around them	No new babies until it goes down

For every villager the plugin handles:

• trading works as usual, with the same prices, discounts and reputation
• restocks happen at fixed times of day (07:00, 12:00 and 17:00 by default) when a player opens the trades
• level ups happen the vanilla way, with the new trades
• gravity, water, damage, zombie conversion and curing keep working
• a hurt villager, a raid nearby, or a bed or workstation placed nearby gives it its full AI back right away

What it never does:

• make villagers invincible, or hide them from zombies
• remove a villager
• touch, on its own, iron farms, villages, babies, villagers that never traded (so rerolling works), NPCs, or villagers another plugin changed

Results

Measured on Paper 26.2, average tick time over a full Minecraft day:

1,146 villagers, like a busy survival server	MSPT
Without the plugin	50.7 ms
FrozenVillagers, default config	18.6 ms (-63%)
Trading halls frozen by staff	13.4 ms (-74%)

Stress test with 4,000 villagers and a player online:

	MSPT	TPS
Without optimizations	208 ms	4.8
FrozenVillagers, automatic	88 ms	11.3
Plus the free villagers frozen by staff	33 ms	20
Everything frozen by staff	7.2 ms	20

The plugin itself costs about 0.1 to 0.25 ms per tick. /fv status shows it live.

Commands

All commands need frozenvillagers.admin (op by default).

Command	What it does
/fv freeze [radius|selector]	Freezes villagers
/fv unfreeze [radius|selector]	Gives them their AI back and excludes them from the automatic features
/fv auto [radius|selector]	Puts them back to automatic
/fv adopt [radius|selector]	Takes over villagers another optimizer plugin froze
/fv inspect [selector]	Shows what the plugin does with a villager and why
/fv status	Counts the villagers and shows the plugin's own cost
/fv reload	Reloads the config

Configuration

The defaults work out of the box. The options you are most likely to change:

Option	Default	What it does
restock.times	[1000, 6000, 11000]	Restock windows in day time: 07:00, 12:00 and 17:00
restock.mode	reset-uses	reset-uses keeps prices as they are, vanilla lets demand raise them
restock.require-workstation	false	Only restock villagers whose workstation is still next to them
surplus.crowd	12	How many jobless villagers without a bed make a crowd
births.enabled	false	Stop breeding when there is too much surplus around the breeder
freeze.disable-physics	false	Also turn off physics for villagers frozen by staff
migration.adopt-other-optimizers	false	Adopt villagers from BubbleVillagers and similar plugins as they load
worlds	[]	Worlds for the automatic features, empty means all

The full config.yml

# FrozenVillagers. Every option is explained in the README.

# Worlds where the automatic optimizations run. An empty list means all
# worlds. Villagers frozen by staff with /fv freeze stay frozen everywhere.
worlds: []

# How often, in ticks, each villager is checked again. The checks are spread
# over these ticks, so they never all happen at once. 100 = 5 seconds.
check-interval: 100

# For switching from BubbleVillagers, VillagerOptimizer or AntiVillagerLag.
# With true, every villager those plugins optimized is adopted on its own
# when its chunk loads, like /fv adopt does. Villagers whose AI any other
# plugin turned off are still left alone. Turn it off again once
# /fv status shows no villagers without AI because of another plugin.
migration:
  adopt-other-optimizers: false

# /fv freeze, for staff.
freeze:
  # Frozen villagers always have their AI, item pickup and pushing turned
  # off. With true their physics are off too: they no longer fall or get
  # pushed by water. Saves a bit more, but only use it for villagers that
  # stand on solid ground.
  disable-physics: false
  # The largest radius allowed in /fv freeze, unfreeze, auto and adopt.
  max-command-radius: 32

# Villagers the plugin slows down get their AI back for "active" ticks
# every "cycle" ticks, and have it off the rest of the time. The default is
# 1 second every 10 seconds.
pulse:
  cycle: 200
  active: 20

# Villagers that can't move and have nothing to look for, except a bed they
# can never reach: locked in a 1x1 cell or in a vehicle, with a profession,
# traded at least once, without a bed. They are slowed down. Since they
# can't move anyway, players don't see any difference.
trapped:
  enabled: true

# Surplus villagers: adults with no profession (or nitwits) that have had no
# bed for a while, packed together with many others like them. This is what
# piles up next to a breeder. They are slowed down until they find a bed or
# a job, or the crowd shrinks. Iron farm villagers always have a bed, so they
# are never touched.
surplus:
  enabled: true
  # How many villagers without a bed and a job there must be in the 3x3
  # chunks around a villager for it to count as surplus.
  crowd: 12
  # Ticks without a bed before a villager can count as surplus. 6000 = 5 minutes.
  grace: 6000
  # Turn off pushing between surplus villagers. Saves work in big crowds, but
  # entity cramming no longer kills them, so a crowd can grow without limit.
  disable-collisions: false

# Stops breeding when there is too much surplus around the parents, even if
# it is stored in other chunks. No villager is ever removed.
births:
  enabled: false
  # Villagers without a bed and a job (babies included) allowed within
  # "radius" blocks of the parents before babies stop being born.
  max-surplus: 24
  radius: 64

# Villagers frozen or slowed down by the plugin can't walk to their
# workstation, so they restock when a player opens their trades, once per
# window below. Day times: 0 = 06:00, 1000 = 07:00, 6000 = 12:00, 11000 = 17:00.
restock:
  enabled: true
  times: [1000, 6000, 11000]
  # reset-uses: trades are refilled and prices don't go up with demand.
  # vanilla: the vanilla restock, prices go up a bit for trades used a lot.
  mode: reset-uses
  # Only restock villagers whose workstation is still there and close to them.
  require-workstation: false
  # Max distance in blocks from the villager's feet to its workstation.
  workstation-reach: 2.5
  # Sent to the player when a villager restocks. Empty sends nothing.
  # MiniMessage format, %next% is the time until the next restock.
  message: ""

Run /fv reload after changing it. Bad values are reported in the console and replaced by the defaults.

Switching from BubbleVillagers or VillagerOptimizer

Install FrozenVillagers, run /fv adopt (or turn on migration.adopt-other-optimizers to adopt villagers as their chunks load), then remove the old plugin. Tested with 4,000 villagers. Back up your world first. The full steps are in the README.

Requirements

• Paper 26.2
• Java 25

Every option, how each feature works and how it was tested are in the README.