🧠 NeuroLag v1.2.0

Smart, TPS-aware mob AI optimization with 18+ advanced features

NeuroLag monitors your server's TPS in real time and automatically optimizes mob AI when performance drops — then fully restores everything when the server recovers. With 18+ advanced features, it's built for survival, minigame, and high-population servers.

✨ Features (28 Total)

Original Features (v1.0.5-1.0.6)

#	Feature	Description
🔮	Tiered Optimization	MEDIUM (reduce range) and CRITICAL (disable AI) states
🏘️	Chunk-Based AI	Mobs near players always keep AI, only distant mobs optimized
🐌	Tick-Rate Throttling	Mobs sluggish instead of frozen in MEDIUM state
🥚	Spawn Suppression	Lower mob spawn caps during lag
💬	Per-Player Notify	Players see action bar when nearby mobs are optimized
🔬	Simulate Mode	`/nlag simulate <tps>` to test without real lag
📝	Auto Lag Reports	Timestamped reports after CRITICAL events
🛡️	Entity Whitelist	Bosses, named mobs, and pets never touched
🔔	Discord Webhook	Posts embeds to Discord on lag events
🧬	Memory Pressure	Aggressive optimization when JVM heap > 80%
👥	Player-Count Scaling	Thresholds adjust as player count changes
📊	TPS Graph	In-game ASCII history chart via `/nlag graph`

New Features (v1.1.0)

#	Feature	Description
1️⃣	CPU Throttling Mode	Detect and optimize during CPU lag (>80%)
2️⃣	Region-Based Optimization	Smart regional optimization instead of global
3️⃣	Custom Mob Tier Weights	Different mobs have different "cost"
4️⃣	Animation Freezing	Stop animations, not just AI
5️⃣	Real-Time Metrics API	Plugin-to-plugin communication
6️⃣	In-Game Dashboard	Live BOSSBAR/HOLOGRAM health indicator
7️⃣	Detailed Audit Reports	HTML reports with server specs, plugins, mob analysis
8️⃣	Multi-Server Sync	Share TPS across Bungeecord/Velocity networks
9️⃣	AI Difficulty Scaling	Respects game difficulty settings
🔟	Mobile Web Dashboard	Access metrics from browser (phone/tablet)
1️⃣1️⃣	Predictive Prevention	Anticipate lag before it hits
1️⃣2️⃣	Custom Zones	WorldGuard integration for protected areas
1️⃣3️⃣	Smart Culling	Intelligent mob removal in groups
1️⃣4️⃣	Config Profiles	Instant profile switching (survival/minigame/etc)
1️⃣5️⃣	Audio/Visual Alerts	Sound and particle notifications
1️⃣6️⃣	Stress Test Mode	Simulate load without real lag
1️⃣7️⃣	Config Validator	Check configuration validity
1️⃣8️⃣	Auto Backup	Automatic config backups with auto-restore

📦 Installation

Download NeuroLag-1.1.0.jar
Place in plugins/ folder
Start server
Edit plugins/NeuroLag/config.yml and plugins/NeuroLag/en.yml
Run /nlag reload

Requirements: Paper 1.21+, Java 21+

🎮 Commands

All require neurolag.admin (default: op). Aliases: /neurolag, /nl

Command	Description
`/nlag`	Show help panel
`/nlag status`	Current TPS, stats, and activation counts
`/nlag graph`	ASCII TPS history
`/nlag toggle`	Pause/resume monitoring
`/nlag simulate <tps>`	Test a specific TPS value
`/nlag reload`	Hot-reload config
`/nlag dashboard`	Show in-game dashboard
`/nlag audit`	Generate audit report
`/nlag zone`	Zone management
`/nlag profile <name>`	Switch config profile
`/nlag validate`	Validate configuration
`/nlag backup`	Manage backups
`/nlag stresstest`	Run stress test

🔐 Permissions

Permission	Description	Default
`neurolag.admin`	Full control	`op`
`neurolag.stresstest`	Run stress tests	`op`
`neurolag.dashboard`	View dashboard	`op`
`neurolag.audit`	View reports	`op`
`neurolag.zone`	Manage zones	`op`
`neurolag.profile`	Switch profiles	`op`
`neurolag.validate`	Validate config	`op`
`neurolag.backup`	Manage backups	`op`
`neurolag.web`	Web dashboard	`op`
`neurolag.api`	Metrics API	`true`

⚙️ Configuration

The main file is config.yml. This file contains:

Core settings (TPS thresholds, check interval, etc.)
Feature toggles (enable/disable 18 features)
Per-world settings

Language-specific messages are in separate files:

en.yml — English (default)
vi.yml — Vietnamese
es.yml — Spanish
fr.yml — French
de.yml — German
ja.yml — Japanese
zh.yml — Chinese

Set language in config.yml:

settings:
  language: en  # en, vi, es, fr, de, ja, zh

Core Settings

settings:
  language: en              # Language file to load
  check-interval: 10        # TPS check frequency (seconds)
  enable-logging: true      # Log events to console
  hysteresis-buffer: 0.5    # TPS recovery threshold

Tier Configuration

tiers:
  medium:
    tps-trigger: 18.0       # Activation threshold
    range-multiplier: 0.5   # Follow range reduction
  critical:
    tps-trigger: 15.0       # Critical threshold

Feature Toggle

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

region-optimization:
  enabled: true

mob-weights:
  enabled: true
  
animation-freezing:
  enabled: true

# ... and 14 more features in config.yml

🧠 How It Works

Every <check-interval> seconds:
│
├─ Read TPS
├─ Apply memory-pressure offset if heap > 80%
├─ Apply player-count scaling
├─ Apply predictive offset if TPS trending down
│
└─ For each world:
     ├─ Compute state: NORMAL / MEDIUM / CRITICAL
     │
     ├─ NORMAL   → restore all AI
     ├─ MEDIUM   → reduce follow range, tick-throttle distant mobs
     └─ CRITICAL → disable AI on distant mobs, cull excess mobs

Every server tick (background):
└─ Throttle task cycles through MEDIUM mobs
   → AI on for 1 tick every N ticks

🔧 Advanced Features

CPU Throttling (Feature 1)

cpu-throttling:
  enabled: true
  cpu-threshold: 80        # CPU % before activation
  mode: THROTTLE_TASKS

Region-Based Optimization (Feature 2)

region-optimization:
  enabled: true
  use-regions: true
  regions-size: 16         # 16×16 chunks per region

Custom Mob Weights (Feature 3)

mob-weights:
  enabled: true
  weights:
    ZOMBIE: 1.0
    SKELETON: 1.2
    CREEPER: 1.5
    ENDERMAN: 2.0

Web Dashboard (Feature 10)

web-dashboard:
  enabled: true
  port: 8080
  auth:
    token: "your-secret-key"

Config Profiles (Feature 14)

config-profiles:
  enabled: true
  
  profiles:
    survival:
      critical-tps: 15.0
      max-entities: 500
    minigame:
      critical-tps: 12.0
      max-entities: 1000

📊 Performance Impact

NeuroLag is designed to have minimal impact when TPS is good:

NORMAL state: No optimization, zero overhead
MEDIUM state: Minor reduction in AI processing
CRITICAL state: Aggressive optimization, significant TPS gain

Expected improvements:

Light servers: 5-10% TPS gain
Medium servers: 10-30% TPS gain
Overloaded servers: 30-50%+ TPS gain

🐛 Troubleshooting

Q: Mobs aren't being optimized

Check if plugin is enabled: enabled: true in config.yml
Verify TPS triggers: Set tps-trigger low for testing
Run /nlag status to check current state

Q: Server is too laggy even with optimization

Enable CPU throttling: cpu-throttling.enabled: true
Lower max-entities-per-world
Try lower critical-tps threshold
Check plugin list for conflicts

Q: Want to protect specific mobs

Use entity whitelist: Add mob types to whitelist-types
Use protect-named-mobs: true for custom-named mobs
Use protect-tamed-mobs: true for player pets

Q: How to test optimization

Use /nlag simulate 14 to force TPS=14
Use /nlag stresstest to simulate load
Run /nlag validate to check config

📜 Changelog

See CHANGELOG.md for detailed version history.

Current: v1.1.0 (2026-03-14)

Added 18 new features
Fixed 5 bugs from v1.0.6
Enhanced documentation
Multi-language support

📝 License

🙏 Support

For issues, questions, or suggestions:

Visit: https://modrinth.com/user/Duong2012G
Report bugs with /nlag audit output

Enjoy smooth servers! 🚀

NeuroLag