All settings reference

Complete searchable reference of every setting, default value, and allowed range in nusa-global.yml.

On this page

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.

KeyDefaultCategory
feature-flags.async-chunk-iotrueFeature flags
feature-flags.region-file-compressiontrueFeature flags
feature-flags.async-playerdata-savetrueFeature flags
feature-flags.ai-precompute-queuetrueFeature flags
feature-flags.entity-tracking-cullingtrueFeature flags
feature-flags.hopper-tick-spreadingtrueFeature flags
feature-flags.entity-behavior-switchestrueFeature flags
feature-flags.nbt-packet-validationtrueFeature flags
feature-flags.crash-pattern-guardtrueFeature flags
feature-flags.packet-flood-detectiontrueFeature flags
feature-flags.tick-starvation-guardtrueFeature flags
feature-flags.redstone-abuse-limitertrueFeature flags
feature-flags.miscellaneous-securitytrueFeature flags
feature-flags.netty-native-transporttrueFeature flags
feature-flags.chunk-compression-batchingtrueFeature flags
feature-flags.netty-tuningtrueFeature flags
feature-flags.pre-generationtrueFeature flags
feature-flags.shared-packet-encodingtrueFeature flags
feature-flags.tiered-entity-updatestrueFeature flags
feature-flags.batch-tab-listtrueFeature flags
feature-flags.pooled-broadcast-bufferstrueFeature flags
feature-flags.tuning-wizardtrueFeature flags
feature-flags.live-dashboardtrueFeature flags
feature-flags.discord-webhookfalseFeature flags
async-chunk-io.threads0Storage & I/O
region-file-compression.level3Storage & I/O
async-playerdata-save.threads0Storage & I/O
async-playerdata-save.warn-queued-players1024Storage & I/O
async-playerdata-save.warn-queued-mib64Storage & I/O
ai-precompute-queue.threads0Entities & AI
ai-precompute-queue.max-queued256Entities & AI
entity-tracking-culling.threads0Entities & AI
entity-tracking-culling.max-queued256Entities & AI
ai-precompute-queue.max-candidates128Entities & AI
ai-precompute-queue.exclude-mob-types[]Entities & AI
entity-tracking-culling.max-ray-blocks128Entities & AI
entity-tracking-culling.max-snapshot-boxes1024Entities & AI
hopper-tick-spreading.groups4Entities & AI
hopper-tick-spreading.full-container-backoff-ticks5Entities & AI
entity-behavior.mob-trackertrueEntities & AI
entity-behavior.entity-collisiontrueEntities & AI
entity-behavior.mob-aitrueEntities & AI
entity-behavior.mob-item-pickuptrueEntities & AI
entity-behavior.baby-mob-spawn-from-spawnerstrueEntities & AI
entity-behavior.mob-spawningtrueEntities & AI
entity-behavior.chunk-tickingtrueEntities & AI
entity-behavior.weather-tickingtrueEntities & AI
entity-behavior.villager-tickingtrueEntities & AI
tuning-presetDEFAULTEntities & AI
entity-behavior.ticking-modeVANILLAEntities & AI
entity-behavior.goal-selector-throttle.enabledtrueEntities & AI
entity-behavior.goal-selector-throttle.interval4Entities & AI
entity-behavior.goal-selector-throttle.min-player-distance32Entities & AI
entity-behavior.skip-idle-goal-tickstrueEntities & AI
entity-behavior.brain-distance-scaling.enabledtrueEntities & AI
entity-behavior.brain-distance-scaling.near-radius12Entities & AI
entity-behavior.brain-distance-scaling.max-interval20Entities & AI
entity-behavior.brain-distance-scaling.distance-shift9Entities & AI
entity-behavior.sensor-cadence.water-check-interval1Entities & AI
entity-behavior.sensor-cadence.eye-fluid-interval1Entities & AI
entity-behavior.sensor-cadence.equipment-sync-interval1Entities & AI
entity-behavior.sensor-cadence.line-of-sight-interval1Entities & AI
entity-behavior.sensor-cadence.turtle-helmet-effecttrueEntities & AI
entity-behavior.sensor-cadence.dolphin-treasure-seekfalseEntities & AI
entity-behavior.sensor-cadence.waypoint-locator-bartrueEntities & AI
entity-behavior.sensor-cadence.powder-snow-freezingtrueEntities & AI
entity-behavior.sensor-cadence.wall-suffocation-checktrueEntities & AI
entity-behavior.sensor-cadence.player-only-pushingfalseEntities & AI
tick-budgets.item-merge-scans-per-tick150Tick budgets, world & PvP
tick-budgets.projectile-chunk-loads-per-tick10Tick budgets, world & PvP
tick-budgets.projectile-max-chunk-loads10Tick budgets, world & PvP
tick-budgets.vehicle-collision-stack-limit0Tick budgets, world & PvP
world-mechanics.persist-transient-projectilesfalseTick budgets, world & PvP
world-mechanics.suppress-zero-velocity-packetstrueTick budgets, world & PvP
world-mechanics.suppress-immune-fire-packetstrueTick budgets, world & PvP
world-mechanics.advancement-criterion-triggerstrueTick budgets, world & PvP
world-mechanics.compact-death-dropsfalseTick budgets, world & PvP
world-mechanics.bypass-chest-top-obstructionfalseTick budgets, world & PvP
world-mechanics.spawner-check-spawn-rulestrueTick budgets, world & PvP
world-mechanics.visual-effects.fall-impact-particlestrueTick budgets, world & PvP
world-mechanics.visual-effects.death-poof-particlestrueTick budgets, world & PvP
world-mechanics.visual-effects.water-splash-particlestrueTick budgets, world & PvP
world-mechanics.visual-effects.bubble-column-particlestrueTick budgets, world & PvP
world-mechanics.visual-effects.spawner-flame-particlestrueTick budgets, world & PvP
pvp-mechanics.allow-sprint-criticalsfalseTick budgets, world & PvP
pvp-mechanics.fishing-hook-pull-entitiestrueTick budgets, world & PvP
pvp-mechanics.fishing-hook-knockbackfalseTick budgets, world & PvP
pvp-mechanics.ignore-netherite-kb-resistancefalseTick budgets, world & PvP
pvp-mechanics.mace.fall-distance-cap-1Tick budgets, world & PvP
pvp-mechanics.mace.flatten-fall-scalingfalseTick budgets, world & PvP
pvp-mechanics.knockback.custom-profilefalseTick budgets, world & PvP
pvp-mechanics.knockback.horizontal0.4Tick budgets, world & PvP
pvp-mechanics.knockback.vertical0.4Tick budgets, world & PvP
pvp-mechanics.knockback.vertical-limit0.4Tick budgets, world & PvP
pvp-mechanics.knockback.friction2Tick budgets, world & PvP
bedrock-optimization.enabledtrueBedrock & Geyser
bedrock-optimization.detect-floodgate-uuidtrueBedrock & Geyser
bedrock-optimization.detect-geyser-brandtrueBedrock & Geyser
bedrock-optimization.username-prefix.Bedrock & Geyser
bedrock-optimization.moved-wrongly-multiplier2.5Bedrock & Geyser
bedrock-optimization.moved-too-quickly-multiplier1.5Bedrock & Geyser
bedrock-optimization.extra-floating-tolerance-ticks40Bedrock & Geyser
bedrock-optimization.near-distance6Bedrock & Geyser
bedrock-optimization.far-entity-update-interval6Bedrock & Geyser
bedrock-optimization.cull-micro-rotation-updatestrueBedrock & Geyser
bedrock-optimization.max-particles-per-packet16Bedrock & Geyser
bedrock-optimization.max-particle-distance24Bedrock & Geyser
bedrock-optimization.max-chunks-per-tick2Bedrock & Geyser
bedrock-optimization.tab-window-millis400Bedrock & Geyser
hub-networking.shared-cache-entries8192Network & hubs
hub-networking.near-distance8Network & hubs
hub-networking.far-interval4Network & hubs
hub-networking.waypoint-far-interval1Network & hubs
hub-networking.snapshot-interval4Network & hubs
hub-networking.max-snapshot-players1024Network & hubs
hub-networking.tab-window-millis200Network & hubs
hub-networking.max-tab-entries4096Network & hubs
combat-priority-override.enabledtrueNetwork & hubs
combat-priority-override.window-ticks80Network & hubs
networking.flush-consolidationtrueNetwork & hubs
networking.ip-tos24Network & hubs
networking.tcp-fastopentrueNetwork & hubs
networking.tcp-fastopen-backlog256Network & hubs
networking.chunk-batch-max-packets32Network & hubs
networking.chunk-batch-max-bytes2097152Network & hubs
networking.chunk-batch-delay-millis1Network & hubs
pre-generation.minimum-tps18World pre-generation
pre-generation.resume-tps19World pre-generation
pre-generation.max-average-mspt40World pre-generation
pre-generation.max-in-flight2World pre-generation
pre-generation.requests-per-tick1World pre-generation
pre-generation.progress-interval-ticks200World pre-generation
pre-generation.max-radius-chunks256World pre-generation
pre-generation.player-buffer-chunks2World pre-generation
security.warning-interval-ticks200Security guards
security.max-warnings-per-interval32Security guards
security.max-log-value-length128Security guards
security.nbt-packet-validation.actionSKIPSecurity guards
security.nbt-packet-validation.max-bytes2097152Security guards
security.nbt-packet-validation.max-depth512Security guards
security.nbt-packet-validation.max-nodes2097152Security guards
security.crash-pattern-guard.actionSKIPSecurity guards
security.crash-pattern-guard.max-payload-bytes2097152Security guards
security.crash-pattern-guard.patterns[]Security guards
security.packet-flood-detection.actionSKIPSecurity guards
security.packet-flood-detection.rate-per-second300Security guards
security.packet-flood-detection.burst600Security guards
security.tick-starvation-guard.actionSKIPSecurity guards
security.tick-starvation-guard.max-packets-per-tick64Security guards
security.tick-starvation-guard.max-processing-micros2000Security guards
security.redstone-abuse-limiter.max-updates-per-chunk-per-tick4096Security guards
security.redstone-abuse-limiter.max-deferred-per-chunk8192Security guards
security.redstone-abuse-limiter.max-deferred-total65536Security guards
security.redstone-abuse-limiter.warning-interval-ticks200Security guards
security.miscellaneous-security.disable-placed-block-nbt-readingfalseSecurity guards
security.miscellaneous-security.downloader-request-channels["wdl:request"]Security guards
security.miscellaneous-security.downloader-request-rate-per-second2Security guards
security.miscellaneous-security.downloader-request-burst8Security guards
security.miscellaneous-security.downloader-actionSKIPSecurity guards
management.dashboard.update-interval-seconds3Dashboard & Discord
management.dashboard.max-subscribers16Dashboard & Discord
management.dashboard.json-endpoint-enabledfalseDashboard & Discord
management.dashboard.json-port9240Dashboard & Discord
management.dashboard.json-token''Dashboard & Discord
management.discord.webhook-url''Dashboard & Discord
management.discord.low-tps-threshold15Dashboard & Discord
management.discord.low-tps-duration-seconds60Dashboard & Discord
management.discord.cooldown-seconds300Dashboard & Discord
management.discord.repeated-security-threshold10Dashboard & Discord
management.discord.repeated-security-window-seconds60Dashboard & Discord
management.discord.queue-capacity32Dashboard & Discord
management.discord.request-timeout-seconds5Dashboard & Discord
management.discord.notify-fatal-exceptionstrueDashboard & Discord
management.discord.notify-low-tpstrueDashboard & Discord
management.discord.notify-module-disabledtrueDashboard & Discord
management.discord.notify-repeated-securitytrueDashboard & Discord

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 keyType / defaultRange / unitWhat it does & when it applies
feature-flags.async-chunk-iobooleantruetrue / falseOffload 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-compressionbooleantruetrue / falseCompress 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-savebooleantruetrue / falseWrite 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-queuebooleantruetrue / falsePrecompute 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-cullingbooleantruetrue / falseHide 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-spreadingbooleantruetrue / falseSpread 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-switchesbooleantruetrue / falseMaster 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-validationbooleantruetrue / falseInspect 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-guardbooleantruetrue / falseBlock oversized custom payloads and configured literal exploit channel patterns.Applies when: startup; bypassed temporarily during /nusa safemode on (except management)
feature-flags.packet-flood-detectionbooleantruetrue / falseRate-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-guardbooleantruetrue / falseCap 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-limiterbooleantruetrue / falseDefer 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-securitybooleantruetrue / falseEnable 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-transportbooleantruetrue / falsePrefer 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-batchingbooleantruetrue / falseGroup 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-tuningbooleantruetrue / falseApply 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-generationbooleantruetrue / falseEnable 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-encodingbooleantruetrue / falseEncode 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-updatesbooleantruetrue / falseSend 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-listbooleantruetrue / falseCombine rapid numeric tab-list updates into short batch windows.Applies when: startup; bypassed temporarily during /nusa safemode on (except management)
feature-flags.pooled-broadcast-buffersbooleantruetrue / falseReuse pooled direct Netty buffers for multi-recipient broadcasts.Applies when: startup; bypassed temporarily during /nusa safemode on (except management)
feature-flags.tuning-wizardbooleantruetrue / falseEnable the /nusa setup configuration guide and Cloud Panel pointer.Applies when: startup; bypassed temporarily during /nusa safemode on (except management)
feature-flags.live-dashboardbooleantruetrue / falseEnable 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-webhookbooleanfalsetrue / falseSend 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 keyType / defaultRange / unitWhat it does & when it applies
bedrock-optimization.enabledbooleantruetrue / falseMaster switch for movement setback leniency, particle caps, and smooth chunk pacing for Bedrock (Geyser/Floodgate) players.Applies when: startup
bedrock-optimization.detect-floodgate-uuidbooleantruetrue / falseAutomatically identify Bedrock players via Floodgate XUID UUIDs (most-significant bits == 0).Applies when: bedrock-optimization.enabled
bedrock-optimization.detect-geyser-brandbooleantruetrue / falseAutomatically identify Bedrock players via the Geyser client brand payload.Applies when: bedrock-optimization.enabled
bedrock-optimization.username-prefixstring.0..16 printable ASCII charsFallback Floodgate username prefix for Bedrock detection (set empty string to disable prefix matching).Applies when: bedrock-optimization.enabled
bedrock-optimization.moved-wrongly-multipliernumber2.51..16 xMultiply 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-multipliernumber1.51..10 xMultiply Spigot moved-too-quickly threshold for Bedrock players to tolerate mobile RakNet jitter.Applies when: bedrock-optimization.enabled
bedrock-optimization.extra-floating-tolerance-ticksinteger400..400 tickExtra floating ticks allowed before kick checks when Bedrock players stand on partial block edges.Applies when: bedrock-optimization.enabled
bedrock-optimization.near-distancenumber6>0..4096 blocksRadius in blocks within which Bedrock viewers always receive every-tick entity movement updates.Applies when: bedrock-optimization.enabled
bedrock-optimization.far-entity-update-intervalinteger61..20 tickTick 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-updatesbooleantruetrue / falseSkip tiny head-only rotations (< 5.6 degrees) for distant entities viewed by Bedrock players.Applies when: bedrock-optimization.enabled
bedrock-optimization.max-particles-per-packetinteger161..1024 particlesCap particles per packet sent to Bedrock players to prevent mobile GPU frame drops.Applies when: bedrock-optimization.enabled
bedrock-optimization.max-particle-distancenumber24>0..512 blocksMaximum distance in blocks at which ordinary particles are sent to Bedrock players.Applies when: bedrock-optimization.enabled
bedrock-optimization.max-chunks-per-ticknumber20.25..64 chunk/tickMaximum chunks sent per tick to each Bedrock player so Geyser chunk translation stays smooth.Applies when: bedrock-optimization.enabled
bedrock-optimization.tab-window-millisinteger40050..2000 msTab-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 keyType / defaultRange / unitWhat it does & when it applies
ai-precompute-queue.threadsinteger00..256 threadsBackground target-precompute worker threads (0 = automatic up to 4 threads).Applies when: feature-flags.ai-precompute-queue
ai-precompute-queue.max-queuedinteger2561..65536 jobsMaximum target queries queued per tick before seamlessly falling back to vanilla selection.Applies when: feature-flags.ai-precompute-queue
entity-tracking-culling.threadsinteger00..256 threadsBackground occlusion raycast worker threads (0 = automatic up to 4 threads).Applies when: feature-flags.entity-tracking-culling
entity-tracking-culling.max-queuedinteger2561..65536 jobsMaximum visibility raycast jobs queued per tick before falling back to vanilla distance tracking.Applies when: feature-flags.entity-tracking-culling
ai-precompute-queue.max-candidatesinteger1281..4096 candidatesMaximum candidate targets evaluated per mob snapshot.Applies when: feature-flags.ai-precompute-queue
ai-precompute-queue.exclude-mob-typeslist[]namespaced IDs, e.g. minecraft:zombieNamespaced 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-blocksinteger1281..1024 blocksMaximum blocks traversed per line-of-sight occlusion raycast.Applies when: feature-flags.entity-tracking-culling
entity-tracking-culling.max-snapshot-boxesinteger10241..16384 boxesMaximum block bounding boxes captured per visibility snapshot.Applies when: feature-flags.entity-tracking-culling
hopper-tick-spreading.groupsinteger41..64 groupsNumber of staggered tick groups for idle hoppers (1 keeps vanilla polling).Applies when: feature-flags.hopper-tick-spreading
hopper-tick-spreading.full-container-backoff-ticksinteger50..600 tickExtra 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-trackerbooleantruetrue / falseSend 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-collisionbooleantruetrue / falseEnable 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-aibooleantruetrue / falseMaster 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-pickupbooleantruetrue / falseAllow 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-spawnersbooleantruetrue / falseAllow monster and trial spawners to summon baby mob variants.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches)
entity-behavior.mob-spawningbooleantruetrue / falseEnable 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-tickingbooleantruetrue / falseRun 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-tickingbooleantruetrue / falseAdvance natural rain and thunder cycles automatically.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches)
entity-behavior.villager-tickingbooleantruetrue / falseTick villager AI, professions, and restocking. Disable only on static lobby servers.Applies when: feature-flags.entity-behavior-switches (HUB preset overrides 5 switches)
tuning-presetstringDEFAULTDEFAULT / HUBDEFAULT 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-modestringVANILLAVANILLA / OPTIMIZED / EXTRA_OPTIMIZEDAI 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.enabledbooleantruetrue / falseAllow 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.intervalinteger41..600 tickBase 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-distancenumber32>0..4096 blocksDistance 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-ticksbooleantruetrue / falseSkip 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.enabledbooleantruetrue / falseScale 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-radiusnumber12>0..4096 blocksRadius 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-intervalinteger201..600 tickMaximum tick interval between Brain sensor updates for very distant mobs.Applies when: entity-behavior.brain-distance-scaling.enabled
entity-behavior.brain-distance-scaling.distance-shiftinteger91..20 levelsBit-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-intervalinteger11..20 tickTicks 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-intervalinteger11..20 tickTicks 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-intervalinteger11..20 tickTicks 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-intervalinteger11..40 tickTicks 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-effectbooleantruetrue / falseProcess 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-seekbooleanfalsetrue / falseRegister 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-barbooleantruetrue / falseEnable 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-freezingbooleantruetrue / falseRun 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-checkbooleantruetrue / falseRun 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-pushingbooleanfalsetrue / falseOnly 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 keyType / defaultRange / unitWhat it does & when it applies
tick-budgets.item-merge-scans-per-tickinteger1501..100000 scan/tickServer-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-tickinteger101..10000 chunk/tickMaximum chunks that all flying projectiles combined may load in one tick.Applies when: startup
tick-budgets.projectile-max-chunk-loadsinteger101..10000 chunkMaximum chunks a single projectile may load before being discarded.Applies when: startup
tick-budgets.vehicle-collision-stack-limitinteger00..1000 vehiclesRemove 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-projectilesbooleanfalsetrue / falseSave 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-packetsbooleantruetrue / falseSkip sending entity velocity packets when the knockback delta is zero.Applies when: startup
world-mechanics.suppress-immune-fire-packetsbooleantruetrue / falseSkip visual fire metadata packets when the entity already has Fire Resistance.Applies when: startup
world-mechanics.advancement-criterion-triggersbooleantruetrue / falseEvaluate player advancement triggers. Turn off only on minigame or lobby servers that do not use advancements.Applies when: startup
world-mechanics.compact-death-dropsbooleanfalsetrue / falseKeep items dropped on player death neatly grouped instead of scattering wide.Applies when: startup
world-mechanics.bypass-chest-top-obstructionbooleanfalsetrue / falseAllow players to open chests even when a solid block sits directly above them.Applies when: startup
world-mechanics.spawner-check-spawn-rulesbooleantruetrue / falseCheck light level and biome rules before spawners summon mobs (false suits Skyblock or Prison grinders).Applies when: startup
world-mechanics.visual-effects.fall-impact-particlesbooleantruetrue / falseSend block dust particles when entities land from a fall. Disable to cut particle traffic.Applies when: startup
world-mechanics.visual-effects.death-poof-particlesbooleantruetrue / falseSend white smoke particles when entities die. Disable to cut particle traffic.Applies when: startup
world-mechanics.visual-effects.water-splash-particlesbooleantruetrue / falseSend water splash particles when entities enter water. Disable to cut particle traffic.Applies when: startup
world-mechanics.visual-effects.bubble-column-particlesbooleantruetrue / falseSend splash particles on bubble columns. Disable to cut particle traffic.Applies when: startup
world-mechanics.visual-effects.spawner-flame-particlesbooleantruetrue / falseEmit flame and smoke particles from monster spawners. Disable to reduce spawner packets.Applies when: startup
pvp-mechanics.allow-sprint-criticalsbooleanfalsetrue / falseAllow players to land critical hits while continuing to sprint (classic 1.8 combat feel).Applies when: startup
pvp-mechanics.fishing-hook-pull-entitiesbooleantruetrue / falsePull hooked entities toward the player when reeling in a fishing rod.Applies when: startup
pvp-mechanics.fishing-hook-knockbackbooleanfalsetrue / falseApply knockback and hit-flash when a fishing bobber strikes a living entity (1.8 rod PvP).Applies when: startup
pvp-mechanics.ignore-netherite-kb-resistancebooleanfalsetrue / falseIgnore passive Netherite armor knockback resistance during PvP hits.Applies when: startup
pvp-mechanics.mace.fall-distance-capnumber-1-1.0 or >0..4096 blocksMaximum 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-scalingbooleanfalsetrue / falseDisable fall-distance bonus scaling on Mace attacks completely.Applies when: startup
pvp-mechanics.knockback.custom-profilebooleanfalsetrue / falseEnable the custom horizontal, vertical, and friction knockback multipliers below.Applies when: startup
pvp-mechanics.knockback.horizontalnumber0.40..10 valueHorizontal knockback velocity multiplier.Applies when: pvp-mechanics.knockback.custom-profile
pvp-mechanics.knockback.verticalnumber0.40..10 valueUpward vertical lift applied when the target is on the ground.Applies when: pvp-mechanics.knockback.custom-profile
pvp-mechanics.knockback.vertical-limitnumber0.40..10 valueMaximum upward vertical velocity cap after knockback.Applies when: pvp-mechanics.knockback.custom-profile
pvp-mechanics.knockback.frictionnumber20.1..100 valueVelocity 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 keyType / defaultRange / unitWhat it does & when it applies
async-chunk-io.threadsinteger00..256 threadsChunk disk I/O worker count. 0 automatically scales with available CPU cores.Applies when: feature-flags.async-chunk-io
region-file-compression.levelinteger3-5..22 level zstdZstd 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.threadsinteger00..256 threadsBackground player-save worker count. 0 automatically selects up to 2 threads.Applies when: feature-flags.async-playerdata-save
async-playerdata-save.warn-queued-playersinteger10241..2147483647 playersLog a slow-disk warning when pending player saves exceed this count.Applies when: feature-flags.async-playerdata-save
async-playerdata-save.warn-queued-mibinteger641..2147483647 MiBLog 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 keyType / defaultRange / unitWhat it does & when it applies
hub-networking.shared-cache-entriesinteger81921..65536 entriesShort-lived cache size for shared broadcast packet buffers.Applies when: feature-flags.shared-packet-encoding
hub-networking.near-distancenumber8>0..4096 blocks3D distance in blocks within which players receive every-tick movement updates.Applies when: feature-flags.tiered-entity-updates
hub-networking.far-intervalinteger41..20 tickTick interval for updating visible players beyond near-distance.Applies when: feature-flags.tiered-entity-updates
hub-networking.waypoint-far-intervalinteger11..4 tickTick interval for distant player locator bar updates (set 4 in crowded hubs).Applies when: feature-flags.tiered-entity-updates
hub-networking.snapshot-intervalinteger41..20 tickTicks between rebuilding the player distance lookup snapshot.Applies when: feature-flags.tiered-entity-updates
hub-networking.max-snapshot-playersinteger10242..2048 playersMaximum players indexed per distance snapshot before using direct fallback.Applies when: feature-flags.tiered-entity-updates
hub-networking.tab-window-millisinteger2001..1000 msBatching window in milliseconds for coalescing numeric tab-list updates.Applies when: feature-flags.batch-tab-list
hub-networking.max-tab-entriesinteger40961..16384 entriesMaximum buffered tab entries before flushing immediately.Applies when: feature-flags.batch-tab-list
combat-priority-override.enabledbooleantruetrue / falseKeep players actively fighting at 1-tick movement updates regardless of distance.Applies when: feature-flags.tiered-entity-updates
combat-priority-override.window-ticksinteger801..1200 tickTicks a combat pair stays on full-rate updates after a hit (80 ticks = 4 seconds).Applies when: combat-priority-override.enabled
networking.flush-consolidationbooleantruetrue / falseConsolidate Netty socket flushes under load to reduce OS wakeups.Applies when: feature-flags.netty-tuning
networking.ip-tosinteger240..255IP Type-of-Service byte for low-delay game packets (0 keeps OS default).Applies when: feature-flags.netty-tuning
networking.tcp-fastopenbooleantruetrue / falseEnable TCP FastOpen on the listening socket when supported by the OS.Applies when: feature-flags.netty-tuning
networking.tcp-fastopen-backloginteger2561..65535 connectionsPending connection backlog hint for TCP FastOpen.Applies when: networking.tcp-fastopen
networking.chunk-batch-max-packetsinteger321..1024 packetsMaximum chunk packets grouped into a single send batch.Applies when: feature-flags.chunk-compression-batching
networking.chunk-batch-max-bytesinteger20971521024..8388608 byteMaximum byte size grouped into a single chunk batch.Applies when: feature-flags.chunk-compression-batching
networking.chunk-batch-delay-millisinteger10..10 msMaximum 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 keyType / defaultRange / unitWhat it does & when it applies
pre-generation.minimum-tpsnumber181..20 TPSPause background chunk pre-generation automatically when TPS drops below this threshold.Applies when: feature-flags.pre-generation
pre-generation.resume-tpsnumber191..20 TPS, ≥ minimum-tpsResume paused pre-generation once TPS recovers to at least this value.Applies when: feature-flags.pre-generation
pre-generation.max-average-msptnumber40>0..50 msPause pre-generation when average tick time (MSPT) exceeds this threshold.Applies when: feature-flags.pre-generation
pre-generation.max-in-flightinteger21..64 requestConcurrent chunk generation tasks allowed in flight (can be raised during offline maintenance).Applies when: feature-flags.pre-generation
pre-generation.requests-per-tickinteger11..64 request/tickNew chunk generation tasks admitted per tick.Applies when: feature-flags.pre-generation
pre-generation.progress-interval-ticksinteger20020..72000 tickConsole progress log interval in ticks (200 ticks ≈ 10 seconds at 20 TPS).Applies when: feature-flags.pre-generation
pre-generation.max-radius-chunksinteger2561..2048 chunkMaximum radius (in chunks) accepted by one /nusa pregen <radius> <world> command.Applies when: feature-flags.pre-generation
pre-generation.player-buffer-chunksinteger20..32 chunkExtra 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 keyType / defaultRange / unitWhat it does & when it applies
security.warning-interval-ticksinteger2001..72000 tickMinimum nominal tick interval between repeated security log warnings.Applies when: corresponding security guard enabled
security.max-warnings-per-intervalinteger321..4096 warningMaximum security warning lines logged per interval.Applies when: corresponding security guard enabled
security.max-log-value-lengthinteger12816..1024 charactersMaximum sanitized character length printed for untrusted values in security logs.Applies when: corresponding security guard enabled
security.nbt-packet-validation.actionstringSKIPSKIP / DISCONNECT; KICK = legacy aliasAction 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-bytesinteger20971521024..2097152 byteMaximum incoming NBT payload size in bytes.Applies when: feature-flags.nbt-packet-validation
security.nbt-packet-validation.max-depthinteger5121..512 levelsMaximum allowed nesting depth for compound and list NBT tags.Applies when: feature-flags.nbt-packet-validation
security.nbt-packet-validation.max-nodesinteger20971521..2097152 nodeMaximum total NBT tag elements allowed in a single packet.Applies when: feature-flags.nbt-packet-validation
security.crash-pattern-guard.actionstringSKIPSKIP / DISCONNECT; KICK = legacy aliasAction 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-bytesinteger20971521024..2097152 byteMaximum byte length for incoming custom payload packets.Applies when: feature-flags.crash-pattern-guard
security.crash-pattern-guard.patternslist[]0..128 rule objectsCustom literal filter rules (id, channel, substring, max-bytes) to block specific exploit channels.Applies when: feature-flags.crash-pattern-guard
security.packet-flood-detection.actionstringSKIPSKIP / DISCONNECT; KICK = legacy aliasAction when a connection exceeds the packet flood rate.Applies when: feature-flags.packet-flood-detection
security.packet-flood-detection.rate-per-secondinteger3001..1000000 packets/secondsSustained incoming PLAY packets per second allowed per player.Applies when: feature-flags.packet-flood-detection
security.packet-flood-detection.burstinteger6001..1000000 tokenShort-term packet burst capacity per player.Applies when: feature-flags.packet-flood-detection
security.tick-starvation-guard.actionstringSKIPSKIP / DISCONNECT; KICK = legacy aliasSKIP 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-tickinteger641..65536 packets/players/tickMaximum packets processed on the main thread for one player per tick.Applies when: feature-flags.tick-starvation-guard
security.tick-starvation-guard.max-processing-microsinteger20001..50000 µs/players/tickMaximum 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-tickinteger40961..1048576 updateRedstone updates allowed per chunk per tick before deferring excess work.Applies when: feature-flags.redstone-abuse-limiter
security.redstone-abuse-limiter.max-deferred-per-chunkinteger81921..1048576 entriesMaximum deferred redstone updates queued for a single chunk.Applies when: feature-flags.redstone-abuse-limiter
security.redstone-abuse-limiter.max-deferred-totalinteger655361..16777216 entries/worldMaximum 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-ticksinteger2001..72000 tickMinimum tick interval between redstone limiter warnings.Applies when: feature-flags.redstone-abuse-limiter
security.miscellaneous-security.disable-placed-block-nbt-readingbooleanfalsetrue / falseBlock raw BlockEntityTag data from items when placing blocks (recommended on public Creative servers).Applies when: feature-flags.miscellaneous-security
security.miscellaneous-security.downloader-request-channelslist["wdl:request"]0..128 channel namespacedNamespaced plugin channels rate-limited for World Downloader requests.Applies when: feature-flags.miscellaneous-security
security.miscellaneous-security.downloader-request-rate-per-secondinteger21..10000 request/secondsAllowed recognized World Downloader requests per second.Applies when: feature-flags.miscellaneous-security
security.miscellaneous-security.downloader-request-burstinteger81..1000000 tokenAllowed burst count for recognized World Downloader requests.Applies when: feature-flags.miscellaneous-security
security.miscellaneous-security.downloader-actionstringSKIPSKIP / DISCONNECT; KICK = legacy aliasAction 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 keyType / defaultRange / unitWhat it does & when it applies
management.dashboard.update-interval-secondsinteger31..60 secondsRefresh interval in seconds for live /nusa status watch subscribers.Applies when: feature-flags.live-dashboard
management.dashboard.max-subscribersinteger161..128 subscriberMaximum admins watching /nusa status watch at the same time.Applies when: feature-flags.live-dashboard
management.dashboard.json-endpoint-enabledbooleanfalsetrue / falseExpose 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-portinteger92401..65535 portLocal TCP port for the optional JSON metrics endpoint.Applies when: feature-flags.live-dashboard and json-endpoint-enabled
management.dashboard.json-tokenstring''20..256 printable non-whitespace ASCII when enabledPrivate 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-urlstring''empty or an official HTTPS Discord webhook URLPrivate official HTTPS Discord webhook URL for server health alerts.Applies when: feature-flags.discord-webhook and a valid webhook URL
management.discord.low-tps-thresholdnumber151..20 TPSTPS threshold below which sustained low-TPS alerts trigger.Applies when: feature-flags.discord-webhook and a valid webhook URL
management.discord.low-tps-duration-secondsinteger601..3600 secondsSeconds 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-secondsinteger3001..86400 secondsMinimum cooldown in seconds between alerts of the same category.Applies when: feature-flags.discord-webhook and a valid webhook URL
management.discord.repeated-security-thresholdinteger102..1000000 incidentsBlocked 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-secondsinteger601..3600 secondsTime window in seconds for counting repeated security rejections.Applies when: feature-flags.discord-webhook and a valid webhook URL
management.discord.queue-capacityinteger321..256 alertMaximum outgoing Discord alerts buffered in memory.Applies when: feature-flags.discord-webhook and a valid webhook URL
management.discord.request-timeout-secondsinteger51..30 secondsHTTP timeout in seconds when delivering Discord webhook messages.Applies when: feature-flags.discord-webhook and a valid webhook URL
management.discord.notify-fatal-exceptionsbooleantruetrue / falseSend 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-tpsbooleantruetrue / falseSend a Discord alert when sustained low TPS is detected.Applies when: feature-flags.discord-webhook and a valid webhook URL
management.discord.notify-module-disabledbooleantruetrue / falseSend 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-securitybooleantruetrue / falseSend a Discord alert summary when a connection repeatedly triggers packet guards.Applies when: feature-flags.discord-webhook and a valid webhook URL
Nusa product documentation · NusaSpigotPaper fork · Java 21 / 25

Loading the index…