232 lines
6.4 KiB
Markdown
232 lines
6.4 KiB
Markdown
# 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` 可执行并反馈切换结果
|
||
|
||
---
|
||
|
||
如需，我可以在下一步补一版「面向运维发布」的精简版文档（只保留部署、参数、回滚、排障）。
|