Performance, hubs & pregen

How NusaSpigot keeps 20.00 TPS using async I/O, adaptive mob AI, tick budgets, PvP/world tweaks, and crowded-hub networking.

On this page

NusaSpigot speeds up your server without breaking plugins by following one strict engineering rule: world, entity, and block changes always stay on the single main thread, while heavy disk I/O, compression, and snapshot math run on background worker threads.

1. Steady 20.00 TPS tick pacing

Standard Java sleep timers on Windows hosts often round idle pauses up to ~15.6 ms, making quiet local servers look like they dipped to 19.0–19.8 TPS even with zero load.

NusaSpigot keeps high-resolution timer pacing calibrated automatically on Windows and uses fine sub-millisecond pacing at the end of each 50 ms tick—waking up immediately the moment player packets or main-thread tasks arrive.

2. Storage, Entities & Adaptive AI

  • Async Chunk & Player Saves (async-chunk-io, async-playerdata-save): Disk reads, Zstd region compression, and player .dat writes happen off the main thread so saving never freezes combat.
  • Smart Hoppers (hopper-tick-spreading): Idle hoppers spread across 4 staggered tick groups and back off for 5 ticks (full-container-backoff-ticks) when pointing into a full chest, while keeping Bukkit InventoryMoveItemEvent compatibility intact.
  • Brain Distance Scaling & Sensor Cadence: Mobs like villagers, piglins, and wardens run at full speed within 12.0 blocks (brain-distance-scaling.near-radius) and scale down gradually up to 20 ticks when far away. Dolphin treasure structure lookups (dolphin-treasure-seek) default to false to prevent ocean freeze spikes.

For busy Survival SMPs with lots of mob farms, enable OPTIMIZED ticking mode and gentle sensor intervals:

hopper-tick-spreading:
  groups: 4
  full-container-backoff-ticks: 8
 
entity-behavior:
  ticking-mode: OPTIMIZED
  skip-idle-goal-ticks: true
  sensor-cadence:
    water-check-interval: 4
    equipment-sync-interval: 4
    line-of-sight-interval: 6
    player-only-pushing: true

3. Tick budgets, World & PvP mechanics

NusaSpigot includes practical gameplay and anti-lag switches right inside nusa-global.yml:

  • Tick budgets (tick-budgets.*): Caps dropped-item merge scans (150 per tick) and projectile chunk loads (10 per tick) so TNT blasts or pearl cannons cannot stall the server. Set vehicle-collision-stack-limit: 10 to automatically clear stacked boat/minecart lag traps.
  • World mechanics (world-mechanics.*): Prevents transient snowball/firework disk bloat (persist-transient-projectiles: false), lets Skyblock grinders ignore light rules (spawner-check-spawn-rules: false), groups PvP loot (compact-death-drops: true), and lets you toggle heavy particle packets.
  • PvP mechanics (pvp-mechanics.*): Optional 1.8-style sprint criticals, fishing-rod knockback, Netherite knockback-resistance bypass, Mace smash fall-distance cap (for example 30.0 blocks to stop orbital one-shot traps), and custom horizontal/vertical knockback profiles.

4. Crowded hubs & world pre-generation

  • Crowded Hub Networking (hub-networking.*): Encodes shared broadcasts once, batches rapid tab-list updates (200 ms), and updates distant players every 4 ticks while keeping active fighters at 1-tick precision (combat-priority-override.enabled: true).
  • TPS-Aware Pregen (/nusa pregen): Run nusa pregen 150 world (radius in chunks) before launch day; see World pre-generation. Generation automatically pauses if TPS drops below 18.0 or MSPT exceeds 40.0 ms, and skips chunks near online players (player-buffer-chunks: 2).
Nusa product documentation · NusaSpigotPaper fork · Java 21 / 25

Loading the index…