# Linux Game Manager Core Map

Last refreshed: 2026-02-21

## Top-Level Structure

- `linux-game-manager.sh`: Main orchestrator, UI wrappers, CLI option handling, install/remove/update flows, cache and settings behavior.
- `.install/`: Per-game installer scripts sourced by `game_installer`.
- `.launch/`: Per-game launch scripts (`.game`) and runnable entries (`.sh`, usually symlinks).
- `.update/`: Optional per-game update scripts expected to define `run_update()`.
- `speech/speak_window_title.sh`: Accessibility helper for announcing focused window titles.
- `README.md`: Project summary and high-level behavior notes.
- `.files/`: Game-specific auxiliary assets/scripts used by some installers or launchers.

## Catalog Snapshot

- Installers: 38 (`.install/*.sh`)
- Launcher definitions: 38 (`.launch/*.game`)
- Launcher runnable entries: 26 (`.launch/*.sh`, both symlinks and files)
- Update scripts: 5 (`.update/*.sh`)

Regenerate this snapshot with:

```bash
python3 .codex/skills/linux-game-manager-dev/scripts/audit_game_catalog.py
```

## Main Runtime Flows

1. **Install flow**
- `game_installer` builds menu from `.install/*.sh`.
- Selected installer is sourced in the current shell.
- If `.launch/<game>.game` exists and `.launch/<game>.sh` does not, the manager creates a symlink.

2. **Launch flow**
- `game_launcher` enumerates `.launch/*.sh` entries.
- Entries with first line `#//` are skipped.
- Selected launcher is sourced/executed.

3. **Removal flow**
- `game_removal` resolves launcher entry to real script.
- It extracts the first `installPath`-containing line from launcher script to infer directory to remove.
- If no `installPath` reference is found, only launcher entry is removed.

4. **Update flow**
- `game_update` lists `.update/*.sh`.
- Selected updater is sourced.
- `run_update()` is called and must exist.

## CLI Surface

- `-i`: install game
- `-r`: remove game
- `-u`: update game
- `-t`: show number of available games
- `-C`: clear cache
- `-D`: create desktop launcher
- `-L`: show license
- `-h`: show help
- `-N`: enable no-cache mode
- `-R`: force redownload mode

## Config and State

- Cache: `${XDG_CACHE_HOME:-$HOME/.cache}/linux-game-manager`
- Config base: `${XDG_CONFIG_HOME:-$HOME/.config}/storm-games/linux-game-manager`
- Settings overrides: `settings.conf` in config base
- Default install root: `${HOME}/.local/games`

## Contributor Pitfalls

- Mismatched `.install/<Game>.sh` vs `.launch/<Game>.game` names create orphaned or invisible entries.
- Missing `installPath` reference in launcher prevents full uninstall.
- `game_removal` parses the first `installPath` match in launcher text, so comments containing `installPath` can break removal path detection.
- Missing `run_update()` in `.update` scripts breaks update flow.
- Bypassing shared download helpers risks cache and validation regressions.
- For `uv`-based Python games that need `speechd`, copy host Python `speechd` bindings into a game-local directory and export `PYTHONPATH` from the launcher.