96 lines
6.4 KiB
Markdown
96 lines
6.4 KiB
Markdown
# 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.
|