docs: update README and guides for multi-expansion direction

BUILD_INSTRUCTIONS.md

@@ -69,25 +69,36 @@ Binary output:
 build/bin/wowee
 ```
 
-## 4. Provide WoW 3.3.5a Data
+## 4. Provide WoW Data (Extract + Manifest)
 
-Supply your own legally obtained data files in either:
+Wowee loads assets from an extracted loose-file tree indexed by `manifest.json` (it does not read MPQs at runtime).
 
-1. `./Data/`
+### Option A: Extract into `./Data/` (recommended)
-2. Path pointed to by `WOW_DATA_PATH`
 
-Example:
+Run:
+
+```bash
+# WotLK 3.3.5a example
+./extract_assets.sh /path/to/WoW/Data wotlk
+```
+
+The output includes:
 
 ```text
 Data/
-  common.MPQ
+  manifest.json
-  common-2.MPQ
+  interface/
-  expansion.MPQ
+  sound/
-  lichking.MPQ
+  world/
-  patch.MPQ
+  expansions/
-  patch-2.MPQ
+```
-  patch-3.MPQ
+
-  enUS/
+### Option B: Use an existing extracted data tree
+
+Point wowee at your extracted `Data/` directory:
+
+```bash
+export WOW_DATA_PATH=/path/to/extracted/Data
 ```
 
 ## 5. Run
@@ -118,12 +129,12 @@ Ensure `extern/imgui` exists:
 git clone https://github.com/ocornut/imgui.git extern/imgui
 ```
 
-### MPQ/Data not found at runtime
+### Data not found at runtime
 
-Place data under `./Data` or set:
+Verify `Data/manifest.json` exists (or re-run `./extract_assets.sh ...`), or set:
 
 ```bash
-export WOW_DATA_PATH=/path/to/WoW/Data
+export WOW_DATA_PATH=/path/to/extracted/Data
 ```
 
 ### Clean rebuild

README.md

@@ -4,10 +4,19 @@
   <img src="assets/Wowee.png" alt="Wowee Logo" width="240" />
 </p>
 
-A native C++ client for World of Warcraft 3.3.5a (Wrath of the Lich King) with a fully functional OpenGL rendering engine.
+A native C++ World of Warcraft client with a custom OpenGL renderer.
+
+Primary target today is **WotLK 3.3.5a**, with active work to broaden compatibility across **Vanilla (Classic) + TBC + WotLK**.
 
 > **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-02-15)
+
+- **Compatibility direction**: support **Vanilla (Classic) + TBC + WotLK** by selecting an expansion profile and using opcode/parser variants (`src/game/packet_parsers_classic.cpp`, `src/game/packet_parsers_tbc.cpp`).
+- **Primary target**: WoW **WotLK 3.3.5a (build 12340)** online client, tested mainly against WotLK emulator cores (AzerothCore/TrinityCore variants).
+- **Current focus**: protocol correctness (chat, spell casting results, transports) and visuals accuracy (M2/WMO edge cases, equipment textures).
+- **Warden**: crypto + module plumbing are implemented; full module execution is still in progress (see Warden docs).
+
 ## Features
 
 ### Rendering Engine
@@ -16,7 +25,7 @@ A native C++ client for World of Warcraft 3.3.5a (Wrath of the Lich King) with a
 - **Sky System** -- WoW-accurate DBC-driven lighting with skybox authority
   - **Skybox** -- Camera-locked celestial sphere (M2 model support, gradient fallback)
   - **Celestial Bodies** -- Sun (lighting-driven), White Lady + Blue Child (Azeroth's two moons)
-  - **Moon Phases** -- Server time-driven deterministic phases (30-day / 27-day cycles)
+  - **Moon Phases** -- Game time-driven deterministic phases when server time is available (fallback: local cycling for development)
   - **Stars** -- Baked into skybox assets (procedural fallback for development/debug only)
 - **Atmosphere** -- Procedural clouds (FBM noise), lens flare with chromatic aberration, cloud/fog star occlusion
 - **Weather** -- Rain and snow particle systems (2000 particles, camera-relative)
@@ -26,7 +35,10 @@ A native C++ client for World of Warcraft 3.3.5a (Wrath of the Lich King) with a
 - **Post-Processing** -- HDR, tonemapping, shadow mapping (2048x2048)
 
 ### Asset Pipeline
-- **MPQ** archive extraction (StormLib), **BLP** DXT1/3/5 textures, **ADT** terrain tiles, **M2** character models with animations, **WMO** buildings, **DBC** database files (Spell, Item, SkillLine, Faction, etc.)
+- 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` 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
@@ -41,7 +53,7 @@ A native C++ client for World of Warcraft 3.3.5a (Wrath of the Lich King) with a
 - **Vendors** -- Buy and sell items, gold tracking, inventory sync
 - **Loot** -- Loot window, gold looting, item pickup
 - **Gossip** -- NPC interaction, dialogue options
-- **Chat** -- SAY, YELL, WHISPER, chat window with formatting
+- **Chat** -- Tabs/channels, emotes, chat bubbles, clickable URLs, clickable item links with tooltips
 - **Party** -- Group invites, party list
 - **UI** -- Loading screens with progress bar, settings window with opacity slider
 
@@ -52,34 +64,53 @@ A native C++ client for World of Warcraft 3.3.5a (Wrath of the Lich King) with a
 ```bash
 # Ubuntu/Debian
 sudo apt install libsdl2-dev libglew-dev libglm-dev \
-                 libssl-dev libstorm-dev cmake build-essential
+                 libssl-dev cmake build-essential \
+                 libstorm-dev  # for asset_extract
 
 # Fedora
 sudo dnf install SDL2-devel glew-devel glm-devel \
-                 openssl-devel StormLib-devel cmake gcc-c++
+                 openssl-devel cmake gcc-c++ \
+                 StormLib-devel  # for asset_extract
 
 # Arch
-sudo pacman -S sdl2 glew glm openssl stormlib cmake base-devel
+sudo pacman -S sdl2 glew glm openssl cmake base-devel \
+                 stormlib  # for asset_extract
 ```
 
 ### Game Data
 
-This project requires WoW 3.3.5a (patch 3.3.5, build 12340) data files. You must supply your own legally obtained copy. Place (or symlink) the MPQ files into a `Data/` directory at the project root:
+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).
-wowee/
+
-└── Data/
+#### 1) Extract MPQs into `./Data/`
-    ├── common.MPQ
+
-    ├── common-2.MPQ
+```bash
-    ├── expansion.MPQ
+# WotLK 3.3.5a example
-    ├── lichking.MPQ
+./extract_assets.sh /path/to/WoW/Data wotlk
-    ├── patch.MPQ
-    ├── patch-2.MPQ
-    ├── patch-3.MPQ
-    └── enUS/          (or your locale)
 ```
 
-Alternatively, set the `WOW_DATA_PATH` environment variable to point to your WoW data directory.
+```
+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` supports `classic`, `turtle`, `tbc`, `wotlk` targets.
+
+#### 2) Point wowee at the extracted data
+
+By default, wowee looks for `./Data/`. You can override with:
+
+```bash
+export WOW_DATA_PATH=/path/to/extracted/Data
+```
 
 ### Compile & Run
 
@@ -142,6 +173,7 @@ make -j$(nproc)
 ## Documentation
 
 ### Getting Started
+- [Project Status](docs/status.md) -- Current code state, limitations, and near-term direction
 - [Quick Start](docs/quickstart.md) -- Installation and first steps
 - [Build Instructions](BUILD_INSTRUCTIONS.md) -- Detailed dependency, build, and run guide
 
@@ -153,20 +185,22 @@ make -j$(nproc)
 - [SRP Implementation](docs/srp-implementation.md) -- Cryptographic details
 - [Packet Framing](docs/packet-framing.md) -- Network protocol framing
 - [Realm List](docs/realm-list.md) -- Realm selection system
+- [Warden Quick Reference](docs/WARDEN_QUICK_REFERENCE.md) -- Testing notes and common fixes
+- [Warden Implementation](docs/WARDEN_IMPLEMENTATION.md) -- What works today and what remains
 
 ## Technical Details
 
 - **Graphics**: OpenGL 3.3 Core, GLSL 330, forward rendering with post-processing
 - **Performance**: 60 FPS (vsync), ~50k triangles/frame, ~30 draw calls, <10% GPU
 - **Platform**: Linux (primary), C++20, CMake 3.15+
-- **Dependencies**: SDL2, OpenGL/GLEW, GLM, OpenSSL, StormLib, ImGui, FFmpeg
+- **Dependencies**: SDL2, OpenGL/GLEW, GLM, OpenSSL, ImGui, FFmpeg (StormLib for asset extraction tooling; Unicorn optional for Warden emulation)
 - **Architecture**: Modular design with clear separation (core, rendering, networking, game logic, asset pipeline, UI, audio)
 - **Networking**: Non-blocking TCP, SRP6a authentication, RC4 encryption, WoW 3.3.5a protocol
-- **Asset Loading**: Async terrain streaming, lazy loading, MPQ archive support
+- **Asset Loading**: Extracted loose-file tree + `manifest.json` indexing, async terrain streaming, overlay layers
 - **Sky System**: WoW-accurate DBC-driven architecture
   - **Skybox Authority**: Stars baked into M2 sky dome models (not procedurally generated)
   - **Lore-Accurate Moons**: White Lady (30-day cycle) + Blue Child (27-day cycle)
-  - **Deterministic Phases**: Computed from server game time (consistent across sessions)
+  - **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)

docs/architecture.md

@@ -89,7 +89,7 @@ Wowee follows a modular architecture with clear separation of concerns:
 - VAO/VBO/EBO management
 
 **Texture** - Texture management
-- Loading (will support BLP format)
+- Loading (BLP via `AssetManager`, optional PNG overrides for development)
 - OpenGL texture object
 - Mipmap generation
 
@@ -191,11 +191,14 @@ Wowee follows a modular architecture with clear separation of concerns:
 
 ### 6. Asset Pipeline (`src/pipeline/`)
 
-**MPQManager** - Archive management
+**AssetManager** - Runtime asset access
-- Loads .mpq files (via StormLib)
+- Loads an extracted loose-file tree indexed by `Data/manifest.json`
-- Priority-based file lookup (patch files override base files)
+- Layered resolution via optional overlay manifests (multi-expansion dedup)
-- Data extraction with caching
+- File cache + path normalization
-- Locale support (enUS, enGB, etc.)
+
+**asset_extract (tool)** - MPQ extraction
+- Uses StormLib to extract MPQs into `Data/` and generate `manifest.json`
+- Driven by `extract_assets.sh`
 
 **BLPLoader** - Texture parser
 - BLP format (Blizzard texture format)
@@ -385,7 +388,7 @@ Window::swapBuffers()
 ```
 World::loadMap(mapId)
     ↓
-MPQManager::readFile("World/Maps/{map}/map.adt")
+AssetManager::readFile("World/Maps/{map}/map.adt")
     ↓
 ADTLoader::load(adtData)
     ├─ Parse MCNK chunks (terrain)
@@ -394,7 +397,7 @@ ADTLoader::load(adtData)
     └─ Parse MCNR chunks (normals)
     ↓
 For each texture reference:
-    MPQManager::readFile(texturePath)
+    AssetManager::readFile(texturePath)
     ↓
     BLPLoader::load(blpData)
     ↓

docs/quickstart.md

@@ -9,9 +9,11 @@ Implemented today:
 - SRP6a authentication + world connection
 - Character creation/selection and in-world entry
 - Full 3D rendering pipeline (terrain, water, sky, M2/WMO, particles)
-- Core gameplay systems (movement, combat, spells, inventory, quests, vendors, loot, chat)
+- Core gameplay plumbing (movement, combat/spell casting, inventory/equipment, chat)
 - Transport support (boats/zeppelins) with active ongoing fixes
 
+For a more honest snapshot of gaps and current direction, see `docs/status.md`.
+
 ## Build And Run
 
 ### 1. Clone
@@ -34,9 +36,22 @@ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
 cmake --build build -j"$(nproc)"
 ```
 
-### 4. Provide WoW Data
+### 4. Provide WoW Data (Extract + Manifest)
 
-Put your legal WoW 3.3.5a data in `Data/` (or set `WOW_DATA_PATH`).
+Wowee loads assets from an extracted loose-file tree indexed by `manifest.json`.
+
+If you do not already have an extracted `Data/manifest.json`, extract from your WoW install:
+
+```bash
+# WotLK 3.3.5a example
+./extract_assets.sh /path/to/WoW/Data wotlk
+```
+
+By default wowee uses `./Data/`. To override:
+
+```bash
+export WOW_DATA_PATH=/path/to/extracted/Data
+```
 
 ### 5. Run
 
@@ -80,5 +95,5 @@ Use `BUILD_INSTRUCTIONS.md` for distro-specific package lists.
 
 ### Missing assets (models/textures/terrain)
 
-- Verify WoW data files exist under `Data/`
+- Verify `Data/manifest.json` exists (or re-run `./extract_assets.sh ...`)
-- Or export `WOW_DATA_PATH=/path/to/WoW/Data`
+- Or export `WOW_DATA_PATH=/path/to/extracted/Data`

docs/server-setup.md

@@ -374,38 +374,39 @@ UPDATE realmlist SET address='your.server.ip' WHERE id=1;
 
 ## WoW Data Files
 
-The client needs access to WoW 3.3.5a data files for terrain, models, and textures.
+The client needs access to extracted WoW data (terrain, models, textures) indexed by `manifest.json`.
+
+If you have a fresh WoW install (MPQs only), extract once with:
+
+```bash
+./extract_assets.sh /path/to/WoW-3.3.5a/Data wotlk
+```
 
 ### Setting WOW_DATA_PATH
 
 ```bash
 # Linux/Mac
-export WOW_DATA_PATH="/path/to/WoW-3.3.5a/Data"
+export WOW_DATA_PATH="/path/to/extracted/Data"
 
 # Or add to ~/.bashrc
-echo 'export WOW_DATA_PATH="/path/to/WoW-3.3.5a/Data"' >> ~/.bashrc
+echo 'export WOW_DATA_PATH="/path/to/extracted/Data"' >> ~/.bashrc
 source ~/.bashrc
 
 # Run client
-cd /home/k/Desktop/wowee/wowee
+cd /path/to/wowee
 ./build/bin/wowee
 ```
 
 ### Data Directory Structure
 
-Your WoW Data directory should contain:
+Your extracted data directory should contain (example):
 ```
 Data/
-├── common.MPQ
+├── manifest.json
-├── common-2.MPQ
+├── interface/
-├── expansion.MPQ
+├── sound/
-├── lichking.MPQ
+├── world/
-├── patch.MPQ
+└── expansions/
-├── patch-2.MPQ
-├── patch-3.MPQ
-└── enUS/  (or your locale)
-    ├── locale-enUS.MPQ
-    └── patch-enUS-3.MPQ
 ```
 
 ## Testing Features
@@ -567,8 +568,8 @@ account set gmlevel demo 3 -1
 
 3. **Start Client:**
 ```bash
-cd /home/k/Desktop/wowee/wowee
+cd /path/to/wowee
-export WOW_DATA_PATH="/path/to/WoW-3.3.5a/Data"
+export WOW_DATA_PATH="/path/to/extracted/Data"
 ./build/bin/wowee
 ```
 

docs/status.md

@@ -0,0 +1,37 @@
+# Project Status
+
+**Last updated**: 2026-02-15
+
+## What This Repo Is
+
+Wowee is a native C++ World of Warcraft client experiment focused on connecting to real emulator servers (online/multiplayer) with a custom renderer and asset pipeline.
+
+## Current Code State
+
+Implemented (working in normal development use):
+
+- Auth flow: SRP6a auth + realm list + world connect with header encryption
+- Rendering: terrain, WMO/M2 rendering, water, sky system, particles, minimap/world map, loading video playback
+- Core gameplay plumbing: movement, targeting, action bar basics, inventory/equipment visuals, chat (tabs/channels, emotes, item links)
+- Multi-expansion direction: Classic/TBC/WotLK protocol variance handling exists and is being extended (`src/game/packet_parsers_classic.cpp`, `src/game/packet_parsers_tbc.cpp`)
+
+In progress / incomplete (known gaps):
+
+- Quests: some quest UI/markers exist, but parts of quest log parsing are still TODOs
+- Transports: functional support exists, but some spline parsing/edge cases are still TODOs
+- Audio: broad coverage for events/music/UI exists, but 3D positional audio is not implemented yet
+- Warden: crypto + module plumbing are in place; full module execution and server-specific compatibility are still in progress
+
+## Near-Term Direction
+
+- Keep tightening packet parsing across server variants (especially Classic/Turtle and TBC)
+- Keep improving visual correctness for characters/equipment and M2/WMO edge cases
+- Progress Warden module execution path (emulation via Unicorn when available)
+
+## Where To Look
+
+- Entry point: `src/main.cpp`, `src/core/application.cpp`
+- Networking/auth: `src/auth/`, `src/network/`, `src/game/game_handler.cpp`
+- Rendering: `src/rendering/`
+- Assets/extraction: `extract_assets.sh`, `tools/asset_extract/`, `src/pipeline/asset_manager.cpp`
+

src/rendering/sky_system.cpp

@@ -178,8 +178,7 @@ float SkySystem::getWhiteLadyPhase() const {
 }
 
 float SkySystem::getBlueChildPhase() const {
-    // TODO: Second moon support
+    return celestial_ ? celestial_->getBlueChildPhase() : 0.25f;
-    return 0.25f;  // Placeholder phase
 }
 
 } // namespace rendering