# Getting Started with WoWee

WoWee is a native C++ World of Warcraft client that connects to private servers. This guide walks you through setting up and playing WoWee.

## Prerequisites

- **World of Warcraft Game Data** (Vanilla 1.12, TBC 2.4.3, or WotLK 3.3.5a)
- **A Private Server** (AzerothCore, TrinityCore, Mangos, or Turtle WoW compatible)
- **System Requirements**: Linux, macOS, or Windows with a Vulkan-capable GPU

## Installation

### Step 1: Build WoWee

See [Building](README.md#building) section in README for detailed build instructions.

**Quick start (Linux/macOS)**:
```bash
./build.sh
cd build/bin
./wowee
```

**Quick start (Windows)**:
```powershell
.\build.ps1
cd build\bin
.\wowee.exe
```

### Step 2: Extract Game Data

WoWee needs game assets from your WoW installation:

**Using provided script (Linux/macOS)**:
```bash
./extract_assets.sh /path/to/wow/directory
```

**Using provided script (Windows)**:
```powershell
.\extract_assets.ps1 -WowDirectory "C:\Program Files\World of Warcraft"
```

**Manual extraction**:
1. Install [StormLib](https://github.com/ladislav-zezula/StormLib)
2. Extract to `./Data/`:
   ```
   Data/
   ├── dbc/           # DBC files
   ├── map/           # World map data
   ├── adt/           # Terrain chunks
   ├── wmo/           # Building models
   ├── m2/            # Character/creature models
   └── blp/           # Textures
   ```

### Step 3: Connect to a Server

1. **Start WoWee**
   ```bash
   cd build/bin && ./wowee
   ```

2. **Enter Realm Information**
   - Server Address: e.g., `localhost:3724` or `play.example.com:3724`
   - WoWee fetches the realm list automatically
   - Select your realm and click **Connect**

3. **Choose Character**
   - Select existing character or create new one
   - Customize appearance and settings
   - Click **Enter World**

## First Steps in Game

### Default Controls

| Action | Key |
|--------|-----|
| Move Forward | W |
| Move Backward | S |
| Strafe Left | A |
| Strafe Right | D |
| Jump | Space |
| Toggle Chat | Enter |
| Interact (talk to NPC, loot) | F |
| Open Inventory | B |
| Open Spellbook | P |
| Open Talent Tree | T |
| Open Quest Log | Q |
| Open World Map | W (when not typing) |
| Toggle Minimap | M |
| Toggle Nameplates | V |
| Toggle Party Frames | F |
| Toggle Settings | Escape |
| Target Next Enemy | Tab |
| Target Previous Enemy | Shift+Tab |

### Customizing Controls

Press **Escape** → **Keybindings** to customize hotkeys.

## Recommended First Steps

### 1. Adjust Graphics Settings
- Press Escape → **Video Settings**
- Select appropriate **Graphics Preset** for your GPU:
  - **LOW**: Low-end GPUs or when performance is priority
  - **MEDIUM**: Balanced quality and performance
  - **HIGH**: Good GPU with modern drivers
  - **ULTRA**: High-end GPU for maximum quality

### 2. Adjust Audio
- Press Escape → **Audio Settings**
- Set **Master Volume** to preferred level
- Adjust individual audio tracks (Music, Ambient, UI, etc.)
- Toggle **Original Soundtrack** if available

### 3. Configure UI
- Press Escape → **Game Settings**
- Minimap preferences (rotation, square mode, zoom)
- Bag settings (separate windows, compact mode)
- Action bar visibility

### 4. Complete First Quest
- Talk to nearby NPCs (they have quest markers ! or ?)
- Accept quest, complete objectives, return for reward
- Level up and gain experience

## Important Notes

### Data Directory
Game data is loaded from `Data/` subdirectory:
- If running from build folder: `../../Data` (symlinked automatically)
- If running from binary folder: `./Data` (must exist)
- If running in-place: Ensure `Data/` is in correct location

### Settings
- Settings are saved to `~/.wowee/settings.cfg` (Linux/macOS)
- Or `%APPDATA%\wowee\settings.cfg` (Windows)
- Keybindings, graphics settings, and UI state persist

### Multi-Expansion Support
WoWee auto-detects expansion from server:
- **Vanilla 1.12** - Original game
- **TBC 2.4.3** - Burning Crusade
- **WotLK 3.3.5a** - Wrath of the Lich King

You can override with environment variable:
```bash
WOWEE_EXPANSION=tbc ./wowee    # Force TBC
```

## Troubleshooting

### "No realm list" or "Connection Failed"
- Check server address is correct
- Verify server is running
- See [Troubleshooting Guide](TROUBLESHOOTING.md#connection-issues)

### Graphics Errors
- See [Graphics Troubleshooting](TROUBLESHOOTING.md#graphics-issues)
- Start with LOW graphics preset
- Update GPU driver

### Audio Not Working
- Check system audio is enabled
- Verify audio files are extracted
- See [Audio Troubleshooting](TROUBLESHOOTING.md#audio-issues)

### General Issues
- Comprehensive troubleshooting: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
- Check logs in `~/.wowee/logs/` for errors
- Verify expansion matches server requirements

## Server Configuration

### Tested Servers
- **AzerothCore** - Full support, recommended for learning
- **TrinityCore** - Full support, extensive customization
- **Mangos** - Full support, solid foundation
- **Turtle WoW** - Full support, 1.17 custom content

### Server Requirements
- Must support Vanilla, TBC, or WotLK protocol
- Warden anti-cheat supported (module execution via emulation)
- Network must allow connections to realm list and world server ports

See [Multi-Expansion Guide](EXPANSION_GUIDE.md) for protocol details.

## Next Steps

1. **Explore the World** - Travel to different zones and enjoy the landscape
2. **Join a Guild** - Find other players to group with
3. **Run Dungeons** - Experience instanced content
4. **PvP** - Engage in player-versus-player combat
5. **Twink Alt** - Create additional characters
6. **Customize Settings** - Fine-tune graphics, audio, and UI

## Getting Help

- **Game Issues**: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
- **Graphics Help**: See [Graphics & Performance](README.md#graphics--performance) section
- **Multi-Expansion**: See [EXPANSION_GUIDE.md](EXPANSION_GUIDE.md)
- **Building Issues**: See [README.md](README.md#building)

## Tips for Better Performance

- Start with reasonable graphics preset for your GPU
- Close other applications when testing
- Keep GPU drivers updated
- Use FSR2 (if supported) for smooth 60+ FPS on weaker hardware
- Monitor frame rate with debug overlay (if available)

## Enjoy!

WoWee is a project to experience classic World of Warcraft on a modern engine. Have fun exploring Azeroth!