audiogame-manager/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

**Critical**: Be sure to keep this file up to date with new changes.

## Project Overview

**Audiogame Manager** is a comprehensive bash-based installer and launcher system for Windows audio games running under Wine on Linux. The project focuses on accessibility, providing speech synthesis support and screen reader compatibility for audio games designed for blind and visually impaired users.

## Architecture

### Core Components

- **Main Script**: `audiogame-manager.sh` - Entry point providing interactive menus for game installation, launching, and management with Wine32/64 bottle support
- **Includes Directory**: `.includes/` - Modular helper scripts containing core functionality
  - `functions.sh` - Core utilities (download, cache management, validation, requirements checking)
  - `dialog-interface.sh` - UI abstraction layer supporting both console (dialog) and GUI (yad) modes
  - `bottle.sh` - Wine bottle management, RHVoice installation, and prefix management
  - `checkup.sh` - System dependency validation
  - `help.sh` - Documentation system
  - `desktop.sh` - Desktop integration
  - `update.sh` - Auto-update mechanisms
- **Game Scripts**: `game-scripts/` - Individual game update/launch scripts
- **Install Scripts**: `.install/` - Game installation scripts (100+ games supported)
- **Speech Integration**: `speech/` - TTS and accessibility tools
  - `set-voice.sh` - Voice configuration with test functionality
  - Supports multiple TTS engines (RHVoice, SAPI, Cepstral)
  - Per-bottle voice configuration system
  - NVDA screen reader compatibility through custom DLL
- **Wine Integration**: `wine/` - Wine setup utilities including bottle creation and dependency installation
  - `mkwine.sh` - Wine bottle creation
  - Distribution-specific dependency installers

### Wine Architecture

The project uses Wine with a unified architecture:
- **Wine64 Only**: All games use wine64+WOW64 exclusively - it runs both 32-bit and 64-bit applications efficiently
- **Wine32 ELIMINATED**: As of 2025-12-06, wine32 bottle is no longer created or used
- **Unified bottle**: Single wine64 prefix (stored in `~/.local/wine64`) for ALL games, including SAPI games
- **Custom bottles**: Can be stored in `~/.local/share/audiogame-manager/wineBottles/` with per-bottle configurations in `~/.config/audiogame-manager/`
- **IMPORTANT**: Never create game-specific wine directories like `~/.local/winegamename` - use the standard bottle system

#### SAPI and Speech SDK Support (WINETRICKS_FORCE=1)

**Discovery (2025-12-06)**: Setting `WINETRICKS_FORCE=1` enables reliable speechsdk installation in wine64+WOW64 bottles, eliminating the need for wine32 for most SAPI-dependent games.

**Implementation:**
- `audiogame-manager.sh:96` - wine64 bottle creation includes speechsdk with `WINETRICKS_FORCE=1`
- `audiogame-manager.sh:99` - Restores win10 after speechsdk (see caveat below)
- `.includes/bottle.sh:176-181` - Only speechsdk installations use `WINETRICKS_FORCE=1` (other deps use regular winetricks)
- Both bottles install Microsoft Mike as the default SAPI voice automatically

**CAVEAT**: The `speechsdk` winetricks verb sets `w_set_winver winxp` at the end, trampling any previously set Windows version. Always call `winetricks win10` AFTER installing speechsdk.

**Migrated SAPI Games (wine64):**
- Bloodshed - Tested and confirmed working
- Kitchensinc Games - Tested and confirmed working (VB6)
- Oh Shit - Migrated, requires testing
- Dog Who Hates Toast - Migrated, requires testing (VB6)
- Lunimals - Migrated, requires testing (VB6)
- VIP Mud - Migrated, requires testing (VB6)
- Entombed - Migrated, requires testing (complex .NET dependencies)
- Skateboarder Pro - Already configured for wine64, now functional
- Three D velocity - Already configured for wine64, now functional

**Migrated Self-Voicing Games (wine64):**
- Shadow Line - Migrated, requires Windows 8 via per-app versioning
- Villains From Beyond - Tested and confirmed working

#### Per-Application Windows Version

**Problem (2025-12-08)**: Some games require specific Windows versions (e.g., Shadow Line needs win8) but with a unified bottle, `winetricks winXX` changes the version globally for ALL games.

**Solution**: Use Wine's per-application settings via registry keys:
```
[HKEY_CURRENT_USER\Software\Wine\AppDefaults\executable.exe]
"Version"="win8"
```

**Implementation:**
- Game installers set `export winVer="win8"` (or win7, win10)
- `install_wine_bottle()` stores this in `gameWinVer` (doesn't apply globally)
- `add_launcher()` calls `set_app_winver()` which writes the per-exe registry key
- Located in `.includes/bottle.sh:186-209` (`set_app_winver` function)

**Architecture Selection Logic:**
- Games explicitly setting `WINEARCH=win64` will use wine64 (new behavior)
- Games passing `sapi` dependency use wine64 with speechsdk pre-installed
- Legacy games passing `speechsdk` dependency still use wine32 for compatibility
- Default architecture is wine64 for all new games

### Interface System

Dialog interface automatically detects environment:
- Console mode: Uses `dialog` for accessibility
- GUI mode: Uses `yad` when DISPLAY is available
- All UI functions are prefixed with `agm_` (audiogame manager)

## Development Commands

### System Check
```bash
./audiogame-manager.sh -c     # Check system requirements and dependencies
bash -n audiogame-manager.sh  # Basic syntax check
```

### Installation and Usage
```bash
./audiogame-manager.sh        # Launch installed games menu
./audiogame-manager.sh -i     # Install games (interactive menu)
./audiogame-manager.sh -I "Game Name"  # Install a game noninteractively
./audiogame-manager.sh -h     # Show help
```

### Wine Bottle Management
```bash
./wine/mkwine.sh [bottle_name] [architecture]  # Create a new Wine bottle
```

### Voice and Speech Testing
```bash
./speech/set-voice.sh         # Configure and test voice settings
./speech/set-voice.sh [bottle_name]  # Configure voice for a specific bottle
```

### Dependency Management
```bash
# Check all required packages
./.includes/checkup.sh packages

# Install Wine dependencies for different distros
./wine/install-dependencies-arch.sh
./wine/install-dependencies-debian.sh
```

### Testing All Include Files
```bash
for f in .includes/*.sh; do bash -n "$f"; done
```

## Key Patterns and Conventions

### Coding Style - **EXTREMELY IMPORTANT - MUST BE FOLLOWED**

- **Variables**: Use camelCase for variable names (e.g., `gameTitle`, `wineBottle`, `installPath`)
  - **CRITICAL**: ALL variables must use camelCase - no exceptions
  - Examples: `selectedGame`, `wineArch`, `installPath`, `downloadUrl`
  - Never use: `selected_game`, `wine_arch`, `install_path`, `download_url`
- **Functions**: Use snake_case for function names (e.g., `install_game`, `create_wine_bottle`, `check_dependencies`)
  - **CRITICAL**: ALL functions must use snake_case - no exceptions
  - Examples: `get_wine_bottle()`, `process_launcher_flags()`, `download_file()`
  - Never use: `getWineBottle()`, `processLauncherFlags()`, `downloadFile()`
- **Shebang**: Use `#!/bin/bash` for all bash scripts
  - **CRITICAL**: .sh files in .install/ are game installers, not typical bash scripts If they contain # on the first line they are disabled and will not show up in audiogame-manager
- **Sourcing pattern**:
  - **Main script** (`audiogame-manager.sh`): Use `source "${scriptDir}/.includes/file.sh"` (scriptDir is defined at line 4)
  - **Subdirectory scripts** (game-scripts/, wine/, speech/): Use `source "${0%/*}/../.includes/file.sh"`
  - **CRITICAL**: Never use relative paths like `source .includes/file.sh` - these fail when the current working directory differs from the script location
- **Indentation**: Use consistent indentation (tabs or spaces, follow existing file patterns)
- When fixing code, correct any indentation inconsistencies to match the established style

### Error Handling
- Functions return 0 for success, non-zero for failure
- Use consistent exit codes throughout scripts
- Provide clear error messages with context
- Critical errors vs warnings are clearly distinguished in checkup system
- Progress feedback is provided for all long-running operations
- Always clean up temporary files on exit
- Log important operations for debugging

### File Structure
- Game installers follow naming convention: `.install/Game Name.sh`
  - **IMPORTANT**: Games starting with hash (#) are commented out even if it's a comment
  - First line of a game installer may not start with # unless we're excluding it
- Cache directory: `~/.local/share/audiogame-manager/cache/`
- Wine bottles: `~/.local/wine32/` and `~/.local/wine64/`
- Custom bottles: `~/.local/share/audiogame-manager/wineBottles/`
- Configuration: `~/.config/audiogame-manager/`

### UI Functions
All dialog functions in `.includes/dialog-interface.sh` follow pattern:
- `agm_menu()` - Selection menus
- `agm_msgbox()` - Message display
- `agm_yesno()` - Confirmation dialogs
- `agm_progressbox()` - Progress display
- Functions automatically adapt to console/GUI environment

### Game Integration
- Each game has both an installer (`.install/`) and optional update script (`game-scripts/`)
- Games are categorized by engine type and requirements
- SAPI games automatically use Wine32, others use Wine64
- Games are tracked in configuration files with Wine bottle associations
- Each game can use different Wine bottles with specific configurations

### Game Installation Pattern
1. Check system requirements and dependencies
2. Create or verify Wine bottle
3. Install Wine dependencies via winetricks
4. Download and validate game files (use checksums when available)
5. Configure speech synthesis (typically RHVoice)
6. Add game entry to launcher configuration

### Accessibility Features
- Sound alerts using `sox` for important notifications
- Screen reader compatibility through proper dialog usage
- Keyboard navigation support throughout interface
- Voice testing integrated into setup process

## Dependencies

### Critical (Required)
- wine, curl, dialog, sox
- Archive tools: 7z, cabextract, unzip, xz
- winetricks (for Wine component management)

### Optional (Warnings if missing)
- gawk (for game removal)
- ocrdesktop (installer debugging)
- qjoypad (gamepad support)
- translate-shell, sqlite3, perl (translation features)
- w3m (documentation viewing)
- xclip, xdotool (X11 integration)

### Platform Support
- x86_64 Linux (primary)
- aarch64 with FEX-Emu (alternative Wine implementation)

## Testing
- System requirements: `./audiogame-manager.sh -c`
- Voice functionality: Use built-in voice test in `set-voice.sh`
- Game installation: Test with simple games first before complex ones
- Wine bottle integrity: Check `~/.local/wine32/system.reg` and `~/.local/wine64/system.reg` exist
- Test with different Wine versions when modifying bottle creation
- Verify speech synthesis functionality after TTS changes
- Test game installation scripts in clean environments
- Check both 32-bit and 64-bit compatibility where applicable

## Recent Refactor Notes (2025)

### Major Refactor Status
The project has undergone a significant refactor to modularize functionality. **Status: Largely Complete**

### Key Fixes Applied
1. **Function naming**: Fixed `process_launcher-flags()` → `process_launcher_flags()` in `audiogame-manager.sh:270`
2. **Variable scope**: Added `export game` in main script so `.includes/bottle.sh` functions can access it
3. **Installation logic**: Completed the `-I` option implementation for noninteractive game installation
4. **Code deduplication**: Removed duplicate `check_news` and launcher logic from `update.sh`
5. **Include sourcing**: Fixed all relative path sourcing (e.g., `source .includes/bottle.sh`) to use `${scriptDir}` to ensure desktop launchers and execution from any working directory works correctly

### Critical Variable Handling
- **`$game` variable**: Must be exported when set (line 489 in main script) for bottle.sh functions to work
- **`agmNoLaunch` variable**: Used to prevent main script execution when sourced by other scripts
- **Bottle names**: Derived from game names, converted to lowercase with spaces replaced by hyphens

### Important Patterns
- **Noninteractive installation**: The `-I` option sources the appropriate `.install/GameName.sh` script
- **Variable scope**: Include files rely on exported variables from main script
- **Wine bottle logic**: Game-specific wine versions are handled in `bottle.sh:get_bottle()`

### Common Issues to Watch For
1. **Variable exports**: Ensure variables are exported when needed by include files
2. **Function naming**: Use snake_case for functions, camelCase for variables
3. **Path quoting**: Always quote paths that might contain spaces
4. **Duplicate logic**: Check main script vs includes to avoid redundant code