Images & animations

One file, many pictures

A GAF is a bank of named entries. Each entry contains zero or more frames: a still image, an animation, or a set of alternatives selected by the engine. Each pixel is an 8-bit index into an external palette; the GAF does not contain RGB colors.

Explore a GAF

Small frames. One shared anchor.

PULSE / RLE · 6 frames

6× nearest neighbor · crosshair = anchor

Follow the pointers

The only fixed starting point is the 12-byte file header. Its entry table leads to named entries, then frame-reference tables, then frame headers. A frame’s data pointer leads to pixels or a child-pointer table. Do not assume these blocks are adjacent or ordered.

Byte layouts

Offsets in the file header are file-relative. A + offset in the remaining tables is relative to that record’s start. Sizes are in bytes; u means unsigned and i means signed.

File header · 12 bytes

Scroll table horizontally to see all fields →

Entry header · 40 bytes

Scroll table horizontally to see all fields →

Retail clears the loop byte in memory for one-shot sequences such as weapon explosions and feature burns. The loop flag in the file therefore does not determine every consumer’s final playback behavior. The 40-byte entry is immediately followed by frame_count frame references.

Frame references · 8 bytes each

Scroll table horizontally to see all fields →

The playback cursor advances when its countdown is below 2. A stored 0 or 1 holds for one advance; a value h ≥ 2 holds for exactly h advances. Surveyed values range from 1 to 10 and are constant within an entry. For example, cursorairstrike stores 1, cursorpickup stores 2, and cursornormal stores 10. Timing evidence: 06 R-WFX-01 §1.

Frame header · 24 bytes

Scroll table horizontally to see all fields →

Placement offsets

The pixel at (x_offset, y_offset) in the frame lands at the animation’s anchor, or pen. A leaf frame’s top-left destination is:

left = pen_x - x_offset
top  = pen_y - y_offset

In the pulse example, frame 0 is 12 × 12 with offset (6, 6); frame 5 is 32 × 32 with offset (16, 16). Both centers land at the same pen. Offsets are signed, so a frame can lie entirely to one side of its anchor. GUI gadgets can carry unrelated offsets because their consumer places them using GUI coordinates.

Pixel encoding

Raw pixels and the color key

With compressed = 0, read width × height bytes at data_offset, row by row. The ordinary keyed blitter skips every source index equal to color_key. The bytes still exist in storage; skipping means leave the destination unchanged.

Interactive example

Transparency is an operation, not a color

Before · storage bytes

Index 9 is still in the file.

After · key applied

Index 9 skips the destination. Index 0 stays black.

RLE rows and commands

With compressed = 1, each row begins with a little-endian u16 payload byte count, followed by that many bytes of commands and values. A zero count leaves the entire row transparent. For a nonempty row, expand commands to the frame width.

Malformed rows: retail versus a checked reader

These stricter checks apply to both Nanolathe’s metadata and pixel readers. They are host safety policy, not extra rules enforced by the retail executable. 02 R-MALF-01 §6 owns the malformed-input behavior.

Composed frames

When subframe_count & 0xFF is nonzero, data_offset points to that many u32 absolute child-frame offsets. The ordinary compositor draws the children in table order, all at the same pen. Each leaf uses its own offsets; later opaque pixels cover earlier pixels.

Interactive example

A parent is not a clipping rectangle

Destination clipping

Ordinary retail composition keeps the extensions.

Parent-sized host canvas

A parent-sized intermediate raster loses the outer pixels.

Schematic: dashed line = parent extent; crosshair = shared pen. Green is drawn first, amber second. Ordinary children only; no ALP tint is simulated.

A host that chooses a parent-sized raster places a child at:

child_left = parent.x_offset - child.x_offset
child_top  = parent.y_offset - child.y_offset

That is a useful representation, but it does not reproduce destination-only clipping in general. Roughly half the surveyed retail frames are composed. The later census of 958 GAFs and 123,294 frames found a maximum of 12 children and a zero high byte throughout.

A file you can inspect

Download the 2,762-byte example.gaf, its palette, and its offset manifest. It contains PULSE (six RLE frames) and MASK (one raw frame). The manifest records every header and pixel pointer. The file deliberately puts pixel data and frame headers before their entry headers.

The first 20 bytes are the header and two entry pointers:

00 01 01 00  02 00 00 00  00 00 00 00
EA 07 00 00  9A 0A 00 00

At 0x0812 (0x07EA + 40), the first frame reference is 8B 00 00 00 03 00 00 00: frame header at 0x008B, hold 3. That 24-byte header is:

0C 00 0C 00  06 00 06 00  09 01 00 00
00 00 00 00  14 00 00 00  00 00 00 00

Read it as 12 × 12, offset (6, 6), key 9, compression 1, no children, pixel payload at 0x0014, and zero preserved words. The displayed pulse frames are decoded from these pointers. The asset generator lives in the website source as scripts/gaf-example.py; its --check mode independently decodes the fixture and verifies the generated assets.

Loading and host boundaries

Retail reads the whole file and rewrites offsets into pointers in place, adding the loaded block address to entry, frame, pixel, and child offsets without bounds checks. Truncated or corrupt data can fault during loading. A missing or empty file is null: the effects/anims cache treats that as fatal with the path, while a feature’s filename load is silent.

Entry lookup is a linear scan; first match wins. A missing name produces a null sequence without a message. The established comparison folds only ASCII uppercase letters. Bytes 128…255 stay unchanged; this is not Unicode case folding. The helper has a locale-dependent branch, but the inspected executable’s locale selector starts at zero and has no identified writer or address-taking reference.

Metadata and safety budgets

LoadGAFMetadata retains file and entry fields, frame-reference pointers and delay words, geometry and signed origins, and the complete composite child graph, including the alternate-child selector. It allocates no decoded pixel or transparency planes. It still validates payloads.

LoadGAF uses the same checked index before decoding pixels. Both readers share signed-count handling, first-match lookup, alias handling, malformed-payload rules, aggregate reference/pixel-geometry budgets, and depth limits. A malformed payload rejects the whole bank in both readers. Repeated entry pointers share an immutable reference table and do not spend the reference budget again.

Direct-raster consumers

Some consumers read storage directly instead of using the ordinary blitter. GAFFrame.DirectRaster exposes a checked immutable view for those callers:

The visibility-mask compiler reports unsupported composites with resource provenance. The projectile model adapter omits the unsupported textured face. These are host decisions; they do not establish that retail silently skips those inputs.

Unknowns and caveats

Choose the consumer before choosing the image

The alternate-child byte is a consumer dispatch choice, not a universal property of a flattened sprite. The closed traces establish these differences:

Unknown: remaining feature-mask and structure-texture consumers need their own traces. Nanolathe’s compatibility raster retains ordinary children only, clips them to the parent canvas, and leaves alternate-only coverage transparent. That fallback does not establish retail behavior for other consumers. Fog and glyph paths now traverse their own graphs; direct masks and projectile textures use DirectRaster. Modern fog can use ordered child operations to preserve destination reads and alternate black-child tinting. See the owning research for the implementation’s remaining TODO(question).

Blue rectangles can be a keying mistake

Only 274 of 6,068 raw frames in the later 958-GAF survey contain key index 9. Three mask families account for 99.9% of those key pixels: fog.gaf, fogtiles.gaf, and vismasks.gaf. Ignoring the key paints blue (84, 84, 252) into the transparent region and fills the mask’s bounding box. This observation concerns ordinary keyed decoding; direct-storage consumers still require their own contract.

A correctly decoded panel can look like static

ARMINT.GAF entries PANELSIDE and PANELSIDE2 are 129 × 480 RLE panels, authored as dark per-pixel dither. Roughly 90% of their pixels use the darkest member of different palette ramps; all 41 observed indexes are darker than RGB (23, 19, 39). At 1:1 they are nearly black. Brightening them reveals multicolored noise.

This is established art behavior, supported by exact row/payload alignment for all 480 rows, a coherent ARM emblem in PANELSIDE2, and retail rendering’s matching index distribution. Replacing the noise with a smooth “metal panel” invents art. The engine draws minimap frames and buttons over this background; missing widgets are a separate problem.

Team colors select complete frames

Established, 03 R-RAST-01 §3: the owner’s color index selects a frame in a ten-frame LOGOS.GAF entry, independently of player slot. This is not one global palette-index substitution derived from frame 0. Frames can contain entry-specific spatial differences and even different dimensions, such as 32 × 32 versus 32 × 33.

The reference LOGOS.GAF has 18 entries: all are ten-frame team textures except the ordinary two-frame onoff01. The shaded structure branch applies its interpolated PALETTE.SHD row; the unshaded branch uses the selected frame’s indexes directly. This behavior is retail-measured, not documented by Cavedog.

Sources and evidence

This page adapts the Nanolathe GAF research at commit 11ae6ad. A plain-text snapshot preserves the complete document, citations, and publication-omission notices. The original research omits retail-derived byte examples in this edition; the worked bytes on this page come from the new authored fixture.

Established identifies observed reference-asset facts or bounded executable traces, as stated alongside each claim. Policy identifies Nanolathe host decisions. Unknown retains unresolved behavior; no illustrative image should be treated as additional retail evidence.

Continue with the palette reference, 3DO model reference, or GUI layout reference.