6. Stage a visual novel

Use the full Lesson 5 pack. This lesson adds a VN presentation while preserving its state and progression. Set protocol to 0.5 and revision to 7. A compatible VN reader is required to render the stage; the download checker does not include a player.

Bind images to subjects

Set presentation.protocol to storyorbit.vn/1. The background binding connects scene reader card greenhouse to greenhouse_art at dusk. Sprite bindings connect actor reader card rowan to rowan_neutral and rowan_smile, with expressions neutral and smile.

Copy the new smiling PNG and its exact asset declaration from the finished pack. The transparent sprites share a 256×256 canvas and the same body position. Keep a neutral baseline; expression names in stages and performances must resolve to the actor’s actual bindings. A background is scene art, not a character sprite.

Author the first stage

opening_stages[0] anchors to opening paragraph 0 and its digest. It names the location, scene subject, time of day and cast. Our cast places Rowan in neutral expression. Stage cues describe a visible composition; they do not change story state or choose the reader’s actions.

opening_suggestions provides three authored choices shown at the opening. This is separate from suggestions, which controls runtime suggestion behavior. Our opening choices ask about the seedling, offer help, or ask to stay quietly. None counts as completed care until an actual action is observed.

Give a spoken paragraph a performance

The Rowan annotation on paragraph 1 adds performance: { "focus": true, "expression": "smile" }. Its quote covers that entire paragraph. In a compatible player this focuses the speaker and uses the matching smile sprite. The stable actor ID, paragraph digest, quote and occurrence still matter.

Validate, then compare the two PNGs side by side. Expected private trial: greenhouse at dusk, Rowan visible, three authored opening options, and a smiling focused Rowan during the invitation. If a sprite is absent, check subject kind/ID, actor card, neutral binding, stage cast and uploaded bytes. If a cue is rejected, check paragraph digest and whole-paragraph dialogue eligibility. Do not label a successful JSON check as a VN playback test.

After staging the opening, follow Put authored artwork into the current scene to add one shared image per generated turn, state eligibility and portrait/landscape compositions.

The original teaching artwork

Static previews of the actual downloaded images. The sprite frames are shown separately for comparison; this is not a live player.

Original geometric teaching image: greenhouse glass, sunset and a seedling. — `greenhouse_art`

Original geometric Rowan teaching portrait on a transparent canvas. — `rowan_neutral`

Original geometric seedling keepsake teaching art. — `seedling_reward`

Original aligned smiling Rowan teaching sprite. — `rowan_smile`

Check your work locally

From the extracted bundle folder, create the environment and install the pinned dependencies once. Then check both files, and repeat the start check after your edits. The same commands work for every lesson.

macOS / Linux

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python check.py start/pack.json
.venv/bin/python check.py finished/pack.json

Windows PowerShell

py -3 -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe check.py start/pack.json
.venv\Scripts\python.exe check.py finished/pack.json

Expected for the finished pack: Structural check passed: Creator Pack 0.5 followed by the exact Schema SHA-256. This is a structural check, not host admission or a live playtest.

Working excerpt from the finished pack

This excerpt is generated from the tested download. It is not a complete pack; edit the named fields inside start/pack.json or compare finished/pack.json.

{
  "presentation": {
    "protocol": "storyorbit.vn/1",
    "bindings": [
      {
        "role": "background",
        "subject": {
          "kind": "reader_card",
          "id": "greenhouse"
        },
        "asset_id": "greenhouse_art",
        "time_of_day": "dusk"
      },
      {
        "role": "sprite",
        "subject": {
          "kind": "reader_card",
          "id": "rowan"
        },
        "asset_id": "rowan_neutral",
        "expression": "neutral"
      },
      {
        "role": "sprite",
        "subject": {
          "kind": "reader_card",
          "id": "rowan"
        },
        "asset_id": "rowan_smile",
        "expression": "smile"
      }
    ]
  },
  "opening_stages": [
    {
      "paragraph_index": 0,
      "paragraph_digest": "43a9743240b5b5c2afb0bcb5b3e77526a29e63d49f6b1433d2ae11c0d3e119f2",
      "location": "Greenhouse",
      "subject": {
        "kind": "reader_card",
        "id": "greenhouse"
      },
      "time_of_day": "dusk",
      "time_label": "Before closing",
      "cast": [
        {
          "actor_id": "rowan",
          "expression": "neutral"
        }
      ]
    }
  ],
  "opening_suggestions": [
    "Ask Rowan why the seedling is drooping.",
    "Offer to help with the watering.",
    "Ask to stay for a quiet moment."
  ],
  "performance": {
    "focus": true,
    "expression": "smile"
  }
}

Look up the fields: presentation · entries

Next lesson