147 lines
8.0 KiB
Markdown
147 lines
8.0 KiB
Markdown
# LlamaMod – mods and a level editor for *The Emperor's New Groove* (PC, 2000)
|
||
|
||
German title: *Ein Königreich für ein Lama*. PC port by Argonaut, built on the Croc 2 engine.
|
||
|
||
**LlamaMod** is a one-click mod manager and a full 3D **level editor** for the PC game, for
|
||
**Windows and Linux**. It installs the game from your own CD or ISO into its own folder, applies
|
||
mods without ever touching the original files, and lets you build new levels, edit the original
|
||
ones and share them as small files. Everything is based on a complete reverse engineering of the
|
||
game's level formats and its object scripts ("strats").
|
||
|
||
|
||
|
||
*The launcher: tick the mods you want, set their options, click Apply and Play.*
|
||
|
||
|
||
|
||
*The level editor with Village chapter 1 open: outliner (left), 3D view, inspector (right), assets and scripts (bottom).*
|
||
|
||
More pictures:
|
||
|
||
| | |
|
||
|---|---|
|
||
|  |  |
|
||
| **Launcher**: mods with options, save-game editor, one-click play | **Level editor**: brushes, tiles, meshes, objects, textures, play-test with F5 |
|
||
|  |  |
|
||
| **Test World**: all 253 figures and objects of the game in one level | **Alligator Arena**: a minigame with new, scripted enemies |
|
||
|  |  |
|
||
| **Debug view**: collision and invisible objects in the running game | **glTF/OBJ** export and import for Blender |
|
||
|
||
## Features
|
||
|
||
* **Mods** – tick, *Apply*, *Play*: Test World, Alligator Arena, your own levels, Boot to level,
|
||
Intro skip, Mirror mode, Practice tools (save/restore position, extra checkpoints), Randomizer,
|
||
Draw distance, Built-in cheats, Debug wireframe, Free camera & noclip.
|
||
* **Level editor** – new levels from templates or editing the original levels; brushes, the base
|
||
level's tiles, OBJ/glTF meshes; textures (import, paint, animate); objects from **every world**;
|
||
waypoints, cameras, triggers; fog, music, lights, visibility regions; strat scripts (read,
|
||
change numbers, write new object types); checks for problems; **F5** starts the game directly in
|
||
the level.
|
||
* **Sharing** – a level is a small `.llamalevel` file with only your changes and no game data; the
|
||
receiver's LlamaMod builds it from their own copy. New levels live in the hidden *TestLevel*
|
||
world.
|
||
* **Save games** – unlock worlds and chapters, coins, collectibles; backups before every change.
|
||
* **Safe** – the original CD/ISO and files are never changed; *Restore original* switches all mods
|
||
off.
|
||
|
||
## Get it
|
||
|
||
You need **your own copy of the game** (CD or ISO image). Development used the German CD; other
|
||
language versions should work but are untested.
|
||
|
||
| System | Package | Start |
|
||
|---|---|---|
|
||
| Windows | `LlamaMod-<version>-full-windows-x64.zip` | unzip, start `LlamaMod.exe` (no installation, no admin rights) |
|
||
| Linux | `LlamaMod-<version>-full-linux-x64.tar.gz` | unpack, start `./LlamaMod`; install **Wine** to run the game |
|
||
|
||
Both bring their own Java runtime; the editor needs OpenGL 3.3. A *launcher* edition without the
|
||
editor is also built. What changed: [CHANGELOG.md](CHANGELOG.md).
|
||
|
||
### Build from source
|
||
|
||
Needs a JDK 25 (toolchain) and Gradle running on Java 21 (for Spotless):
|
||
|
||
```bash
|
||
./gradlew spotlessApply build fatJar # tests + build/libs/llamamod-<ver>-all.jar
|
||
java -jar build/libs/llamamod-*-all.jar # LlamaMod
|
||
java -jar build/libs/llamamod-*-all.jar --editor # the level editor alone
|
||
./gradlew packageAll # Linux + Windows packages, full and launcher edition
|
||
```
|
||
|
||
Details: [For developers](docs/developers.md).
|
||
|
||
## Documentation
|
||
|
||
**[docs/](docs/README.md)** – start there.
|
||
|
||
* **[Build your own level](docs/guide/README.md)** – a step-by-step guide for newcomers.
|
||
* **[Level editor manual](docs/manual/index.md)** – every tool and dialog, with tutorials (also
|
||
built into the editor: **F1**).
|
||
* **[Reference](docs/reference/README.md)** – file formats (WAD, geometry, collision, objects,
|
||
textures, music), TestLevel, engine limits.
|
||
* **[Strats](docs/strats/README.md)** – how the game's object scripts work, the script language,
|
||
custom object types, and the [Alligator Arena walkthrough](docs/strats/arena.md).
|
||
* **[Tools](docs/tools.md)** – the app's command line, the Python kit, in-game test harnesses.
|
||
* **[Lab notes](notes/README.md)** – the detailed engineering notebook.
|
||
|
||
## The Python kit
|
||
|
||
The project started as a Python reverse-engineering kit, which is still in [`tools/`](tools/):
|
||
byte-exact parsers and writers for every level chunk, OBJ export/import, a script-driven level
|
||
builder ([`tools/levelbuild.py`](tools/levelbuild.py), example [`levels/testwelt.py`](levels/testwelt.py)),
|
||
texture and picture converters, a music decoder, the debug-view generator and an automated
|
||
in-game tester for Linux/Wine. Python 3.8+ with `numpy` and `Pillow`.
|
||
|
||
```bash
|
||
# export a level to OBJ (+ collision and object markers)
|
||
python3 tools/geom_export.py /path/to/cd/wads/t1l1m001.wad out_village --collision --objects
|
||
# build the original test world from its script
|
||
python3 tools/levelbuild.py levels/testwelt.py testwelt.wad --base /path/to/cd/wads/t1l1m001.wad
|
||
python3 tools/levelbuild.py --types # object types you can place
|
||
# music to WAV, loading picture to PNG
|
||
python3 tools/asf2wav.py /path/to/cd/music/Village.asf village.wav
|
||
python3 tools/cor2png.py /path/to/cd/t111.cor t111.png
|
||
```
|
||
|
||
Where the tools look for the game files (or pass `--base`/`--src`):
|
||
|
||
| Variable | Meaning | Default |
|
||
|---|---|---|
|
||
| `LLAMAMOD_CD` | the CD folder (`wads/`, `music/`, …), also for the Gradle tests | `~/.wine-lama/iso-dk/Setup/Eng/Cd` |
|
||
| `LAMA_WINEPREFIX` | Wine prefix of a hand-made game setup (`lamatest.py`, `levelbuild.py --install`) | `~/.wine-lama` |
|
||
| `APPTEST_ROOT`, `APPTEST_ISO` | session folders and ISO of `apptest.py` | `~/.cache/llamamod-apptest`, `~/Downloads/GROOVE_DK.iso` |
|
||
| `LLAMAMOD_DATA` | data folder of the app | `~/.local/share/LlamaMod` (Windows `%LOCALAPPDATA%\LlamaMod`) |
|
||
|
||
All tools and variables: [docs/tools.md](docs/tools.md#paths).
|
||
|
||
### Key facts in one minute
|
||
|
||
* **The world is made of tiles.** TRAK holds 100–650 small models (render triangles + collision
|
||
polygons); MAP places them on a W × H grid with height and rotation, plus baked vertex colours
|
||
and a 32-region visibility table. No BSP, no single world mesh.
|
||
* **Objects are "strats"**: compiled scripts in STPC. An object's type is its byte offset into
|
||
STPC, so a level can only use the types its own STPC contains (or types merged in from other
|
||
levels).
|
||
* **Scale**: y up, one unit per grid cell; the llama is 0.6 tall, walks 1.1 units/s, steps up
|
||
nothing and jumps ~1.3 far.
|
||
* **The exit** fires only when the llama stands in the LevelDoor's grid cell **on floor with
|
||
collision material 16**.
|
||
* **Textures** are PlayStation-style 15-bit pixels on 256 × 256 pages; there are no free UVs.
|
||
|
||
More: [docs/reference](docs/reference/README.md).
|
||
|
||
### Building on this with an AI assistant
|
||
|
||
This whole project was made by an AI coding agent (Claude Code). To continue it, give an assistant
|
||
the [lab notes](notes/README.md) first – they contain offsets, field meanings, confidence levels and
|
||
pitfalls – and let it regenerate the decompile of `groove.exe` with Ghidra for questions about game
|
||
logic (headless `DumpAll` script, see [Tools](docs/tools.md#reverse-engineering)). Always test in the
|
||
game (`tools/apptest.py`) and change one thing at a time: the engine crashes on inconsistent data.
|
||
|
||
## Legal
|
||
|
||
This is a non-commercial fan project, not affiliated with Disney Interactive or Argonaut Games.
|
||
**No game files are included** – no executable, no level data, no music, no decompiled code. You
|
||
need your own copy of the game; every tool works on that copy. Please share only tools and your own
|
||
content (`.llamalevel` projects contain only your changes), not the game's files.
|