HopperLimiter | Paper & Folia v1.0.1

Hard Chunk Caps

Full Folia Support

Auto Overflow Removal

Zero Config Required

▌ Overview​

▌ Features​

Placement Enforcement​

• Real-time block placement blocking cancels hopper placement the instant the limit is reached
• Hopper minecart blocking intercepts PlayerInteractEvent and EntitySpawnEvent to stop minecart hoppers too
• Per-placement chunk re-scan cache is verified against live tile entities before every decision, preventing drift
• Permission bypass configurable permission node lets trusted staff or donors place freely
• Denial message fully configurable message shown to blocked players with current count and limit

⚖ Three Counting Modes​

• COMBINED block hoppers and hopper minecarts share a single pool (e.g. max 32 total)
• SEPARATE each type has its own independent cap (e.g. 24 block + 8 minecart)
• WEIGHTED each type carries a configurable weight against a shared budget (e.g. minecarts cost 2× a block hopper)

Periodic Validation & Overflow Removal​

• Configurable validation interval re-scans all tracked chunks on a fixed schedule
• Batched processing chunks processed across ticks (chunks-per-tick) to avoid validation spikes
• Overflow removal automatically removes excess hoppers when a chunk exceeds its cap
• Three removal priority modes remove by distance from chunk centre, Y level, or age
• Block hopper actions BREAK (drops item) or REMOVE (silently deletes)
• Minecart hopper actions REMOVE (entity deleted immediately)
• Stale chunk cleanup unloaded chunks are automatically evicted from the cache

Folia Region-Safe Architecture​

• Validation timer runs on GlobalRegionScheduler
• Each chunk's validation dispatched to its own RegionScheduler thread no cross-region access
• Entity removal backup uses EntityScheduler safe under Folia's per-entity threading
• Startup chunk scan dispatches every addChunk call to the correct region thread
• plugin.yml declares folia-supported: true

Chunk Tracking​

• ConcurrentHashMap-backed cache thread-safe reads from any context
• Tracks chunks only when player-loaded (isEntitiesLoaded()) no waste on force-loaded farm chunks
• Cache populated on ChunkLoadEvent and cleared on ChunkUnloadEvent automatically
• Hot reload rescans all loaded chunks and rebuilds the cache from scratch

▌ Commands & Permissions​

Permission Nodes​

• hopperlimiter.reload reload configuration (default: op)
• hopperlimiter.bypass place hoppers beyond the chunk limit (configurable node name)

▌ Configuration Highlights​

# Hopper Limiter Configuration
# Counting mode: COMBINED, SEPARATE, or WEIGHTED
counting-mode: COMBINED
# Limits for different modes
limits:
  combined: 50  # Used in COMBINED mode
  block-hoppers: 30  # Used in SEPARATE mode
  hopper-minecarts: 20  # Used in SEPARATE mode
# Weights for WEIGHTED mode
weights:
  block-hopper: 1
  hopper-minecart: 2
max-weight: 50  # Used in WEIGHTED mode
# Validation interval in seconds (30-120 recommended)
validation-interval: 60
# Chunks processed per tick during validation (prevents lag spikes)
# Lower values = smoother but slower validation
# Higher values = faster but may cause lag
# Recommended: 3-10 chunks per tick
chunks-per-tick: 5
# Overflow handling actions
overflow-handling:
  block-hoppers: BREAK  # BREAK or REMOVE
  hopper-minecarts: REMOVE  # REMOVE only
# Removal priority: distance, y-level, or age
removal-priority: distance
# Permission system
enable-permission-bypass: true
permission-node: hopperlimiter.bypass
# Player notification messages
messages:
  enabled: true
  block-hopper-denied: "&cCannot place hopper! Chunk limit reached (&e{current}/{limit}&c)"
  hopper-minecart-denied: "&cCannot place hopper minecart! Chunk limit reached (&e{current}/{limit}&c)"

▌ Technical Details​

• Server software: Paper 1.20.1+ and Folia fully region-safe
• Java version: Java 17+
• Hard dependencies: None
• Soft dependencies: None
• Thread model: Validation timer → GlobalRegionScheduler · Per-chunk work → RegionScheduler · Entity removal → EntityScheduler
• Cache: ConcurrentHashMap keyed by world + chunk coordinates safe for concurrent reads
• Hot reload: /hl reload unregisters listeners, rebuilds all services, and rescans live chunks
• Performance: Only scans tile entities and entities within tracked player-loaded chunks no world iteration overhead

Support​