173 lines
9.8 KiB
Markdown
173 lines
9.8 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:
|
||
|
||
| | |
|
||
|---|---|
|
||
|  |  |
|
||
| **Test World**: all 253 figures and objects of the game in one level | **Alligator Arena**: a minigame with new, scripted enemies |
|
||
|  |  |
|
||
| **Llama Coaster**: a new roller coaster track for the catacombs cart | **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, Llama Coaster, 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** (the CD or an ISO image of it). Nothing else – LlamaMod
|
||
brings everything it needs (also Java).
|
||
|
||
**Supported game versions:** the **German CD** (*Ein Königreich für ein Lama*, `groove.exe` of
|
||
2001-02-12 – the version everything was developed and tested with) and the **English first release**
|
||
(*The Emperor's New Groove*, `groove.exe` of 2000-10-17). With any other version the level mods
|
||
(Test World, Arena, Coaster, your own levels, Mirror, Randomizer, Draw distance, Debug wireframe)
|
||
should still work; the mods marked *modifies groove.exe* stop with a clear message instead – then
|
||
please send us that `groove.exe` so we can add it.
|
||
|
||
### Install in 5 steps
|
||
|
||
1. **Download** from the **Releases** page of this repository (top of the page):
|
||
* Windows: `LlamaMod-<version>-full-windows-x64.zip`
|
||
* Linux: `LlamaMod-<version>-full-linux-x64.tar.gz`
|
||
|
||
(*full* = with the level editor. The *launcher* packages are the same without the editor.)
|
||
2. **Unpack** it into any folder you like (for example *Documents* or your home folder).
|
||
There is no installer and you need no admin rights.
|
||
3. **Start** LlamaMod:
|
||
* Windows: double-click **`LlamaMod.exe`**. If Windows says *"Windows protected your PC"*,
|
||
click **More info → Run anyway** (the program is not signed, that's all).
|
||
* Linux: install Wine once (`sudo apt install wine` on Ubuntu/Mint/Debian), then double-click
|
||
**`LlamaMod`** or run `./LlamaMod`. `./install-desktop-entry.sh` adds it to your app menu.
|
||
4. **Set up the game** – on the first start a short wizard asks for your game: put the CD in or
|
||
pick the ISO file, click **Set up** and wait about a minute. Your CD/ISO is only read, never
|
||
changed.
|
||
5. **Play** – on the **Mods** tab tick the mods you want, click **Apply**, then **Play**.
|
||
*Restore original* switches all mods off again.
|
||
|
||
New levels (Test World, Alligator Arena, Llama Coaster, your own) are in the hidden world
|
||
**TestLevel**: open the **Save games** tab once and click **Unlock TestLevel**, then pick it on the
|
||
world map. If your antivirus complains about `groove.exe`: mods that change the game program are
|
||
marked *modifies groove.exe*; LlamaMod tells you what to do. More help:
|
||
[Troubleshooting](docs/manual/20-troubleshooting.md). 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` |
|
||
| `LAMA_MOD` | the `lama-mod` script used by `lamatest.py` | `~/.local/bin/lama-mod`, else `tools/lama-mod` |
|
||
| `APPTEST_ROOT`, `APPTEST_ISO` | session folders and ISO of `apptest.py` | `~/.cache/llamamod-apptest` (`$CLAUDE_JOB_DIR/tmp` if set), `~/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.
|