ChunkGuard

ChunkGuard

When the server starts lagging because of a lag machine, you usually have to run around the world looking for whose farm it is. This plugin finds the laggy chunk for you, freezes it, and sends the coordinates to admins.

It only deals with load inside the game. It is not DDoS protection.

How it works

Every second (configurable) the plugin counts events in each chunk: redstone, hoppers, mob spawns, pistons and, optionally, block physics. Each event type has its own weight, and the sum is the chunk's load score for that window.

If a chunk stays above the threshold for several windows in a row (3 by default), it gets frozen. Events of the types you chose are cancelled there, so the chunk stops lagging. Nobody gets kicked, and the players keep playing.

The strike system is there so a single spike, like an explosion or a big farm starting up, doesn't freeze anything.

When a chunk is frozen, admins get a message with the world, coordinates, reason, and the last player who was building nearby. You can also send the same alert to Discord with a webhook.

Features

• Finds lag machines and chunk abuse automatically
• Separate weight for each event type, all of it configurable
• Freezes only the problem chunk, the rest of the world is untouched
• Frozen chunks survive a restart
• Chunk whitelist for farms you trust
• Chat, console and Discord webhook alerts, with a cooldown so it doesn't spam
• Optional auto-clean after a freeze (off by default)
• Ignore specific worlds
• Debug mode to see how much your normal farms score
• All messages are editable in the config

Auto-clean

Off by default. If you turn it on, the plugin cleans the chunk itself after a short delay. Each action is switched on separately:

• entities removes all entities except players, named mobs, tamed pets and the types in keep.types
• machines removes lag machine blocks (redstone, pistons, hoppers, observers and so on, the list is in the config). Terrain and normal builds are not touched
• regenerate tries to regenerate the chunk. Newer versions have no API for this, so the plugin writes a line to the console and falls back to machines if it's enabled

After cleaning, the chunk is unfrozen and admins get a report.

Warning: machines and regenerate delete blocks. If it triggers by mistake, someone can lose a build. Set up the threshold and the whitelist first.

Commands

Main command: /chunkguard (aliases: /cg, /lagshield)

Command	What it does
/cg list	List frozen chunks
/cg tp <id>	Teleport to a frozen chunk
/cg unfreeze <id or all>	Unfreeze a chunk or all of them
/cg whitelist add [world cx cz]	Add a chunk to the whitelist (current chunk if no arguments)
/cg whitelist remove [world cx cz]	Remove a chunk from the whitelist
/cg whitelist list	Show the whitelist
/cg status	Short summary
/cg reload	Reload the config

Permissions: chunkguard.admin for all commands, chunkguard.alert to receive alerts. Both are op-only by default.

Config

window-ticks: 20          # length of one counting window (20 = 1 second)
strikes-required: 3       # windows in a row above the threshold before freezing
threshold: 2500           # load score per window

weights:
  redstone: 1.0
  physics: 0.2
  hopper: 1.5
  spawn: 4.0
  piston: 3.0

monitor:                  # which events to count
  redstone: true
  physics: false          # a lot of events, off by default
  hopper: true
  spawn: true
  piston: true

freeze:
  duration-seconds: 0     # 0 = unfreeze manually
  cancel:                 # what is cancelled in a frozen chunk
    redstone: true
    physics: false
    hopper: true
    spawn: true
    piston: true

auto:
  enabled: false
  delay-seconds: 5
  unfreeze-after: true
  actions:
    entities: true
    machines: false
    regenerate: false

ignore-worlds: []

alerts:
  chat: true
  console: true
  cooldown-seconds: 60
  discord:
    enabled: false
    webhook-url: ""

debug: false

To get started, turn on debug: true for a couple of days and check in the console how much your normal farms score. The threshold should be well above that. If you get false freezes, raise it.

Messages in the config are in Russian by default. You can change them to any language you want.

Compatibility

• Paper, Purpur, Spigot, Bukkit, Folia
• Minecraft 1.20 and newer
• Java 17+
• Uses only the basic Bukkit API, no NMS

Support

Questions or bugs: Discord or the issues tab. Please include your server version and config.

Author: 1mN1kO