A native C++ World of Warcraft client with a custom Vulkan renderer.
WoWee supports Vanilla 1.12, TBC 2.4.3, and WotLK 3.3.5a through expansion-specific profiles and packet parsers. It has been tested with AzerothCore/ChromieCraft, TrinityCore, MaNGOS, and Turtle WoW 1.18.
Watch the latest demonstration · Download the latest release · Read the project status
Note
macOS release DMGs are Developer ID signed, notarized by Apple, and stapled before publication. Gatekeeper should identify them as notarized Developer ID software without requiring an Open Anyway exception.
Important
WoWee is an educational and research project. It contains no Blizzard Entertainment assets, data, or proprietary code. You must supply your own legally obtained game data and comply with the laws in your jurisdiction. WoWee is not affiliated with or endorsed by Blizzard Entertainment.
- Vulkan terrain, WMO, M2, water/lava, particles, lighting, shadows, weather, and asynchronous world streaming
- SRP6 authentication, RC4 header encryption, and protocol handling for all three supported expansions
- Character creation and selection, movement, transports, combat, spells, talents, inventory, banks, vendors, trainers, quests, loot, mail, auction house, gossip, chat, parties, pets, maps, and taxi travel
- Optional Warden module execution through Unicorn Engine x86 emulation
This is an active work in progress, not a drop-in replacement for the official client. See Known limitations before reporting a bug.
The world editor and AMD FSR3 frame generation are early developer features. Their interfaces, formats, runtime requirements, and behavior may change. FSR2 upscaling is available, but graphics acceleration features are still under active development and should not be treated as release-critical functionality.
Unicorn enables Warden execution. StormLib is needed by the asset extractor, but is not required by the client at runtime.
Ubuntu / Debian
sudo apt install build-essential cmake pkg-config git \
libsdl2-dev libglm-dev libssl-dev zlib1g-dev libx11-dev \
libvulkan-dev vulkan-tools glslc \
libavformat-dev libavcodec-dev libswscale-dev libavutil-dev
# Optional: Warden execution and MPQ extraction
sudo apt install libunicorn-dev
sudo apt install libstorm-devFedora
sudo dnf install gcc-c++ cmake pkgconf-pkg-config git \
SDL2-devel glm-devel openssl-devel zlib-devel libX11-devel \
vulkan-devel vulkan-tools glslc ffmpeg-devel
# Optional: Warden execution
sudo dnf install unicorn-develFor asset_extract, build StormLib
from source if it is unavailable in your enabled Fedora repositories.
Arch Linux
sudo pacman -S base-devel cmake pkgconf git \
sdl2-compat glm openssl zlib libx11 \
vulkan-headers vulkan-icd-loader vulkan-tools shaderc \
ffmpegInstall unicorn for optional Warden execution. StormLib is not in the official
repositories; install stormlib-git from the AUR if you need asset_extract.
macOS
Vulkan runs through MoltenVK.
brew install cmake pkg-config sdl2 glm openssl@3 zlib ffmpeg \
vulkan-loader vulkan-headers molten-vk shaderc
# Optional: Warden execution and MPQ extraction
brew install unicorn stormlibFor Windows/MSYS2, Visual Studio, and platform-specific notes, see the complete build guide.
git clone --recurse-submodules https://github.com/Kelsidavis/WoWee.git
cd WoWee
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallelThe optional build.sh and build.ps1 helpers fetch supported AMD SDK sources
when needed. A plain CMake build works without them and uses the internal
fallback when optional SDK components are unavailable.
WoWee does not read MPQs at runtime. Extract a legally obtained client into a
loose-file Data/ tree with a generated manifest.json:
# Linux / macOS
./extract_assets.sh /path/to/WoW/Data wotlk
# Windows PowerShell
.\extract_assets.ps1 "C:\Games\WoW-3.3.5a\Data" wotlkValid targets are classic, turtle, tbc, and wotlk. Each target is kept
separately, so multiple expansions can coexist:
Data/
└── expansions/
├── classic/manifest.json
├── turtle/manifest.json
├── tbc/manifest.json
└── wotlk/manifest.json
The login-screen Assets selector normally follows the selected server's expansion. It can be overridden per saved server profile.
To store data elsewhere:
export WOW_DATA_PATH=/path/to/extracted/DataThe Asset Pipeline GUI provides extraction, texture-pack management, ordering, and override controls.
./build/bin/woweeIf a MaNGOS realm advertises a world address that is unreachable from your LAN, override only the host; the advertised port is preserved:
export WOWEE_REALM_HOST_OVERRIDE=192.168.1.50Turtle WoW defaults to authentication build 7272. Older compatible servers can use:
export WOWEE_TURTLE_AUTH_BUILD=7234Docker or Podman can build all supported targets without installing a host toolchain:
./container/run-linux.sh # build/linux/bin/wowee
./container/run-macos.sh # build/macos/bin/wowee
./container/run-windows.sh # build/windows/bin/wowee.exePowerShell equivalents are included. macOS defaults to ARM64; set
MACOS_ARCH=x86_64 for Intel. See Container Builds for
all options.
wowee_editor is an early-stage tool for experimenting with custom zones and
open, JSON-friendly formats. It is not yet a production-ready content pipeline.
cmake --build build --target wowee_editor
./build/bin/wowee_editor --data Data
# Batch conversion examples
./build/bin/wowee_editor --convert-m2 Creature/Bear/Bear.m2 --data Data
./build/bin/wowee_editor --convert-wmo World/WMO/Stormwind/Stormwind.wmo --data DataCurrent work includes terrain editing, object placement, water, NPCs, quests,
lighting, and experimental AzerothCore export. Exported zones can load from
custom_zones/ or output/, but formats and compatibility may change.
See the editor format specification for the custom binary and catalog formats.
| Input | Action |
|---|---|
W A S D |
Move |
| Mouse | Look or orbit camera |
| Left click | Target or interact |
Tab |
Cycle targets |
1–0, -, = |
Action-bar slots 1–12 |
B / C / P / N |
Bags / character / spellbook / talents |
L / M / O |
Quest log / map / guild roster |
Enter or / |
Open chat |
/unstuck |
Recover when terrain or WMO collision traps the character |
Escape |
Close windows or deselect |
F1 / F4 |
Performance HUD / shadows |
Graphics presets and individual controls are available under Video Settings. Shadows and MSAA have the largest performance cost; FSR2 can improve frame rate on supported hardware.
- Architecture
- Authentication and SRP Implementation
- Packet Framing and Realm List
- Sky System
- Warden Quick Reference and Implementation
WoWee uses C++20 and CMake 3.15+. GitHub Actions builds Linux x86-64/ARM64, Windows x86-64/ARM64, and macOS ARM64 releases. Security checks include CodeQL, Semgrep, AddressSanitizer, and UndefinedBehaviorSanitizer.
The codebase is split into focused rendering, networking, gameplay, asset, UI, audio, and editor modules. Start with the architecture guide before making broad changes.
- The Warden RSA modulus is a placeholder; module execution otherwise works through Unicorn x86 emulation.
- Terrain/WMO transitions are a longstanding regression area. Character floor
selection can occasionally prefer the wrong surface or leave the character
stuck. Enter
/unstuckin chat to recover, then include the location and relevant log lines in a bug report. - Long rotational Northrend transport paths can occasionally show spline-wrap glitches.
- World-map zone hover has edge cases near continent boundaries.
- Pet-bar protocol behavior may require adjustment for non-AzerothCore forks.
When reporting a bug, include the relevant client log lines, expansion, server core, and reproduction steps.
WoWee source code is available under the MIT License. World of Warcraft and its assets are property of Blizzard Entertainment, Inc.
- WoWDev Wiki — file-format documentation
- TrinityCore — server reference
- MaNGOS — server reference
- StormLib — MPQ library