[MD]
# PRTS 服务端整合发布说明（1.20.1 / 1.21.1 / 1.21.1 多线程版）
> 一个服务端，三个分支：稳定版按游戏版本选，多线程版单独评估。
> 开源项目，GPL-3.0 协议。
---
## 一、这是什么
PRTS 是一个面向高负载模组服的混合服务端，核心特点是：
- **模组 + 插件同服**：Forge / NeoForge 模组和 Bukkit / Spigot 插件可以同时运行。
- **项目血统**：Arclight（混合端）→ Luminara → PRTS（由 ElainAwa 维护）。
- **无感优化**：不改游戏玩法，只降低同样逻辑的服务器资源消耗，并修复大量模组服生产环境中的崩溃。
> 所有版本的 jar 请到 GitHub Releases 页面手动选择下载，后续版本更新以 Releases 页为准：
> https://github.com/ElainAwa/PRTS-SERVER/releases
---
## 二、稳定版：1.20.1 + 1.21.1
两个稳定分支功能几乎一致，主要区别只是游戏版本和加载器，按你的整合包版本选即可。
| 分支 | 游戏版本 / 加载器 | 当前版本 |
|---|---|---|
| PRTS-1.20.1 | 1.20.1 / Forge 47.4.16 | v1.0.66 |
| PRTS-1.21.1 | 1.21.1 / NeoForge 21.1.248 | v1.0.29 |
### 共同特性
- Forge / NeoForge 模组 + Bukkit 插件同服：两边生态可以一起用。
- ServerCore 全套移植：激活范围、繁殖上限、刷怪控制、动态配置、指令与统计。
- routeB 空间化实体追踪（AreaMap）：替代原版全量实体广播，玩家附近实体追踪更省 CPU。
- 区块票据延迟传播（ticketpropagator）：优化区块加载票据扩散，降低传送 / 跑图尖峰。
- 零速度跳过 / 异步日志：低感知优化。
- NearbyPlayerIndex 空间玩家索引：玩家查找更省。
- ClientModGuard：客户端模组预检 + 启动崩溃自愈，减少“坏客户端模组炸服”。
- 大量模组兼容崩溃修复：长期在 250+ 模组科技整合包上实际运行和修复。
> 1.21.1 分支在此基础上还有动力铁轨优化、主线程卡顿看门狗 / 线程耗时统计、可选开启的可靠区块保存（WAL journal）。
---
## 三、多线程版：1.21.1-Multithreading
- 单独一条技术路线：在 1.21.1 稳定版基础上，把原来单线程的世界 tick 拆到多个工作线程，定位是多线程工程验证版，目前仍有许多bug。
- 主线程只做调度与同步：维度 worker、区域 worker 与独立子任务池承担重负载计算，玩家与世界权威写入保持主线程。所有并行子系统都有兜底路径，环境过载或不兼容时按序降级，而不是卡死或损坏存档。
## 并行引擎
将单线程世界 tick 拆分为多线程执行，以下功能全部默认开启：
- **异步寻路** (`pathfinding-async`)：怪物/村民寻路在工作线程计算，并复用有效导航路径
- **维度并行** (`dimension-parallel`)：主世界/下界/末地在独立 worker 线程 tick
- **区域并行** (`region-parallel`)：实体按区块条带划分为多个区域并行 tick
- 区域数 2/4/8/16（`region-count`，默认 4）
- 按负载自动增减区域（`region-auto-scale`）
- 不等宽条带：繁忙区域向相邻区域让渡边界组（`uneven-stripes`）
- **实体批并行** (`entity-batch-parallel`)：区域内的实体阶段再扇出到子任务池，村民等持久化生物离开主线程 tick
- **区块环境并行** (`chunk-env-parallel`)：随机刻/流体刻扇出到子任务池，并用 3×3 区块锁（`chunk-env-lock`）保证相邻区块不会并发写入
- **方块实体分档调度** (`be-parallel-allow` / `be-main-thread-force`)：Create 方块实体默认在区域 worker 上 tick；已知必须主线程的类型（Create 轨道、红石链、移动储存接口、注液器、Lootr 箱子）锁定主线程
- **异步传送门** (`portal-async`)：传送进入未生成区块时提交异步加载，而不是卡住 worker
- **无玩家维度多 tick** (`dimension-worker-multitick`，默认 4)：无玩家维度每个 barrier 会话可连 tick 多次，更快消化积压
### ThreadPolicy 自动学习
运行时检测 worker 访问主线程专属 API（`getBlockEntity` / `setBlock` 等）的违规，自动把不安全实体类路由回主线程：
- 滑动窗口统计（默认 2400 tick；窗口内 5 次违规触发路由）
- 路由持久化（`config/prts-learned-routes.json`，启动加载 / 关服保存）
- 双向 Probation：被路由的类定期回 worker 试跑，成功后恢复并行（指数退避）
- 安全阀：worker 异常 → 永久降级主线程
- 默认策略 `thread-policy: stats` 只统计不拦截；`enforce` 仅用于测试服定位
## 区块系统
- **细粒度状态机** (`chunk-system-enabled`)：区块生成按「区块 × 状态」拆成任务，带优先级与依赖门控并行调度，新地形按序到达且多区块同时推进
- **并行 worldgen 调度器** (`chunk-system-scheduler`)：依赖门控的 worldgen 任务图在工作线程执行，FEATURES 前后使用分级锁域
- **需求调度**：每 tick 需求预算（`chunk-demand-per-tick`）、最低排空窗口（`chunk-demand-min-drain-ms`）、按玩家距离分桶优先且带饥饿兜底（`chunk-demand-player-priority`）、区块发送速率下限（`chunk-send-rate-floor`，默认 128 块/tick）
- **方向感知预取** (`chunk-prefetch`)：沿移动方向预铺窗口与走廊、静止时后台预生成（`idle-enabled`）、登录预热（`login-warmup-enabled`）
- **异步区块 IO** (`chunk-async-io-enabled`)：区块反序列化离开主线程
- **生成预算**：每 tick 提交上限（`generation-tasks-per-tick`）、滚动 2 秒窗口（`chunkgen-inflight-limit`）、堆压力卫兵（`generation-memory-guard-*`）在逼近堆上限时降速或暂停生成；`-Xms` 与 `-Xmx` 相同的启动参数同样适用
## Barrier 与故障处理
- Watchdog 感知（`barrier-watchdog-aware`）：并行等待不误触发看门狗强杀
- 软降级（`barrier-soft-degrade`，默认开）：主线程落后时，晚到的区域跳过本轮剩余工作，而不是拖住全服
- 硬超时动作（`barrier-timeout-action`，默认 `degrade`）：真卡死时该维度退回主线程串行并自动恢复（`barrier-timeout-recover-ticks`）；`crash` 则 dump 全线程后停机
- 整服兜底（`on-fault-fallback-vanilla`）：连续硬超时后退回原版串行 tick，重启恢复
## 模组兼容
- **Create**：动力网络拓扑变更加锁串行，无源分裂网络自动愈合，锁链与应力仪表保持正确。装配器、移动储存接口、溜槽、注液器安全路由；长轨道假轨栅格化跨 tick 分摊（`create-track-lazy-spread`）；传送带乘客注册延迟到主线程
- **Minecolonies**：殖民地 NPC 在区域 worker 工作（安全方块实体读取），工作 AI 相位错峰（`colony-npc-phase-stagger`），工作间隔可配置
- **Lithium**：检测到 Lithium 时生成驱动收口主线程，规避其线程检查
- **Sable / Simulated**：绳索物理的 native 入口已串行化，目前只解决跨线程 native 死锁导致的崩溃；物理结构仍存在 bug，属后续修复方向
- **SuperbWarfare**：引擎侧适配——弹道局部查询、IFF 节流、广播裁剪；可选载具休眠（`sbw-vehicle-sleep`）
## 事件桥与主分支优化
与主分支 `1.21.1` 对齐：
- 事件桥按需注册 Bukkit/Forge 转发器，无插件监听时短路跳过（`event-bridge.*`、`event-shortcircuit.*`）
- 实体空间索引、POI 查询预检、碰撞收集批处理、邻居更新熔断（默认开）
- 光照：每 tick 传播预算（`lighting.budget-*`）与独立光照线程（`lighting.threaded`）
- 看门狗、实体清理、AE2LT 节流、可靠区块保存（WAL）
- 容器菜单广播预检（`menu-broadcast`，默认关——先实测归因再开）
- Moonrise 快速调色板读取路径已移植（默认未注册，待验证）
## 配置
`prts-features.yml`（服务端根目录）首次启动自动生成，每个配置项都带一行注释。注释默认中文，把 `locale` 改为 `en_us` 并重启即可切换为英文；旧配置文件缺失的新配置项会自动补齐。
主要开关（生成时的默认值）：
```yaml
locale: zh_cn # 配置注释语言（zh_cn / en_us）
parallel:
pathfinding-async: true # 异步寻路：工作线程计算
dimension-parallel: true # 维度并行：各维度独立 worker tick
region-parallel: true # 区域并行：实体按区块条带并行 tick
region-count: 4 # 区域数（2/4/8/16）
region-auto-scale: true # 按负载自动增减区域数
entity-batch-parallel: true # 实体阶段扇出到子任务池
chunk-env-parallel: true # 随机刻/流体刻进子任务池
portal-async: true # 未生成区块的传送门异步加载
thread-policy: stats # worker 世界访问策略：off/stats/enforce
main-thread-routing: auto # 违规实体类自动路由回主线程
route-threshold: 5 # 触发路由的违规次数
route-window-ticks: 2400 # 违规统计窗口（tick）
chunk-system-enabled: true # 区块×状态细粒度状态机
chunk-send-rate-floor: 128 # 区块发送速率下限（块/tick）
be-parallel-allow: ["create:*"] # 允许在区域 worker tick 的方块实体
barrier-soft-degrade: true # 晚到区域跳过本轮剩余工作
barrier-timeout-action: degrade # 硬超时：降级串行并自动恢复
dimension-worker-multitick: 4 # 无玩家维度每会话 tick 数
chunk-prefetch:
enabled: true # 沿玩家移动方向预取
idle-enabled: true # 静止时后台预生成
generation-tasks-per-tick: 50 # 每 tick 生成提交上限
chunkgen-inflight-limit: 128 # 滚动 2 秒提交窗口
generation-memory-guard-enabled: true # 堆压力高时降速生成
barrier-watchdog-aware: true # 并行等待时不误触发看门狗
barrier-timeout-ms: 120000 # barrier 卡死超时（毫秒）
```
全部设为 `false` 即退回单线程行为，可以当作普通 1.21.1 稳定版使用。
> 多线程分支为工程验证定位：并行引擎默认开启，建议先小范围测试，确认与整合包无冲突后再上生产。
---
## 四、通用运行要求
- Java 21：推荐 Adoptium Temurin 21，低于 21 无法启动。
- 内存建议：中小型整合包 4G 起步，大型整合包 8G–16G。
---
## 五、兼容性说明
- 支持 Forge / NeoForge 模组与 Bukkit / Spigot 插件同服。
- 可与常见优化模组共存（如 ModernFix、FerriteCore、PacketFixer、Spark 等，具体按版本验证）。
- 不建议再安装重复功能的 Bukkit 优化插件，可能互相打架。
- 多线程分支与部分“全局可变图结构”类红石优化模组有兼容回退逻辑；遇到具体模组问题请带日志反馈。
---
## 六、许可与第三方署名
- 本项目整体以 GPL-3.0 开源。
- 借鉴 / 移植的第三方代码（ServerCore、VMP / HariPlayer、Mohist、Youer、Paper 等）均保留原作者版权与许可声明，集中登记见 [THIRD-PARTY.md](https://github.com/ElainAwa/PRTS-SERVER/blob/1.20.1/THIRD-PARTY.md)。
- 完整许可证：仓库根目录 `LICENSE`。
[/MD]
