Chunk Optimization
Block Limiter
The block limiter caps the number of identical blocks per chunk. It's the most flexible way to stop hopper / piston / TNT farms from tanking your TPS.
- Per-material caps — Set a different limit for any block type (hoppers, observers, pistons, TNT, dispensers, ...)
- Full event coverage — BlockPlace, BlockBreak, BlockBurn, Piston push/pull, Explosion, Ignite, HangingPlace, VehicleCreate
- Cross-chunk pistons — Tracks blocks moving between chunks via piston extension
- Async scanning — Chunks are scanned asynchronously and cached with a 2-hour Caffeine TTL
- Anti-spam messages — Players hitting a limit don't get spammed with chat messages
Entity Limiter
Refused at the door. With prevent-over-limit-spawns (on by default) breeding, eggs and dispensers are turned down when the chunk already holds its cap, and the player is told why — instead of watching half a pen disappear a minute later. The sweep below still handles what was already there when a limit is lowered.
Enforces per-entity-type limits per chunk. The background sweep runs every 5 minutes and removes excess entities — silently or with a configurable broadcast.
- Per-type caps — Different limits for zombies, cows, item frames, armor stands, etc.
- Visible-only filter — Uses
isVisibleByDefault()so plugin-created invisible entities are ignored - Auto cleanup — Background task trims excess entities to the configured cap
Tile Entity Limiter
Caps the total number of tile entities (chests, hoppers, signs, beacons, etc.) per chunk. The default cap is 256, which matches the threshold that typically becomes load-time-noticeable on modern servers.
The check fires on BlockPlace when the placed block is a TileState. Players hitting the limit see tile-entity-limit-reached with current count and limit.
Chunks GUI
/chunks opens a paginated GUI listing every loaded chunk with a full breakdown — entity count, tile entity count, redstone components, computed cost, plus the top 5 entity types and top 5 tile types per chunk. Left-click any entry to teleport to its center.
Both entry points sort by descending cost, heaviest first, and chunks that cost nothing are left out — there are thousands of them and they answer no question.
The menu and /xantilag top read the same scan, cached for ten seconds and bounded by chunk-limits.max-chunks-per-check. They can therefore never disagree, and opening the menu on a busy server no longer schedules one region task per loaded chunk.
| Mechanic | Value |
|---|---|
| Cost formula | entities × 1 + tile_entities × 2 + redstone × 0.5 |
| Items per page | 45 |
| Navigation slots | 48 (previous) / 50 (next) |
| Folia safety | Each chunk is sampled on its owning region thread |
| Layout | Driven by guis/chunks.yml + lang/<code>.yml |