🚀 CLE Beta-v2.3

Config Version: 5

💡 Note: This update introduces a new config version (5).
Existing configurations will be automatically merged with new defaults.

Changes:

• Added more than one notification feature. (Can have all 3 notification methods enabled if you so wish.)
• Code cleanup
• Changed config version to #4 (Should auto update when you run the new update)

Updates:

• Removed Hopper Limiter due to high thread usage.
• Removed Redstone Limiter due to aggressive behavior.

Redstone Limiter will return after the rework is complete. No need to update the plugin, disable those two features.

Update 2.0 The Folia Update!

• Reworked redstone limiter
• 100% supports folia
• Updated README
• Optimized plugin performance (0.1% thread usage)
• Optimized SQLite Database

A helpful guide for the Redstone Limiter:

redstone-limiter:
  enabled: true              # Set to true to enable
  reset-period-ms: 4000      # Reset counters every 4 seconds

  blocks:
    enabled: true
    threshold:
      GLOBAL: 6              # Default limit for all redstone blocks
      PISTON: 6              # Pistons can activate 6 times per reset period
      OBSERVER: 12           # Observers can trigger 12 times per reset period
      DISPENSER: 6
      REPEATER: 10
      HOPPER: 12

  chunks:
    enabled: true
    threshold: 4000          # Maximum total redstone events per chunk

  max-piston-push: 12        # Maximum blocks a piston can push at once

redstone-limiter:
  enabled: true
  blocks:
    threshold:
      PISTON: 10           # Allow more complex contraptions
      OBSERVER: 20
      REPEATER: 15
  chunks:
    threshold: 8000        # Higher limit for creative builds

redstone-limiter:
  enabled: true
  blocks:
    threshold:
      PISTON: 6            # Standard settings work well
      OBSERVER: 12
  chunks:
    threshold: 4000

redstone-limiter:
  enabled: true
  blocks:
    threshold:
      PISTON: 4            # Stricter limits
      OBSERVER: 8
      REPEATER: 6
  chunks:
    threshold: 2000        # Lower chunk threshold
  max-piston-push: 8       # Reduce piston push limit

Special Thanks to R00tB33rMan for helping make this update possible. If you have any bugs please join the Discord and report them. <3

ClearLaggEnhanced Changelog

[1.4-Beta]

✨ Added

• Lombok Support - Added Lombok framework for cleaner code
• Database Indexes - Added 3 strategic indexes to laggy_chunks table for 10-100x faster queries
  • idx_laggy_chunks_world - Fast world filtering
  • idx_laggy_chunks_entity_count - Fast sorting by entity count
  • idx_laggy_chunks_composite - Fast chunk lookups by coordinates
• Auto-Update System - Config and messages files now automatically update while preserving user customizations
  • Automatic backups created (e.g., config.yml.backup-v1)
  • Smart merging of new values with user settings
  • Version tracking for both config.yml and messages.yml
• Professional Messages - Complete overhaul of messages.yml
  • Consistent color scheme with documentation
  • Added icons (✓, ✗, ⚠, ⏰, ⚡, etc.)
  • Better formatting with borders and bullets
  • All messages now properly colored
• Java Records - Converted data classes to use modern Java 17 records

🔧 Changed

• Entity Clearing Logic - Completely refactored for better UX
  • BREAKING: Removed confusing blacklist system
  • Now uses whitelist-only approach: "Clear everything EXCEPT whitelisted entities"
  • Items on ground (DROPPED_ITEM) now properly clear by default
  • Living entities clear by default unless whitelisted
  • Much more intuitive for server owners
• Database Schema - Changed world column from TEXT to VARCHAR(255)
  • 50-70% storage reduction for world names
  • Better indexing performance
• Config Defaults - Updated default world list
  • Changed from ["world_nether", "world_the_end"] to [] (all worlds)
  • More sensible defaults for new installations
• Whitelist - Refined default protected entities
  • Added: CAT, PARROT, GLOW_ITEM_FRAME, CHEST_MINECART, FURNACE_MINECART, HOPPER_MINECART, CHEST_BOAT
  • Removed: OAK_BOAT (consolidated to BOAT)

⚡ Performance

• Main Thread Optimization - Removed unnecessary runTask() calls
  • ClearCommand.java - Direct execution (saves ~1-2ms per operation)
  • MobLimiterListener.java - Direct execution in MONITOR event
  • Reduced main thread blocking and task queue overhead
• Database Performance - Query speed improvements with new indexes
  • ChunkFinder queries 10-100x faster as data grows
  • Efficient world-specific filtering
  • Optimized sorting by entity count

🐛 Fixed

• Entity Clearing Bug - Items on ground now properly clear
  • Previous logic only cleared items in blacklist
  • New logic clears all non-whitelisted entities
• Config Migration - Improved existing migration system
  • Better handling of deprecated keys
  • Clearer console output during migration
  • Fixed edge cases in setting preservation

🗑️ Removed

• Blacklist System - Removed from config.yml (36 lines)
  • Confusing two-list system replaced with simpler whitelist-only
  • Old blacklist entries automatically converted during migration

📝 Technical Details

• Lombok Dependency: 1.18.30
• Config Version: 1 → 2 (auto-migration implemented)
• Messages Version: 1 → 2 (auto-migration implemented)
• Java Version: 17 (using records and text blocks)
• Code Cleanup: Removed all inline comments per project style

Migration Guide

From 1.3 to 1.4

Automatic Migration

When you first start v1.4, the plugin will:

1. Detect outdated config (v1) and messages (v1)
2. Create backups: config.yml.backup-v1 and messages.yml.backup-v1
3. Merge your customizations with new defaults
4. Log all migrated settings to console

Manual Steps (Optional)

None required! Everything is automatic.

Breaking Changes

1. Blacklist Removed: If you relied on blacklist behavior, adjust your whitelist:
   • Old: Blacklist = entities to clear
   • New: Whitelist = entities to protect, everything else clears

Reverting

If you need to revert:

1. Stop server
2. Restore from backup: cp config.yml.backup-v1 config.yml
3. Edit config-version: 1 in config.yml
4. Start server with old plugin version

Performance Impact

Added — Per‑Chunk Entity Limiter (Armor Stands, Boats, etc.)

• New limiter that caps the number of specified non-mob entities per chunk (e.g., armor stands, boats, minecarts, item frames, paintings).
• Actively detects over-cap scenarios even if players move entities into a chunk (e.g., via water streams, pistons)—not just at spawn time.
• Automatically removes the excess entities beyond the configured cap and sends a staff notification with world, chunk coordinates, entity type, and count removed.
• Fully configurable caps per entity type, worlds to include/exclude, check intervals, selection priority for removal, and notification throttling.
• Optional bypass permission for trusted users so their placed entities are not counted or removed.

Configuration

• Configure per-entity caps per chunk, globally or per-world.
• Choose which entities are monitored (e.g., ARMOR_STAND, BOAT, MINECART variants, ITEM_FRAME, PAINTING, TNT_MINECART, etc.).
• Control how “excess” entities are chosen for removal (e.g., oldest first, furthest from center, random) to minimize disruption.
• Set staff notification options (enabled, message format, permissions, cooldown to prevent spam) and console logging.
• Define excluded worlds or regions if needed.

Notifications and Permissions

• Staff alert sent on first detection and then rate-limited: e.g., "[ClearLaggEnhanced] Chunk x=12,z=-34 in world ‘survival’: removed 8 excess ARMOR_STAND (limit=12)."
• Console log entry mirroring the alert (optional).
• Suggested permissions (adjust to your plugin’s scheme):
  • clearlagenhanced.limiter.notify — receive staff alerts
  • clearlagenhanced.limiter.bypass — player’s entities aren’t counted/removed

Behavior

• Triggers on spawn, chunk load, and periodic sweeps to catch entities moved post-spawn (water, pistons, minecarts, leads, boats, etc.).
• Removal is safe and batched to avoid lag spikes. Limits apply per chunk to prevent dense stacks.

Example — How It Works

1. Example configuration (YAML-style, adapt to your config format):

entity-limiter:
  enabled: true
  check-interval-ticks: 200   # every 10 seconds
  notify:
    enabled: true
    permission: clearlagenhanced.limiter.notify
    cooldown-seconds: 60
  selection-policy: OLDEST     # OLDEST | FURTHEST | RANDOM
  limits:
    ARMOR_STAND: 12
    BOAT: 8
    MINECART: 16
  worlds:
    include: ["survival", "skyblock"]
    exclude: []
  bypass-permission: clearlagenhanced.limiter.bypass

1. In-game scenario:

• A player sets up a water stream that pushes 30 armor stands into a single chunk.
• On the next sweep (or when the chunk loads), the plugin detects 30 ARMOR_STAND in that chunk where the limit is 12.
• The plugin removes 18 excess armor stands using the OLDEST policy.
• Staff online with clearlagenhanced.limiter.notify see: "[ClearLaggEnhanced] Chunk x=120,z=45 (survival): removed 18 excess ARMOR_STAND (limit=12)."
• Console logs the same event (optional), and further alerts for this chunk are suppressed for the configured cooldown period to prevent spam.

Notes

• If you already use other limiters (mobs, spawners, hoppers, redstone), this feature operates independently and complements them.
• Recommended: tune limits conservatively at first; then adjust based on typical player builds.
• Consider granting the bypass permission to trusted builders to avoid accidental cleanup during creative projects.

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

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:

• Ensure hopper limiter is enabled:
  • lag-prevention.hopper-limiter.enabled: true
• Set a visible base cooldown (example):
  • lag-prevention.hopper-limiter.transfer-cooldown: 8
• Set a testable soft cap (example):
  • lag-prevention.hopper-limiter.max-hoppers-per-chunk: 5
• Optional: enable debug to see rate-limited throttling notices:
  • debug: true

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

• Ensure no chunk forcing:
  • 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.

Quick reference: expected messages and keys

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

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.

Implement advanced throttling features for lag prevention:

• Add HopperLimiterListener to throttle hopper activity.
• Add MobLimiterListener to control mob spawning per chunk.
• Add RedstoneLimiterListener to enforce redstone activity limits.
• Add SpawnerLimiterListener to slow down spawners and cap spawn rates.
• Extend LagPreventionManager to support entity optimization and limit enforcement.