![[IMG]](https://i.imgur.com/xIvssNP.png "[IMG]")
There are currently 11 modules.
Key functions:
Prevents Villager OverloadSmarter AI scheduling and focus-based simulation!
In-game setup: (Identical for both)
~450 villagers in one chunk
~150 villagers assigned jobs
Without ServerOptimizer:
![[IMG]](https://i.imgur.com/8427Ylf.png "[IMG]")
With ServerOptimizer:
![[IMG]](https://i.imgur.com/81xPheL.png "[IMG]")
Chunk-Aware PerformanceSoft-preloads and async I/O handling to prevent spikes.
Entity Logic SimplifiedReduce brain ticks and idle entity waste.
AFK-Friendly OptimizationDynamic render distance control for idle players.
Fully Configurable ModulesTurn features on/off instantly from an in-game GUI.
Spark-Tested ImprovementsReal, measurable TPS gains across SMP environments.
Modules »
| Module | Description |
| AFK Render Distance | Automatically reduces render distance and simulation range for AFK players to free up server resources while keeping active players unaffected. |
| Mob Optimizer | Parks mobs outside player range to reduce AI usage, merges dropped items, culls excess projectiles and XP orbs, and prevents entity lag buildup. |
| Villager Governor | Smartly manages villager AI and trade restocking to reduce lag — only activates villagers near players and applies restock/career change cooldowns. |
| Packet Throttler | Reduces unnecessary packet spam for AFK or distant players, lowering network load and improving TPS stability. |
| TPS Reactive Scaling | Automatically scales optimization aggressiveness based on current TPS — the lower the TPS, the stronger the performance boost applied. |
| Hopper Redstone Optimizer | Intelligently throttles hopper and redstone activity during lag spikes while maintaining gameplay functionality. |
| Frames & Maps Manager | Controls item frame and map updates to prevent performance drops from excessive block updates or rendering. |
| Entity Budgets | Sets per-chunk entity limits and automatically manages excess to prevent mob overpopulation and lag spikes. |
| Explosions Optimizer | Reduces lag from large explosions by limiting block calculations or using async logic where possible. |
| Chunk IO Manager | Warns about excessive synchronous chunk loads, rate-limits them, and softly preloads nearby chunks to avoid lag spikes during player movement. |
| Spawn Density Controller | Adjusts mob spawning density dynamically to maintain stable performance during heavy load. |
Files »
YAML:
################################################################################
# Server Optimizer #
# Safe, async-first, Paper-only optimization #
# Modules included:
# - AFK Render Distance (per-player view distance)
# - Packet Throttler (ProtocolLib optional)
# - Mob Optimizer (AI duty-cycler, parking, cleanup)
# - Villager Governor (workstation/brain/trades control)
# - TPS-Reactive Governor (auto-tune under load)
# - Hopper & Redstone Pacifier (tile-entity + clock taming)
# - Map & Item Frame Dampener (render/update throttles)
# - Projectiles & Orbs Budget (entity storms protection)
# - Explosion & TNT Tamer (stagger & cap)
# - Chunk I/O Smoother (sync-load watch + soft-preload)
# - Spawn Density Controller (prevent cap herding)
################################################################################
config-version: 1
enabled: true
################################################################################
# GLOBAL MESSAGING & DEBUG
################################################################################
messaging:
enabled: true
prefix: "&8[&bServerOpt&8]&r "
send-to-player: true # Show player-facing nudges (AFK/ACTIVE, etc.)
notify-admins: false # Staff receive change notifications
admin-permission: "serveropt.notify"
messages:
became-afk: "&7Lowered your view distance to &b%new%&7 (AFK)."
returned-active: "&7Restored your view distance to &a%new%&7."
using-essx: "&7Using &bEssentialsX&7 AFK status for you."
status-format: "&b%player%&7 → &f%state%&7 | vd=&f%new%&7 | idle=&f%idle%s&7"
reloaded: "&bServerOptimizer &7config reloaded."
no-permission: "&cYou lack permission."
player-not-found: "&cPlayer not found."
only-players: "&cThis command can only be used in-game."
unknown-module: "&cUnknown module: &f%module%&c."
already-enabled: "&e%module% &7is already enabled."
already-disabled: "&e%module% &7is already disabled."
enabled-ok: "&aEnabled &f%module%&a."
disabled-ok: "&cDisabled &f%module%&c."
toggle-failed: "&cFailed to toggle &f%module%&c. See console."
list-header: "&bServerOptimizer &7modules:"
list-line: "&7- %module%: %state%"
gui-opened: "&7Opening modules GUI..."
version-line: "&bServerOptimizer&7 v%version% &8| &7Server: %impl% &8| &7Bukkit: %bukkit% &8| &7Java: %java%"
usage: "&7Usage: /serveropt (reload|status [player]|modules|list|enable <module>|disable <module>|toggle <module>|version)"
debug:
verbose: false # Extra logs (enable temporarily when tuning)
log-applies: true # Log when we change view distance / AI / throttles
################################################################################
# MODULE: AFK RENDER DISTANCE
################################################################################
afk-render-distance:
enabled: true # Master switch for the AFK Render Distance module.
use-essentialsx-afk: true # If EssentialsX is installed, trust its AFK flag.
# If false (or EssentialsX missing), use the internal idle timer below.
afk-after-seconds: 300 # Idle time (seconds) before a player is considered AFK (when not using EssentialsX).
check-period-ticks: 100 # How often to evaluate AFK state & apply VD (ticks; 20 = 1s). 100 = every 5s.
hysteresis-seconds: 10 # Anti-flap buffer: requires this many seconds across the AFK threshold to switch states.
activity-events: # What counts as “activity” for the internal AFK timer.
movement: true # Block-to-block movement.
rotation: false # Yaw/pitch changes (micro-aim adjustments).
chat: true # Player sends chat message.
command: true # Player runs a command.
interact: true # Player interacts (clicks) with world/entities.
inventory: true # Player clicks inside an inventory.
ignore:
gamemodes: [SPECTATOR] # Players in these gamemodes are never AFK-throttled.
worlds-exclude: [] # World names to exclude entirely from AFK throttling.
permissions-bypass: ["serveropt.bypass"] # Players with any of these perms are never AFK-throttled.
view-distance:
min-distance: 2 # Never set below this VD for safety/visibility.
max-distance: 32 # Never set above this VD even if configured per-world.
cap-to-server-view-distance: true # Also cap to the server’s global view-distance if true.
active-view-distance: -1 # When ACTIVE, set VD to this value; -1 = keep player’s current/original.
afk-view-distance: 4 # When AFK, set VD to this value (safe noticeable reduction).
adaptive-afk: # Optional: gradually lower AFK VD the longer someone stays AFK.
enabled: false # Turn on to use the steps below.
stickiness-seconds: 10 # Minimum time between adaptive changes to avoid rapid oscillation.
steps: [] # Timed levels while AFK (uses the minimum of step VD vs. base AFK VD).
# Example:
# - after-seconds: 300
# view-distance: 6
# - after-seconds: 600
# view-distance: 4
# Per-world overrides (add your worlds under this section).
# Tip: copy the "world" block and rename to your world names.
world-overrides:
world:
active-view-distance: -1 # Override only for "world" (ACTIVE).
afk-view-distance: 4 # Override only for "world" (AFK).
################################################################################
# MODULE: PACKET THROTTLER (ProtocolLib required; auto-disables if missing)
################################################################################
packet-throttler:
enabled: true # Master switch for the Packet Throttler module.
# Requires ProtocolLib; will auto-disable if ProtocolLib is missing.
coalesce-window-ms: 60 # Global “dedupe” window: identical packets to the same player within'
# this time are merged into one (helps with spammy updates).
packets: # Fine-grained per-packet-type throttles.
ENTITY_EQUIPMENT: { enabled: true, window-ms: 80 } # Armor/tools rapidly changing (e.g., armories/minigames).
ENTITY_METADATA: { enabled: true, window-ms: 80 } # General entity data changes; safe to coalesce modestly.
ENTITY_VELOCITY: { enabled: true, window-ms: 50 } # Knockback/velocity bursts; tight window preserves feel.
ANIMATION: { enabled: true, window-ms: 80 } # Swing/bed/etc. animations; dedupe reduces noise.
ENTITY_HEAD_ROTATION: { enabled: false, window-ms: 50 } # Turn on if head-rotation spam is heavy.
REL_ENTITY_MOVE: { enabled: false, window-ms: 50 } # Movement deltas; keep off unless truly necessary.
REL_ENTITY_MOVE_LOOK: { enabled: false, window-ms: 50 } # Movement+look; same guidance as above.
ENTITY_LOOK: { enabled: false, window-ms: 50 } # Look-only updates; enable if you’re desperate.
NAMED_ENTITY_SPAWN: { enabled: false, window-ms: 0 } # Spawns: usually don’t throttle.
SPAWN_ENTITY: { enabled: false, window-ms: 0 } # Generic spawns: usually don’t throttle.
budgets:
enabled: false # Hard budget on throttled packets per player per second.
per-player-per-second: 400 # If enabled, clamps bursty clients (e.g., modded or lagging) to this rate.
bypass:
near-players-radius: 28 # Inside this radius, skip throttling critical packets
when-combat: true # Skip throttling for engaged entities (took dmg / has target)
entity-whitelist: [SKELETON] # Never throttle critical packets for these types
critical-packets:
- ENTITY_EQUIPMENT
- ENTITY_METADATA
- ANIMATION
################################################################################
# MODULE: MOB OPTIMIZER (AI duty-cycler, parking, cleanup)
################################################################################
mob-optimizer:
enabled: true # Master switch for the Mob Optimizer module.
scan-period-ticks: 100 # How often to scan mobs per world/chunk (ticks; 20 = 1s).
# NOTE: Runs on the main thread for safety with entity/chunk APIs.
wake-radius: 18 # If a player is within this distance, nearby mobs are fully "awake".
parking: # Settings for pausing mobs when no players are close.
enabled: true # If true, eligible mobs are parked (AI off / slowed) to save CPU.
respect-activation-range: true # If true, keeps mobs awake when the server would normally activate them.
whitelist: # Only these entity types can be parked/duty-cycled.
[ZOMBIE, SKELETON, CREEPER, SPIDER, VILLAGER, WITCH, ENDERMAN]
duty: # Per-entity-type duty-cycling (short active bursts, then rest).
VILLAGER:
enabled: true # Use bursts for this type (pairs well with Villager Governor).
interval-ticks: 100 # How often to grant a short “active” window to parked villagers.
burst-ticks: 8 # Length of each active window (ticks).
reduce-movement-speed: true # While parked, lower movement speed instead of full pause (less jarring).
speed-multiplier: 0.60 # Movement scale when parked (1.0 = normal, 0.6 = 40% slower).
ZOMBIE: { enabled: true, interval-ticks: 60, burst-ticks: 4, reduce-movement-speed: true, speed-multiplier: 0.75 }
SKELETON: { enabled: true, interval-ticks: 60, burst-ticks: 4, reduce-movement-speed: true, speed-multiplier: 0.75 }
CREEPER: { enabled: true, interval-ticks: 60, burst-ticks: 3, reduce-movement-speed: true, speed-multiplier: 0.70 }
SPIDER: { enabled: true, interval-ticks: 60, burst-ticks: 4, reduce-movement-speed: true, speed-multiplier: 0.75 }
# Tip: Higher interval / lower burst = more savings; invert for smoother feel.
cleanup: # Lightweight entity cleanup to prevent “storms” of small entities.
merge-items: true # Merge nearby identical item stacks to reduce entity count.
item-merge-radius: 1.5 # Max distance (blocks) to merge items together.
cull-xp-orbs: true # Remove very old XP orbs (players rarely need long-lived orbs).
xp-orb-max-age-seconds: 120 # XP orbs older than this are removed (seconds).
cull-projectiles: true # Remove very old arrows/snowballs/tridents, etc.
projectile-max-age-seconds: 60 # Projectiles older than this are removed (seconds).
engagement:
recent-damage-seconds: 5 # Treat mobs as engaged for this long after being hurt
recent-target-seconds: 5 # Treat mobs as engaged for this long after acquiring a target
los-radius: 24 # If a player has LoS within this radius, consider mob engaged/visible
parking:
soft-park-near-players: true # Near players: prefer slow-walk over AI-off
soft-park-speed-multiplier: 0.25 # Movement when soft-parked (AI on, very slow)
hard-park-distance-multiplier: 2 # > (wake-radius * multiplier) away → allow AI-off
################################################################################
# MODULE: VILLAGER GOVERNOR (workstation / brain / trades control)
################################################################################
villager-governor:
enabled: true # Enables or disables the Villager Governor module entirely.
wake-radius: 22.0 # How close a player must be before villagers "wake up" and start working again.
max-active-per-chunk: 10 # Maximum number of villagers allowed to be fully active in a single chunk at once.
min-active-per-chunk: 2 # Minimum number of villagers that will always remain active when players are nearby.
duty: # Controls how villagers alternate between active (working) and parked (paused) states.
interval-ticks: 80 # How often the system rotates which villagers are active (in ticks, 20 = 1 second).
burst-ticks: 10 # How long each active villager stays awake and working per cycle.
buckets: 20 # Number of groups ("buckets") villagers are divided into for time-rotation fairness.
reduce-movement-speed: false # If true, parked villagers move slower instead of being fully paused (safer visually).
speed-multiplier: 0.85 # How much slower parked villagers move (only applies if reduce-movement-speed = true).
grace-seconds: 30 # If a villager stays parked this long near players, they’ll automatically wake up.
restock: # Controls how villager trade restocking is throttled.
enabled: true # Enables throttling of villager restock events.
min-interval-seconds: 120 # Minimum time between restocks per villager (prevents spam).
block-when-no-player-near: true # Prevent restocks if no players are nearby (saves performance).
career: # Controls how often villagers can change or pick up new professions.
enabled: true # Enables throttling of career changes.
cooldown-seconds: 30 # Minimum time between career changes for the same villager.
deny-when-no-player-near: true # Prevent career changes when no players are nearby.
global-max-per-minute: 60 # Global cap on how many career changes can occur across the server per minute.
daytime:
keep-awake: true # If true, do not park villagers during the day’s first moments (see grace).
wake-at-dawn-grace-ticks: 200 # ~10s after sunrise (200 ticks) where we always wake + avoid parking.
never-park-when-sleeping: true # If a villager is sleeping and it’s daytime, force wake + never park that tick.
################################################################################
# TPS-REACTIVE GOVERNOR (auto-tighten when TPS/MSPT is bad)
################################################################################
tps-reactive:
enabled: true # Master switch: dynamically tightens settings when TPS dips.
sample-window-seconds: 20 # Average TPS over this window before deciding actions (smoother = larger).
thresholds:
warn-tps: 19.0 # When avg TPS < this → apply "light" actions below.
hard-tps: 17.0 # When avg TPS < this → apply stronger "hard" actions below.
actions:
# Light measures when TPS < warn-tps (mild, barely noticeable to players)
light:
afk-render-distance:
extra-afk-drop: 1 # AFK VD = config AFK VD minus this value (e.g., 4 → 3).
mob-optimizer:
shorten-bursts-by: 1 # Reduce burst-ticks by N (shorter active windows = less CPU).
cleanup:
xp-orb-max-age-seconds: 90 # Orbs older than this are culled (tighter than base config).
projectile-max-age-seconds: 45 # Projectiles older than this are culled (tighter than base config).
# Hard measures when TPS < hard-tps (aggressive—prioritize server health)
hard:
afk-render-distance:
extra-afk-drop: 2 # Push AFK VD even lower under heavy load.
mob-optimizer:
shorten-bursts-by: 2 # Much shorter bursts → big CPU savings.
villager-governor:
max-active-per-chunk: 4 # Fewer active villagers per chunk during stress.
spawn-density:
world-cap-multiplier: 0.85 # Scales hostile caps (e.g., 85% of normal) for spawn control.
################################################################################
# HOPPER & REDSTONE PACIFIER (reduce TE churn & clock spam)
################################################################################
hopper-redstone:
enabled: true # Master switch for hopper timing + redstone debouncing.
hoppers:
check-interval-ticks: 16 # Hopper tick rate (vanilla 8). Higher = fewer checks, lower CPU, slower flow.
max-per-chunk: 120 # Soft budget: above this, extra hoppers are deprioritized/slow-ticked.
redstone:
debounce-ticks: 2 # Suppress pulses faster than this (kills ultra-fast flicker clocks).
observer-cooldown-ticks: 4 # Adds cooldown to observers (prevents massive observer chains from spiking).
################################################################################
# MAP & ITEM FRAME DAMPENER (render/update throttles)
################################################################################
frames-maps:
enabled: true # Master switch for throttling item frames and map rendering.
item-frames:
max-per-chunk: 80 # If a chunk exceeds this many frames, frame updates are throttled.
rotation-cooldown-ticks: 2 # Minimum ticks between rotation updates (prevents rapid spam).
maps:
max-renders-per-second: 150 # Global render budget for maps (keeps heavy map art in check).
per-player-per-second: 30 # Per-player render budget (prevents one player from hogging renders).
################################################################################
# PROJECTILES & ORBS BUDGETS
################################################################################
entity-budgets:
enabled: true # Master switch for entity-per-chunk budgets and aging rules.
per-chunk: # Hard-ish caps per chunk; excess gets culled or delayed.
arrows: 64
tridents: 16
snowballs: 64
xp-orbs: 200
aging: # Remove very old entities to prevent buildup.
arrow-max-age-seconds: 120 # Remove arrows older than this.
trident-max-age-seconds: 180 # Remove tridents older than this (thrown & stuck ones).
advanced:
exempt-near-players: true # If players are within exempt-radius, do nothing.
exempt-radius: 16.0 # Distance for the exemption.
recent-launch-exempt-seconds: 5 # Never cull projectiles within N seconds of launch.
burst-tick-allowance: 4 # Allow this many launches per chunk per tick before checking caps.
merge-xp-orbs: true # Gently merge nearby older XP orbs to reduce entity count.
xp-merge-radius: 1.25 # Merge distance for orbs.
xp-min-age-to-merge-seconds: 4 # Don’t merge very fresh orbs.
xp-min-age-to-count-seconds: 2 # Fresh orbs don’t count against per-chunk cap (pickup grace).
only-cull-stationary: true # Aging removes only stationary (stuck) projectiles.
sweep-period-ticks: 200 # How often to run the merge/aging sweep.
max-entity-checks-per-tick: 2000 # Safety budget for sweep work per run.
################################################################################
# EXPLOSION & TNT TAMER (stagger/cap explosions)
################################################################################
explosions:
enabled: true # Master switch for staggering/capping explosions.
max-concurrent-per-chunk: 8 # If more than this explode in the same chunk simultaneously,
# queue/roll some into next tick to flatten spikes.
tnt:
chain-delay-ticks: 1 # Insert a tick between chained TNT updates (smoother blasts).
max-per-tick-global: 200 # Hard global cap per tick (prevents TNT storms from freezing the server).
################################################################################
# CHUNK I/O SMOOTHER (sync load watch + soft-preload)
################################################################################
chunk-io:
enabled: true # Master switch for monitoring + smoothing chunk loads.
warn-on-sync-load: false # Log when plugins force synchronous chunk loads (noisy; helpful when tuning).
rate-limit-sync-loads: true # Smooth bursts of sync loads by queuing across ticks.
max-sync-loads-per-tick: 20 # Ceiling for sync loads per tick (when smoothing is enabled).
soft-preload:
enabled: true
radius: 2 # Preload a small ring of chunks around a target (teleports/warps)
# to reduce hitching when a player lands.
################################################################################
# SPAWN DENSITY CONTROLLER (avoid cap herding)
################################################################################
spawn-density:
enabled: true # Master switch for scaling natural mob caps per world.
worlds:
world:
scale-hostile-cap: 1.00 # 1.0 = vanilla hostile cap; <1 lowers density slightly (e.g., 0.9).
scale-passive-cap: 1.00 # 1.0 = vanilla passive cap; <1 lowers density slightly.
player-proximity-boost: false # If true, allow a small boost near scattered players
# (keeps the world feeling alive without swarms).
################################################################################
# MODULE GUI (toggle each module individually in-game)
################################################################################
gui:
modules:
title: "&bServerOptimizer &fModules"
rows: 4
items:
afk-render-distance:
slot: 10
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aAFK Render Distance &7[ON]"
name-off: "&cAFK Render Distance &7[OFF]"
lore:
- "&7Per-player VD while AFK."
- "&7Click to toggle."
packet-throttler:
slot: 11
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aPacket Throttler &7[ON]"
name-off: "&cPacket Throttler &7[OFF]"
lore:
- "&7Coalesce duplicate packets."
- "&7Click to toggle."
mob-optimizer:
slot: 12
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aMob Optimizer &7[ON]"
name-off: "&cMob Optimizer &7[OFF]"
lore: ["&7AI duty-cycle, cleanup.", "&7Click to toggle."]
villager-governor:
slot: 13
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aVillager Governor &7[ON]"
name-off: "&cVillager Governor &7[OFF]"
lore: ["&7Workstation/brain throttles.", "&7Click to toggle."]
tps-reactive:
slot: 14
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aTPS Reactive &7[ON]"
name-off: "&cTPS Reactive &7[OFF]"
lore: ["&7Auto-tighten under load.", "&7Click to toggle."]
hopper-redstone:
slot: 15
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aHopper/Redstone &7[ON]"
name-off: "&cHopper/Redstone &7[OFF]"
lore: ["&7Debounce & cooldown.", "&7Click to toggle."]
frames-maps:
slot: 16
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aFrames & Maps &7[ON]"
name-off: "&cFrames & Maps &7[OFF]"
lore: ["&7Throttle renders/updates.", "&7Click to toggle."]
entity-budgets:
slot: 19
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aEntity Budgets &7[ON]"
name-off: "&cEntity Budgets &7[OFF]"
lore: ["&7Chunk caps & aging.", "&7Click to toggle."]
explosions:
slot: 20
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aExplosions &7[ON]"
name-off: "&cExplosions &7[OFF]"
lore: ["&7Stagger/cap TNT.", "&7Click to toggle."]
chunk-io:
slot: 21
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aChunk I/O &7[ON]"
name-off: "&cChunk I/O &7[OFF]"
lore: ["&7Watch sync loads.", "&7Click to toggle."]
spawn-density:
slot: 22
material-on: "LIME_DYE"
material-off: "GRAY_DYE"
name-on: "&aSpawn Density &7[ON]"
name-off: "&cSpawn Density &7[OFF]"
lore: ["&7Scale per-world caps.", "&7Click to toggle."]Commands »
| Command | Description | Permission |
| Code (Text): /serveropt reload | Reloads the plugin configuration and restarts all modules. | Code (Text): serveropt.admin |
| Code (Text): /serveropt status [player] | Displays optimization status for a specific player (or yourself if no player is specified). | Code (Text): serveropt.admin |
| Code (Text): /serveropt modules | Opens the modules GUI, allowing toggling individual optimization modules on/off. | Code (Text): serveropt.modules |
Permissions »
| Permission | Description | Default |
| Code (Text): serveropt.admin | Access to all Code (Text): /serveropt admin commands. | op |
| Code (Text): serveropt.bypass | Player is never AFK-throttled by the AFK Render Distance system. | op |
| Code (Text): serveropt.notify | Receives admin notifications when optimization actions are applied (e.g. AI throttling, villager management). | op |
| Code (Text): serveropt.modules | Allows the player to open and toggle modules using the in-game Modules GUI. | op |
