# LlamaMod launcher – UX review (2026-11-07)

Usability pass by "lxux" over the mod manager without the editor (the *launcher* edition that
Discord testers get, `edition.properties` `editor=false`; the full edition was checked too).
Used like a new, non-technical user on Xvfb (1920×1080 screen with a window manager; windows of
980×760, 1280×720 and 1920×1040), mouse only: the first-start wizard with
`~/Downloads/GROOVE_DK.iso` and its error cases (a text file named `.iso`, a folder without the
game, a truncated ISO, cancelling the copy), the Mods tab (all categories, every option editor,
badges, Apply/Restore, progress), Save games (unlock, edit, save, backups), Settings (resolution,
virtual desktop, Wine, theme, data folder, cache, set up again) and Play. The game ran on its own
display (`-Dllamamod.gameDisplay=:9`, supported by `GameLauncher.wineProcess`) with the private
PulseAudio of an apptest session (`PULSE_SERVER`); the game's audio went into the null sink. Game
messages were tested by killing the game, deleting `game/groove.exe`, and crashing it on purpose
(`ExeSmokeMod` with `crash=true`). Light and dark themes.

Not tested live: "not enough disk space" (no small file system without root; the check is
covered by code review), Windows (the antivirus notice is unchanged there).

## Before / after

| Before | After |
|---|---|
| ![](../img/app/ux_start_before.jpg) | ![](../img/app/ux_start_after.jpg) |
| The app opens with the mod list scrolled to the end (Visual, Cheats); Levels and Gameplay are out of sight. | The list opens at the top and keeps its place when it is rebuilt (Apply, theme). Short windows get a lower header. |
| ![](../img/app/ux_mods_before.jpg) | ![](../img/app/ux_mods_after.jpg) |
| Options have no explanation unless you hover (Worlds "all"? Checkpoint spacing "10" of what?). Descriptions talk about "far clip plane", "strafe", "rigid object models". | Every option is explained next to it. Mod descriptions say what happens in the game and which keys to press. |
| ![](../img/app/ux_wizard_before.jpg) | ![](../img/app/ux_wizard_after.jpg) |
| A text file is "shorter than expected (truncated?)", a wrong folder gets "expected Setup/…/Hd/groove.exe", a half-downloaded ISO is "Game found" and fails only after Set up. | Plain messages that say what to do; an incomplete ISO is caught at once, with both sizes. |
| ![](../img/app/ux_exe_before.jpg) | ![](../img/app/ux_exe_after.jpg) |
| On Linux a missing groove.exe is blamed on antivirus software and explained with Windows Defender menus. After Rebuild you have to click Play again. | Linux gets a short message; **Rebuild** writes the file and starts the game. |
| ![](../img/app/ux_saves_before.jpg) | ![](../img/app/ux_saves_after.jpg) |
| "lowest 4 bits of the coin count", "unknown item flag (bit 0)", "Cursor on", "Revert"; no hint how to restore a backup. | Plain wording, "Opens at", "Undo changes"; **Import…** starts in the backups folder and the hint says so. |
| ![](../img/app/ux_settings_before.jpg) | ![](../img/app/ux_settings_after.jpg) |
| "registry values ScreenW/ScreenH", "wine from PATH"; the mod cache shows 0.0 MB after applying 6 mods (stale). | "Automatic (1920x1052)" shows the real size, plain hints, a note on what *Set up again* keeps; the cache size is current. |
| ![](../img/app/ux_dark_before.jpg) | ![](../img/app/ux_dark_after.jpg) |
| Dark theme: the *modifies groove.exe* badge is dark orange on grey (barely readable). | A lighter badge text in the dark theme. |

| New: quitting a hidden or hung game | New: crash report |
|---|---|
| ![](../img/app/ux_quit_after.jpg) | ![](../img/app/ux_crash_after.jpg) |
| While the game runs, Play becomes **■ Quit game** (neutral colour) with a confirmation. | Shown as soon as Wine reports the crash (the game hides behind Wine's error window until that is closed), with Quit game / Open logs. |

![](../img/app/ux_av_linux_before.jpg)

*Before: on Linux every first Apply of an exe mod showed this Windows Defender notice. Now it is
shown on Windows only.*

## Findings

Severity: **H** = blocks or seriously misleads; **M** = friction every session; **L** = polish.

| # | Sev | Where | Finding | Status |
|---|---|---|---|---|
| 1 | H | Mods tab | Opens scrolled to the bottom: building the cards queues "scroll caret into view" for the last spinner/text field. Also after Apply and theme changes the list jumped. | **Fixed**: `reload()` restores the scroll position (top on the first build) after those events |
| 2 | H | Mod options | Option explanations existed only as tooltips. Non-technical users don't hover; "Worlds: all", "Checkpoint spacing 10", "Camera speed 3", "Fog: Scaled" are guesswork. | **Fixed**: grey explanation next to every option (wraps with the window) |
| 3 | H | Mod texts | Descriptions were written for developers ("far clip plane", "strafe", "rigid object models", "1/32 tile per tick", "Used by the level editor's Play button" in the launcher edition) and Free camera/Practice did not say which key switches them on. | **Fixed**: all 11 built-in mods rewritten: what changes in the game, keys (F7/F9, F5/F8, "can be changed below"), how to reach the Test World. Cheat codes kept as "(code ← → …)" |
| 4 | H | Wizard | A non-ISO file → "ISO image is shorter than expected (truncated?)"; a wrong folder → "expected Setup/…/Hd/groove.exe and Setup/…/Cd/wads". | **Fixed**: "This file is not a CD image (ISO)…" / "The game was not found here… (it contains a folder named Setup)" |
| 5 | H | Wizard | A truncated ISO (interrupted download) passed the check ("Game found: 187 files") and failed after Set up with the same cryptic message. | **Fixed**: `IsoImage` compares the file size with the end of the last file extent: "The ISO file is incomplete: it has 300 MB, but the CD image needs 582 MB. The download or copy was probably interrupted – copy the file again." |
| 6 | M | Wizard | Not enough space was only found after Set up ("Not enough disk space: … needed"). | **Fixed**: checked when the source is chosen (nearest existing parent of the data folder); the installer's message says to free space or choose another folder |
| 7 | M | Wizard | Cancel during the copy silently went back to the first page. Long messages were cut at the dialog edge. | **Fixed**: "Setup cancelled. Click Set up to continue – files already copied are kept." (resume works); messages wrap |
| 8 | H | Play | No way to stop the game from LlamaMod; under Wine a hung or hidden game blocked Apply and saves until the user found `wineserver -k`. | **Fixed**: the Play button reads **■ Quit game** while the game runs (neutral colour, confirmation "Progress since your last save is lost") |
| 9 | H | Play | A crash only produced "The game has ended." – and under Wine not even that while Wine's error window (often invisible behind/inside the virtual desktop) kept the process alive. | **Fixed**: `GameLauncher.crashReport()` reads game.log; the app shows "The game crashed" with advice (switch off the last mods / Restore original, report game.log), Quit game and Open logs – also while the error window is still open |
| 10 | M | Play / Linux | The antivirus notice (Windows Defender menus) appeared on Linux before every first exe-mod Apply; "groove.exe was removed or changed – probably by antivirus software" on Linux. | **Fixed**: notice on Windows only; Linux gets a plain "missing or changed – Rebuild" dialog |
| 11 | M | Play | After **Rebuild** in that dialog the user had to click Play again. | **Fixed**: Rebuild continues with the launch (also after Apply → Play) |
| 12 | M | Play | "Creating Wine prefix (once, takes a moment)", "Writing registry values". | **Fixed**: "Preparing Wine for the game (only the first time, may take a minute)", "Writing the game settings" |
| 13 | M | Settings | A wrong *Wine command* showed "Found: /wrong/path" and Play failed with "Cannot run program … error=2". | **Fixed**: "Not found: … – correct the command or leave the field empty", Play explains the same; the line updates when the field is left |
| 14 | M | Settings | The mod cache size was computed once at start (0.0 MB after applying 548 MB). | **Fixed**: the tab refreshes when opened |
| 15 | M | Settings | "Game resolution (registry values ScreenW/ScreenH)"; what "Automatic" means was only in a tooltip. | **Fixed**: the entry reads "Automatic (1920x1052)" (updates with *Run in a window*); plain hint mentions typing a custom size |
| 16 | M | Window | At 1280×720 (laptops) the 150 px header left room for 3½ mod cards. | **Fixed**: header is 104 px when the window is under 860 px tall (also the default 980×760 window) |
| 17 | M | Saves | "The game stores only the lowest 4 bits of the coin count (0–15). Collectible = unknown item flag (bit 0)." "Cursor on", "Revert". Status after saving printed the full backup path. Restoring a backup meant finding the folder by hand. | **Fixed**: plain hint, "Opens at", "Undo changes", "Save game 1 saved. The old version was backed up (Import… restores it)."; Import… opens in the backups folder |
| 18 | M | Status bar | "6 mod(s) active, 33 file(s) changed." / "Applying mods – done." – no next step, no duration. | **Fixed**: "Mods applied – 6 active (took 3 s). Click Play to start the game."; every task ends with "– done (took …)" |
| 19 | L | Mod cards | "v1 · testworld": ids mean nothing to players. | **Fixed**: "v1"; the id is in the tooltip (for the command line) |
| 20 | L | Dark theme | *modifies groove.exe* badge text nearly invisible. | **Fixed** |
| 21 | L | Hints | Grey hint text used `Label.disabledForeground` (about 3:1 contrast). | **Fixed**: `App.hintColor()` (blend of label and background, ~6:1), used for option, settings, wizard and save hints |
| 22 | L | Mods intro | Fixed 640 px wrap; long technical sentence. | **Fixed**: "Tick the mods you want, then click Apply and Play…" |
| 23 | L | Wizard done | "Choose mods on the Mods tab, edit save games…". | **Fixed**: "Next: tick the mods you like on the Mods tab, click Apply, then Play. The Save games tab can unlock worlds." |
| 24 | L | Launcher edition | No help/manual at all (the manual window lives in the editor plugin and needs an editor context). | Open – a Help button would need `ManualWindow` without `EditorContext` |
| 25 | L | Mirror mode | *Worlds* is free text ("all" / "1,3"); a list of checkboxes would be friendlier. | **Fixed** 2026-11-07: check boxes per world (new `ModOption.Type.MULTI`; stored "all"/"1,3" still load) |
| 26 | L | Wizard | The copy page shows the file name, not "123 of 568 MB" or a time. | **Fixed** 2026-11-07: "Copying 123 of 568 MB (file)" |
| 27 | L | Save games | The chapter table shows 4–5 rows at 720 px height. | **Fixed** 2026-11-07: lives moved into the world-map section (one header less), narrower number/check columns, centered coins – 6 rows at 1280×720 and 840×720 (was 4.5) |

## Changes (files)

* UI: `ui/MainFrame` (Quit game, crash dialog, Rebuild → continue, header height, task duration,
  settings refresh), `ui/ModsPanel` (inline option hints, scroll position, card height, badge,
  version label, status), `ui/SetupWizard` (free-space check, cancel message, wrapped messages),
  `ui/SettingsPanel`, `ui/SavesPanel`, `ui/AntivirusDialogs` (Windows-only notice, Linux text,
  `problem` returns the choice), `ui/App.hintColor()`, `messages.properties`.
* Platform: `IsoImage` (not-an-ISO and incomplete-ISO messages, extent check), `GameSource`
  (game-not-found message), `Installer` (space and damage messages, `notEnoughSpace`),
  `GameLauncher` (`crashReport()`, `isCommand()`, Wine-command check, progress texts).
* Mods (texts only, no behaviour or cache-key change): testworld, mirror, randomizer,
  boottolevel, cheats, debug, fog, freecam, introskip, practice, levels.
* Test: `platform/LauncherMessagesTest`.
* Manual: chapters 02 (wizard errors, Quit game, inline explanations, Save games/Settings
  labels), 18 (options explained, Windows-only antivirus), 20 (new "Setting up and playing"
  table, Wine command, first Play), generated mod reference, `img/app_mods.jpg`,
  `img/app_saves.jpg`.