CircuitBreaker

⚙️ CircuitBreaker: The Performance Suite

Tired of server-wide lag cleaners that punish players? CircuitBreaker is a smart, high-performance plugin built for Paper servers that finds the exact source of lag—and stops it cold.

[!tip] v2.0 IS HERE! CircuitBreaker is now a 2-in-1 performance suite. It now includes an optional, smart Entity Culler alongside its famous Physics Lag detector!

🛑 Stop Punishing Your Players!

For too long, server owners have had two bad options for fighting lag machines:

• The Sledgehammer (e.g., ClearLagg): This clumsy approach deletes all entities and items server-wide. It punishes innocent players, creates its own lag spike, and doesn't even fix the root cause.

• The Veto (e.g., Limiters): These plugins impose strict, global limits on pistons or hoppers. This stifles creativity, breaks vanilla-friendly farms, and punishes your entire community.

CircuitBreaker is different. It's not a sledgehammer; it's a scalpel. It provides a dynamic, surgical response by monitoring two separate systems—physics and entities—one chunk at a time.

💡 System 1: Physics Lag (The 3-Strike System)

This is the core of the plugin, designed to stop redstone/piston lag machines.

• 🥇 STRIKE 1 & 2: The "Warning Tap" If a chunk gets too "loud" (exceeding the lag-threshold), the plugin performs a "soft reset" (a quick, safe chunk unload/reload). This immediately breaks simple lag cycles.

• 🥉 STRIKE 3: The "Circuit Breaks" If the lag persists, the plugin flips the breaker for that one chunk. It's put in "time out," and all its physics events are canceled. The lag stops instantly.

• ♻️ The "Forgiveness" Timer It's not permanent! Every 15 minutes (configurable), the plugin wipes the slate clean for all chunks.

💡 System 2: Entity Lag (The Smart Culler)

This is the new optional v2.0 system. It is disabled by default but can be enabled in the config.

• Smart Scanning: A separate, slower-paced scanner runs every 15-30 seconds (configurable) to check for chunks with too many entities.
• Smart Culling: If a chunk is over the entity-culling.threshold (e.g., 500 entities), the plugin will remove entities... but only unimportant ones.

What We DON'T Cull (The "Important" List)

CircuitBreaker WILL NOT remove entities that are:

• On the config whitelist (e.g., "PLAYER", "VILLAGER", "IRON_GOLEM")
• Named with a Name Tag
• Tamed (e.g., dogs, cats)
• Vehicles (boats, minecarts)

🛡️ Full Admin Control & Persistence

You have 100% control. All administrative actions (like ignoring chunks) are saved to data.yml and persist through server restarts.

Commands

All commands require the permission: circuitbreaker.admin

• /cb status Checks the current status of the chunk you're in (NORMAL, WATCHED, FROZEN, or IGNORED).
• /cb unfreeze Manually unfreezes a (physics-lag) frozen chunk and resets its strike count.
• /cb ignore This is the most important command. Whitelists the chunk you are standing in. It will be ignored by BOTH the physics lag and entity lag systems.
• /cb unignore Removes the chunk you're standing in from the permanent ignore list.

Permissions

• circuitbreaker.admin Grants access to all /cb commands. (Default: op)
• antilag.notify Receives alerts when a chunk is frozen or when an entity cull occurs. (Default: op)

🛠️ Compatibility

• ✅ Built for Paper: Requires Paper 1.21+ or compatible forks (Purpur, Pufferfish).
• ❌ Folia Incompatible: This plugin is NOT compatible with Folia. It includes a built-in safety check and will disable itself with a clear message if Folia is detected.

🔧 Full Configuration (config.yml v2.0)

The entire plugin is configurable. Tune the thresholds to perfectly match your server's performance profile.

# ------------------------------
# CircuitBreaker Config v2.0
# ------------------------------

# --- v1.0: Physics Lag Detector ---
# Set to false to disable the 3-strike physics lag system.
enabled: true

# How many block physics events in 1 second (20 ticks)
# will trigger a "lag" warning? (v1.1 Tuned Value)
lag-threshold: 20000

# How many "strikes" a chunk gets before it is frozen.
strike-limit: 3

# How many minutes of no lag before a chunk's strike count is reset.
strike-reset-minutes: 15

# How long (in ticks) to "soft reset" a chunk for.
# 200 ticks = 10 seconds
soft-reset-duration-ticks: 200

# How long (in ticks) to "hard freeze" a chunk for.
# 6000 ticks = 5 minutes
# Set to -1 to freeze chunks permanently (requires admin /cb unfreeze).
freeze-duration-ticks: 6000

# Send a broadcast message to admins when a chunk is frozen OR culled?
notify-admins: true

# ------------------------------
# v2.0: Entity Culling Settings
# ------------------------------
entity-culling:
  # Set to true to enable this new entity-culling feature.
  # This is disabled by default.
  enabled: false

  # How often (in seconds) to scan all loaded chunks.
  # This is a HEAVY task. Do not set this too low!
  scan-interval-seconds: 15

  # How many entities must be in a *single chunk* to trigger a cull.
  threshold: 500

  # A list of entity types to *NEVER* kill (case-insensitive).
  whitelist:
    - "PLAYER"
    - "VILLAGER"
    - "IRON_GOLEM"
    - "ARMOR_STAND"
    - "ITEM_FRAME"
    - "PAINTING"
    - "MINECART"
    - "BOAT"
    - "CHEST_BOAT"