# [MOD] StarsectorParallel 0.1.0 —— 远行星号逻辑侧多线程并行化
> 发布物：`_Release/v0.1.0/archive/StarsectorParallel-0.1.0.zip`
> 作者：GerBetria 许可：MIT（自身代码）
---
## 一句话
把远行星号**逻辑侧**可并行的引擎热点（战斗 AI 推进、市场经济推进、舰队任务分配等）
路由到异构感知线程池，并按 CPU 拓扑自动分派到性能核 / 能效核。
**只管逻辑，不动渲染、物理、存档序列化、传感。**
---
## ⚠️ 首先：它依赖 MixinLib
**StarsectorParallel 是 MixinLib 的 mixin mod，不是独立 agent。
必须先安装 MixinLib 并完成其 `-javaagent` 注入，否则本 mod 不会被加载。**
- 推荐直接用 **MixinFR**（MixinLib + Fast Rendering 整合包），装好后本 mod 开箱可用；
- 也可单独装 MixinLib；
- **两份 MixinLib 不能同时启用**（即装了 MixinFR 就不要再单独装 MixinLib）。
mod 列表里请把 **StarsectorParallel 排在 MixinLib（或 MixinFR）之后**。
---
## 安装
1. 解压 `StarsectorParallel-0.1.0.zip`；
2. 把其中的 `StarsectorParallel/` 文件夹整个放进游戏目录的 `mods/` 下；
```
starsector/
└── mods/
├── MixinFR/ ← 先装好这个
└── StarsectorParallel/ ← 本 mod
```
3. 启动器里勾选 **StarsectorParallel**（排在 MixinLib 之后）；
4. 正常启动。
**不需要** install.bat、**不需要**改 vmparams（agent 槽由 MixinLib 独占）。
文件夹名不要改。卸载直接删文件夹。
---
## 请先看这段：收益预期管理（重要）
本 mod 优化的是 **CPU 侧的逻辑热点**。它**不改变游戏单线程模拟的帧率上限**，
也**不优化渲染、显存或磁盘 IO**。
我们自己的 JFR 实测（95 个 mod 的重载环境）显示：并行池在整段启动与运行中的
CPU 占用仅约 **1.7%**——也就是说在**大量场景下你可能感觉不到变化**。
什么样的环境才可能受益：
- CPU 侧真的有热点（大规模战斗、市场经济推进繁重、大量舰队 AI）；
- 你的瓶颈**不是** GPU / 显存 / 磁盘 IO；
- 多 mod、大内存堆环境（并行空间更大）。
**如果你的瓶颈在 GPU 或 IO，装它可能毫无体感，甚至因为线程调度而略微变差。**
这是诚实的预期说明——先装了试试，没效果就卸载，不需要客气。
---
## 运行时开关
在 `vmparams` 加 `-D` 参数，改完重启游戏。**全部默认开启。**
| 参数 | 作用 |
|---|---|
| `-Dsparallel.master=false` | **总开关**：完全退回原版行为（排查问题先用它） |
| `-Dsparallel.heterogeneous=false` | 关异构分池（强制同构单池） |
| `-Dsparallel.placement=false` | 关线程放置（不做 P/E 核偏置） |
| `-Dsparallel.c1=false` | 关 C1：战斗 AI 批量并行 |
| `-Dsparallel.c3=false` | 关 C3-sub/E1：市场推进并行 |
| `-Dsparallel.g3=false` | 关 G3：舰队任务分配 |
| `-Dsparallel.e5=false` / `-Dsparallel.e7=false` | 关 E5 / E7 缓存复用 |
排查顺序：先 `master=false` 确认是不是本 mod 引起的，再逐项关到具体子系统。
---
## 兼容矩阵（如实写）
| 维度 | 声明 |
|---|---|
| 游戏版本 | **0.98a-RC8**；游戏更新后混淆映射变化会导致本 mod 失效（属预期） |
| 汉化版本 | 传统汉化版（ZYT）与启动优化版（YHCS）**均已实测**；英文原版按同一套字节码锚点推断兼容，欢迎反馈 |
| Java | 无需单独安装，用游戏自带 JRE 17 |
| 其他 Mixin mod | 可用；冲突只在 `mixinlib.log` 报 WARN，不阻断 |
| MTPerf | 共存时其引擎字节码补丁在 MixinLib 双 JVM 下静默跳过；其脚本级功能不受影响 |
| GraphicsLib | Intel 核显上 `Bloom is not supported; disabling` 与本 mod 无关 |
| 大规模战斗 | **不改变单线程模拟的帧率上限** |
---
## 已知问题
- 收益因环境差异极大（见上面"收益预期管理"）。
- **第三方 mod 默认不并行**：未注册为线程安全的 mod 逻辑一律回主线程串行执行。
这是保守设计，保证不会因为并发而损坏存档，不是 bug。
- 汉化包若改动了目标类，对应注入点会**优雅跳过**（退回原版路径，不崩溃）。
- 游戏版本更新后可能整体失效（混淆映射变化）。
---
## 报告问题请附三件套
1. `starsector-core/mixinlib.log`
2. `starsector-core/starsector.log`
3. `vmparams`
外加：游戏版本、汉化版本、启用 mod 列表、CPU 型号、以及**你的瓶颈大概在哪**
（任务管理器看 CPU 还是 GPU 先满）。
---
## 源码与许可
- **完整源码就在压缩包内**：`StarsectorParallel-0.1.0-source/` 目录。
构建方法见其中的 `BUILD.md`。这是本发布方式与常见 mod 最大的不同，主动说明以省疑问。
（MIT 许可不强制提供源码，这是自愿的。）
- 自身代码：**MIT**。
- 第三方：JNA 5.14.0（Apache-2.0 或 LGPL-2.1，本项目选用 Apache-2.0），
见包内 `THIRD-PARTY-NOTICES/`。
- 运行时依赖 **MixinLib（GPL-3.0-only）** —— 本包**不含** MixinLib 任何文件，
请从 MixinLib 项目获取。
- **本项目为独立 clean-room 实现**，未包含、未复制社区上游多线程优化项目
（MT 系列，作者 StarCore）的任何源代码；仅吸收其方法论与热点地图，
并在此致谢。详见包内 `NOTICE`。
**署名**：GerBetria。这是第三方作品，**不是** MixinLib / Fast Rendering 作者的官方发布。
---
## 更新日志摘要（0.1.0）
首个对外版本。四子项目架构（依赖单向 injector → core → async → runtime）：
- **parallel-runtime**：跨平台多线程运行时（无帧语义，可独立分发）——拓扑发现、
线程放置、通用工作池。
- **parallel-async**：通用异步组合层（无帧语义，可独立分发）——`Async` 门面、
挂钟调度、有界 IO 卸载、线程归约。
- **parallel-core**：帧语义层——门面、帧屏障、帧调度、缓存、遥测。
- **starsector-injector**：远行星号逻辑注入 mod（MixinLib 形态）。
已接线的热点：C1 战斗 AI 批量并行、C3-sub/E1 市场推进并行、G3 舰队任务分配、
E5/E6/E7 缓存与字符串复用。全维度同构无损降级（关闭 = 等价原版）。
详见包内 `CHANGELOG.md`。
| 
发表于