# \u2699\ufe0f CircuitBreaker v2.0 | The All-in-One Performance Suite<\/p>\n
<\/p>\n
**CircuitBreaker** is a powerful, high-performance anti-lag plugin for modern Minecraft (Paper 1.21+). It moves beyond basic entity killing by providing a **dual-system, automated response** to both **physics lag** and **entity lag**.<\/p>\n
This plugin ensures your server maintains high **TPS** by surgically neutralizing lag sources without punishing legitimate players.<\/p>\n
—<\/p>\n
## \ud83c\udfaf Core Philosophy<\/p>\n
* **Surgical:** Targets the *exact* chunk causing lag, leaving all other chunks unaffected.
\n* **Intelligent:** Uses a “tiered response” to differentiate between a temporary spike and a malicious, persistent machine.
\n* **Non-Destructive (Physics):** The physics lag system *never* breaks blocks or destroys player property; it only pauses the laggy process.
\n* **Smart Culling (Entities):** The *optional* entity lag system intelligently removes excess entities while protecting important ones (pets, named mobs, villagers, etc.).<\/p>\n
—<\/p>\n
## \u2728 v2.0: What’s New?<\/p>\n
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:<\/p>\n
1. **Physics Lag Detector (v1.0):** The 3-Strike “Hard Freeze” system that stops redstone\/piston lag machines.
\n2. **Entity Lag Culler (v2.0):** An optional scanner that removes excessive, unimportant entities (e.g., from massive mob farms) to prevent entity cramming lag.<\/p>\n
—<\/p>\n
## \ud83d\udca1 System 1: Physics Lag (The 3-Strike System)<\/p>\n
This is the core of the plugin. It *only* detects **Block Physics Lag**.<\/p>\n
1. **Detection:** The plugin counts every `BlockPhysicsEvent` (from pistons, redstone, water, etc.) per chunk, every second.
\n2. **Strike 1 & 2 (Soft Reset):** If a chunk exceeds the `lag-threshold`, it performs a “Soft Reset”\u2014unloading and reloading the chunk to break simple loops.
\n3. **Strike 3 (Hard Freeze):** If the lag persists, the plugin performs a “Hard Freeze,” adding the chunk to a “jail” and **canceling all future physics events** from it.
\n4. **The “Forgiveness” Timer:** A global timer (`strike-reset-minutes`) clears all strikes every 15 minutes to ensure fairness.<\/p>\n
<\/p>\n
—<\/p>\n
## \ud83d\udca1 System 2: Entity Lag (The Culler)<\/p>\n
This is the new **optional** v2.0 system. It must be enabled in `config.yml`.<\/p>\n
1. **Detection:** A separate, slower ticker (`scan-interval-seconds`) runs to check the total number of entities in each loaded chunk.
\n2. **Threshold Check:** If `chunk.getEntities().length` is greater than the `entity-culling.threshold` (e.g., 500), it triggers a cull.
\n3. **Smart Culling:** The plugin loops through all entities in that chunk and **removes** them *unless* they are “important.”<\/p>\n
### What is an “Important” Entity? (Will NOT be culled)
\n* Anything on the `entity-culling.whitelist` in the config (e.g., “PLAYER”, “VILLAGER”, “IRON_GOLEM”).
\n* Any entity with a **custom name**.
\n* Any **tamed pet** (dogs, cats, parrots).
\n* Any **vehicle** (boats, minecarts).<\/p>\n
—<\/p>\n
## \ud83d\udee1\ufe0f Admin Guide: Commands & Permissions<\/p>\n
You have 100% control. All administrative actions (like ignoring chunks) are **saved to `data.yml`** and persist through server restarts.<\/p>\n
### \ud83d\udd11 Permissions
\n| Permission | Description | Default |
\n| :— | :— | :— |
\n| `circuitbreaker.admin` | Grants access to all `\/cb` commands. | `op` |
\n| `antilag.notify` | Receives alerts when a chunk is frozen *or* culled. | `op` |<\/p>\n
### \ud83d\udcdf Commands
\n| Command | Alias | Description |
\n| :— | :— | :— |
\n| `\/cb status` | `\/cb status` | Checks the status of your current chunk (`NORMAL`, `WATCHED`, `FROZEN`, `IGNORED`). |
\n| `\/cb unfreeze` | `\/cb unfreeze` | Manually unfreezes a (physics-lag) frozen chunk. |
\n| `\/cb ignore` | `\/cb ignore` | **(Most Important!)** Whitelists your current chunk. It will be ignored by *both* the physics lag and entity lag systems. |
\n| `\/cb unignore` | `\/cb unignore` | Removes your current chunk from the permanent ignore list. |<\/p>\n
—<\/p>\n
## \ud83d\udd27 Full Configuration (`config.yml` v2.0)<\/p>\n
Tune the plugin to perfectly match your server’s needs.<\/p>\n
“`yaml
\n# ——————————
\n# CircuitBreaker Config v2.0
\n# ——————————<\/p>\n
# — v1.0: Physics Lag Detector —
\n# Set to false to disable the 3-strike physics lag system.
\nenabled: true<\/p>\n
# How many block physics events in 1 second (20 ticks)
\n# will trigger a “lag” warning?
\nlag-threshold: 20000<\/p>\n
# How many “strikes” a chunk gets before it is frozen.
\nstrike-limit: 3<\/p>\n
# How many minutes of no lag before a chunk’s strike count is reset.
\nstrike-reset-minutes: 15<\/p>\n
# How long (in ticks) to “soft reset” a chunk for.
\n# 200 ticks = 10 seconds
\nsoft-reset-duration-ticks: 200<\/p>\n
# How long (in ticks) to “hard freeze” a chunk for.
\n# 6000 ticks = 5 minutes
\n# Set to -1 to freeze chunks permanently (requires admin \/cb unfreeze).
\nfreeze-duration-ticks: 6000<\/p>\n
# Send a broadcast message to admins when a chunk is frozen OR culled?
\nnotify-admins: true<\/p>\n
# ——————————
\n# v2.0: Entity Culling Settings
\n# ——————————
\nentity-culling:
\n # Set to true to enable this new entity-culling feature.
\n # This is disabled by default.
\n enabled: false<\/p>\n
# How often (in seconds) to scan all loaded chunks.
\n # This is a HEAVY task. Do not set this too low!
\n scan-interval-seconds: 15<\/p>\n
# How many entities must be in a *single chunk* to trigger a cull.
\n threshold: 500<\/p>\n
# A list of entity types to *NEVER* kill (case-insensitive).
\n whitelist:
\n – “PLAYER”
\n – “VILLAGER”
\n – “IRON_GOLEM”
\n – “ARMOR_STAND”
\n – “ITEM_FRAME”
\n – “PAINTING”
\n“`<\/p>\n
## \ud83d\udd17 Compatibility<\/p>\n
* **Requires:** Paper 1.21+ (or forks like Purpur, Pufferfish).
\n* **Folia:** 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.<\/p>\n","protected":false},"excerpt":{"rendered":"
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\u2014and stops it cold.<\/p>\n","protected":false},"featured_media":40361,"template":"","meta":{"_minecraft_slug":"circuitbreaker","_minecraft_project_id":"89XN4Be6","_minecraft_author":"AJA_R3TR0","_minecraft_license":"CC-BY-NC-SA-4.0","_minecraft_downloads":105,"_minecraft_follows":2,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"circuitbreaker.zip","_minecraft_size_bytes":51839,"_minecraft_version_count":3,"_minecraft_updated_at":"2026-05-15T19:36:10.300794Z","_minecraft_date_created":"2025-12-12T06:47:46.123477Z","_minecraft_date_modified":"2025-11-16T12:11:01.812871Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/circuitbreaker","_minecraft_icon_attachment_id":40361,"_minecraft_imported_at":"2026-06-01T21:40:36+00:00","_minecraft_import_hash":"bcc9598df99812ee30e3e45f96b841f5","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[89,126,90,127,129,123],"mod_loader":[132,134],"minecraft_version":[62,37,40,73,74,38,78,79,80,81,82],"class_list":["post-40360","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-game-mechanics","mod_category-management","mod_category-optimization","mod_category-paper","mod_category-spigot","mod_category-technology","mod_loader-paper","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n