documentation for level builders: docs index, step-by-step guide, file format reference (wad, geometry, objects, textures, audio, testlevel chapters, engine limits), strat vm and script language with the arena as worked example, tools overview, developer notes; readme rewritten as project front page with screenshots; review notes moved to notes/dev

docs/reference/engine-limits.md

@@ -0,0 +1,67 @@
+# Engine facts and limits
+
+Numbers to design levels with, and the things that crash the game. Measured in the game with the
+test harness unless noted.
+
+## Scale and movement
+
+One unit = one grid cell. Measured with the jump lab ([`levels/sprunglabor.py`](../../levels/sprunglabor.py))
+and a coin measuring track ([notes/levelbau.md](../../notes/levelbau.md#findings-from-the-game-tests-lamatest-xvfb)):
+
+| Quantity | Value |
+|---|---|
+| llama height | about 0.6 |
+| walking speed | about 1.1 units/s (≈ 1 s to accelerate) |
+| highest edge a jump clears | 0.35 (0.5 is too high) |
+| long jump with a run-up | about 1.3 units (from standing: much shorter, a 0.5 gap fails) |
+| comfortable parkour | gaps of 0.3 with +0.2 height, platforms ≥ 1.5 long |
+| step-up without jumping | none – any edge with wall collision blocks; use slopes or walls without collision |
+| frame rate of the logic | 30 frames per second (script speeds are per frame) |
+
+Controls are **camera-relative**; the start camera sits behind the llama and moves aside if
+something solid is right behind it – keep the area behind start points clear.
+
+## Drawing
+
+| Fact | Value |
+|---|---|
+| draw distance | = **fog end** of the active environment zone; originals 7–16 cells at detail *Maximum* (roller coaster up to 23), about half at *Minimum* |
+| objects | drawn only within about **12.5 units of the llama** (they keep running); their activity radius also follows the fog end |
+| hidden areas | visibility regions: a cell is drawn only if the camera region's mask contains its region |
+| texture coordinates | none per vertex – every triangle shows half of a texture rectangle |
+| lights | light only object models; tiles use baked vertex colours |
+
+The *Draw distance* mod scales all fog values of all levels
+([notes/mod-fog.md](../../notes/mod-fog.md)).
+
+## Memory and counts
+
+| Limit | Value | Source |
+|---|---|---|
+| level memory | **16 MB** for STPC, TEXT, TRAK, MAP, LGPC and the strat pool; originals use up to ~7 MB | `FUN_0041eea0` |
+| strat heap | 65533 words (≈ 256 KB) for strat slots (0x154 bytes each), collision blocks and variables | `FUN_0041ae20` |
+| strat slots | `poolExtra + 30` – must cover placed **and** spawned objects | MAP |
+| vertices per tile model | 8000 (transform buffer) | |
+| collision polygon | within ±8 units of its tile's origin | i16 fixed point |
+| texture pages | 127 | signed page byte |
+| texture entries | 65535 | u16 face field |
+| sound samples | 128 per level | signed char id |
+| file sizes that worked | TRAK up to 1 MB, 5800 tiles, WAD up to ~7 MB (originals); the test world: 628 models, 2474 tiles, 6.3 MB | measured |
+
+## Things that crash the game
+
+| Cause | Symptom |
+|---|---|
+| a tile outside the W × H grid | memory corruption, crash on load or later |
+| vertex-colour block not exactly one entry per vertex | objects read shifted, crash |
+| a strat type with collision but type flags 0 (or too few collision-bone words) | page fault in the heap allocator `FUN_0041ae20` |
+| exit target (7, 7, 7) in world 9 | crash after saving (world 10 has no name) |
+| a selectable chapter without a WAD | "Couldnt load wad" on the world map |
+| a waypoint-dependent type without its boxes | not a crash: the game removes the object ("removing strat") |
+| world-9 chapters 2–31 (unpatched exe) | progress, language or options overwritten ([TestLevel](testlevel.md)) |
+
+## Coordinates, numbers, angles
+
+* Game space: x east, y up, z = grid row; strats use 20.12 fixed point (4096 = 1.0).
+* MAP angles: 4096 = 360°; strat angles: 0x1000000 = 360°.
+* Objects on a flat original floor tile stand at `tile.y + 0.25`.