[前置] paraFrame 1.0.0 —— 并行/异步运行时库
本帖最后由 GerBeria 于 2026-11-1 18:03 编辑[前置] paraFrame 1.0.0 —— 并行/异步运行时库
附件：paraFrame-1.0.0.zip（前置库 mod 本体 + 完整可重建源码 + API 文档） 体积 2,051,051 字节 (1.96 MiB)｜SHA-256 aff348f645bb4f9a655a262340291a53a81531c932717b00c27f4d99ab195279
这是什么
一个前置库：三层纯 Java 的并行/异步运行时。
三层零游戏依赖——不感知游戏版本， 游戏更新也不会让它失效。
API使用指南： https://docs.qq.com/aio/DUk91d1JXWm9vT1dx
三层怎么选
[*]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/ 下
[*]启动器里勾选 paraFrame；
[*]正常启动。
同目录下还有一个 paraFrame-1.0.0-source/，那是给需要重建/审查源码的人用的， 不用放进 mods/。
给 mod 作者
paraFrame/docs/ 里有三份文档：
[*]API使用指南.md —— 详尽教程，含心智模型、逐层 API、反模式和诊断，
[*]API手册.md —— 速查表
[*]迁移指南.md —— 从 MT 系列迁移过来的人看
在线版（API使用指南）： https://docs.qq.com/aio/DUk91d1JXWm9vT1dx
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+ 即可重建。
本项目为独立 clean-room 实现，未包含、未复制社区上游多线程优化项目（MT 系列， 作者 一名刀客塔 ）的任何源代码，仅吸收其方法论与热点地图，并在此致谢。详见包内 NOTICE。
署名：GerBeria。这是第三方作品，不是任何上游项目或其作者的官方发布。
反馈
问题请发到本帖，附上：
[*]使用它的 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。
GerBeria 发表于 2026-11-1 18:08
这是我项目拆分的产物之一，AI写的，能用 也只是能用。
什么项目，这个拆分了之后什么功能，所答非所闻啊{:5_124:} 离情笃生 发表于 2026-11-1 16:20
我是玩家，有小白能看懂的解释吗
这是我项目拆分的产物之一，AI写的，能用 也只是能用。 我是玩家，有小白能看懂的解释吗
{:tieba_36:}ai技术大爆发，太多狠活了 看不懂，顶一下
页:
[1]