# Neko Core 改动与使用说明

本文档基于当前工作区变更状态整理，目标是说明：

- 这个服务端改了什么
- 如何构建与使用
- 做了哪些优化
- 当前已知限制与建议

---

## 1. 项目定位与结果

当前分支是在 `Luminol 1.21.8` 基础上，完成了 `Neko Core` 定制化改造，已实现：

- 构建链路可用（`applyAllPatches` 可通过）
- `luminol-server` 可编译
- 可产出并启动可运行包（`paperclip/bundler`）
- 新增后端切换命令，可在游戏内切换碰撞加速后端（含 `FFM`）

---

## 2. 本次主要改动（按模块）

## 2.1 构建与打包链路

涉及文件：

- `build.gradle.kts`
- `luminol-server/build.gradle.kts`
- `luminol-server/build.gradle.kts.patch`

主要改动：

- 锁定/适配 `hyacinthusweight` 构建链路，保证 patch + mache 流程可运行。
- 修复 `macheRemapJar` 参数链路（显式 remapper、mappings、params 的可用输入）。
- 修复打包任务名与类型适配：
  - 使用 `createBundlerJar` / `createPaperclipJar`（替代旧命名）。
- 统一到 Java 25 构建运行方案，确保插件与打包任务兼容。

---

## 2.2 补丁与上游对齐

涉及目录：

- `luminol-api/paper-patches/features/*.patch`
- `luminol-server/paper-patches/features/*.patch`
- `folia-api`（工作区变更）
- `folia-server`（工作区变更）

主要改动：

- 对漂移的 feature patch 做了重建与兼容修复，恢复补丁应用链路。
- 修复了因补丁上下文漂移导致的 `apply...FeaturePatches` 失败问题。
- 保留了当前能通过构建的 patch 状态。

---

## 2.3 品牌与命令

涉及文件：

- `luminol-server/src/main/java/me/earthme/luminol/config/modules/misc/ServerModNameConfig.java`
- `luminol-server/src/main/java/me/earthme/luminol/commands/CommandRegister.java`
- `luminol-server/src/main/java/me/earthme/luminol/commands/backend/NekoBackendCommand.java`（新增目录/文件）

主要改动：

- 默认服务端名改为 `Neko Core`。
- 注册并启用 `/nekobackend` 命令。

`/nekobackend` 子命令：

- `status`：查看当前生效后端和关键配置
- `set <AUTO|GPU|FFM|JAVA|VANILLA>`：运行时切换后端
- `reload`：重载后端选择器

---

## 2.4 配置系统重构（优化模块）

涉及文件：

- `luminol-server/src/main/java/me/earthme/luminol/config/modules/optimizations/AcceleratedCollisionConfig.java`
- `AfkEntityTrackingConfig.java`
- `EntityLimiterConfig.java`
- `ExplosionOptimizerConfig.java`
- `MobAiReducerConfig.java`
- `SkipZeroDeltaPacketsConfig.java`
- `VehicleMotionConfig.java`

主要改动：

- 统一到 Luminol 现行配置风格（`IConfigModule` + 注解字段）。
- 修复历史“伪 API”配置写法导致的编译与运行不一致问题。

---

## 2.5 优化逻辑实现与兼容修复

涉及文件：

- `collision/*`（`CollisionBackendSelector`、`RegionCollisionHandler`、`backend/*`）
- `afktracking/AfkTrackingManager.java`
- `entitylimiter/LuminolEntityLimiter.java`
- `mobaireducer/*`（`MobAiReducerHandler`、`OptimizedBreedGoal`、`OptimizedTemptGoal`）
- `explosion/LuminolExplosionOptimizer.java`
- `org/leavesmc/.../LeavesPluginMeta.java`
- `src/minecraft/java/...` 与 `src/minecraft/resources`

主要改动：

- 恢复并对齐 `FFM/GPU/JAVA/VANILLA` 后端选择逻辑。
- 修复若干上游 API 变化导致的编译点（实体、世界、门户位置转换、插件元数据等）。
- 调整部分优化逻辑为当前上游可编译/可运行版本。

---

## 3. 优化了什么（功能视角）

## 3.1 碰撞加速（AR / Accelerated Recoiling 体系）

- 支持多后端：
  - `FFM`（Foreign Function & Memory）
  - `GPU`
  - `JAVA`
  - `VANILLA`（回退）
  - `AUTO`（自动选择）
- 可通过游戏内命令热切换后端（`/nekobackend set ...`）。

## 3.2 AFK 追踪优化

- 保留 AFK 追踪入口与配置化能力。
- 对不兼容的底层字段访问做了兼容处理，避免构建失败。

## 3.3 实体限制与 AI 优化

- 实体上限限制器、溢出清理、AI 目标逻辑等可配置能力保留。
- 对上游访问权限/签名变化做了兼容调整。

## 3.4 爆炸与网络细节优化

- 包含爆炸优化、零位移包处理、载具运动相关优化配置入口。

---

## 4. 使用方法

## 4.1 构建

建议环境：

- JDK: Java 25（当前链路已按此验证）
- OS: Windows（已验证）

在仓库根目录执行：

```bash
./gradlew applyAllPatches
./gradlew :luminol-server:createPaperclipJar
```

产物路径：

- `luminol-server/build/libs/luminol-paperclip-1.21.8-R0.1-SNAPSHOT.jar`
- `luminol-server/build/libs/luminol-bundler-1.21.8-R0.1-SNAPSHOT.jar`
- `luminol-server/build/libs/luminol-server-1.21.8-R0.1-SNAPSHOT.jar`

## 4.2 启动

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

首次启动需同意 EULA：

- 编辑 `eula.txt` 为 `eula=true`

## 4.3 游戏内后端控制（AR）

```text
/nekobackend status
/nekobackend set FFM
/nekobackend set GPU
/nekobackend set JAVA
/nekobackend set VANILLA
/nekobackend set AUTO
/nekobackend reload
```

说明：

- `set` 会立即切换并更新运行态配置字段。
- 如果某后端初始化失败，会自动回退（可用 `status` 确认当前实际后端）。

---

## 5. 关键配置项（示例）

路径：`luminol_config` 下对应优化配置（按模块名）。

重点建议关注：

- `accelerated_collision.enabled`
- `accelerated_collision.backend`（`AUTO/GPU/FFM/JAVA/VANILLA`）
- `accelerated_collision.max_collision`
- `accelerated_collision.grid_size`
- `accelerated_collision.density_threshold`
- `accelerated_collision.max_threads`

---

## 6. 已知注意事项

- 本次改造包含大量上游漂移兼容修复，后续升级 Minecraft/Folia 版本时，建议优先重跑 patch 重建流程再改业务逻辑。
- `FFM` 后端依赖 native 库资源加载，若切到 `FFM` 失败，请先检查平台库文件是否打入最终 jar 的 `natives/<platform>/` 目录。
- 若打包时报 `paperclip` 产物文件占用，先关闭仍在运行的服务端 Java 进程再重试。

---

## 7. 快速验收清单

- 能执行 `:luminol-server:createPaperclipJar`
- `paperclip` 可启动并通过 EULA 后进入 `Done (...)`
- 进服后 `/nekobackend status` 可返回当前状态
- `/nekobackend set FFM` 可执行并反馈切换结果

---

如需，我可以在下一步补一版「面向运维发布」的精简版文档（只保留部署、参数、回滚、排障）。