llamamod/notes/editor-manual.md

Level editor – user manual and in-app help (editor.tools.help)

The complete user manual (English, forum audience) lives as Markdown in docs/manual/ (one file per chapter + img/). It is bundled into the jar (build.gradle → processResources copies docs/manual to com/eliasmueller/llamamod/editor/tools/help/manual/) and shown by Help → Manual (F1).

Chapters

index.md defines the order and the groups of the contents tree (H2 = group, list links = chapters): Getting started (01 introduction & concepts, 02 installing, 03 editor window, 04 navigation, 05 selection), Tutorials (first level in 10 minutes, parkour, edit an original level, Blender model), Building levels (06 geometry, 07 meshes & library, 08 textures, 09 objects incl. cross-world import, 10 waypoints, 11 cameras & triggers, 12 environment, 13 visibility, 14 level settings), Testing and sharing (15 build/problems/play-test, 16 original levels, 17 sharing), Reference (18 mods, 19 keyboard/mouse/menu, 20 troubleshooting & FAQ, 21 glossary).

Markdown subset (own converter Markdown, no dependency): ATX headings (one H1 per file), paragraphs, bold/italic/code, links, images on their own line, nested lists, GFM tables, block quotes (callouts), fenced code, rules; no raw HTML. Anchors = GitHub slugs, so the files also read well on GitHub/forums.

Generated blocks <!-- generated:NAME -->…<!-- /generated:NAME --> are filled from the live program (ManualContent): shortcuts (tool keys, keyed commands, key conflicts), menus (every menu command with key and tooltip), panels (dock panels) – from EditorExtensions, i.e. built-ins and all plugins – and mods (built-in LlamaMod mods with options, from ModRegistry). The window regenerates them at run time; ManualTest rewrites the copies in docs/manual when they are stale (-Dllamamod.manual.noUpdate=true turns that off). Key names are locale-independent ("Ctrl+Shift+D").

Manual window (ManualWindow)

Own frame (stays open next to the editor, works while a modal dialog is open): toolbar back / forward (Alt+Left/Right), contents (Alt+Home), previous / next chapter, search field (Ctrl+F), Export menu; left: Contents tree (groups → chapters → H2 sections, follows navigation) and Search (all words must match; ranked by title hits; excerpt; the words are highlighted on the page); right: the page (Swing HTML with CSS from the current FlatLaf colours, images scaled to the page width and loaded synchronously so anchors land correctly, previous/next links at the end). Internal links navigate, external ones open the browser. Re-rendered on theme change (light/dark). -Dllamamod.manual.dir=docs/manual reads the Markdown from a folder (reloaded on every open) for writing the manual.

Export (ManualExport): HTML folder (index.html + one page per chapter with a sidebar, manual.css with light/dark prefers-color-scheme, used images), one self-contained HTML file (all chapters, images as data URIs, links rewritten to in-page anchors – for forum attachments), and Print this chapter (system print dialog → PDF). Also Help → Export manual as HTML….

Context help (ContextHelp, context-help.txt)

F1 opens the chapter for what the mouse pointer is over (else the focus owner), in the main window and in every dialog/window owned by it. Topics, collected walking up the component tree: client property HelpTopics.PROP (inspector sections inspector.x:<title> / inspector.g:<group>, tool options bar tool.<id>), menu items / toolbar buttons (action.<id> via the action's "spec"), tool buttons (tool.<id> by tooltip), inner tabs (tab.<title>), dock tabs (panel.<id>), the selected node kind inside Inspector/Outliner (node.<KIND>), the viewport (tool.<active tool>), the window title (dialog.<title>), window.editor. Mapping file src/main/resources/.../tools/help/context-help.txt (topic = file.md#anchor, prefix* keys are wildcards; exact matches of any candidate beat wildcards). The Help → Manual menu item opens the manual where it was (F1 key = context).

"?" buttons: every Inspector section header, the tool options bar (next to the tool name), and the right end of every dock's tab row (FlatLaf trailing component, help for the visible panel).

Shell changes (minimal, backwards compatible): new editor/ui/HelpTopics (handler hook + "?" button helper; without a handler nothing is shown), InspectorPanel.section (topic property + "?"), ToolOptionsBar (topic property + "?"), build.gradle (processResources). help.shortcuts moved from F1 to Ctrl+F1 (re-registered by the help plugin).

Tests / verification

• ManualTest: every .md is in the contents; exactly one H1 per file; all internal links and anchors resolve, all images exist, no placeholder images; every context-help.txt target resolves; generated references contain every tool / every built-in mod; search; HTML folder and single-file export; Markdown subset unit checks. Unmapped tools/panels/sections are reported on stdout (not a failure, so new plugins do not break the build).
• ManualTour (test classes, X display): screenshots for the manual and an end-to-end context-help run with java.awt.Robot (real mouse/F1 events) on Xvfb :17. Results: ? on the Inspector's "Object parameters" → 09-objects#object-parameters; F1 over the Textures panel → 08-textures#texture-manager; F1 over the viewport with the Brush tool → 06-geometry#brush-tool-b; F1 over the "Waypoint chain" section → 10-waypoints#waypoint-chain-section; F1 in the modal Preferences dialog → 03-editor-window#preferences. Images: img/editor/manual_*.jpg.

Maintaining the manual

• Edit docs/manual/*.md; run ./gradlew test --tests '*ManualTest*' (link check + regenerates the generated blocks). New chapter: add it to index.md.
• New tool/panel/section/dialog: add a line to context-help.txt (the test prints what is unmapped).
• Screenshots: ManualTour steps geo,nav,village,manual,context,dark, RetakeTour steps library,insert (open a GeoLibDemo level) and texpaint (village), and the other tours (EditorTour, ObjectsTour, EnvTour); keep images ≤ 1000 px wide (jar size).
• SmokeTour (same command line, GeoLibDemo level): real-input checks of the death plane height field (typed value without Enter + OK), Ctrl-inverted snapping of the place tool and the Inspector's "Exclude from build"; prints PASS/FAIL.