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/textures.md

@@ -0,0 +1,53 @@
+# Textures (TEXT chunk)
+
+Each level carries its own textures. Parse and rebuild are byte-identical for all level WADs
+(including the RLE encoder). Code: [`format/TextChunk.java`](../../src/main/java/com/eliasmueller/llamamod/format/TextChunk.java),
+[`tools/textchunk.py`](../../tools/textchunk.py). Lab notes: [notes/textures.md](../../notes/textures.md),
+editor side: [notes/editor-tools-textures.md](../../notes/editor-tools-textures.md).
+
+## Layout
+
+```
+u32 nPal                      0 in all WADs (8-bit palettes are unused)
+u32 nPages                    13–22 per level, all 256×256
+  nPages × { u32 flags, u32 w, u32 h, data }
+     flags & 0x80 : u32 length + RLE16      (all original pages)
+     other ≠ 0    : w·h raw u16
+u32 nTex                      ~180–1260 texture entries
+  nTex × { u16 flags, u8 page, u8 clut (0xff), u8 x0, x1, y0, y1 }    (edges inclusive)
+u32 nAnim                     texture animations
+  nAnim × { u16 texIndex, u8 type, payload }    type 8 = flip book: list of texture indices
+```
+
+RLE16: a sequence of s16 *n*; *n* > 0 → *n* literal pixels follow, *n* < 0 → the next pixel
+repeated −*n* times.
+
+## Pixels
+
+16 bit in **PlayStation order**: bits 0–4 red, 5–9 green, 10–14 blue, bit 15 = STP
+(semi-transparency). `0x0000` is fully transparent. Export to PNG uses alpha 0 = `0x0000`,
+alpha 128 = STP 0, alpha 255 = STP 1. The page flags (low 7 bits) select the blend class:
+1/6 opaque, 4/7 alpha blend, 5 another blend mode, 2/3 special converters (*likely* the
+PlayStation semi-transparency modes; details open).
+
+## Texture entries
+
+A face never has its own UVs: it names a **texture entry**, a rectangle on a page, and shows half
+of it ([Geometry](geometry.md#no-free-texture-coordinates)). Entry flag bit 0 = flat colour (the
+rectangle bytes are R, G, B instead) – the level builder appends such entries for plain colours.
+Other entry flag bits (blend mode, size class) are only partly understood.
+
+Limits: at most **127 pages** per level (signed page byte) and 65535 entries (u16 face field).
+
+## Changing textures
+
+* **Replace pixels, keep the table.** Exporting pages to PNG and importing them back changes no
+  index anywhere: `tools/text_export.py export level.wad dir` / `import level.wad dir new.wad`.
+* **Add pages and entries.** New pages and entries are appended; faces then use the new indices.
+  The editor's texture manager does this, including colour reduction, painting onto faces and
+  flip-book animations ([manual chapter 8](../manual/08-textures.md)).
+* **Same name, same picture.** Texture *indices* differ between base levels. The builders resolve
+  texture names (`grass`, `stone`, …) by picture fingerprint on each base and copy missing
+  village pictures over ([notes/levelbau.md](../../notes/levelbau.md)).
+
+![Contact sheet of the Village 1 textures with their indices, made by tools/texsheet.py](../img/village-textures.jpg)