All settings reference
Complete searchable reference of every setting, default value, and allowed range in nusa-global.yml.
On this page
- Quick key index
- Feature flags (feature-flags.)
- Bedrock & Geyser (bedrock-optimization.)
- Entities, hoppers & AI (entity-behavior., hopper-tick-spreading.)
- Tick budgets, world & PvP (tick-budgets., world-mechanics., pvp-mechanics.)
- Storage & async I/O (async-chunk-io., region-file-compression., async-playerdata-save.)
- Network & crowded hubs (hub-networking., combat-priority-override., networking.)
- World pre-generation (pre-generation.)
- Security guards (security.)
- Dashboard & Discord alerts (management.)
Use Ctrl K (or the search bar at the top) to jump straight to any setting, or browse by category below. Every key listed here lives in nusa-global.yml and takes effect after a full server restart.
Quick key index
176 configuration options available in nusa-global.yml. Select any key to jump to its explanation below.
Feature flags (feature-flags.*)
Master switches that turn NusaSpigot modules on or off globally.
All options below belong in nusa-global.yml and require a full server restart. Missing keys automatically use the default value.
| Complete key | Type / default | Range / unit | What it does & when it applies |
|---|---|---|---|
feature-flags.async-chunk-io | booleantrue | true / false | Offload physical region chunk reads and writes to dedicated I/O worker threads so disk activity does not stall the main thread.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.region-file-compression | booleantrue | true / false | Compress newly written region sectors with Zstandard (zstd) to save disk space. Turn this off before migrating back to plain Paper.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.async-playerdata-save | booleantrue | true / false | Write detached player NBT save snapshots on background I/O workers instead of blocking the main tick.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.ai-precompute-queue | booleantrue | true / false | Precompute mob target candidates on background snapshots while keeping final AI, events, and movement on the main thread.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.entity-tracking-culling | booleantrue | true / false | Hide entity packets behind solid walls using worker raycasts to save player bandwidth and client FPS.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.hopper-tick-spreading | booleantrue | true / false | Spread idle hopper checks across staggered tick groups so large storage rooms do not spike a single tick.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.entity-behavior-switches | booleantrue | true / false | Master switch for mob behavior toggles, HUB preset overrides, Brain distance scaling, and sensor cadence.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.nbt-packet-validation | booleantrue | true / false | Inspect incoming NBT payload size and depth at the network decoder stage before allocating server objects.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.crash-pattern-guard | booleantrue | true / false | Block oversized custom payloads and configured literal exploit channel patterns.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.packet-flood-detection | booleantrue | true / false | Rate-limit excessive incoming packets per second from any single player connection.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.tick-starvation-guard | booleantrue | true / false | Cap how much main-thread time and packet count one player can consume in a single tick.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.redstone-abuse-limiter | booleantrue | true / false | Defer extreme redstone neighbor updates per chunk so redstone lag machines cannot freeze TPS.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.miscellaneous-security | booleantrue | true / false | Enable placed-block raw NBT filtering and rate-limiting for recognized World Downloader requests.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.netty-native-transport | booleantrue | true / false | Prefer native OS network transport (such as Linux epoll) whenever supported by the host.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.chunk-compression-batching | booleantrue | true / false | Group outbound chunk packets into short batches for cleaner compression and socket flushes.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.netty-tuning | booleantrue | true / false | Apply low-latency socket tuning (flush consolidation, IP_TOS, and TCP FastOpen).Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.pre-generation | booleantrue | true / false | Enable the TPS-aware background world pre-generation engine (/nusa pregen).Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.shared-packet-encoding | booleantrue | true / false | Encode eligible broadcast packets once and share the buffer across recipients.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.tiered-entity-updates | booleantrue | true / false | Send distant player movement updates less frequently in crowded lobbies while keeping nearby players smooth.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.batch-tab-list | booleantrue | true / false | Combine rapid numeric tab-list updates into short batch windows.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.pooled-broadcast-buffers | booleantrue | true / false | Reuse pooled direct Netty buffers for multi-recipient broadcasts.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.tuning-wizard | booleantrue | true / false | Enable the /nusa setup configuration guide and Cloud Panel pointer.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.live-dashboard | booleantrue | true / false | Enable live telemetry for /nusa status and the in-game /nusa gui panel.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
feature-flags.discord-webhook | booleanfalse | true / false | Send sustained low-TPS or security summaries to a private Discord webhook URL.Applies when: startup; bypassed temporarily during /nusa safemode on (except management) |
Bedrock & Geyser (bedrock-optimization.*)
Automatic Floodgate/Geyser detection, stair/slab setback multipliers, mobile particle caps, and chunk pacing.
All options below belong in nusa-global.yml and require a full server restart. Missing keys automatically use the default value.
| Complete key | Type / default | Range / unit | What it does & when it applies |
|---|---|---|---|
bedrock-optimization.enabled | booleantrue | true / false | Master switch for movement setback leniency, particle caps, and smooth chunk pacing for Bedrock (Geyser/Floodgate) players.Applies when: startup |
bedrock-optimization.detect-floodgate-uuid | booleantrue | true / false | Automatically identify Bedrock players via Floodgate XUID UUIDs (most-significant bits == 0).Applies when: bedrock-optimization.enabled |
bedrock-optimization.detect-geyser-brand | booleantrue | true / false | Automatically identify Bedrock players via the Geyser client brand payload.Applies when: bedrock-optimization.enabled |
bedrock-optimization.username-prefix | string. | 0..16 printable ASCII chars | Fallback Floodgate username prefix for Bedrock detection (set empty string to disable prefix matching).Applies when: bedrock-optimization.enabled |
bedrock-optimization.moved-wrongly-multiplier | number2.5 | 1..16 x | Multiply Spigot moved-wrongly threshold for Bedrock players to stop rubberbanding on stairs, slabs, and carpets.Applies when: bedrock-optimization.enabled |
bedrock-optimization.moved-too-quickly-multiplier | number1.5 | 1..10 x | Multiply Spigot moved-too-quickly threshold for Bedrock players to tolerate mobile RakNet jitter.Applies when: bedrock-optimization.enabled |
bedrock-optimization.extra-floating-tolerance-ticks | integer40 | 0..400 tick | Extra floating ticks allowed before kick checks when Bedrock players stand on partial block edges.Applies when: bedrock-optimization.enabled |
bedrock-optimization.near-distance | number6 | >0..4096 blocks | Radius in blocks within which Bedrock viewers always receive every-tick entity movement updates.Applies when: bedrock-optimization.enabled |
bedrock-optimization.far-entity-update-interval | integer6 | 1..20 tick | Tick interval for distant entity updates sent to Bedrock viewers to lower Geyser and mobile CPU load.Applies when: bedrock-optimization.enabled |
bedrock-optimization.cull-micro-rotation-updates | booleantrue | true / false | Skip tiny head-only rotations (< 5.6 degrees) for distant entities viewed by Bedrock players.Applies when: bedrock-optimization.enabled |
bedrock-optimization.max-particles-per-packet | integer16 | 1..1024 particles | Cap particles per packet sent to Bedrock players to prevent mobile GPU frame drops.Applies when: bedrock-optimization.enabled |
bedrock-optimization.max-particle-distance | number24 | >0..512 blocks | Maximum distance in blocks at which ordinary particles are sent to Bedrock players.Applies when: bedrock-optimization.enabled |
bedrock-optimization.max-chunks-per-tick | number2 | 0.25..64 chunk/tick | Maximum chunks sent per tick to each Bedrock player so Geyser chunk translation stays smooth.Applies when: bedrock-optimization.enabled |
bedrock-optimization.tab-window-millis | integer400 | 50..2000 ms | Tab-list coalescing window in milliseconds for Bedrock players to prevent mobile UI stutter.Applies when: bedrock-optimization.enabled |
Entities, hoppers & AI (entity-behavior.*, hopper-tick-spreading.*)
Worker queues, hopper backoff, DEFAULT/HUB preset, distant mob goal throttling, Brain distance scaling, and sensor cadence.
All options below belong in nusa-global.yml and require a full server restart. Missing keys automatically use the default value.
| Complete key | Type / default | Range / unit | What it does & when it applies |
|---|---|---|---|
ai-precompute-queue.threads | integer0 | 0..256 threads | Background target-precompute worker threads (0 = automatic up to 4 threads).Applies when: feature-flags.ai-precompute-queue |
ai-precompute-queue.max-queued | integer256 | 1..65536 jobs | Maximum target queries queued per tick before seamlessly falling back to vanilla selection.Applies when: feature-flags.ai-precompute-queue |
entity-tracking-culling.threads | integer0 | 0..256 threads | Background occlusion raycast worker threads (0 = automatic up to 4 threads).Applies when: feature-flags.entity-tracking-culling |
entity-tracking-culling.max-queued | integer256 | 1..65536 jobs | Maximum visibility raycast jobs queued per tick before falling back to vanilla distance tracking.Applies when: feature-flags.entity-tracking-culling |
ai-precompute-queue.max-candidates | integer128 | 1..4096 candidates | Maximum candidate targets evaluated per mob snapshot.Applies when: feature-flags.ai-precompute-queue |
ai-precompute-queue.exclude-mob-types | list[] | namespaced IDs, e.g. minecraft:zombie | Namespaced mob IDs excluded from background target precomputation so they keep vanilla target lookup.Applies when: feature-flags.ai-precompute-queue |
entity-tracking-culling.max-ray-blocks | integer128 | 1..1024 blocks | Maximum blocks traversed per line-of-sight occlusion raycast.Applies when: feature-flags.entity-tracking-culling |
entity-tracking-culling.max-snapshot-boxes | integer1024 | 1..16384 boxes | Maximum block bounding boxes captured per visibility snapshot.Applies when: feature-flags.entity-tracking-culling |
hopper-tick-spreading.groups | integer4 | 1..64 groups | Number of staggered tick groups for idle hoppers (1 keeps vanilla polling).Applies when: feature-flags.hopper-tick-spreading |
hopper-tick-spreading.full-container-backoff-ticks | integer5 | 0..600 tick | Extra cooldown ticks when a hopper points into a completely full container (try 8 on hopper-heavy servers).Applies when: feature-flags.hopper-tick-spreading |
entity-behavior.mob-tracker | booleantrue | true / false | Send mob visibility packets to clients. If false, mobs stay on the server without being rendered.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.entity-collision | booleantrue | true / false | Enable entity-to-entity pushing and cramming checks. Turn off in crowded lobbies to save CPU.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.mob-ai | booleantrue | true / false | Master switch for mob AI goals, Brain tasks, and pathfinding.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.mob-item-pickup | booleantrue | true / false | Allow mobs to inspect and pick up dropped items or equip gear from the ground.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.baby-mob-spawn-from-spawners | booleantrue | true / false | Allow monster and trial spawners to summon baby mob variants.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.mob-spawning | booleantrue | true / false | Enable natural periodic mob spawning while leaving spawners, commands, and plugins untouched.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.chunk-ticking | booleantrue | true / false | Run random crop ticks, scheduled fluid/block ticks, and block entities in loaded chunks.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.weather-ticking | booleantrue | true / false | Advance natural rain and thunder cycles automatically.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.villager-ticking | booleantrue | true / false | Tick villager AI, professions, and restocking. Disable only on static lobby servers.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
tuning-preset | stringDEFAULT | DEFAULT / HUB | DEFAULT follows your individual settings. HUB automatically disables entity collision, natural spawning, chunk ticks, weather, and villager ticks in memory.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.ticking-mode | stringVANILLA | VANILLA / OPTIMIZED / EXTRA_OPTIMIZED | AI goal throttling level for distant mobs. Use OPTIMIZED on busy SMPs to save MSPT while keeping nearby mobs normal.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.goal-selector-throttle.enabled | booleantrue | true / false | Allow slower AI goal re-evaluation for distant mobs when OPTIMIZED or EXTRA_OPTIMIZED is selected.Applies when: entity-behavior.ticking-mode is OPTIMIZED or EXTRA_OPTIMIZED |
entity-behavior.goal-selector-throttle.interval | integer4 | 1..600 tick | Base tick interval between distant mob goal re-evaluations (doubled in EXTRA_OPTIMIZED).Applies when: entity-behavior.ticking-mode is OPTIMIZED or EXTRA_OPTIMIZED |
entity-behavior.goal-selector-throttle.min-player-distance | number32 | >0..4096 blocks | Distance in blocks from the nearest player before mob goal throttling starts.Applies when: entity-behavior.ticking-mode is OPTIMIZED or EXTRA_OPTIMIZED |
entity-behavior.skip-idle-goal-ticks | booleantrue | true / false | Skip AI goal and target selector evaluations while an entity is in its inactive/distant state.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.brain-distance-scaling.enabled | booleantrue | true / false | Scale 1.14+ Brain sensor ticks (villagers, piglins, wardens) dynamically by distance to players.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.brain-distance-scaling.near-radius | number12 | >0..4096 blocks | Radius in blocks around players where Brain mobs always run at full 1-tick speed.Applies when: entity-behavior.brain-distance-scaling.enabled |
entity-behavior.brain-distance-scaling.max-interval | integer20 | 1..600 tick | Maximum tick interval between Brain sensor updates for very distant mobs.Applies when: entity-behavior.brain-distance-scaling.enabled |
entity-behavior.brain-distance-scaling.distance-shift | integer9 | 1..20 levels | Bit-shift divisor controlling how gradually Brain intervals grow with squared distance.Applies when: entity-behavior.brain-distance-scaling.enabled |
entity-behavior.sensor-cadence.water-check-interval | integer1 | 1..20 tick | Ticks between water-state checks on non-player entities (raise to 4 on high-entity servers).Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.sensor-cadence.eye-fluid-interval | integer1 | 1..20 tick | Ticks between eye-level fluid checks on non-player entities.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.sensor-cadence.equipment-sync-interval | integer1 | 1..20 tick | Ticks between equipment change scans on non-player living entities.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.sensor-cadence.line-of-sight-interval | integer1 | 1..40 tick | Ticks between clearing the mob line-of-sight cache (4–10 works well on mob-heavy SMPs).Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.sensor-cadence.turtle-helmet-effect | booleantrue | true / false | Process the passive Water Breathing check for players wearing a Turtle Helmet.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.sensor-cadence.dolphin-treasure-seek | booleanfalse | true / false | Register the dolphin treasure-hunting goal (off by default because structure lookups can cause lag spikes).Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.sensor-cadence.waypoint-locator-bar | booleantrue | true / false | Enable the 1.21.6+ player Waypoint Locator bar tracking system.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.sensor-cadence.powder-snow-freezing | booleantrue | true / false | Run powder-snow freezing checks on non-player entities.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.sensor-cadence.wall-suffocation-check | booleantrue | true / false | Run inside-wall suffocation checks on non-player entities every tick.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
entity-behavior.sensor-cadence.player-only-pushing | booleanfalse | true / false | Only let players push entities so densely packed farm mobs stop pushing each other.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches) |
Tick budgets, world & PvP (tick-budgets.*, world-mechanics.*, pvp-mechanics.*)
Per-tick item/projectile budgets, world rules, particle toggles, Mace caps, 1.8 PvP switches, and custom knockback profiles.
All options below belong in nusa-global.yml and require a full server restart. Missing keys automatically use the default value.
| Complete key | Type / default | Range / unit | What it does & when it applies |
|---|---|---|---|
tick-budgets.item-merge-scans-per-tick | integer150 | 1..100000 scan/tick | Server-wide cap on dropped item merge scans per tick so huge item explosions do not stall the tick.Applies when: startup |
tick-budgets.projectile-chunk-loads-per-tick | integer10 | 1..10000 chunk/tick | Maximum chunks that all flying projectiles combined may load in one tick.Applies when: startup |
tick-budgets.projectile-max-chunk-loads | integer10 | 1..10000 chunk | Maximum chunks a single projectile may load before being discarded.Applies when: startup |
tick-budgets.vehicle-collision-stack-limit | integer0 | 0..1000 vehicles | Remove excess stacked boats or minecarts colliding in one spot (0 = disabled; try 10 to block vehicle lag machines).Applies when: startup |
world-mechanics.persist-transient-projectiles | booleanfalse | true / false | Save snowballs and fireworks to disk on chunk unload (false by default to prevent projectile save lag traps).Applies when: startup |
world-mechanics.suppress-zero-velocity-packets | booleantrue | true / false | Skip sending entity velocity packets when the knockback delta is zero.Applies when: startup |
world-mechanics.suppress-immune-fire-packets | booleantrue | true / false | Skip visual fire metadata packets when the entity already has Fire Resistance.Applies when: startup |
world-mechanics.advancement-criterion-triggers | booleantrue | true / false | Evaluate player advancement triggers. Turn off only on minigame or lobby servers that do not use advancements.Applies when: startup |
world-mechanics.compact-death-drops | booleanfalse | true / false | Keep items dropped on player death neatly grouped instead of scattering wide.Applies when: startup |
world-mechanics.bypass-chest-top-obstruction | booleanfalse | true / false | Allow players to open chests even when a solid block sits directly above them.Applies when: startup |
world-mechanics.spawner-check-spawn-rules | booleantrue | true / false | Check light level and biome rules before spawners summon mobs (false suits Skyblock or Prison grinders).Applies when: startup |
world-mechanics.visual-effects.fall-impact-particles | booleantrue | true / false | Send block dust particles when entities land from a fall. Disable to cut particle traffic.Applies when: startup |
world-mechanics.visual-effects.death-poof-particles | booleantrue | true / false | Send white smoke particles when entities die. Disable to cut particle traffic.Applies when: startup |
world-mechanics.visual-effects.water-splash-particles | booleantrue | true / false | Send water splash particles when entities enter water. Disable to cut particle traffic.Applies when: startup |
world-mechanics.visual-effects.bubble-column-particles | booleantrue | true / false | Send splash particles on bubble columns. Disable to cut particle traffic.Applies when: startup |
world-mechanics.visual-effects.spawner-flame-particles | booleantrue | true / false | Emit flame and smoke particles from monster spawners. Disable to reduce spawner packets.Applies when: startup |
pvp-mechanics.allow-sprint-criticals | booleanfalse | true / false | Allow players to land critical hits while continuing to sprint (classic 1.8 combat feel).Applies when: startup |
pvp-mechanics.fishing-hook-pull-entities | booleantrue | true / false | Pull hooked entities toward the player when reeling in a fishing rod.Applies when: startup |
pvp-mechanics.fishing-hook-knockback | booleanfalse | true / false | Apply knockback and hit-flash when a fishing bobber strikes a living entity (1.8 rod PvP).Applies when: startup |
pvp-mechanics.ignore-netherite-kb-resistance | booleanfalse | true / false | Ignore passive Netherite armor knockback resistance during PvP hits.Applies when: startup |
pvp-mechanics.mace.fall-distance-cap | number-1 | -1.0 or >0..4096 blocks | Maximum fall distance counted for Mace smash damage (-1.0 = uncapped; e.g. 30.0 prevents orbital one-shot traps).Applies when: startup |
pvp-mechanics.mace.flatten-fall-scaling | booleanfalse | true / false | Disable fall-distance bonus scaling on Mace attacks completely.Applies when: startup |
pvp-mechanics.knockback.custom-profile | booleanfalse | true / false | Enable the custom horizontal, vertical, and friction knockback multipliers below.Applies when: startup |
pvp-mechanics.knockback.horizontal | number0.4 | 0..10 value | Horizontal knockback velocity multiplier.Applies when: pvp-mechanics.knockback.custom-profile |
pvp-mechanics.knockback.vertical | number0.4 | 0..10 value | Upward vertical lift applied when the target is on the ground.Applies when: pvp-mechanics.knockback.custom-profile |
pvp-mechanics.knockback.vertical-limit | number0.4 | 0..10 value | Maximum upward vertical velocity cap after knockback.Applies when: pvp-mechanics.knockback.custom-profile |
pvp-mechanics.knockback.friction | number2 | 0.1..100 value | Velocity retention divisor applied to existing motion before knockback.Applies when: pvp-mechanics.knockback.custom-profile |
Storage & async I/O (async-chunk-io.*, region-file-compression.*, async-playerdata-save.*)
Background chunk disk workers, Zstandard region compression level, and detached player data saving.
All options below belong in nusa-global.yml and require a full server restart. Missing keys automatically use the default value.
| Complete key | Type / default | Range / unit | What it does & when it applies |
|---|---|---|---|
async-chunk-io.threads | integer0 | 0..256 threads | Chunk disk I/O worker count. 0 automatically scales with available CPU cores.Applies when: feature-flags.async-chunk-io |
region-file-compression.level | integer3 | -5..22 level zstd | Zstd compression level for newly written chunks. Default 3 balances storage savings and low CPU use.Applies when: feature-flags.region-file-compression |
async-playerdata-save.threads | integer0 | 0..256 threads | Background player-save worker count. 0 automatically selects up to 2 threads.Applies when: feature-flags.async-playerdata-save |
async-playerdata-save.warn-queued-players | integer1024 | 1..2147483647 players | Log a slow-disk warning when pending player saves exceed this count.Applies when: feature-flags.async-playerdata-save |
async-playerdata-save.warn-queued-mib | integer64 | 1..2147483647 MiB | Log a memory warning when pending player save snapshots exceed this MiB threshold.Applies when: feature-flags.async-playerdata-save |
Network & crowded hubs (hub-networking.*, combat-priority-override.*, networking.*)
Shared broadcast cache, tiered movement updates, combat priority window, tab-list batching, and Netty socket tuning.
All options below belong in nusa-global.yml and require a full server restart. Missing keys automatically use the default value.
| Complete key | Type / default | Range / unit | What it does & when it applies |
|---|---|---|---|
hub-networking.shared-cache-entries | integer8192 | 1..65536 entries | Short-lived cache size for shared broadcast packet buffers.Applies when: feature-flags.shared-packet-encoding |
hub-networking.near-distance | number8 | >0..4096 blocks | 3D distance in blocks within which players receive every-tick movement updates.Applies when: feature-flags.tiered-entity-updates |
hub-networking.far-interval | integer4 | 1..20 tick | Tick interval for updating visible players beyond near-distance.Applies when: feature-flags.tiered-entity-updates |
hub-networking.waypoint-far-interval | integer1 | 1..4 tick | Tick interval for distant player locator bar updates (set 4 in crowded hubs).Applies when: feature-flags.tiered-entity-updates |
hub-networking.snapshot-interval | integer4 | 1..20 tick | Ticks between rebuilding the player distance lookup snapshot.Applies when: feature-flags.tiered-entity-updates |
hub-networking.max-snapshot-players | integer1024 | 2..2048 players | Maximum players indexed per distance snapshot before using direct fallback.Applies when: feature-flags.tiered-entity-updates |
hub-networking.tab-window-millis | integer200 | 1..1000 ms | Batching window in milliseconds for coalescing numeric tab-list updates.Applies when: feature-flags.batch-tab-list |
hub-networking.max-tab-entries | integer4096 | 1..16384 entries | Maximum buffered tab entries before flushing immediately.Applies when: feature-flags.batch-tab-list |
combat-priority-override.enabled | booleantrue | true / false | Keep players actively fighting at 1-tick movement updates regardless of distance.Applies when: feature-flags.tiered-entity-updates |
combat-priority-override.window-ticks | integer80 | 1..1200 tick | Ticks a combat pair stays on full-rate updates after a hit (80 ticks = 4 seconds).Applies when: combat-priority-override.enabled |
networking.flush-consolidation | booleantrue | true / false | Consolidate Netty socket flushes under load to reduce OS wakeups.Applies when: feature-flags.netty-tuning |
networking.ip-tos | integer24 | 0..255 | IP Type-of-Service byte for low-delay game packets (0 keeps OS default).Applies when: feature-flags.netty-tuning |
networking.tcp-fastopen | booleantrue | true / false | Enable TCP FastOpen on the listening socket when supported by the OS.Applies when: feature-flags.netty-tuning |
networking.tcp-fastopen-backlog | integer256 | 1..65535 connections | Pending connection backlog hint for TCP FastOpen.Applies when: networking.tcp-fastopen |
networking.chunk-batch-max-packets | integer32 | 1..1024 packets | Maximum chunk packets grouped into a single send batch.Applies when: feature-flags.chunk-compression-batching |
networking.chunk-batch-max-bytes | integer2097152 | 1024..8388608 byte | Maximum byte size grouped into a single chunk batch.Applies when: feature-flags.chunk-compression-batching |
networking.chunk-batch-delay-millis | integer1 | 0..10 ms | Maximum wait in milliseconds before flushing a partial chunk batch.Applies when: feature-flags.chunk-compression-batching |
World pre-generation (pre-generation.*)
TPS/MSPT safety thresholds and concurrency limits for /nusa pregen.
All options below belong in nusa-global.yml and require a full server restart. Missing keys automatically use the default value.
| Complete key | Type / default | Range / unit | What it does & when it applies |
|---|---|---|---|
pre-generation.minimum-tps | number18 | 1..20 TPS | Pause background chunk pre-generation automatically when TPS drops below this threshold.Applies when: feature-flags.pre-generation |
pre-generation.resume-tps | number19 | 1..20 TPS, ≥ minimum-tps | Resume paused pre-generation once TPS recovers to at least this value.Applies when: feature-flags.pre-generation |
pre-generation.max-average-mspt | number40 | >0..50 ms | Pause pre-generation when average tick time (MSPT) exceeds this threshold.Applies when: feature-flags.pre-generation |
pre-generation.max-in-flight | integer2 | 1..64 request | Concurrent chunk generation tasks allowed in flight (can be raised during offline maintenance).Applies when: feature-flags.pre-generation |
pre-generation.requests-per-tick | integer1 | 1..64 request/tick | New chunk generation tasks admitted per tick.Applies when: feature-flags.pre-generation |
pre-generation.progress-interval-ticks | integer200 | 20..72000 tick | Console progress log interval in ticks (200 ticks ≈ 10 seconds at 20 TPS).Applies when: feature-flags.pre-generation |
pre-generation.max-radius-chunks | integer256 | 1..2048 chunk | Maximum radius (in chunks) accepted by one /nusa pregen <radius> <world> command.Applies when: feature-flags.pre-generation |
pre-generation.player-buffer-chunks | integer2 | 0..32 chunk | Extra chunk buffer around online players skipped by pregen.Applies when: feature-flags.pre-generation |
Security guards (security.*)
NBT decoder limits, crash pattern filters, packet flood rate limits, tick starvation budgets, and redstone abuse deferral.
All options below belong in nusa-global.yml and require a full server restart. Missing keys automatically use the default value.
| Complete key | Type / default | Range / unit | What it does & when it applies |
|---|---|---|---|
security.warning-interval-ticks | integer200 | 1..72000 tick | Minimum nominal tick interval between repeated security log warnings.Applies when: corresponding security guard enabled |
security.max-warnings-per-interval | integer32 | 1..4096 warning | Maximum security warning lines logged per interval.Applies when: corresponding security guard enabled |
security.max-log-value-length | integer128 | 16..1024 characters | Maximum sanitized character length printed for untrusted values in security logs.Applies when: corresponding security guard enabled |
security.nbt-packet-validation.action | stringSKIP | SKIP / DISCONNECT; KICK = legacy alias | Action when a packet fails NBT limits (SKIP drops the packet; DISCONNECT kicks the sender).Applies when: feature-flags.nbt-packet-validation |
security.nbt-packet-validation.max-bytes | integer2097152 | 1024..2097152 byte | Maximum incoming NBT payload size in bytes.Applies when: feature-flags.nbt-packet-validation |
security.nbt-packet-validation.max-depth | integer512 | 1..512 levels | Maximum allowed nesting depth for compound and list NBT tags.Applies when: feature-flags.nbt-packet-validation |
security.nbt-packet-validation.max-nodes | integer2097152 | 1..2097152 node | Maximum total NBT tag elements allowed in a single packet.Applies when: feature-flags.nbt-packet-validation |
security.crash-pattern-guard.action | stringSKIP | SKIP / DISCONNECT; KICK = legacy alias | Action when a custom payload exceeds size limits or matches a blocked pattern.Applies when: feature-flags.crash-pattern-guard |
security.crash-pattern-guard.max-payload-bytes | integer2097152 | 1024..2097152 byte | Maximum byte length for incoming custom payload packets.Applies when: feature-flags.crash-pattern-guard |
security.crash-pattern-guard.patterns | list[] | 0..128 rule objects | Custom literal filter rules (id, channel, substring, max-bytes) to block specific exploit channels.Applies when: feature-flags.crash-pattern-guard |
security.packet-flood-detection.action | stringSKIP | SKIP / DISCONNECT; KICK = legacy alias | Action when a connection exceeds the packet flood rate.Applies when: feature-flags.packet-flood-detection |
security.packet-flood-detection.rate-per-second | integer300 | 1..1000000 packets/seconds | Sustained incoming PLAY packets per second allowed per player.Applies when: feature-flags.packet-flood-detection |
security.packet-flood-detection.burst | integer600 | 1..1000000 token | Short-term packet burst capacity per player.Applies when: feature-flags.packet-flood-detection |
security.tick-starvation-guard.action | stringSKIP | SKIP / DISCONNECT; KICK = legacy alias | SKIP defers excess packets to the next tick; DISCONNECT kicks connections that exhaust their tick budget.Applies when: feature-flags.tick-starvation-guard |
security.tick-starvation-guard.max-packets-per-tick | integer64 | 1..65536 packets/players/tick | Maximum packets processed on the main thread for one player per tick.Applies when: feature-flags.tick-starvation-guard |
security.tick-starvation-guard.max-processing-micros | integer2000 | 1..50000 µs/players/tick | Maximum main-thread microseconds spent on one player per tick (2000 µs = 2 ms).Applies when: feature-flags.tick-starvation-guard |
security.redstone-abuse-limiter.max-updates-per-chunk-per-tick | integer4096 | 1..1048576 update | Redstone updates allowed per chunk per tick before deferring excess work.Applies when: feature-flags.redstone-abuse-limiter |
security.redstone-abuse-limiter.max-deferred-per-chunk | integer8192 | 1..1048576 entries | Maximum deferred redstone updates queued for a single chunk.Applies when: feature-flags.redstone-abuse-limiter |
security.redstone-abuse-limiter.max-deferred-total | integer65536 | 1..16777216 entries/world | Maximum deferred redstone updates queued per world (at least max-deferred-per-chunk).Applies when: feature-flags.redstone-abuse-limiter |
security.redstone-abuse-limiter.warning-interval-ticks | integer200 | 1..72000 tick | Minimum tick interval between redstone limiter warnings.Applies when: feature-flags.redstone-abuse-limiter |
security.miscellaneous-security.disable-placed-block-nbt-reading | booleanfalse | true / false | Block raw BlockEntityTag data from items when placing blocks (recommended on public Creative servers).Applies when: feature-flags.miscellaneous-security |
security.miscellaneous-security.downloader-request-channels | list["wdl:request"] | 0..128 channel namespaced | Namespaced plugin channels rate-limited for World Downloader requests.Applies when: feature-flags.miscellaneous-security |
security.miscellaneous-security.downloader-request-rate-per-second | integer2 | 1..10000 request/seconds | Allowed recognized World Downloader requests per second.Applies when: feature-flags.miscellaneous-security |
security.miscellaneous-security.downloader-request-burst | integer8 | 1..1000000 token | Allowed burst count for recognized World Downloader requests.Applies when: feature-flags.miscellaneous-security |
security.miscellaneous-security.downloader-action | stringSKIP | SKIP / DISCONNECT; KICK = legacy alias | Action when recognized World Downloader requests exceed budget.Applies when: feature-flags.miscellaneous-security |
Dashboard & Discord alerts (management.*)
Live /nusa status intervals, optional loopback JSON metrics endpoint, and Discord webhook alert thresholds.
All options below belong in nusa-global.yml and require a full server restart. Missing keys automatically use the default value.
| Complete key | Type / default | Range / unit | What it does & when it applies |
|---|---|---|---|
management.dashboard.update-interval-seconds | integer3 | 1..60 seconds | Refresh interval in seconds for live /nusa status watch subscribers.Applies when: feature-flags.live-dashboard |
management.dashboard.max-subscribers | integer16 | 1..128 subscriber | Maximum admins watching /nusa status watch at the same time.Applies when: feature-flags.live-dashboard |
management.dashboard.json-endpoint-enabled | booleanfalse | true / false | Expose an optional local read-only JSON metrics endpoint (not required for Cloud Panel linking).Applies when: feature-flags.live-dashboard and json-endpoint-enabled |
management.dashboard.json-port | integer9240 | 1..65535 port | Local TCP port for the optional JSON metrics endpoint.Applies when: feature-flags.live-dashboard and json-endpoint-enabled |
management.dashboard.json-token | string'' | 20..256 printable non-whitespace ASCII when enabled | Private Bearer token (20–256 printable ASCII chars) required when the local JSON endpoint is enabled.Applies when: feature-flags.live-dashboard and json-endpoint-enabled |
management.discord.webhook-url | string'' | empty or an official HTTPS Discord webhook URL | Private official HTTPS Discord webhook URL for server health alerts.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.low-tps-threshold | number15 | 1..20 TPS | TPS threshold below which sustained low-TPS alerts trigger.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.low-tps-duration-seconds | integer60 | 1..3600 seconds | Seconds TPS must stay below low-tps-threshold before sending a Discord alert.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.cooldown-seconds | integer300 | 1..86400 seconds | Minimum cooldown in seconds between alerts of the same category.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.repeated-security-threshold | integer10 | 2..1000000 incidents | Blocked security events from one connection required to trigger a summary alert.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.repeated-security-window-seconds | integer60 | 1..3600 seconds | Time window in seconds for counting repeated security rejections.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.queue-capacity | integer32 | 1..256 alert | Maximum outgoing Discord alerts buffered in memory.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.request-timeout-seconds | integer5 | 1..30 seconds | HTTP timeout in seconds when delivering Discord webhook messages.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.notify-fatal-exceptions | booleantrue | true / false | Send a Discord alert on unhandled fatal tick or watchdog errors.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.notify-low-tps | booleantrue | true / false | Send a Discord alert when sustained low TPS is detected.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.notify-module-disabled | booleantrue | true / false | Send a Discord alert when runtime safemode activates or a plugin fails to enable.Applies when: feature-flags.discord-webhook and a valid webhook URL |
management.discord.notify-repeated-security | booleantrue | true / false | Send a Discord alert summary when a connection repeatedly triggers packet guards.Applies when: feature-flags.discord-webhook and a valid webhook URL |