<div align="center">

# 🐱 Neko Core

**喵核心** · 为高负载生存 / 战争服打造的 Folia 定制服务端

*碰撞加速 · 网络优化 · 实时可观测 · 一键调优*

<br>

![MC](https://img.shields.io/badge/Minecraft-1.21.8-blue?style=for-the-badge)
![Base](https://img.shields.io/badge/Based%20on-Folia%20/%20Luminol-brightgreen?style=for-the-badge)
![Java](https://img.shields.io/badge/Build-Java%2025-orange?style=for-the-badge)
![License](https://img.shields.io/badge/License-GPL%20v3-red?style=for-the-badge)

`AUTO` · `GPU` · `FFM` · `JAVA` · `VANILLA` —— 碰撞后端，游戏内热切换

</div>

---

## 🎯 这是什么

**Neko Core** 是在 [Luminol 1.21.8](https://github.com/LuminolMC/Luminol)（Folia 分支）之上的定制服务端，把三套各自为政的优化整合成一个能打的整体：

| 体系 | 来自 | 解决什么 |
| :--- | :--- | :--- |
| 🚀 **AR 碰撞加速** | AcceleratedRecoiling | 高实体密度下的碰撞计算瓶颈 |
| 🌐 **网络优化** | Kitin | 弱网卡顿、带宽爆炸、地形/粒子刷屏 |
| 🧹 **LagFixer / ESU** | LagFixer + ESU | 实体堆积、爆炸卡服、挂机跟踪、冗余发包 |

> 构建基线 **Java 25**，全程对照 **Paper/Folia 原版**做实测，数字不掺水。

---

## ⚡ 性能亮点：AR 碰撞加速

不是"叠加一层 native"，而是**真正替换掉原版那次昂贵的空间查询**——tick 前用 native 广相位算出 per-region 碰撞图（线程隔离，Folia 安全），`pushEntities` 直接 O(1) 查图，原版推挤/拥挤伤害逻辑完全保留。

**实测**（对照已优化的 Paper/Folia 原版，MSPT 越低越好）：

```
场景：8000 实体散布                     场景：3000 实体密集
┌──────────┬─────────┬─────────┐        ┌──────────┬─────────┬─────────┐
│ 后端     │  MSPT   │ vs 原版 │        │ 后端     │  MSPT   │ vs 原版 │
├──────────┼─────────┼─────────┤        ├──────────┼─────────┼─────────┤
│ FFM   🥇 │  78.5ms │  3.19×  │        │ FFM   🥇 │  24.1ms │  3.05×  │
│ JAVA     │ 204.6ms │  1.23×  │        │ VANILLA  │  73.6ms │  1.00×  │
│ VANILLA  │ 250.8ms │  1.00×  │        │ JAVA     │  94.0ms │  0.78×  │
└──────────┴─────────┴─────────┘        └──────────┴─────────┴─────────┘
                  FFM 稳定 ~3× 领先原版
```

> 📌 不是"数十倍"——因为对照组是**已经有空间索引优化的 Paper/Folia**，不是裸原版。3× 是实打实可复现的硬提升。

---

## 🧩 功能一览

### 🚀 碰撞加速（默认开）
- 多后端：`AUTO / GPU / FFM / JAVA / VANILLA`，启动优先 FFM、失败自动回退
- FFM：批量内存拷贝 + 零分配路径 + 碰撞数削峰
- 密度门控：只有局部密集的实体走加速，稀疏实体走原版（零行为偏差）

### 🌐 网络优化（`config/Network.yml`）
- **区块惰性加载** — 小范围反复横跳不重发地形包
- **高频实体包减量** — 船/矿车在农场不再每 tick 强制同步；高速 TNT/掉落物/经验球跳过冗余包
- **粒子限流打包** — 视野/距离/遮挡剔除后再发，治领地特效刷屏
- **区块发送限速 + QoS** — 全局限速 + 按 IP/域名/线路分组限流、级联限流
- **玩家自适应限流** — 按延迟/抖动动态收紧弱网玩家的发送率与跟踪范围
- **多端口监听** — 额外端口可单独配 PROXY Protocol v2（FRP 与直连共存）

### 🧹 LagFixer / ESU（默认关，按需开）
- **EntityLimiter** — 每区块实体上限 + 周期溢出清扫（带削峰：单次清扫有移除上限，爆发不卡）。生成闸门用 per-chunk/per-tick 计数缓存，实体爆发时不再全 region 扫描（O(N²)→O(N)）
- **EntityCull 视锥剔除** 👁️ — 玩家视野锥外、且超出近距豁免半径的实体**不发包给该客户端**（背后的怪不占带宽/不卡客户端）。转身即恢复（每 tick 重判），近距离始终可见防贴脸突现。多人混战 / 刷怪海减客户端压力专用
- **MobAiThrottle** 🧟 — 远离玩家的怪物寻路/索敌降频（按非活跃时长分级），玩家靠近立即恢复。**惊变100天 / 刷怪海专治**，移动控制仍每 tick 不抽搐
- **MobAiReducer** — 精简生物 AI 目标
- **ExplosionOptimizer** — 爆炸威力上限 / 防连锁 / 管理模式
- **AFK 实体跟踪降频** — 全员挂机且实体远时降频，活动即恢复
- **ESU 零位移包裁剪** — 跳过零位移/零旋转的实体移动包
- **ESU 生物 velocity 包降频** 🚦 — 走路的怪不再每 tick 发速度包（变化太小/发得太频就跳过，~20包/秒→7包/秒）；击退/爆炸/坠落立即发，玩家与投射物不受影响。丧尸海/混战第二大带宽源

### 📊 实时可观测
- **出站带宽实时监控** — 当前 Mbps、峰值、本次累计用量
- **内置 spark profiler** 🔥 — 原生集成（Folia 安全），`/spark` 直接可用：`profiler` 采样找热点、`health` 看 TPS/MSPT/CPU/内存。无需装插件，战争爆发时一条命令定位瓶颈

---

## 🎮 命令

```bash
# 碰撞后端
/nekobackend status                          # 当前后端与关键配置
/nekobackend set <AUTO|GPU|FFM|JAVA|VANILLA> # 运行时热切换
/nekobackend reload                          # 重载后端选择器

# 实时带宽
/nekobackend bandwidth                       # 出站带宽：现在 / 峰值 / 累计

# 内置 spark profiler（无需插件，Folia 安全）
/spark profiler --timeout 60                 # 采样 60s 找 MSPT 热点（出网页报告）
/spark health                                # TPS / tick 时长 / CPU / 内存
/spark tps                                   # 实时 TPS

# 一键开关优化模块（无需改配置重启）
/nekobackend toggle <module> <on|off>
#   module ∈ entity_limiter / entity_cull / explosion_optimizer / afk_entity_tracking /
#            mob_ai_reducer / mob_ai_throttle / skip_zero_delta_packets
```

---

## 🔧 构建与启动

**环境：JDK 25**。在 `Luminol-ver-1.21.8` 目录：

```bash
./gradlew applyAllPatches
./gradlew :luminol-server:jar :luminol-server:createBundlerJar :luminol-server:createPaperclipJar \
          --no-daemon --no-configuration-cache
```

启动（推荐 paperclip）：

```bash
java -jar NekoCore-paperclip-1.21.8-R0.1-SNAPSHOT.jar --nogui
```

首启自动生成 `config/Network.yml`；碰撞与 LagFixer/ESU 配置在 `luminol_config/`。

> 📦 已构建好的产物见 **[Releases](https://github.com/dmz7p4xmqh-coder/Luminol-Core/releases)**。

---

## ⚠️ 使用须知

- **追求原版还原度**：AR 的实体挤压表现与原版不完全一致，可将后端设为 `VANILLA`。
- **任何优化异常**：把对应模块 `enabled` 置 `false`（或 `/nekobackend toggle ... off`）即可回退，无需回滚 jar。
- **性能数字**：来自本机无头环境实测，对照组为已优化的 Paper/Folia 碰撞（非裸原版）。真实大型服收益理论更高，但需生产环境验证。

---

## 📝 更新日志

| 版本 | 内容 |
| :--- | :--- |
| **v1.0.8** | 🚦 ESU 生物 velocity 包降频：走路的怪不再每 tick 发速度包，丧尸海/混战第二大带宽源；`/nekobackend toggle entity_velocity_packet` 开关 |
| **v1.0.7** | 🐛 修复插件兼容性：服务端版本号在缺少 folia-api 元数据时退化成 `Unknown-Version`，导致按语义版本解析版本号的插件（如 SkinsRestorer）启动崩溃（`parseInt("")`）。现回退到合法版本号 `1.21.8-R0.1-SNAPSHOT` |
| **v1.0.6** | ⚡ 修复 EntityLimiter 生成闸门的 O(N²)：原本每生成一个实体都全 region 扫一遍（实体爆发时限制器自己成卡顿源），改为 per-chunk/per-tick 计数缓存，爆发场景 O(N²)→O(N) |
| **v1.0.5** | 👁️ EntityCull 视锥/距离剔除：视野外远处实体不发包给客户端，`/nekobackend toggle entity_cull on` 游戏内开关 |
| **v1.0.4** | 🔥 内置 spark profiler 原生集成（Folia 安全），`/spark` 开服即用；修复启动日志在 Windows GBK 控制台的乱码 |
| **v1.0.3** | 🧟 MobAiThrottle：远离玩家的怪物 AI 降频（惊变100天 / 刷怪海专治） |
| **v1.0.2** | EntityLimiter 溢出清扫削峰 + `/nekobackend toggle` 模块热开关 |
| **v1.0.1** | 出站带宽实时监控（当前 / 峰值 / 累计 Mbps） |
| **v1.0.0** | 首版：AR 碰撞加速 + Kitin 网络优化 + LagFixer/ESU 整合 |

---

## 🙏 致谢上游

Neko Core 站在巨人的肩膀上，向以下项目致敬：

- [**Luminol**](https://github.com/LuminolMC/Luminol) — 本项目的基底（Folia 分支 + 可配置原版特性 + API）
- [**Folia** / **Paper**](https://github.com/PaperMC/Folia) — 区域化多线程服务端核心
- [**AcceleratedRecoiling**](https://github.com/) — 碰撞加速架构灵感
- [**Kitin**](https://github.com/SucIXR/Kitin) — 网络优化体系
- **LagFixer** / **ESU** — 实体限制与发包优化

各上游许可（GPL/LGPL）均予以尊重，相关署名保留在对应源码中。

<details>
<summary>📎 Luminol API 接入（点击展开）</summary>

```kotlin
repositories {
    maven { url = "https://repo.menthamc.org/repository/maven-public/" }
}
dependencies {
    compileOnly("me.earthme.luminol:luminol-api:$VERSION")
}
```

</details>

---

<div align="center">

**🐱 Neko Core** · 让你的服务器跑得像猫一样轻

*Built with [Claude Code](https://claude.com/claude-code)*

</div>