# Level building with `tools/levelbuild.py`

As of: 2026-11-06 (exit + parkour reworked). Builds complete level WADs from a level description (Python script).
The base is always an original level (default: village `t1l1m001.wad`): its strat code/object models
(STPC), textures (TEXT), sound etc. are taken over; **geometry (TRAK), tile grid,
vertex colours, objects and waypoints (MAP) are generated completely from scratch.**
Result checked in game: `out/testwelt.wad` (= installed test world, see below).

## Invocation

```
python3 tools/levelbuild.py levels/testwelt.py out/testwelt.wad            # build
python3 tools/levelbuild.py levels/testwelt.py out/testwelt.wad --install  # + install as TestLevel
python3 tools/levelbuild.py levels/testwelt.py out/t.wad --set start=ziel  # pass variables to the script
python3 tools/levelbuild.py --types                 # placeable strat types of the base level
python3 tools/levelbuild.py --textures tex.png      # texture contact sheet + name list
python3 tools/texsheet.py WAD out.png [--all] [--only 1,2,3] [--size 96]
```
`--install` copies to `~/.wine-lama/mods/testlevel/wads/T1L9M001.wad` (creates
`.orig` once) and creates the chapter symlinks 2..49 (see "Exit"). Test in game: `tools/lamatest.py run out/x.wad outdir` (see testharness.md).

## Level script

```python
LEVEL_ARGS = dict(name='Testwelt', seed=7)      # NAME chunk, random seed (texture rotation)

def build(L):                                     # L = levelbuild.Level
    L.sea(0, 0, 88, 72, y=-2.0, kill=(6, 4, 80, 66))   # sea + death plane
    L.box(14, 12, 26, 24, -0.4, 0, top='stein', side='stein')
    L.stairs(26, 18, 29, 22, 0, 1.5, 3, '+x')
    L.player(20, 14.5, rot=0)
    L.checkpoint(17, 18.5)
    L.exit(70.5, 12.5)
    L.strat('Bunny', 66, 34)
    L.coins([(27, 20), (28, 20)])

def report(L):                                    # optional, after building
    ...
```
`L.opts` contains the `--set` values (strings).

### Coordinates
* Game coordinates as for strats: **x towards east, y up, z = grid row (positive,
  "south")**, 1 unit = 1 grid cell. Village grid: 96×96 → everything must lie within x,z ∈ [0,96).
* Angles in **degrees**, 0° = facing +z, 90° = facing +x (checked in game).
* Internally converted into export space (z mirrored); winding order is corrected
  automatically (`_orient`), you only specify the desired outward normal.

### Geometry building blocks
| Method | Description |
|---|---|
| `floor(x0,z0,x1,z1,y, tex, rot='random', coll=True)` | horizontal surface (subdivided into 1×1 tiles) |
| `box(x0,z0,x1,z1,y0,y1, top, side, side_top=None, bottom=None, sides='nesw', side_coll=None)` | cuboid; `side_top` = texture of the topmost wall row (e.g. `'graskante'`), `side_coll=False` = walls without collision (low plinths walkable) |
| `platform(x,z,w,d,y, top, side, thick=0.5, side_top='graskante', bottom='erde')` | floating platform, top edge y |
| `pillar(x,z,y0,y1,size, side, top)` | pillar around a centre point |
| `ramp(x0,z0,x1,z1, ya, yb, '+x', top, side, base)` | ramp, rises in direction `+x/-x/+z/-z` |
| `stairs(x0,z0,x1,z1, y0, y1, n, '+x', top, side, base, walkable=True)` | stairs; `walkable`: invisible slope as collision |
| `fence(pts, y, height)` | fence (posts + rail) along a point list |
| `tree(x,z,y, height, crown)` | blocky tree |
| `sea(x0,z0,x1,z1, y, tex='meer', kill=(...))` | water surface without collision + death plane |
| `quad([BL,BR,TR,TL], tex, coll, rot)` | single quad (corners seen from the front) |
| `collider(pts, normal)` | invisible collision surface |
| `obj(path, offset, scale, tex)` | OBJ file (game coordinates), `usemtl tex_N` or texture name |
| `height_at(x,z)` | height of the topmost walkable surface |

Textures: name from `TEX` (village: `gras, gras2, gras_dunkel, blumen, sand, erde, graskante,
stein, stein_kante, stein_moos, platte, holz_dunkel, holz_maser, holzbalken, rinde, kiste,
inka, muster_lila, …`), a direct index (int) or a flat colour (`'meer'`, `'rot'`, … or
`(r,g,b)`; appended to the texture table as a flat-colour entry (flags 0x105, page −1)).
Contact sheet with indices: `notes/img/texturen_dorf.png`.
**Every triangle shows a whole texture tile** (the engine has no free UVs) – so
everything is split into 1×1 pieces; narrow/flat walls show the texture squashed.

### Lighting (vertex colours)
`L.sun = dict(azimuth=215, elevation=50, color=(1,.93,.8), strength=.62, sky=(.5,.55,.66),
ground=(.3,.28,.24), ao=.55, ao_radius=1.3, shadow=.35)` – per vertex:
sky/ground hemisphere light + sun (Lambert) with **shadows** (ray towards the sun against all
cuboids) + **ambient occlusion** (24 rays, range `ao_radius`). Cuboids, pillars,
stairs, platforms register as shadow casters (`solids`). 1.0 = texture colour
(vertex colour 0x80), max. 2.0. `tint=(r,g,b)` multiplies per building block.

### Objects (strats)
`L.strat(name, x, z, y=None, rot=None, params=None, wp='relative', variant=0, hidden=False)`
* `y=None`: place on the topmost walkable surface at (x,z).
* Type fields (nvars, slots, flags, extra memory) and parameters are copied from the **first
  original instance** of the type (`params=[…]` overrides; count must match).
* `variant`: types with several code entry points (e.g. SmashPot: 2 spawn stubs).
* **Waypoints** (`wp`): `'relative'` = move the original's waypoint chain along (offset to the
  object is kept, y is set to the floor if there is one), `'here'` = all points on
  the object, `'none'` = none (−1), or your own list `[(x,z[,y[,deg]]), …]` (extra fields
  of the original waypoints are taken over). Chains are renumbered (no references into the
  old level).
* `player(x,z,rot)` (strat `Llama`), `checkpoint(x,z)` (`CheckPointPost`), `exit(x,z)`
  (`LevelDoor`), `coins([(x,z),…])`.
* Types that are in the village code but not placed there, via `Strats.BORROWED` with type fields
  from another level: currently `RubyIdol` (from t1l1m002).
* `poolExtra` is set to max(original, number of strats + 80); the original's parameter pool
  is kept, new parameters are appended.

### What `build()` generates
1. All triangles are distributed onto tiles by (grid cell, height band of 10 units from y = −3);
   tile origin = cell centre/band centre (collision d must be within ±8).
2. **Collision**: every quad with `coll=True` becomes a collision polygon; floors only in their
   own cell, walls/slopes additionally in neighbouring cells up to 0.3 distance (the engine only checks
   the tiles of the cell the player stands in). Unused helper vertices make sure
   the tile box encloses the collision polygons.
3. Identical tile models are merged (vertex colours are stored per tile in MAP).
4. **Death plane**: original model 0 of the village (invisible, material 0x1e) in every cell
   of the `kill` area that is not completely covered by floor.
5. MAP: zone grid = 0, zone 0 sees everything (mask 0xffffffff), no tile swaps (alt block
   empty), tile blocks A/B/models/vertex colours consistent, strats + waypoints new, light/
   environment zones (90-byte block) and rest unchanged.
6. TEXT: appended flat colours. NAME: `LEVEL_ARGS['name']`.
7. Cross-check: MAP is fully parsed again after writing.

## Findings from the game tests (lamatest, Xvfb)
* **Scale**: llama ≈ 0.6 units tall, walks ≈ 1.1 units/s (coin measuring track, see below; the
  0.85 noted earlier was too low), needs ~1 s to accelerate. A jump (X) clears
  0.35 high edges, 0.5 not. **With a run-up it flies ~1.3 far** (horizontally as fast as
  when walking), onto +0.2 it lands after ~1.05; from standing much shorter (0.5 gap not
  cleared). → Parkour: gaps 0.3 with +0.2, platforms before/after ≥ 1.5 long (after
  landing there must be room for the next take-off), larger heights via stairs/ramps.
  Measuring level: `levels/sprunglabor.py` (`--set spur=a..g|m`; `m` = coin measuring track: a coin every 0.25 →
  coin counter × 0.25 = distance walked; `f` = long jump over water).
* **No step logic**: even a 0.12 high edge *with wall collision* blocks the llama.
  Without wall collision (`side_coll=False`) it walks up onto low plinths; stairs with
  an invisible slope (`stairs(walkable=True)`) and ramps are walkable (checked).
* **Controls are camera-relative** (Up = camera view direction). The start camera is behind
  the llama; if there is an obstacle right behind it (e.g. a post), it moves aside →
  keep the area behind start points clear.
* Rot 0° = facing +z, 90° = facing +x.
* **Death plane works**: falling into the sea → health gone, respawn at the last
  checkpoint (or start).
* Player waypoint chain (14 points for the village llama, meaning unclear): `player()` puts the
  first one 8 units behind the llama, the rest on the llama, extra fields from the original.
* **LevelDoor** (exit) – solved, see section "Exit (LevelDoor)" below.
* Sizes that work: TRAK 0.6–1.0 MB, up to 1100 models, 5200 tiles, WAD up to 6.9 MB
  (originals: TRAK ≤ 1 MB, ≤ 5800 tiles, WAD ≤ 6.85 MB). Test world: 628 models,
  2474 tiles, TRAK 646 KB, WAD 6.3 MB.

## Exit (LevelDoor) – how it works

Strat bytecode (village, STPC 0x430332, 3 parameters, invisible, no model), decoded via the
VM `FUN_0054d180` (opcode < 0x45: table 0x5796bc with 16-bit operand, otherwise 0x578ff4+op·4):
```
g65,g66,g67 = param 0,1,2            ; tribe, world, chapter of the next level (20.12)
loop:  if g21 == 3                    ; game state "running"
   and player.floor.material == 16     ; property 0x11 = *(strat+0xc0)+4 = material byte of the
                                       ; collision polygon below the player (FUN_00403020)
   and floor(player.x) == floor(door.x) and floor(player.z) == floor(door.z)   ; same grid cell
   -> op 0x192 (FUN_0054d620): level change(param), g1 += 1, end
   yield
```
* So the door is only a trigger; in the village there is a floor polygon with
  **material 16** in the doorway (8 of them in the village, also in all other levels). Our test world had
  material 0 everywhere → nothing happened. **Fix:** mosaic in the gate with `mat=16` (`box(..., mat=TUER_MAT)`),
  door in the same grid cell, the player's path leads right through it.
* **Only tiles of the door cell count** (cell list, FUN_004036d0), not the height (t1l3m002–4: floor
  3 units below the door). **Village 1 & co.:** the door cell initially contains *no* material 16 –
  it is in the **swap model** of the tile (MAP tile swap, WFPC 0x10000): the RubyIdolDoor in
  the same cell swaps tile 420 from model 48 to 49 when opening (op 0x11a/0x11b), and only
  model 49 has the exit pad (42.25–42.75 / 49.23–49.50, y 3.25). Checked in game
  (2026-11-07): model 49 inserted + door removed, llama at 42.5/3.5/49.37 → immediately the summary
  "Dorf Kapitel 1"; original (door closed) → nothing. Affects 8 of the 31 original doors (Ruby,
  PressurePad, Lab doors); the pad at 43.5/48.45 (cell 43,48), on the other hand, is a house entrance
  (zone teleport). t1l3m003: 2 of the 4 doors (cells 71,48/71,49) have no pad at all.
* Second path (strat code at 0x4252aa, player logic [likely]): floor material 16 and cell =
  g104/g105 (set by the LevelDoor at start, Llama sets them to −1) → level change(g101..g103).
* Parameters in the originals: (1, world, chapter+1) = next chapter; in the last chapter of a
  world **(7,7,7)** = "world completed" → back to the selection map, unlock the next world.
* `FUN_0054d620`: remembers the current level (0x585008..14), sets the next (0x584eb4/b8/bc), shows the
  summary (coins x/55, secrets) with "EINGABETASTE = speichern / ESC = weiter" (Enter = save / Esc = continue). Progress
  0x585018/19 (max. world/chapter, in KSV +0x42/+0x43): if you are in the highest unlocked chapter,
  the next chapter is unlocked; with (7,7,7) the next world.
* **(7,7,7) in world 9 crashes**: unlocks "world 10" → after saving, the
  map cursor is on world 10, world name pointer 0x57bd40[9] = NULL → page fault at 0x41B5CC.
* **Solution for the test world: parameters (1,9,1)** – after the summary chapter 1 is reloaded (no
  crash, tested with saving). Side effect: chapter 2 is unlocked (and from
  chapter n, chapter n+1). If its WAD is missing, the selection crashes ("Couldnt load wad").
  That is why `levelbuild.py --install` (function `kapitel_links()`) creates in the mod
  **symlinks T1L9M002..049.wad → T1L9M001.wad and T192..T1949.COR → T191.COR** (world 9 has
  49 chapter slots, table 0x572420) and calls `lama-mod an`. For this, `lama-mod` now also takes
  symlinks from mod folders (`find … -type f -o -type l`). Checked: chapter 2 on the map is
  selectable and loads the test world.
* The selection map shows no background for world 9 (only text) and 772 as the coin target
  (coin table 0x5722f4 only has worlds 1–8) – cosmetic.

## The test world (`levels/testwelt.py` → `out/testwelt.wad`, installed as T1L9M001.wad)
**Rebuilt compactly on 2026-11-06** ("everything closer together"): L-shaped island, main part 32.5×23.5
(x 11..43.5, z 9.5..33) + strip below the parkour end (x 43.5..49, z 9.5..20.5), previously
42×34 (x 10..52, z 8..42). Gallery, enclosure and parkour adjoin each other directly, no empty
meadows any more. NAME chunk "Testwelt" (not shown anywhere in the game).
Preview images (phone, 1280 px): `notes/img/vorschau/` (01–03 Blender renderings with
labels, 04–11 game shots, 12 montage). Older images `notes/img/testwelt_*.jpg` still show
the old, sprawling layout.

| Area | old | new |
|---|---|---|
| Start square | x 14..22, z 11..19 (8×8) | x 15..21, z 12..19 (6×7) |
| Gallery | z 22..38, columns 2.5, rows z 25/28.5/32/35.5 | x 14.5..32.5, z 20.5..32, columns 1.9, rows z 22.5/25.2/27.9/30.6 (spacing 2.7) |
| Enclosure | x 39..49, z 24..35 | x 33..42, z 20.8..30 (directly east of the gallery) |
| Parkour | x 22..53.6 | x 21..52.6 (only shifted by −1 in x, same dimensions) |
| Exit | LevelDoor (51.5/15.5) | LevelDoor (50.5/15.5), cell 50/15, mosaic with material 16 |

* **Start square** (x 15..21, z 12..19): stone square with Inca mosaic, 4 Inca pillars, flower beds,
  trees, 2 coins, checkpoint (16.1/17.4). The llama starts at (18, 14.6) facing south
  (gallery directly behind it, parkour stairs on the left of the picture).
* **Gallery** (z 20.5..32): 4 rows, each object on a flat plinth (0.9 wide, 0.08 high,
  walkable), gap 1.0 between plinths, sand path (0.6) in front of each row, coloured post at the
  start of the row (yellow/grey/blue/red), main path north–south at x 15.6..16.3:
  1. Collectables: Coin, ChargeBooster, RubyIdol, HealthFull, HealthGenerator, ChacaChargePotion, Secret
  2. Crates/pots: SmashPot (2 variants), Jar, ObjectDontDropInBox, WaterReboundPoints, CheatTeleport
  3. Characters: TipoVillage, ChacaVillage, PachaGivingInfo, KidOnLlama, Wompy
  4. Mechanics: PressurePadDoor, RubyIdolDoor, SwitchPlatformPadVillage, AppearingPlatformsVillage,
     RisingColumns, SinkingStatue, FallingTree, CheckPointPost
* **Enclosure** (x 33..42, z 20.8..30, fence, entrance on the west side z 20.8..24): Bunny ×2, Ladybird,
  FlockOfBirds, VillagerHerder; viewing pedestal (0.6) with stairs on the west side between
  gallery rows 2 and 3.
* **Parkour** (starts at the east edge of the square, **everything on the line z = 15.5 going east**,
  so it can be done without rotating the camera – rotating via A/S or Left/Right was not
  reproducible in scripts). Geometry is written in the script as "old x + PX" (PX = −1):
  stairs 0→0.8 · **stop step** +0.3 (no gap: the llama runs into it and stands still) ·
  2 gaps of 0.3 with +0.2 each onto 1.5 long wooden blocks · beam 0.5 wide · middle platform (1.5) with
  checkpoint · sand ramp 1.5→2.4 · **stop step** +0.3 · 3 stepping stones (1.5 long, gaps 0.3,
  +0.2 each) · narrow beam 0.45 · stairs 3.3→4.0 · goal platform (4.0; x 47.6..52.6, juts out over
  the coast) with pillars, parapet and gate; below it a mosaic with material 16, LevelDoor at
  (50.5 / 15.5). 18 coins along the way. Below the parkour there is meadow (falling down is harmless).
* **Scripted run** (start → goal → exit → summary), old version 4/4, compact version 2/2
  runs successful (summary 18/55 coins); the .seq is time-based/relative and stayed unchanged:
  ```
  python3 tools/levelbuild.py levels/testwelt.py out/testwelt_parkour.wad --set start=parkour
  lamatest.py run out/testwelt_parkour.wad OUTDIR --seq "$(cat levels/testwelt_parkour.seq)"
  ```
  (`run:T:x@t,…` holds Up for T s and presses X at fixed times; the stop steps reset the
  timing error. Shots (`shot@`) block ~0.4 s → never shortly before a jump.)
* Checked in game: loading without a crash (many runs), all 31 gallery objects appear
  (coin/secret/… react: coin counter, "GEHEIMNIS!"), the llama walks through gallery/enclosure,
  up the stairs, jumps onto platform B and onto stepping stone 1, up the ramp, stairs to the
  goal platform, sea = respawn, complete parkour by script, exit → summary → chapter 1 again.
  Images: current `notes/img/vorschau/` (compact layout); `notes/img/testwelt_*.jpg` =
  old sprawling layout (1–6 + montage even still with the old parkour).
* Start point for tests is switchable: `--set start=platz|reihe1..4|weg1..4|gehege|podest|parkour|pk1..pk5|ziel|ziel2`
  (`podest` = on the viewing pedestal, looking west over the gallery);
  exit parameters `--set tuer=1,9,1`.

### Village types not placed
| Type | Reason |
|---|---|
| Llama | is the player (start) |
| LevelDoor | exit at the end of the parkour (needs a floor with material 16, see above) |
| CameraSide | camera zone, invisible |
| CutSceneCameraDirectional | cutscene camera, invisible |
| CutSceneTrigger | starts a cutscene |
No placeable type crashed the game (no bisection needed).
Note: mechanics objects (doors, pillars, statue) belong to specific geometry /
tile swaps in the village; in the gallery they stand "bare" (e.g. a floating RubyIdolDoor sign).
Types that only exist in the code (BouncingCoin, Sparkles, RubyIdolStatue …) have no
original instance with type fields and are not offered (exception: RubyIdol via `Strats.BORROWED`).

## Preview renderings (Blender)
`/usr/bin/blender` (Debian 3.0.1): **Cycles renders only black** (even the default scene), OCIO
is missing ("Color management: fallback", only the "Standard" view). **Eevee works**, but needs an
X display → own `Xvfb :7` (never :0, :5 belongs to lamatest). Procedure (scripts in
`tools/vorschau/`: `strats_json.py` (call from levelbau/), `render_level.py`, `label.py`):
1. `geom_export.py out/testwelt.wad GE` → level.obj/mtl + page_NN.png
2. Strat positions: run the level script with `levelbuild.Level` (without `L.build`), `L.strats` as JSON
3. `DISPLAY=:7 STRATS=strats.json VIEWS=schraeg,schraeg2,oben blender -b -P render_level.py -- GE r 64`:
   own OBJ reader (the 3.0 importer does not know vertex colours), mirroring OBJ→game (y_blender =
   −game z, flip winding), material = texture (closest) × vertex colour, a little emission,
   sun + sky, markers for strats (coins gold, llama start orange cone, gallery objects
   in row colour, animals white, exit purple ring); writes PNG + JSON per view with
   image coordinates of the area names.
4. PIL: scale to 1280 px, labels (Start/Galerie/Gehege/Parkour/Ziel), JPG q85.