storm/audiogame-manager
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
2908a031c66f610ac517349f2970a58296fbe73c
audiogame-manager/CLAUDE.md

12 KiB
Raw Blame History

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:95 - wine32 bottle creation uses WINETRICKS_FORCE=1
  • audiogame-manager.sh:157 - wine64 bottle creation now includes speechsdk with WINETRICKS_FORCE=1
  • .includes/bottle.sh:158 - All additional winetricks installations use WINETRICKS_FORCE=1
  • Both bottles install Microsoft Mike as the default SAPI voice automatically

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, has issues (crashes after launch - needs further investigation)
  • Villains From Beyond - Tested and confirmed working

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

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

Installation and Usage

./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

./wine/mkwine.sh [bottle_name] [architecture]  # Create a new Wine bottle

Voice and Speech Testing

./speech/set-voice.sh         # Configure and test voice settings
./speech/set-voice.sh [bottle_name]  # Configure voice for a specific bottle

Dependency Management

# 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

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
Reference in New Issue View Git Blame Copy Permalink