LagWarden [1.16.5 - 26.2] — lag machine detector with one-command throttling

The short version

/tps tells you the server is struggling. It does not tell you where or why.

LagWarden answers that: the type of the mechanism, the world, the chunk, the block coordinates, the event
rate per second, how long it has been running, and the likely builder with an explicit confidence level.

Then you deal with it in one command:

The mechanism now runs 8x slower. No blocks were broken, no entities were deleted, the build is intact.
Two minutes later the restriction lifts itself.


The detector

Six types, no cut-down version:

• Redstone clocks and fast pulse generators
• Hopper spam and conveyor loops
• Item spam — droppers, dupe conveyors, mountains of ground items
• Mass entity spawning — spawners, breeding, eggs, minecarts
• TNT and end crystal clusters, frequent explosions
• Lavacasts and cobblestone/obsidian generators

Every finding reports the type, world, chunk, block coordinates, rate per second, duration and the likely
builder. A dual threshold (burst + sustained) plus hysteresis keeps it away from legitimate farms.
Message anti-spam is configurable.


[HR][/HR]

Throttling instead of destruction

Every ticking mechanism produces a stream of events. Suppress a fraction of those events and the mechanism
keeps existing but runs 2x, 4x, 8x or 16x slower.

Command	What it does
/lag throttle <number>	Slow down a detected machine by its number from the findings list or from /lag chunks
/lag throttle chunk [level] [seconds]	Slow down the chunk you are standing in
/lag throttle <cx> <cz> [world] [level] [seconds]	Slow down an arbitrary chunk by coordinates
/lag unthrottle <number|all>	Remove the slowdown
/lag throttles	What is currently throttled and how much time is left

• Level 0..4, meaning x1 / x2 / x4 / x8 / x16. Default x8.
• Default duration 120 seconds, adjustable per command.
• A throttle is always temporary. It expires on its own, and it is also lifted by
  /lag unthrottle, by /lag reload and by disabling the plugin. There is nowhere for it to stick.
• Throttling never breaks blocks and never deletes entities. That is an architectural rule.
• The nearest player gets "your mechanism was slowed down due to server load, the build was not touched",
  so nobody thinks they were robbed.
• At most 64 throttled objects at a time.

[HR][/HR]

Everything else

• /lag — server status. TPS over 10 seconds / 1 minute / 5 minutes, MSPT, memory, loaded chunks,
  total entities, uptime, load profile indicator.
• /lag chunks — problem chunk ranking. Not a plain "most entities" list: a composite load score built
  from entity count, hoppers, other tile entities, redstone events per second, hopper moves per second, item
  spawns, entity spawns and explosives. Each line states the main reason. All weights are configurable.
• /lag inspect — chunk card. Counters for all six detectors, entities by category, hoppers and other
  tile entities, active throttles and the latest placement log entries for that chunk.
• /lag scan — force an immediate full scanner pass when you need the numbers right now.
• /lag entities — entity breakdown by type, per world or for your current chunk.
• /lag tp <number> — teleport to a chunk from the last listing, at a safe height.
• Likely builder. The plugin keeps its own placement log: who placed redstone components, hoppers,
  droppers, spawners and TNT after the plugin was installed. Every report carries a confidence level:
  exact / was nearby / most frequent visitor / unknown. The log is kept in memory and is cleared when
  the server restarts.
• Ground item cleaner on a timer, with 60 / 30 / 10 / 5 second warnings and a strict keep list, plus
  manual /lag clear.
• Per-chunk entity limit in blocking mode. New entities above the limit simply do not spawn.
  Existing entities are never removed.
• Low TPS warning to console and to admins, with the top 3 problem chunks attached, and a recovery
  message when TPS comes back.
• /lag self — the plugin's own overhead, measured, not promised.
• Per-world disabling, English and Russian messages files, /lag reload without a restart.

[HR][/HR]

How this differs from other free anti-lag plugins

Typical anti-lag plugin	LagWarden
Ranks chunks by entity count	Composite load score: entities, hoppers, redstone rate, spawn rate, explosives — with the reason printed
Says "this chunk has a lot of entities"	Says "redstone clock, 380 per second, sustained 74 s, block 205/64/-633"
Has no idea who built it	Keeps a placement log and names a likely builder with a confidence level
Single threshold, so it fires at a 30-hopper sorter	Dual threshold: it needs both a burst and 30–60 seconds of sustained excess, with a dip allowance
Fixes lag by deleting entities and wiping builds	Throttling: the mechanism slows down and stays intact. The plugin never breaks blocks and never deletes player entities
Acts silently and cannot be undone	Every action is announced with numbers and is reverted by a timer, by /lag unthrottle or by /lag reload
Often subscribes to BlockPhysicsEvent and becomes a lag source itself	BlockPhysicsEvent is never used. That is an architectural rule, not a config option

Why the dual threshold matters. A legitimate farm either runs in bursts or runs steadily but an order
of magnitude slower than a lag machine. Defaults are deliberately high: 40 redstone triggers per second
on a single block, while the fastest legal repeater clock is around 5/s; 150 hopper transfers per
second per chunk, while one hopper tops out at 2.5/s — that is roughly 60 hoppers running non-stop in one
chunk. The rule is: better to miss a weak lag machine than to touch someone's farm.

[HR][/HR]

The plugin does not lag your server

• /lag self reports the real overhead — you can verify the claim instead of trusting it.
• Self-limiting. If the plugin uses more than 1% of the tick budget for a minute, it lowers its own
  scanner frequency and logs one warning.
• Zero allocations in hot handlers. No Location objects, no strings, no boxing, no streams inside
  BlockRedstoneEvent, InventoryMoveItemEvent or ItemSpawnEvent. Keys are packed longs stored in a custom
  primitive open-addressing map.
• A disabled feature costs nothing: its listener is not registered at all.
• BlockPhysicsEvent is never used.
• Chunk#getEntities() is never used for bulk scanning — the javadoc states it can force-load
  entities. Counting goes through world.getEntities() once per second, bucketed by coordinates, with a single
  reused Location object.
• Budgeted scanner: at most 8 chunks and 2 ms per pass, a full sweep spread over tens of seconds.
• Heavy work is async: sorting, formatting and file writes never run on the main thread.
• Hard structure limits (10 000 tracked chunks, 20 000 blocks) with eviction of inactive keys.
  Memory growth is visible directly in /lag self.

[HR][/HR]

Item cleaner safety

All of these are on by default:

• min-age-seconds: 30 — freshly dropped loot is never taken.
• keep-named — items renamed in an anvil are kept.
• keep-enchanted — enchanted items are kept.
• keep-materials — a configurable valuables list: diamonds, netherite, ancient debris, elytra,
  totems, enchanted books, shulker boxes, nether star, beacons, dragon egg.
• only-when-players-online — no cleanup runs on an empty server.
• Warnings at 60 / 30 / 10 / 5 seconds, configurable.
• lagwarden.bypass.cleaner exempts a player's items entirely.

The cleaner only touches dropped items lying on the ground. Chests, inventories, item frames and armor
stands are not affected at all.

[HR][/HR]

Installation

1. Download LagWarden.jar from this page.
2. Drop it into your plugins folder.
3. Restart the server (do not use /reload).
4. Open plugins/LagWarden/config.yml, set language and disabled-worlds if needed.
5. Run /lag, then /lag chunks, then /lag inspect 1.

No dependencies. Java 8 or newer. Works on Spigot, Paper and their forks (Purpur, Pufferfish, Leaf).

Commands

Command	Permission	Description
/lag	lagwarden.use	Status: TPS, MSPT, memory, chunks, entities, profile
/lag help	lagwarden.use	Command list
/lag chunks [world] [page]	lagwarden.chunks	Problem chunk ranking with score and reason
/lag entities [world|chunk] [all]	lagwarden.entities	Entity breakdown by type
/lag tp <number>	lagwarden.tp	Teleport to a chunk from the last listing
/lag inspect <number|cx cz [world]>	lagwarden.inspect	Chunk card: counters, entities, hoppers, placement log, throttles
/lag scan	lagwarden.scan	Immediate full scanner pass
/lag clear [world] [confirm]	lagwarden.clear	Immediate ground item cleanup
/lag throttle <number|chunk|cx cz [world]> [level] [sec]	lagwarden.throttle	Slow down a detected machine or a chunk
/lag unthrottle <number|all>	lagwarden.throttle	Remove a slowdown
/lag throttles	lagwarden.throttle	Active slowdowns with remaining time
/lag self	lagwarden.self	The plugin's own overhead
/lag reload	lagwarden.reload	Reload configuration and lift all restrictions

Permissions

Permission	Default	Description
lagwarden.use	op	Base /lag command
lagwarden.chunks	op	/lag chunks
lagwarden.entities	op	/lag entities
lagwarden.tp	op	/lag tp
lagwarden.inspect	op	/lag inspect
lagwarden.scan	op	/lag scan
lagwarden.throttle	op	/lag throttle, /lag unthrottle, /lag throttles
lagwarden.clear	op	Manual item cleanup
lagwarden.self	op	/lag self
lagwarden.reload	op	Reload configuration
lagwarden.notify	op	Receive low TPS and detector messages in chat
lagwarden.bypass.limits	false	Entity limits do not apply to this player
lagwarden.bypass.cleaner	false	This player's items are never cleaned up
lagwarden.admin	op	All of the above

[HR][/HR]

What this plugin does NOT do

• It never acts on its own. The detector reports a finding and stops there; nothing is throttled,
  limited or removed until you type a command. The load profile is an indicator, not a controller.
• It cannot identify who built something older than the plugin. The placement log starts when you
  install it, and it lives in memory, so it also starts over after a server restart. For anything older the
  report says "unknown" or "was nearby", clearly labelled.
• It never breaks blocks. Not in any mode, not with any setting. Throttling slows a mechanism down;
  it does not dismantle it.
• It never deletes player entities. The chunk limit only blocks new spawns.
• It does not change view-distance or server spawn limits. The Spigot API has no setters for those,
  so promising it would be a lie.
• It does not run on Folia. The plugin deliberately refuses to load on Folia instead of breaking
  your server. Folia support is planned for a later release.
• Exact MSPT is Paper-only. On plain Spigot that data is not exposed by the API, so the plugin shows
  an honest estimate and labels it as an estimate.
• No config GUI and no WorldGuard / GriefPrevention integration yet. Both are planned for
  later releases; the integration will ship as a separate add-on jar.
• It does not fix lag caused by other plugins, weak hardware or bad server configuration.

[HR][/HR]

FAQ















Support and feedback

• Bug reports and suggestions: https://t.me/lagwardenbot
• Questions: the discussion tab of this resource.
• When reporting a problem, please include: server software and Minecraft version, plugin version, output
  of /lag and /lag self, your config.yml and the relevant log section.
• Anonymous usage statistics are collected via bStats and can be disabled with metrics: false.