Changelog

Added

• Hopper limiter: Cached per-chunk hopper counts to enable soft-cap–based cooldown scaling.
  
  • New concurrent cache: hopperCountByChunk keyed as "world:x,z".
    
  • Lazy initialization: If a loaded chunk has no cache entry at use time, it’s scanned and cached.
    
  • Event-driven updates:
    
    • ChunkLoadEvent: scan and seed cache.
      
    • ChunkUnloadEvent: remove cache and related per-chunk tick maps to prevent leaks.
      
    • BlockPlaceEvent (HOPPER): increment chunk count.
      
    • BlockBreakEvent (HOPPER): decrement chunk count (floors at 0).
      
  • Debug messaging for throttling per chunk uses the existing key debug.hopper.throttling from messages.yml (rate limited to once per 100 ticks per chunk).
    

Changed

• Hopper cooldown computation now properly applies the soft cap:
  
  • Base cooldown: lag-prevention.hopper-limiter.transfer-cooldown ticks (min 1).
    
  • If hopper count in the chunk > max-hoppers-per-chunk, effective cooldown increases by 2 * (excess) ticks.
    
• The count method is now cache-backed:
  
  • countHoppersInChunkCached(Chunk) returns the cached number, performs a synchronous scan if necessary for loaded chunks, and returns 0 for unloaded chunks (no forced chunk loads).
    

Fixed

• Soft-cap effect was previously ineffective because hopper counts always returned 0; now it reflects real counts and increases cooldown in hopper-dense chunks.

Performance/Memory

• Event-driven cache maintenance avoids per-tick scanning.
• Lazy scan only occurs on first access for loaded chunks without a cache entry.
• Cleanup on ChunkUnloadEvent prevents memory leaks by removing:
  
  • hopperCountByChunk, lastMoveTickByChunk, lastLogTickByChunk entries for the chunk.
    

Compatibility

• Java 17+, Spigot/Paper 1.17+ APIs.
• No changes to permissions, commands, or message keys.
• Configuration keys reused:
  
  • lag-prevention.hopper-limiter.enabled
    
  • lag-prevention.hopper-limiter.transfer-cooldown
    
  • lag-prevention.hopper-limiter.max-hoppers-per-chunk
    
  • debug
    

[HR][/HR]

How to test the new hopper limiter behavior

1) Build and install

• Build the plugin (build completed successfully during this session).
• Place the generated JAR into your server’s plugins folder.
• Start the server.

2) Configure
In plugins/ClearLaggEnhanced/config.yml:
Reload:

• /lagg reload (or restart the server).

3) Baseline verification (≤ cap)

• In a single chunk, place 5 hoppers (equal to the configured cap).
• Set up a simple hopper-to-chest item transfer.
• Observe transfers occur at the base cooldown (8 ticks in the example).
• With debug on, you should not see persistent throttling logs for this chunk.

4) Soft-cap scaling (> cap)

• Increase hoppers in the same chunk to 8 (3 above cap).
• Expected effective cooldown: base + (2 * excess) = 8 + (2*3) = 14 ticks.
• Observe that transfers are slower (roughly 75% speed of baseline).
• With debug enabled, you should periodically see:
  debug.hopper.throttling once per ~100 ticks per chunk (rate-limited).
• Reduce back to 5 hoppers; transfers should return to the base rate on the next allowed move.

5) Event-driven cache updates

• Block place:
  
  • Place a hopper in the test chunk and confirm the slowdown increases immediately (no server reload).
    
• Block break:
  
  • Break a hopper and confirm slowdown decreases accordingly (no server reload).
    
• Chunk load:
  
  • Move far enough away (or use a second account) so the test chunk unloads, then return to load it.
    
  • On reload, behavior should match the current in-world number of hoppers (cache is reseeded).
    
• Chunk unload:
  
  • Move away to unload the chunk; ensure no debug spam continues for that chunk; upon coming back, the count re-initializes and matches reality.
    

6) Unloaded chunk behavior

• When a chunk is unloaded, the system treats the count as 0 (no extra cooldown added due to unknown state).
• This minimizes false throttling for inactive areas.

7) Stress/regression checks

• Place 30+ hoppers in a single chunk and verify transfers are heavily throttled without server lag spikes.
• Verify other systems remain unaffected:
  
  • Entity clear commands still function (/lagg clear, /lagg next, /lagg tps).
    
  • Messages resolve correctly (check messages.yml entries still appear).
    
• TPS stability:
  
  • Monitor /lagg tps or your profiler; event-driven design should avoid per-tick overhead.
    

8) Optional observability

• If you have a diagnostics command or profiler, confirm:
  
  • No growth in per-chunk maps after chunk unloads.
    
  • Hopper counts change as you place/break hoppers.
    

[HR][/HR]

Quick reference: expected messages and keys

• Debug throttling message key: debug.hopper.throttling in messages.yml
  
  • Placeholders: {x}, {z} (chunk coordinates).
    

[HR][/HR]

Rollback plan

• Set lag-prevention.hopper-limiter.enabled: false to disable hopper throttling entirely if needed.
• Revert to a previous plugin build if you need to remove the feature.