Kelsidavis-WoWee/docs/architecture.md

Architecture Overview

System Design

Wowee follows a modular architecture with clear separation of concerns:

┌─────────────────────────────────────────────┐
│           Application (main loop)            │
│  - State management (auth/realms/game)      │
│  - Update cycle                             │
│  - Event dispatch                           │
└──────────────┬──────────────────────────────┘
               │
       ┌───────┴────────┐
       │                │
┌──────▼──────┐  ┌─────▼──────┐
│   Window    │  │   Input    │
│  (SDL2 +    │  │ (Keyboard/ │
│   Vulkan)   │  │   Mouse)   │
└──────┬──────┘  └─────┬──────┘
       │                │
       └───────┬────────┘
               │
    ┌──────────┴──────────┐
    │                     │
┌───▼────────┐   ┌───────▼──────┐
│  Renderer  │   │  UI Manager  │
│  (Vulkan)  │   │   (ImGui)    │
└───┬────────┘   └──────────────┘
    │
    ├─ Camera + CameraController
    ├─ TerrainRenderer (ADT streaming)
    ├─ WMORenderer (buildings, collision)
    ├─ M2Renderer (models, particles, ribbons)
    ├─ CharacterRenderer (skeletal animation)
    ├─ WaterRenderer (refraction, lava, slime)
    ├─ SkyBox + StarField + Weather
    ├─ LightingManager (Light.dbc volumes)
    └─ SwimEffects, ChargeEffect, Lightning

Core Systems

1. Application Layer (src/core/)

Application (application.hpp/cpp) - Main controller

• Owns all subsystems (renderer, game handler, asset manager, UI)
• Manages application state (AUTH → REALM_SELECT → CHAR_SELECT → IN_WORLD)
• Runs update/render loop
• Populates GameServices struct and passes to GameHandler at construction

Window (window.hpp/cpp) - SDL2 + Vulkan wrapper

• Creates SDL2 window with Vulkan surface
• Owns VkContext (Vulkan device, swapchain, render passes)
• Handles resize events

Input (input.hpp/cpp) - Input management

• Keyboard state tracking (SDL scancodes)
• Mouse position, buttons (1-based SDL indices), wheel delta
• Per-frame delta calculation

Logger (logger.hpp/cpp) - Thread-safe logging

• Multiple log levels (DEBUG, INFO, WARNING, ERROR, FATAL)
• File output to logs/wowee.log
• Configurable via WOWEE_LOG_LEVEL env var

2. Rendering System (src/rendering/)

Renderer (renderer.hpp/cpp) - Main rendering coordinator

• Manages Vulkan pipeline state
• Coordinates frame rendering across all sub-renderers
• Owns camera, sky, weather, lighting, and all sub-renderers
• Shadow mapping with PCF filtering

VkContext (vk_context.hpp/cpp) - Vulkan infrastructure

• Device selection, queue families, swapchain
• Render passes, framebuffers, command pools
• Sampler cache (FNV-1a hashed dedup)
• Pipeline cache persistence for fast startup

Camera (camera.hpp/cpp) - View/projection matrices

• Position and orientation
• FOV, aspect ratio, near/far planes
• Sub-pixel jitter for TAA/FSR2 (column 2 NDC offset)
• Frustum extraction for culling

TerrainRenderer - ADT terrain streaming

• Async chunk loading within configurable radius
• 4-layer texture splatting with alpha blending
• Frustum + distance culling
• Vegetation/foliage placement via deterministic RNG

WMORenderer - World Map Objects (buildings)

• Multi-material batch rendering
• Portal-based visibility culling
• Floor/wall collision (normal-based classification)
• Interior glass transparency, doodad placement

M2Renderer - Models (creatures, doodads, spell effects)

• Skeletal animation with GPU bone transforms
• Particle emitters (WotLK FBlock format)
• Ribbon emitters (charge trails, enchant glows)
• Portal spin effects, foliage wind displacement
• Per-instance animation state

CharacterRenderer - Player/NPC character models

• GPU vertex skinning (256 bones)
• Race/gender-aware textures via CharSections.dbc
• Equipment rendering (geoset visibility per slot)
• Fallback textures (white/transparent/flat-normal) for missing assets

WaterRenderer - Terrain and WMO water

• Refraction/reflection rendering
• Magma/slime with multi-octave FBM noise flow
• Beer-Lambert absorption

Skybox + StarField + Weather

• Procedural sky dome with time-of-day lighting
• Star field with day/night fade (dusk 18:00–20:00, dawn 04:00–06:00)
• Rain/snow particle systems per zone (via zone weather table)

LightingManager - Light.dbc volume sampling

• Time-of-day color bands (half-minutes, 0–2879)
• Distance-weighted light volume blending
• Fog color/distance parameters

3. Networking (src/network/)

TCPSocket (tcp_socket.hpp/cpp) - Platform TCP

• Non-blocking I/O with per-frame recv budgets
• 4 KB recv buffer per call
• Portable across Linux/macOS/Windows

WorldSocket (world_socket.hpp/cpp) - WoW world connection

• RC4 header encryption (derived from SRP session key)
• Packet parsing with configurable per-frame budgets
• Compressed move packet handling

Packet (packet.hpp/cpp) - Binary data container

• Read/write primitives (uint8–uint64, float, string, packed GUID)
• Bounds-checked reads (return 0 past end)

4. Authentication (src/auth/)

AuthHandler - Auth server protocol (port 3724)

• SRP6a challenge/proof flow
• Security flags: PIN (0x01), Matrix (0x02), Authenticator (0x04)
• Realm list retrieval

SRP (srp.hpp/cpp) - Secure Remote Password

• SRP6a with 19-byte (152-bit) ephemeral
• OpenSSL BIGNUM math
• Session key generation (40 bytes)

Integrity - Client integrity verification

• Checksum computation for Warden compatibility

5. Game Logic (src/game/)

GameHandler (game_handler.hpp/cpp) - Central game state

• Dispatch table routing 664+ opcodes to domain handlers
• Owns all domain handlers via composition
• Receives dependencies via GameServices struct (no singleton access)

Domain Handlers (SOLID decomposition from GameHandler):

• EntityController - UPDATE_OBJECT parsing, entity spawn/despawn
• MovementHandler - Movement packets, speed, taxi, swimming, flying
• CombatHandler - Damage, healing, death, auto-attack, threat
• SpellHandler - Spell casting, cooldowns, auras, talents, pet spells
• InventoryHandler - Equipment, bags, bank, mail, auction, vendors
• QuestHandler - Quest accept/complete, objectives, progress tracking
• SocialHandler - Party, guild, LFG, friends, who, duel, trade
• ChatHandler - Chat messages, channels, emotes, system messages
• WardenHandler - Anti-cheat module management

OpcodeTable - Expansion-agnostic opcode mapping

• LogicalOpcode enum → wire opcode via JSON config per expansion
• Runtime remapping for Classic/TBC/WotLK/Turtle protocol differences

Entity / EntityManager - Entity lifecycle

• Shared entity base class with update fields (uint32 array)
• Player, Unit, GameObject subtypes
• GUID-based lookup, field extraction (health, level, display ID, etc.)

TransportManager - Transport path evaluation

• Catmull-Rom spline interpolation from TransportAnimation.dbc
• Clock-based motion with server time synchronization
• Time-closed looping paths (wrap point duplicated, no index wrapping)

Expansion Helpers (game_utils.hpp):

• isActiveExpansion("classic") / isActiveExpansion("tbc") / isActiveExpansion("wotlk")
• isClassicLikeExpansion() (Classic or Turtle WoW)
• isPreWotlk() (Classic, Turtle, or TBC)

6. Asset Pipeline (src/pipeline/)

AssetManager - Runtime asset access

• Extracted loose-file tree indexed by Data/manifest.json
• Layered resolution via optional overlay manifests (multi-expansion dedup)
• File cache with configurable budget (256 MB min, 12 GB max)
• PNG override support (checks for .png before .blp)

asset_extract (tool) - MPQ extraction

• Uses StormLib to extract MPQs into Data/ and generate manifest.json
• Driven by extract_assets.sh / extract_assets.ps1

BLPLoader - Texture decompression

• DXT1/3/5 block compression (RGB565 color endpoints)
• Palette mode with 1/4/8-bit alpha
• Mipmap extraction

M2Loader - Model binary parsing

• Version-aware header (Classic v256 vs WotLK v264)
• Skeletal animation tracks (embedded vs external .anim files, flag 0x20)
• Compressed quaternions (int16 offset mapping)
• Particle emitters, ribbon emitters, attachment points
• Geoset support (group × 100 + variant encoding)

WMOLoader - World object parsing

• Multi-group rendering with portal visibility
• Doodad placement (24-bit name index + 8-bit flags packing)
• Liquid data, collision geometry

ADTLoader - Terrain parsing

• 64×64 tiles per map, 16×16 chunks per tile (MCNK)
• MCVT height grid (145 vertices: 9 outer + 8 inner per row × 9 rows)
• Texture layers (up to 4 with alpha blending, RLE-compressed alpha maps)
• Async loading to prevent frame stalls

DBCLoader - Database table parsing

• Binary DBC format (fixed 4-byte uint32 fields + string block)
• CSV fallback for pre-extracted data
• Expansion-aware field layout via dbc_layouts.json
• 20+ DBC files: Spell, Item, Creature, Faction, Map, AreaTable, etc.

7. UI System (src/ui/)

UIManager - ImGui coordinator

• ImGui initialization with SDL2/Vulkan backend
• Screen state management and transitions
• Event handling and input routing

Screens:

• AuthScreen - Login with username/password, server address, security code
• RealmScreen - Realm list with population and type indicators
• CharacterScreen - Character selection with 3D animated preview
• CharacterCreateScreen - Race/class/gender/appearance customization
• GameScreen - Main HUD: chat, action bar, target frame, minimap, nameplates, combat text, tooltips
• InventoryScreen - Equipment paper doll, backpack, bag windows, item tooltips with stats
• SpellbookScreen - Tabbed spell list with icons, drag-drop to action bar
• QuestLogScreen - Quest list with objectives, details, and rewards
• TalentScreen - Talent tree UI with point allocation
• SettingsScreen - Graphics presets (LOW/MEDIUM/HIGH/ULTRA), audio, keybindings

8. Audio System (src/audio/)

AudioEngine - miniaudio-based playback

• WAV decode cache (256 entries, LRU eviction)
• 2D and 3D positional audio
• Sample rate preservation (explicit to avoid miniaudio pitch distortion)

Sound Managers:

• AmbientSoundManager - Wind, water, fire, birds, crickets, city ambience, bell tolls
• ActivitySoundManager - Swimming strokes, jumping, landing
• MovementSoundManager - Footsteps (terrain-aware), mount movement
• MountSoundManager - Mount-specific movement audio
• MusicManager - Zone music with day/night variants

9. Warden Anti-Cheat (src/game/)

4-layer architecture:

• WardenHandler - Packet handling (SMSG/CMSG_WARDEN_DATA)
• WardenModuleManager - Module lifecycle and caching
• WardenModule - 8-step pipeline: decrypt (RC4), strip RSA-2048 signature, decompress (zlib), parse PE headers, relocate, resolve imports, execute
• WardenEmulator - Unicorn Engine x86 CPU emulation with Windows API interception
• WardenMemory - PE image loading with bounds-checked reads, runtime global patching

Threading Model

• Main thread: Window events, game logic update, rendering
• Async terrain: Non-blocking chunk loading (std::async)
• Network I/O: Non-blocking recv in main thread with per-frame budgets
• Normal maps: Background CPU generation with mutex-protected result queue
• GPU uploads: Second Vulkan queue for parallel texture/buffer transfers

Memory Management

• Smart pointers: std::unique_ptr / std::shared_ptr throughout
• RAII: All Vulkan resources wrapped with proper destructors
• VMA: Vulkan Memory Allocator for GPU memory
• Object pooling: Weather particles, combat text entries
• DBC caching: Lazy-loaded mutable caches in const getters

Build System

CMake with modular targets:

• wowee - Main executable
• asset_extract - MPQ extraction tool (requires StormLib)
• dbc_to_csv / auth_probe / blp_convert - Utility tools

Dependencies:

• SDL2, Vulkan SDK, OpenSSL, GLM, zlib (system)
• ImGui (submodule in extern/)
• VMA, vk-bootstrap, stb_image (vendored in extern/)
• StormLib (system, optional — only for asset_extract)
• Unicorn Engine (system, optional — only for Warden emulation)
• FFmpeg (system, optional — for video playback)

CI: GitHub Actions for Linux (x86-64, ARM64), Windows (MSYS2), macOS (ARM64) Container builds: Docker cross-compilation for Linux, macOS (osxcross), Windows (LLVM-MinGW)

Code Style

• C++20 standard
• Namespaces: wowee::core, wowee::rendering, wowee::game, wowee::ui, wowee::network, wowee::auth, wowee::audio, wowee::pipeline
• Naming: PascalCase for classes, camelCase for functions/variables, kPascalCase for constants
• Headers: .hpp extension, #pragma once
• Commits: Conventional style (feat:, fix:, refactor:, docs:, perf:)