NyxLagScope - Find What Lags 1.0.0

Most lag comes from a few chunks: a redstone clock nobody turned off, a hopper wall, a mob farm whose collection broke, eighty cows in a pen. Timings tools tell you which code is slow, not which place. NyxLagScope finds the place, explains it in plain words, and slows it down instead of deleting a player's work.

How it works

1. Scan while playing. /lagscope scan 30 listens to every loaded chunk for 30 seconds: redstone changes, hopper transfers, pistons, mob spawns, item drops, flowing water, explosions, chunks loaded again and again.
2. Count. Then it counts what each chunk contains: mobs, villagers, dropped items, minecarts, hoppers, furnaces, spawners and other ticking blocks. The counting is spread over several ticks (2 ms per tick at most by default), so the scan never lags the server itself.
3. Rank. Each chunk gets a score from what it contains and what happens in it. The report lists the worst chunks, with the share of the load they hold.

Features

• Plain-language report. "Redstone 57k changes/min, busiest at -1012 69 -308": no timings to decode. Each line is clickable: details, teleport.
• Chunk details with advice. Every cause comes with what it means and what to do ("a clock that never stops: add a lever so it only runs when needed"). The busiest block is pointed out, one click to go there.
• In-game heat map. /lagscope map colours every chunk around you from green to red and labels the worst ones. Only you see it, it is never saved, it hides itself after 5 minutes.
• Optimize without deleting. /lagscope optimize makes a chunk cheaper and keeps everything in it: redstone dust, repeaters, comparators and lamps change state at most twice a second, pistons fire once a second, hoppers move one item a second, spawners are capped, extra mobs are put to rest (they stay, keep their name and items, but stop thinking), and loose items are merged. Clocks and farms keep working, slower. Only the measures that match what the scan found are applied, with a preview first.
• Optimize the worst in one click, see the gain. /lagscope optimize top treats the 5 worst chunks, then scans again and shows each score before and after. On our demo base: 1,666 → 246 points (-85%), nothing removed.
• Optimizations stay until you undo them. They survive restarts (optimized.yml); /lagscope optimize list and /lagscope optimize off undo any of them, mobs wake up.
• Merge the loot instead of deleting it. Identical dropped items become full stacks and experience orbs one orb: players keep every item and every point of XP, the server ticks far fewer entities. Deleting is still there for real junk. Every fix is previewed first and can be undone for 10 minutes (/lagscope undo).
• Safe by default. Named, tamed, leashed and riding mobs and mobs of other plugins are never removed; villagers only if you allow it. Items that can never be picked up or never despawn (shop displays) are kept. Players near a cleaned chunk are told what happened (can be turned off).
• Spawn limits (optional). Cap a mob type per chunk for breeding, spawners and eggs. Natural spawning is never touched.
• Lag alerts. When the server stays above 45 ms per tick, staff are told, a short scan finds the worst chunks, and the alert can be posted to a Discord webhook.
• Menu. /lagscope menu: the worst chunks as items (shift-click to optimize), scan, optimize the worst, heat map and undo one click away.
• Costs nothing between scans. NyxLagScope registers its listeners at the start of a scan and removes them at the end.

Commands & permissions

• /lagscope (aliases /lscope, /nyxlag) — open the menu
• /lagscope scan [seconds] — scan for 5 to 300 seconds (30 by default)
• /lagscope report — the last report · /lagscope chunk <rank> — details of a chunk
• /lagscope here — what makes the chunk you stand in expensive
• /lagscope map [on|off] — heat map · /lagscope tp <rank> [spot] — go to a chunk or to its busiest block
• /lagscope status — TPS, ms per tick, chunks, entities and ticking blocks per world
• Permission nyxlagscope.use for all of the above
• /lagscope optimize <rank|here>, /lagscope optimize top [n], /lagscope optimize list, /lagscope optimize off <n|here|all> — nyxlagscope.optimize
• /lagscope fix merge <rank|here>, /lagscope fix items <rank|here>, /lagscope fix mobs <rank|here> <type> <keep>, /lagscope undo — nyxlagscope.fix
• Lag alerts — nyxlagscope.alerts · /lagscope reload — nyxlagscope.admin (includes all the others)

All permissions are given to operators by default.

Installation

1. Drop NyxLagScope-1.0.0.jar into your plugins/ folder and restart the server (Java 21 or newer).
2. Run /lagscope scan while players are online, then /lagscope report or /lagscope map.
3. Optional: tune plugins/NyxLagScope/config.yml (every option is commented), pick the language, set the lag alert threshold or a Discord webhook, then /lagscope reload.

No internet connection is needed: the plugin never contacts any server, except the Discord webhook you set yourself (off by default).

Compatibility

• Tested in game on Paper 1.21.11, 26.2 and 26.3, and on Folia 1.21.11 (on Folia, chunks are read by the region that owns them; lag alerts are off because Folia has no single server tick).
• Java 21 or newer. No other plugin needed.
• Every message is in lang/en.yml and lang/fr.yml (MiniMessage), every option is commented in config.yml, including the weight of each lag source in the score.

Good to know
The score is an estimate built from what a chunk contains and what happens in it: Paper does not measure the time spent in each chunk. The -85% above is that score, measured by a new scan after optimizing. It is made to find the places worth looking at, and the weights can be tuned in config.yml. When nothing stands out, the report says so: your lag probably comes from somewhere else (plugins, view distance, player count).

Support
Questions, bugs, suggestions: join the NyxStudio Discord and open a post in #support, or send a message to Nyx_Studio on voxel.shop. Bug reports with your server version and the output of /lagscope status get fixed fastest.