[前置] paraFrame 1.0.0 —— 并行/异步运行时库

GerBeria

[前置] paraFrame 1.0.0 —— 并行/异步运行时库

附件：paraFrame-1.0.0.zip（前置库 mod 本体 + 完整可重建源码 + API 文档） 体积 2,051,051 字节 (1.96 MiB)｜SHA-256 aff348f645bb4f9a655a262340291a53a81531c932717b00c27f4d99ab195279

这是什么

一个前置库：三层纯 Java 的并行/异步运行时，给 mod 作者用。

• 给玩家：和 MagicLib / LazyLib 一样，装进 mods/ 就行。单独装它不会有任何效果——
  

它是库，不含任何游戏内容；只有当你装的某个 mod 要求"需要 paraFrame"时，它才有存在的意义。

• 给 mod 作者：把 jars/ 里的 jar 加进项目依赖即可使用。
  

三层零游戏依赖——不 import 任何 com.fs.* 类。所以它不感知游戏版本， 游戏更新也不会让它失效。这一条不是口头承诺：构建脚本会在编译后扫描每个 class， 一旦出现游戏类引用就直接构建失败。

---

三层怎么选

• runtime｜parallel-runtime.jar｜CPU 拓扑发现、线程放置（EcoQoS / uclamp）、通用线程池（P/E 双角色、加权分片、背压、进度回调、任务组）｜无
• async｜parallel-async.jar｜CompletableFuture 友好 API：异步组合、挂钟调度、有界 IO 卸载、线程归约｜无
• core｜parallel-core.jar｜帧语义层：门面、帧屏障、帧适配器、帧缓存、遥测｜有
  

依赖单向：core → async → runtime。

「帧」是抽象概念——游戏主循环、渲染循环、批处理分片都算。没有帧概念的宿主 （启动器、命令行工具、后台服务）只用 runtime + async 即可。

---

安装（玩家）

• 解压 paraFrame-1.0.0.zip；
• 把其中的 paraFrame/ 文件夹整个放进游戏目录的 mods/ 下：
  

`` starsector/ └── mods/ └── paraFrame/ ├── mod_info.json └── jars/ ``

• 启动器里勾选 paraFrame；
• 正常启动。
  

不需要 install.bat、不需要改 vmparams。文件夹名不要改。卸载直接删文件夹。

同目录下还有一个 paraFrame-1.0.0-source/，那是给需要重建/审查源码的人用的， 不用放进 mods/。

---

给 mod 作者

把 paraFrame/jars/ 里需要的 jar 加进你的项目依赖，按需选层（见上表）。 jna-5.14.0.jar 编译期需要、运行期可选。

paraFrame/docs/ 里有三份文档：

• API使用指南.md —— 详尽教程，含心智模型、逐层 API、反模式和诊断，建议先看这个
• API手册.md —— 速查表
• 迁移指南.md —— 从 MT 系列迁移过来的人看
  

在线版（API使用指南）： https://docs.qq.com/aio/DUk91d1JXWm9vT1dx

---

它会不会拖慢游戏

不会。三点说明：

• 没有 modPlugin，paraFrame 在启动时不执行任何代码——它的 jar 只是躺在
  

classpath 上等别人引用；

• 线程池是用到才建的，而且由调用方（使用它的 mod）负责生命周期；
• jna-5.14.0.jar 是唯一会做原生调用的部分，且**只在探测 CPU 拓扑和设置线程优先级时
  

用一次**，不常驻、不轮询。

如果你想彻底排除它，直接从 mods/ 删掉即可——不会有残留、不影响存档。

---

mod 作者容易踩的三个坑

1. worker 线程里不能碰游戏状态。 游戏对象几乎都不是线程安全的。worker 里算完的 东西要回主线程落地：core 用 onMainThread(...)（endFrame() 时 flush）， async 用 thenDispatch(...)。

2. 不要用 CPU 池跑阻塞 IO。 CPU 池线程数按核数固定，被 IO 堵住就废了。 用 async.io().supply(...)，那是独立的池。

3. 批量提交不要用单发循环。 单发循环每一项各占一个等待位，几千项就可能被判饱和。 批量走 mapAsync / submitStages——整批只占 1 个位置。

---

兼容性（如实写）

• 字节码目标：Java 8（major=52）。游戏自带 JRE 17 可用；非游戏程序 Java 8+ 均可用
• 游戏版本：不感知。mod_info.json 声明 0.98a-RC8，只是因为这是实测环境；代码不引用任何游戏类，老版本玩家可自行改这个字段
• 操作系统：Windows（EcoQoS）/ Linux（uclamp）/ macOS（降级 no-op）/ 其他（JVM 兜底）
  

• CPU 架构：全大核 / Intel 大小核 / AMD 多 CCD 均可用；非异构自动退化为单池
• 其他前置：与 MagicLib / GraphicsLib / LazyLib / LunaLib 无交集、无冲突
• MixinLib：不依赖。但如果你在 mixin mod 里用它，注意你的 mixin 类本身仍需 ≤ JAVA_16
  

---

依赖与许可

• paraFrame 自身：MIT
• JNA 5.14.0：Apache-2.0（双许可，本项目选 Apache-2.0），见包内 THIRD-PARTY-NOTICES/
• 其他运行时依赖：无。不联网、不加载未列出的原生库
• 游戏本体：不依赖、不包含
  

完整源码就在压缩包内（paraFrame-1.0.0-source/），配一个 JDK 8+ 即可重建。 自证：同 JDK 下重建出的三个 jar 与包内 jar 逐字节相同；两次打包的 zip SHA-256 也相同。

本项目为独立 clean-room 实现，未包含、未复制社区上游多线程优化项目（MT 系列， 作者 StarCore）的任何源代码，仅吸收其方法论与热点地图，并在此致谢。详见包内 NOTICE。

署名：GerBetria。这是第三方作品，不是任何上游项目或其作者的官方发布。

---

反馈

问题请发到本帖，附上：

• 使用它的 mod 名称与版本（如果是某个 mod 报错）
• 你的 JDK 版本（java -version）
• CPU 型号
• 完整报错栈或最小复现
  

纯库的问题往往出在"调用时机"上，所以调用栈比现象描述有用得多。

---

更新日志（1.0.0）

首个独立发行版。内容等价于 StarsectorParallel 0.1.0 中的三层库，本次不引入新功能， 只做"变成一个能独立安装的前置库"所需的一切：

• mod 本体形态：mod_info.json + jars/，可直接放进 mods/
• 独立构建链（只依赖 javac + jar + JNA，不需要游戏 SDK / MixinLib / Gradle）
• 位级可复现构建
• 独立版本线（1.0.0 起，与 mod 本体 0.1.0 脱钩）
• 完整 API 文档随包
  

三层能力快照见包内 CHANGELOG.md。

---