ChunkGuard

ChunkGuard is a lightweight, high-performance entity management plugin for Minecraft Paper 1.21+ servers. It protects your server's TPS and your players' client-side FPS by strictly limiting the number of specific entities and blocks that can exist within a single chunk, without breaking legitimate vanilla mob farms.

Key Features

• Smart Mob Farm Exemption: Automatically ignores hostile mobs generated by natural spawners or biome generation, allowing traditional mob farms to function perfectly while still preventing spawn egg and dispenser abuse.
• Granular Entity Limits: Define exact maximum limits per chunk across multiple categories, including hanging entities (Item Frames, Paintings), transportation (Boats, Minecarts), passive animals, and hostile mobs.
• Targeted Monitoring: Toggle specific checks on or off via the config (e.g., monitor only placements but ignore natural spawning) to customize the exact level of protection your server needs.
• Non-Intrusive Notifications: Alerts players with a clean Action Bar message when they hit a limit, preventing chat spam while keeping them informed.
• In-Game Commands: Use /chunkguard status [page] to browse all tracked entity limits in a paginated view, /chunkguard reload to hot-reload the config without a restart, and /chunkguard help for a full command reference.
• Clean Console Output: The console stays completely silent during normal operation. Block warnings are always logged when a limit is enforced, while verbose attempt logging is gated behind an optional debug mode for fine-tuning.

Functionality

While standard lag-clearing plugins are fantastic for cleaning up dropped items, they don't solve the issue of a player placing 400 Item Frames in their storage room or breeding 200 cows in a 1x1 pen. These dense clusters of entities cause massive client-side frame drops and severe server-side ticking lag.

ChunkGuard acts as a strict, invisible boundary. It actively listens to player interactions, mob spawning, and block placements. If a player attempts to place a 21st Item Frame in a chunk where the limit is set to 20, the placement is instantly canceled, the item stays in their hand, and they receive a gentle warning in their action bar.

The Smart Spawning System

A common issue with chunk limiters is that they break player-built mob grinders. ChunkGuard solves this by evaluating the reason an entity spawned.

If a zombie spawns from a dungeon spawner or naturally in the dark, ChunkGuard allows it, ensuring your players' hard-built farms continue to yield drops. However, if a player tries to bypass server limits by spamming Zombie spawn eggs or using a dispenser, ChunkGuard will immediately step in and block the spawn once the chunk limit is reached. Note: Passive animals (like cows or pigs) are always limited, regardless of how they spawn, to prevent infinite breeding lag machines.

Permissions

Installation & Configuration

ChunkGuard is a server-side plugin designed specifically for Paper 1.21+. Simply drop the JAR file into your plugins folder and restart your server.

The generated plugins/ChunkGuard/config.yml comes pre-configured with highly balanced, server-friendly defaults for every major entity type (e.g., max 30 Pigs, 20 Item Frames, 10 Minecarts per chunk). You can easily adjust these numbers, uncomment projectile limits, or toggle specific monitoring features to perfectly match your server's hardware constraints.

🛠 Support & Bug Reports

Found a bug or need help setting up the plugin?
Report issues directly on Discord.