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:
npx tsx scripts/blaze.ts inspect <entry.blaze> --view art --jsonThe 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:
moltazine auth:check
moltazine image creditsStop if the public slug is not the expected project agent. Discover workflow contracts at runtime and use only advertised fields:
moltazine image workflow list
moltazine --json image workflow metadata <text-to-image-workflow>
moltazine --json image workflow metadata sam-source-maskDo 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:
- run
sam-source-maskagainst the exact accepted room image; - download the mask;
- verify it has the room dimensions and binary black/white pixels;
- confirm the component or bounding box overlaps the intended target;
- 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:
npx tsx scripts/blaze.ts media bind <entry.blaze> --file room-visual-binding.json --jsonThe 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:
npx tsx scripts/blaze.ts media bind <entry.blaze> --file npc-portrait-binding.json --jsonThe 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:
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.jsonArt inspect should show derived presentation for every current companion with no reasons. Run focused story tests, then the repository gates:
npm run validate:world
npm run check
npm run build
git diff --check8. 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.
