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

  1. 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.
  2. Never run /reload. Reloading leaks memory and breaks plugin listeners. Always stop and start the server cleanly when adding, updating, or removing JARs in plugins/.
  3. 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):

  1. Set online-mode=false in server.properties on the backend NusaSpigot server (authentication happens on the proxy).
  2. Recommended (Velocity): Enable proxies.velocity.enabled: true, proxies.velocity.online-mode: true, and paste your forwarding.secret inside config/paper-global.yml.
  3. BungeeCord: Set settings.bungeecord: true in spigot.yml and firewall your backend server port so nobody can connect directly bypassing the proxy.
  4. 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 doctor

nusa 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 on immediately 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 start or /spark health) to pinpoint which plugin or world entity is responsible.
  • Remember to turn /nusa safemode off once testing is done (safemode also resets automatically on restart).
Nusa product documentation · NusaSpigotPaper fork · Java 21 / 25

Loading the index…