storm/audiogame-manager
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
f7252e24edca491b1ed2dbc351f0d24337c6a4c2
audiogame-manager/CLAUDE.md
Storm Dragon f7252e24ed One more directive in the CLAUDE.md file.
2025-10-18 21:10:50 -04:00

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

./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: Use modular sourcing: . "${0%/*}/.includes/file.sh"
  • 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

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