# CLAUDE.md

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

## Overview

Audiogame Manager is a bash-based installer and launcher for Windows audio games running under Wine on Linux. It provides an accessible interface for managing audio games specifically designed for blind and visually impaired users.

## Architecture

### Core Components

- **Main Script**: `audiogame-manager.sh` - Entry point with Wine32/64 bottle management and main menu system
- **Includes Directory**: `.includes/` - Shared functionality modules
  - `functions.sh` - Core utilities (download, cache management, requirements checking)
  - `dialog-interface.sh` - UI abstraction layer supporting both console (dialog) and GUI (yad) modes
  - `bottle.sh` - Wine prefix management
  - `checkup.sh` - System dependency validation
  - `help.sh` - Help system
- **Game Scripts**: `game-scripts/` - Individual game update/launch scripts
- **Install Scripts**: `.install/` - Game installation scripts (100+ games supported)
- **Speech Integration**: `speech/` - Voice and TTS management
  - `set-voice.sh` - Voice configuration with test functionality
  - NVDA and Cepstral installers
- **Wine Integration**: `wine/` - Wine setup and dependency management

### Wine Architecture

The project uses dual Wine environments:
- **Wine32**: For SAPI-dependent games (stored in `~/.local/wine32`)
- **Wine64**: For modern games (stored in `~/.local/wine64`)

Wine32 version is controlled by `wineThirtyTwoVersion` variable in main script and auto-manages installation/updates.

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

### Installation and Usage
```bash
./audiogame-manager.sh -i     # Install games (interactive menu)
./audiogame-manager.sh -h     # Show help
./audiogame-manager.sh        # Launch installed games menu
```

### Voice Testing
```bash
./speech/set-voice.sh         # Configure and test voice settings
```

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

## Key Patterns and Conventions

### Error Handling
- Functions return 0 for success, non-zero for failure
- Critical errors vs warnings are clearly distinguished in checkup system
- Progress feedback is provided for all long-running operations

### File Structure
- Game installers follow naming convention: `.install/Game Name.sh`
- Cache directory: `~/.local/share/audiogame-manager/cache/`
- Wine bottles: `~/.local/wine32/` and `~/.local/wine64/`

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

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