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

### `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
- Display configuration analysis
- Game-specific config validation
- Performance tools availability

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

**Integration**: 
- Called by setup scripts for validation
- Can be run independently for troubleshooting
- Provides recommendations for missing components

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