S3-004: Complete original graphics and animation importing

Parent and ownership

Parent epic: https://github.com/stacksjs/the-settlers-iii-remake/issues/5 Source owner: stacksjs/the-settlers-iii-remake. Master roadmap: https://github.com/stacksjs/the-settlers-iii-remake/issues/4.

Problem and observable result

Import all action and direction sequences with anchors. Preserve tint, shadows, and construction stages. Reject malformed and oversized data.

The current application is a browser prototype. Passing the Riverlands campaign does not establish original-game or native parity. This issue is complete only when its stated behavior has retained evidence.

Evidence and interfaces

Verified source observations and decoded content enter immutable, versioned catalogs. Distinguish original facts, reference-remake behavior, and engineering decisions.

• https://github.com/JakeSteam/settlers/blob/8426388935b436e65b0697ac401c4247ab097364/en/changes/changes.htm
• https://github.com/paulwedeck/settlers-remake/tree/6ad8c4230a4aa4cd21840f8cb59a38344e41c3e0

Pin the inspected revisions and fixture hashes in the implementation evidence. Original-game observations govern rules and timing. JSettlers is implementation evidence, not an authoritative balance specification. Unknown values remain explicitly unverified.

Acceptance criteria

• Import all action and direction sequences with anchors.
• Preserve tint, shadows, and construction stages.
• Reject malformed and oversized data.
• The visible result agrees with the underlying simulation or platform state, including failure paths.
• Tests exercise the maintained public interface and retain reproducible fixtures or execution receipts.

Test matrix

• Decode representative worker, ship, siege, and building fixtures.
• Reject truncated frame tables.
• Exercise invalid input, cancellation or interruption, and repeated execution where this interface permits them.
• Verify determinism/conservation for simulation changes and resource ownership/disposal for platform changes.
• Run owning-repository lint, relevant type checks and tests. Capture actual native output for native capability claims.

Scope constraints

Implement this behavior as a complete verifiable slice. Do not silently expand into adjacent tickets or substitute simplified gameplay. Keep the shared TypeScript simulation, shared stx signals, and ts-css conventions. Native gameplay and HUD must not depend on a WebView. HomeOS reuse must not introduce a kernel dependency into the game. Existing unrelated edits and authored guidance must be preserved.

Blocked by

• https://github.com/stacksjs/the-settlers-iii-remake/issues/19

Upstream release and adoption

Application behavior belongs here. If a reproduction identifies a framework defect, repair and release its owning source first, update Stacks where affected, then install the verified packages here.

No node_modules edits, copied runtimes, generated-source string patches, fabricated globals, successful no-op implementations, or skipped release gates. Push tested conventional commits as Chris to the owning origin/main without coauthor trailers or force pushes.

Completion evidence

• Implementation commits and relevant upstream issue links.
• Exact checks and results, fixture hashes, and screenshots/native execution evidence where applicable.
• Published package versions, downstream lockfile identity, and release receipts when affected.
• Remaining limitations stated explicitly. Partial work does not close this issue.

The original survey-sign images are available in the demo. The pinned MapObjectDrawer uses objects file 1, sequences 94 through 99 for coal, gems, gold, iron, sulfur and empty ground. All twelve frames decode with their original 14x24 dimensions and (-8,-21) anchors.

Integration is tracked in #207. Frame selection follows the reference's resource scaling; it will not change mining quantities or be presented as an observation of original Gold behavior. Original rasters remain local.

The tutorial map's decoded win conditions are all disabled, and it has no quest text or tip. Getting its economy working does not establish complete tutorial objectives.

Survey signs now use twelve original demo frames for coal, gems, gold, iron, sulfur and empty ground, with their original pixels and anchors. The browser pairs atlas coordinates with a bitmap named by its bytes, including after a cached-page reload. #207 has the implementation and validation; CI passes.

This completes the survey-symbol slice. Civilian profession animations, original fonts, remaining media and full scene comparison are still open.

The Roman geologist import is complete in #209: 119 movement and survey frames retain their original anchors and aligned torso layers. #210 also corrected the generic DAT table alignment, repairing existing specialist and soldier clothing. Independent decoded-frame comparisons and the full CI checks pass.

This advances the importer without completing its full scope. Player colors and original map-slot identity are tracked in #211. Other professions, remaining actions, shadows and the rest of the original content still need coverage.

The RGB expansion correction in #213 and player-color layers in #211 are complete. Current imports retain 3,647 untinted movable bodies and 3,647 grayscale torso masks with independently checked original pixels and anchors. Clothing, borders and minimap identity colors agree, including original slots retained after civilization filtering. Saves and replay checksums stay compatible.

The next graphics gap is original shadows: the browser still uses a generic oval. The demo has separate shadow tables, and AdvancedDatFileReader applies shadow-specific alignment and a file-11 specialist shift. ShadowTranslator also supplies its own opacity and reads no per-pixel body-color bytes. Reusing the torso offset or body decoder would give incorrect results.

Full shadows, additional profession/faction action sequences and broader #20 acceptance remain unfinished. The palette work establishes agreement with the supplied source, not measured Gold runtime colors. Passing browser and unit checks.

The original shadow-mask work is now scoped in #214.

Original movable shadows are now complete for the imported sequences in #214: original masks, signed anchors, independent table alignment, exact action frames and reference depth ordering replace the generic oval. The full browser gate passed, including independent source pixels and steep-terrain occlusion.

The related terrain-cache correction in #216 also passed the complete Linux gate. The next graphics defect is #215: shared terrain edges develop coverage gaps during face painting and chunk filtering. The current fix passes the flat-ground regression across zoom and camera offsets; textures, lighting, fog and overlap checks are still being completed. This does not finish the broader original graphics and animation import.

Progress: original graphics importing (still open)

bun run assets:import now converts 1,990 frames (b2efc1f): final and construction-site images for all 24 Roman buildings the engine defines, pile sizes one to eight for 23 Roman goods, Roman carrier walking cycles in six directions empty-handed and with each good (torso layers composited), saplings, crop growth stages, trees, stone deposits and landscape textures. Sequence numbers come from the pinned reference tables (EMaterialType, movables-ROMAN, building XML), each retained as a provenance input. Sprites the demo lacks are listed in the manifest's missing array instead of being substituted (none at present). assets:verify checks every required key, 72 frames per carrier and every building composite; content:verify covers all 33 converted files.

Remaining for this issue: other professions' work animations, soldiers, ships, siege, effects, shadows as separate layers, other civilizations, and anything outside the Amazons demo data. Redistribution rights remain unverified (S3-003).

Evidence base for this update (all on main, authored as Chris):

• 3ca4847 deterministic session, rules profile, routing, goods, carriers, construction, production, territory, visibility, saves and replays
• da2a104 reference building geometry and the delivery livelock fix
• b2efc1f the browser game on the engine, expanded original-media import
• 7b1cc36 worlds from decoded original maps
• a495e7a, 0a3ff46, 0e7889e, e5c1a53, f3b71ce, ed1dc8f controls, missions, render scene, save migration, checkpoints, audit and statistics

Checks: ./buddy lint (0 problems), bun run typecheck (app, tools, stx), ./buddy test --unit (106 tests, 0 failures), bun run assets:verify, bun run content:verify, and the production browser scenario. CI passed on 0e7889e and 9e2ba7c (which contains f3b71ce), including the production Chrome check.

Rule values are the roman-engineering 0.2.0 profile (resources/game/engine/rules.ts). Every value names its evidence class: manual candidates (M) from the pinned manual, reference-remake geometry (E), or placeholders (U) that name their owning issue. qualificationGaps() lists them and the profile cannot qualify a release. Adopting observed original values remains with S3-002/S3-007; nothing here is an original-executable observation.

Completed the landscape material slice in #219. All 32 base images for the 37 source types preserve independently decoded original pixels and their continuous or face-local UV policy. Actual 1x/2x rendering passed. The next import/rendering slice is #220: 41 ordered transition families and 160 additional source images. This does not complete the broader graphics inventory.

Validation: full CI, 413 unit tests and all 16 browser suites. The original diagnostic artifact checksum and ZIP integrity were independently verified.

The asset-download recovery in #221 is complete. Interrupted and inactive requests now retry within the existing deadline, verified partial bytes are never published, and timeout diagnostics retain transfer progress. A fresh original archive passed the normal provenance pipeline. CI passed with all 417 units and 546 browser steps; the original diagnostic artifact was independently checked. Mixed-face terrain transitions continue under #220.

The terrain correction in #220 is published and its full application CI is running. The separate scheduled dependency-bot failure exposed an upstream discovery defect: Buddy follows the generated storage/framework/defaults link into an installed package, then proposes an update to a file the repository does not own. The Git writer correctly rejects it.

stacksjs/buddy#1459 retains the real-filesystem scanner, adapter and catalog reproductions. The source correction excludes aliases while keeping real workspace, vendored and workflow declarations discoverable. Verification also exposed a linked-worktree diagnosis defect, tracked in stacksjs/buddy#1460. Release and installed-consumer qualification are pending. No application ignore rule or write-safety bypass has been added.