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/guide/design-rules.md

@@ -0,0 +1,48 @@
+# Design rules
+
+The numbers and rules that matter when you design a level for this engine. Background and sources:
+[Engine facts and limits](../reference/engine-limits.md).
+
+## Sizes to design with
+
+| | |
+|---|---|
+| one grid cell | 1 unit |
+| llama | 0.6 tall, walks 1.1 units/s |
+| jump up | ≤ 0.35 (0.5 fails) |
+| jump across, with a run-up | ~1.3 (from standing much less) |
+| easy parkour | gaps 0.3 with +0.2 height, platforms ≥ 1.5 long |
+| steps without jumping | none – use slopes or walls without collision |
+| draw distance | the fog end of the zone: 8–16 cells in the originals |
+| objects visible | within ~12.5 units of the llama |
+
+![The Test World's gallery: every figure of the game on a pedestal](../img/testworld-gallery.jpg)
+
+## Rules that keep the level working
+
+1. **One player start**, with nothing solid right behind the llama (start camera).
+2. **Exit = LevelDoor + floor with collision material 16 in the same cell.** Target (1, 9,
+   chapter) in TestLevel – never (7, 7, 7).
+3. **A death floor or death plane** under every place the llama can fall to.
+4. **A checkpoint** before every hard part.
+5. **TestLevel chapter 1 or 32–49** for new levels.
+6. **Guards and box walkers need their waypoint boxes** (and guards an event bit someone sets),
+   or the game removes them.
+7. **Every area must be visible from where the camera is**: with visibility regions, check the
+   masks (*Check for problems* reports regions nothing can see).
+8. **Stay within the budget**: 16 MB level memory, 127 texture pages, 128 sounds – the import
+   preview and *Check for problems* show where you are.
+
+The editor and both level builders enforce the data-level rules (tiles inside the grid, vertex
+colours, type fields, collision cells) automatically. *Check for problems* reports the rest.
+
+## Good habits
+
+* **Play-test often** (F5). The engine is unforgiving and a small change can stop the exit or
+  hide an area.
+* **Look at the originals.** Open an original level in the editor and see how it builds doors,
+  cameras and enemy paths; the [debug view mod](../tools.md#debug-view) shows collision and
+  invisible objects in the running game.
+* **Keep levels compact.** Short sight lines hide the draw distance and keep the frame rate up.
+* **Copy numbers** (speeds, parameters, waypoint fields) from original objects that already do
+  what you want.