Skip to content

EXPANSION_GUIDE.md

Latest commit

 

History

History
130 lines (94 loc) · 4.04 KB

EXPANSION_GUIDE.md

File metadata and controls

130 lines (94 loc) · 4.04 KB

Multi-Expansion Architecture Guide

WoWee supports three World of Warcraft expansions in a unified codebase using an expansion profile system. This guide explains how the multi-expansion support works.

Supported Expansions

  • Vanilla (Classic) 1.12 - Original World of Warcraft
  • The Burning Crusade (TBC) 2.4.3 - First expansion
  • Wrath of the Lich King (WotLK) 3.3.5a - Second expansion
  • Turtle WoW 1.17 - Custom Vanilla-based server with extended content

Architecture Overview

The multi-expansion support is built on the Expansion Profile system:

  1. ExpansionProfile (include/game/expansion_profile.hpp) - Metadata about each expansion

    • Defines protocol version, data paths, asset locations
    • Specifies which packet parsers to use

  2. Packet Parsers - Expansion-specific message handling

    • packet_parsers_classic.cpp - Vanilla 1.12 / Turtle WoW message parsing
    • packet_parsers_tbc.cpp - TBC 2.4.3 message parsing
    • Default (WotLK 3.3.5a) parsers in game_handler.cpp and domain handlers

  3. Update Fields - Expansion-specific entity data layout

    • Loaded from update_fields.json in expansion data directory
    • Defines UNIT_END, OBJECT_END, field indices for stats/health/mana

How to Use Different Expansions

At Startup

WoWee auto-detects the expansion based on:

  1. Realm list response (protocol version)
  2. Server build number
  3. Update field count

Manual Selection

Set environment variable:

WOWEE_EXPANSION=tbc ./wowee    # Force TBC
WOWEE_EXPANSION=classic ./wowee # Force Classic

Key Differences Between Expansions

Packet Format Differences

SMSG_SPELL_COOLDOWN

  • Classic: 12 bytes per entry (spellId + itemId + cooldown, no flags)
  • TBC/WotLK: 8 bytes per entry (spellId + cooldown) + flags byte

SMSG_ACTION_BUTTONS

  • Classic: 120 slots, no mode byte
  • TBC: 132 slots, no mode byte
  • WotLK: 144 slots + uint8 mode byte

SMSG_PARTY_MEMBER_STATS

  • Classic/TBC: Full uint64 for guid, uint16 health
  • WotLK: PackedGuid format, uint32 health

Data Differences

  • Talent trees: Different spell IDs and tree structure per expansion
  • Items: Different ItemDisplayInfo entries
  • Spells: Different base stats, cooldowns
  • Character textures: Expansion-specific variants for races

Adding Support for Another Expansion

  1. Create new expansion profile entry in expansion_profile.cpp
  2. Add packet parser file (packet_parsers_*.cpp) for message variants
  3. Create update_fields.json with correct field layout
  4. Test realm connection and character loading

Code Patterns

Checking Current Expansion

#include "game/game_utils.hpp"

// Shared helpers (defined in game_utils.hpp)
if (isActiveExpansion("tbc")) {
    // TBC-specific code
}

if (isClassicLikeExpansion()) {
    // Classic or Turtle WoW
}

if (isPreWotlk()) {
    // Classic, Turtle, or TBC (not WotLK)
}

Expansion-Specific Packet Parsing

// In packet_parsers_*.cpp, implement expansion-specific logic
bool TbcPacketParsers::parseXxx(network::Packet& packet, XxxData& data) {
    // Custom logic for this expansion's packet format
}

Common Issues

"Update fields mismatch" Error

  • Ensure update_fields.json matches server's field layout
  • Check OBJECT_END and UNIT_END values
  • Verify field indices for your target expansion

"Unknown packet" Warnings

  • Expansion-specific opcodes may not be registered
  • Check packet parser registration in game_handler.cpp
  • Verify expansion profile is active

Packet Parsing Failures

  • Each expansion has different struct layouts
  • Always read data size first, then upfront validate
  • Use size capping (e.g., max 100 items in list)

References

  • include/game/expansion_profile.hpp - Expansion metadata
  • include/game/game_utils.hpp - isActiveExpansion(), isClassicLikeExpansion(), isPreWotlk()
  • src/game/packet_parsers_classic.cpp / packet_parsers_tbc.cpp - Expansion-specific parsing
  • docs/status.md - Current feature support
  • docs/ directory - Additional protocol documentation