Nix Config Umu Game

Installing a Windows game launcher with umu

The bundled scripts/umu-install.nu renders the files in scripts/templates/. It creates a prefix, runs the installer, and writes launchers. Use the Nix DW-Proton default unless research identifies a specific installed release; then select it with PROTONPATH and pin that path in the game's conf. Every per-game detail lives under ~/Games/, never in this repo.

Bundled files

• scripts/umu-install.nu: installer and template renderer
• scripts/templates/*.tpl: non-executable templates; placeholders use @NAME@
• scripts/tests/test_install.py: offline regression tests

Layout

• ~/Games/global.conf: optional, sourced by every game before its own conf
• ~/Games/<name>/prefix: the Wine prefix (WINEPREFIX)
• ~/Games/<name>/conf: optional per-game overrides (ENABLE_MANGOHUD=0, ...)
• ~/Games/<name>/prelaunch: optional executable, run before every launch
• ~/Games/<name>/run: generated launcher
• ~/Games/<name>/exec: generated helper: exec <exe-or-tool> [args...]
• ~/Games/<name>/<name>.desktop: generated desktop entry
• ~/Games/<name>/uninstall: generated: drop the desktop entry and (with y) the dir

Run, from the repo root:

nu .agents/skills/nix-config-umu-game/scripts/umu-install.nu <name> <setup.exe> <launcher> [gameid] [setup-args...]

<launcher> is relative to the prefix and GAMEID defaults to umu-default. At install, PROTONPATH resolves from $PROTONPATH, $UMU_PROTONPATH (the Nix-provided DW-Proton), then Steam's per-user compatibilitytools.d. At launch, the generated run script checks the current $PROTONPATH and $UMU_PROTONPATH before its saved default. A game's conf is sourced after those defaults, so set PROTONPATH there to pin a particular installed version across launches.

Procedure

1. Research first. Mandatory before inventing any fix: a documented fix beats a custom patch every time. Check the game's Lutris installer YAML as data only (https://lutris.net/api/installers/<game-slug> encodes winetricks verbs, write_file content, and prelaunch_command; do not install or run Lutris), then ProtonDB (protondb.com/app/<id>), Steam Community / r/linux_gaming threads, and GitHub issues for the launcher and Proton. Record whether reports require a Proton family and exact release. If no exact release is required, use the Nix-provided DW-Proton default. If one is required, inspect $UMU_PROTONPATH and installed Steam tools under ~/.local/share/Steam/compatibilitytools.d/ or ~/.steam/root/compatibilitytools.d/; select the matching installed path with PROTONPATH. Prefix the installer command with PROTONPATH="<selected-tool-directory>" and set the same value in the game's conf to pin it across launches; otherwise the runtime Nix UMU_PROTONPATH may take precedence. If the required release is absent from Nix and Steam, stop and ask the user before downloading it from elsewhere. Do not substitute a different release or use ProtonPlus/Lutris to fetch one.
2. Slug. Pick a lowercase <name> (e.g. wuthering-waves).
3. GAMEID. The umu database maps a title to a GAMEID whose protonfixes add CJK fonts, drop the SteamOS/SteamDeck vars, and keep Wine's Documents inside the prefix. Without it some games save into the host home or the wrong prefix. Fetch https://raw.githubusercontent.com/Open-Wine-Components/umu-database/main/umu-database.csv, match the title, and use its umu-<id>; if nothing matches, leave the default.
4. Download. curl -fL <url> -o ~/Games/<name>/setup.exe. The CN store pages are JS/token driven, so the user normally supplies the URL or the file itself.
5. Install. Run the bundled script. The first run also downloads umu's Steam runtime and the protonfix fonts, so it is slow. The installer is usually a GUI the user clicks through, but extra args after [gameid] go to setup.exe, so try a silent flag first (/S, /quiet, --silent); if it ignores them, fall back to clicking. On some CN installers the last page auto-starts the launcher. The script writes run/exec even if the installer exits non-zero, so a killed installer is not fatal.
6. Find the launcher. If <launcher> is only known after install, locate it under ~/Games/<name>/prefix/drive_c and set LAUNCHER in ~/Games/<name>/conf. Re-running the installer script invokes setup.exe again; only do so if that installer is known to handle reruns.
7. Per-game fix. Port step 1 findings into ~/Games/<name>/prelaunch (bash, chmod +x): winetricks verbs via ~/Games/<name>/exec winetricks <verbs>, file patches or registry tweaks via ~/Games/<name>/exec. Never commit the fix to this repo.
8. Re-run every launch, not once. A launcher that self-updates overwrites files it patches, so those patches belong in prelaunch.
9. Verify. ~/Games/<name>/run must open a visible launcher window. MangoHud is enabled by default with FPS and frame time at the top-left; set ENABLE_MANGOHUD=0 in conf to disable it, or override MANGOHUD_CONFIG. Re-running prelaunch must be idempotent. The launcher may then download the game body itself (tens of GB) -- that is the launcher's job, not this skill's, so the install is done once the window is usable. A crawl usually means the proxy: the launcher probes the CDN itself and mihomo routes that probe through a distant node, so the download starts from a far mirror; routing is in the mihomo README. ENABLE_LOG=1 captures last-run.log when something misbehaves.

Invisible / transparent launcher window

A WebView2/.NET (WPF) launcher that shows an empty or fully transparent window is rendering with AllowsTransparency. Fix the DLL, not Wine:

1. find ~/Games/<name>/prefix/drive_c -iname 'launcher_main.dll' (usually under a X.Y.Z.W version dir).
2. Rename that WPF property in place, keeping the byte length so PE offsets stay valid: bbe -e 's/\x12AllowsTransparency/\x09IsEnabled\x1bA\x00\x03AAAAA/' <dll>.
3. Put it in ~/Games/<name>/prelaunch so it is re-applied on every launch, because a launcher self-update restores the original DLL. Restart the launcher after patching.

Half-width tile instead of fullscreen

Niri tiles a new window into a column of default-column-width { proportion 0.500000; } (50%), and a launcher that only opens a large borderless window cannot take over the screen by itself: with a 4K panel at scale 1.5 Niri's logical space is 2560x1440, so a window asking for the physical 3840x2160 becomes an ordinary half-width tile. Nothing is broken -- the umu app-id is just not covered by a rule.

Every umu/Proton game reports steam_app_<GAMEID>. In this repo home/linux/gui/niri/conf/windowrules.kdl matches app-id="^steam_app_[0-9]+$" and sets open-fullscreen true, so games open fullscreen without a per-game rule. niri validate checks the live config, Mod+Shift+F (fullscreen-window) toggles an already-open window, and setting the in-game resolution to the compositor's logical size (2560x1440 here) avoids the mismatch too.

A launcher shares that app id with its game, so the rule also catches the launcher's own windows: a helper that is still untitled while it maps, and the announcement popup (公告 / Announcement), which on this launcher renders as a pure white rectangle. Fullscreening either one buries the UI that opened it, so both are excluded. A window rule applies when a window opens, so an already-open offender needs Mod+Shift+F on it or a relaunch; drop open-fullscreen true altogether if a launcher keeps surprising you -- the game then costs one Mod+Shift+F per session instead.