PSX TIM (texture) Confirmed

At a glance

In the game

Every texture: character skins, floors and walls, the world map, UI panels and cursors, menu glyphs and the dialog font.

Magic

0x00000010 as the first u32

Lives in

Inside PROT.DAT entries (usually behind LZS), inside TIM-packs and field-packs, and two in the unindexed head gap of PROT.DAT before the first entry (0x018E0, 0x11218)

Parser

crates/tim (parse, parse_strict, PNG export, encode PNG-to-TIM); catalogs legaia_asset::tim_catalog / tim_deep_catalog / tim_labels

Confidence

Confirmed - public format; Legaia's upload habits byte-checked against retail VRAM dumps.

Used by

Renderer, Asset viewer, ROM patcher

What a TIM is

The PSX has 1 MB of video memory (VRAM), one 1024×512 grid of 16-bit pixels. A TIM is a “VRAM-ready” image: a rectangle of pixel data plus the VRAM coordinates it uploads to. Most textures are palettised - 4-bit (16 colours) or 8-bit (256 colours) indices - and the palette, the CLUT (colour look-up table), is itself just another small rectangle of VRAM pixels, usually one row of 16 or 256 entries.

Every TIM in the streaming files is 4bpp with a CLUT. Most sit inside PROT.DAT entries behind LZS compression; two UI sheets sit in the unindexed gap before the first entry, where no per-entry walker reaches them.

One image, many palettes

A 4bpp CLUT block may hold several 16-entry rows, so one sheet of indexed shapes is recoloured per use by picking a row. Legaia's system-UI sheets work this way.

asset-viewer tim extracted/PROT.DAT --offset 0x018E0 --clut 2   # panel chrome
asset-viewer tim extracted/PROT.DAT --offset 0x018E0 --clut 7   # cursor

Flat-strip CLUT uploads: when the header lies

This is the trap that makes textures “disappear” in a straightforward renderer. Two TIM families declare a multi-row CLUT rectangle that would run off the bottom of VRAM. The game does not upload that rectangle - it uploads the palette as one flat horizontal strip of w × h entries at the block's origin.

Town meshes address cells mid-strip (town01 uses (64, 510) = strip entry 64) with texture pages inside the (960, 256) image. A renderer that honours the declared rectangle clips the rows past y = 512, leaves the strip empty, and the meshes sampling it render black or drop - even though every byte is on the disc. Row 510 in every captured field save is byte-identical to the strip upload.

Cataloging every TIM on the disc

Scanning PROT.DAT as one flat stream (rather than per entry) catches every raw TIM whichever addressing layer hosts it, including the head-gap sheets. Two tiers, one label table:

Both tiers admit a hit only through parse_strict: no reserved flag bits, pixel mode 0..3, block sizes exactly 12 + w*h*2, non-zero dimensions, image rectangle inside VRAM. The CLUT rectangle is deliberately not bounds-checked - the row-479 palette band parks legitimate blocks at rows 510..511 with heights up to 16. The deep tier additionally requires the decoded bytes to render to RGBA, because LZS decompresses anything without error. The asset viewer builds both catalogs live from a user-supplied disc.

Encoding: PNG to TIM (texture replacement)

A replacement texture only works if it is the same size as the original, so it drops into the same slot on the disc. legaia_tim::encode copies the original's structure verbatim - pixel mode, block dimensions, every VRAM placement field - and takes pixels from caller-supplied RGBA. It backs legaia-patcher tim-replace and the ROM patcher's texture panel.

Alpha to STP mapping

PSX texels carry a 1-bit semi-transparency flag (STP), not an alpha channel:

Palette fitting

• A pixel whose position held the same colour keeps its original index verbatim; other matches reuse the first palette entry that decodes to the colour. Untouched regions keep their STP choices, so encode(decode(tim)) reproduces the original byte-for-byte across the whole raw catalog.
• Indexed modes must fit 16 / 256 distinct 15-bit colours. New colours overwrite slots the new image no longer references; overflow is a hard error listing the offending pixels, or, behind an explicit quantize opt-in, the least-frequent extras fold to their nearest palette colour.
• If any palette slot changes, the rebuilt palette is replicated into every CLUT row, so multi-palette variants do not recolour new indices with stale rows.

VRAM emulation in the engine port

crates/engine-render keeps a 1024×512 R16Uint VRAM page so the per-primitive palette and texture-page selectors (CBA / TSB) plus 4/8/15bpp CLUT decoding run in a fragment shader. The viewer uploads every sibling TIM into VRAM so multi-page meshes bind the right CLUT. Some character meshes reference CLUT rows in other PROT entries than their mesh; the viewer's --vram-extra-dir flag covers scene types whose chain is not traced.

How we know

See also