SAS3: sprite animations

Source

docs/formats/sas3.md

SHA-256

0d909785…aae274f4

A set of 2D animations for one sprite sheet. The sprites list rectangles (quads) of the sheet. Each animation is a timed list of frames that show a sprite, move it, play a sound or jump. Each animation has up to four directions, and a direction can reuse another's frames mirrored. It drives the units in battle (25 shared sets in battle/battle_data_release.dat #0), the actors of event scenes, the shop and class-change screens, and one picture of the Warren Report. The sheets it draws from are sprite packs or plain btx textures. Gibbed's SequenceFile reads it (and the PSP's SAS\0, version 0).

Where they are

confirmed (C# scan, all 10,016 .dat files): a SAS3 is always a pakd entry, never a whole payload or inside an ashg.

Header

16 bytes. Every offset in a SAS3 is from its start (its magic).

Animation table

At 0x10, up to sprite_table_offset: one row of four u32 per animation, one per direction, 0x10 + 16a + 4d for animation a and direction d. confirmed (C# scan): 1–118 animations per file. 14 of the 25 unit sets (#0/0–#0/11, #0/23, #0/24) have 118; the other 11 have 1–13.

Sprite table

At sprite_table_offset. confirmed (C# scan): 1–137 sprites per file.

Sprites

Each at its sprite_offset. confirmed (C# scan): the sprites follow the table back to back, in table order.

Quads

One quad (a textured rectangle) each; the draw builds one quad per record (0x1402e3340).

Animations

Each at an animation_offset. confirmed (C# scan): the animations follow the sprites in ascending order of offset. They lie back to back except for 190 gaps of one or two frames (14 or 28 bytes) in 12 of the unit sets. The gaps hold well-formed frames (types 0–3) that no animation reaches: dead data, kept for a byte-identical rebuild.

Frames

14 bytes. The arguments at 0x04–0x0D mean different things by type (next table). Unused argument bytes are 0 in every frame (C# scan, all 1,995 files).

Frame types

What 0x1402e3cb0 does with each type, so each row is likely. Counts are frames in the files (confirmed, C# scan). Gibbed's names are given where they differ from what the code does.

Padding

confirmed (C# scan, all 1,995): the SAS3 ends with the last animation's last frame. It isn't aligned, and as a pakd entry it is followed by 1–16 zero bytes, to align16(end + 1) (containers.md). Every byte before the end is the header, a table, a sprite, an animation or a dead frame in a gap.

How the game reads it

Every fact here is static analysis of the unpacked executable (Ghidra 12.1.4, the decompiled code in local/exe/decomp/), so at most likely. The functions are in the names list.

• likely: the game reads a SAS3 in place, through pointers, and never checks its magic, sizes or counts. Source: the functions below.
• likely: the battle loader stores a pointer to each entry of unit_animation_sets (#0) in a table of 25 at 0x140D69DD0. It stops after 25, so a 26th entry would never be used. A unit's animation points at one slot of that table. Source: 0x1402d4a30 → 0x1402d9ca0; 0x1402e65e0.
• likely: an event actor (scene ID 0x12000 + n) registers its sprite pack (#n/0) and plays the SAS3 beside it. Source: 0x140323530, 0x1403267c0 → 0x1403263d0; 0x140350380 finds the entry.
• likely: the shop gives 0x1403ed560 the SAS3 (entry #1) and a btx (entry #0) of a menu/sequence/ file; the btx becomes the sheet. Source: 0x14030c300 → 0x1403ed560.
• likely: to start an animation the game takes an animation index (8 bits) and a direction (0–3), and looks up the table entry at 0x10 + 16a + 4d. Source: 0x1402e2820, 0x1402d9bf0.
• likely: each tick it runs every frame whose time has come (0x1402e3b80 → 0x1402e3cb0). After the last frame the animation lasts until the counter reaches duration. An animation with no direction at all ends after 60 ticks. Source: 0x1402e3b80.
• likely: to draw, it takes the shown sprite, SAS3 + sprite_offset[index], and builds one quad per quad record (0x1402e1d00 → 0x1402e3340). Each quad's place is the animation's position plus the record's x and y, and its size is width × height, all times 1/scale. Its texture coordinates are u, v, u + width and v + height, divided by the sheet texture's width and height. flip_x and flip_y mirror the quad. Source: 0x1402e1d00, 0x1402e3340.

Replacing or editing animations

What static analysis says an edited SAS3 must keep; likely, untested in game.

• Offsets must point right. The game follows sprite_table_offset, each sprite_offset and each animation_offset (stored doubled, with the mirror bit) without checking them. Keep the animation table at 0x10, and keep sprite_table_offset = 0x10 + 16 × animations.
• Stay within the 8-bit indices. A frame can show only sprites 0–255, and a frame count over 127 reads as negative. Animation indices are 8-bit too. Keep scale nonzero.
• Keep every sprite index in range. The game doesn't check one. #0/3 already has three frames that show sprite 27 or 28 of its 27 sprites (0–26), which read past its sprite table.
• Keep quads inside the sheet. Their u, v, width and height are texels of the sheet they're drawn with, so a SAS3 and its sheet are edited together (ashg.md).
• The unit sets are shared. Every unit drawn with one of the 25 unit_animation_sets sets uses its sprites and quads, so editing a set changes every unit that uses it.

Rebuilding

• likely: the layout is fully positional: header, animation table, sprite table, sprites in table order, then animations in offset order. A rebuild that writes them back in that order, keeps the dead frames in the gaps (or the offsets they imply), and pads the entry as pakd entries are gives back the original. The C# scan accounts for every byte this way. Source: C# scan, all 1,995; not yet round-tripped by the toolchain (R30).

Leads

• How the 25 unit sets' quads map onto the unit sheets. Their rectangles reach 1,024 × 384 and 1,024 × 512, larger than the 512 × 384 and 1,024 × 256 sheets (ashg.md). The same goes for what sheet 1 selects in 11 of the sets, and which set each class uses.
• Gibbed names #0/23 dorgalua and #0/24 dorgalua_xl; the other 23 sets are unnamed.
• "Direction": the four columns of the animation table are Gibbed's directions (also his native actor_set_direction). The code takes a column 0–3 (0x1402e2820) from object byte +0x30, a menu bool (0x1403ecb00: +0xE5 != 0) or constants; nothing read shows it is a facing. A trace of UNIT +0x30 (from the facing natives) would settle the word.
• "Sprite", "sheet", "frame", "animation" are generic words the references use too; none is the game's word for these exact structures.
• How a type-9 loop (value 100 or more) loops back, and what the flag bits and the +0x46/+0x47/+0x49/+0x66 values (types 9, 10, 14) do: the animation state is read in 0x1402e29b0 and by the unit and event code.
• That type 8 plays a sound effect: it calls 0x140288830 in the sound code with the u16. Match the IDs against the sound tables (sabf.md).
• Which code plays menu/sequence/classchange.dat (0x1402bc560 loads it) and WarrenReport.dat #86.