dsts-extractor 0.8.1__py3-none-any.whl

dsts_extractor/__main__.py

@@ -0,0 +1,4 @@
+from dsts_extractor.cli import main
+
+if __name__ == "__main__":
+    main()

dsts_extractor/anim.py

@@ -0,0 +1,587 @@
+"""Reader for Digimon Story: Time Stranger .anim files.
+
+Format reverse-engineered from chr391 / chr090 samples. The layout descends
+from Media.Vision's DSCS .anim format (see Pherakki/Romsstar Blender-Tools-for-DSCS,
+FileReaders/AnimReader.py) with these DSTS-specific differences:
+
+- The 0x14 "always_16384" field (rotation precision marker in DSCS) is **0** in
+  every observed DSTS file — repurposed or removed.
+- The pointer table at 0x30..0x5C has been reshuffled and grown. DSTS adds two
+  new rel-ptrs at 0x30/0x34 (chunk-data shortcuts) and one at 0x5C (a 16-byte
+  block of mostly-zeros — purpose still TBD), while the original six DSCS
+  rel-ptrs are pushed from 0x30..0x44 down to 0x38..0x4C.
+- The kf_chunks_ptrs entries are `<HHI>` per chunk like DSCS, but with the
+  first two H's **swapped**: DSCS = (always_zero, length, abs_ptr), DSTS =
+  (length, always_zero, abs_ptr).
+- Each KeyframeChunk has a **32-byte** header (8 × u32) in place of DSCS's
+  16-byte header. The bytecount fields live in u32 slots; two of the u32
+  slots (I[2] and I[7]) hold values whose meaning is still TBD — they don't
+  affect skeletal animation when anim_scl/anim_su counts are zero.
+
+Smallest-3 quaternion encoding is the same as DSCS: 48 bits per quaternion,
+1 reserved bit + 3 × 15-bit signed-int components + 2-bit largest-index.
+"""
+
+from __future__ import annotations
+
+import math
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+
+_FILETYPE_MAGIC = b"80AE"
+_HEADER_SIZE = 0x60
+_CHUNK_HEADER_SIZE = 32
+_IDX_LIST_SECTION_START = 0x60
+
+
+@dataclass(frozen=True)
+class AnimHeader:
+    """Parsed 96-byte file header. Field offsets in comments."""
+
+    filetype: str                       # 0x00: "80AE"
+    duration_seconds: float             # 0x04
+    fps: float                          # 0x08
+    setup_and_static_data_size: int     # 0x0C — file offset where bone_mask starts
+    num_bones: int                      # 0x0E
+    total_frames: int                   # 0x10
+    num_keyframe_chunks: int            # 0x12
+    static_rot_count: int               # 0x16
+    static_loc_count: int               # 0x18
+    static_scl_count: int               # 0x1A
+    static_su_count: int                # 0x1C
+    anim_rot_count: int                 # 0x1E
+    anim_loc_count: int                 # 0x20
+    anim_scl_count: int                 # 0x22
+    anim_su_count: int                  # 0x24
+    bone_mask_bytes: int                # 0x28
+    num_uv_channels: int                # 0x2A (always 12 in chr391/chr090)
+
+
+@dataclass(frozen=True)
+class KeyframeChunk:
+    """Decoded per-chunk keyframe data.
+
+    Each track is sparse: a list of (frame_index_within_chunk, value) tuples.
+    Frame 0 of the chunk always has a value for every animated channel; later
+    frames have a value only where the keyframes_in_use bitmask is set.
+    """
+
+    cumulative_frames: int   # frame index (in the whole anim) where this chunk starts
+    frames_in_chunk: int     # = increment + 1
+    rotations: tuple[tuple[tuple[int, tuple[float, float, float, float]], ...], ...]
+    """Per-animated-bone list of (frame_in_chunk, quaternion_wxyz)."""
+    locations: tuple[tuple[tuple[int, tuple[float, float, float]], ...], ...]
+    """Per-animated-bone list of (frame_in_chunk, position)."""
+    scales: tuple[tuple[tuple[int, tuple[float, float, float]], ...], ...]
+    """Per-animated-bone list of (frame_in_chunk, scale)."""
+
+
+@dataclass(frozen=True)
+class AnimFile:
+    header: AnimHeader
+    static_rot_bones: tuple[int, ...]   # bone indices with static rotation
+    static_loc_bones: tuple[int, ...]
+    static_scl_bones: tuple[int, ...]
+    static_su_channels: tuple[int, ...]
+    anim_rot_bones: tuple[int, ...]     # bone indices that animate rotation
+    anim_loc_bones: tuple[int, ...]
+    anim_scl_bones: tuple[int, ...]
+    anim_su_channels: tuple[int, ...]
+    static_rotations: tuple[tuple[float, float, float, float], ...]  # WXYZ per static_rot bone
+    static_locations: tuple[tuple[float, float, float], ...]
+    static_scales: tuple[tuple[float, float, float], ...]
+    static_shader_uniforms: tuple[float, ...]
+    bone_mask: tuple[int, ...]          # 0 = bone has no data of any kind
+    chunks: tuple[KeyframeChunk, ...]
+
+
+# ---------------------------------------------------------------------------
+# Smallest-3 quaternion decode (DSCS-compatible)
+
+
+def _decode_quaternion(raw: bytes) -> tuple[float, float, float, float]:
+    """Decode a 6-byte smallest-3 quaternion into (w, x, y, z).
+
+    Bit layout (MSB-first within each byte):
+        bit 0      : reserved (always 0)
+        bits 1..15 : component 0 → X (or W if largest_index says so)
+        bits 16..30: component 1 → Y
+        bits 31..45: component 2 → Z
+        bits 46..47: largest_index (0..3), index in XYZW where the omitted
+                     (largest-magnitude) component is reinserted.
+
+    Components are scaled by 1/sqrt(2). The omitted component is recovered
+    via |q| = 1.
+    """
+    if len(raw) != 6:
+        raise ValueError(f"quaternion blob must be 6 bytes, got {len(raw)}")
+    bits = 0
+    for b in raw:
+        bits = (bits << 8) | b
+    # `bits` is now a 48-bit integer; bit 47 (LSB after the OR-shift) maps to
+    # MSB position 0 of the input. Iterating j=2,1,0 reads comp0 first (= the
+    # 15 bits just below the reserved top bit), comp1 next, comp2 last.
+    largest_index = bits & 0b11
+    comps: list[float] = []
+    for j in (2, 1, 0):
+        v = (bits >> (2 + 15 * j)) & 0x7FFF
+        comps.append((v - 16383) / 16384.0 / math.sqrt(2.0))
+    # comps == [comp0, comp1, comp2] → these map to (X, Y, Z) before the
+    # omitted component is reinserted. Do NOT reverse — that swaps X with Z.
+    sum_sq = sum(c * c for c in comps)
+    largest = math.sqrt(max(0.0, 1.0 - sum_sq))
+    xyzw = comps[:]
+    xyzw.insert(largest_index, largest)
+    x, y, z, w = xyzw
+    return (w, x, y, z)
+
+
+# ---------------------------------------------------------------------------
+# Header + idx-list parsing
+
+
+def _parse_header(blob: bytes) -> AnimHeader:
+    if len(blob) < _HEADER_SIZE:
+        raise ValueError(f"anim too small for header: {len(blob)} < {_HEADER_SIZE}")
+    filetype = blob[0:4]
+    if filetype != _FILETYPE_MAGIC:
+        raise ValueError(f"unexpected anim magic: {filetype!r}")
+    duration, fps = struct.unpack_from("<ff", blob, 0x04)
+    (
+        setup_data_size,
+        num_bones,
+        total_frames,
+        num_kf_chunks,
+        always_zero,
+    ) = struct.unpack_from("<HHHHH", blob, 0x0C)
+    if always_zero != 0:
+        # DSCS expects 16384 here; DSTS samples we've seen all have 0.
+        raise ValueError(
+            f"unexpected value at 0x14: {always_zero} (expected 0 for DSTS)"
+        )
+    (
+        s_rot,
+        s_loc,
+        s_scl,
+        s_su,
+        a_rot,
+        a_loc,
+        a_scl,
+        a_su,
+    ) = struct.unpack_from("<HHHHHHHH", blob, 0x16)
+    # The u16 at 0x26 is a parallel shader-uniform-anim count that we don't
+    # decode. It equals `anim_su_count` in effect/camera anims and ranges
+    # 1..15 on some chr anims whose `anim_su_count` is 0. Verified empirically:
+    # it does not shift the offsets of any section the parser walks (every
+    # decoded quaternion stays unit). Read it for completeness, then drop.
+    _su_count_2, bone_mask_bytes, num_uv = struct.unpack_from("<HHH", blob, 0x26)
+    return AnimHeader(
+        filetype=filetype.decode("ascii"),
+        duration_seconds=duration,
+        fps=fps,
+        setup_and_static_data_size=setup_data_size,
+        num_bones=num_bones,
+        total_frames=total_frames,
+        num_keyframe_chunks=num_kf_chunks,
+        static_rot_count=s_rot,
+        static_loc_count=s_loc,
+        static_scl_count=s_scl,
+        static_su_count=s_su,
+        anim_rot_count=a_rot,
+        anim_loc_count=a_loc,
+        anim_scl_count=a_scl,
+        anim_su_count=a_su,
+        bone_mask_bytes=bone_mask_bytes,
+        num_uv_channels=num_uv,
+    )
+
+
+def _read_rel_ptr(blob: bytes, field_offset: int) -> int:
+    """Read a u32 rel-pointer at `field_offset` and resolve to an absolute file offset.
+
+    Returns 0 (sentinel for "no data section") when the rel value is 0.
+    """
+    val = struct.unpack_from("<I", blob, field_offset)[0]
+    if val == 0:
+        return 0
+    return field_offset + val
+
+
+def _align(n: int, boundary: int) -> int:
+    return (n + boundary - 1) & ~(boundary - 1)
+
+
+def _read_idx_list(
+    blob: bytes,
+    cursor: int,
+    count: int,
+    boundary: int,
+    sentinel: int,
+) -> tuple[tuple[int, ...], int]:
+    """Read `count` u16 indices, then skip sentinel-padding to `boundary` alignment.
+
+    Returns (idxs, new_cursor).
+    """
+    if count == 0:
+        return (), cursor
+    idxs = struct.unpack_from(f"<{count}H", blob, cursor)
+    cursor += count * 2
+    end_aligned = _align(count * 2, boundary)
+    pad_bytes = end_aligned - count * 2
+    if pad_bytes:
+        pad_values = struct.unpack_from(f"<{pad_bytes // 2}H", blob, cursor)
+        if any(v != sentinel for v in pad_values):
+            raise ValueError(
+                f"idx-list padding sentinel mismatch at 0x{cursor:x}: "
+                f"got {pad_values!r}, expected {sentinel}"
+            )
+        cursor += pad_bytes
+    return idxs, cursor
+
+
+# ---------------------------------------------------------------------------
+# Keyframe-chunk parsing
+
+
+def _read_keyframes_in_use(
+    blob: bytes,
+    cursor: int,
+    total_anim_channels: int,
+    increment_frames: int,
+) -> tuple[list[list[bool]], int]:
+    """Decode the keyframes-in-use bitmask.
+
+    Layout: total_anim_channels × increment_frames bits, channel-major,
+    MSB-first within each byte. Returns one list-of-bools per animated channel,
+    each of length `increment_frames`.
+
+    Pad bytes (before and after the mask) live in the chunk header's
+    pre_mask_pad / post_mask_pad fields and are advanced by the caller.
+    """
+    total_bits = total_anim_channels * increment_frames
+    if total_bits == 0:
+        return [[] for _ in range(total_anim_channels)], cursor
+    nbytes = (total_bits + 7) // 8
+    raw = blob[cursor : cursor + nbytes]
+    cursor += nbytes
+    # Unpack bits MSB-first
+    flat = []
+    for byte in raw:
+        for bit in range(8):
+            flat.append(bool(byte & (0x80 >> bit)))
+    per_channel: list[list[bool]] = []
+    for ch in range(total_anim_channels):
+        start = ch * increment_frames
+        per_channel.append(flat[start : start + increment_frames])
+    return per_channel, cursor
+
+
+def _read_chunk(
+    blob: bytes,
+    chunk_start: int,
+    anim_rot_count: int,
+    anim_loc_count: int,
+    anim_scl_count: int,
+    anim_su_count: int,
+    cumulative_frames: int,
+    frames_in_chunk: int,
+) -> KeyframeChunk:
+    """Read one keyframe chunk starting at `chunk_start`.
+
+    DSTS chunk layout:
+        [0..32)   chunk header (8 × u32):
+                    I[0] = frame_0_rot_bytecount (= anim_rot_count × 6)
+                    I[1] = frame_0_loc_bytecount (= anim_loc_count × 12)
+                    I[2] = pad bytes between frame_0 sections and the mask
+                    I[3] = frame_0_su_bytecount  (= anim_su_count × 4)
+                    I[4] = keyframed_rot_bytecount
+                    I[5] = keyframed_loc_bytecount
+                    I[6] = pad bytes between the mask and keyframed_rot
+                    I[7] = pad bytes after the keyframed sections (chunk-final pad)
+        [32..)    frame_0_rot   (anim_rot_count × 6, smallest-3 quat)
+                  frame_0_loc   (anim_loc_count × 12, fff)
+                  frame_0_scl   (anim_scl_count × 12, fff)
+                  frame_0_su    (anim_su_count  × 4,  f)
+                  pre_mask_pad  (I[2] bytes — between frame_0 sections and the mask)
+                  mask          (ceil((total_anim_channels) × (frames_in_chunk-1) / 8) bytes,
+                                 channel-major, MSB-first within each byte)
+                  keyframed_rot
+                  keyframed_loc
+                  keyframed_scl
+                  keyframed_su
+                  end_pad       (I[6] + I[7] bytes, after the keyframed sections)
+
+    DSCS used implicit alignment for the equivalent pads; DSTS stores the
+    pad-byte counts explicitly. I[6] and I[7] are both trailing-pad fields:
+    I[7] alone matched chunk size when I[6] happened to be zero (which it
+    is for most anims), but anims like chr391_fe04 set I[6]=1 and require
+    BOTH to land at the right total. Treating I[6] as a pad between mask
+    and kf_rot (the obvious DSCS-style guess) shifts every keyframed quat
+    by 1 byte and silently corrupts the smallest-3 decode.
+    """
+    hdr = struct.unpack_from("<8I", blob, chunk_start)
+    f0_rot_bc = hdr[0]
+    f0_loc_bc = hdr[1]
+    pre_mask_pad = hdr[2]
+    f0_su_bc = hdr[3]
+    kf_rot_bc = hdr[4]
+    kf_loc_bc = hdr[5]
+    end_pad_a = hdr[6]
+    end_pad_b = hdr[7]
+
+    expected_f0_rot = anim_rot_count * 6
+    expected_f0_loc = anim_loc_count * 12
+    expected_f0_su = anim_su_count * 4
+    if f0_rot_bc != expected_f0_rot:
+        raise ValueError(
+            f"chunk@0x{chunk_start:x}: frame_0_rot_bytecount={f0_rot_bc} != expected {expected_f0_rot}"
+        )
+    if f0_loc_bc != expected_f0_loc:
+        raise ValueError(
+            f"chunk@0x{chunk_start:x}: frame_0_loc_bytecount={f0_loc_bc} != expected {expected_f0_loc}"
+        )
+    if f0_su_bc != expected_f0_su:
+        raise ValueError(
+            f"chunk@0x{chunk_start:x}: frame_0_su_bytecount={f0_su_bc} != expected {expected_f0_su}"
+        )
+
+    cursor = chunk_start + _CHUNK_HEADER_SIZE
+
+    # frame_0_rot
+    frame_0_rotations: list[tuple[float, float, float, float]] = []
+    for i in range(anim_rot_count):
+        q = _decode_quaternion(bytes(blob[cursor + i * 6 : cursor + (i + 1) * 6]))
+        frame_0_rotations.append(q)
+    cursor += f0_rot_bc
+
+    # frame_0_loc
+    frame_0_locations: list[tuple[float, float, float]] = []
+    for i in range(anim_loc_count):
+        frame_0_locations.append(
+            struct.unpack_from("<fff", blob, cursor + i * 12)  # type: ignore[arg-type]
+        )
+    cursor += f0_loc_bc
+
+    # No frame_0_scl block in the chunk: the chunk header declares only
+    # f0_rot_bc, f0_loc_bc, pre_mask_pad, f0_su_bc (no f0_scl_bc), and a
+    # mask-bytecount audit confirms the mask sits immediately after f0_su.
+    # Default animated-scl tracks to identity at frame 0; subsequent keyframes
+    # in the mask provide the actual per-frame values.
+    frame_0_scales: list[tuple[float, float, float]] = [
+        (1.0, 1.0, 1.0) for _ in range(anim_scl_count)
+    ]
+
+    # frame_0_su
+    frame_0_su: list[float] = []
+    for i in range(anim_su_count):
+        frame_0_su.append(struct.unpack_from("<f", blob, cursor + i * 4)[0])
+    cursor += f0_su_bc
+
+    # pre-mask explicit pad
+    cursor += pre_mask_pad
+
+    # keyframes_in_use mask: total_anim_channels × increment_frames bits,
+    # channel-major, MSB-first within each byte.
+    increment_frames = max(0, frames_in_chunk - 1)
+    total_anim_channels = (
+        anim_rot_count + anim_loc_count + anim_scl_count + anim_su_count
+    )
+    per_channel_mask, cursor = _read_keyframes_in_use(
+        blob, cursor, total_anim_channels, increment_frames
+    )
+    # No explicit pad between mask and keyframed_rot — kf_rot starts immediately
+    # after the mask. The remaining `end_pad_a` (= I[6]) and `end_pad_b` (= I[7])
+    # bytes live at the END of the chunk, after kf_su.
+    _ = (end_pad_a, end_pad_b)  # consumed by caller for chunk-end accounting
+
+    # keyframed_rot — only values for set bits in the rot portion of the mask
+    rot_mask = per_channel_mask[0:anim_rot_count]
+    loc_mask = per_channel_mask[anim_rot_count : anim_rot_count + anim_loc_count]
+    scl_mask = per_channel_mask[
+        anim_rot_count + anim_loc_count : anim_rot_count + anim_loc_count + anim_scl_count
+    ]
+    # su_mask kept unused at present (no anim_su in observed chr files)
+    _ = per_channel_mask[anim_rot_count + anim_loc_count + anim_scl_count :]
+
+    expected_kf_rot = sum(sum(m) for m in rot_mask) * 6
+    expected_kf_loc = sum(sum(m) for m in loc_mask) * 12
+    if kf_rot_bc != expected_kf_rot:
+        raise ValueError(
+            f"chunk@0x{chunk_start:x}: keyframed_rot_bytecount={kf_rot_bc} != "
+            f"expected {expected_kf_rot} from mask"
+        )
+    if kf_loc_bc != expected_kf_loc:
+        raise ValueError(
+            f"chunk@0x{chunk_start:x}: keyframed_loc_bytecount={kf_loc_bc} != "
+            f"expected {expected_kf_loc} from mask"
+        )
+    # DSCS stored keyframed_scl_bytecount at hdr[6]; in DSTS that slot was
+    # repurposed as post_mask_pad. No samples observed for anim_scl != 0 yet.
+
+    # Assemble per-bone sparse tracks: (frame_in_chunk, value) pairs.
+    # Frame 0 always has a sample; subsequent frames i (1..increment_frames)
+    # have a sample iff mask[i-1] is set.
+    rotations: list[tuple[tuple[int, tuple[float, float, float, float]], ...]] = []
+    rot_cursor = cursor
+    for ch_idx in range(anim_rot_count):
+        track = [(0, frame_0_rotations[ch_idx])]
+        for frame_minus_1, present in enumerate(rot_mask[ch_idx]):
+            if present:
+                q = _decode_quaternion(bytes(blob[rot_cursor : rot_cursor + 6]))
+                rot_cursor += 6
+                track.append((frame_minus_1 + 1, q))
+        rotations.append(tuple(track))
+    cursor += kf_rot_bc
+
+    locations: list[tuple[tuple[int, tuple[float, float, float]], ...]] = []
+    loc_cursor = cursor
+    for ch_idx in range(anim_loc_count):
+        track = [(0, frame_0_locations[ch_idx])]
+        for frame_minus_1, present in enumerate(loc_mask[ch_idx]):
+            if present:
+                v: tuple[float, float, float] = struct.unpack_from(  # type: ignore[assignment]
+                    "<fff", blob, loc_cursor
+                )
+                loc_cursor += 12
+                track.append((frame_minus_1 + 1, v))
+        locations.append(tuple(track))
+    cursor += kf_loc_bc
+
+    scales: list[tuple[tuple[int, tuple[float, float, float]], ...]] = []
+    scl_cursor = cursor
+    for ch_idx in range(anim_scl_count):
+        track = [(0, frame_0_scales[ch_idx])]
+        for frame_minus_1, present in enumerate(scl_mask[ch_idx]):
+            if present:
+                v2: tuple[float, float, float] = struct.unpack_from(  # type: ignore[assignment]
+                    "<fff", blob, scl_cursor
+                )
+                scl_cursor += 12
+                track.append((frame_minus_1 + 1, v2))
+        scales.append(tuple(track))
+
+    return KeyframeChunk(
+        cumulative_frames=cumulative_frames,
+        frames_in_chunk=frames_in_chunk,
+        rotations=tuple(rotations),
+        locations=tuple(locations),
+        scales=tuple(scales),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Top-level parse
+
+
+def parse_anim(blob: bytes | bytearray | memoryview) -> AnimFile:
+    blob = bytes(blob)
+    header = _parse_header(blob)
+
+    # Bone idx lists at 0x60. DSCS padding boundaries: rotations to 16, others to 8.
+    cursor = _IDX_LIST_SECTION_START
+    sentinel = header.num_bones  # padded with num_bones value, matching DSCS convention
+    static_rot_idxs, cursor = _read_idx_list(blob, cursor, header.static_rot_count, 16, sentinel)
+    static_loc_idxs, cursor = _read_idx_list(blob, cursor, header.static_loc_count, 8, sentinel)
+    static_scl_idxs, cursor = _read_idx_list(blob, cursor, header.static_scl_count, 8, sentinel)
+    su_sentinel = header.num_uv_channels
+    static_su_idxs, cursor = _read_idx_list(blob, cursor, header.static_su_count, 8, su_sentinel)
+    anim_rot_idxs, cursor = _read_idx_list(blob, cursor, header.anim_rot_count, 8, sentinel)
+    anim_loc_idxs, cursor = _read_idx_list(blob, cursor, header.anim_loc_count, 8, sentinel)
+    anim_scl_idxs, cursor = _read_idx_list(blob, cursor, header.anim_scl_count, 8, sentinel)
+    anim_su_idxs, cursor = _read_idx_list(blob, cursor, header.anim_su_count, 8, su_sentinel)
+
+    # Rel ptrs to static-pose sections (DSTS reshuffled offsets).
+    abs_rot_ptr = _read_rel_ptr(blob, 0x40)
+    abs_loc_ptr = _read_rel_ptr(blob, 0x44)
+    abs_scl_ptr = _read_rel_ptr(blob, 0x48)
+    abs_su_ptr = _read_rel_ptr(blob, 0x4C)
+
+    # Static rotations
+    static_rotations: list[tuple[float, float, float, float]] = []
+    for i in range(header.static_rot_count):
+        raw = blob[abs_rot_ptr + i * 6 : abs_rot_ptr + (i + 1) * 6]
+        static_rotations.append(_decode_quaternion(bytes(raw)))
+
+    # Static locations
+    static_locations: list[tuple[float, float, float]] = []
+    for i in range(header.static_loc_count):
+        static_locations.append(
+            struct.unpack_from("<fff", blob, abs_loc_ptr + i * 12)  # type: ignore[arg-type]
+        )
+
+    # Static scales
+    static_scales: list[tuple[float, float, float]] = []
+    for i in range(header.static_scl_count):
+        static_scales.append(
+            struct.unpack_from("<fff", blob, abs_scl_ptr + i * 12)  # type: ignore[arg-type]
+        )
+
+    # Static shader-uniform values
+    static_shader_uniforms: list[float] = []
+    for i in range(header.static_su_count):
+        static_shader_uniforms.append(
+            struct.unpack_from("<f", blob, abs_su_ptr + i * 4)[0]
+        )
+
+    # Bone mask at setup_and_static_data_size (per-bone byte, padded).
+    mask_start = header.setup_and_static_data_size
+    bone_mask: tuple[int, ...] = ()
+    if header.bone_mask_bytes:
+        raw_mask = blob[mask_start : mask_start + header.num_bones]
+        bone_mask = tuple(raw_mask)
+
+    # Keyframe chunks
+    chunks: list[KeyframeChunk] = []
+    if header.num_keyframe_chunks > 0:
+        abs_kf_ptrs = _read_rel_ptr(blob, 0x38)
+        abs_kf_counts = _read_rel_ptr(blob, 0x3C)
+        if abs_kf_ptrs == 0 or abs_kf_counts == 0:
+            raise ValueError("num_keyframe_chunks > 0 but kf_ptrs/kf_counts rel-ptrs are 0")
+        for i in range(header.num_keyframe_chunks):
+            # DSTS kf_ptrs entry: <HHI> = (length, always_zero, abs_ptr).
+            # length is "bytes from chunk start to end-of-file" (not the chunk's actual size).
+            length, always_zero, abs_ptr = struct.unpack_from(
+                "<HHI", blob, abs_kf_ptrs + i * 8
+            )
+            if always_zero != 0:
+                raise ValueError(
+                    f"chunk[{i}] expected always_zero=0, got {always_zero}"
+                )
+            cumulative_frames, frames_minus_1 = struct.unpack_from(
+                "<HH", blob, abs_kf_counts + i * 4
+            )
+            frames_in_chunk = frames_minus_1 + 1
+            chunk = _read_chunk(
+                blob,
+                abs_ptr,
+                header.anim_rot_count,
+                header.anim_loc_count,
+                header.anim_scl_count,
+                header.anim_su_count,
+                cumulative_frames,
+                frames_in_chunk,
+            )
+            chunks.append(chunk)
+
+    return AnimFile(
+        header=header,
+        static_rot_bones=static_rot_idxs,
+        static_loc_bones=static_loc_idxs,
+        static_scl_bones=static_scl_idxs,
+        static_su_channels=static_su_idxs,
+        anim_rot_bones=anim_rot_idxs,
+        anim_loc_bones=anim_loc_idxs,
+        anim_scl_bones=anim_scl_idxs,
+        anim_su_channels=anim_su_idxs,
+        static_rotations=tuple(static_rotations),
+        static_locations=tuple(static_locations),
+        static_scales=tuple(static_scales),
+        static_shader_uniforms=tuple(static_shader_uniforms),
+        bone_mask=bone_mask,
+        chunks=tuple(chunks),
+    )
+
+
+def read_anim(path: Path) -> AnimFile:
+    return parse_anim(path.read_bytes())