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

Level editor – UX review (2026-11-07)

Usability pass by "edux": the editor used like a new user on Xvfb (1920×1080 screen; windows of 1500×920, 1920×1050 and 1280×720), mouse and keyboard only, following the manual's tutorials (Your first level, Make a parkour, Edit an original level, Import a Blender model) plus placing objects, the Objects/Environment/Textures panels, Shift+F5, dark theme, F1 help and Preferences. Play-tests ran from the editor's own F5 / Shift+F5 flow, with the game on its own display and the editor started with the private PulseAudio server of an apptest session (PULSE_SERVER and -Dllamamod.gameDisplay are inherited by GameLauncher; the game's audio went into the private null sink). Both play-tests (new flat-floor level, Village from the camera position) started straight in the level, and Escape in the game returned to the editor.

Before / after

Before	After
A 1920-wide window: the Inspector is 170 px wide and shows no values at all. Side docks have two rows of tabs.	The docks get their intended widths (290 / 340 px). Side-dock tabs are icons with the active one named. The engine fields of the object type are folded away.
The Brush tool's buttons read "Bl…", "Pl…", the texture names "gr…", the numbers show "0,5".	Full labels and a decimal point.
The Coin tool's options are cut off: only the top pixels of the fields are visible.	The options are on one line, or wrap to a second row in narrow windows.
Help comes before Geometry, and the shortcuts are German ("Strg", "Umschalt").	The menus are File … Geometry, Tools, Help, and the keys are named "Ctrl", "Shift".
Open original level: the description is cut at the right edge, and the selected row's id is grey on orange.	The text wraps and the id is readable.
A 1280×720 window: the right dock is squeezed to 130 px. Also, Esc did not close the dialog, so it was still open and blocked every key.	The docks keep their sizes and the tool options wrap. Esc closes dialogs.

New: Play while the game still runs offers to quit it.

Findings

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

#	Sev	Where	Finding	Status
1	H	Docks (DockLayout.applySizes)	The right dock started at about 170 px instead of 340. The inner split's width was read before the outer divider moved. Effect: Inspector values and Brush buttons are invisible or truncated in every session that has no saved layout.	Fixed: lay out the outer split first
2	H	Window resize	When the window shrinks (1280×720, a laptop), the GL canvas's large minimum size squeezes the side docks to about 130 px.	Fixed: the viewport card has a small minimum size
3	H	Inspector sections	A section kept the height it had when created. Wrapped text and later rows (the Llama's waypoint buttons, the parameter descriptions) were clipped.	Fixed: the maximum height follows the preferred height
4	H	Inspector rows	Labels had a minimum height of 10 px. When the GridBag fell back to minimum sizes, every descender was cut ("Obiect tvpe").	Fixed
5	H	Tool options bar	Options wider than the space left of Snap/View/Layers (the Coin, Place and Zones tools at 1500 px, the Brush tool at 1280 px) went to a second FlowLayout row that the bar did not grow for, so they were invisible.	Fixed: WrapLayout, the bar grows to two rows; all tools have the same bar height, so the viewport no longer jumps when you switch tools
6	H	Dialogs	Esc did not close the editor's own dialogs (Open original level, New level, Level settings, Import mesh …). A dialog half off-screen then silently swallowed all keys.	Fixed: Esc acts as the close button on every JDialog that has no Esc binding of its own
7	M	Side docks	Four tabs in 290 px wrapped into two rows that swap places when clicked (Swing's wrap layout). Clicks hit the wrong row, and typing into the filter field fired tool shortcuts.	Fixed: one scrolling row; in the side docks inactive tabs show only their icon (title as tooltip) and only the active tab has a ×. The asset, environment and texture sub-tabs also use one scrolling row
8	M	Locale (Main)	On a German system: menu keys read "Strg+Umschalt+D" and "Strg+Öffnende Klammer", spinners showed "0,75" next to "0.25", and Swing dialogs said "Ja"/"Nein" while the manual says Yes. Cause: ImageIO loads AWT before anything else.	Fixed: Locale.setDefault(ENGLISH) as the first line of Main.main (framework change, see below)
9	M	Menu bar	Geometry (a plugin menu) came after Help.	Fixed: plugin menus go before Tools, and Help is last
10	M	View menu	There were two Panels submenus (the Textures plugin's View/Panels entry and the shell's own), and a separator between every submenu.	Fixed: plugin entries are merged into the one Panels menu, and the submenus form one block
11	M	Toolbar	Tools were sorted by order number only, so the groups interleaved (Place objects, Brush, Coins, Tiles, Waypoints, Collision …) with separators in between. Two tools had the same icon (Zones and Zones & triggers).	Fixed: grouped in workflow order Select · Geometry · Texture paint · Objects · Environment. Zones & triggers uses the trigger icon
12	M	Start-up	The last tool was restored (for example Brush or Scale), so the first click in a freshly opened level drew a brush.	Fixed: the editor always starts with Select
13	M	Play / F5	"The game is still running. Quit it first" was a dead end, because the game window is often hidden (another display, or full screen behind the editor).	Fixed: Quit game and play kills our own game (GameLauncher.kill), waits for the previous play-test to restore the mod selection, then starts. Tested: the old game was closed and the new one started in the village
14	M	Inspector, objects	Every object showed the engine fields of its type (code offset, variables, slots, type flags, extra memory) above Transform.	Fixed: they moved to a Type details section that is folded at first. Object type stays in Type
15	M	Inspector number fields	Long values showed their end ("6238" for 40.6238, "396, 4096, 8192").	Fixed: the caret goes to the start and the full value is in the tooltip. Truncated labels ("Flags (2 = not s…") also get a tooltip
16	M	Outliner filter	Typing "Coin" showed a collapsed Coin group (depth 3), so the matches needed another click.	Fixed: groups are expanded down to depth 4 while filtering
17	M	Move / rotate / scale	No feedback during a drag: how far, which snap step.	Fixed: the status bar shows "Move 1 item Δ x 0.50 y 0.00 z 0.00 cells (snap 0.25, Ctrl = free)", the rotation angle and the scale factors
18	M	Assets panel	Tile models is empty in a new level ("0 of 0" and a white area). The Imported tab gave no hint either.	Fixed: grey hints ("no tile models yet … the Library tab has ready-made pieces", "File → Import mesh…", "Nothing matches the filter", "Open a level …")
19	M	Window size	The first-start size of 1500×920 is larger than a 1366×768 laptop screen, so the window hung over the edges.	Fixed: the size is clamped to the screen, and the window is maximized when it doesn't fit
20	L	Open original level	The description was clipped (the dialog was packed before the text was set), and the selected row's id was grey on orange.	Fixed
21	L	Status bar	The last-build label was cut ("Built 03:37:16 · 6158 KB · 2 w…").	Fixed: "Built 03:37 · 6.0 MB · 2 warnings"
22	M	New level	A new level keeps the base level's 13 zones and 30 lights. Their outlines float far from the 16×14 floor (pink boxes in the sky), which is confusing in an empty level.	Fixed (0.2.0): new projects keep only the start zone and the directional lights; teleport zones, point lights, waypoints and region masks of the base are removed (stored as edits, old projects unchanged). Directional light markers are drawn above the player start
23	M	Play-test	While the game runs, nothing in the editor says so: the status line falls back to "Ready" after 6 s.	Fixed (edui): EditorContext.setGameRunning(what, stop); while the play-test game runs the status bar shows a green "Game running: " badge and the toolbar Play button becomes Stop game; both reset when the watcher sees the game exit (img/editor/ui_playtest_running.jpg)
24	L	Shift+F5	There is no mark in the viewport showing which point "the middle of the view" is.	Fixed (edui): crosshair in the middle of the viewport while Shift is held (300 ms delay, hidden while a mouse button is down) or while Play from camera position is hovered; green = valid start, red = not (status bar says why) – tools.playtest.PlayHereMarker, Viewport.setHudOverlay
25	L	Outliner	Rows show technical ids (brush:n19, strat:6). Several brushes are all called "Floor".	Fixed (edui): rows read "Coin 3", "Floor 2", "Waypoint 4", "Chain 1 – Llama", "Light 2", "Model 12 (…)", position/height in the grey column; the id is the row tooltip (filter still matches ids)
26	L	Inspector hints	Help texts in tool sections use fixed 215–230 px HTML widths, so they don't use a wider dock.	Fixed (edui): Widgets.wrappingLabel(html) wraps at the container/viewport width (Inspector hints, GeoWidgets.hint, environment Ui.Form.note, ParamsSection.note)
27	L	Problems panel	It shows "No problems." before any check has run.	Not fixed
28	L	Duplicates	Objects can be placed from both the Objects panel (left) and Assets → Objects (bottom).	Kept: both are documented, and drag & drop needs the grid
29	L	Menus	Key names come from AWT ("Ctrl+Open Bracket"), while the manual writes "Ctrl+[".	Not fixed (would need a custom accelerator renderer)
30	L	Toolbar	The tool buttons stay enabled while no level is open.	Not fixed (harmless)

These worked well: the start page with recent projects, the New level dialog, crash recovery (a killed editor offered Recover and restored the level), coin lines, Quick setups with options-bar exit targets, Death plane height…, Array duplicate, the Import mesh dialog (preview, size, warnings, click-to-place), context help (F1 opened the chapter of the panel under the mouse), the Shift+F5 hint when aiming at the sky, and the dark theme (readable; the selected Snap toggle has rather low contrast).

Changes (files)

• editor/ui: DockLayout (sizes, scroll tabs, compact side tabs, minimum viewport size), ToolOptionsBar + new WrapLayout, EditorWindow (menu order, merged Panels menu, start tool, window size), EditorExtensions.tools() (grouped order), EditorApp (Esc closes dialogs), OpenOriginalDialog, PlayTest (status text), panels/InspectorPanel, panels/OutlinerPanel, panels/AssetBrowserPanel, tools/TransformSupport.
• Plugins (one-liners): tools/objects/ZoneTool (icon), tools/environment/EnvironmentPanel and tools/textures/TextureManagerPanel (scroll tabs), tools/playtest/PlaytestRunner (Quit game and play).
• Framework: Main.java: Locale.setDefault(Locale.ENGLISH) as the first line of main (it affects the launcher UI too: English key names and Swing dialog buttons, decimal points).
• Manual: 03 (docks, toolbar groups, start tool), 05 (drag feedback, Type details), 09 (Objects tab icon), 15 and 20 (Quit game and play).

Verified: ./gradlew spotlessApply build green (239 tests, ManualTest/ShortcutConflictTest/ EditorShellTest included), every fix checked in the running editor (screenshots above), two play-tests in the game.