llamamod/notes/editor-tools-textures.md

Level editor – texture tools (editor.tools.textures)

Plugin TexturesEditorPlugin (phase 3). User guide: editor-guide.md#textures.

What it adds

Item	Where
Texture manager	panel textures (bottom dock, Ctrl+Shift+T; Window button = own 1300×760 frame)	pages, atlas, table, details, animation editor
Import texture…	File menu (replaces the built-in file.importTexture), panel toolbar	ImportDialog
Replace texture pixels…	Edit menu, panel toolbar	image → the selected texture's rectangle
Paint texture	tool texpaint, key M (own toolbar group)	PaintTool
Texture eyedropper	Edit menu, key I; Shift+click in the paint tool
Checks	Build/Check	> 127 pages = error, entry on a missing page = error

TexState holds the window's current texture (shared by panel, tool, eyedropper; selecting a TextureEntry anywhere, e.g. in the outliner, makes it current).

Texture manager (TextureManagerPanel)

• Pages: thumbnail, index, blend class of the page format (Blend.ofPage). Context menu: export page PNG, replace page from PNG (scaled to 256×256, reduced with the page's class).
• Atlas: the page (nearest-neighbour, fit to the view until the wheel zooms) with all rectangles: white = used, red = unused, cyan = animated, orange = current with 8 handles. Drag inside the current rectangle = move, handles = resize (one undo step per drag: TextureLibrary.setRect with a merge key). Click selects the smallest rectangle under the cursor; double-click activates the paint tool; tooltips show size/usage.
• Table: #, preview, name (editable), page, rectangle, blend, faces (tile-model faces + brushes), models, animation ("frame" = used as a frame). Filters: all / on this page / used / unused / animated / imported; search by name or number.
• Texture tab: name, X/Y/W/H spinners, blend class (sets the entry flags), raw flags, usage line, Duplicate (new entry with the same rectangle, e.g. for frames), Select users (tiles whose models use it).
• Animation tab (AnimEditor): create/remove, type flip-book / scroll up / scroll down, frame delay (≈ fps at 30 game frames/s), back and forth, frame list (+ − ◀ ▶), scroll band / speed / top row, live preview (AnimSpec.frameAt/offsetAt).

Usage counts (TextureLibrary.usage): faces of TRAK tile models (faces[i+4]), brush string parameters "#n", animation targets and frames. Object (STPC) models are not counted – their textures are in the same table, so "unused" means not used by tiles/brushes/animations.

Import (ImportDialog, ColorReduction, TextureLibrary.importItems)

• Size = longest side (16…256 or original), aspect kept; rectangles need not be powers of two.
• Blend classes (Blend), derived from the flag pairs of all original level WADs (entry flags ↔ page flags & 0x7f, counts over 33 WADs):

Class	entry flags	page flags	originals
Opaque	0x0104	0x81	16 551 entries
Cut-out	0x0406	0x84	1 774
Semi-transparent (mode 1)	0x1406	0x87	528
Additive (mode 2)	0x2406	0x85	649
Darken (mode 3)	0x3406	0x82	574

Others seen: 0x1104/class 6 (186), 0x2104/class 3 (38), 0x4406/class 5 (469), object-model entries 0x8cc6/0xbbc6/0x9cc6/0xb8c6 (bit 15). Entry bits 12–14 = blend mode, 0x400 = has transparent pixels.

• Colour reduction to ABGR1555: alpha < cut → 0x0000; with "keep half-transparent" alpha < 192 → STP 0 (black becomes 0x0421, never 0); optional colour key (magenta / top-left pixel) and 4×4 ordered dithering; opaque class ignores alpha. Preview = the game's 15-bit result.
• Packing: with "pack into free space" the importer searches pages of the same format class for a free block (FreeMap, summed-area table over a 256×256 occupancy mask built from all rectangles plus scroll bands), 8-pixel grid, largest images first; otherwise / if full it appends pages (≤ 127). Optional 1-pixel border (edge pixels repeated) against filtering seams. One undoable Batch: SetProp pixels of changed existing pages (the project stores only the changed pixel runs), AddNode pages, AddNode entries (always appended – faces reference the index).
• Village test: two 32×32 imports land in free space of existing pages, a 200×100 semi-transparent one gets a new 0x87 page; the WAD builds and re-imports (TextureLibraryTest).

Paint tool (PaintTool)

• Hover shows the face under the cursor (white outline) and model/face/texture/flags in the status bar (plus "model shared by n tiles"). Face picking: ctx.pickNode → tile, then a Möller–Trumbore ray test against that tile model's triangles (tile transform, export space).
• Click = assign the current texture; scope Face / Same texture in model / Whole model. Shift+click or the eyedropper button / I = pick. The clicked face stays selected (orange).
• Rotate cycles the face's corners (v0,v1,v2 → v1,v2,v0; winding and plane unchanged), Mirror toggles 0x20 (mirror U), Other half cycles 0x800/0x10 (Geometry.faceUvs: no 0x800 = corners (a,v1)(b,v1)(a,v0); 0x800 = (a,v1)(b,v1)(b,v0); 0x810 = (b,v0)(a,v0)(a,v1)).
• Unique: if the tile's model is shared, the edit first adds a copy of the model and points the tile at it (one undo step).
• Brushes: the clicked side's normal (from three depth samples) picks the parameter top (n.y > 0.7) / bottom / side, else the first texture parameter (tex, post, trunk …); the value becomes "#n". Rotate increments texRot (0–3) of the last painted brush.

Texture animations (decoded, AnimSpec)

Loader FUN_00406e40 (16-byte runtime records at 0x581138, count 0x581134), update FUN_0040c6e0, called once per rendered frame from FUN_0054b590 while the game is not paused. The runtime texture record (20 bytes at 0x581154 + tex·0x14) holds the page and the UVs as floats (+0xc / +0x10 = v0 / v1, divided by the page height at 0x58114c + page·0x20 + 8).

Type	File payload	Behaviour
8 flip-book	delay, n, pingPong, n × u16 texture	every delay+1 frames the texture's runtime record is replaced by the next frame's (loop or back and forth). 214 in the levels (torches, water, flags), e.g. 03 08 00 d0 03 …
1 / 2 scroll	band−1, speed, v0	V range = v0+off … v0+off+band, off −= / += speed per frame, wraps in the band. 7× type 1, 2× type 2 (rivers, lava: 1f 02 01)
10 / 11	band−1, speed, v0, n, n × u16	scroll as 2 / 1, each wrap switches to the next / previous frame. Unused
7 / 9	u16 palette, u16 delay, u8 first, u8 last	palette cycling of 8-bit pages. Unused (no palettes)

The editor viewport does not animate textures; the Animation tab previews them.

Known limits

• Texture entries are never deleted (indices are referenced by faces and object models); unused ones can be reused by moving their rectangle.
• Object (STPC) model faces cannot be painted.
• Painting a shared original tile model changes every tile using it unless Unique is on.
• The page format of an existing page is not changed by the importer; importing into a page of another class is avoided.

Files: src/main/java/com/eliasmueller/llamamod/editor/tools/textures/*, tests TextureLibraryTest (colour reduction, anim round trip of all village animations, packing, build + undo), tour steps TexTourSteps (with playtest.EdTour).