Features
Counting Modes
HopperLimiter supports three independent counting strategies. Choose based on how you want to treat block hoppers vs. hopper minecarts.
COMBINED
A single numeric cap covers all hopper types together.
Chunk cap: 50
Block hoppers: 30 + Hopper minecarts: 15 = 45 total ✓
Block hoppers: 30 + Hopper minecarts: 25 = 55 total ✗ → blocked
Best for simplicity. Players must manage their total hopper footprint without caring about the split.
SEPARATE
Block hoppers and hopper minecarts each have their own independent limit.
Block hopper limit: 30 → current: 28 (OK), placing 3 more → blocked at 30
Hopper minecart limit: 20 → current: 19 (OK), placing 2 more → blocked at 20
Best when you want to allow more of one type than the other.
WEIGHTED
Each hopper type has a cost (weight). The chunk's total weight score must stay at or below the configured maximum.
block-hopper-weight: 1
hopper-minecart-weight: 2
max-weight: 50
20 block hoppers (1×20) + 10 minecarts (2×10) = weight 40 ✓
20 block hoppers (1×20) + 16 minecarts (2×16) = weight 52 ✗ → blocked
Best when hopper minecarts are significantly laggier than block hoppers on your setup.
Placement Prevention
When a player tries to place a hopper that would exceed the limit, the BlockPlaceEvent is cancelled. The player receives a configurable message showing the current count and cap.
✗ You cannot place more than 50 hoppers in this chunk! (50/50)
The block is never actually placed — no items are lost.
Overflow Handling & Removal Priority
During periodic validation, if a chunk is found to be over its limit, excess hoppers are removed based on the configured removal-priority:
| Priority | Behaviour |
|---|---|
distance | Hoppers farthest from the chunk center are removed first |
y-level | Lowest Y-level hoppers are removed first |
age | Oldest hoppers (by load order) are removed first |
The overflow-action controls what happens to removed hoppers:
| Action | Behaviour |
|---|---|
BREAK | Hopper breaks naturally, dropping its contents as items |
REMOVE | Hopper is silently deleted with no drops |
Use BREAK on survival servers so players don't lose items. Use REMOVE on creative or restricted servers for clean removal.
Periodic Validation
A background scanner runs every validation-interval seconds across all loaded chunks. This catches hoppers placed via:
- Commands (e.g.
/setblock) - Pistons pushing hoppers between chunks
- Other plugin interference
The scanner processes chunks-per-tick chunks per scheduler tick to avoid TPS spikes.
Permission Bypass
Players with hopperlimiter.bypass can always place hoppers regardless of the chunk limit. This is intended for trusted builders or staff who need freedom without completely disabling the limiter.
Performance Design
- No per-tick scanning — the plugin is purely event-driven for placement prevention
- O(1) chunk lookups — per-chunk counts are cached in memory; no repeated scans needed
- Configurable validation rate — spread background scans across ticks to minimize impact