llamamod/notes/dev/ux-review-launcher.md

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
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.
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.
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.
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.
"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.
"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.
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
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.

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.