From 17bf963f3efa1bf6a62402d9f92533980c767ceb Mon Sep 17 00:00:00 2001
From: Kelsi <kelsihates2fa@gmail.com>
Date: Wed, 11 Mar 2026 15:36:02 -0700
Subject: [PATCH] docs: add comprehensive troubleshooting guide for users

---
 TROUBLESHOOTING.md | 186 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 186 insertions(+)
 create mode 100644 TROUBLESHOOTING.md

diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 00000000..034fb769
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,186 @@
+# 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:
+```bash
+# 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.