llamamod/notes/editor-ui.md

Level editor – application shell (editor.ui, phase 2)

The Swing/FlatLaf editor around the phase-1 core (editor-api.md, editor-format.md) and viewport (editor-render.md). Package com.eliasmueller.llamamod.editor.ui (+ .panels, .tools, .view). Design brief: editor-design.md.

Launch

• LlamaMod header: Level Editor button next to Play (ui/MainFrame.openEditor). Same JVM, same AppPaths/Config/ModManager objects; after a play-test LlamaMod refreshes (EditorEnv.setModsChanged).
• llamamod --editor [project.llamalevel | t1l3m002] – standalone (exits when closed). Without an argument it offers crash recovery. -Dllamamod.editor.cd=DIR uses another CD folder, -Dllamamod.editor.msaa=0 disables multisampling (software GL).
• Programmatic: EditorApp.open(new EditorEnv(paths, cfg, modManager, false), arg) on the EDT.

Window

Area	Content
Menu	File (New level, Open original level, Open project, Open recent, Save, Save as, Close, Import mesh/texture, Export WAD), Edit (Undo/Redo with labels, History, Cut/Copy/Paste/Duplicate/Delete, Select all/none/similar, Hide/Show/Lock, Preferences), View (Frame, Camera ›, local space, snap, collision, dark theme, Panels ›, Layers ›), Level (Settings, Check, Build, Play), Help (Keyboard shortcuts, About)
Toolbar	new/open original/open/save · undo/redo · Select Q / Move W / Rotate E / Scale R · duplicate/delete/frame · Build · Play
Options bar	active tool + its options · Snap toggle, move step (1…1/16 cell), angle step · World/Local · camera view · Layers popup
Docks	left: Outliner, History · right: Inspector · bottom: Assets, Problems. Tabs can be closed, moved to another dock (tab context menu), reopened in View → Panels; layout and split sizes are remembered
Viewport	render.Viewport with the live scene; empty state ("Open a level or create a new one", recent projects) while no level is open
Status bar	messages, hovered item, cursor position (game cells) and grid cell, counts, last build (click → Problems), progress of background tasks

Shortcuts (Help → Keyboard shortcuts lists all, incl. plugins): RMB+WASDQE fly, MMB orbit, Shift+MMB pan, wheel zoom, F frame, Home frame level, numpad 7/1/3/5 views, Q/W/E/R tools, X local space, G snap, C collision, H hide, Alt+H show all, L lock, Ctrl+D duplicate, Del delete, Ctrl+Z/Y/Shift+Z, Ctrl+X/C/V, Ctrl+A, Ctrl+B build, F5 play, F1 help. Single keys never fire while a text field has the focus; while the GL canvas has the focus a KeyEventDispatcher maps keys to actions (AWT canvases do not get Swing key bindings).

• Status messages: ctx.status(msg) shows a message for ~6 s; the autosave note uses backgroundStatus, which waits until a fresher user message has expired (it no longer replaces e.g. the glTF export result).
• Inspector property labels have a fixed 118 px column; longer labels wrap onto more lines (InspectorPanel.fitLabel) instead of being cut ("Exclude from build").
• Readable names everywhere (img/editor/ui_readable_names.jpg: outliner filter "coin 3", inspector "Coin 3", status bar hover "Coin 3"/"Tile 41, 66 · Model 87", asset tab "Model 0"); inspector button rows wrap without clipping in a narrow dock (ui_waypoint_buttons_narrow.jpg); long property labels wrap (ui_inspector_label_wrap.jpg).
• Narrow inspector (2026-11-07, ui_inspector_narrow.jpg): Position/Rotation X/Y/Z use AxisLayout (one row while each cell gets ≥ 66 px, else stacked one per row; also the brush rotation spinners); reference buttons (InspectorPanel.RefButton) show the longest name that fits ("Waypoint 5 (chain 3)" → "Waypoint 5" → "#5", other names drop a "(…)" suffix, then "…"), full name + id in the tooltip.
• The naming logic lives in editor.model.ReadableNames (so editor.io can use it: brush compile warnings "Floor 2: … – skipped", Validator messages, "is still used by" errors); ui.NodeNames extends it. Also: waypoint added / pilot mode status, object check texts ("Coin 3: …", "Waypoint chain at Waypoint 4 (chain 2)"), missing texture page ("Texture #5 uses page 7, but the level has only 4 texture pages (0–3)"), Problems tooltip. Numbers in filter queries match whole numbers at both ends ("2" no longer finds "Floor 12"); the tile palette filter uses the same rule on model names/numbers.
• Tool status and check texts use NodeNames too (geometry, tile paint, collision, texture paint, lights, brush-outside-grid check, "Placed Model 12 in cell …"); the outliner filter applies the whole-number rule to the old label and the id as well ("tile 3" no longer finds x = 39).

Architecture

Class	Role
EditorWindow	the JFrame; implements EditorContext; owns selection, viewport, SceneRenderer, docks, actions, key dispatch, document switching
EditorContext	the API plugins use (document/scene/history, selection, viewport, pick helpers, execute, hidden/locked, layers, tools, status, background tasks, problems, panels)
EditorExtensions / EditorPlugin / PluginLoader	registry + discovery (below)
BuiltinEditorPlugin	everything built in, registered through the same API
Document	Project + History + file + autosave state; dirty()
Selection	ordered node set, primary = last, listeners get the source (avoid echo loops), auto-pruned
ProjectController	new/open/save/save as/recent, autosave + recovery, thumbnail, import/export
PlayTest	check, background build, install/mod-selection/save-slot helpers for the play-test plugin (the old menu-based play() is gone; level.play is a disabled placeholder that PlaytestEditorPlugin replaces)
TaskRunner	runTask: one background task on its own daemon thread; progress and completion are posted with invokeLater from that thread, so the completion always runs after the last progress update, also when the task or the done callback throws (replaced SwingWorker, whose done() goes through a Swing timer)
NodeNames	readable names shared by outliner, inspector header, status-bar hover, reference buttons and the Tile models asset tab ("Floor 2", "Coin 3", "Waypoint 4 (chain 2)", "Tile 3, 4 · Model 12", "Model 12"); numbers follow the level order
view.SceneRenderer	scene model → RenderScene, live, stable pick ids
view.Thumbnails	software rasteriser for asset thumbnails
tools.SelectTool, TransformSupport, Transformers, EditOps	selection/transform tools and edit operations
panels.*	Outliner, Inspector, AssetBrowser, Problems, History

All edits go through ctx.execute(Command) (→ History); drags use one merge key per gesture, so a drag is one undo step (TransformSupport, inspector drag-scrub). Scene events arrive synchronously; the window collects them and flushes the renderer once per EDT turn.

Scene → render adapter (view.SceneRenderer)

• Pick ids kind<<24 | n (PickId.TILE/OBJECT/WAYPOINT/ZONE/LIGHT, PICK_BRUSH=6, PICK_OTHER=7), assigned per node on first use, stable for the document (idOf, nodeOf).
• Tiles: one instance per tile (mesh per TileModel, collision overlay), transform + first colour frame; a CHANGED tile only updates its instance (RenderScene.changed(inst) → one chunk rebuild); a changed model rebuilds its mesh and its tiles. Objects: model via StratModels from the STPC raw chunk (same rules as LevelSceneAdapter), markers for logic objects. Markers/overlays (waypoints, zones + teleport targets, lights, regions, brush boxes) are rebuilt as a whole (RenderScene.overlaysChanged(), cheap). Texture/STPC changes or RELOADED rebuild everything (~0.3 s for the village).
• Brushes: BrushCompiler.compile (the build's own code) for a live preview; generated tiles get the pick id of the smallest enabled brush whose bounds contain them, plus an outline box and handle marker.
• Waypoints default to "selection only" (chains of selected objects/waypoints), View → Layers can show all.
• Hidden nodes: instance/marker visible=false (renderer change: invisible tiles leave the static batches); locked nodes are drawn but pickNode ignores them.

Extension API (phase 3)

Rule for parallel agents: never edit editor.ui itself. Create a package of your own, e.g. com.eliasmueller.llamamod.editor.tools.waypoints, with a class whose simple name ends in EditorPlugin:

public final class WaypointEditorPlugin implements EditorPlugin {
    @Override public void install(EditorExtensions x) {
        x.tool(new WaypointTool());                                         // toolbar + shortcut
        x.panel(new PanelSpec("waypoints", "Waypoints", "waypoint", Dock.RIGHT, 30, false, WaypointPanel::new));
        x.action(ActionSpec.of("wp.newChain", "Tools", 10, 10, "New waypoint chain", "waypoint", "ctrl shift W",
                ctx -> ...).enabledWhen(ctx -> ctx.document() != null));
        x.inspector(new ChainSection());                                    // extra inspector content
        x.layer(new LayerSpec("wpLabels", "Waypoint labels", "waypoint", false, 55));
        x.renderContributor(new ChainLabels());                             // overlay geometry in that layer
        x.check((scene, out) -> ...);                                       // build/check problems
        x.transformer(new MyNodeTransformer());                             // gizmo support for a node kind
        x.template(new MyLevelTemplate());                                  // "New level" start content
        x.assetTab(new AssetTab("prefabs", "Prefabs", "assets", 50, PrefabTab::new));
        x.onOpen(ctx -> ctx.addSceneListener(e -> ...));                    // runs once the window exists
        AssetDrop.register("prefab", (ctx, data, ground) -> ...);          // drag & drop into the viewport
    }
}

Discovery: PluginLoader scans the classpath (jar or class folders) for *EditorPlugin.class below com/eliasmueller/llamamod/editor/ (no shared registration file); -Dllamamod.editor.plugins=a.B,c.D adds others. A plugin that throws is skipped with a message. Built-ins install first; registering the same id again replaces (panels, tools, actions, asset tabs, layers).

API	Notes
Tool	id/name/icon/tooltip/shortcut/group/order; activate/deactivate; mousePressed(ToolEvent) → true = owns the drag (else default click-select); mouseDragged/Released/Moved, keyPressed; gizmoMode() (null = no gizmo) + gizmo(ctx, GizmoEvent) + placeGizmo(ctx); drawOverlay(depthTested, onTop) (export space, call ctx.repaintTool()); optionsBar(ctx); inspectorSection(ctx, sel); cursor(). Right/middle mouse and Alt always stay with the camera
ToolEvent	x/y/shift/ctrl/alt/clickCount, lazy pick() (respects layers/hidden/locked), surface() (geometry point), onPlane(y), ground(), toGame(p) / toExport(x, y, z)
ActionSpec	menu path "Tools" or "View/Camera", group/order, label, icon, KeyStroke string, run, enabledWhen, checked (check box item), tip; x.toolbarAction(id, section)
PanelSpec	id, title, icon, default Dock, order, visible by default, factory ctx → JComponent (created once; follow addDocumentListener/selection().addListener/addSceneListener)
InspectorSection	appliesTo(sel), create(ctx, sel) (rebuilt on selection change), replacesProperties()
RenderContributor	layer(), affectedBy(SceneEvent), followsSelection(), build(ctx, builder) → builder.overlay() lines/triangles, builder.marker(node, x, y, z, rgba) (pickable → selects node)
NodeTransformer	position (game cells), yaw (deg or NaN), scale (or null), set(node, pos, yaw, scale) → prop map. set must compute from the node it gets (the shell passes a drag-start snapshot)
LevelTemplate	fill(Scene) adds nodes directly (no undo) before the editor shows the new level
LevelCheck	adds Problem.error/warning/info(msg, node); errors block Build/Play
Icons	vector icons by name; Icons.register(name, painter) for your own (16×16 Java2D); Icons.swatch(colour, w, h)
NodeNames	NodeNames.name(node) (one node) or NodeNames.of(scene) (index for many: nameOf, objectName, waypointName, chainStarts) – use it instead of Node.label() in UI texts; tooltips may show node.id()
AxisLayout	public layout for X/Y/Z cells: one row, or stacked when a cell would be narrower than its minimum (new AxisLayout(AxisLayout.CELL_MIN))
WrapLayout	public FlowLayout that grows to more rows in a narrow container (inspector button rows: ParamsSection.compact switches a FlowLayout bar to it)
Widgets, util.SwingListeners	Widgets.button(text, icon, tip, run), Widgets.listCell(c, list, selected), Widgets.wrappingLabel(html) (help text that wraps at the dock width – use it instead of <body style='width:…'>); onTextChange, onMenuOpen
ErrorDialog	ctx.error(title, t) uses it: plain sentence (ErrorDialog.plain(t), no exception class names) + collapsible Details (stack trace)
Game state	ctx.setGameRunning(what, stop) (default no-op): while a play-test game runs the status bar shows "Game running: what" and the toolbar Play button becomes Stop game (runs stop); null resets. PlaytestRunner sets it on launch and clears it when its watcher sees the game exit
AssetDrop	register(kind, handler); dragSource(list, value → payload(kind, data)) makes a list draggable into the viewport
EditorPrefs	ctx.prefs() JSON settings in <data>/editor/settings.json; prefix your keys
NodeCopy	duplicate/snapshot nodes (fresh ids)
EditOps (tools)	placeTile, placeObject, copies, duplicate, delete, … reusable from plugins

Coordinate reminder: render/viewport points are export space (z = −game z); model positions are game space (ToolEvent.toGame / toExport). Drop/placement points: ctx.groundAt(x, y), ctx.viewCentre(). Commands: editor-api.md (Edits, SetProp, Batch with merge key).

Render additions used by tools (backwards compatible, editor.render)

Viewport.setHudOverlay(pixels) (second pixel overlay independent of the tool, e.g. the Shift+F5 crosshair), Viewport.setInput(ViewportInput) (tool hook: left-button press/drag/release not on the gizmo, moves, keys), setToolOverlay(depthTested, onTop), setScreenOverlay(pixels) (marquee), unproject(x, y, depth) public, isFlying(), canvas(); RenderScene.overlaysChanged(); LevelSceneAdapter.mesh/page/collision public; invisible tile instances are no longer baked into chunks; History.undoLabels()/redoLabels().

Project lifecycle

• New level: dialog (name, author, base level by name with its loading picture, TestLevel chapter = next free one, template Empty / Flat floor / Island). Templates add brushes, a Llama (one start camera node 2 cells behind, PlayerStart) and a LevelDoor on a material-16 floor.
• Open original level: list "Village – Chapter 1" … "Lab – Chapter 5" (+ unused/front-end WADs) with the CD loading pictures (OriginalLevels, Cor).
• Save (.llamalevel, default folder <data>/levels = listed as mods in LlamaMod), Save as, Open recent (10), dirty marker "•" in the title, confirm on close/new/open. Thumbnail: viewport screenshot 640×360 PNG on every save (also the TestLevel loading picture).
• Autosave every 90 s (Preferences) while dirty → <data>/editor/autosave/*.llamalevel + .json (title, original file, time); deleted on save/close/discard. After a crash the next start offers Recover / Discard / Later (verified: kill during editing → recovered with all edits).

Build & Play-test

• Check: Validator + checks (no player start = error, no exit in a new level = warning, no geometry, brushes outside the grid). Messages with node ids are double-clickable in Problems.
• Build (Ctrl+B): validates, snapshots the project (ProjectIO.write), then reads + builds the WAD in the background (UI stays usable) → Problems: "Build OK: tiles (from brushes), objects, waypoints, KB, time" + warnings.
• Play (F5): build → write the current state to <data>/levels/<stem>.llamalevel (if that is the document's own file it counts as saved; otherwise the user's file stays untouched) → enable the level mod next to the active mods (turns off other mods writing the same WAD, incl. Test World on chapter 1), TestLevel chapter option = project chapter → ModManager.apply → save slot (Preferences, default 3; backup first) unlocked up to the level if needed and map cursor on it → start the game.
• Boot to level (phase 3, editor.tools.playtest, notes/editor-playtest.md): Play now also applies the exe mod boot-to-level, so the game loads the level directly (no menus) and Escape quits; Shift+F5 = play from the camera position (holding Shift or hovering the action shows a green/red crosshair at that point). While the game runs: "Game running" badge + Stop game button (see Game state). The old menu-based run is still available (Level → Play boots straight into the level off). -Dllamamod.editor.noLaunch=true skips the launch (tests start the game through apptest).

Tests

• EditorShellTest (CD needed, -Dllamamod.cd): drag = one undo step + world-grid snapping, rotate about a pivot, duplicate with waypoint-chain copy + delete/undo, brush move/scale, renderer live updates (tile move, marker move, delete/undo, waypoints of the selection), templates build brush tiles + thumbnails render, plugin discovery, number-field arithmetic.
• EditorTour (test classes, not a unit test): scripted run on an X display, writes the screenshots below. java -cp all.jar:build/classes/java/test -Dllamamod.data=DIR -Dllamamod.editor.msaa=0 com.eliasmueller.llamamod.editor.ui.EditorTour OUTDIR village,select,move,… (steps: empty, recover, village, select, move, rotate, marquee, panels, layers, build, drag, newlevel, place, save, play, crash, dark, shortcuts, dialogs).
• End-to-end (2026-11-06, Xvfb :8 editor, :7 game): new level "Editor Island" (Island template, chapter 7) → 2 coins + checkpoint placed, checkpoint duplicated → saved → Build OK (1830 brush tiles, 6 objects, 5.6 MB) → Play (noLaunch: mod applied, slot 3 unlocked, cursor on TestLevel 7) → apptest start/tolevel --world 9: slot shows "TestLevel Kapitel 7", the island loads with trees, coins and checkpoints, the llama walks (img/editor/ui_e2e_game.jpg). Drag & drop from the asset browser into the viewport placed an object (Robot drag). Crash recovery verified.

Screenshots (img/editor/ui_*.jpg): empty state, village, select+move gizmo, moved, rotate, marquee (+ result), assets (tile models, objects, textures), level settings, layers (collision), build, drag & drop, new island, placed objects, play-test dialog, dark theme, shortcuts, new-level and open-original dialogs, LlamaMod header button, game.

Known limits / next steps

• Rotation only about the vertical axis (rx/rz via the inspector); scale only for brushes.
• Brush preview recompiles all brushes on every brush change (fine for dozens; a large level may need per-brush compilation). Generated brush tiles are picked by bounds heuristics.
• Tile models without tiles have no "place" preview; dropping places in the cell under the cursor with grey vertex colours (no lighting bake for original tile models).
• Clipboard is in-memory (same window), paste offsets by one step per paste.
• The LlamaMod mod list shows a newly installed play-test level only after restarting LlamaMod (AppState.registry is created once).
• Not tested on Windows hardware (the viewport was tested under Wine in phase 1).