LagGuard Pro v1.0

---

LagGuardPro is a lightweight performance protection plugin focused on hot chunks.
It detects where lag is building up and applies staged, configurable actions to keep the server playable — plus PRO tools (GUI, history, Discord alerts, placeholders) to manage performance faster.

---

• Stage system: OK → WARN → SOFT → HARD → EMERGENCY
• Hot chunk report: identify the most problematic chunks (items/mobs/hoppers/spawners)
• Smart item cleanup: safe filters + hot-chunk targeting
• Hopper transfer throttling: chunk-based window limits (reduces transfer spikes)
• Emergency spawn limiter: optional per-chunk mob caps for selected spawn reasons
• Admin GUI: quick toggles + manual hot cleanup + report shortcut
• History recorder: MSPT/TPS/stage sampling + CSV export (history.csv)
• Discord webhooks: stage changes + optional status snapshot (cooldown supported)
• PlaceholderAPI support (optional): useful placeholders for scoreboards

---

Stage System
LagGuardPro evaluates server performance periodically and updates the stage automatically:
OK → WARN → SOFT → HARD → EMERGENCY

Each stage can trigger different actions (fully configurable).

Hot Chunk Tracking
Tracks pressure indicators per chunk:

• ground items
• hostile/passive mobs
• optional tile counts (hoppers/spawners) when supported

Use:

• /lagguard report 10

Smart Item Cleanup (Safe by design)
Cleanup never removes (configurable):

• whitelisted materials
• named items
• lore items
• enchanted items
• unstackable items (max stack size = 1)

Supports hot-chunk-only cleanup for minimal impact.

Hopper Transfer Throttling
When the server is under load, LagGuardPro can throttle hopper transfers per chunk using window limits (configurable).

Emergency Spawn Limiter
Optional per-chunk caps in EMERGENCY stage for selected spawn reasons.

---

• /lagguard status
• /lagguard report [top]
• /lagguard gui
• /lagguard history [minutes]
• /lagguard clearitems [hot|global] [minAgeSec] [max]
• /lagguard dryrun <on|off>
• /lagguard reload
• /lagguard debug chunk <x> <z> [world]

---

• lagguard.view
• lagguard.admin
• lagguard.reload
• lagguard.clearitems
• lagguard.debug
• lagguard.gui
• lagguard.history

---

• %lagguard_stage%
• %lagguard_mspt10%
• %lagguard_mspt60%
• %lagguard_tps1m%

---

• Paper 1.21+ (recommended)
• Java 21+

---

• SAFE (recommended starting point)
• BALANCED
• AGGRESSIVE (for struggling servers)

---

• MSPT/TPS values depend on server implementation and load.
• Hopper throttling is event-based (transfer events), not a full tick scheduler replacement.
• Discord webhooks require outbound HTTPS access (some hosts may block it).

---

• Paper build + Java version
• Plugin version
• plugins/LagGuardPro/config.yml
• Steps to reproduce + relevant logs