llamamod/docs/tools.md

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/.

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: Mods, 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
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, notes/mod-*.md

Command line

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.

Debug view

The Debug wireframe mod (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.

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	list, extract and replace WAD chunks
geomlib.py	library: WAD, TRAK, STPC models, MAP tile part, TEXT, collision
geom_export.py	level → OBJ/MTL with textures and vertex colours, --collision (collision.obj by material), --objects, preview renders
geom_import.py	OBJ → new world geometry in a copy of a level
geom_demo.py	example geometry for geom_import.py
mapchunk.py	MAP parser/writer
map_dump.py	print a level's tiles, strats, lights
strats.py	object types of a level: names, instance counts, code offsets, type fields
strat_table.py	type × level table → notes/strat_types_table.md
stpcwalk.py	rough walk through STPC (models, animations, code)
textchunk.py, text_export.py	TEXT chunk; export pages to PNG and import them back
texsheet.py	contact sheet of a level's textures with indices
levelbuild.py	level builder from a Python script (guide)
make_testlevel.py	early experiment: one object per type on a floor plate
debugviz.py, debugviz_check.py	debug-view WADs for all levels and an offline check
cor2png.py, png2cor.py	loading pictures (COR) ↔ PNG
asf2wav.py	music (ASF) → WAV, exact decoder
disx86.py	disassemble groove.exe at a virtual address
vorschau/	Blender (Eevee) preview renders of a level with labels
lama-mod	shell script: CD overlay of symlinks for mods in a hand-made Wine setup (pre-LlamaMod)

Level scripts in levels/: testwelt.py (the original test world), sprunglabor.py (jump lab used to measure the llama), testwelt_parkour.seq (scripted run).

Paths

The tools find the original game files through these environment variables (tools/lamapaths.py); the defaults match a hand-made Wine setup. Command-line options (--base, --src, --root, --iso) win over them.

Variable	Used by	Default
LLAMAMOD_CD	levelbuild.py, debugviz.py, debugviz_check.py, Gradle tests (-Dllamamod.cd)	$LAMA_WINEPREFIX/iso-dk/Setup/Eng/Cd – the CD folder (wads/, music/, *.cor)
LAMA_WINEPREFIX	lamatest.py, levelbuild.py --install	~/.wine-lama
LAMA_MOD	lamatest.py	~/.local/bin/lama-mod, else tools/lama-mod
APPTEST_ROOT	apptest.py (session folders)	$CLAUDE_JOB_DIR/tmp if set, else ~/.cache/llamamod-apptest
APPTEST_ISO	apptest.py (first install)	~/Downloads/GROOVE_DK.iso
LAMATEST_DIR	lamatest.py (state, logs)	/tmp/lamatest-$USER

A missing folder stops the tool with a message naming the variable to set.

Testing in the game

Tool	What it does	Notes
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
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

Linux only; needs Wine, Xvfb, xdotool, ImageMagick, tesseract (German data, for reading menu texts) and PulseAudio. Session folders and the ISO: APPTEST_ROOT, APPTEST_ISO (see Paths).

./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/	testwelt.llamalevel: the original test world as an editor project
packaging/	icons, Windows (launch4j) and Linux packaging files
deb-build/	older script (German) that builds a Debian package of the game itself from your ISO, with the soundtrack converted to MP3