Plugins, proxies & safemode
Run Paper/Spigot plugins, connect Velocity or BungeeCord proxies, and isolate plugin lag with /nusa doctor.
On this page
NusaSpigot preserves every public Bukkit, Spigot, and Paper 1.21.11 API method signature. Standard plugins—including LuckPerms, Vault, WorldEdit, WorldGuard, EssentialsX, Citizens, MythicMobs, TAB, ViaVersion, Geyser, and Floodgate—work without special patches.
Plugin rules to remember
- Download plugins matching Minecraft 1.21.x / Paper. Plugins using internal NMS bytecode (packet/protocol libraries like ProtocolLib, PacketEvents, or Citizens) must support Minecraft 1.21.11.
- Never run
/reload. Reloading leaks memory and breaks plugin listeners. Always stop and start the server cleanly when adding, updating, or removing JARs inplugins/. - One real main thread: NusaSpigot never fakes
Bukkit.isPrimaryThread()on worker threads, so plugins expecting thread-safe Bukkit events behave identically to Paper.
Setting up Velocity or BungeeCord proxies
When running NusaSpigot behind a proxy network (such as Lobby + SMP + Minigames):
- Set
online-mode=falseinserver.propertieson the backend NusaSpigot server (authentication happens on the proxy). - Recommended (Velocity): Enable
proxies.velocity.enabled: true,proxies.velocity.online-mode: true, and paste yourforwarding.secretinsideconfig/paper-global.yml. - BungeeCord: Set
settings.bungeecord: trueinspigot.ymland firewall your backend server port so nobody can connect directly bypassing the proxy. - Geyser/Floodgate on proxy: Install Floodgate on both the proxy and backend servers (sharing the same
key.pem) so NusaSpigot automatically detects Floodgate UUIDs for Bedrock optimization.
Finding laggy or conflicting plugins
If TPS drops or a mechanic acts unexpectedly, isolate the cause in two minutes without guessing:
Step 1: Run /nusa doctor
nusa doctornusa doctor inspects your JVM startup flags, active NusaSpigot modules, and loaded plugins. For example, if a plugin registers global InventoryMoveItemEvent listeners on hoppers, NusaSpigot automatically falls back to vanilla hopper polling where needed to protect plugin accuracy.
Step 2: Test live with /nusa safemode
nusa safemode on
nusa safemode status
nusa safemode off/nusa safemode onimmediately bypasses NusaSpigot optimizations and security guards at runtime—no restart required.- If the lag or bug persists during safemode, run Paper's built-in profiler (
/spark profiler startor/spark health) to pinpoint which plugin or world entity is responsible. - Remember to turn
/nusa safemode offonce testing is done (safemodealso resets automatically on restart).