llamamod/docs/reference/textures.md

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, tools/textchunk.py. Lab notes: notes/textures.md, editor side: 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). 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).
• 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).