NeuroLag

---

📖 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,19:00-22:00" ```

F12 — Protected Zones

Mobs inside defined cuboid zones (or WorldGuard regions) are never throttled, culled, or have their attributes modified. Follow range is always restored to default when a mob is found inside a protected zone.

F13 — Smart Group Culling

Instead of culling random mobs, groups entities by type and only targets types with more than `min-type-before-cull` instances, preserving ecological diversity while reducing the highest-density populations.

F14 — Per-Player Action Bar Notifications

Players near affected mobs receive an action-bar warning during MEDIUM/CRITICAL states. Configurable radius (`radius-blocks: 64`).

F15 — Alert System

Admin action-bar broadcasts on state transitions. Optional Discord webhook and in-game sound alerts. Sound names, particle types, particle count, and whether to show an action-bar alert are all configurable in `monitors.yml` under `alerts.*`. Includes per-player cooldown to prevent sensory spam on multi-world servers.

F16 — Player-Count Scaling

TPS thresholds dynamically tighten as more players join. Configure `min-players`, `max-players`, and `max-threshold-offset` to have the plugin optimize more aggressively during peak player counts.

F17 — Animation Freezing

Freezes the velocity of mobs beyond `freeze-distance-chunks` during CRITICAL state, preventing physics drift without requiring NMS or packet-level access.

F18 — Config Auto-Backup

Automatically creates timestamped ZIP bundles of all NeuroLag YAML files (including `lang/`) on a configurable schedule and keeps the N most recent copies. Each backup is accompanied by a `.sha256` checksum file that is verified before any restore. Protects against zip-bomb attacks with per-entry (10 MB) and total-restore (50 MB) size caps.

F19 — Safe Mode for Critical State

When enabled in the critical TPS tier configuration, Safe Mode selectively disables only dangerous AI components while preserving essential game mechanics. Prevents over-optimization that would break villager trading, mob escaping water, and other critical behaviors.

F20 — Mob Importance Scoring System

Assigns importance scores to all mobs based on type, naming, tamed status, equipment, and leash status. Named mobs (10x), tamed mobs (20x), and equipped mobs (1.5x) receive higher priority. System protects important mobs during culling operations.

F21 — Mob Behavior Groups

Categorizes mobs into behavior groups for targeted optimization: - PASSIVE (low priority): Cows, pigs, sheep, chickens - AGGRESSIVE (high priority): Zombies, skeletons, creepers - NEUTRAL (medium priority): Endermen, iron golems - SPECIAL (preserve): Villagers, bosses, named mobs - AQUATIC (water-based): Dolphins, guardians, squids

F22 — Dynamic Region Sizing

Automatically adjusts region size based on player count for optimal performance: - 0-5 players: 16 chunks (large regions) - 6-20 players: 8 chunks (medium regions) - 21-50 players: 4 chunks (small regions) - 50+ players: 2 chunks (very small regions)

F23 — Hot Region Decay

Regions gradually cool down when players leave, preventing regions from staying hot indefinitely. Heat decays at 5% per second when no players are present.

F24 — EWMA Prediction Algorithm

Exponentially Weighted Moving Average provides better short-term TPS prediction by giving more weight to recent samples. Alpha smoothing factor of 0.3 for optimal responsiveness.

F25 — Linear Regression Trend Analysis

Detects downward TPS trends using linear regression to predict lag before it occurs. Combines with simple average and EWMA for robust prediction accuracy.

F26 — Annotation-Based Config Validation

`@ConfigValidation` annotation allows field-level validation rules for configuration values. Validates numeric ranges, required fields, and boundary warnings with clear error messages.

F27 — Config Migration System

Automatic version checking and stepwise migrations for config files. Creates backups before migration and supports rollback. Migrates config.yml, features.yml, monitors.yml, and systems.yml while preserving user settings.

F28 — Event-Driven Architecture

EventBus pattern decouples optimization logic from the main engine. Components can register as `OptimizationListener` to react to optimization state changes, enabling plugins/addons to extend functionality.

F29 — Refactored Optimizer Classes

Optimization logic extracted into dedicated classes following Single Responsibility Principle: - `MobCuller` - Entity culling with importance scoring - `AIThrottler` - AI throttling and tick management - `SpawnSuppressor` - Spawn rate adjustment logic

F30 — Comprehensive Config Guide

`CONFIG-GUIDE.md` provides detailed explanations for all configuration options, including usage examples, recommended values, and troubleshooting tips organized by functional areas.

F31 — Enhanced Config Comments

All YAML configuration files (config.yml, features.yml, monitors.yml, systems.yml) include detailed inline comments, section headers, and security notes for better understanding and configuration management.

---

📊 Monitoring & Reporting

| Feature | Description | |---|---| | Metrics API | Real-time TPS, state, CPU, and heap display for admins | | Metrics API | Embedded HTTP server at configurable port with JSON API | | Metrics API | `/nlag graph` — TPS history chart in chat | | Metrics API | On-demand or auto-generated reports covering server specs, plugin list, chunk stats, and mob analysis. Entity collection is capped at 5 000 per world to avoid main-thread spikes. Full HTML escaping prevents XSS. | | Metrics API | Logged when critical events last more than the minimum duration | | Metrics API | Plugin-message channel (`neurolag.api`) for third-party integrations |

---

🔗 Multi-Server Sync

Propagates TPS state across a network in real time. Supports:

- MySQL (recommended) — sub-100 ms latency via Pub/Sub - MySQL — polling-based, works with any shared database

Cascade warnings alert local admins when a peer server enters CRITICAL state.

---

🗂️ Config Profiles

Switch between named configuration presets at runtime:

``` /nlag profile survival /nlag profile event /nlag profile clear ```

Profiles override `critical-tps`, `medium-tps`, and `max-entities` without touching your base config files.

---

🧩 Developer API

```java NeuroLagAPI api = NeuroLagAPI.getInstance();

api.getCurrentTps(); api.getWorldState("world"); // "NORMAL" | "MEDIUM" | "CRITICAL" api.isManualOverride(); api.getCriticalActivationCount(); api.getMediumActivationCount(); ```

---

🔁 How It Works

``` Every check-interval seconds (default: 10):

Raw TPS │ ├─ Memory pressure penalty (if heap > threshold) ├─ CPU throttle penalty (if CPU > threshold) ├─ Predictive offset (if downward trend detected) └─ Difficulty scaling (per-world adjustment) │ ▼ Effective TPS │ ┌────────┴─────────┐ │ Hysteresis FSM │ NORMAL ↔ MEDIUM ↔ CRITICAL └────────┬─────────┘ │ ┌────────┴────────────────────────────────┐ │ Per-world optimization pass │ │ • Collect targets (cached 4 ticks) │ │ • Spawn suppression │ │ • Smart culling (if CRITICAL) │ │ • Batched AI/range update (≤ 50/batch) │ │ • Admin + player notifications │ └─────────────────────────────────────────┘

On recovery to NORMAL: → restoreWorld() — full AI + default FOLLOW_RANGE for all mobs ```

---

📦 Requirements

| Component | Version | Notes | |---|---|---| | Java | 21+ | Required | | Paper | 1.21+ | Required; Spigot is not supported | | WorldGuard | 7.x | Optional — enables WG region integration | | Redis | Any recent | Optional — for multi-server sync | | MySQL | 8.x | Optional — alternative sync backend |

---

🚀 Installation

1. Download `NeuroLag-1.5.2.jar` from Modrinth. 2. Place it in your `plugins/` folder. 3. Start the server once to generate all config files. 4. Edit the files in `plugins/NeuroLag/`:

| File | Purpose | |---|---| | `config.yml` | TPS thresholds, target rules, per-world overrides | | `features.yml` | Toggle and tune each optimization feature | | `monitors.yml` | Dashboard, web API, alerts, Discord, audit | | `systems.yml` | Sync, zones, profiles, backup, validator |

5. Run `/nlag validate` to catch configuration errors. 6. Run `/nlag status` to confirm everything is active.

> ⚠️ Do not use `/reload`. Always do a full server restart or use `/nlag reload` for NeuroLag-specific changes.

---

⌨️ Commands

| Command | Description | Permission | |---|---|---| | `/nlag status` | TPS, CPU, heap, per-world states, activation counts | `neurolag.admin` | | `/nlag graph` | ASCII TPS history chart (last 60 samples) | `neurolag.admin` | | `/nlag toggle` | Pause / resume monitoring and mob optimizations | `neurolag.admin` | | `/nlag simulate <tps|clear>` | Force a TPS value for testing (0–20) | `neurolag.admin` | | `/nlag dashboard [off]` | Show / hide BossBar dashboard | `neurolag.dashboard` | | `/nlag audit` | Generate an HTML audit report | `neurolag.audit` | | `/nlag zone` | Show loaded protected zones | `neurolag.zone` | | `/nlag profile [name|clear]` | Switch or clear a config profile | `neurolag.profile` | | `/nlag validate` | Validate all config values and report errors | `neurolag.validate` | | `/nlag backup` | Create a manual backup ZIP now | `neurolag.backup` | | `/nlag backup list` | List available backups | `neurolag.backup` | | `/nlag backup restore [file]` | Restore from latest or named backup | `neurolag.backup` | | `/nlag stresstest [count] [min]` | Spawn test mobs for load testing | `neurolag.stresstest` | | `/nlag sync` | Show multi-server peer TPS states | `neurolag.admin` | | `/nlag reload` | Hot-reload all NeuroLag config files | `neurolag.admin` |

Aliases: `/neurolag`, `/nl`, `/neuromob`

---

🔐 Permissions

| Permission | Description | Default | |---|---|---| | `neurolag.admin` | Full control; grants all sub-commands | OP | | `neurolag.dashboard` | Use `/nlag dashboard` | OP | | `neurolag.audit` | Use `/nlag audit` | OP | | `neurolag.zone` | Use `/nlag zone` | OP | | `neurolag.profile` | Use `/nlag profile` | OP | | `neurolag.validate` | Use `/nlag validate` | OP | | `neurolag.backup` | Use `/nlag backup` | OP | | `neurolag.stresstest` | Use `/nlag stresstest` | OP | | `neurolag.web` | Web dashboard access control (outside Bukkit) | OP | | `neurolag.api` | Read plugin metrics via NeuroLagAPI | `true` |

---

🔧 Configuration

NeuroLag uses a split-config layout. All files are in `plugins/NeuroLag/`.

`config.yml` — Core Settings

```yaml settings: language: en # en, vi, es, fr, de, ja, zh check-interval: 10 # seconds between TPS samples enable-logging: true hysteresis-buffer: 0.5 # TPS gap before state recovers

tiers: medium: tps-trigger: 18.0 range-multiplier: 0.5 # scale mob FOLLOW_RANGE to 50% in MEDIUM critical: tps-trigger: 15.0

targets: hostile-mobs: true passive-mobs: false water-mobs: true whitelist-types: [WARDEN, ELDER_GUARDIAN, ENDER_DRAGON, WITHER] protect-named-mobs: true protect-tamed-mobs: true ```

`features.yml` — Optimization Toggles

```yaml culling: enabled: true max-entities-per-world: 500 priority: "FAR_FROM_PLAYER" # FAR_FROM_PLAYER | GROUP | RANDOM

chunk-ai: enabled: true distance-chunks: 4

tick-throttle: enabled: true ticks-per-ai-tick: 4

spawn-suppression: enabled: true monster-limit: 30 animal-limit: 10

cpu-throttling: enabled: true cpu-threshold: 80 mode: THROTTLE_TASKS

memory-pressure: enabled: true percent: 0.80 # 80% heap used = apply penalty offset: 0.5

smart-culling: enabled: true cull-in-groups: true min-type-before-cull: 2 removal-particle: POOF ```

`monitors.yml` — Dashboard & Alerts

```yaml dashboard: enabled: true type: BOSSBAR update-interval: 2 bossbar: name: "Server Health" color: BLUE

web-dashboard: enabled: true port: 8080 auth: token: "change-this-token-now" require-auth: true allow-query-token: false # keep false for security

discord: enabled: false webhook-url: "" notify-on-critical: true notify-on-recovery: true

audit-reports: enabled: true generate-on: CRITICAL_EVENT output-format: HTML ```

`systems.yml` — Maintenance & Sync

```yaml stress-test: enabled: false max-mob-count: 2000 cooldown-seconds: 300 max-mobs-per-chunk: 80 # NEW 1.5.2 — crash-prevention density cap entity-types: - ZOMBIE - SKELETON - CREEPER

multi-server: enabled: false backend: REDIS # REDIS or MYSQL

zone-protection: enabled: false integrate-worldguard: false zones: - "world 0 60 0 100 200 100"

config-profiles: enabled: true profiles: survival: critical-tps: 15.0 medium-tps: 18.0 max-entities: 500

auto-backup: enabled: true backup-interval-minutes: 60 keep-backups: 10 ```

---

🔒 Security (v1.5.2)

NeuroLag 1.5.2 ships with three security improvements to the web dashboard:

| Feature | Default | Config Key | |---|---|---| | IP allow-list | Enabled (replaces placeholder on every `start()` call, even when dashboard is disabled) | `web-dashboard.auth.token` in `monitors.yml` | | IP allow-list | 60 req/min | `web-dashboard.rate-limit` in `monitors.yml` | | IP allow-list | Disabled | `web-dashboard.ip-whitelist` in `monitors.yml` |

On first startup, if the token is still `"change-this-token-now"`, NeuroLag automatically generates a cryptographically secure random token, saves it to `monitors.yml` (creating the file if needed), and prints it to the console. Use it as your `Authorization: Bearer <token>` header.

> 1.5.2 fix: Token generation now runs before the `enabled` check, so the placeholder is replaced even if you have `web-dashboard.enabled: false`. Previously, flipping the dashboard on after initial setup could expose the default token until the next restart.

---

🌐 Web Dashboard

The embedded HTTP server exposes a live dashboard and JSON API.

Routes:

| Route | Method | Description | |---|---|---| | `/` | GET | HTML live dashboard (auto-refreshes) | | `/api/status` | GET | JSON metrics snapshot | | `/api/cmd` | POST | Limited command bridge |

Allowed commands via `/api/cmd`: `reload`, `status`, `graph`, `validate`

Authentication:

Always use the `Authorization: Bearer <token>` request header. The `?token=...` query-string fallback is disabled by default (`allow-query-token: false`) because tokens in URLs appear in server access logs and browser history.

```bash

Correct

curl -H "Authorization: Bearer my-secret-token" http://localhost:8080/api/status

Works but insecure — only if allow-query-token: true

curl "http://localhost:8080/api/status?token=my-secret-token" ```

> ⚠️ Always change the default token and never expose the web dashboard port publicly without a reverse proxy or firewall rule.

---

🔗 Multi-Server Sync

Share TPS state across a network so operators can see the health of every node from one place.

Redis (recommended)

```yaml multi-server: enabled: true backend: REDIS cascade-warnings: true redis: host: localhost port: 6379 password: "" ```

MySQL

```yaml multi-server: enabled: true backend: MYSQL mysql: host: localhost port: 3306 database: neurolag user: root password: "" ```

Use `/nlag sync` to see live peer states:

``` [NeuroLag] This server: MyServer_25565 - LobbyServer_25565 → 19.8 TPS [NORMAL] - SurvivalNode_25566 → 16.2 TPS [MEDIUM] ```

> v1.5.1: Redis subscriber now exits cleanly on reload. MySQL reconnect uses exponential back-off to avoid log spam during DB outages.

---

🛡️ Protected Zones

Define cuboid zones where mobs are never optimized, throttled, or culled.

```yaml zone-protection: enabled: true integrate-worldguard: false # set true to also protect WorldGuard regions zones: - "world 0 60 0 100 200 100" # world minX minY minZ maxX maxY maxZ - "world_nether -50 0 -50 50 128 50" ```

Protected mobs always have: - AI enabled - `FOLLOW_RANGE` restored to Minecraft default - Velocity unfrozen - Immunity from smart culling

> unconditionally `FOLLOW_RANGE` is now unconditionally restored for protected mobs on every optimization pass, not just when the mob happens to re-enter the zone.

---

🗂️ Config Profiles

Switch between named presets at runtime without editing files.

```yaml config-profiles: enabled: true profiles: survival: critical-tps: 15.0 medium-tps: 18.0 max-entities: 500 event: critical-tps: 14.0 medium-tps: 17.0 max-entities: 900 minigame: critical-tps: 12.0 medium-tps: 16.0 max-entities: 1000 ```

``` /nlag profile event — switch to event profile /nlag profile clear — return to base config /nlag profile — show all profiles + current active ```

---

💾 Backup System

Automatic backups save all NeuroLag `.yml` files (including `lang/`) as timestamped ZIP bundles.

```yaml auto-backup: enabled: true backup-interval-minutes: 60 keep-backups: 10 ```

Backups are stored in `plugins/NeuroLag/backups/`.

``` /nlag backup — create now /nlag backup list — list all /nlag backup restore — restore latest /nlag backup restore config-bundle-2026-04-18_12-00-00.zip ```

v1.6.0 security improvements: - Each backup ZIP is accompanied by a `.sha256` checksum file. - Restore verifies the checksum before extracting; a mismatch aborts with a `SEVERE` log. - Zip-bomb protection: 10 MB per-entry cap and 50 MB total-restore cap. - Backup list is cached in memory; `purgeOld()` uses filename-based sort — no filesystem stat calls.

> v1.5.1: The `lang/` subdirectory is included in all backup bundles so custom language files are not lost on restore.

---

🧩 Developer API

```java // Get the API instance NeuroLagAPI api = NeuroLagAPI.getInstance();

// Read current TPS and world state double tps = api.getCurrentTps(); String state = api.getWorldState("world"); // "NORMAL" | "MEDIUM" | "CRITICAL" boolean override = api.isManualOverride();

// Read lifetime counters int critCount = api.getCriticalActivationCount(); int medCount = api.getMediumActivationCount(); ```

Subscribe to state changes via the plugin-message channel `neurolag.api` (requires `neurolag.api` permission set to `true` on the target player).

---

🔍 Troubleshooting

Stress test crashes the server when spawning many mobs at spawn

Fixed in 1.5.2. The stress test now checks per-chunk mob density (7×7 chunk grid around the spawn point) against `stress-test.max-mobs-per-chunk` (default 80) before spawning. If the limit would be exceeded, the count is reduced automatically. Update to 1.5.2.

Web dashboard token was still the default placeholder after enabling the dashboard

Fixed in 1.5.2. Token generation now runs before the `enabled` check, so the placeholder is always replaced regardless of whether the dashboard starts or not. Update to 1.5.2.

MySQL log spam: "connection lost — reconnecting" floods console during DB outage

Fixed in 1.5.2. Reconnect log messages are now suppressed using the same power-of-2 streak filter used for SQL errors (logs on streak 1, 2, 4, 8, 16 …). Update to 1.5.2.

Entity count stays above maxEntities permanently when zone protection is active

Fixed in 1.5.2. The culling pass now pre-filters protected mobs before calculating the removal count, so the math is correct and the engine converges to the target entity count even when a subset of mobs is zone-protected. Update to 1.5.2.

Mobs are frozen after /nlag toggle or /nlag reload

Fixed in 1.5.1. In-flight batch tasks were re-applying AI restrictions after `restoreAll()` ran. Update to 1.5.1 and the issue is resolved. If you are running 1.4.0, trigger a full server restart as a workaround.

TPS keeps spiking on a mob-heavy server even with NeuroLag active

Make sure `collectTargets` caching is active (1.5.1+). On older versions, the entity scan ran every tick. Also lower `check-interval` and reduce `max-entities-per-world` in `features.yml`.

FOLLOW_RANGE stays reduced after server recovers to NORMAL

Fixed in 1.5.1. Protected-zone mobs and mobs in worlds returning to NORMAL now always have `FOLLOW_RANGE` reset to the Minecraft default via the new `restoreWorld()` call.

Redis/MySQL exceptions flooding the log on reload

Fixed in 1.5.1. Redis subscriber now joins before pool close. MySQL reconnect uses exponential back-off so errors only log at streaks 1, 2, 4, 8, 16, …

Web dashboard token showing in server access logs

Set `allow-query-token: false` (now the default in 1.5.1) and use the `Authorization: Bearer <token>` header instead.

Custom language files lost after backup restore

Fixed in 1.5.1. Backup bundles now include the `lang/` subdirectory. Restore from a 1.5.1 backup to get language files back.

Mobs inside protected zones being removed by smart culling

Fixed in 1.5.1. The `cull()` method now checks `zoneManager.isProtected()` before removing any mob. Update to 1.5.1.

No optimization happening at all

1. Run `/nlag validate` — look for config errors. 2. Run `/nlag status` — check that `Override` shows `OFF`. 3. Check `ignored-worlds` in `config.yml` — your world may be excluded. 4. Use `/nlag simulate 10` to force CRITICAL state and verify mobs respond. 5. Check `targets` in `config.yml` — `hostile-mobs` and `water-mobs` must be `true`.

Web dashboard returns 401 even with the correct token

Ensure you are sending the token in the `Authorization` header, not the query string (`allow-query-token` is `false` by default). Example:

```bash curl -H "Authorization: Bearer your-token-here" http://localhost:8080/api/status ```

/reload breaks the plugin

Use `/nlag reload` instead of the server-level `/reload` command. Server `/reload` can leave dangling tasks and broken event registrations in any plugin.

---

❓ FAQ

Does NeuroLag affect player behaviour?

No. It only modifies non-player mob AI and attribute values (`FOLLOW_RANGE`). Players, their items, and their abilities are never touched.

Will mobs stay frozen permanently?

No. NeuroLag always restores full AI and default attributes when the server returns to NORMAL state, when the plugin is disabled, or when `/nlag toggle` is used to pause monitoring.

Does it support multiple worlds?

Yes. Each world is tracked independently with its own state machine. Per-world TPS thresholds can be configured in `config.yml` under `world-settings`.

Does it support Folia?

No. NeuroLag uses the Bukkit scheduler API which is not compatible with Folia's per-region threading. Folia support is planned for a future release.

Can I use it alongside other optimization plugins?

Yes, but ensure culling and AI-disable settings do not conflict. NeuroLag is designed to coexist with plugins like Spark, ClearLag, and Chunky.

How do I know it's working?

Run `/nlag status` — you will see current TPS, CPU, heap, per-world states, and lifetime activation counts. Run `/nlag simulate 10` to force CRITICAL state and watch mobs respond in real time.

Is the config validator mandatory?

No, but strongly recommended. Run `/nlag validate` after every manual config edit to catch type mismatches, out-of-range values, and missing fields before they cause runtime errors.

What happens to mobs when I do /nlag reload?

As of 1.5.1: all pending batch tasks are cancelled, `restoreAll()` runs (mobs get full AI back), then all services restart with the new config. No mobs are left in a restricted state.

---

📄 Credits

Modrinth: Duong2012G Modrinth: Apache 2.0 Modrinth: https://modrinth.com/user/Duong2012G

*Open source — contributions welcome.*

---

📋 Changelog

See CHANGELOG.md for a full version history.

1.3.0 - 1.3.0 — 5 targeted bug fixes: wrong `api-version` in `plugin.yml`, web token not generated when disabled, culling count wrong with protected zones, AI update scheduler saturation, stress test crash on dense spawn areas, MySQL reconnect log spam - 1.3.0 — 4 critical + 5 high bug fixes: task leak, mob freeze, entity scan cache, FOLLOW_RANGE restore, query-token security, Redis/MySQL stability, zone culling, lang backup - 1.3.0 — Lifecycle overhaul, zone protection, backup bundles, web auth improvements - 1.3.0 — Predictive scheduler, zone manager, web dashboard, multi-server sync, config profiles, backup system, developer API