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

set -e  # Exit on error
trap cleanup EXIT  # Always cleanup

Logging

# 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

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

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:

./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:

./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:

./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:

./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:

./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:

./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:

./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:

./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:

./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

# 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

# 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

# 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

#!/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