Compatibility
Minecraft: Java Edition
Platforms
Tags
Creators
Details
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.


