Mathih13
8100fe9820
The script host now runs on benilla-lua alone. The vendored C Lua 5.1.5 (`third_party/lua-src`) and mlua are removed, about 17k lines. `vm_parity` checks benilla-lua against the answers the C build recorded on Linux and macOS, and `front_end` checks every corpus chunk's compiled shape against the C build's digest. `GRAMMAR.md` records each grammar change from 5.1, by client address. A handler's `this`, `event` and `arg1`… are bound in one VM call. An event fire saves and restores `event`, while the handler runner saves only `this` (`0x704d50`). Ours on the branch: VM fixes from review (hook dispatch counts, registers and frames around a collection, protected-call handlers, library errors) and `vm_parity`'s two-VM leftovers removed. Tests: the full gate chain on the merged tree, `vm_parity` and `front_end` among them. Live: smoke and a stock-glue login. Load time is level with C Lua, and memory is within 7%. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-Authored-By: Sam <samuv.eth@gmail.com>
124 lines
7.0 KiB
Markdown
124 lines
7.0 KiB
Markdown
<div align="center">
|
|
<h1>benilla</h1>
|
|
<p><b>A complete World of Warcraft 1.12.1 client, written from scratch in Rust and <a href="https://bevy.org">Bevy</a></b></p>
|
|
<p>
|
|
<a href="https://discord.gg/wJSJx467G4"><img src="https://img.shields.io/discord/1529280129518538922?style=for-the-badge&logo=discord&logoColor=white&label=discord&color=5865F2" alt="Discord"></a>
|
|
<a href="https://www.youtube.com/playlist?list=PLdCnpZNKxyb8"><img src="https://img.shields.io/badge/devlog-youtube-FF0000?style=for-the-badge&logo=youtube&logoColor=white" alt="YouTube devlog"></a>
|
|
<a href="LICENSE-MIT"><img src="https://img.shields.io/badge/license-MIT%20%2F%20Apache--2.0-blue?style=for-the-badge" alt="License"></a>
|
|
</p>
|
|
</div>
|
|
|
|
benilla plays the whole game: character creation, questing and professions, dungeons and raids,
|
|
battlegrounds and honor, groups, guilds, trade, mail and the auction house, on the stock 1.12
|
|
interface and with your addons. It connects to a 1.12.1 server over the original protocol and
|
|
reads the game's data from your own 1.12.1 install. Every file format, the network protocol and
|
|
the interface engine are written from scratch, with no original client code, no third-party WoW
|
|
crates and no bundled game assets.
|
|
|
|
What the real client does is read at its bytes in
|
|
[benilla-re](https://github.com/samwhosung/benilla-re), the reverse engineering benilla is built
|
|
against, by the same client addresses the comments here cite.
|
|
|
|
## What's inside
|
|
|
|
- **Formats:** readers for the whole asset stack (the MPQ patch chain, BLP, DBC, ADT, WDT, WDL, M2
|
|
and WMO), wired into Bevy as an asset source.
|
|
- **World:** terrain streamed out to the horizon, portal-culled buildings with interior lighting,
|
|
doodads and ground clutter, swimmable water, sky and weather, and the client's own day/night
|
|
lighting, fog and gamma.
|
|
- **Models:** GPU-skinned M2s with the full animation controller, particles, ribbons and the spell
|
|
visuals, and characters end to end: customization, the armor composite, weapons with their
|
|
enchant glows, forms, stealth and mounts.
|
|
- **Movement:** networked movement in both directions, the server-granted modes from slow fall to
|
|
roots, a follow camera with collision, boats, zeppelins and taxi flights.
|
|
- **Networking:** SRP6 auth through world-session crypto and the object mirror into the ECS,
|
|
covering the game from movement and chat through combat, spells, groups and raids, quests,
|
|
trade, mail, the auction house and battlegrounds.
|
|
- **Interface:** a FrameXML and Lua engine that runs the stock 1.12 interface off your install's
|
|
patch chain, and third-party 1.12 addons: Questie, pfUI, Bagnon, Bartender2 and most others
|
|
run. By choice, the options window and the ESC menu follow the Classic Era client's rather than
|
|
1.12's.
|
|
- **Audio:** music, ambience and effects under the client's own selection and crossfade rules,
|
|
with interior and underwater transitions and zone reverb.
|
|
|
|
The format readers and the UI engine core are plain Rust with no Bevy in them, and the world
|
|
renderer runs with no game attached. [`docs/MAP.md`](docs/MAP.md) maps every crate and subsystem,
|
|
and [`docs/DEVIATIONS.md`](docs/DEVIATIONS.md) lists everywhere benilla differs from 1.12.1; both are
|
|
generated from the code.
|
|
|
|
## Status
|
|
|
|
Complete and fully playable. What is left:
|
|
|
|
- The long tail of small features that separates a working client from a finished one, tracked
|
|
as [issues](https://github.com/samwhosung/benilla/issues).
|
|
- Addons, options and performance, ongoing.
|
|
|
|
benilla is a faithful 1.12.1 client and the foundation people build on. There are no prebuilt
|
|
downloads: a packaged build, a particular server's changes or anything 1.12.1 never had belongs
|
|
in a fork, and forks are welcome. GitHub lists
|
|
[every public fork](https://github.com/samwhosung/benilla/forks).
|
|
|
|
Not planned: other expansions or client versions, Warden (anticheat).
|
|
|
|
## Running it
|
|
|
|
benilla builds and runs on macOS, Linux and Windows. You need:
|
|
|
|
- **A 1.12.1 client (build 5875)** for the game data, in any locale. benilla only reads it, and
|
|
shows its text in the client's language; development runs on English clients.
|
|
- **A 1.12.1 server.** [vmangos](https://github.com/vmangos/core) is what development runs
|
|
against; cMaNGOS and the other 1.12.1 cores speak the same protocol. benilla does not answer
|
|
Warden, so a server that enforces it disconnects the session after its timeout; vmangos ships
|
|
with Warden off.
|
|
- **Stable Rust and a C compiler**, which some dependencies build with: on macOS the
|
|
Xcode command line tools, on Linux the ALSA and udev development packages and pkg-config, on
|
|
Windows the MSVC build tools that the Rust installer sets up.
|
|
|
|
```sh
|
|
WOW_DATA=/path/to/WoW/Data cargo run --release -p benilla
|
|
```
|
|
|
|
On Windows, in PowerShell:
|
|
|
|
```powershell
|
|
$env:WOW_DATA="C:\path\to\WoW\Data"; cargo run --release -p benilla
|
|
```
|
|
|
|
Each release is a tag on the [Releases page](https://github.com/samwhosung/benilla/releases):
|
|
`git checkout <tag>` first runs that release, and `main` is the development tip.
|
|
|
|
`WOW_DATA` names the install's `Data` folder; a link to the install named `WoW` at the repo root
|
|
does the same (`ln -s /path/to/WoW WoW`, or on Windows a junction, which needs no admin rights:
|
|
`New-Item -ItemType Junction -Path WoW -Target C:\path\to\WoW`). The server defaults to
|
|
`localhost:3724`, the stock auth port. Point `WOW_HOST` at another (`WOW_HOST=play.example.com`, or
|
|
`play.example.com:5000` for a remapped port), or set it from the Realmlist button on the login
|
|
screen, which remembers it. Credentials go in at the login screen, or set `WOW_USER` and `WOW_PASS`
|
|
to skip it.
|
|
|
|
Settings, screenshots and addons live in `benilla-config/` at the repo root: a 1.12 addon goes in
|
|
`benilla-config/AddOns/`. [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) has the rest, from the
|
|
player build to the tests.
|
|
|
|
## Contributing
|
|
|
|
Issues and pull requests are open. [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) says where to
|
|
start, what gets in, how a change is judged and what happens to a pull request once it is open.
|
|
Bugs, questions and ideas are welcome on the [Discord](https://discord.gg/wJSJx467G4) too.
|
|
|
|
---
|
|
|
|
Early inspiration and file format guidance came from the
|
|
[wowemulation-dev](https://github.com/wowemulation-dev) community, and
|
|
[warcraft-rs](https://github.com/wowemulation-dev/warcraft-rs) in particular.
|
|
|
|
benilla is an independent fan project, not affiliated with or endorsed by Blizzard Entertainment.
|
|
It ships **no Blizzard content**: no art, models, sounds, maps, MPQ contents or FrameXML. You
|
|
provide your own legally obtained 1.12.1 client, and the stock interface runs off its FrameXML at
|
|
runtime. The few files under `crates/benilla-app/assets/ui/` are our own, not copies of it:
|
|
adapters over stock files, and the settings windows and script error log benilla draws itself.
|
|
|
|
World of Warcraft is a trademark of Blizzard Entertainment, Inc. Our own code is licensed under
|
|
[MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE), at your option. The kira audio engine under
|
|
`third_party/` is vendored under the same two licenses, with its author's copyright notices beside it.
|