# Llama Level Editor – design brief

Goal (from the project owner): a fully fledged, graphical **3D level editor** for "Ein Königreich für ein Lama"
(Emperor's New Groove PC) – "everything the Argonaut developers probably had available. Support everything that
is possible. Nicely organised, easy to use, well designed." Results are shared as LlamaMod mods.

## Scope
- Create new levels from scratch (primitive building blocks like levels/testwelt, tile painting, objects).
- Open and modify ORIGINAL levels (move/add/delete objects, tiles, waypoints, zones, lights …).
- Import own 3D models (OBJ, glTF) as level geometry incl. textures and collision.
- Import/edit textures.
- Everything the format allows: tiles (TRAK models on the MAP grid, height, rotation, alt models), strats/objects
  with parameters and flags, waypoint chains / paths / camera nodes, environment+teleport/respawn zones (the 90-byte
  records), fog per zone, lights (LGHT), visibility regions (region grid + masks), vertex colours / lighting bake,
  collision polygons and materials (e.g. 16 = exit floor, 30 = death/no floor), level name, music, kill plane.
- Play-test button: build + launch the game straight into the level.

## Architecture
- Same Gradle project (`~/projects/llamamod`), packages under `com.eliasmueller.llamamod.editor`:
  - `editor.model` – scene model (pure data, no UI): Scene, nodes for tiles/brushes/meshes, objects (strats),
    waypoints, zones, lights, regions, materials, assets. Undoable commands (`editor.model.cmd`).
  - `editor.io` – project file format, original-level import (WAD → Scene), build (Scene → WAD) on top of
    `format` and `levelbuild`.
  - `editor.render` – OpenGL viewport (LWJGL 3 via lwjgl3-awt `AWTGLCanvas` inside Swing), textured +
    vertex-coloured rendering, wireframe/collision overlays, picking, gizmos.
  - `editor.ui` – Swing shell (FlatLaf, same look as LlamaMod): menu/toolbar, viewport, outliner (tree),
    inspector (properties), asset browser (models, object types, textures), status bar.
- Launch: from LlamaMod ("Level Editor" button/tab) and standalone `--editor [file]`.
- Natives: LWJGL natives for linux-x64 and windows-x64 must be packaged (both packages).

## Project format (`.llamalevel`)
- A zip: `level.json` (scene) + `assets/` (imported meshes, PNG textures) + `thumbnail.png`.
- Contains NO original game data. Original-level edits store only a reference (`base: "t1l1m001"`) plus edits
  (diff); new levels reference a base level for its object code (STPC) and textures (default `t1l1m001`).
- Deterministic build: same project + same CD → byte-identical WAD.
- Versioned schema (`formatVersion`), forward-compatible loading (unknown fields kept).

## LlamaMod integration
- Every `.llamalevel` in `<data>/levels/` (plus "Import level…") appears as a mod in category `levels`.
- New levels occupy TestLevel (world 9) chapters 1..49; the user picks a free slot (default: next free).
  Edited original levels replace that level's WAD.
- Conflicts (two mods writing the same WAD) are reported clearly.

## Conventions
- English everywhere, only necessary comments, no commits, `./gradlew spotlessApply build` green.
- Reuse `format`, `levelbuild`, `mods.debug` (collision/marker knowledge), `mods.mirror` (env-zone/light layouts).
- Test in game with `tools/apptest.py` (private silent PulseAudio, own Xvfb display; user watches :5).
- UI screenshots on Xvfb (llvmpipe OpenGL works there) – look at them, iterate on design.