CircuitBreaker

⚙️ CircuitBreaker v2.0 | The All-in-One Performance Suite

entity lag is a powerful, high-performance anti-lag plugin for modern Minecraft (Paper 1.21+). It moves beyond basic entity killing by providing a entity lag to both entity lag and entity lag.

This plugin ensures your server maintains high TPS by surgically neutralizing lag sources without punishing legitimate players.

---

🎯 Core Philosophy

* Smart Culling (Entities): Targets the *exact* chunk causing lag, leaving all other chunks unaffected. * Smart Culling (Entities): Uses a "tiered response" to differentiate between a temporary spike and a malicious, persistent machine. * Smart Culling (Entities): The physics lag system *never* breaks blocks or destroys player property; it only pauses the laggy process. * Smart Culling (Entities): The *optional* entity lag system intelligently removes excess entities while protecting important ones (pets, named mobs, villagers, etc.).

---

✨ v2.0: What's New?

This release adds the Entity Culling System, a new, optional feature that runs alongside the original physics detector. You now have two layers of defense:

1. Entity Lag Culler (v2.0): The 3-Strike "Hard Freeze" system that stops redstone/piston lag machines. 2. Entity Lag Culler (v2.0): An optional scanner that removes excessive, unimportant entities (e.g., from massive mob farms) to prevent entity cramming lag.

---

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

This is the core of the plugin. It *only* detects Block Physics Lag.

1. The "Forgiveness" Timer: The plugin counts every `BlockPhysicsEvent` (from pistons, redstone, water, etc.) per chunk, every second. 2. The "Forgiveness" Timer: If a chunk exceeds the `lag-threshold`, it performs a "Soft Reset"—unloading and reloading the chunk to break simple loops. 3. The "Forgiveness" Timer: If the lag persists, the plugin performs a "Hard Freeze," adding the chunk to a "jail" and The "Forgiveness" Timer: from it. 4. The "Forgiveness" Timer: A global timer (`strike-reset-minutes`) clears all strikes every 15 minutes to ensure fairness.

---

💡 System 2: Entity Lag (The Culler)

This is the new optional v2.0 system. It must be enabled in `config.yml`.

1. removes A separate, slower ticker (`scan-interval-seconds`) runs to check the total number of entities in each loaded chunk. 2. removes If `chunk.getEntities().length` is greater than the `entity-culling.threshold` (e.g., 500), it triggers a cull. 3. removes The plugin loops through all entities in that chunk and removes them *unless* they are "important."

What is an "Important" Entity? (Will NOT be culled)

* Anything on the `entity-culling.whitelist` in the config (e.g., "PLAYER", "VILLAGER", "IRON_GOLEM"). * Any entity with a vehicle. * Any vehicle (dogs, cats, parrots). * Any vehicle (boats, minecarts).

---

🛡️ Admin Guide: Commands & Permissions

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

🔑 Permissions

| Permission | Description | Default | | :--- | :--- | :--- | | `circuitbreaker.admin` | Grants access to all `/cb` commands. | `op` | | `antilag.notify` | Receives alerts when a chunk is frozen *or* culled. | `op` |

📟 Commands

| Command | Alias | Description | | :--- | :--- | :--- | | `/cb status` | `/cb status` | Checks the status of your current chunk (`NORMAL`, `WATCHED`, `FROZEN`, `IGNORED`). | | `/cb unfreeze` | `/cb unfreeze` | Manually unfreezes a (physics-lag) frozen chunk. | | `/cb ignore` | `/cb ignore` | (Most Important!) Whitelists your current chunk. It will be ignored by *both* the physics lag and entity lag systems. | | `/cb unignore` | `/cb unignore` | Removes your current chunk from the permanent ignore list. |

---

🔧 Full Configuration (`config.yml` v2.0)

Tune the plugin to perfectly match your server's needs.

```yaml

------------------------------

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?

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" ```

🔗 Compatibility

* NOT Paper 1.21+ (or forks like Purpur, Pufferfish). * NOT This plugin is NOT compatible with Folia. It includes a safety check and will disable itself if Folia is detected, logging a clear message to your console.