Put authored artwork into the current scene

One generation can select one creator-supplied illustration for all its narration blocks. Dialogue keeps its character stage. A reader’s manually requested Imagine image also appears directly on its current page, with reading and choice controls still available.

Start with Lesson 6’s complete greenhouse pack. First reuse its existing image, then substitute your own portrait and landscape art. The protocol remains 0.5, with no migration required for old packs, but the checker, host and reader must support these additional fields. This tutorial was checked against schema snapshot 18756b09a11f4f234d1e2fcd5237a93be0b4bad8f9afae7d2a99243d7d9cd959.

1. Give the artwork a stable identity

Download and extract Lesson 6. Edit finished/pack.json and append this object to its existing illustrations array. Keep the original opening illustration. It references the included greenhouse_art, so no new files are needed yet.

{
  "id": "greenhouse_after_care",
  "asset_id": "greenhouse_art",
  "variant_asset_ids": [],
  "alt": "A seedling sits on a bench under green window frames at sunset.",
  "actor_ids": [],
  "entry_ids": ["arrival"]
}

asset_id names a declared asset; alt truthfully describes the image. This establishing view has no people, so actor_ids is empty. If you replace it with a picture of Rowan, include the actual actor card ID rowan; list every depicted actor. Omitting an actor to show their image early is not an authoring shortcut.

Use declared static images with access: "standard" and without reference_only. PNG, JPEG and WebP are supported; APNG belongs to character performance and cannot be used here. The actual file’s SHA-256, byte size, MIME and uploaded attachment must agree with its declaration.

2. Check eligibility, then suitability for this turn

Keep the existing presentation.protocol and presentation.bindings. Add this rule to the presentation.illustration_rules array:

{
  "id": "after_shared_care",
  "illustration_id": "greenhouse_after_care",
  "when": {
    "op": "all",
    "conditions": [
      { "op": "gte", "path": "/trust", "value": 2 },
      { "op": "eq", "path": "/left", "value": false }
    ]
  },
  "match": "All narration stays in the greenhouse at dusk, with the seedling bench as a suitable establishing view. No move to another place or time.",
  "priority": 10
}

Both snippets are partial objects, not complete packs. Increase manifest.revision from the lesson’s 7 to 8; use a higher new revision in your own project. Preserve the other story, state, opening and progression fields.

when uses the same state condition grammar as achievements. Here, shared care must reach 2 and the reader must not have left. This makes the rule a candidate; it does not prove the picture fits the story. observed is not allowed here. Have an existing runtime rule record a qualifying action in state first.

match describes the actual present scene for which the image is suitable. The host evaluates eligible candidates in one JEV semantic batch against the complete generation, never one call per block. Describe compatible place, time, people and action throughout all narration. Mentioning, remembering or planning a greenhouse visit is insufficient, as is leaving halfway through the narration. A matching rule does not instruct the narrator to rewrite the story to fit the picture.

Selection eligibility is not media secrecy. when governs this rule. Asset reveal_when, entry scope and depicted actors’ disclosure conditions still govern the image. Use separate, correctly gated assets for unrevealed material; do not also use them as public covers. Depicted-actor checks also apply to same-byte aliases. Configure reveal_when correctly for every asset ID and variant; never register private bytes as a separate always-visible public asset.

3. Understand the achievement and artwork boundary

Eligibility uses state and disclosure before the turn begins. A character or image newly unlocked during the turn can become a candidate on the following turn. Rehearse this sequence with the greenhouse pack:

Turn	Starting /trust	What happens	Expected result
First	0	Complete one care action	Trust becomes 1; this rule is not evaluated
Second	1	Complete another care action	Trust becomes 2 and the achievement may settle; this rule still is not evaluated
Third	2	Stay in the greenhouse at dusk	The rule is eligible; show the image only if semantic matching also succeeds
A later turn	2	Move from the greenhouse to the path home	One image cannot cover the whole turn; keep ordinary staging

Scene selection creates no achievement, permanent unlock or additional state. This continuation rule does not run automatically on the opening. Fixed opening illustrations retain their exact opening_illustrations paragraph placement; opening staging uses opening_stages.

4. Prepare portrait and landscape compositions

Declare both real files in assets, put the main asset ID in asset_id, and place the other ID in variant_asset_ids. Both must depict the same scene, people and event, with different framing. Day versus night, or before versus after a confession, belongs in different illustrations and rules.

variant_asset_ids permits eight additional assets, excluding the main image; IDs must be distinct. The main image and every variant must be disclosed for the candidate to qualify. A landscape variant cannot hide an undisclosed actor. Readers select a composition from actual image dimensions and their current viewport; there are no ios_asset_id or web_asset_id fields.

Prepare a portrait composition for phones and a wide composition for desktops. Web preserves the full composition with a blurred extension; iOS may crop a near-matching image to fill the viewport, and uses a blurred extension for larger differences. Keep faces and important details away from image edges. Portrait artwork reduces framing differences on a phone. Rotation selects from existing variants and never generates artwork.

5. Keep a large catalogue understandable

Filter candidates with entry_ids and existing state conditions before writing short, distinct match descriptions. Group by current chapter, location and relationship stage instead of making every picture always eligible. entry_ids belongs to the illustration; state conditions belong to the rule’s when.

When multiple rules match, the highest priority wins: -1000 to 1000, default 0. If that highest priority still names different illustrations, the host abstains; array order does not break the tie. Several winning rules pointing to the same illustration may select that image. Priority resolves successful matches; it does not reduce the candidates sent for matching.

A pack currently supports up to 128 rules, 128 illustrations and 128 assets; variants consume asset slots too. The optional selection has one provider attempt, a six-second budget and a 60,000-byte bound for candidate questions plus complete turn text. No eligible candidates or no narration means no matching call. Oversized input, timeout, failure or ambiguity keeps ordinary staging while the story continues. Large catalogues are not automatically split into more batches.

6. What readers see on iOS and web

Readers can start reading while generation is still streaming. Selection settles only after successful acceptance of the whole turn. If the reader is still on its narration, the image appears directly there; otherwise it appears when they revisit that block. Arrival never moves the reading cursor.

The selected art covers every narration block in that turn, including an ending coda. Dialogue retains its character stage. Entering or revisiting an eligible page fades and expands the image to the full stage while keeping text and controls. Ordinary updates do not restart it; overlays pause it. Reduce Motion uses a static composition. Missing image bytes do not block reading.

Imagine remains an explicit reader action. On completion it uses the same scene surface without another click to view. The exact page’s Imagine image takes precedence over authored art; it does not replace the other pages in that turn. iOS requests a suitable portrait size from its actual portrait viewport; web also selects for its own viewport. output_size is an Imagine request field, not a Creator Pack field. Revisiting or rotating a page reuses its generated image without another purchase.

7. Validate and run a private trial

From the extracted directory, run .venv/bin/python check.py finished/pack.json, or .venv\Scripts\python.exe check.py finished/pack.json on Windows. Follow the download’s README first if the checker dependencies are not installed. Verify the exact schema above, or a newer snapshot supporting the same fields; an older 0.5 schema can reject the additions.

The site’s tests merge these two JSON objects into both localized Lesson 6 packs, validate schema and references, and rehearse the state eligibility boundary above. They make no live JEV or Imagine calls and do not establish a service trial for your artwork. Create a private journey on the new revision through a compatible host, then check:

1. Complete two care actions and continue in the greenhouse. Treat eligibility and semantic matching as separate steps.
2. Mix narration and dialogue; only narration receives authored scene art. Change location or merely recall/mention the greenhouse to check for false matches.
3. Confirm late image arrival preserves the reading position. Leave and revisit the page: reuse the image and replay its entrance.
4. Continue reading on iOS portrait, landscape and web. Manually request Imagine; its result appears directly, with no new generation on rotation or return.

For missing art, check exact schema, entry, pre-turn state, disclosure of every variant and depicted actor, scene changes across the complete turn, then priority ties. Record actual results and client versions before publishing through Lesson 9. Rule edits do not retroactively reclassify accepted passages; existing journeys retain their starting pack revision.

Return to Lesson 6 · All 0.5 fields