WoWee - World Of Warcraft Engine Experiment

A native C++ World of Warcraft client with a custom Vulkan renderer.

Protocol Compatible with Vanilla (Classic) 1.12 + TBC 2.4.3 + WotLK 3.3.5a.

Legal Disclaimer: This is an educational/research project. It does not include any Blizzard Entertainment assets, data files, or proprietary code. World of Warcraft and all related assets are the property of Blizzard Entertainment, Inc. This project is not affiliated with or endorsed by Blizzard Entertainment. Users are responsible for supplying their own legally obtained game data files and for ensuring compliance with all applicable laws in their jurisdiction.

Status & Direction (2026-05-13)

• Compatibility: Vanilla (Classic) 1.12 + TBC 2.4.3 + WotLK 3.3.5a are all supported via expansion profiles and per-expansion packet parsers. All three expansions are roughly on par.
• Tested against: AzerothCore/ChromieCraft, TrinityCore, Mangos, and Turtle WoW (1.18).
• Current focus: stability hardening after a large god-object decomposition pass — chasing down behavioral regressions that crept in during the refactor (NPC/UI hitboxes, packet handlers, periodic-spam guards, optimistic-state syncs).
• Warden: Full module execution via Unicorn Engine CPU emulation. Decrypts (RC4→RSA→zlib), parses and relocates the PE module, executes via x86 emulation with Windows API interception. Module cache at ~/.local/share/wowee/warden_cache/.
• CI: GitHub Actions builds for Linux (x86-64, ARM64), Windows (MSYS2 x86-64 + ARM64), and macOS (ARM64). Security scans via CodeQL, Semgrep, and sanitizers. 31 unit-test suites covering protocol parsers, animation FSMs, world-map state, chat markup, macro evaluator, and editor units.
• Container builds: Multi-platform Docker build system for Linux, macOS (arm64/x86_64 via osxcross), and Windows (LLVM-MinGW) cross-compilation.
• Release: v1.9.1-preview — 530+ WoW API functions, 140+ events, broad opcode coverage across Classic / TBC / WotLK / Turtle.

World Editor

Standalone tool for creating custom WoW zones with novel open format exports.

# Build
cmake --build build --target wowee_editor

# Run
./build/bin/wowee_editor --data Data

# Batch convert assets
./build/bin/wowee_editor --convert-m2 Creature/Bear/Bear.m2 --data Data
./build/bin/wowee_editor --convert-wmo World/WMO/Stormwind/Stormwind.wmo --data Data

6 editing modes (Sculpt, Paint, Objects, Water, NPCs, Quests) with 30+ terrain tools, multi-select, time-of-day lighting, quest chains, and full undo/redo.

146+ novel open format catalogs covering everything from terrain (WOT/WHM/WOC), models (WOM1/WOM2/WOM3, WOB), and textures (BLP→PNG) to data-table replacements for spells, items, quests, NPCs, gossip, factions, achievements, mail templates, calendar events, glyphs, talents, currencies, BG rewards, voiceovers, and more. Every catalog round-trips through JSON for human-friendly editing and version control. See tools/editor/FORMAT_SPEC.md for the binary specs.

Exported zones auto-load in the wowee client from custom_zones/ or output/ directories. Sidecar files (.wom, .wob, .png, .json) placed next to legacy .m2 / .wmo / .blp / .dbc are picked up at load time, enabling incremental migration of an existing extracted Data tree without overwriting originals.

AzerothCore integration: File > Generate Server Module creates a ready-to-import module with SQL spawn tables, map registration, teleport commands, zone flags, and a server admin README.

Features

Rendering Engine

• Terrain -- Multi-tile streaming with async loading, texture splatting (4 layers), frustum culling, expanded load radius during taxi flights
• Atmosphere -- Procedural clouds (FBM noise), lens flare with chromatic aberration, cloud/fog star occlusion
• Characters -- Skeletal animation with GPU vertex skinning (256 bones), race-aware textures, per-instance NPC hair/skin textures
• Buildings -- WMO renderer with multi-material batches, frustum culling, collision (wall/floor classification, slope sliding), interior glass transparency
• Instances -- WDT parser for WMO-only dungeon maps, area trigger portals with glow/spin effects, seamless zone transitions
• Water & Lava -- Terrain and WMO water with refraction/reflection, magma/slime rendering with multi-octave FBM noise flow, Beer-Lambert absorption, M2 lava waterfalls with UV scroll
• Particles -- M2 particle emitters with WotLK struct parsing, billboarded glow effects, lava steam/splash effects
• Lighting -- Shadow mapping with PCF filtering, per-frame shadow updates, AABB-based culling, interior/exterior light modes, WMO window glass with fresnel reflections
• Performance -- Binary keyframe search for animations, incremental spatial index, static doodad skip, hash-free render/shadow culling

Asset Pipeline

• Extracted loose-file Data/ tree indexed by manifest.json (fast lookup + caching)
• Optional overlay layers for multi-expansion asset deduplication
• asset_extract + extract_assets.sh (Linux/macOS) / extract_assets.ps1 (Windows) for MPQ extraction (StormLib tooling)
• File formats: BLP (DXT1/3/5), ADT, M2, WMO, DBC (Spell/Item/Faction/etc.)

Gameplay Systems

• Authentication -- Full SRP6a implementation with RC4 header encryption
• Character System -- Creation (with nonbinary gender option), selection, 3D preview, stats panel, race/class support
• Movement -- WASD movement, camera orbit, spline path following, transport riding (trams, ships, zeppelins), movement ACK responses
• Combat -- Auto-attack, spell casting with cooldowns, damage calculation, death handling, spirit healer resurrection
• Targeting -- Tab-cycling with hostility filtering, click-to-target, faction-based hostility (using Faction.dbc)
• Inventory -- 23 equipment slots, 16 backpack slots, drag-drop, auto-equip, item tooltips with weapon damage/speed, server-synced bag sort (quality/type/stack), independent bag windows
• Bank -- Full bank support for all expansions, bag slots, drag-drop, right-click deposit (non-equippable items)
• Spells -- Spellbook with specialty, general, profession, mount, and companion tabs; drag-drop to action bar; item use support
• Talents -- Talent tree UI with proper visuals and functionality
• Action Bar -- 12 slots, drag-drop from spellbook/inventory, click-to-cast, keybindings
• Trainers -- Spell trainer UI, buy spells, known/available/unavailable states
• Quests -- Quest markers (! and ?) on NPCs and minimap, quest log, quest details, turn-in flow, quest item progress tracking
• Auction House -- Search with filters, pagination, sell picker with tooltips, bid/buyout
• Mail -- Item attachment support for sending
• Vendors -- Buy, sell, and buyback (most recent sold item), gold tracking, inventory sync
• Loot -- Loot window, gold looting, item pickup, chest/gameobject looting
• Gossip -- NPC interaction, dialogue options
• Chat -- Tabs/channels, emotes, chat bubbles, clickable URLs, clickable item links with tooltips
• Party -- Group invites, party list, out-of-range member health via SMSG_PARTY_MEMBER_STATS
• Pets -- Pet tracking via SMSG_PET_SPELLS, action bar (10 slots with icon/autocast tinting/tooltips), dismiss button
• Map Exploration -- Subzone-level fog-of-war reveal, world map with continent/zone views, quest POI markers, taxi node markers, party member dots
• NPC Voices -- Race/gender-specific NPC greeting, farewell, vendor, pissed, aggro, and flee sounds for all playable races including Blood Elf and Draenei
• Warden -- Warden anti-cheat module execution via Unicorn Engine x86 emulation (cross-platform, no Wine)
• UI -- Loading screens with progress bar, settings window with graphics quality presets (LOW/MEDIUM/HIGH/ULTRA), shadow distance slider, minimap with zoom/rotation/square mode, top-right minimap mute speaker, separate bag windows with compact-empty mode (aggregate view)

Graphics & Performance

Quality Presets

WoWee includes four built-in graphics quality presets to help you quickly balance visual quality and performance:

Preset	Shadows	MSAA	Normal Mapping	Clutter Density
LOW	Off	Off	Disabled	25%
MEDIUM	200m distance	2x	Basic	60%
HIGH	350m distance	4x	Full (0.8x)	100%
ULTRA	500m distance	8x	Enhanced (1.2x)	150%

Press Escape to open Video Settings and select a preset, or adjust individual settings for a custom configuration.

Performance Tips

• Start with LOW or MEDIUM if you experience frame drops
• Shadows and MSAA have the largest impact on performance
• Reduce shadow distance if shadows cause issues
• Disable water refraction if you encounter GPU errors (requires FSR to be active)
• Use FSR2 (built-in upscaling) for better frame rates on modern GPUs

Building

Prerequisites

# Ubuntu/Debian
# Optional packages (libunicorn-dev / libstorm-dev) enable the Warden
# module executor and the asset_extract tool respectively.
sudo apt install libsdl2-dev libglm-dev libssl-dev \
                 libvulkan-dev vulkan-tools glslc \
                 libavformat-dev libavcodec-dev libswscale-dev libavutil-dev \
                 zlib1g-dev cmake build-essential libx11-dev \
                 libunicorn-dev libstorm-dev

# Fedora — unicorn-devel and StormLib-devel are optional (see above)
sudo dnf install SDL2-devel glm-devel openssl-devel \
                 vulkan-devel vulkan-tools glslc \
                 ffmpeg-devel zlib-devel cmake gcc-c++ libX11-devel \
                 unicorn-devel StormLib-devel

# Arch — vulkan-devel is not a real package on Arch; install the
# headers + loader explicitly. unicorn is optional (Warden);
# StormLib must be installed from AUR for asset_extract.
sudo pacman -S sdl2 glm openssl \
               vulkan-headers vulkan-icd-loader vulkan-tools shaderc \
               ffmpeg zlib cmake base-devel libx11 \
               unicorn

# macOS (Homebrew) — unicorn (Warden) and stormlib (asset_extract) are optional
brew install cmake pkg-config sdl2 glm openssl@3 zlib ffmpeg \
             vulkan-loader vulkan-headers shaderc \
             unicorn stormlib

Container build

Cross-compile inside Docker / Podman with no host toolchain — see container/README.md for full options.

• Install Docker (or Podman)
• From the repo root, run one of:
  • ./container/run-linux.sh → build/linux/bin/wowee
  • ./container/run-macos.sh (Intel: MACOS_ARCH=x86_64 …) → build/macos/bin/wowee
  • ./container/run-windows.sh → build/windows/bin/wowee.exe
• PowerShell siblings (.ps1) are provided for each script.

Game Data

This project requires WoW client data that you extract from your own legally obtained install.

Wowee loads assets via an extracted loose-file tree indexed by manifest.json (it does not read MPQs at runtime).

For a cross-platform GUI workflow (extraction + texture pack management + active override state), see:

• Asset Pipeline GUI

1) Extract MPQs into ./Data/

# Linux / macOS
./extract_assets.sh /path/to/WoW/Data wotlk

# Windows (PowerShell)
.\extract_assets.ps1 "C:\Games\WoW-3.3.5a\Data" wotlk
# Or double-click extract_assets.bat

Data/
  manifest.json
  interface/
  sound/
  world/
  expansions/

Notes:

• StormLib is required to build/run the extractor (asset_extract), but the main client does not require StormLib at runtime.
• extract_assets.sh / extract_assets.ps1 support classic, turtle, tbc, wotlk targets.

2) Point wowee at the extracted data

By default, wowee looks for ./Data/. You can override with:

export WOW_DATA_PATH=/path/to/extracted/Data

Compile & Run

git clone --recurse-submodules https://github.com/Kelsidavis/WoWee.git
cd WoWee

mkdir build && cd build
cmake ..
make -j$(nproc)

./bin/wowee

AMD FSR2 SDK (External)

• Build scripts (build.sh, rebuild.sh, build.ps1, rebuild.ps1) auto-fetch the AMD SDK to:
  • extern/FidelityFX-FSR2
• Source URL:
  • https://github.com/GPUOpen-Effects/FidelityFX-FSR2.git
• Ref:
  • master (depth-1 clone)
• The renderer enables the AMD backend only when both are present:
  • extern/FidelityFX-FSR2/src/ffx-fsr2-api/ffx_fsr2.h
  • extern/FidelityFX-FSR2/src/ffx-fsr2-api/vk/shaders/ffx_fsr2_accumulate_pass_permutations.h
• If the SDK checkout is missing generated Vulkan permutation headers, CMake auto-bootstraps them from third_party/fsr2_vk_permutations.
• If SDK files are missing entirely, CMake falls back to the internal non-AMD FSR2 path automatically.

FidelityFX SDK (Framegen Extern)

• Build scripts and CI also fetch:
  • extern/FidelityFX-SDK
• Source URL:
  • https://github.com/Kelsidavis/FidelityFX-SDK.git
• Ref:
  • main (depth-1 clone)
  • Override with env vars:
    • WOWEE_FFX_SDK_REPO=https://github.com/<you>/FidelityFX-SDK.git
    • WOWEE_FFX_SDK_REF=<branch-or-tag>
• This ref includes Vulkan framegen building blocks (frameinterpolation + opticalflow) and Vulkan shader manifests:
  • sdk/src/backends/vk/CMakeShadersFrameinterpolation.txt
  • sdk/src/backends/vk/CMakeShadersOpticalflow.txt
• CMake option:
  • WOWEE_ENABLE_AMD_FSR3_FRAMEGEN=ON enables a compile-probe target (wowee_fsr3_framegen_amd_vk_probe) that validates SDK FI/OF/FSR3/Vulkan interface headers at build time.
• Runtime toggle:
  • In settings, AMD FSR3 Frame Generation (Experimental) persists to config.
  • Runtime library loader is Path A only (official AMD runtime).
  • Auto-probe checks common names (for example amd_fidelityfx_vk / ffx_fsr3_vk) in loader paths.
  • Override runtime path with:
    • WOWEE_FFX_SDK_RUNTIME_LIB=/absolute/path/to/<amd-runtime-library>
  • If runtime is missing, FG is cleanly unavailable (Path C).

Current FSR Defaults

• Upscaling quality default: Native (100%)
• UI quality order: Native (100%), Ultra Quality (77%), Quality (67%), Balanced (59%)
• Default FSR Sharpness: 1.6
• Default FSR2 Jitter Sign: 0.38
• Performance (50%) preset is intentionally removed.

Controls

Camera & Movement

Key	Action
WASD	Move camera / character
Mouse	Look around / orbit camera
Shift	Move faster
Mouse Left Click	Target entity / interact
Tab	Cycle targets

UI & Windows

Key	Action
B	Toggle bags
C	Toggle character
P	Toggle spellbook
N	Toggle talents
L	Toggle quest log
M	Toggle world map
O	Toggle guild roster
Enter	Open chat
/	Open chat with slash
Escape	Close windows / deselect

Action Bar

Key	Action
1-9, 0, -, =	Use action bar slots 1-12
Drag & Drop	Spells from spellbook, items from inventory
Click	Cast spell / use item

Debug & Development

Key	Action
F1	Performance HUD
F4	Toggle shadows

Documentation

Getting Started

• Project Status -- Current code state, limitations, and near-term direction
• Quick Start -- Installation and first steps
• Build Instructions -- Detailed dependency, build, and run guide
• Asset Pipeline GUI -- Python GUI for extraction, pack installs, ordering, and override rebuilds

Technical Documentation

• Architecture -- System design and module overview
• Authentication -- SRP6 auth protocol details
• Server Setup -- Local server configuration
• Sky System -- Celestial bodies, Azeroth astronomy, and WoW-accurate sky rendering
• SRP Implementation -- Cryptographic details
• Packet Framing -- Network protocol framing
• Realm List -- Realm selection system
• Warden Quick Reference -- Warden module execution overview and testing
• Warden Implementation -- Technical details of the implementation

CI / CD

• GitHub Actions builds on every push: Linux (x86-64, ARM64), Windows (x86-64, ARM64 via MSYS2), macOS (ARM64)
• All build jobs are AMD-FSR2-only (WOWEE_ENABLE_AMD_FSR2=ON) and explicitly build wowee_fsr2_amd_vk
• Each job clones AMD's FSR2 SDK and FidelityFX-SDK (Kelsidavis/FidelityFX-SDK, main by default)
• Linux CI validates FidelityFX-SDK Kits framegen headers
• FSR3 Path A runtime build auto-bootstraps missing VK permutation headers via tools/generate_ffx_sdk_vk_permutations.sh
• CI builds wowee_fsr3_framegen_amd_vk_probe when that target is generated for the detected SDK layout
• If FSR2 generated Vulkan permutation headers are absent upstream, WoWee bootstraps them from third_party/fsr2_vk_permutations
• Container build via container/run-{linux,macos,windows}.sh (Docker/Podman)

Security

• GitHub Actions runs a dedicated security workflow at .github/workflows/security.yml.
• Current checks include:
  • CodeQL for C/C++
  • Semgrep static analysis
  • Sanitizer build (ASan + UBSan)

Technical Details

• Platform: Linux (primary), Windows (MSYS2/MSVC), macOS — C++20, CMake 3.15+
• Dependencies: SDL2, Vulkan, GLM, OpenSSL, ImGui, FFmpeg, Unicorn Engine (StormLib for asset extraction tooling)
• Architecture: Modular design with clear separation (core, rendering, networking, game logic, asset pipeline, UI, audio). The original god-object classes were decomposed into domain-focused subsystems: GameHandler → dispatch table + 8 domain handlers + EntityController + GameServices; ChatPanel → 15+ modules with 11 command files under src/ui/chat/; WorldMap → 16 modules under src/rendering/world_map/; TransportManager → 7 spline parsers + path repository + CatmullRomSpline in src/math/; AnimationController → composed FSM (Locomotion / Combat / Activity / Mount) with 30-phase character animation state machine.
• Networking: Non-blocking TCP, SRP6a authentication, RC4 encryption, WoW 3.3.5a protocol
• Asset Loading: Extracted loose-file tree + manifest.json indexing, async terrain streaming, overlay layers
• Sky System: WoW-accurate DBC-driven architecture
  • Lore-Accurate Moons: White Lady (30-day cycle) + Blue Child (27-day cycle)
  • Deterministic Phases: Computed from server game time when available (fallback: local time/dev cycling)
  • Camera-Locked: Sky dome uses rotation-only transform (translation ignored)
  • No Latitude Math: Per-zone artistic constants, not Earth-like planetary simulation
  • Zone Identity: Different skyboxes per continent (Azeroth, Outland, Northrend)

License

This project's source code is licensed under the MIT License.

This project does not include any Blizzard Entertainment proprietary data, assets, or code. World of Warcraft is (c) 2004-2024 Blizzard Entertainment, Inc. All rights reserved.

References

• WoWDev Wiki -- File format documentation
• TrinityCore -- Server reference
• MaNGOS -- Server reference
• StormLib -- MPQ library

Known Issues

This is a work in progress and the bug list is non-trivial. Current known gaps (as of v1.9.1-preview):

• Warden RSA modulus is a placeholder; full anti-cheat parity needs the modulus extracted from a real WoW.exe. Module execution itself (Unicorn x86 emulation) is otherwise working.
• Quest GameObject loot (e.g. Bundle of Wood on ChromieCraft) is not 100% reliable — the CMSG_GAMEOBJ_USE → cast → CMSG_LOOT chain works for most chests but a few quest objectives still need confirmation.
• Transport edge cases — most trams/ships/zeppelins ride correctly, but the long Northrend rotational paths still show the occasional spline wrap glitch.
• World-map zone hover has edge cases at continent boundaries.
• Pet bar protocol uses values targeted at AzerothCore-style servers; other forks may need adjustment.

If you hit something that looks wrong, please open an issue with the relevant log line — the dispatch tables print LOG_INFO / LOG_DEBUG for most packet handlers, which makes triage straightforward.

Star History