claude-home/gaming/scripts/CONTEXT.md

# Gaming Scripts Context

## Overview
This directory contains automation and helper scripts for gaming setup, configuration, and maintenance. These scripts are designed to work with Steam Tinker Launch and various gaming tools on Linux.

## Script Categories

### Setup and Configuration
- **Purpose**: Automate initial setup and configuration of gaming environments
- **Target**: Steam Tinker Launch, game-specific configurations, system optimization
- **Pattern**: Interactive setup with validation and backup creation

### Validation and Testing  
- **Purpose**: Verify gaming environment is properly configured
- **Target**: Hardware detection, driver validation, configuration checking
- **Pattern**: Comprehensive system checks with colored output and recommendations

### Performance Monitoring
- **Purpose**: Monitor and optimize gaming performance
- **Target**: FPS monitoring, resource usage, bottleneck identification
- **Pattern**: Real-time monitoring with logging and alerting

## Common Patterns

### Error Handling
```bash
set -e  # Exit on error
trap cleanup EXIT  # Always cleanup
```

### Logging
```bash
# Colored output functions
log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
log_warning() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
```

### Dependency Checking
```bash
check_dependencies() {
    local deps=("steam" "gamescope" "nvidia-smi")
    for dep in "${deps[@]}"; do
        command -v "$dep" >/dev/null 2>&1 || {
            log_error "$dep not found"
            return 1
        }
    done
}
```

### Configuration Backup
```bash
backup_config() {
    local config_file="$1"
    if [ -f "$config_file" ]; then
        cp "$config_file" "${config_file}.backup.$(date +%Y%m%d_%H%M%S)"
    fi
}
```

## Current Scripts

### Setup and Initialization Scripts

#### `clean-slate-setup.sh`
**Purpose**: Reset Ready or Not configuration to clean slate for testing
**Features**:
- Backs up existing STL configuration for game 1144200 (Ready or Not)
- Removes game-specific configuration files
- Clears STL cache and temporary files
- Resets to vanilla Steam/Proton configuration
- Preserves backup for rollback if needed

**Usage**:
```bash
./gaming/scripts/clean-slate-setup.sh
```

**When to Use**:
- Before testing new Proton versions
- When troubleshooting configuration conflicts
- After major STL updates
- When starting fresh configuration process

**Safety Features**:
- Creates timestamped backups before removal
- Confirms destructive operations
- Provides restoration instructions

#### `install-ron-mods.sh`
**Purpose**: Install and configure mods for Ready or Not
**Features**:
- Automated mod installation process
- Validates mod compatibility
- Configures STL for mod support
- Enables -noeac flag for EasyAntiCheat bypass (required for mods)
- Creates backup of game files before modding

**Usage**:
```bash
./gaming/scripts/install-ron-mods.sh
```

**Requirements**:
- Ready or Not installed via Steam
- STL configured for game ID 1144200
- Mods downloaded to staging directory
- EasyAntiCheat must be disabled for mods to work

**Warning**: Installing mods disables online multiplayer due to EasyAntiCheat requirements

### Launch and Execution Scripts

#### `launch-ron-direct.sh`
**Purpose**: Launch Ready or Not directly with specific configuration, bypassing normal Steam launch
**Features**:
- Direct game executable launch
- Custom environment variables
- Debugging output
- Performance monitoring hooks
- GameScope integration
- Proton version override

**Usage**:
```bash
./gaming/scripts/launch-ron-direct.sh [options]
```

**When to Use**:
- Testing specific Proton versions
- Debugging launch issues
- Running with custom environment settings
- Bypassing Steam overlay for testing
- Capturing detailed launch logs

**Options**:
- Direct Proton control
- Environment variable injection
- Debug logging enablement
- Performance profiling

### Diagnostic and Troubleshooting Scripts

#### `check-stl-logs.sh`
**Purpose**: Analyze Steam Tinker Launch logs for common issues and errors
**Features**:
- Parses recent STL logs (default: game 1144200)
- Identifies common error patterns
- Highlights warnings and failures
- Provides recommendations for fixes
- Color-coded output for easy scanning
- Searches for specific error types (GPU, audio, shader compilation, etc.)

**Usage**:
```bash
./gaming/scripts/check-stl-logs.sh [game-id]

# Check Ready or Not logs (default)
./check-stl-logs.sh

# Check specific game
./check-stl-logs.sh 730  # Counter-Strike 2
```

**Log Location**: `~/.config/steamtinkerlaunch/logs/`

**Common Issues Detected**:
- DXVK shader compilation errors
- GPU compatibility issues
- Audio crackling/latency problems
- EasyAntiCheat conflicts
- GameScope configuration errors
- Missing dependencies

#### `diagnose-crash.sh`
**Purpose**: Comprehensive crash analysis for Ready or Not
**Features**:
- Collects crash logs from multiple sources
- Analyzes Proton crash dumps
- Checks system logs for GPU/driver errors
- Examines game save file corruption
- Reviews STL configuration for conflicts
- Generates diagnostic report

**Usage**:
```bash
./gaming/scripts/diagnose-crash.sh
```

**Information Gathered**:
- Game crash dumps (if available)
- Proton logs
- STL logs
- System dmesg output (GPU errors)
- X11/Wayland logs
- Audio system status
- Recent configuration changes

**Output**: Creates detailed diagnostic report with recommendations

#### `fix-steam-override.sh`
**Purpose**: Fix Steam launch option override issues in STL
**Features**:
- Detects conflicting Steam launch options
- Resolves STL vs Steam configuration conflicts
- Resets launch parameters to STL-managed state
- Validates proper integration
- Backs up current launch options

**Usage**:
```bash
./gaming/scripts/fix-steam-override.sh [game-id]
```

**Common Issues Fixed**:
- Launch options not being applied
- STL settings ignored by Steam
- Conflicting Proton version selections
- Environment variable conflicts
- GameScope parameters not passed correctly

**Safety**: Always backs up current configuration before making changes

### Testing and Validation Scripts

#### `validate-gaming-setup.sh`
**Purpose**: Comprehensive validation of gaming environment
**Features**:
- NVIDIA driver and GPU detection
- Steam and Steam Tinker Launch validation
- GameScope availability check
- Audio system detection (PipeWire/PulseAudio)
- Display configuration analysis
- Game-specific config validation
- Performance tools availability (GameMode, MangoHUD)
- Proton version detection

**Usage**:
```bash
./gaming/scripts/validate-gaming-setup.sh
```

**Checks Performed**:
- ✅ NVIDIA drivers installed and working
- ✅ Steam running and accessible
- ✅ STL installed and configured
- ✅ GameScope available for session management
- ✅ Audio system functional
- ✅ Display server (X11/Wayland) compatible
- ✅ Performance tools available
- ✅ Game files present and valid

**Integration**:
- Called by setup scripts for validation
- Can be run independently for troubleshooting
- Provides recommendations for missing components
- Exit codes indicate success/failure for automation

#### `test-vanilla-proton.sh`
**Purpose**: Test game with vanilla Proton (no STL modifications)
**Features**:
- Temporarily disables STL for testing
- Launches game with stock Proton
- Compares performance and stability
- Helps identify if STL is causing issues
- Restores STL configuration after test

**Usage**:
```bash
./gaming/scripts/test-vanilla-proton.sh [game-id]
```

**When to Use**:
- Game not launching with STL
- Performance issues suspected to be STL-related
- Comparing STL vs vanilla behavior
- Debugging configuration problems
- Verifying game works with base Proton

**Process**:
1. Backs up current STL configuration
2. Disables STL for specified game
3. Launches game with Steam's default Proton
4. Waits for game exit
5. Restores STL configuration
6. Reports differences observed

#### `ready-or-not-compatibility-test.sh`
**Purpose**: Comprehensive Ready or Not compatibility testing
**Features**:
- Tests multiple Proton versions
- Validates GPU compatibility
- Checks audio configuration
- Tests different GameScope settings
- Validates shader compilation
- Reports which configurations work

**Usage**:
```bash
./gaming/scripts/ready-or-not-compatibility-test.sh
```

**Test Matrix**:
- Proton Experimental
- Proton GE (latest)
- Proton 8.0+
- Various GameScope configurations
- DXVK vs VKD3D
- Different audio backends

**Output**:
- Detailed compatibility report
- Performance metrics for each configuration
- Recommendations for optimal settings
- Known issues and workarounds

**Duration**: ~30-60 minutes (tests multiple configurations)

## Script Execution Flow

### Typical Troubleshooting Workflow

**Issue: Game Won't Launch**
```bash
# 1. Validate environment
./validate-gaming-setup.sh

# 2. Check logs for errors
./check-stl-logs.sh

# 3. Try vanilla Proton
./test-vanilla-proton.sh

# 4. If still failing, diagnose crash
./diagnose-crash.sh

# 5. Fix Steam override conflicts if needed
./fix-steam-override.sh
```

**Issue: Game Crashes**
```bash
# 1. Diagnose crash
./diagnose-crash.sh

# 2. Check STL logs
./check-stl-logs.sh

# 3. Run compatibility test
./ready-or-not-compatibility-test.sh

# 4. Try clean configuration
./clean-slate-setup.sh
```

**Issue: Mods Not Working**
```bash
# 1. Verify game works without mods
./test-vanilla-proton.sh

# 2. Clean install mods
./clean-slate-setup.sh
./install-ron-mods.sh

# 3. Launch with debugging
./launch-ron-direct.sh --debug
```

## Script Maintenance

### Regular Updates Needed
- **Proton Versions**: Update compatibility tests as new Proton versions release
- **Game Updates**: Adjust scripts when Ready or Not updates change requirements
- **STL Updates**: Modify scripts for STL configuration changes
- **Driver Updates**: Update GPU detection for new NVIDIA drivers

### Testing Requirements
- Test scripts after STL updates
- Verify compatibility with new Proton versions
- Validate on different hardware configurations
- Check after major game patches

## Integration Points

### With Home Lab Infrastructure
- **Logging**: Scripts log to standard locations for centralized monitoring
- **Monitoring**: Performance scripts can integrate with existing monitoring systems
- **Documentation**: All scripts include comprehensive help and documentation
- **Configuration**: Scripts respect existing configuration patterns and backup strategies

### With Steam Tinker Launch
- **Config Management**: Scripts handle STL configuration files properly
- **Game Detection**: Scripts can identify and configure specific games
- **Environment Setup**: Scripts set up proper environment variables and system configuration
- **Troubleshooting**: Scripts provide diagnostic information for STL issues

### With System Services
- **Audio Systems**: Scripts detect and configure PipeWire/PulseAudio
- **Display Managers**: Scripts work with X11 and Wayland display systems
- **GPU Drivers**: Scripts validate and configure NVIDIA/AMD drivers
- **Performance Tools**: Scripts integrate with GameMode, MangoHUD, and other performance tools

## Development Patterns

### Script Structure
```bash
#!/bin/bash
# Script description and purpose

set -e  # Exit on error

# Color definitions
RED='\033[0;31m'
GREEN='\033[0;32m'
# ... etc

# Logging functions
log_info() { ... }
log_success() { ... }
# ... etc

# Main functionality functions
check_something() { ... }
setup_something() { ... }
validate_something() { ... }

# Main execution
main() {
    log_info "Starting script..."
    check_something
    setup_something  
    validate_something
    log_success "Script completed"
}

main "$@"
```

### Testing Approach
- Scripts should validate their own prerequisites
- Include dry-run modes where applicable
- Provide verbose output for debugging
- Include rollback mechanisms for destructive operations

### Documentation Standards
- Each script includes comprehensive comments
- Usage examples in script headers
- Integration notes for complex setups
- Troubleshooting sections for common issues

## Maintenance Notes

### Regular Tasks
- Update game-specific configurations as games are updated
- Validate scripts work with new versions of Steam Tinker Launch
- Test scripts with different hardware configurations
- Update performance optimization settings based on new research

### Monitoring Integration
- Scripts should support being called from monitoring systems
- Performance scripts should output metrics in parseable formats
- Error conditions should be properly logged and alertable
- Resource usage should be monitored for long-running scripts

### Security Considerations
- Scripts handle configuration files with proper permissions
- No hardcoded paths or credentials
- Proper input validation for user-provided parameters
- Safe handling of system-level configuration changes