如何给benilla贡献代码:Rust魔兽世界客户端开发者上手指南
如何给benilla贡献代码:Rust魔兽世界客户端开发者上手指南
benilla 是一个用 Rust 和 Bevy 从零打造的完整魔兽世界 1.12.1 客户端:MPQ/BLP/DBC 等资源格式读取、SRP6 网络协议、FrameXML 与 Lua 界面引擎全部纯 Rust 实现。无论你是想修一个 bug、补齐一个缺失的协议包,还是基于它开发自己的功能扩展,这篇 benilla 贡献指南都能带你完成从环境搭建到首个 PR 被合并的完整流程。
先懂核心原则:1.12.1 就是唯一规范 📏
写代码之前,先理解 benilla 的取舍——这决定了哪些 PR 会被合入:
| ✅ 会被接受 | ❌ 不会被接受 |
|---|---|
| bug 修复(附改动前后的对比说明) | 1.12.1 没有的功能(哪怕是客户端模组会加的) |
| 向 1.12.1 靠拢的补齐:缺失的包、动词、窗口、效果 | 来自游戏安装的任何内容(美术、模型、声音、数据) |
| benilla 与原版不一致的修正(须给出参考事实) | 大而杂的改动(一个 PR 只做一件事) |
一句话概括:benilla 是"大家共同的地基",不是发挥创意的地方——只有让 benilla 更像 1.12.1、或修复 bug 的改动才会被接受。详见 docs/CONTRIBUTING.md。
环境搭建:三步装好开发工具 🛠️
一键克隆仓库
git clone https://gitcode.com/gh_mirrors/be/benilla
安装 Rust 工具链
rust-toolchain.toml 把工具链锁定在 1.98.1,并自动附带 clippy 与 rustfmt 组件(rustup 会按它自动安装)。此外还需要一个 C 编译器(部分依赖要编译 C 代码):
- macOS:Xcode 命令行工具(同时提供音频绑定所需的 libclang)
- Linux:ALSA 与 udev 开发包 + pkg-config
- python3:部分门禁脚本依赖它
准备 1.12.1 客户端与服务器
- 用
WOW_DATA环境变量指向你自己的 1.12.1 客户端(build 5875,任意语言)的Data目录;也可以在仓库根目录建一个名为WoW的符号链接。benilla 只读不写。 - 准备任意 1.12.1 服务器(开发环境使用 vmangos),用
WOW_HOST指定地址,默认localhost:3724。 - 脚本化运行需要专用测试账号:把
WOW_USER、WOW_PASS、WOW_CHAR各占一行写入仓库根目录的.probe-identity文件(切勿提交)。
⚠️ 超过一千个测试依赖游戏数据,缺少安装时它们会跳过——此时"门禁全绿"是空心的,尽量在有安装的环境里验证。
先跑起来:确认客户端能玩
WOW_DATA=/path/to/WoW/Data cargo play
cargo play 是项目自定义的 alias(等价于 cargo run --profile play -p benilla),是最常用的开发命令。你的设置、截图和插件都会放在仓库根目录的 benilla-config/ 文件夹里,1.12 插件直接放进 benilla-config/AddOns/ 即可加载。
选题方向:新手如何找到第一个任务
- 从 issues 入手:维护者创建的 issue 都先对照 1.12.1 核对过,写清了原版客户端做什么、benilla 现在做什么、代码在哪里——随便挑一个即可开始。跳过标注
in progress的;有了首个 commit 就尽快开 draft PR 并注明Fixes #N占坑。 - 从参考表找缺口:reference/ 目录按 reference/PIN 锁定的提交,vendor 了 benilla-re 逆向工程的表(操作码、事件、CVar、Lua 绑定等),README 里列了每张表由哪些测试读取。
- 从地图入手:docs/MAP.md 是由代码自动生成的完整子系统地图——20 个 crate 从
benilla-mpq、benilla-dbc等格式读取器到benilla-world世界渲染器,Bevy 插件的加载顺序也一目了然。 - 不想开服务器就测 UI:
addon_harness示例能把界面加载进无窗口、无服务器、无登录的 VM,一秒钟内返回结果,适合纯 FrameXML 工作。
快速读懂代码:3 份文档 + 一个开发循环 📖
| 文档 | 用途 |
|---|---|
| AGENTS.md | 项目规则总纲,规定了阅读顺序 |
| docs/METHOD.md | 工作方法:参考先行、用工具测量绝不靠眼睛、小步提交 |
| docs/MAP.md | 定位"现在建了什么"(自动生成,禁止手改) |
| docs/CONTRIBUTING.md | 什么能进、如何评判、PR 开出后会发生什么 |
日常循环很短:
cargo test -p <crate>:只跑单个 crate 的测试,反馈最快- scripts/check.sh:验证你分支改动的 crate 及其依赖方
- scripts/gates.sh:完整门禁链,合并前的最终关卡
PR 被合入的 4 个评判标准 ✅
- 门禁全绿:fmt、clippy(警告一律拒绝)、工作区测试(带与不带游戏数据各跑一遍)、文档链接检查、player 构建与引擎启动检查。
- 写明参考事实:1.12.1 实际做什么,以及你在哪里知道的(benilla-re 条目、DBC 字段、FrameXML 的一行、抓包)。
- 一行注释:在关键处写一行——代码做什么 + 背后对应的 1.12 事实,不写历史。
- 一行 commit 信息:说清改了什么、对玩家还是开发者。
PR 开出后,维护者会对照参考核查、rebase 并补全,最终以 squash 合并成一个 commit(作者仍是你)。所以打开 PR 时务必勾选 "Allow edits by maintainers"。
想加新功能?在 benilla 之上构建 🧩
1.12.1 没有的功能不会进主仓库,但项目明确欢迎,有两条官方路径:
- 独立 crate:通过
benilla_app::run_with注册你自己的 Bevy 插件,范例见 crates/benilla-app/examples/extended_launcher.rs。客户端构建行会显示extended,配置放在自己的benilla-config/,不碰主仓库的 CVar 表。 - fork:
run_with够不到的部分就留给 fork;benilla 不承诺稳定 API,外部 crate 应锁定所基于的 benilla 版本。
提交前最后核对清单 📋
- [ ]
scripts/gates.sh全绿 - [ ] PR 里写明了参考事实(1.12.1 的行为及出处)
- [ ] 一个 PR 只做一件事
- [ ] 未提交
.probe-identity等本地文件 - ] 未提交任何游戏安装内容(硬规则,见 [docs/METHOD.md)
- [ ] 跨平台改动(如新增
cfg(target_os))在 commit 里说明构建过哪些平台
至此,你已具备向 benilla 提交合格 PR 的全部条件。祝第一次贡献顺利!🎉