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 specific architectural requirements:
- **Modern approach**: Use WOW64 (wine64) for everything by default - it can run both 32-bit and 64-bit applications efficiently
- **Wine32**: Legacy 32-bit prefix (stored in `~/.local/wine32`) - only for SAPI-dependent games with WOW64 issues
- **Wine64**: Modern prefix (stored in `~/.local/wine64`) - primary target for all games
- Wine32 version is controlled by `wineThirtyTwoVersion` variable in main script and auto-manages installation/updates
- **Custom bottles**: 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

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