claude-home/gaming/troubleshooting.md

title	description	type	domain	tags
Gaming Troubleshooting Guide	Troubleshooting solutions for Linux gaming issues including launch failures, performance problems, audio/display issues, NVIDIA GPU detection, DLSS, ray tracing, and Ready or Not-specific fixes.	troubleshooting	gaming	steam proton stl nvidia dlss gamescope ready-or-not dxvk audio pipewire

Gaming Troubleshooting Guide

Quick Fixes by Issue Type

Game Won't Launch

1. Check Proton Version: Try GE-Proton10-11 or Proton 8.0-5
2. Verify Paths: Ensure CUSTOMCMD points to correct executable
3. Disable STL: Test with vanilla Proton first
4. Check Dependencies: Ensure required libraries are installed

Performance Issues

1. Enable GameMode: USEGAMEMODERUN="1"
2. Check DXVK Settings: Ensure ESYNC/FSYNC are enabled
3. Monitor GPU Usage: Use MangoHUD to identify bottlenecks
4. Adjust GameScope: Try different scaling options

Audio Problems

1. Increase Latency: STL_PULSE_LATENCY_MSEC="120"
2. PipeWire Fix: PIPEWIRE_LATENCY="256/48000"
3. Disable Audio Acceleration: In game settings
4. Check Audio Device: Ensure correct output selected

Display Issues

1. GameScope Resolution: Match native monitor resolution
2. Fullscreen Toggle: Try Alt+Enter in-game
3. Disable Compositing: Temporarily for testing
4. Check Graphics Drivers: Ensure latest NVIDIA drivers

Ready or Not Specific Issues

Menu Freeze / Mods Menu

Symptoms: Game freezes when accessing mods or certain menus Solution:

# Add to environment variables
PROTON_SET_GAME_DRIVE="1"

EasyAntiCheat Issues

Symptoms: Game won't start or kicks you from servers Solution:

# Add to game arguments
GAMEARGS="-noeac"

Note: This disables EAC and prevents online play

Black Screen on Launch

Symptoms: Game launches but shows black screen Solutions:

1. NVIDIA Driver Issue:

   # Try forcing NVIDIA GPU
   __NV_PRIME_RENDER_OFFLOAD=1
   __GLX_VENDOR_LIBRARY_NAME=nvidia
   

2. GameScope Issue:

   # Disable GameScope temporarily
   USEGAMESCOPE="0"
   

Performance Stuttering

Symptoms: Frequent frame drops or stuttering Solutions:

1. Enable DXVK Async:

   DXVK_ASYNC="1"
   

2. Force Large Address Aware:

   PROTON_FORCE_LARGE_ADDRESS_AWARE="1"
   

3. Limit Frame Rate:

   # In GameScope args
   GAMESCOPE_ARGS="-W 3440 -H 1440 -r 240 -f --immediate-flips --rt --fps-limit-method=2 --"
   

NVIDIA-Specific Troubleshooting

GPU Not Detected

1. Check Driver Installation:

   nvidia-smi
   lspci | grep -i nvidia
   

2. Verify Vulkan Support:

   vulkaninfo | grep deviceName
   

3. Force NVIDIA in STL:

   USEPRIMERUN="1"  # If on hybrid graphics
   

DLSS Issues

Enable DLSS Support:

PROTON_ENABLE_NVAPI="1"
USEDLSS="1"
PROTON_HIDE_NVIDIA_GPU="0"  # Don't hide GPU from game

Ray Tracing Problems

Enable Ray Tracing (DX12 games only):

USERAYTRACING="1"
STL_VKD3D_CONFIG="dxr"

Configuration File Locations

Steam Tinker Launch

• Global Config: ~/.config/steamtinkerlaunch/global.conf
• Game Configs: ~/.config/steamtinkerlaunch/gamecfgs/1144200.conf
• Logs: ~/.config/steamtinkerlaunch/logs/

Proton/Steam

• Compatdata: ~/.steam/steam/steamapps/compatdata/1144200/
• Game Install: ~/.steam/steam/steamapps/common/Ready Or Not/

Emergency Recovery

Reset Game Configuration

# Backup current config
cp ~/.config/steamtinkerlaunch/gamecfgs/1144200.conf ~/.config/steamtinkerlaunch/gamecfgs/1144200.conf.backup

# Reset to minimal config
cat > ~/.config/steamtinkerlaunch/gamecfgs/1144200.conf << 'EOF'
USEGAMEMODERUN="1"
USEPROTON="GE-Proton10-11"
GAMEARGS="-noeac"
EOF

Clean Proton Prefix

# Remove compatdata (Steam will recreate)
rm -rf ~/.steam/steam/steamapps/compatdata/1144200/
# Launch game to regenerate prefix

Verify Game Files

1. Open Steam
2. Right-click Ready or Not
3. Properties → Local Files → Verify integrity

Testing Methodology

Systematic Testing

1. Vanilla Test: Disable all STL settings
2. Minimal STL: Add only essential settings
3. Incremental: Add one setting at a time
4. Document: Record what works/doesn't work

Performance Testing

1. Baseline: Test without any modifications
2. With STL: Test with recommended settings
3. Compare: Use MangoHUD to compare frame rates
4. Optimize: Adjust settings based on results

Common Error Messages

Error	Cause	Solution
"Failed to initialize graphics"	Driver/GPU issue	Update NVIDIA drivers
"EasyAntiCheat timeout"	EAC conflict	Add -noeac argument
"Access violation"	Memory issue	Enable PROTON_FORCE_LARGE_ADDRESS_AWARE
"Vulkan initialization failed"	DXVK issue	Try PROTON_USE_WINED3D="1"

Hardware-Specific Notes

High Refresh Rate Monitors

• Ensure GameScope refresh rate matches monitor
• May need to limit frame rate for stability
• Test with vsync on/off

Multiple Monitors

• Specify primary display in GameScope
• May need to disable secondary monitors during play
• Check for focus issues

HDR Displays

For full HDR setup (vk-hdr-layer, KDE config, per-API env vars), see the steam-game-setup skill: .claude/skills/steam-game-setup/SKILL.md → HDR Configuration section

Xbox / Console Issues

Menu Delays Caused by Pi-hole Blocking

Symptoms: Multi-second (5-10s) hangs when toggling menus in online games (e.g., MLB The Show) Root Cause: Pi-hole gravity-blocks Microsoft telemetry domains that the Xbox calls synchronously during menu transitions. The game gets 0.0.0.0 from DNS, attempts TCP connect, and waits for timeout. Solution: Create a per-client Xbox group in Pi-hole with allowlist entries for the blocked domains. See xbox-pihole-mlb-the-show-incident.md for full details. Key domains to whitelist for Xbox:

• settings-win.data.microsoft.com
• arc.msn.com
• v10.events.data.microsoft.com
• v20.events.data.microsoft.com
• activity.windows.com

Diagnostic tip: Look for rapid retry patterns in Pi-hole logs (same domain queried every 1-3s from the Xbox IP) — this signals a blocked domain causing timeout loops.

Gray Zone Warfare — EAC Failures on Proton (2026-03-31)

Severity: High — game unplayable online

Problem: EAC errors when connecting to servers on Linux/Proton. Two error codes observed:

• 0x0002000F — "The client failed to register in time" (EAC timeout)
• 0x00020011 — "The client failed to start the session" (EAC session init failure)

Game launches fine, EAC bootstrapper reports success ("Easy Anti-Cheat successfully loaded in-game"), but fails when joining a server at "Synchronizing Live Data".

Root Cause: EOS SDK cannot load steam_api64.dll at startup:

LogEOSSDK: Error: Unable to load the Steamworks library: steam_api64.dll
LogEOSSDK: Error: Integrated Platform Steam failed to get steamworks sdk

Without Steam integration, EOS has no user identity → Invalid user EOS ID → EAC cannot start a client session. The steam_api64.dll exists in the game tree at Engine/Binaries/ThirdParty/Steamworks/Steamv158/Win64/ but EOS isn't resolving that path under Wine/Proton.

Additionally: upgrading from GE-Proton9-25 to GE-Proton10-25 and nuking the compatdata prefix may have triggered the regression. The game was working earlier the same day on GE-Proton9-25.

Log locations:

• EAC bootstrapper: compatdata/2479810/pfx/drive_c/users/steamuser/AppData/Roaming/EasyAntiCheat/.../anticheatlauncher.log
• Game log: compatdata/2479810/pfx/drive_c/users/steamuser/AppData/Local/GZW/Saved/Logs/GZW.log
• STL launch log: ~/.config/steamtinkerlaunch/logs/gamelaunch/id/2479810.log

What was tried (did NOT fix):

1. Installed Proton EasyAntiCheat Runtime (AppID 1826330)
2. Deleted stale world cache (GZW/Content/SKALLA/PrebuildWorldData/World/cache/)
3. Nuked compatdata prefix for clean rebuild
4. Verified game files (Steam repaired 20 files)
5. Upgraded to GE-Proton10-25

What to try next:

1. Restore GE-Proton9-25 — the version that was working earlier. Old prefix backed up at compatdata/2479810.bak
2. Check Proton issue #7721 — master tracking issue for GZW on Proton
3. split_lock_detect=off kernel param — reported to help with EAC init timeouts on some systems

Lesson: Don't upgrade Proton versions on a game that's currently working. Pin working Proton versions per-game in STL configs and only upgrade intentionally with a rollback plan (keep the old compatdata prefix).

Game version: 0.4.0.0-231948-H (EA Pre-Alpha) STL config: ~/.config/steamtinkerlaunch/gamecfgs/id/2479810.conf

Useful Commands

Check Running Game Process

# See game processes and GPU usage
nvidia-smi
ps aux | grep -i "ready\|proton"

Monitor Performance

# Real-time GPU monitoring
watch -n 1 nvidia-smi

# STL logs
tail -f ~/.config/steamtinkerlaunch/logs/steamtinkerlaunch.log

GameScope Debug

# Launch with GameScope debug
gamescope --debug -- steam steam://rungameid/1144200