From 2b8bb76d7ae3d45267b86cc3bc41343fa43cc580 Mon Sep 17 00:00:00 2001
From: Kelsi <kelsihates2fa@gmail.com>
Date: Wed, 11 Mar 2026 15:35:23 -0700
Subject: [PATCH] docs: add comprehensive multi-expansion architecture guide

---
 EXPANSION_GUIDE.md | 126 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 EXPANSION_GUIDE.md

diff --git a/EXPANSION_GUIDE.md b/EXPANSION_GUIDE.md
new file mode 100644
index 00000000..6a2dc26e
--- /dev/null
+++ b/EXPANSION_GUIDE.md
@@ -0,0 +1,126 @@
+# 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
+
+## 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 message parsing
+   - `packet_parsers_tbc.cpp` - TBC 2.4.3 message parsing
+   - `packet_parsers_wotlk.cpp` (default) - WotLK 3.3.5a message parsing
+
+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:
+```bash
+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
+
+```cpp
+#include "game/expansion_profile.hpp"
+
+// Global helper
+bool isClassicLikeExpansion() {
+    auto profile = ExpansionProfile::getActive();
+    return profile && (profile->name == "Classic" || profile->name == "Vanilla");
+}
+
+// Specific check
+if (GameHandler::getInstance().isActiveExpansion("tbc")) {
+    // TBC-specific code
+}
+```
+
+### Expansion-Specific Packet Parsing
+
+```cpp
+// In packet_parsers_*.cpp, implement expansion-specific logic
+bool parseXxxPacket(BitStream& 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
+- `docs/status.md` - Current feature support by expansion
+- `src/game/packet_parsers_*.cpp` - Format-specific parsing logic
+- `docs/` directory - Additional protocol documentation