Kelsidavis-WoWee/TROUBLESHOOTING.md

Troubleshooting Guide

This guide covers common issues and solutions for WoWee.

Connection Issues

"Authentication Failed"

• Cause: Incorrect server address, expired realm list, or version mismatch
• Solution:
  1. Verify server address in realm list is correct
  2. Ensure your WoW data directory is for the correct expansion (Vanilla/TBC/WotLK)
  3. Check that the emulator server is running and reachable

"Realm List Connection Failed"

• Cause: Server is down, firewall blocking connection, or DNS issue
• Solution:
  1. Verify server IP/hostname is correct
  2. Test connectivity: ping realm-server-address
  3. Check firewall rules for port 3724 (auth) and 8085 (realm list)
  4. Try using IP address instead of hostname (DNS issues)

"Connection Lost During Login"

• Cause: Network timeout, server overload, or incompatible protocol version
• Solution:
  1. Check your network connection
  2. Reduce number of assets loading (lower graphics preset)
  3. Verify server supports this expansion version

Graphics Issues

"VK_ERROR_DEVICE_LOST" or Client Crashes

• Cause: GPU driver issue, insufficient VRAM, or graphics feature incompatibility
• Solution:
  1. Immediate: Disable advanced graphics features:
     • Press Escape → Video Settings
     • Set graphics preset to LOW
     • Disable Water Refraction (requires FSR)
     • Disable MSAA (set to Off)
  2. Medium term: Update GPU driver to latest version
  3. Verify: Use a graphics test tool to ensure GPU stability
  4. If persists: Try FSR2 disabled mode - check renderer logs

Black Screen or Rendering Issues

• Cause: Missing shaders, GPU memory allocation failure, or incorrect graphics settings
• Solution:
  1. Check logs: Look in ~/.wowee/logs/ for error messages
  2. Verify shaders compiled: Check for .spv files in assets/shaders/compiled/
  3. Reduce shadow distance: Press Escape → Video Settings → Lower shadow distance from 300m to 100m
  4. Disable shadows entirely if issues persist

Low FPS or Frame Stuttering

• Cause: Too high graphics settings for your GPU, memory fragmentation, or asset loading
• Solution:
  1. Apply lower graphics preset: Escape → LOW or MEDIUM
  2. Disable MSAA: Set to "Off"
  3. Reduce draw distance: Move further away from complex areas
  4. Close other applications consuming GPU memory
  5. Check CPU usage - if high, reduce number of visible entities

Water/Terrain Flickering

• Cause: Shadow mapping artifacts, terrain LOD issues, or GPU memory pressure
• Solution:
  1. Increase shadow distance slightly (150m to 200m)
  2. Disable shadows entirely as last resort
  3. Check GPU memory usage

Audio Issues

No Sound

• Cause: Audio initialization failed, missing audio data, or incorrect mixer setup
• Solution:
  1. Check system audio is working: Test with another application
  2. Verify audio files extracted: Check for .wav files in Data/Audio/
  3. Unmute audio: Look for speaker icon in minimap (top-right) - click to unmute
  4. Check settings: Escape → Audio Settings → Master Volume > 0

Sound Cutting Out

• Cause: Audio buffer underrun, too many simultaneous sounds, or driver issue
• Solution:
  1. Lower audio volume: Escape → Audio Settings → Reduce Master Volume
  2. Disable distant ambient sounds: Reduce Ambient Volume
  3. Reduce number of particle effects
  4. Update audio driver

Gameplay Issues

Character Stuck or Not Moving

• Cause: Network synchronization issue, collision bug, or server desync
• Solution:
  1. Try pressing Escape to deselect any target, then move
  2. Jump (Spacebar) to test physics
  3. Reload the character: Press Escape → Disconnect → Reconnect
  4. Check for transport/vehicle state: Press 'R' to dismount if applicable

Spells Not Casting or Showing "Error"

• Cause: Cooldown, mana insufficient, target out of range, or server desync
• Solution:
  1. Verify spell is off cooldown (action bar shows availability)
  2. Check mana/energy: Look at player frame (top-left)
  3. Verify target range: Hover action bar button for range info
  4. Check server logs for error messages (combat log will show reason)

Quests Not Updating

• Cause: Objective already completed in different session, quest giver not found, or network desync
• Solution:
  1. Check quest objective: Open quest log (Q key) → Verify objective requirements
  2. Re-interact with NPC to trigger update packet
  3. Reload character if issue persists

Items Not Appearing in Inventory

• Cause: Inventory full, item filter active, or network desync
• Solution:
  1. Check inventory space: Open inventory (B key) → Count free slots
  2. Verify item isn't already there: Search inventory for item name
  3. Check if bags are full: Open bag windows, consolidate items
  4. Reload character if item is still missing

Performance Optimization

For Low-End GPUs

Graphics Preset: LOW
- Shadows: OFF
- MSAA: OFF
- Normal Mapping: Disabled
- Clutter Density: 25%
- Draw Distance: Minimum
- Particles: Reduced

For Mid-Range GPUs

Graphics Preset: MEDIUM
- Shadows: 200m
- MSAA: 2x
- Normal Mapping: Basic
- Clutter Density: 60%
- FSR2: Enabled (if desired)

For High-End GPUs

Graphics Preset: HIGH or ULTRA
- Shadows: 350-500m
- MSAA: 4-8x
- Normal Mapping: Full (1.2x strength)
- Clutter Density: 100-150%
- FSR2: Optional (for 4K smoothness)

Getting Help

Check Logs

Detailed logs are saved to:

• Linux/macOS: ~/.wowee/logs/
• Windows: %APPDATA%\wowee\logs\

Include relevant log entries when reporting issues.

Check Server Compatibility

• AzerothCore: Full support
• TrinityCore: Full support
• Mangos: Full support
• Turtle WoW: Full support (1.17)

Report Issues

If you encounter a bug:

1. Enable logging: Watch console for error messages
2. Reproduce the issue consistently
3. Gather system info: GPU, driver version, OS
4. Check if issue is expansion-specific (Classic/TBC/WotLK)
5. Report with detailed steps to reproduce

Clear Cache

If experiencing persistent issues, clear WoWee's cache:

# Linux/macOS
rm -rf ~/.wowee/warden_cache/
rm -rf ~/.wowee/asset_cache/

# Windows
rmdir %APPDATA%\wowee\warden_cache\ /s
rmdir %APPDATA%\wowee\asset_cache\ /s

Then restart WoWee to rebuild cache.