diff --git a/gaming/scripts/CONTEXT.md b/gaming/scripts/CONTEXT.md index 0147af8..0fdb1a9 100644 --- a/gaming/scripts/CONTEXT.md +++ b/gaming/scripts/CONTEXT.md @@ -62,26 +62,325 @@ backup_config() { ## Current Scripts -### `validate-gaming-setup.sh` +### 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 +- Audio system detection (PipeWire/PulseAudio) - Display configuration analysis - Game-specific config validation -- Performance tools availability +- Performance tools availability (GameMode, MangoHUD) +- Proton version detection **Usage**: ```bash ./gaming/scripts/validate-gaming-setup.sh ``` -**Integration**: +**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