如何给benilla贡献代码:Rust魔兽世界客户端开发者上手指南

原创2026-10-26 13:33:422,145 阅读

如何给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/ 即可加载。

选题方向:新手如何找到第一个任务

  1. 从 issues 入手:维护者创建的 issue 都先对照 1.12.1 核对过,写清了原版客户端做什么、benilla 现在做什么、代码在哪里——随便挑一个即可开始。跳过标注 in progress 的;有了首个 commit 就尽快开 draft PR 并注明 Fixes #N 占坑。
  2. 从参考表找缺口:reference/ 目录按 reference/PIN 锁定的提交,vendor 了 benilla-re 逆向工程的表(操作码、事件、CVar、Lua 绑定等),README 里列了每张表由哪些测试读取。
  3. 从地图入手:docs/MAP.md 是由代码自动生成的完整子系统地图——20 个 crate 从 benilla-mpq、benilla-dbc 等格式读取器到 benilla-world 世界渲染器,Bevy 插件的加载顺序也一目了然。
  4. 不想开服务器就测 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 个评判标准 ✅

  1. 门禁全绿:fmt、clippy(警告一律拒绝)、工作区测试(带与不带游戏数据各跑一遍)、文档链接检查、player 构建与引擎启动检查。
  2. 写明参考事实:1.12.1 实际做什么,以及你在哪里知道的(benilla-re 条目、DBC 字段、FrameXML 的一行、抓包)。
  3. 一行注释:在关键处写一行——代码做什么 + 背后对应的 1.12 事实,不写历史。
  4. 一行 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 版本。

提交前最后核对清单 📋

至此,你已具备向 benilla 提交合格 PR 的全部条件。祝第一次贡献顺利!🎉

登录后查看全文
benilla