gamewrap/docs/roadmap.md

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:

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:

• Steam launch works reliably with the chosen install method
• MangoHud enable/disable works correctly
• GameMode enable/disable works correctly
• doctor, status, and dry-run are trustworthy for normal troubleshooting
• launch failures are visible and understandable
• README and CLI help are clear enough for a new user
• no major known bugs remain in the core launch path
• native Linux games validated in real testing
• Proton / Windows games validated in real testing
• 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