248 lines
11 KiB
Markdown
248 lines
11 KiB
Markdown
# 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
|