NeuroLag

<div align="center"> <img src="https://cdn.modrinth.com/data/neurolag/icon.png" width="120" alt="NeuroLag Icon"/> # NeuroLag **Smart TPS-aware mob AI optimizer for Paper 1.21+** (https://img.shields.io/badge/Modrinth-1.8.0-00AF5C?logo=modrinth)](https://modrinth.com/user/Duong2012G) (https://img.shields.io/badge/Paper-1.21%2B-blue?logo=papermc)](https://papermc.io) (https://img.shields.io/badge/Java-21%2B-orange?logo=openjdk)](https://adoptium.net) (https://img.shields.io/badge/License-Apache%202.0-blue)](LICENSE) *Protect your TPS before the lag even starts — then quietly undo everything when the server recovers.* (https://modrinth.com/user/Duong2012G) • (https://modrinth.com/user/Duong2012G) • (CHANGELOG.md) </div> --- ## 📖 Table of Contents * ✨ Features * 🔁 How It Works * 📦 Requirements * 🚀 Installation * ⌨️ Commands & Permissions * 🔧 Configuration * 🌐 Web Dashboard * 🔗 Multi-Server Sync * 🛡️ Protected Zones * 🗂️ Config Profiles * 💾 Backup System * 🧩 Developer API * 🔍 Troubleshooting * ❓ FAQ * 📄 Credits --- ## ✨ Features ### 🧠 Intelligent TPS State Machine NeuroLag continuously samples TPS, CPU load, heap usage, player count, and predictive trend data to decide which of three states to apply per world: | State | Default Trigger | Effect | |---|---|---| | `NORMAL` | TPS ≥ 18.0 | No restrictions; full AI restored | | `MEDIUM` | TPS < 18.0 | Follow-range scaled, pathfinding limited, tick-throttle on | | `CRITICAL` | TPS < 15.0 | Full AI disable, spawn suppression, smart culling | All thresholds are configurable per-world and can be overridden by config profiles. A **hysteresis buffer** (default 0.5 TPS) prevents oscillation at the boundary. --- ### ⚡ 31 Optimization Features #### F1 — CPU Throttle Penalty Monitors JVM CPU usage. When usage exceeds the configured threshold (default 80%), a 1.5 TPS penalty is applied to the effective TPS calculation, triggering stricter mob optimizations before the server thread becomes saturated. #### F2 — Region-Based Pathfinding Cutoff Divides each world into configurable regions. Mobs beyond the pathfinding distance threshold (`disable-pathfinding-distance-chunks: 8`) have their `FOLLOW_RANGE` attribute zeroed, eliminating expensive A* pathfinding for mobs no player will ever see. #### F3 — Chunk-Based AI Toggle Mobs outside a configurable chunk radius from any player (`distance-chunks: 4`) have their AI disabled entirely during CRITICAL state. Mobs within range always retain full AI regardless of server state. #### F4 — Velocity Freeze Distant AI-disabled mobs have their velocity zeroed to prevent passive drift. Configurable minimum chunk distance (`freeze-distance-chunks: 6`). #### F5 — Spawn Suppression During MEDIUM and CRITICAL states, monster and animal spawn limits are reduced (`monster-limit: 30`, `animal-limit: 10`) to slow mob population growth while the server is already under load. #### F6 — Smart Culling When the per-world entity count exceeds `max-entities-per-world` during CRITICAL state, the lowest-priority mobs are removed. Supports three culling strategies: | Strategy | Behaviour | |---|---| | `FAR_FROM_PLAYER` | Remove mobs furthest from any player first | | `GROUP` | Remove mob types that have the most instances | | `RANDOM` | Shuffle and remove | Protected-zone mobs and named / tamed mobs (if whitelisted) are **never** culled. #### F7 — Tick Throttling During MEDIUM state, non-priority mobs have their AI ticked only once every N game ticks (`ticks-per-ai-tick: 4`) instead of every tick. This halves or quarters AI cost without fully disabling mobs. #### F8 — Mob Weight System Each entity type is assigned a weight score. Culling prioritizes heaviest entities first. Fully configurable (`zombies.yml`-style block in `features.yml`). | Entity | Default Weight | |---|---| | Bat | 0.3 | | Bee | 0.5 | | Zombie | 1.0 | | Skeleton | 1.2 | | Creeper | 1.5 | | Enderman | 2.0 | | Wither | 3.0 | | Ender Dragon | 4.0 | #### F9 — AI Difficulty Scaling Adjusts the effective TPS threshold based on world difficulty, so optimization triggers earlier on Easy (players care less) and later on Hard (players want full mob behaviour). | Difficulty | TPS Offset | |---|---| | Peaceful | +3.0 (never optimizes) | | Easy | −1.0 (optimizes sooner) | | Normal | 0.0 | | Hard | +1.0 (defers optimization) | #### F10 — Memory Pressure Penalty Monitors JVM heap usage ratio. When used heap exceeds the configured threshold (default 80%), a configurable TPS penalty is added, pre-emptively triggering optimizations before a GC pause hits. #### F11 — Predictive Scheduler Tracks historical TPS over a sliding window and a configurable set of peak hours. If a downward TPS trend is detected early (before the threshold is crossed), an `earlyOffset` penalty is applied to trigger optimizations proactively. Configurable peak hours example: ```yaml peak-hours: "17:00-19:00,1