linux-game-manager/.codex/skills/linux-game-manager-dev/references/core-map.md

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:

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.