documentation for level builders: docs index, step-by-step guide, file format reference (wad, geometry, objects, textures, audio, testlevel chapters, engine limits), strat vm and script language with the arena as worked example, tools overview, developer notes; readme rewritten as project front page with screenshots; review notes moved to notes/dev

docs/tools.md

@@ -0,0 +1,121 @@
+# Tools
+
+Everything in this repository that you can run, what it is for and where its code and notes are.
+None of the tools contain game data; they all work on your own copy of the game.
+
+## LlamaMod (Java app)
+
+The main product: a mod manager with a launcher and a 3D level editor, for Windows and Linux.
+Java 25 + Swing, sources in [`src/main/java/com/eliasmueller/llamamod/`](../src/main/java/com/eliasmueller/llamamod/).
+
+![The LlamaMod launcher](img/launcher.jpg)
+
+| Part | What it does | Docs |
+|---|---|---|
+| launcher | first-start wizard (copies the game from CD/ISO), mod list with options, save-game editor, starts the game (Wine on Linux) | [manual: Installing](manual/02-installing.md), [manual: Mods](manual/18-mods.md), [notes/llamamod-app.md](../notes/llamamod-app.md) |
+| level editor | 3D editor for new and original levels: brushes, tiles, meshes, textures, objects, waypoints, cameras, zones, lights, visibility, strat scripts, play-test, glTF export | [editor manual](manual/index.md) |
+| mods | Test World, Alligator Arena, level projects, Boot to level, Intro skip, Mirror mode, Practice tools, Randomizer, Draw distance, Built-in cheats, Debug wireframe, Free camera | [manual: LlamaMod mods](manual/18-mods.md), `notes/mod-*.md` |
+
+### Command line
+
+```text
+llamamod                        start the GUI
+llamamod --version              show the version and build id
+llamamod --install <iso|folder> set up the game data
+llamamod --mods                 list available mods and their options
+llamamod --apply [id,id,...] [--opt id.key=value ...]
+                                apply mods (none = original); options are saved
+llamamod --launch [--wait]      start the game
+llamamod --registry             show the registry values
+llamamod --saves                show save games
+llamamod --unlock <slot 1-3> <world> <chapter> [--cursor]
+llamamod --editor [project.llamalevel | t1l1m001]   level editor
+llamamod --editor-build <project.llamalevel> <out.wad> [--cd <dir>]
+llamamod --editor-import <level.wad|t1l1m001> <project.llamalevel> [--cd <dir>]
+llamamod --editor-new <project.llamalevel> [base level] [--name <name>] [--cd <dir>]
+llamamod --import-level <project.llamalevel>   (into the level folder, shown as a mod)
+llamamod --remove-level <id|file>   move a level mod's file to backups/levels/
+```
+
+Data folder: `-Dllamamod.data=<folder>` or `LLAMAMOD_DATA` (default `~/.local/share/LlamaMod`,
+Windows `%LOCALAPPDATA%\LlamaMod`). Source: [`Main.java`](../src/main/java/com/eliasmueller/llamamod/Main.java).
+
+### Debug view
+
+The *Debug wireframe* mod
+([`mods/debug/`](../src/main/java/com/eliasmueller/llamamod/mods/debug/)) adds visible geometry to
+every level: collision as coloured frames (invisible walls filled red, the exit floor violet, death
+planes magenta) and markers for invisible objects (start, exit, checkpoints, cameras, triggers,
+zones). Gameplay is unchanged. Its Python ancestor is `tools/debugviz.py`; colour legend and
+details: [notes/debugviz.md](../notes/debugviz.md).
+
+![Debug view in Village 3](img/debug-view.jpg)
+
+## Python kit (`tools/`)
+
+The reverse-engineering toolkit the project started with. Python 3.8+ with `numpy` and `Pillow`
+(`capstone` for `disx86.py`). All parsers rebuild the original files byte for byte.
+
+| Tool | Purpose |
+|---|---|
+| [`wadtool.py`](../tools/wadtool.py) | list, extract and replace WAD chunks |
+| [`geomlib.py`](../tools/geomlib.py) | library: WAD, TRAK, STPC models, MAP tile part, TEXT, collision |
+| [`geom_export.py`](../tools/geom_export.py) | level → OBJ/MTL with textures and vertex colours, `--collision` (collision.obj by material), `--objects`, preview renders |
+| [`geom_import.py`](../tools/geom_import.py) | OBJ → new world geometry in a copy of a level |
+| [`geom_demo.py`](../tools/geom_demo.py) | example geometry for `geom_import.py` |
+| [`mapchunk.py`](../tools/mapchunk.py) | MAP parser/writer |
+| [`map_dump.py`](../tools/map_dump.py) | print a level's tiles, strats, lights |
+| [`strats.py`](../tools/strats.py) | object types of a level: names, instance counts, code offsets, type fields |
+| [`strat_table.py`](../tools/strat_table.py) | type × level table → [notes/strat_types_table.md](../notes/strat_types_table.md) |
+| [`stpcwalk.py`](../tools/stpcwalk.py) | rough walk through STPC (models, animations, code) |
+| [`textchunk.py`](../tools/textchunk.py), [`text_export.py`](../tools/text_export.py) | TEXT chunk; export pages to PNG and import them back |
+| [`texsheet.py`](../tools/texsheet.py) | contact sheet of a level's textures with indices |
+| [`levelbuild.py`](../tools/levelbuild.py) | level builder from a Python script ([guide](guide/levels-in-code.md)) |
+| [`make_testlevel.py`](../tools/make_testlevel.py) | early experiment: one object per type on a floor plate |
+| [`debugviz.py`](../tools/debugviz.py), [`debugviz_check.py`](../tools/debugviz_check.py) | debug-view WADs for all levels and an offline check |
+| [`cor2png.py`](../tools/cor2png.py), [`png2cor.py`](../tools/png2cor.py) | loading pictures (COR) ↔ PNG |
+| [`asf2wav.py`](../tools/asf2wav.py) | music (ASF) → WAV, exact decoder |
+| [`disx86.py`](../tools/disx86.py) | disassemble `groove.exe` at a virtual address |
+| [`vorschau/`](../tools/vorschau/) | Blender (Eevee) preview renders of a level with labels |
+| [`lama-mod`](../tools/lama-mod) | shell script: CD overlay of symlinks for mods in a hand-made Wine setup (pre-LlamaMod) |
+
+Level scripts in [`levels/`](../levels/): `testwelt.py` (the original test world),
+`sprunglabor.py` (jump lab used to measure the llama), `testwelt_parkour.seq` (scripted run).
+
+Several scripts have **hard-coded paths** to the original author's Wine setup at the top (see
+[Levels from scripts](guide/levels-in-code.md#a-python-level)).
+
+## Testing in the game
+
+| Tool | What it does | Notes |
+|---|---|---|
+| [`tools/apptest.py`](../tools/apptest.py) | runs the game **through LlamaMod** in an isolated session: own data folder, Wine prefix, invisible X display (Xvfb), muted private PulseAudio; applies mods, unlocks a level, navigates the menus, presses keys, takes screenshots, detects crashes | [notes/llamamod-app.md](../notes/llamamod-app.md#testing-mods-in-game-toolsapptestpy) |
+| [`tools/lamatest.py`](../tools/lamatest.py) | the older harness for a hand-made Wine setup: loads a WAD as TestLevel and runs a key sequence | [notes/testharness.md](../notes/testharness.md) |
+
+Linux only; needs Wine, Xvfb, xdotool, ImageMagick, tesseract (German data, for reading menu
+texts) and PulseAudio. `apptest.py` defaults to a session root inside the author's job folder –
+set `APPTEST_ROOT`.
+
+```bash
+./gradlew fatJar
+tools/apptest.py run demo --display 7 --mods arena --level 9 49 \
+    --seq "Up:1.5 shot:walk z shot:kick" --out /tmp/demo
+```
+
+## Reverse engineering
+
+* `re/ghidra_scripts/DumpAll.java` – headless Ghidra script that decompiles every function of
+  `groove.exe` into one C file. The exe, the decompile and (currently) the script itself are
+  excluded from the repository (`.gitignore`). Run
+  `analyzeHeadless <projdir> groove -import groove.exe -scriptPath re/ghidra_scripts -postScript DumpAll.java groove_decomp.c`
+  (Ghidra 12.x needs JDK 25).
+* Key functions: MAP loader `0x42ac50`, TRAK `0x42aac0`, STPC `0x42ab50`, strat VM `0x54d180`,
+  chunk dispatcher `0x558960`.
+
+## Other folders
+
+| Folder | Content |
+|---|---|
+| [`examples/`](../examples/) | `testwelt.llamalevel`: the original test world as an editor project |
+| [`packaging/`](../packaging/) | icons, Windows (launch4j) and Linux packaging files |
+| [`deb-build/`](../deb-build/) | older script (German) that builds a Debian package of the game itself from your ISO, with the soundtrack converted to MP3 |