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

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.

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.

/chunks top reuses the same GUI but sorted by descending cost — the laggiest chunks surface first.

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.yml