WoWee/docs/quickstart.md

Quick Start Guide

Current Status

Wowee is a fully functional native C++ World of Warcraft 3.3.5a client! The application includes:

✅ Complete SRP6a authentication system ✅ Character creation and selection ✅ Full 3D rendering engine (terrain, water, sky, characters, buildings, particles) ✅ Online multiplayer gameplay (movement, combat, spells, inventory, quests) ✅ Offline single-player mode ✅ Comprehensive UI system (action bar, spellbook, inventory, quest log, chat) ✅ Asset pipeline for all WoW formats (MPQ, BLP, M2, ADT, WMO, DBC)

Quick Start

Prerequisites

Ensure you have all dependencies installed (see main README.md for details).

Build & Run

# Clone the repository
git clone https://github.com/yourname/wowee.git
cd wowee

# Get ImGui (required)
git clone https://github.com/ocornut/imgui.git extern/imgui

# Set up game data (see "Game Data" section in README.md)
# Either symlink Data/ directory or set WOW_DATA_PATH environment variable

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

# Run
./bin/wowee

What Works Right Now

Authentication & Character Selection

• Login with username and password
• Realm selection with population info
• Character list with 3D preview
• Character creation (all races and classes)
• Enter world seamlessly

In-Game Gameplay

• Movement: WASD movement with camera orbit
• Combat: Auto-attack, spell casting, damage calculation
• Targeting: Click-to-target, tab-cycling, faction-based hostility
• Inventory: Full equipment and backpack system with drag-drop
• Spells: Spellbook organized by class specialties, drag-drop to action bar
• Quests: Quest markers on NPCs and minimap, quest log, quest details, turn-in
• Vendors: Buy and sell items with gold tracking
• Loot: Loot window for items and gold
• Chat: Send and receive chat messages (SAY, YELL, WHISPER)
• NPCs: Gossip interactions, animations

Rendering

• Multi-tile terrain streaming with async loading
• Animated water with reflections and refractions
• Dynamic day/night cycle with sun and moon
• Procedural star field (1000+ stars)
• Volumetric clouds with FBM noise
• Weather effects (rain and snow)
• Skeletal character animations (256 bones, GPU skinning)
• Building rendering (WMO) with frustum culling
• M2 particle emitters
• Post-processing (HDR, tonemapping, shadow mapping)

Single-Player Mode

• Play offline without a server connection
• Local character persistence
• Simulated combat and XP
• Settings persistence

Common Tasks

Connecting to a Server

1. Launch wowee: ./bin/wowee
2. Enter your username and password
3. Enter the auth server address (default: localhost)
4. Click "Login"
5. Select your realm from the list
6. Select or create a character
7. Click "Enter World"

Single-Player Mode

1. Launch wowee
2. Click "Single Player" on the auth screen
3. Create or select a character
4. Play offline without a server connection

Playing the Game

Movement:

• WASD to move
• Mouse to look around / orbit camera
• Shift for sprint

Combat:

• Left-click to target enemies
• Tab to cycle targets
• 1-9, 0, -, = to use action bar abilities
• Drag spells from spellbook (P) to action bar

Inventory:

• Press I to open inventory
• Drag items to equipment slots to equip
• Drag items to vendors to sell
• Drag items to action bar to use

Quests:

• Click NPCs with ! marker to get quests
• Press L to view quest log
• Click NPCs with ? marker to turn in quests
• Quest markers appear on minimap

Chat:

• Press Enter to open chat
• Type message and press Enter to send
• Chat commands: /say, /yell, /whisper [name]

Development & Debugging

Performance Monitoring:

• Press F1 to toggle performance HUD
• Shows FPS, draw calls, triangle count, GPU usage

Rendering Debug:

• F2: Toggle wireframe mode
• F9: Toggle time progression
• F10: Toggle sun/moon
• F11: Toggle stars
• +/-: Manual time control
• C: Toggle clouds
• L: Toggle lens flare
• W: Cycle weather

Settings:

• Settings window available in-game
• Adjust UI opacity
• Configure graphics options

Advanced Configuration

Environment Variables:

# Set custom WoW data path
export WOW_DATA_PATH="/path/to/WoW-3.3.5a/Data"

# Run with custom data path
WOW_DATA_PATH="/path/to/data" ./bin/wowee

Server Configuration: Edit auth server address in the login screen or configure default in Application settings.

Troubleshooting

Connection Issues

Problem: Cannot connect to authentication server

• Check that the auth server is running and reachable
• Verify the server address and port (default: 3724)
• Check firewall settings

Problem: Disconnected during gameplay

• Network timeout or unstable connection
• Check server logs for errors
• Application will return to authentication screen

Rendering Issues

Problem: Low FPS or stuttering

• Press F1 to check performance stats
• Reduce graphics settings in settings window
• Check GPU driver version

Problem: Missing textures or models

• Verify all WoW 3.3.5a MPQ files are present in Data/ directory
• Check that Data/ path is correct (or WOW_DATA_PATH is set)
• Look for errors in console output

Problem: Terrain not loading

• Async terrain streaming may take a moment
• Check for MPQ read errors in console
• Verify ADT files exist for the current map

Gameplay Issues

Problem: Cannot interact with NPCs

• Ensure you're within interaction range (5-10 yards)
• Check that NPC is not in combat
• Left-click to target NPC first

Problem: Spells not working

• Check that you have enough mana/rage/energy
• Verify spell is on cooldown (check action bar)
• Ensure you have a valid target (for targeted spells)

Problem: Items not equipping

• Check that item is for your class
• Verify you meet level requirements
• Ensure equipment slot is not already occupied (or drag to replace)

Performance Notes

Default configuration:

• VSync: Enabled (60 FPS cap)
• Resolution: 1920x1080 (configurable in Application settings)
• OpenGL: 3.3 Core Profile
• Shadow Map: 2048x2048 resolution
• Particles: 2000 max (weather), emitter-dependent (M2)

Optimization tips:

• Frustum culling automatically enabled
• Terrain streaming loads chunks as needed
• WMO distance culling at 160 units
• Async terrain loading prevents frame stalls

Useful Resources

• WoWDev Wiki: https://wowdev.wiki/ - File formats and protocol documentation
• TrinityCore: https://github.com/TrinityCore/TrinityCore - Server reference implementation
• MaNGOS: https://github.com/cmangos/mangos-wotlk - Alternative server reference
• StormLib: https://github.com/ladislav-zezula/StormLib - MPQ library documentation
• ImGui: https://github.com/ocornut/imgui - UI framework

Known Issues

• Stormwind Mage Quarter: Water overflows near Moonwell area (geometry constraint issue)
• Particle emitters: Some complex emitters may have minor visual glitches
• Hair textures: Occasional texture resolution on some race/gender combinations

See GitHub issues for full list and tracking.

Getting Help

1. Check console output for error messages (use LOG_DEBUG builds for verbose output)
2. Consult WoWDev Wiki for protocol and format specifications
3. Review Architecture documentation for system design
4. Report bugs on GitHub issue tracker

---

Enjoy playing WoW with a native C++ client! 🎮