# 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 LlamaMod launcher: tick mods, set their options, Apply and Play](docs/img/readme-launcher.jpg)

*The launcher: tick the mods you want, set their options, click Apply and Play.*

![The LlamaMod level editor with Village chapter 1 open](docs/img/readme-editor.jpg)

*The level editor with Village chapter 1 open: outliner (left), 3D view, inspector (right), assets and scripts (bottom).*

More pictures:

| | |
|---|---|
| ![Test World gallery](docs/img/testworld-gallery.jpg) | ![Alligator Arena](docs/manual/img/mod_arena.jpg) |
| **Test World**: all 253 figures and objects of the game in one level | **Alligator Arena**: a minigame with new, scripted enemies |
| ![Llama Coaster](docs/manual/img/mod_coaster.jpg) | ![Debug view](docs/img/debug-view.jpg) |
| **Llama Coaster**: a new roller coaster track for the catacombs cart | **Debug view**: collision and invisible objects in the running game |
| ![glTF in Blender](docs/img/gltf-blender.jpg) | |
| **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.