launchlayer

#!/usr/bin/env bash
# LaunchLayer — layered game launch orchestration for Steam and beyond.
#
# Steam launch options MUST include %command%, e.g.:
#   "/path/to/launchlayer" %command%
#
# Config layers (in order):
#   launch.d/profiles/<profile>.env (LAUNCHLAYER_PROFILE or auto-detected)
#   launch.d/default.env
#   launch.d/presets/*.env (via INCLUDE= or auto-selected standard/native)
#   games/<AppID>.env (GAMES_DIR / LAUNCHLAYER_GAMES_DIR)
#
# Utility subcommands:
#   --list-games [--configured] [--json] [--grep NAME]
#   --init-appid APPID|NAME [preset] [--force]
#   --paths APPID|NAME [--json]       shader cache, compatdata, install paths
#   --show-config APPID|NAME [--json] resolved config + launch chain
#   --edit-appid APPID|NAME           open/create per-game config in $EDITOR
#   --validate-config [APPID|all]     lint .env files
#   --scan-anticheat [--update-list]    find EAC/BattlEye vs anticheat-appids.txt
#   --scan-detections                   audit heuristic vs list mismatches + hints
#   --cache-report [--min-gb N] [--grep NAME] [--json] [--shader-only|--compat-only]
#   --launch-stats [APPID]            summarize launch.log
#   --status [AppID]                  runtime and cache state
#   --dry-run %command%               print env + launch chain without running
#   --show-cpu-topology               V-Cache CCD hints for X3D_CPUS
#   --detect-environment              print auto-detected platform/hardware state
#   --help, -h                        grouped command reference
#   --version, -V                     version and install paths
#   --completions [status|enable|disable|print] [--shell bash|zsh|fish|all]
#   --doctor [--json]                 full environment + config health check
#   --setup [--completions] [--systemd] [--symlink] [--print-launch-option]
#   --init-appid APPID|NAME [preset] [--force]
#   --bulk-set-include PRESET [--all-configured|--all-installed] [--grep NAME] [APPID|NAME...]
#   --export-config / --backup-config / --import-config / --restore-backup / --prune-backups
#   --backup-timer / --backup-prefs / --tui-prefs / --hub-prefs
#   --hub-fingerprint / --hub-publish / --hub-update / --hub-delete
#   --hub-recommend / --hub-search / --hub-apply
#   --tui                             interactive game/config browser
#   --install-systemd                 install user maintenance timer (resolved paths)
#   --sysctl [status|install]         vm.max_map_count helper (install needs root)
#   --pause-vram-hogs / --resume-vram-hogs / --cleanup-stale-launch [pid]
#
# Config root: set LAUNCHLAYER_CONFIG_DIR to use launch.d/ outside the script tree.
#
# Machine profiles (layered, before default.env):
#   LAUNCHLAYER_PROFILES=steam-deck,flatpak-steam   or legacy LAUNCHLAYER_PROFILE=
#
# Per-game .env keys (see launch.d/presets/ and examples/games/2357570.env):
#   INCLUDE=presets/competitive.env
#   DLSS_SWAPPER=1                   # or dll for dlss-swapper-dll (manual DLL path)
#     https://wiki.cachyos.org/configuration/gaming/#forcing-the-latest-dlss-preset
#   PROTON_DLSS_UPGRADE / PROTON_FSR4_UPGRADE / PROTON_XESS_UPGRADE
#   SHADER_CACHE_BOOST=1             # raise Mesa/NVIDIA shader cache size limits
#   LAUNCH_WRAPPERS=""               LAUNCH_WRAPPERS_BEFORE=""  (don't also list dlss-swapper)
#   GAME_EXTRA_ARGS="-flag1 -flag2"  UNSET_VARS="DXVK_ASYNC"
#   PRE_LAUNCH_CMD=""  POST_LAUNCH_CMD=""
#   FORCE_NATIVE=1 / FORCE_PROTON=1  BENCHMARK=1  DEBUG=1
#   GAMEMODE MANGOHUD GAMESCOPE VRAM_HOGS NETWORK_TUNE PIPEWIRE_LOW_LATENCY
#   GPU_POWER_CHECK DISK_PREFLIGHT_MIN_GB GPU_VRAM_PROCESS_MIN_MB CONCURRENT_LAUNCH_GUARD
#   SHADER_CACHE_* COMPATDATA_* PROTON_* DXVK_* VKD3D_* __GL_*
#
# Module layout (lib/):
#   common.sh       — paths, globals, logging
#   keys.sh         — config key registry
#   load-modules.sh — shared source order for lib/* subtrees
#   platform/       — paths, os, steam-detect, gpu, desktop, profiles
#   tools.sh        — optional dependency detection
#   config.sh       — layered .env loading
#   vdf.sh          — libraryfolders.vdf parsing
#   steam/          — library discovery, native/EAC detection (library.sh, detect.sh)
#   hardware/       — cpu, compositors/, display detection
#   detected-defaults.sh — auto-detected machine defaults
#   gpu.sh          — GPU-specific launch helpers
#   preflight.sh    — pre-launch checks
#   runtime/        — summary, tuning, chain, logging
#   vram.sh         — VRAM hog pause/resume
#   inspect/        — show, maintenance, reports, validation, backup
#   cli/            — colors, json, help; cli.sh — version, subcommands, flags
#   prefs/          — paths, backup, tui preference helpers (hub prefs in lib/hub/)
#   completions/    — core, shells, helpers, cli
#   setup/          — sysctl, systemd, doctor, onboard
#   commands/       — status, environment, games, hub, dispatch
#   tui/            — config, primitives, menus, main loop
#   launch.sh       — main launch orchestration
#
# Other repo paths:
#   share/launchlayer/templates/  user pref templates (backup.conf, tui.conf, hub.conf)
#   share/launchlayer/sysctl/     vm.max_map_count drop-in (elasticsearch.conf)
#   share/launchlayer/systemd/    user systemd unit templates
#   share/launchlayer/completions/ shell completion scripts
#   examples/games/               example per-game .env files
#   scripts/                      one-time root setup (setup-workstation-tuning.sh)

set -euo pipefail

# Requires bash 4.2+ (associative arrays, mapfile, etc.).
if (( BASH_VERSINFO[0] < 4 || (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] < 2) )); then
	echo "launchlayer: requires bash >= 4.2 (found ${BASH_VERSION})" >&2
	exit 1
fi

# Resolve script location and config root (LAUNCHLAYER_CONFIG_DIR overrides launch.d path).
# Follow symlinks so ~/.local/bin/launchlayer still finds lib/ next to the real script.
_script_source="${BASH_SOURCE[0]}"
if _script_resolved="$(readlink -f "$_script_source" 2>/dev/null)" && [[ -n "$_script_resolved" ]]; then
	_script_source="$_script_resolved"
elif command -v python3 >/dev/null 2>&1; then
	_script_resolved="$(python3 -c 'import os, sys; print(os.path.realpath(sys.argv[1]))' "$_script_source" 2>/dev/null || true)"
	[[ -n "$_script_resolved" ]] && _script_source="$_script_resolved"
fi
SCRIPT_DIR="$(cd "$(dirname "$_script_source")" && pwd)"
unset _script_source _script_resolved
# Legacy env var aliases (deprecated).
: "${LAUNCHLAYER_CONFIG_DIR:=${STEAM_LAUNCH_CONFIG_DIR:-}}"
if [[ -n "${LAUNCHLAYER_CONFIG_DIR:-}" ]]; then
	CONFIG_DIR="$(cd "$LAUNCHLAYER_CONFIG_DIR" && pwd)"
else
	CONFIG_DIR="$SCRIPT_DIR"
fi
LIB_DIR="$SCRIPT_DIR/lib"

# Exposed for the watchdog subprocess which re-invokes this script.
# Load modules in dependency order.
# shellcheck source=lib/common.sh
source "$LIB_DIR/common.sh"
# shellcheck source=lib/keys.sh
source "$LIB_DIR/keys.sh"
# shellcheck source=lib/load-modules.sh
source "$LIB_DIR/load-modules.sh"
launchlayer_load_pre_main
LAUNCHLAYER_MAIN_SCRIPT="$(realpath_portable "${BASH_SOURCE[0]}")"
launchlayer_load_post_main

# Global flags (--quiet, --verbose) apply to subcommands and game launches.
mapfile -t _launchlayer_argv < <(cli_parse_global_flags "$@")
set -- "${_launchlayer_argv[@]}"
unset _launchlayer_argv

# --dry-run must be stripped before subcommand or launch dispatch.
if [[ "${1:-}" == "--dry-run" ]]; then
	DRY_RUN=1
	shift
fi

# Utility verbs exit here; unrecognized --flags error instead of launching.
if [[ $# -gt 0 && "${1:-}" == --* && "${1:-}" != "--dry-run" ]]; then
	rc=0
	handle_subcommand "$@" || rc=$?
	if (( rc == 0 )); then
		exit 0
	fi
	if cli_is_known_subcommand "${1:-}"; then
		exit "$rc"
	fi
	cli_unknown_subcommand "${1:-}"
	exit 1
fi

if [[ $# -eq 0 ]]; then
	if [[ -t 0 && -t 1 ]] && command -v fzf >/dev/null 2>&1; then
		run_tui
		exit 0
	fi
	print_usage_brief
	exit 0
fi

run_game_launch "$@"