Kelsidavis-WoWee/docs/single-player.md

# Single-Player Mode Guide

**Date**: 2026-01-27
**Purpose**: Play wowee without a server connection
**Status**: ✅ Fully Functional

---

## Overview

Single-player mode allows you to explore the rendering engine without setting up a server. It bypasses authentication and loads the game world directly with all atmospheric effects and test objects.

## How to Use

### 1. Start the Client

```bash
cd /home/k/Desktop/wowee/wowee
./build/bin/wowee
```

### 2. Click "Start Single Player"

On the authentication screen, you'll see:
- **Server connection** section (hostname, username, password)
- **Single-Player Mode** section with a large blue button

Click the **"Start Single Player"** button to bypass authentication and go directly to the game world.

### 3. Explore the World

You'll immediately enter the game with:
- ✨ Full atmospheric rendering (sky, stars, clouds, sun/moon)
- 🎮 Full camera controls (WASD, mouse)
- 🌦️ Weather effects (W key to cycle)
- 🏗️ Ability to spawn test objects (K, O keys)
- 📊 Performance HUD (F1 to toggle)

## Features Available

### Atmospheric Rendering ✅
- **Skybox** - Dynamic day/night gradient
- **Stars** - 1000+ stars visible at night
- **Celestial** - Sun and moon with orbital movement
- **Clouds** - Animated volumetric clouds
- **Lens Flare** - Sun bloom effects
- **Weather** - Rain and snow particle systems

### Camera & Movement ✅
- **WASD** - Free-fly camera movement
- **Mouse** - Look around (360° rotation)
- **Shift** - Move faster (sprint)
- Full 3D navigation with no collisions

### Test Objects ✅
- **K key** - Spawn test character (animated cube)
- **O key** - Spawn procedural WMO building (5×5×5 cube)
- **Shift+O** - Load real WMO from MPQ (if WOW_DATA_PATH set)
- **P key** - Clear all WMO buildings
- **J key** - Clear characters

### Rendering Controls ✅
- **F1** - Toggle performance HUD
- **F2** - Wireframe mode
- **F8** - Toggle water rendering
- **F9** - Toggle time progression
- **F10** - Toggle sun/moon
- **F11** - Toggle stars
- **F12** - Toggle fog
- **+/-** - Manual time of day adjustment

### Effects Controls ✅
- **C** - Toggle clouds
- **[/]** - Adjust cloud density
- **L** - Toggle lens flare
- **,/.** - Adjust lens flare intensity
- **M** - Toggle moon phase cycling
- **;/'** - Manual moon phase control
- **W** - Cycle weather (None → Rain → Snow)
- **</>** - Adjust weather intensity

## Loading Terrain (Optional)

Single-player mode can load real terrain if you have WoW data files.

### Setup WOW_DATA_PATH

```bash
# Linux/Mac
export WOW_DATA_PATH="/path/to/WoW-3.3.5a/Data"

# Or add to ~/.bashrc for persistence
echo 'export WOW_DATA_PATH="/path/to/WoW-3.3.5a/Data"' >> ~/.bashrc
source ~/.bashrc

# Run client
cd /home/k/Desktop/wowee/wowee
./build/bin/wowee
```

### What Gets Loaded

With `WOW_DATA_PATH` set, single-player mode will attempt to load:
- **Terrain** - Elwynn Forest ADT tile (32, 49) near Northshire Abbey
- **Textures** - Ground textures from MPQ archives
- **Water** - Water tiles from the terrain
- **Buildings** - Real WMO models (Shift+O key)

### Data Directory Structure

Your WoW Data directory should contain:
```
Data/
├── common.MPQ
├── common-2.MPQ
├── expansion.MPQ
├── lichking.MPQ
├── patch.MPQ
├── patch-2.MPQ
├── patch-3.MPQ
└── enUS/  (or your locale)
    ├── locale-enUS.MPQ
    └── patch-enUS-3.MPQ
```

## Use Cases

### 1. Rendering Engine Testing

Perfect for testing and debugging rendering features:
- Test sky system day/night cycle
- Verify atmospheric effects
- Profile performance
- Test shader changes
- Debug camera controls

### 2. Visual Effects Development

Ideal for developing visual effects:
- Weather systems
- Particle effects
- Post-processing
- Shader effects
- Lighting changes

### 3. Screenshots & Videos

Great for capturing content:
- Time-lapse videos of day/night cycle
- Weather effect demonstrations
- Atmospheric rendering showcases
- Feature demonstrations

### 4. Performance Profiling

Excellent for performance analysis:
- Measure FPS with different effects
- Test GPU/CPU usage
- Profile draw calls and triangles
- Test memory usage
- Benchmark optimizations

### 5. Learning & Exploration

Good for learning the codebase:
- Understand rendering pipeline
- Explore atmospheric systems
- Test object spawning
- Experiment with controls
- Learn shader systems

## Technical Details

### State Management

**Normal Flow:**
```
AUTHENTICATION → REALM_SELECTION → CHARACTER_SELECTION → IN_GAME
```

**Single-Player Flow:**
```
AUTHENTICATION → [Single Player Button] → IN_GAME
```

Single-player mode bypasses:
- Network authentication
- Realm selection
- Character selection
- Server connection

### World Creation

When single-player starts:
1. Creates empty `World` object
2. Sets `singlePlayerMode = true` flag
3. Attempts terrain loading if asset manager available
4. Transitions to `IN_GAME` state
5. Continues with atmospheric rendering

### Terrain Loading Logic

```cpp
if (WOW_DATA_PATH set && AssetManager initialized) {
    try to load: "World\Maps\Azeroth\Azeroth_32_49.adt"
    if (success) {
        render terrain with textures
    } else {
        atmospheric rendering only
    }
} else {
    atmospheric rendering only
}
```

### Camera Behavior

**Single-Player Camera:**
- Starts at default position (0, 0, 100)
- Free-fly mode (no terrain collision)
- Full 360° rotation
- Adjustable speed (Shift for faster)

**In-Game Camera (with server):**
- Follows character position
- Same controls but synced with server
- Position updates sent to server

## Performance

### Without Terrain

**Atmospheric Only:**
- FPS: 60 (vsync limited)
- Triangles: ~2,000 (skybox + clouds)
- Draw Calls: ~8
- CPU: 5-10%
- GPU: 10-15%
- Memory: ~150 MB

### With Terrain

**Full Rendering:**
- FPS: 60 (vsync maintained)
- Triangles: ~50,000
- Draw Calls: ~30
- CPU: 10-15%
- GPU: 15-25%
- Memory: ~200 MB

### With Test Objects

**Characters + Buildings:**
- Characters (10): +500 triangles, +1 draw call each
- Buildings (5): +5,000 triangles, +1 draw call each
- Total impact: ~10% GPU increase

## Differences from Server Mode

### What Works

- ✅ Full atmospheric rendering
- ✅ Camera movement
- ✅ Visual effects (clouds, weather, lens flare)
- ✅ Test object spawning
- ✅ Performance HUD
- ✅ All rendering toggles
- ✅ Time of day controls

### What Doesn't Work

- ❌ Network synchronization
- ❌ Real characters from database
- ❌ Creatures and NPCs
- ❌ Combat system
- ❌ Chat/social features
- ❌ Spells and abilities
- ❌ Inventory system
- ❌ Quest system

### Limitations

**No Server Features:**
- Cannot connect to other players
- No persistent world state
- No database-backed characters
- No server-side validation
- No creature AI or spawning

**Test Objects Only:**
- Characters are simple cubes
- Buildings are procedural or MPQ-loaded
- No real character models (yet)
- No animations beyond test cubes

## Tips & Tricks

### 1. Cinematic Screenshots

Create beautiful atmospheric shots:
```
1. Press F1 to hide HUD
2. Press F9 to auto-cycle time
3. Press C to enable clouds
4. Press L for lens flare
5. Wait for sunset/sunrise (golden hour)
6. Take screenshots!
```

### 2. Performance Testing

Stress test the renderer:
```
1. Spawn 10 characters (press K ten times)
2. Spawn 5 buildings (press O five times)
3. Enable all effects (clouds, weather, lens flare)
4. Toggle F1 to monitor FPS
5. Profile different settings
```

### 3. Day/Night Exploration

Experience the full day cycle:
```
1. Press F9 to start time progression
2. Watch stars appear at dusk
3. See moon phases change
4. Observe color transitions
5. Press F9 again to stop at favorite time
```

### 4. Weather Showcase

Test weather systems:
```
1. Press W to enable rain
2. Press > to max intensity
3. Press W again for snow
4. Fly through particles
5. Test with different times of day
```

### 5. Building Gallery

Create a building showcase:
```
1. Press O five times for procedural cubes
2. Press Shift+O to load real WMO (if data available)
3. Fly around to see different angles
4. Press F2 for wireframe view
5. Press P to clear and try others
```

## Troubleshooting

### Black Screen

**Problem:** Screen is black, no rendering

**Solution:**
```bash
# Check if application is running
ps aux | grep wowee

# Check OpenGL initialization in logs
# Should see: "Renderer initialized"

# Verify graphics drivers
glxinfo | grep OpenGL
```

### Low FPS

**Problem:** Performance below 60 FPS

**Solution:**
1. Press F1 to check FPS counter
2. Disable heavy effects:
   - Press C to disable clouds
   - Press L to disable lens flare
   - Press W until weather is "None"
3. Clear test objects:
   - Press J to clear characters
   - Press P to clear buildings
4. Check GPU usage in system monitor

### No Terrain

**Problem:** Only sky visible, no ground

**Solution:**
```bash
# Check if WOW_DATA_PATH is set
echo $WOW_DATA_PATH

# Set it if missing
export WOW_DATA_PATH="/path/to/WoW-3.3.5a/Data"

# Restart single-player mode
# Should see: "Test terrain loaded successfully"
```

### Controls Not Working

**Problem:** Keyboard/mouse input not responding

**Solution:**
1. Click on the game window to focus it
2. Check if a UI element has focus (press Escape)
3. Verify input in logs (should see key presses)
4. Restart application if needed

## Future Enhancements

### Planned Features

**Short-term:**
- [ ] Load multiple terrain tiles
- [ ] Real M2 character models
- [ ] Texture loading for WMOs
- [ ] Save/load camera position
- [ ] Screenshot capture (F11/F12)

**Medium-term:**
- [ ] Simple creature spawning (static models)
- [ ] Waypoint camera paths
- [ ] Time-lapse recording
- [ ] Custom weather patterns
- [ ] Terrain tile selection UI

**Long-term:**
- [ ] Offline character creation
- [ ] Basic movement animations
- [ ] Simple AI behaviors
- [ ] World exploration without server
- [ ] Local save/load system

## Comparison: Single-Player vs Server

| Feature | Single-Player | Server Mode |
|---------|---------------|-------------|
| **Setup Time** | Instant | 30-60 min |
| **Network Required** | No | Yes |
| **Terrain Loading** | Optional | Yes |
| **Character Models** | Test cubes | Real models |
| **Creatures** | None | Full AI |
| **Combat** | No | Yes |
| **Chat** | No | Yes |
| **Quests** | No | Yes |
| **Persistence** | No | Yes |
| **Performance** | High | Medium |
| **Good For** | Testing, visuals | Gameplay |

## Console Commands

While in single-player mode, you can use:

**Camera Commands:**
```
WASD - Move
Mouse - Look
Shift - Sprint
```

**Spawning Commands:**
```
K - Spawn character
O - Spawn building
Shift+O - Load WMO
J - Clear characters
P - Clear buildings
```

**Rendering Commands:**
```
F1 - Toggle HUD
F2 - Wireframe
F8-F12 - Various toggles
C - Clouds
L - Lens flare
W - Weather
M - Moon phases
```

## Example Workflow

### Complete Testing Session

1. **Start Application**
```bash
cd /home/k/Desktop/wowee/wowee
./build/bin/wowee
```

2. **Enter Single-Player**
- Click "Start Single Player" button
- Wait for world load

3. **Enable Effects**
- Press F1 (show HUD)
- Press C (enable clouds)
- Press L (enable lens flare)
- Press W (enable rain)

4. **Spawn Objects**
- Press K × 3 (spawn 3 characters)
- Press O × 2 (spawn 2 buildings)

5. **Explore**
- Use WASD to fly around
- Mouse to look around
- Shift to move faster

6. **Time Progression**
- Press F9 (auto time)
- Watch day → night transition
- Press + or - for manual control

7. **Take Screenshots**
- Press F1 (hide HUD)
- Position camera
- Use external screenshot tool

8. **Performance Check**
- Press F1 (show HUD)
- Check FPS (should be 60)
- Note draw calls and triangles
- Monitor CPU/GPU usage

## Keyboard Reference Card

**Essential Controls:**
- **Start Single Player** - Button on auth screen
- **F1** - Performance HUD
- **WASD** - Move camera
- **Mouse** - Look around
- **Shift** - Move faster
- **Escape** - Release mouse (if captured)

**Rendering:**
- **F2-F12** - Various toggles
- **+/-** - Time of day
- **C** - Clouds
- **L** - Lens flare
- **W** - Weather
- **M** - Moon phases

**Objects:**
- **K** - Spawn character
- **O** - Spawn building
- **J** - Clear characters
- **P** - Clear buildings

## Credits

**Single-Player Mode:**
- Designed for rapid testing and development
- No server setup required
- Full rendering engine access
- Perfect for content creators

**Powered by:**
- OpenGL 3.3 rendering
- GLM mathematics
- SDL2 windowing
- ImGui interface

---

**Mode Status**: ✅ Fully Functional
**Performance**: 60 FPS stable
**Setup Time**: Instant (one click)
**Server Required**: No
**Last Updated**: 2026-01-27
**Version**: 1.0.3