feat: GraphicsArchive.animation draws sequence views as the game does #468

Merged
jqueuniet merged 3 commits from feat/animation into main 2026-11-01 07:52:28 +01:00
Owner

Closes #466

GraphicsArchive.animation(cls1, cls2, sequence, view, options?) (wasm, FFI, Python) draws one view of a sequences() entry as one PNG, an APNG when it has several frames. icon() frames now always fill the canvas.

Placement (creatures)

Per SKWINSPX DM2_QUERY_CREATURE_PICST / DM2_DRAW_PICST, each tick is drawn as the game draws a creature one tile ahead, centre cell:

s       = (0x0f, type, dtRaw7, 0xfe)[4 × byte5 + view]   64 = full size
size    = (n × s + s / 2) >> 6                            CALC_STRETCHED_SIZE
offset  = (0x0f, type, 0x0c, 0xfe) + image offset + byte6 shift,
          scaled by s, X negated when mirrored
anchor  = blit rect 5075 + rotate5x5(byte4, view) + offset

All creature rects (5000–5099, DOS EN and Mac US) have mode 7: bottom-centre, so frames share a ground point; walking creatures move across the tile and scale per step.

Changes

  • apng() takes placed frames on a canvas bounding them all; fixes the invalid first fcTL (#466 item 1).
  • dtRectangle (1, 0, 4, 0) decoded as the engine's blit rect table (documented).
  • sequences() steps gain scale (byte 5) and shift (byte 6); the view logic moves to Archive::creature_ticks, creature_view_image, ornament_view, shared by sequences() and animation().
  • ConvertError::NoSequenceView for a missing sequence or view.

Limits

  • The stretch formula is the engine's, including its +1 when enlarging; sampling follows stretch256.
  • No viewport clipping: canvases cover the whole walk (268 px wide for creature 0's side view).
  • Ornaments are drawn at their top-left; their engine placement isn't traced.
  • Amiga unverified; not checked in-game. Frame sheets of a few DOS views were checked visually.

Tests

  • graphics_animation: every fcTL matches IHDR for icon() and animation(); creature 0 command 3 front pinned at 153×119; ornament 0x17 9 frames; bad sequence / view / class refused; unknown option refused.
  • Unit test for rotation, stretch rounding, mode 7 origin and sampling.
  • Python: animation returns an APNG.
  • All 2328 DOS creature views render without error (probe, not committed).

https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7

Closes #466 `GraphicsArchive.animation(cls1, cls2, sequence, view, options?)` (wasm, FFI, Python) draws one view of a `sequences()` entry as one PNG, an APNG when it has several frames. `icon()` frames now always fill the canvas. ## Placement (creatures) Per SKWINSPX `DM2_QUERY_CREATURE_PICST` / `DM2_DRAW_PICST`, each tick is drawn as the game draws a creature one tile ahead, centre cell: ```text s = (0x0f, type, dtRaw7, 0xfe)[4 × byte5 + view] 64 = full size size = (n × s + s / 2) >> 6 CALC_STRETCHED_SIZE offset = (0x0f, type, 0x0c, 0xfe) + image offset + byte6 shift, scaled by s, X negated when mirrored anchor = blit rect 5075 + rotate5x5(byte4, view) + offset ``` All creature rects (5000–5099, DOS EN and Mac US) have mode 7: bottom-centre, so frames share a ground point; walking creatures move across the tile and scale per step. ## Changes - `apng()` takes placed frames on a canvas bounding them all; fixes the invalid first `fcTL` (#466 item 1). - `dtRectangle` `(1, 0, 4, 0)` decoded as the engine's blit rect table (documented). - `sequences()` steps gain `scale` (byte 5) and `shift` (byte 6); the view logic moves to `Archive::creature_ticks`, `creature_view_image`, `ornament_view`, shared by `sequences()` and `animation()`. - `ConvertError::NoSequenceView` for a missing sequence or view. ## Limits - The stretch formula is the engine's, including its +1 when enlarging; sampling follows `stretch256`. - No viewport clipping: canvases cover the whole walk (268 px wide for creature 0's side view). - Ornaments are drawn at their top-left; their engine placement isn't traced. - Amiga unverified; not checked in-game. Frame sheets of a few DOS views were checked visually. ## Tests - `graphics_animation`: every `fcTL` matches IHDR for `icon()` and `animation()`; creature 0 command 3 front pinned at 153×119; ornament 0x17 9 frames; bad sequence / view / class refused; unknown option refused. - Unit test for rotation, stretch rounding, mode 7 origin and sampling. - Python: `animation` returns an APNG. - All 2328 DOS creature views render without error (probe, not committed). https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7
The first fcTL must match IHDR; icon() sized it to frame 0, so frames
of differing sizes gave an invalid APNG. Frames are now placed on a
canvas bounding them all.

Refs #466

Claude-Session: https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7
decode_animation_png / GraphicsArchive::animation place each
creature step as DM2_QUERY_CREATURE_PICST draws it one tile ahead:
per-step scale and shift, image offset, mirror, and the blit rect of
its grid position, bottom-centred. Steps expose bytes 5 and 6 (scale,
shift); the dtRectangle record is decoded as the engine's blit rects.

Refs #466

Claude-Session: https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7
feat(bindings): GraphicsArchive.animation
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 1m3s
CI / python bindings (3.11) (pull_request) Successful in 28s
CI / audit (push) Successful in 19s
CI / msrv (1.90) (push) Successful in 29s
CI / stable (push) Successful in 1m0s
CI / python bindings (3.11) (push) Successful in 28s
a1cbc3fa35
Closes #466

Claude-Session: https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7
jqueuniet deleted branch feat/animation 2026-11-01 07:52:28 +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!468
No description provided.