Thunder Smith character-skin contract#

Thunder Smith is SmolForge's small animated workshop familiar. Contributors may create alternate character skins, but every skin must fit the same frame, action, anchor, and compositing rules so SmolForge can place it into official workshop scenes without per-skin exceptions.

New user skins follow the profile-aware character skin specification: skin.json plus one horizontal strip per action. The older 8 × 9 atlas remains a validated runtime artifact and can be exported into that user-facing format.

Kit contents#

• Official Thunder Smith spritesheet
• Apron and horned-helmet vNext study
• Spritesheet contact sheet
• Action reference board
• Official SmolForge prop board
• Generated motion previews
• Current product-pack contact sheet
• Current product-pack motion previews
• Current product-pack regeneration receipt
• Skin-swap stage demonstration
• Upload demo screenshot
• Example exported Sites composite
• Validation report
• Machine-validatable v1 skin schema
• Legacy atlas metadata (not a skin.json schema)
• Generation prompts
• User-package exporter
• Interactive upload and compositing demo

The interactive demo accepts either a transparent standalone PNG/WebP or the legacy 1536 × 1872 atlas. It validates atlas dimensions, required frames, and transparent unused cells; lets the user animate or scrub each state; and composites the character between fixed SmolForge background and foreground prop layers. It can export the resulting stage as a 960 × 600 PNG.

Export the legacy canonical atlas as a valid compatibility product profile package:

node docs/design/thunder-smith-kit/scripts/export-user-package.mjs \
  --output /tmp/thunder-smith-product

This exporter is intentionally crop-only: it never mirrors the readable S, invents missing frames, resizes art, or hides game-profile gaps. It does not recreate official/product-skin/, whose non-directional actions are curated generated art. The crop-only export and the checked-in official product skin are two distinct packages.

The GIFs under official/previews/ are legacy-atlas visual-QA derivatives. They remain useful for reviewing the compatibility source, but they do not represent the current curated product strips unless explicitly regenerated. The official product package is split into authoring source/ and installable dist/. Run npm run build:character-skin from the repository root to validate the canonical v0.4 manifest contract, file magic, decoded dimensions, alpha, per-frame occupancy, safe bounds, and transparent-pixel RGB; rebuild the installable package; emit lossless runtime WebPs; and regenerate the current contact sheet, per-action previews, receipt, and TypeScript manifest. npm run check:character-skin fails when any derived package, runtime, or QA artifact is missing, stale, or unexpected.

The contact sheet uses the receipt's fixed nine-row order: idle, walk right, walk left, wave, celebrate, fail, wait, work, and review. Its eight columns are the maximum clip width; unused cells intentionally show only the checkerboard. The preview GIFs loop for visual QA even when a runtime clip has different playback semantics.

The official Thunder Smith S badge#

The vNext official Thunder Smith carries one unmistakable uppercase S on a terracotta leather work apron:

• The S is embossed directly into the apron bib rather than mounted on a separate square body tile.
• It is part of the character layer and appears in every used frame.
• It remains on the same anatomical side and at a consistent apparent scale.
• The S must read normally, never backward. A mechanically mirrored frame must have its badge redrawn or corrected.
• It is the only letter, word, logo, or rune in the official character art.

The official product package uses the apron-and-horned-helmet Thunder Smith for every product action, including independently generated left- and right-facing walk strips. No strip is mirrored; the S badge, hammer hand, and tail side remain consistent. Generated upstream videos are not committed, so the curated package is pinned by its manifest, selected source pixels, output hashes, and regeneration receipt rather than deterministically regenerated from the legacy atlas. The exact committed source-art revision is recorded in skin.json and export-report.json. The public contract Gist is a specification source, not the provenance source for these pixels.

The checked-in manifest and license file currently declare CC-BY-4.0. That assertion has repository history but no independent rights evidence in this kit. The project owner must confirm that the source and generated media can be distributed under those terms before enabling public registry distribution; the build preserves the existing declaration and does not treat it as proof.

The current fail.v01 source strip bows in disappointment and then returns to an upright stance. Until replacement art provides a truly failed final hold, the manifest truthfully uses loop with bowed frame 3 as its reduced-motion poster. It must not use hold on the neutral final frame.

The current product-pack contact sheet passes the structural checks, but manual visual review still shows faint baked floor/contact shadows in parts of the directional walks and celebrate sequence. Those pixels predate the deterministic packager and conflict with the clean character-layer ideal below. Keep them as known source-art debt rather than deleting character pixels heuristically; replacement strips should remove them before this art is treated as registry gold.

Community skins do not need to wear the S. Their author may use a simple personal emblem, a blank badge, or no badge at all. The upload contract is about geometry and behavior, not ownership of the character's identity. SmolForge remains recognizable through the fixed stage, prop, palette, and UI layers around the uploaded character.

Legacy atlas geometry#

The app reads one fixed transparent atlas:

Used cells must contain one complete character pose. Every cell after a row's last used frame must be fully transparent.

running means actively working or processing. It is not locomotion. Directional travel belongs only in running-right and running-left.

Character layer versus SmolForge layers#

A submitted skin contains the character only:

• body, clothing, optional personal badge, and identity-defining worn accessories;
• hard-edged, physically attached effects when a state truly needs them;
• transparent pixels everywhere else.

The character atlas must not contain scenery, floors, cast shadows, floating marks, UI, labels, or task-specific objects. In particular, do not bake any of the official SmolForge objects into a skin.

SmolForge separately owns and composites:

1. Stage layer — workshop floor, backdrop, lighting bed, and placement.
2. Prop layer — official product objects and contextual effects.
3. Character layer — the selected official or community skin.
4. UI layer — labels, controls, status text, and accessibility affordances.

This separation lets one skin work on Code, Actions, Sites, Transcripts, and future surfaces without regenerating the character.

Official action and object mapping#

The app may pair a character state with an official object according to page context. The object is never required inside the uploaded atlas.

These are compositing defaults, not alternate meanings for the animation rows. For example, failed must read as failure whether it appears beside an issue stone or a thunder drum.

Cell anchors, baseline, facing, and scale#

Coordinates below are local to each 192 × 208 cell.

• Safe bounds: keep visible character pixels within x = 18…174 and y = 16…192.
• Ground anchor: the midpoint between the feet or lowest body contact is anchored at (96, 192) in grounded poses.
• Baseline: y = 192. Do not draw a floor or shadow on it.
• Canonical facing: three-quarter front-right, with the face and S badge readable.
• Directional facing: running-right faces and travels toward image right; running-left faces and travels toward image left.
• Non-directional rows: retain the canonical three-quarter facing unless the motion needs a small temporary head or torso turn.
• Scale: establish one canonical body scale from the base character and hold it across the atlas. A typical grounded character is 150–168 px tall, never wider than the safe bounds, with no frame-to-frame zooming.
• Airborne motion: move the character upward for jumping; do not shrink it. The conceptual landing point remains (96, 192).
• Wide poses: waving limbs and running strides must remain inside the safe bounds and must not cross into a neighboring cell.

Small pose-driven bounding-box changes are expected. Apparent body scale, camera angle, material, and head-to-body proportion must remain stable.

State behavior#

• idle: subtle breathing, blink, or tiny material sway; visibly animated but calm enough to sit beside code.
• running-right: clear rightward locomotion with an alternating gait.
• running-left: clear leftward locomotion with matching identity and cadence.
• waving: greeting shown through the limb pose, without motion marks.
• jumping: anticipation, lift, peak, descent, and settle using body position.
• failed: readable deflation, sadness, or error reaction without a floating red X.
• waiting: expectant, asking posture for approval, help, or user input.
• running: focused work, processing, scanning, or busy-hand motion without walking or directional travel.
• review: attentive inspection using lean, gaze, blink, or head tilt.

Do not use speed lines, dust, floor marks, glows, auras, loose sparkles, floating punctuation, detached smoke, or separate tear droplets. Any approved effect must touch the character, be opaque, and remain inside the frame.

Upload validation#

A user upload is accepted only when all of the following pass:

File and grid#

• PNG or WebP with alpha support.
• Exactly 1536 × 1872 px.
• Exactly the required 8 × 9 cell layout and row order.
• Every required used cell is non-empty.
• Every unused cell is fully transparent.
• Fully transparent pixels contain no hidden RGB residue.

Geometry#

• No visible pixel crosses a cell boundary.
• Character pixels stay inside the 18 px horizontal and 16 px vertical safe margins, except that grounded poses may touch the y = 192 baseline.
• Grounded poses align to the same baseline and horizontal anchor.
• Scale and camera remain stable; preview animation has no size popping.

Identity and semantics#

• The official Thunder Smith has one readable, correctly oriented S badge in every frame. Community skins consistently preserve whatever badge choice their author made: personal emblem, blank badge, or none.
• The same character identity, face, proportions, palette, material, and worn accessories persist across all rows.
• Directional rows face the correct way and show an alternating gait.
• Each row communicates its declared state; running is work, not foot-running.
• idle contains visible micro-motion rather than six identical frames.

Clean compositing#

• Background is transparent, with no chroma-key fringe.
• No scenery, floor, cast or drop shadow, UI, readable text beyond the S, official SmolForge prop, detached effect, guide mark, or neighboring pose is present.
• Edges are clean enough to remain readable when rendered at one cell or smaller.

Automated checks should reject structural failures. A contact sheet and per-row motion preview must still receive visual review for identity drift, backward badges, wrong facing, inert motion, and semantic mistakes.

Contributor workflow#

1. Design one canonical full-body character on a removable flat chroma background.
2. Lock the identity, camera, scale, palette, material, and any optional worn badge or emblem.
3. Generate one horizontal strip per row using the exact frame count.
4. Correct running-left rather than accepting a backward S.
5. Extract frames and compose the atlas deterministically; do not ask an image model to lay out the final 8 × 9 atlas.
6. Validate the atlas, then inspect a contact sheet and every row in motion.

See GENERATION-PROMPT.md for a complete example and a reusable one-row prompt.