feat: GraphicsArchive.sequences for creature and ornament animations #465

Merged
jqueuniet merged 2 commits from feat/sequences into main 2026-10-31 22:20:55 +01:00
Owner

GraphicsArchive.sequences(cls1, cls2) lists the animations of a creature (0x0f) or a wall / floor ornament (0x09 / 0x0a) as JSON. Each has frame_ms (one tick, 134) and views: the images one per tick, ready for icon().

Format (per SKWINSPX v5/, checked on DOS EN data)

  • (0x0f, type, dtRaw8, 0xfb): command → offset; 0xffff = any other command.
  • 0xfc / 0xfd: parallel per-step arrays. 0xfc holds sound, next jump, chance, action bit and ticks (+ random extra). 0xfd holds an image per direction, the 5×5 position and 2-bit mirror flags.
  • Ornaments: period word or 0x0d digit text, one step per tick; step s draws cls4 block 4s.. (walls) / 10s.. (floors).

Documented in docs/formats/graphics-dat.md § Animation sequences.

Choices (from the discussion)

  • Timing: uniform frameMs. Each step repeats once per base tick, so icon() at 134 ms plays it at the engine's base pace. Random extra ticks and step chances are exposed per step but not in frames, which follow every next with every chance succeeding. Static creatures cycle every record one tick each, as the engine does.
  • V5 only: Japanese and Sega CD creatures return [], as their command tables live in the executable.
  • Ornaments list every view whose images all exist.

Deviations / limits

  • icon() does not flip; mirror per frame tells the caller.
  • Creature type 78 names images its archive lacks (no views); floor ornament 0x18 has no image block for its step 2 (no views).
  • DOS and Mac US data differ (e.g. Mac US type 19 command 0x13 uses one image for all directions).
  • Amiga ships the records too but is unverified: 28 of 647 sequences have no front image, and its mirror bits look different.
  • 0xfc byte 0 bit 7, byte 2 bit 6, byte 3 bit 1 and 0xfd bytes 5–6 remain unidentified.
  • Not checked in-game.

Tests: every DOS and Mac US creature (76) and animated ornament (48); creature 0's walk renders as a 12-frame APNG; Mac JP returns []; Python binding.

Closes #462

https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7

`GraphicsArchive.sequences(cls1, cls2)` lists the animations of a creature (`0x0f`) or a wall / floor ornament (`0x09` / `0x0a`) as JSON. Each has `frame_ms` (one tick, 134) and `views`: the images one per tick, ready for `icon()`. ## Format (per SKWINSPX `v5/`, checked on DOS EN data) - `(0x0f, type, dtRaw8, 0xfb)`: command → offset; `0xffff` = any other command. - `0xfc` / `0xfd`: parallel per-step arrays. `0xfc` holds sound, `next` jump, chance, action bit and ticks (+ random extra). `0xfd` holds an image per direction, the 5×5 position and 2-bit mirror flags. - Ornaments: period word or `0x0d` digit text, one step per tick; step `s` draws `cls4` block `4s..` (walls) / `10s..` (floors). Documented in `docs/formats/graphics-dat.md` § Animation sequences. ## Choices (from the discussion) - Timing: uniform `frameMs`. Each step repeats once per base tick, so `icon()` at 134 ms plays it at the engine's base pace. Random extra ticks and step chances are exposed per step but not in `frames`, which follow every `next` with every chance succeeding. Static creatures cycle every record one tick each, as the engine does. - V5 only: Japanese and Sega CD creatures return `[]`, as their command tables live in the executable. - Ornaments list every view whose images all exist. ## Deviations / limits - `icon()` does not flip; `mirror` per frame tells the caller. - Creature type 78 names images its archive lacks (no views); floor ornament `0x18` has no image block for its step 2 (no views). - DOS and Mac US data differ (e.g. Mac US type 19 command `0x13` uses one image for all directions). - Amiga ships the records too but is unverified: 28 of 647 sequences have no front image, and its mirror bits look different. - `0xfc` byte 0 bit 7, byte 2 bit 6, byte 3 bit 1 and `0xfd` bytes 5–6 remain unidentified. - Not checked in-game. Tests: every DOS and Mac US creature (76) and animated ornament (48); creature 0's walk renders as a 12-frame APNG; Mac JP returns `[]`; Python binding. Closes #462 https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7
Archive::creature_sequences reads the V5 engine's per-command records
(0x0f, type, dtRaw8/dtRaw7, 0xfb/0xfc/0xfd): each step's images and
mirrors per direction, ticks, random extra ticks, chance, jump, sound,
action and grid position. Archive::ornament_steps gives a wall or floor
ornament's steps from its period word or 0x0d text.

Claude-Session: https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7
feat(bindings): GraphicsArchive.sequences
All checks were successful
CI / msrv (1.90) (pull_request) Successful in 29s
CI / audit (pull_request) Successful in 20s
CI / stable (pull_request) Successful in 57s
CI / python bindings (3.11) (pull_request) Successful in 26s
CI / msrv (1.90) (push) Successful in 28s
CI / audit (push) Successful in 19s
CI / stable (push) Successful in 57s
CI / python bindings (3.11) (push) Successful in 27s
340262c471
A creature's or ornament's animations as JSON, their views one image
per tick ready for icon().

Closes #462

Claude-Session: https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7
jqueuniet deleted branch feat/sequences 2026-10-31 22:20:55 +01:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jqueuniet/dm2-tools!465
No description provided.