Minecraft Server Diagnostics
Entity Lag vs. Physics Lag: Which is Killing Your Minecraft Server?
Not all lag is created equal. Learn the difference between entity lag and physics loop lag, and configure your defenses to stop both.
If you run a Minecraft server, you've probably heard players complain about "lag." But when you type `/tps`, you see the TPS dropping without knowing why. Diagnosing lag can be frustrating because **lag has different root causes**.
The two most common culprits are **Entity Lag** and **Physics Lag**. In this guide, we'll explain how they differ, how to diagnose them, and how **CircuitBreaker** provides a unified defense against both.
Entity Lag: Too Many Objects to Track
Entity lag occurs when there are too many individual, active entities loaded in your server worlds. An entity is anything that can move, tick, or interact, including monsters, animals, item drops, and item frames.
- The Cause: Massive mob farms (e.g. 500 chickens in a single block), massive amounts of floating items on the ground from auto-farms, or thousands of armor stands in lobby regions.
- The Mechanism: The server must calculate pathfinding, collisions, gravity, and movements for every single entity on every tick, which quickly overwhelms the CPU thread.
Physics Lag: Infinite Block Updates
Physics lag occurs when block state changes propagate infinitely through a world, triggering heavy event checks inside Minecraft's physics engine.
- The Cause: Redstone clocks, repeating observer chains, piston arrays, and water/lava flow loops.
- The Mechanism: Every block state change calls a `BlockPhysicsEvent`, forcing the server to check neighboring blocks. When griefers build loops, the event queue gets flooded.
Comparison: Entity vs. Physics Lag
| Feature | Entity Lag | Physics Lag |
|---|---|---|
| Main Culprit | Mob farms, item drops, entities | Redstone loops, pistons, observers |
| Detection Metric | Entity count per chunk | Physics events per second |
| Lag Impact | Consistent, slow TPS decrease | Sudden, violent TPS drop to 5 or lower |
The Dual Defense: How CircuitBreaker Solves Both
Instead of installing separate plugins to manage entities and physics, **CircuitBreaker provides a dual-layer defense system**:
- Layer 1: The Physics Shield (v1.0): Automatically monitors physics updates per chunk. When a loop exceeds threshold limits, it performs a soft reset, and finally a surgical hard freeze on the laggy chunk.
- Layer 2: The Smart Culler (v2.0): Scans chunks for excessive entity counts. If a chunk contains more than 500 entities, it selectively removes unimportant mobs while **fully protecting named entities, tamed pets, and villagers**.
Conclusion
Diagnosing lag is the first step toward a smooth Minecraft server. By configuring **CircuitBreaker** to protect against both physics loops and entity overflow, you ensure your server remains stable and your community enjoys a lag-free experience.