# gamewrap Roadmap

## Purpose

`gamewrap` is a Steam-first Linux game launcher wrapper that keeps Steam launch options short while moving launch behavior into a readable, persistent config.

The project is designed to make features like MangoHud and GameMode easier to use without requiring users to remember long launch commands, environment variables, or per-game flag combinations.

Core product goals:
- keep Steam launch options simple
- prefer human-friendly configuration over flag-heavy one-off commands
- fail clearly when launch requirements are not met
- keep runtime overhead low
- support both quick default usage and deeper profile-based customization

## Current Direction

The current preferred Steam usage is:

```text
gamewrap %command%
```

The preferred low-maintenance install approach is:
1. install with `cargo install`
2. ensure `~/.cargo/bin` is on PATH in the desktop session

This lets Steam resolve `gamewrap` by name without committing to long-term package maintenance yet.

## Current Feature Set

Implemented features:
- Steam-first launcher flow with `gamewrap %command%`
- Default launch mode with MangoHud and GameMode
- Friendly setting names for all launch options
- Named profiles with full inheritance chains and cycle detection
- Per-profile environment variable overrides (`profile env set/unset/list/clear`)
- Manual executable-to-profile bindings
- Observed game history with launch count, timestamps, and display names
- Play time tracking per game (when post-launch hook is configured)
- `game rename` for human-readable game names
- `game forget` to remove entries from observed history
- `gamewrap last` to see the most recently played game
- gamescope Wayland compositor integration
- vkBasalt post-processing integration
- FPS cap via MangoHud
- Proton esync/fsync/large-address-aware controls
- Pre-launch and post-launch shell hooks
- `status` command
- `doctor` preflight checks with color-coded output
- `dry-run` launch plan preview
- `config edit` to open config in `$EDITOR`
- Config and profile export/import for sharing
- `profile tree` for visualizing inheritance chains
- `notify test` for graphical notification verification
- ANSI color output (respects NO_COLOR, CLICOLOR, CLICOLOR_FORCE)
- Shell completion with live candidates (profiles, games, settings)
- Clear runtime dependency checks and actionable error messages

Friendly settings supported:
- `overlay`, `performance`, `steam-host-libs`, `game-libs`, `verbose`
- `gamescope`, `gamescope-width`, `gamescope-height`, `gamescope-fps`
- `fps-cap`, `vkbasalt`
- `esync`, `fsync`, `large-address-aware`
- `pre-launch`, `post-launch`
- `env-vars` (via `profile env` subcommands)

## v1 Done Criteria

The project can be considered functionally complete for v1 when all of the following are true:

- [x] Steam launch works reliably with the chosen install method
- [x] MangoHud enable/disable works correctly
- [x] GameMode enable/disable works correctly
- [x] `doctor`, `status`, and `dry-run` are trustworthy for normal troubleshooting
- [x] launch failures are visible and understandable
- [x] README and CLI help are clear enough for a new user
- [x] no major known bugs remain in the core launch path
- [x] native Linux games validated in real testing
- [x] Proton / Windows games validated in real testing
- [x] one intentional failure case tested

**v1 complete — 2026-05-31.**

## Validation Still Desired

Real-world validation to finish before calling v1 done:
- test at least one native Linux game
- test at least one Proton / Windows game
- test one intentional failure case
- confirm Steam launch behavior with the preferred install method
- confirm notification behavior for internal launcher failures
- confirm that profile binding works on an actual game executable

## Packaging and Distribution Plan

Long-term packaging direction:
- distro-native packages first
- `cargo install` remains supported but is not the ideal end-user distribution path

Planned packaging targets:
- Arch Linux / AUR
- Debian / Ubuntu
- Fedora / RPM

Packaging goals:
- install `gamewrap` to a system-visible path such as `/usr/bin/gamewrap`
- allow Steam launch options to use `gamewrap %command%`
- avoid requiring absolute paths for normal packaged installs

Packaging status:
- deferred for now in favor of low maintenance
- still an explicit project direction, not abandoned

Repository:
- Gitea: https://git.44r0n.cc/44r0n7/gamewrap.git (canonical for now)
- Issue tracker: https://git.44r0n.cc/44r0n7/gamewrap/issues

Still undecided:
- homepage URL
- release hosting / distribution channels
- whether to mirror to GitHub

## Deferred Feature Expansion

Features that were deferred from the initial scope and are now implemented:
- ✓ `gamescope` integration
- ✓ `vkBasalt` integration
- ✓ Custom environment presets (per-profile env var overrides)
- ✓ Proton and Wine compatibility toggles (esync, fsync, large-address-aware)

Features still deferred:
- Benchmark and recording profile presets (named templates that bundle several settings)
- Additional launcher helpers beyond the current set

## Recommended Expansion Order

Items 1–3 are now implemented. Remaining if development continues:

4. Benchmark / recording profile presets — named templates that bundle several settings into a shareable starting point
5. Graphics API detection (advisory only — see separate section)
6. Additional launcher helpers only if they clearly improve the main use case

## Future Proton and Compatibility Controls

One planned expansion area is support for common Steam/Proton launch adjustments that users often copy from compatibility guides, community comments, or ProtonDB reports.

Examples of future controls that may be worth supporting:
- DXVK-related toggles
- VKD3D-related toggles
- esync/fsync toggles
- Wine debug environment controls
- fullscreen and compositor-related tweaks
- launch-time environment overrides for specific games
- Proton-specific compatibility presets that bundle several known-good settings

This should not become a free-form dump of obscure environment variables by default. The intended direction is:
- expose the most common useful adjustments with friendly names
- keep raw environment overrides available only as an advanced escape hatch if ever added
- prefer reusable presets and profiles over forcing users to remember low-level variables
- use `doctor` and help text to explain what a toggle actually changes

Potential sources of future ideas:
- recurring compatibility patterns seen in ProtonDB reports
- common launch command snippets shared in Linux gaming communities
- settings that repeatedly solve real issues in actual testing

Guardrails for this work:
- do not blindly mirror every ProtonDB workaround
- avoid adding toggles that are highly game-specific unless they can be grouped into a sensible preset model
- keep the main UX readable and non-intimidating
- require a clear explanation in help text for every added compatibility control

## Graphics API Detection (Maybe)

A potential future addition: detect a game's graphics API at launch time and use that to surface
warnings or skip inapplicable settings. Not on the roadmap yet, but worth revisiting.

Specific cases where it would help:

- **vkBasalt safety** — vkBasalt only works with Vulkan. For OpenGL or WineD3D games, `ENABLE_VKBASALT=1`
  silently does nothing. Detection could skip the env var or warn in `doctor`.
- **Gamescope compatibility** — Gamescope is Vulkan-only. If `gamescope = on` is set but the game uses
  OpenGL, it will fail or fall back unexpectedly. A preflight warning would catch this.
- **DXVK vs VKD3D-Proton env hints** — Per-profile overrides like `DXVK_ASYNC 1` only matter for D3D9/10/11
  games (DXVK). D3D12 games use VKD3D-Proton with a different set of vars. Detection could surface
  a mismatch warning when running `doctor`.
- **MangoHud invocation method** — MangoHud works as both a command prefix and an env var injection. The
  env var path works better for some Vulkan games. Detection could pick the right method.

How detection would likely work in practice:
- Check for `d3d9.dll`/`d3d11.dll`/`dxgi.dll` in the game directory → DXVK (D3D9/10/11 via Vulkan)
- Check for `d3d12.dll` → VKD3D-Proton (D3D12 via Vulkan)
- Check for `.dxvk-cache` / `.d3d12.cache` files → reliable secondary signals
- Native Linux ELFs: inspect imported libs with `ldd` or `file` — harder, lower priority

Guardrails if this is ever added:
- Detection should be advisory only — never silently override user config
- Emit warnings in `doctor` and `dry-run`, not at actual launch time
- Degrade gracefully when detection is inconclusive (most common case)
- Do not make profile selection automatic based on detection results

The "avoid" note in Product Boundaries refers to _automatic profile selection_ based on detection,
not to using detection for diagnostics and warnings. Those are meaningfully different.

## Product Boundaries

Things `gamewrap` should continue to optimize for:
- simple Steam usage
- low system impact
- minimal always-on behavior
- understandable configuration
- useful diagnostics

Things to avoid unless clearly justified:
- automatic profile selection based on graphics API or runtime detection (advisory warnings are fine)
- heavy background services
- large dependency trees just to support optional extras
- turning the project into a general desktop/session manager

## Installation Strategy for Now

Short-term recommended install strategy:
- `cargo install --path . --force` — installs to `~/.cargo/bin/gamewrap`
- Ensure `~/.cargo/bin` is on PATH in your desktop session so Steam can find it by name

Reason:
- low maintenance
- easy updates
- Steam can resolve `gamewrap` by name if `~/.cargo/bin` is on session PATH
- no distro package maintenance burden yet

## Dependency Maintenance (post-1.0)

Checked 2026-05-31. Most crates are on current patch versions via `cargo update`. Two deferred upgrades:

- **toml 0.8 → 1.x**: top-level `from_str`/`to_string_pretty` likely unchanged but the 1.x release has low-level Deserializer/Serializer API changes. Verify against 1.x docs before upgrading. Low urgency — 0.8 is still maintained.
- **owo-colors 1.x → 4.x**: major version jump. Our usage (`.green()`, `.bold()`, `.dimmed()`, `.cyan()`, `OwoColorize`) is fundamental and unlikely to have changed, but read the changelog before upgrading. Low urgency — 1.x works fine.
- **clap_complete `unstable-dynamic` feature**: may have been renamed to `unstable-command` in 4.6.x. Run `cargo update && cargo test` — if it fails, rename the feature flag in `Cargo.toml`. Low risk, one-line fix if needed.

## Notes for Future Work

Before starting packaging or deferred features, re-check:
- whether the install story should remain PATH-based for personal use
- whether the project is going public
- whether package maintenance is worth the overhead
- whether v1 behavior is stable enough to freeze the main CLI/config model