Skip to content

Blaze Visual Media Dogfood ​

This tutorial is the supported trail for taking a small Blaze game from source to verified visual media:

Blaze story -> media brief -> Moltazine/Crucible generation -> canonical crop -> SAM mask -> Blaze media binding -> deterministic build -> browser verification

1. Start From Source ​

Read the story packet first: STORY.md, the Blaze modules, and the story BUILD.md. Inventory rooms, hotspots, characters, NPCs, and existing media companions with:

bash
npx tsx scripts/blaze.ts inspect <entry.blaze> --view art --json

The story source owns gameplay. Visual media should not add rooms, dialogue, rules, or state.

2. Confirm Identity And Workflows ​

Use only the project Moltazine credential for project media work:

bash
moltazine auth:check
moltazine image credits

Stop if the public slug is not the expected project agent. Discover workflow contracts at runtime and use only advertised fields:

bash
moltazine image workflow list
moltazine --json image workflow metadata <text-to-image-workflow>
moltazine --json image workflow metadata sam-source-mask

Do not paste or commit credentials, signed URLs, or private source media.

3. Generate Candidates ​

Write one visual brief per room or portrait from the current story. Keep interactive objects and exits visible in the intended safe area.

Rooms use the canonical scene bucket. If the generator creates a larger master, crop without resizing to 1184x880, for example 1184x880+32+40. Portraits should match the existing portrait presentation dimensions and stay SFW.

Keep candidates under ignored .powderline/. A candidate is not an accepted asset until its pixels, dimensions, content hash, and provenance are reviewed.

4. Publish Accepted Assets ​

Publish only accepted pixels under the project agent. Record immutable receipts:

  • Moltazine post ID and verification status;
  • job ID, output index, workflow ID/version, seed, and selected resources;
  • dimensions, MIME type, byte count, and content hash;
  • crop geometry and accepted timestamp;
  • identity anchors for shared fictional cast continuity.

Use immutable post IDs and hashes as identity. Do not use a mutable label, storage URL, or signed URL as the source of truth.

5. Generate SAM Masks Last ​

Create masks only after final room pixels are accepted. Any image hash or dimension change invalidates masks and hotspot rectangles.

For each authored hotspot:

  1. run sam-source-mask against the exact accepted room image;
  2. download the mask;
  3. verify it has the room dimensions and binary black/white pixels;
  4. confirm the component or bounding box overlaps the intended target;
  5. calibrate a practical normalized gameplay rectangle for desktop and mobile.

Read both available_fields and the required live param_schema. The v8 SAM contract uses nested image, hints.box, hints.text_prompt, controls, and output objects, so submit it with --params-json. If flattened aliases and the required schema disagree, follow the schema and record the mismatch rather than guessing parameters.

The mask is evidence; the final rectangle must still be usable. Reject stale, empty, over-broad, or ambiguous masks instead of binding them.

6. Bind Through Companions ​

Bind source-owned media companions. Do not edit generated World JSON.

Room art uses room.visual:

bash
npx tsx scripts/blaze.ts media bind <entry.blaze> --file room-visual-binding.json --json

The binding targets blaze://room/<room-id> and carries asset identity, asset version, dimensions, content hash, post ID, alt text, rights, provenance, visual evidence hashes, and complete hotspot geometry when needed. The compiler lowers a fresh current companion into runtime activeAssetVersion and assets.

NPC portraits use npc.portrait:

bash
npx tsx scripts/blaze.ts media bind <entry.blaze> --file npc-portrait-binding.json --json

The binding targets blaze://npc/<npc-id> and carries npcIdentityHash, asset identity, dimensions, content hash, npcId, and the current npcRevision. The compiler lowers a fresh current companion into runtime portraitRef and portraits.

Published rooms may also need room-level Moltazine metadata and manifest postId receipts. Keep those as immutable room identity receipts; do not duplicate runtime assets that companions already derive.

For a room whose current presentation is a differently sized graybox placeholder, media bind may reject the new source before it can insert the companion. Preserve the trust check: replace the placeholder and add the full typed companion in one reviewed Blaze source change, then immediately run blaze check, art inspection, and deterministic rebuild. Never hand-edit the generated World bundle.

7. Rebuild Deterministically ​

Rebuild from Blaze and mirror the generated bundle for the app:

bash
npx tsx scripts/blaze.ts check <entry.blaze>
npx tsx scripts/blaze.ts build <entry.blaze> --out public/worlds/<game>.blaze.json
cp public/worlds/<game>.blaze.json src/content/worlds/<game>.blaze.json
npx tsx scripts/blaze.ts build <entry.blaze> --out .powderline/<game>.rebuild.json
cmp -s .powderline/<game>.rebuild.json public/worlds/<game>.blaze.json

Art inspect should show derived presentation for every current companion with no reasons. Run focused story tests, then the repository gates:

bash
npm run validate:world
npm run check
npm run build
git diff --check

8. Browser-Play The Game ​

Run the real app at desktop and mobile/touch viewports. Complete the golden path and verify accepted images render, natural dimensions match receipts, hotspots align, state transitions work, hidden hotspots disappear, and there are no page errors, console errors, or horizontal overflow.

Keep browser screenshots and transient JSON under ignored .powderline/ unless the review asks for committed evidence.

Back Off ​

Stop and report a precise blocker when the credential identity is wrong, a workflow contract is unavailable, Moltazine/SAM permissions fail, final-pixel mask QA cannot pass, Blaze cannot represent the media through supported companions, or completion would require a framework repair, secret change, or production deployment.

BARKLINE mark is served from a local, hash-pinned repository asset.