NeuroLag
面向 Paper 26.1+ 的智能 TPS 感知生物 AI 优化器
在卡顿发生前保护你的 TPS —— 并在服务器恢复后悄然撤销所有操作。
? 下载 • ? 报告错误 • ? 更新日志
? 目录
- ✨ 功能特性
- ? 工作原理
- ? 前置要求
- ? 安装指南
- ⌨️ 命令与权限
- ? 配置说明
- ? Web 仪表盘
- ? 多服同步
- ?️ 受保护区域
- ?️ 配置文件集
- ? 备份系统
- ? 开发者 API
- ? 故障排除
- ❓ 常见问题
- ? 致谢
? 1.9.0 版本更新内容
- Minecraft 26.x:支持 Paper 26.1+、Java 25、世界键(
minecraft:the_nether)、SpawnCategory、原版 /tick 命令支持,以及无生成区块感知功能。
- 崩溃安全的生物状态:原始 AI 和跟随范围存储在生物的玩家定制数据(PDC)中,并在区块加载时恢复——在卡顿事件或崩溃后没有任何生物会保持冻结状态,且 NPC/无 AI 生物永远不会被唤醒。
- 所有生物均被优化:不再仅限于每个世界的第一个 80 个生物;坐骑/骑乘者/拴绳/持久性生物不会被剔除。
- 恢复功能在任何玩家数量下均可工作(此前在约 38 名玩家时会卡在 MEDIUM 状态)。
- 重载真正生效;
/nlag toggle 确实能暂停服务。
- 更安全的 Web 仪表盘与同步(默认回环地址,无通配符 CORS,优先 TLS 的 MySQL,唯一服务器 ID)。
完整列表请参阅 CHANGELOG.md。
✨ 功能特性
? 智能 TPS 状态机
NeuroLag 持续采样 TPS、CPU 负载、堆内存使用率、玩家数量及预测趋势数据,以决定在每个世界中应用以下三种状态之一:
| 状态 |
默认触发条件 |
效果 |
NORMAL |
TPS ≥ 18.0 |
无限制;完全恢复 AI |
MEDIUM |
TPS < 18.0 |
缩放跟随范围,限制寻路,启用刻节流 |
CRITICAL |
TPS < 15.0 |
完全禁用 AI,抑制生成,智能剔除 |
所有阈值均可按世界单独配置,并可通过配置文件集覆盖。迟滞缓冲(默认 0.5 TPS)可防止在边界处出现震荡。
⚡ 31 项优化功能
F1 — CPU 节流惩罚
监控 JVM CPU 使用率。当使用率超过配置的阈值(默认 80%)时,对有效 TPS 计算施加 1.5 的惩罚值,从而在服务器线程饱和之前触发更严格的生物优化。
F2 — 基于区域的寻路截止
将每个世界划分为可配置的区域。超出寻路距离阈值(disable-pathfinding-distance-chunks: 8)的生物,其 FOLLOW_RANGE 属性将被清零,从而消除那些玩家永远看不到的生物的昂贵 A* 寻路计算。
F3 — 基于区块的 AI 切换
在 CRITICAL 状态下,距离任何玩家超出可配置区块半径(distance-chunks: 4)的生物将完全禁用 AI。范围内的生物无论服务器状态如何,始终保留完整的 AI。
F4 — 速度冻结
处于 AI 禁用状态的远距离生物,其速度将被清零以防止被动漂移。可配置最小冻结区块距离(freeze-distance-chunks: 6)。
F5 — 生成抑制
在 MEDIUM 和 CRITICAL 状态下,怪物和动物的生成上限会降低(monster-limit: 30,animal-limit: 10),以便在服务器已承受负载时减缓生物种群的增长。
F6 — 智能剔除
当每世界实体数量在 CRITICAL 状态下超过 max-entities-per-world 时,将移除优先级最低的生物。支持三种剔除策略:
| 策略 |
行为 |
FAR_FROM_PLAYER |
首先移除距离任何玩家最远的生物 |
GROUP |
移除实例数量最多的生物类型 |
RANDOM |
随机排序并移除 |
受保护区域的生物以及命名/驯服的生物(如果在白名单中)绝不会被剔除。
F7 — 刻节流
在 MEDIUM 状态下,非优先生物仅在每 N 个游戏刻(ticks-per-ai-tick: 4)中执行一次 AI 逻辑,而不是每刻都执行。这在不完全禁用生物的情况下,将 AI 成本减半或减至四分之一。
F8 — 生物权重系统
每种实体类型都被分配一个权重分数。剔除时优先考虑重量最大的实体。完全可配置(features.yml 中的 zombies.yml 风格块)。
| 实体 |
默认权重 |
| 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 难度缩放
根据世界难度调整有效 TPS,以便在简单难度(玩家不太在意)下更早触发优化,而在困难难度(玩家希望获得完整的生物行为)下稍后触发。阈值始终会被钳制,以确保健康的服务器可以返回 NORMAL 状态。
| 难度 |
TPS 偏移量 |
| Peaceful (和平) |
+3.0 (永不优化) |
| Easy (简单) |
−1.0 (更早优化) |
| Normal (普通) |
0.0 |
| Hard (困难) |
+1.0 (推迟优化) |
F10 — 内存压力惩罚
监控 JVM 堆内存使用比率。当已用堆内存超过配置的阈值(默认 80%)时,将添加可配置的 TPS 惩罚值,在 GC 暂停发生前提前触发优化。
F11 — 预测调度器
跟踪滑动窗口内的历史 TPS 以及一组可配置的峰值时段。如果检测到早期向下的 TPS 趋势(在阈值被突破之前),将应用 earlyOffset 惩罚值以主动触发优化。
可配置的峰值时段示例:
peak-hours: "17:00-19:00,19:00-22:00"
F12 — 受保护区域
位于定义好的长方体区域(或 WorldGuard 区域)内的生物永远不会被限流、清除或修改属性。当检测到生物位于受保护区域时,跟随范围将始终恢复为默认值。
F13 — 智能群体清除
不是随机清除生物,而是按类型对实体进行分组,仅针对数量超过 min-type-before-cull 阈值的类型进行清除,在降低最高密度种群数量的同时保持生态多样性。
F14 — 玩家动作栏通知
靠近受影响生物的玩家在中度/危急状态下会收到动作栏警告。可配置半径(radius-blocks: 64)。
F15 — 警报系统
在状态转换时通过动作栏向管理员广播。支持可选的 Discord Webhook 和游戏内声音警报。
声音名称、粒子类型、粒子数量以及是否显示动作栏警报均可在 monitors.yml 下的 alerts.* 中配置。包含针对每位玩家的冷却机制,以防止在多世界服务器上造成感官混乱。
F16 — 玩家数量缩放
随着更多玩家加入,TPS 阈值会动态收紧。配置 min-players、max-players 和 max-threshold-offset,以便在玩家数量高峰期更积极地优化插件。
F17 — 动画冻结
在危急状态下,冻结超出 freeze-distance-chunks 距离的生物的速度,无需 NMS 或数据包级访问即可防止物理漂移。
F18 — 配置文件自动备份
按照可配置的频率自动创建所有 NeuroLag YAML 文件(包括 lang/ 目录)的时间戳 ZIP 包,并保留最近的 N 个副本。每个备份都附带一个 .sha256 校验和文件,在恢复之前会进行验证。通过限制单个条目(10 MB)和总恢复大小(50 MB)来防范 zip-bomb 攻击。
F19 — 危急状态的安全模式
如果在危急 TPS 层配置中启用,安全模式仅禁用危险的 AI 组件,同时保留必要的游戏机制。防止过度优化导致村民交易、生物逃离水域以及其他关键行为失效。
F20 — 生物重要性评分系统
根据类型、命名、驯服状态、装备和拴绳状态为所有生物分配重要性分数。命名的生物(10倍)、驯服的生物(20倍)和装备了物品的生物(1.5倍)获得更高的优先级。系统在清除操作中保护重要生物。
F21 — 生物行为组
将生物分类为行为组以进行针对性优化:
- PASSIVE(低优先级):牛、猪、羊、鸡
- AGGRESSIVE(高优先级):僵尸、骷髅、苦力怕
- NEUTRAL(中等优先级):末影人、铁傀儡
- SPECIAL(保留):村民、Boss、命名生物
- AQUATIC(水生):海豚、守卫者、鱿鱼
F22 — 动态区域大小
根据玩家数量自动调整区域大小以实现最佳性能:
- 0-5 名玩家:16 区块(大区域)
- 6-20 名玩家:8 区块(中等区域)
- 21-50 名玩家:4 区块(小区域)
- 50+ 名玩家:2 区块(非常小的区域)
F23 — 热点区域衰减
在最后一位玩家离开附近后,区域保持“热”状态 30 秒,然后冷却。这避免了玩家在传送或离开时生物立即冻结,同时也不会让区域无限期保持“热”状态。
F24 — EWMA 预测算法
指数加权移动平均线(EWMA)通过对近期样本赋予更高权重来提供更准确的短期 TPS 预测。平滑因子 Alpha 设为 0.3 以获得最佳响应速度。
F25 — 线性回归趋势分析
使用线性检测向下 TPS 趋势,从而在滞后发生前进行预测。
结合简单平均值和 EWMA 以实现稳健的预测准确性。
F26 — 基于注解的配置验证
@ConfigValidation 注解允许对配置值进行字段级验证规则。验证数值范围、必填字段和边界警告,并提供清晰的错误消息。
F27 — 配置迁移系统
自动检查版本并对配置文件进行逐步迁移。在迁移前创建备份并支持回滚。迁移 config.yml、features.yml、monitors.yml 和 systems.yml 的同时保留用户设置。
F28 — 事件驱动架构
EventBus 模式将优化逻辑与主引擎解耦。组件可以注册为 OptimizationListener 以响应优化状态的变化,从而使插件/附加组件能够扩展功能。
F29 — 重构后的优化器类
遵循单一职责原则,将优化逻辑提取到专用类中:
MobCuller - 带有重要性评分的实体清除
AIThrottler - AI 限流和刻管理
SpawnSuppressor - 生成率调整逻辑
F30 — 综合配置指南
CONFIG-GUIDE.md 提供了所有配置选项的详细解释,包括使用示例、推荐值以及按功能领域组织的故障排除提示。
F31 — 增强的配置注释
所有 YAML 配置文件(config.yml、features.yml、monitors.yml、systems.yml)
均包含详细的内联注释、章节标题和安全说明,以便于更好地理解和配置管理。
? 监控与报告
| 功能 |
描述 |
| BossBar 仪表盘 |
为管理员提供实时的 TPS、状态、CPU 和堆内存显示 |
| Web 仪表盘 |
嵌入式 HTTP 服务器,端口可配置,提供 JSON API |
| ASCII 图表 |
/nlag graph — 聊天中的 TPS 历史图表 |
| HTML 审计报告 |
按需或自动生成报告,涵盖服务器规格、插件列表、区块统计和生物分析。为避免主线程峰值,每个世界的实体收集上限为 5,000 个。完整的 HTML 转义可防止 XSS 攻击。 |
| 滞后报告 |
当事件持续时间超过最小持续时间时记录 |
| 指标 API |
用于第三方集成的插件消息通道(neurolag.api) |
? 多服务器同步
实时跨网络传播 TPS 状态。支持:
- Redis(推荐)— 通过 Pub/Sub 实现低于 100 毫秒的延迟
- MySQL — 基于轮询,适用于任何共享数据库
当对等服务器进入 CRITICAL(严重)状态时,级联警告会通知本地管理员。
?️ 配置预设 (Config Profiles)
在运行时切换命名的配置预设:
/nlag profile survival
/nlag profile event
/nlag profile clear
预设配置文件会覆盖 critical-tps、medium-tps 和 max-entities,而无需修改基础配置文件。
? 开发者 API
NeuroLagAPI api = NeuroLagAPI.getInstance();
api.getCurrentTps();
api.getWorldState("world"); // "NORMAL" | "MEDIUM" | "CRITICAL"
api.isManualOverride();
api.getCriticalActivationCount();
api.getMediumActivationCount();
? 工作原理
每隔 check-interval 秒执行一次检查(默认值:10):
原始 TPS
│
├─ 内存压力惩罚 (如果堆内存 > 阈值)
├─ CPU 节流惩罚 (如果 CPU > 阈值)
├─ 预测偏移量 (如果检测到下降趋势)
└─ 难度缩放 (按世界调整)
│
▼
有效 TPS
│
┌────────┴─────────┐
│ 迟滞有限状态机 │ NORMAL ↔ MEDIUM ↔ CRITICAL
└────────┬─────────┘
│
┌────────┴────────────────────────────────┐
│ 按世界优化处理流程 │
│ • 收集目标(缓存 4 个刻) │
│ • 生成抑制 │
│ • 智能剔除(仅在 CRITICAL 状态下) │
│ • 批量 AI/范围更新(每批 ≤ 50) │
│ • 管理员与玩家通知 │
└─────────────────────────────────────────┘
恢复至 NORMAL 状态时:
→ restoreWorld() — 对所有生物恢复完整的 AI + 默认的 FOLLOW_RANGE
? 依赖要求
| 组件 |
版本 |
备注 |
| Java |
25+ |
必需(Minecraft 26.x 运行于 Java 25) |
| Paper |
26.1+ |
必需;不支持 Spigot 和 Folia。Minecraft 1.21.x → 请使用 NeuroLag 1.8.x |
| WorldGuard |
7.0.17+ |
可选 — 启用 WG 区域集成(旧版 WorldGuard 不支持 26.x) |
| Redis |
任意近期版本 |
可选 — 用于多服务器同步 |
| MySQL |
8.x / 9.x |
可选 — 替代同步后端 |
? 安装步骤
-
从 Modrinth 下载 NeuroLag-1.9.0.jar。
-
将其放入 plugins/ 文件夹。
-
启动服务器一次以生成所有配置文件。
-
编辑 plugins/NeuroLag/ 中的文件:
| 文件 |
用途 |
config.yml |
TPS 阈值、目标规则、按世界覆盖设置 |
features.yml |
切换和调整各项优化功能 |
monitors.yml |
仪表板、Web API、警报、Discord、审计日志 |
systems.yml |
同步、区域、预设、备份、验证器 |
-
运行 /nlag validate 以捕获配置错误。
-
运行 /nlag status 确认一切正常运行。
⚠️ 请勿使用 /reload。始终进行完整的服务器重启,或使用 /nlag reload 来应用 NeuroLag 相关的更改。
⌨️ 命令
| 命令 |
描述 |
权限 |
/nlag status |
显示 TPS、CPU、堆内存、各世界状态及激活计数 |
neurolag.admin |
/nlag graph |
ASCII TPS 历史图表(最近 60 个样本) |
neurolag.admin |
/nlag toggle |
暂停/恢复监控和生物优化 |
neurolag.admin |
/nlag simulate <tps|clear> |
强制设置 TPS 值以进行测试(0–20) |
neurolag.admin |
/nlag dashboard [off] |
显示/隐藏 BossBar 仪表板 |
neurolag.dashboard |
/nlag audit |
生成 HTML 审计报告 |
neurolag.audit |
/nlag zone |
显示已加载的保护区域 |
neurolag.zone |
/nlag profile [name|clear] |
切换或清除配置预设 |
neurolag.profile |
/nlag validate |
验证所有配置值并报告错误 |
neurolag.validate |
/nlag backup |
立即创建手动备份 ZIP 包 |
neurolag.backup |
/nlag backup list |
列出可用备份 |
neurolag.backup |
/nlag backup restore [file] |
从最新或指定名称的备份中恢复 |
neurolag.backup |
/nlag stresstest [count] [min] |
生成测试生物以进行负载测试 |
neurolag.stresstest |
/nlag sync |
显示多服务器对等节点的 TPS 状态 |
neurolag.admin |
/nlag reload |
热重载所有 NeuroLag 配置文件 |
neurolag.admin |
别名:/neurolag, /nl, /neuromob
? 权限
| 权限 |
描述 |
默认值 |
neurolag.admin |
完全控制;授予所有子命令权限 |
OP |
neurolag.dashboard |
使用 /nlag dashboard |
OP |
neurolag.audit |
使用 /nlag audit |
OP |
neurolag.zone |
使用 /nlag zone |
OP |
neurolag.profile |
使用 /nlag profile |
OP |
neurolag.validate |
使用 /nlag validate |
OP |
neurolag.backup |
使用 /nlag backup |
OP |
neurolag.stresstest |
使用 /nlag stresstest |
OP |
neurolag.web |
Web 仪表板访问控制(Bukkit 外部) |
OP |
neurolag.api |
通过 NeuroLagAPI 读取插件指标 |
true |
? 配置
NeuroLag 采用分离式配置布局。所有文件均位于 plugins/NeuroLag/ 目录下。
config.yml — 核心设置
settings:
language: en # en, vi, es, fr, de, ja, zh
check-interval: 10 # 两次 TPS 采样之间的间隔(秒)
enable-logging: true
hysteresis-buffer: 0.5 # 状态恢复前的 TPS 间隙缓冲
tiers:
medium:
tps-trigger: 18.0
range-multiplier: 0.5 # 在 MEDIUM 状态下将生物 FOLLOW_RANGE 缩放为 50%
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 — 优化开关
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% = 施加惩罚
offset: 0.5
smart-culling:
enabled: true
cull-in-groups: true
min-type-before-cull: 2
removal-particle: POOF
### `monitors.yml` — 仪表盘与警报
```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 # 出于安全考虑请保持为 false
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 — 维护与同步
stress-test:
enabled: false
max-mob-count: 2000
cooldown-seconds: 300
max-mobs-per-chunk: 80 # 1.5.2 新增 —— 崩溃预防密度上限
entity-types:
- ZOMBIE
- SKELETON
- CREEPER
multi-server:
enabled: false
backend: REDIS # REDIS 或 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
? 安全性
自 1.9.0 版本起,仪表盘默认绑定到本地回环地址(loopback),使用恒定时间令牌比较,不再支持通配符 CORS,且在重载时不再泄露线程信息——详见更新日志。
Web 仪表盘加固 (v1.5.2)
NeuroLag 1.5.2 为 Web 仪表盘带来了三项安全改进:
| 功能 |
默认值 |
配置键 |
| 自动生成安全令牌 |
启用(每次调用 start() 时替换占位符,即使仪表盘已禁用) |
monitors.yml 中的 web-dashboard.auth.token |
| 按 IP 限流 |
60 次请求/分钟 |
monitors.yml 中的 web-dashboard.rate-limit |
| IP 白名单 |
禁用 |
monitors.yml 中的 web-dashboard.ip-whitelist |
在首次启动时,如果令牌仍然是 "change-this-token-now",NeuroLag 会自动生成一个密码学安全的随机令牌,将其保存到 monitors.yml(如果需要则创建该文件),并将其打印到控制台。请将其用作你的 Authorization: Bearer <token> 头部。
1.5.2 修复: 令牌生成现在在 enabled 检查之前运行,因此即使你设置了 web-dashboard.enabled: false,占位符也会被替换。以前,如果在初始设置后开启仪表盘,直到下次重启前默认令牌仍可能暴露。
? Web 仪表盘
内置的 HTTP 服务器提供了一个实时仪表盘和 JSON API。
路由:
| 路由 |
方法 |
描述 |
/ |
GET |
HTML 实时仪表盘(自动刷新) |
/api/status |
GET |
JSON 指标快照 |
/api/cmd |
POST |
受限的命令桥接 |
通过 /api/cmd 允许的指令: reload, status, graph, validate
网络: 服务器默认绑定到 127.0.0.1 (web-dashboard.bind-address)。如需远程访问,请在前面放置反向代理,或者明知风险地设置为 0.0.0.0。除非设置了 cors-allowed-origin,否则 CORS 处于关闭状态。
认证:
在浏览器中打开 http://host:8080/#token=<token> —— URL 片段永远不会发送给服务器或被记录。对于 API 调用,请始终使用 Authorization: Bearer <token> 请求头。?token=...
查询字符串回退方式默认禁用 (allow-query-token: false),因为 URL 中的令牌会出现在服务器访问日志和浏览器历史记录中。
# 正确做法
curl -H "Authorization: Bearer my-secret-token" http://localhost:8080/api/status
# 可行但不安全 —— 仅在 allow-query-token: true 时有效
curl "http://localhost:8080/api/status?token=my-secret-token"
⚠️ 请务必更改默认令牌,并且切勿在没有反向代理或防火墙规则的情况下将 Web 仪表盘端口公开暴露。
? 多服务器同步
在网络间共享 TPS 状态,使操作员可以从一个地方查看每个节点的健康状况。
Redis (推荐)
multi-server:
enabled: true
backend: REDIS
cascade-warnings: true
redis:
host: localhost
port: 6379
password: ""
MySQL
multi-server:
enabled: true
backend: MYSQL
mysql:
host: localhost
port: 3306
database: neurolag
user: root
password: ""
使用 /nlag sync 查看实时对等体状态:
[NeuroLag] This server: MyServer_25565
- LobbyServer_25565 → 19.8 TPS [NORMAL]
- SurvivalNode_25566 → 16.2 TPS [MEDIUM]
v1.5.1: Redis 订阅者在重载时现在可以干净退出。MySQL 重连使用指数退避算法,以避免在数据库中断期间产生大量日志垃圾。
?️ 受保护区域
定义方块区域,在这些区域内生物永不被优化、限速或清除。
zone-protection:
enabled: true
integrate-worldguard: false # 设置为 true 以同时保护 WorldGuard 区域
zones:
- "world 0 60 0 100 200 100" # world minX minY minZ maxX maxY maxZ
- "world_nether -50 0 -50 50 128 50"
受保护的生物始终拥有:
- AI 启用
FOLLOW_RANGE 恢复至 Minecraft 默认值
- 速度未冻结
- 免疫智能清除
v1.5.1: FOLLOW_RANGE 现在会在每次优化传递时无条件地为受保护生物恢复,而不仅仅是当生物恰好重新进入区域时。
?️ 配置配置文件
在不编辑文件的情况下,在运行时切换命名预设。
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 — 切换到事件配置
/nlag profile clear — 返回基础配置
/nlag profile — 显示所有配置 + 当前激活的配置
? 备份系统
自动备份会将所有 NeuroLag .yml 文件(包括 lang/ 目录)保存为带时间戳的 ZIP 压缩包。
auto-backup:
enabled: true
backup-interval-minutes: 60
keep-backups: 10
备份存储在 plugins/NeuroLag/backups/ 中。
/nlag backup — 立即创建
/nlag backup list — 列出所有备份
/nlag backup restore — 恢复最新的备份
/nlag backup restore config-bundle-2026-04-18_12-00-00.zip
v1.6.0 安全改进:
- 每个备份 ZIP 都附带一个
.sha256 校验和文件。
- 恢复时会先校验校验和,如果不匹配则中止并记录
SEVERE 日志。
- Zip-bomb 保护:单个条目上限 10 MB,总恢复上限 50 MB。
- 备份列表缓存于内存中;
purgeOld() 使用基于文件名的排序——无需文件系统 stat 调用。
v1.5.1: lang/ 子目录已包含在所有备份包中,以便在恢复时不会丢失自定义语言文件。
? 开发者 API
// 获取 API 实例
NeuroLagAPI api = NeuroLagAPI.getInstance();
// 读取当前 TPS 和世界状态
double tps = api.getCurrentTps();
String state = api.getWorldState("world"); // "NORMAL" | "MEDIUM" | "CRITICAL"
boolean override = api.isManualOverride();
// 读取生命周期计数器
int critCount = api.getCriticalActivationCount();
int medCount = api.getMediumActivationCount();
通过插件消息通道 neurolag.api 订阅状态变更(需要目标玩家拥有设置为 true 的 neurolag.api 权限)。
? 故障排除
在出生点生成大量生物时压力测试导致服务器崩溃
已在 1.5.2 中修复。压力测试现在会在生成前检查出生点周围 7×7 区块网格内的每区块生物密度(默认 stress-test.max-mobs-per-chunk 为 80)。如果超出限制,数量会自动减少。请更新至 1.5.2。
启用 Web 仪表板后,Token 仍保持为默认占位符
已在 1.5.2 中修复。Token 生成现在在 enabled 检查之前运行,因此无论仪表板是否启动,占位符都会被替换。请更新至 1.5.2。
MySQL 日志刷屏:数据库中断期间,“连接丢失 — 正在重连”的消息充斥控制台
已在 1.5.2 中修复。重连日志消息现在使用与 SQL 错误相同的 2 的幂次间隔过滤器进行抑制(在第 1、2、4、8、16… 次间隔时记录)。请更新至 1.5.2。
当区域保护激活时,实体数量始终高于 maxEntities
已在 1.5.2 中修复。清除阶段现在在计算移除数量前先过滤受保护的生物,因此数学计算正确,即使部分生物受到区域保护,引擎也能收敛到目标实体数量。请更新至 1.5.2。
/nlag toggle 或 /nlag reload 后生物被冻结
已在 1.5.1 中修复。飞行中的批处理任务在 restoreAll() 运行后会重新应用 AI 限制。请更新至 1.5.1,问题即可解决。如果你运行的是 1.4.0,请触发完整的服务器重启作为临时解决方案。
即使在 NeuroLag 激活的情况下,高生物密度的服务器上 TPS 仍不断飙升
确保 collectTargets 缓存处于激活状态(1.5.1+)。在旧版本中,实体扫描会在每个刻运行。此外,请在 features.yml 中降低 check-interval 并减少 max-entities-per-world。
服务器恢复正常至 NORMAL 后,FOLLOW_RANGE 仍保持降低状态
已在 1.5.1 中修复。受保护区域的生物以及从非 NORMAL 状态恢复到 NORMAL 的世界中的生物,现在都会通过新的 restoreWorld() 调用将 FOLLOW_RANGE 重置为 Minecraft 默认值。
重载时 Redis/MySQL 异常充斥日志
已在 1.5.1 中修复。Redis 订阅者现在在池关闭前加入。MySQL 重连使用指数退避算法,因此错误仅在第 1、2、4、8、16… 次间隔时记录。
Web 仪表板 Token 出现在服务器访问日志中
设置 allow-query-token: false(1.5.1 中的默认值),并使用 Authorization: Bearer <token> 标头代替。
自定义语言文件在备份恢复后丢失
已在 1.5.1 中修复。备份包现在包含 lang/ 子目录。从 1.5.1 的备份中恢复以找回语言文件。
受保护区域内的生物被智能清除机制移除
已在 1.5.1 中修复。cull() 方法现在在移除任何生物之前会检查 zoneManager.isProtected()。请更新至 1.5.1。
完全没有进行任何优化
- 运行
/nlag validate — 查找配置错误。
- 运行
/nlag status — 检查 Override 是否显示为 OFF。
- 检查
config.yml 中的 ignored-worlds — 你的世界可能被排除在外。
- 使用
/nlag simulate 10 强制进入 CRITICAL 状态并验证生物是否有响应。
- 检查
config.yml 中的 targets — hostile-mobs 和 water-mobs 必须设为 true。
即使使用正确的 Token,Web 仪表板也返回 401 错误
确保你将 Token 发送在 Authorization 标头中,而不是查询字符串中(allow-query-token 默认为 false)。示例:
curl -H "Authorization: Bearer your-token-here" http://localhost:8080/api/status
/reload 破坏了插件
请使用 /nlag reload 而不是服务器级别的 /reload 命令。
服务器的 /reload 可能会在任何插件中留下悬空任务和损坏的事件注册。
❓ 常见问题
NeuroLag 会影响玩家行为吗?
不会。它仅修改非玩家生物(mob)的 AI 和行为属性值(FOLLOW_RANGE)。玩家、他们的物品以及能力均不受影响。
生物会永久冻结吗?
不会。当服务器返回 NORMAL 状态、插件被禁用,或使用 /nlag toggle 暂停监控时,NeuroLag 总会恢复完整的 AI 和默认属性。
是否支持多世界?
支持。每个世界都有独立的状态机进行跟踪。可以在 config.yml 下的 world-settings 中配置每个世界的 TPS 阈值。
是否支持 Folia?
不支持。NeuroLag 使用 Bukkit 调度器 API,这与 Folia 的区域级线程模型不兼容。未来版本计划支持 Folia。
可以与其他优化插件一起使用吗?
可以,但请确保剔除(culling)和禁用 AI 的设置之间没有冲突。NeuroLag 旨在与 Spark、ClearLag 和 Chunky 等插件共存。
如何确认它正在工作?
运行 /nlag status —— 你将看到当前的 TPS、CPU、堆内存、各世界状态以及累计激活次数。运行 /nlag simulate 10 强制进入 CRITICAL 状态,并实时观察生物的响应。
配置验证器是必须的吗?
不是必须的,但强烈建议启用。每次手动编辑配置后,请运行 /nlag validate,以便在引发运行时错误之前捕获类型不匹配、超出范围的值以及缺失字段。
执行 /nlag reload 后生物会发生什么?
从 1.5.1 版本开始:所有待处理的批处理任务将被取消,restoreAll() 将会运行(生物恢复完整 AI),然后所有服务将使用新配置重新启动。不会有生物停留在受限状态。
? 致谢
作者: Duong2012G
许可证: Apache 2.0
Modrinth:
开源 — 欢迎贡献。
? 更新日志
请参阅 CHANGELOG.md 获取完整的版本历史记录。
近期亮点:
- 1.8.0 — 代码审计版本:修复了 7 个漏洞,完成了 2 项未完成的重构,移除了死代码。关键修复包括:RegionOptimizer 的热查找在动态扩容后失效(导致玩家旁边的生物冻结)、长时间运行的服务器上
pendingBatchTasks 的内存泄漏、AIThrottler 的单一职责原则(SRP)重构已完全集成、applyHotRegionDecay 并发修改问题、EventBus 错误记录到 System.err
- 1.7.1 — 5 项针对性漏洞修复:安全模式下的 FOLLOW_RANGE 在每个 tick 中被静默覆盖、Slime/Bat 实体类型在 SafeModeOptimizer 中抛出 NullPointerException、restoreAI() 使用了硬编码的 FOLLOW_RANGE 表而忽略了自定义属性、HARD/EASY 难度缩放逻辑颠倒、Web 仪表板因扫描 IP 导致的速率限制映射内存泄漏
- 1.7.0 — 重大架构重构:提取 MobCuller/AIThrottler/SpawnSuppressor 的单一职责原则(SRP)、引入 EventBus 模式、MobImportanceScorer、MobBehaviorGroups、动态区域大小调整、EWMA+LR 预测、基于注解的配置验证、配置迁移系统
- 1.5.2 — 5 项针对性漏洞修复:
plugin.yml 中的 api-version 错误、禁用时未生成 web token、受保护区域下剔除计数错误、AI 更新调度器饱和、密集刷怪区压力测试崩溃、MySQL 重连日志泛滥
- 1.5.1 — 4 项严重 + 5 项高危漏洞修复:任务泄漏、生物冻结、实体扫描缓存、FOLLOW_RANGE 恢复、查询令牌安全性、Redis/MySQL 稳定性、区域剔除、语言包备份
- 1.4.0 — 生命周期重构、区域保护、备份捆绑包、Web 身份验证改进
- 1.3.0 — 预测调度器、区域管理器、Web 仪表板、多服务器同步、配置配置文件、备份系统、开发者 API
NeuroLag
Smart TPS-aware mob AI optimizer for Paper 26.1+
Protect your TPS before the lag even starts — then quietly undo everything when the server recovers.
? Download • ? Report a Bug • ? Changelog
? 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
? What's new in 1.9.0
- Minecraft 26.x: Paper 26.1+, Java 25, world keys (
minecraft:the_nether), SpawnCategory, vanilla /tick support, no-spawn-chunk aware.
- Crash-safe mob state: original AI/follow-range stored in the mob's PDC and restored on chunk load — nothing stays frozen after a lag event or a crash, and NPC/NoAI mobs are never woken up.
- All mobs are optimised, not just the first 80 per world; mounts/riders/leashed/persistent mobs are never culled.
- Recovery works at any player count (previously stuck in MEDIUM from ~38 players).
- Reload really reloads;
/nlag toggle really pauses.
- Safer web dashboard & sync (loopback by default, no wildcard CORS, TLS-preferred MySQL, unique server ids).
See CHANGELOG.md for the complete list.
✨ 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 based on world difficulty, so optimization triggers earlier on Easy (players care less) and later on Hard (players want full mob behaviour). Thresholds are always clamped so a healthy server can return to NORMAL.
| 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:
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
A region stays hot for 30 seconds after the last player was near it, then cools down. This avoids mobs
freezing the instant a player teleports or leaves, without keeping regions hot indefinitely.
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 |
| BossBar Dashboard |
Real-time TPS, state, CPU, and heap display for admins |
| Web Dashboard |
Embedded HTTP server at configurable port with JSON API |
| ASCII Graph |
/nlag graph — TPS history chart in chat |
| HTML Audit Reports |
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. |
| Lag Reports |
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:
- Redis (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
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 |
25+ |
Required (Minecraft 26.x runs on Java 25) |
| Paper |
26.1+ |
Required; Spigot and Folia are not supported. Minecraft 1.21.x → use NeuroLag 1.8.x |
| WorldGuard |
7.0.17+ |
Optional — enables WG region integration (older WorldGuard does not support 26.x) |
| Redis |
Any recent |
Optional — for multi-server sync |
| MySQL |
8.x / 9.x |
Optional — alternative sync backend |
? Installation
-
Download NeuroLag-1.9.0.jar from Modrinth.
-
Place it in your plugins/ folder.
-
Start the server once to generate all config files.
-
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 |
-
Run /nlag validate to catch configuration errors.
-
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
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
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
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
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
Since 1.9.0 the dashboard binds to loopback by default, uses constant-time token comparison, has no wildcard CORS and no longer leaks threads on reload — see the changelog.
Web dashboard hardening (v1.5.2)
NeuroLag 1.5.2 ships with three security improvements to the web dashboard:
| Feature |
Default |
Config Key |
| Auto-generated secure token |
Enabled (replaces placeholder on every start() call, even when dashboard is disabled) |
web-dashboard.auth.token in monitors.yml |
| Per-IP rate limiting |
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
Network: the server binds to 127.0.0.1 by default (web-dashboard.bind-address). Put a reverse proxy in front for remote access, or set 0.0.0.0 knowingly. CORS is off unless cors-allowed-origin is set.
Authentication:
In a browser open http://host:8080/#token=<token> — the URL fragment is never sent to the server or logged. For API calls 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.
# 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)
multi-server:
enabled: true
backend: REDIS
cascade-warnings: true
redis:
host: localhost
port: 6379
password: ""
MySQL
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.
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
v1.5.1: 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.
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.
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
// 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
- Run
/nlag validate — look for config errors.
- Run
/nlag status — check that Override shows OFF.
- Check
ignored-worlds in config.yml — your world may be excluded.
- Use
/nlag simulate 10 to force CRITICAL state and verify mobs respond.
- 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:
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
Author: Duong2012G
License: Apache 2.0
Modrinth:
Open source — contributions welcome.
? Changelog
See CHANGELOG.md for a full version history.
Recent highlights:
- 1.8.0 — Code audit release: 7 bugs fixed, 2 incomplete refactors completed, dead code removed. Key fixes: RegionOptimizer HOT lookup broke after dynamic resize (mobs froze next to players),
pendingBatchTasks memory leak on long-running servers, AIThrottler SRP refactor fully wired, applyHotRegionDecay concurrent-modification, EventBus errors logged to System.err
- 1.7.1 — 5 targeted bug fixes: Safe Mode FOLLOW_RANGE silently overwritten every tick, NullPointerException in SafeModeOptimizer on Slime/Bat entity types, restoreAI() used a hardcoded FOLLOW_RANGE table ignoring custom attributes, HARD/EASY difficulty scaling inverted, Web Dashboard rate-limit map memory leak from scanner IPs
- 1.7.0 — Major architecture refactor: MobCuller/AIThrottler/SpawnSuppressor SRP extraction, EventBus pattern, MobImportanceScorer, MobBehaviorGroups, dynamic region sizing, EWMA+LR prediction, annotation-based config validation, config migration system
- 1.5.2 — 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.5.1 — 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.4.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
评论 0
登录后参与评分
还没有评论,来抢沙发吧