bbhost路线图与贡献指南：全原生渲染的未来规划与社区开发入门

bbhost是一个让《Bloodborne》（血源诅咒）在 Windows 和 Linux 上原生运行的开源项目：游戏 1.09 版可执行文件不加修改地跑在 PC 的 x86-64 CPU 上，bbhost 重写 PS4 系统库、把 GCN 着色器反编译为 Vulkan 可用的代码，目标是做一个"完整 PC 版"。本文将从项目路线图（全原生渲染的未来规划）和社区贡献指南（如何构建、测试、提交代码）两个角度，带你快速了解这个项目的现状与参与方式。

🎮 先搞懂 bbhost：翻译层，而非模拟器

bbhost 的核心思路很特别：PS4 本身是 x86-64 架构，所以游戏代码不需要模拟，只需要一个"住的地方"。bbhost 做的事情是：

• CPU 侧原生运行：加载游戏的 ELF 可执行文件，重定位、把导入函数绑定到自己的实现上，直接满速执行；
• 重写系统库：文件、线程、音频、视频、网络、PlayStation Network 调用——游戏导入的全部 660 个具名函数都实现了；
• 图形层逐步原生化：挂钩 FromSoftware 自己的图形层 GX，直接从引擎对象构建绘制调用，并把 GCN 着色器反编译（"lift"）成带类型的结构化 SPIR-V，打印为 HLSL 交给玩家的显卡编译。

游戏本体不包含在项目内，玩家需要自备 1.09 更新版的游戏文件与解密后的 eboot（详见 docs/running.md）。

🗺️ 路线图：通往全原生渲染的四个方向

现状速览：哪些已经原生，哪些还在模拟

项目在 README.md 的 Status 一栏持续更新进展，截至目前的格局是：

未来规划：README 中明确列出的 Roadmap

1. 图形全面原生化：把游戏等待的完成信号改由宿主自己的提交时间线提供，让 PM4 命令处理器只负责"排顺序"；同时把游戏内存从 GPU 上搬下来——拷贝走 staging、GPU 写入的缓冲区改由宿主持有，不再需要整体导入约 4 GB 显存；
2. 反编译扩展：把更多引擎函数重写为 C++ 源码，优先选择 Mod 和修复最需要的系统（当前已有 200 个函数完成重写，见 docs/decomp.md）；
3. 性能：在中端硬件上实现稳定 60 fps，并留有更高帧率的余量；
4. PC 功能：更多设置项、每个界面都更完善的键鼠操作，以及更多被还原的删减内容。

渲染侧的更详细设计（命令处理器、标签线程、着色器双编译器等）都写在 docs/rendering.md，它是理解路线图的最佳入口。

🚀 社区开发入门：从克隆到第一次提交

三条基本规则

CONTRIBUTING.md 开宗明义，新手请务必记住：

1. 仓库里不放游戏文件——没有 eboot、没有游戏转储、没有资源，每个人自带自己的 1.09 文件；
2. 写你自己的代码——其他项目只能当"事实参考"（枚举值、错误码、寄存器布局），不能直接粘贴代码；
3. 不提交密钥——token、密码、bbhost-options.toml（内含账户 token）都不能进提交。

快速搭建开发环境（三步走）

第一步，克隆仓库：

git clone https://gitcode.com/gh_mirrors/bb/bbhost

第二步，用 CMake 构建（Linux 原生构建；Windows 可执行文件从 Linux 交叉编译）：

cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build -j

第三步，生成并填写自己的配置，让读取游戏文件的测试能够真正运行：

./build/bbhost --write-config bbhost.toml # 设置 app0 与 eboot 路径 export BBHOST_APP0=/path/to/CUSA00900

依赖清单、Windows 交叉编译（tools/win_deps.sh）、打包脚本等完整说明都在 docs/building.md；配置项可以对照 bbhost.example.toml。首次运行会弹出 setup 窗口，帮你查找并校验游戏文件：

代码去哪儿：目录结构速查表

提交代码前先看它该放在哪（完整版见 README.md 的 Project layout 一节）：

测试文化：每个变更都要"带证据"

这是 bbhost 社区最有特色的部分：

• CI 无 GPU、无游戏文件，所以游戏内的效果证据要由你自己提供——前后对比截图、build/smoke启动到标题画面检查日志、BBHOST_VK_VALIDATE=1下无新增验证错误；
• 重写函数必须双通道校验：没有游戏时，用 tests/decomp/eboot_kit.h 把原始机器代码和重写版并排跑，逐位比对；游戏运行时，用 compare 模式实时对照原版；
• 渲染改动按 F12 帧转储 + tools/f12_check.py 检查，或 tools/menu_drive.sh 无头驱动游戏截图；
• 性能改动要求固定 NUMA 节点（numactl --cpunodebind=0 --membind=0）、交替配置至少两轮对比，并把数字、显卡型号与方法写进 PR。

🧩 新手友好的贡献切入点

如果你还不确定从哪入手，按门槛从低到高排个序：

1. 字节补丁（零代码）：往 patches/ 加一个.toml数据补丁（如 FOV、动态光影开关），补丁清单会自动校验 eboot 的 SHA-256；
2. 插件（轻量代码）：参考 plugins/hello/hello.c 最小示例和 docs/plugins.md，写一个计数帧、改参数的插件；官方已内置 randomizer、boss rush、debug menu 等可学习；
3. 重写引擎函数（硬核）：按 docs/decomp.md 的"Adding one"六步流程操作，从它的 "Next" 清单里挑一个待办（如道具入背包的EquipGameData::AddItem）；
4. 文档与工具：完善 docs/ 或补充 tools/ 下的脚本。

📦 发布流程：了解你提交的代码如何到达玩家

发布是master上的一个带注释的 tag：先用 Markdown 写好面向玩家的 release notes，然后运行 tools/tag_release.sh：

tools/tag_release.sh v0.2.17 notes.md git push <remote> v0.2.17

Release 工作流会构建并签名 Windows / Linux / Steam Deck 包，附带 DXC 着色器编译器与全游戏 pipeline 清单（首启预编译，减少卡顿）。细节见 docs/building.md 的 Packages 一节。

✨ 总结

• bbhost 的路线图很清晰：图形全原生（命令处理器退役、显存去整体导入）、反编译扩展到 Mod 最需要的系统、中端机稳定 60 fps、更多 PC 特性；
• 参与门槛有阶梯：补丁 → 插件 → 反编译重写，任意一层都能贡献；
• 社区文化关键词：自己的代码、双通道校验、PR 必带证据、master永远可构建；
• 建议先读 docs/running.md 跑起来游戏，再对照 docs/rendering.md 与 docs/decomp.md 找一块自己感兴趣的地盘动手。