diff --git a/README.md b/README.md index 9d73c9d0..d0d295c1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

benilla

-

A from-scratch World of Warcraft 1.12.1 client in Rust and Bevy

+

A complete World of Warcraft 1.12.1 client, written from scratch in Rust and Bevy

Discord YouTube devlog @@ -8,65 +8,79 @@

-benilla speaks the original 1.12.1 protocol, so it connects to any server the real client could, -and reads its game data at runtime from your own 1.12.1 install. Every file format and the network -protocol are implemented from scratch, with no original client code, no third-party WoW crates, -and no bundled game assets. +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 works +## What's inside -- **Formats:** readers for the full asset stack (MPQ patch chain, BLP, DBC, ADT/WDT/WDL, M2, WMO), - wired into Bevy as an asset source. -- **World:** streamed terrain out to the horizon, portal-culled WMOs with interior lighting, - doodads and ground clutter, swimmable liquids, sky and weather, and the client's own day/night - lighting, fog and gamma passes. -- **Models:** GPU-skinned M2s with the full animation controller, a near feature-complete particle - system, ribbons, and animated gameobjects from doors to lifts. -- **Characters:** customization end to end, the armor texture composite, weapons with sheathing and - enchant glows, shapeshift forms, stealth and mounts. -- **Movement:** a WoW-feel controller, 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, the object mirror into the ECS, and live - wire coverage from movement and chat through spells, party, quests, mail, trade, vendors, bank, - loot, the auction house, PvP honor and battlegrounds. -- **UI:** a from-scratch FrameXML + Lua engine that runs the client's own stock interface off - your install's patch chain, from the login and character screens through the full HUD, the - classic windows (guild, macros and key bindings included), chat, nameplates, floating combat - text and tooltips; third-party addons load from a `benilla-config/AddOns/` folder beside the - executable (partial: AtlasLoot and Bagnon run). -- **Combat:** melee on the faithful swing law, ranged and Auto Shot, casting with GCD and - cooldowns, combo points, crowd control that really holds you, and the spell visual pipeline. -- **Audio:** music, ambience and SFX under the client's own selection and crossfade rules, with - interior and underwater transitions and zone reverb. +- **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. -## Where it's going +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, +generated from the code. -benilla is done when a 1.12.1 player can do everything here that they could in the original -client, it looks and feels the same, and it runs from a download on Windows, Linux and macOS. -No dates; the order is what is likely, not a promise. +## Status -- The long tail of small features that separates a working client from a finished one. +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. -- Playable downloads for Windows, Linux and macOS. Linux first. + +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 -You need a **1.12.1 (build 5875) client install** for game data, a vanilla server to connect to, -stable Rust and a C compiler (the Lua is built from source; on macOS the Xcode command line -tools, on Linux the ALSA and udev development packages). Any 1.12.1 core works; -[vmangos](https://github.com/vmangos/core) is what development runs against, and cMaNGOS and -the rest speak the same protocol. +benilla builds and runs on macOS, Linux and Windows. You need: + +- **An English 1.12.1 client (build 5875)** for the game data. benilla only reads it. +- **A 1.12.1 server with Warden off.** [vmangos](https://github.com/vmangos/core) is what + development runs against, and it ships with Warden off; cMaNGOS and the other 1.12.1 cores speak + the same protocol. +- **Stable Rust and a C compiler**, because the client's Lua is built from source: 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 ``` -The server defaults to `localhost:3724`, the stock `realmd` auth port. Point `WOW_HOST` -at any IP or hostname, appending the auth port if yours is remapped -(`WOW_HOST=play.example.com:5000`). Credentials go in at the login screen, or set `WOW_USER` / -`WOW_PASS` to skip it. +`WOW_DATA` names the install's `Data` folder; a link to the install named `WoW` at the repo root +does the same. 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 @@ -81,12 +95,12 @@ Early inspiration and file format guidance came from the [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. The stock interface runs off your own install's -FrameXML at runtime; the handful of files under `crates/benilla-app/assets/ui/` are our own -adapters and developer frames, not copies of it. +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 two vendored components -under `third_party/` — the kira audio engine, and a Lua 5.1 patched to the 1.12 client's dialect — +under `third_party/`, the kira audio engine and a Lua 5.1 patched to the 1.12 client's dialect, keep their own upstream licenses, alongside each.