initial commit: llamamod 0.2.0 – reverse-engineered level formats (wad, map, trak, text, stpc), python tools and notes, java mod manager (iso install, mod pipeline with exe patching, save editor, wine/windows launcher) with mods (test world, debug wireframe, mirror, randomizer, fog, cheats, intro skip, practice, free camera, boot to level, level projects) and the 3d level editor (geometry, objects, cross-world import, environment, textures, play-test, manual)

notes/editor-manual.md

@@ -0,0 +1,95 @@
+# 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)**.
+
+![manual window](img/editor/manual_chapter.jpg)
+
+## 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.