Low TPS Guard

Low TPS Guard

A server-side watchdog that clears dropped junk blocks only when they are actually the cause of the lag.

Most clear-lag mods wipe entities on a fixed timer, whether the server needs it or not. Low TPS Guard acts only when two things are true at the same time: the TPS is genuinely low, and an entity analysis proves that piles of dropped low-value blocks are the reason. If the lag comes from anything else, the mod stays completely silent.

How it works

1. Measures the real TPS from the wall-clock time between server ticks, using a 5-second rolling window.
2. Waits for a sustained drop. The TPS must stay below the threshold (default 15) for 10 seconds straight, so single-tick spikes from chunk generation or world saves are ignored.
3. Analyses the entities. One pass over every loaded entity counts how many are dropped low-value blocks versus how many entities exist in total. A cleanup starts only if there are at least 500 of them and they make up at least 35% of all loaded entities.
4. Stays quiet otherwise. If dropped blocks are not the cause, nothing is written to chat, and the mod backs off before checking again. No spam.
5. Warns, then clears. A message goes to chat, and after a 5-second countdown the drops are removed, spread over several ticks so the cleanup itself never causes a spike.

Example output:

[Low TPS Guard] TPS dropped to 9.4 (threshold 15.0) because of 4213 dropped blocks. Clearing them in 5 seconds.
[Low TPS Guard] Removed 4213 dropped blocks. (minecraft:cobblestone x3120, minecraft:stone x901, minecraft:dirt x192)

What gets removed

Only dropped items of these types, and only while they lie on the ground:

- Stone
- Cobblestone
- Netherrack
- Deepslate
- Cobbled Deepslate
- Dirt

The list is fully configurable and accepts items from other mods. Falling block entities of the same types can optionally be included. Items renamed in an anvil are always skipped.

Never touched: mobs, animals, villagers, players, experience orbs, minecarts, boats, item frames, armour stands, or any item that is not on the list. The entity type is checked again at the very moment of deletion, so nothing else can ever be removed.

Performance

Removing an entity in Minecraft is a linear search inside its 16x16x16 chunk section, which means deleting one enormous pile in a single tick is itself a lag spike: a benchmark of 32,000 items stacked in one section takes roughly 100 ms. Low TPS Guard spreads the removals across several ticks (500 per tick by default), keeping every tick in the low milliseconds. The scan does not copy the entity list, and it runs only when a sustained TPS drop has already been detected, not every tick.

Commands

/lowtps status - available to everyone. Current TPS, ms/tick, entity counts, and whether a cleanup would trigger right now.
/lowtps clear - OP only. Runs a cleanup immediately.
/lowtps cancel - OP only. Cancels a scheduled cleanup.

Configuration

config/low_tps_mod.toml is created on first start and is reloaded automatically when you edit it, no restart needed. Every parameter is configurable:

- TPS threshold and how long the drop has to last
- How often the TPS is checked
- Detection thresholds: minimum amount of dropped blocks and their minimum share of all entities
- Warning delay, cooldown between cleanups, and a separate cooldown for when the lag has another cause
- Startup grace period
- The item list, whether falling blocks are included, whether renamed items are protected
- How many entities may be removed per tick
- Every chat message, with colour codes and placeholders such as {tps}, {count} and {delay}

Installation

Server-side only. Put the jar into the server's mods folder. Clients do not need the mod, vanilla clients can connect normally.

Requires NeoForge for Minecraft 1.21.1.