Feature flags | NusaSpigot Docs

Choose a switch deliberately

False disables the named module without automatically disabling other modules. Avoid turning off every guard to investigate one legitimate item. Test one change on staging, restart, and compare the result.

The behavior master controls its own switches and preset overrides. AI precompute, tracking, and hopper flags remain independent. Wizard and status controls are also independent. Safemode is a broader emergency runtime bypass.

Switch reference

All options below belong in nusa-global.yml and require a full restart. Missing keys use defaults. Ranges include both ends unless marked >.

Complete key	Type / default	Range / unit	Purpose, effects, and when to change
`feature-flags.async-chunk-io`	boolean`true`	true / false	Use a dedicated physical region I/O pool. Disable for a controlled comparison with Paper scheduling; synchronous calls still wait for main commits.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.region-file-compression`	boolean`true`	true / false	Write Nusa zstd regions. Disable before migration if Paper format is required; this does not convert old zstd chunks.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.async-playerdata-save`	boolean`true`	true / false	Write detached player-save snapshots through separate I/O workers. Disable for storage diagnosis, not as a backup substitute.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.ai-precompute-queue`	boolean`true`	true / false	Precompute target candidates from snapshots. Final AI, events, pathfinding, and movement stay on main. Profile whether it helps.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.entity-tracking-culling`	boolean`true`	true / false	Calculate visibility candidates including line of sight. Can hide entities behind solid walls; disable for native distance-only tracking.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.hopper-tick-spreading`	boolean`true`	true / false	Spread eligible idle hopper retries. Related inventory listeners restore native polling.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.entity-behavior-switches`	boolean`true`	true / false	Master switch for native behavior controls and preset effects. False restores native behavior for this module, including HUB overrides.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.nbt-packet-validation`	boolean`true`	true / false	Validate network NBT/component structure. Low limits can reject legitimate custom items; retain protection unless diagnosing a specific issue.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.crash-pattern-guard`	boolean`true`	true / false	Apply payload caps and configured literal rules. Does not recognize every exploit; broad rules can reject valid traffic.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.packet-flood-detection`	boolean`true`	true / false	Limit inbound PLAY frame counts per connection. Test legitimate client/plugin bursts before changing limits.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.tick-starvation-guard`	boolean`true`	true / false	Apply a cooperative main-thread player-handler budget. Bounded FIFO deferral can add input latency.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.redstone-abuse-limiter`	boolean`true`	true / false	Bound redstone callbacks per chunk. Dense circuits may run later; full queues can drop updates.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.miscellaneous-security`	boolean`true`	true / false	Enable placement-NBT policy and recognized downloader-request limiting. Does not identify all downloading clients.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.netty-native-transport`	boolean`true`	true / false	Try supported native transport, subject to Paper and OS policy. False selects NIO for TCP.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.chunk-compression-batching`	boolean`true`	true / false	Group serialized chunk scheduling/flush work. Each packet retains its own compression frame; delivery may be delayed.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.netty-tuning`	boolean`true`	true / false	Use Nusa flush/socket controls. False retains Paper tuning behavior.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.pre-generation`	boolean`true`	true / false	Allow pregen commands and generation admission. Does not change other network modules.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.shared-packet-encoding`	boolean`true`	true / false	Reuse eligible native immutable numeric encodes. Chat, metadata, inventory, and plugin codecs keep ordinary encoding.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.tiered-entity-updates`	boolean`true`	true / false	Reduce far player position cadence and coalesce movement locators. May reduce visual smoothness, including nearby under congestion.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.batch-tab-list`	boolean`true`	true / false	Batch compatible numeric tab updates. The window can delay display; ordering barriers remain.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.pooled-broadcast-buffers`	boolean`true`	true / false	Use pooled buffers for eligible numeric broadcasts. Paper may already pool memory; measure any benefit.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.tuning-wizard`	boolean`true`	true / false	Allow console setup previews. Disabling does not disable status.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.live-dashboard`	boolean`true`	true / false	Enable status and related sampling. The optional JSON listener also depends on this flag.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.discord-webhook`	boolean`false`	true / false	Opt into external alert delivery. Requires a private valid webhook; delivery is best effort.Applies when: startup; safemode bypasses optimizations/guards while retaining management features
`feature-flags.external-ai-advisor`	boolean`false`	true / false	Optional analysis component flag. The embedded UI is removed; this alone does not establish current cloud availability.Applies when: startup; safemode bypasses optimizations/guards while retaining management features

Verify the effect

Test actual gameplay rather than only checking a boolean. Startup resources need a restart for normal replacement. Disabling region compression does not undo the format already written; see zstd compatibility.