Craft

The flow manifest

A flow is saved as one JSON object, its manifest. The prelude and a creation flow use the same format. Each step (nodes, also called screens) has a type and that type's data, listed in the step reference. The edges between them set the play order.

Branching

  • A step with one plain edge out goes to its target. A step with no edge out is an ending.
  • A choice where only one option can be picked branches: give it one edge per option, each with sourceHandle set to that option's id.
  • Branches meet again by pointing at the same step.
  • A choice with multiple set can't branch: give it one plain edge.

To see what a player sees, start at start and follow the edges to an ending, once for each branch. The order of nodes means nothing.

A prelude

A timed title, two beats, a found log and a choice that only changes the next line:

{
  "id": "prelude",
  "version": 1,
  "title": "Cold Static",
  "start": "title",
  "nodes": [
    {
      "id": "title",
      "type": "cover",
      "advance": {"mode":"timer","seconds":5},
      "transition": "fade",
      "data": {
        "eyebrow": "Coriolis Station, day 4,211",
        "title": "COLD STATIC",
        "backgroundFill": "linear-gradient(160deg, #14233a 0%, #070a10 72%)"
      }
    },
    {
      "id": "silence",
      "type": "statement",
      "data": {
        "title": "Nine days of silence.",
        "body": "Telemetry stopped without a distress call. The relief crew never reported back.",
        "backgroundFill": "linear-gradient(160deg, #2c2c34 0%, #0b0b0f 76%)"
      }
    },
    {
      "id": "log",
      "type": "reading",
      "data": {
        "title": "Last log entry",
        "body": "Day 4,202. The hum in the lower decks has changed pitch again. Okafor says it is the coolant. I don't think it is the coolant."
      }
    },
    {
      "id": "approach",
      "type": "choice",
      "field": "approach",
      "data": {
        "prompt": "How do you dock?",
        "layout": "cards",
        "options": [
          {"id":"quiet","label":"Run dark and listen first"},
          {"id":"loud","label":"Announce yourself on all bands"}
        ]
      }
    },
    {
      "id": "quiet-beat",
      "type": "statement",
      "data": {"title":"You cut the lights and drift in."}
    },
    {
      "id": "loud-beat",
      "type": "statement",
      "data": {"title":"Your hail echoes back, unanswered."}
    }
  ],
  "edges": [
    {"id":"e1","source":"title","target":"silence"},
    {"id":"e2","source":"silence","target":"log"},
    {"id":"e3","source":"log","target":"approach"},
    {
      "id": "e4",
      "source": "approach",
      "sourceHandle": "quiet",
      "target": "quiet-beat"
    },
    {
      "id": "e5",
      "source": "approach",
      "sourceHandle": "loud",
      "target": "loud-beat"
    }
  ],
  "settings": {"typography":{"headingFont":"Cinzel"}}
}

A creation flow

A background choice that branches into one of two questions, then meets again at a point-buy stat step:

{
  "id": "make-a-pilot",
  "version": 1,
  "title": "Make a Pilot",
  "start": "berth",
  "nodes": [
    {
      "id": "berth",
      "type": "choice",
      "field": "berth",
      "data": {
        "prompt": "Where did you serve?",
        "ai_instruction": "Sets the character's background, debts and contacts.",
        "options": [
          {
            "id": "salvage",
            "label": "Salvage crews",
            "ai_instruction": "Scavenger skills; owes money to a fence."
          },
          {
            "id": "navy",
            "label": "System navy",
            "ai_instruction": "Drilled and ranked; resented by spacers."
          }
        ]
      }
    },
    {
      "id": "salvage-prize",
      "type": "shortText",
      "field": "prize",
      "data": {
        "prompt": "What is the best thing you ever pulled from a wreck?",
        "ai_instruction": "Give the character this item.",
        "optional": true
      }
    },
    {
      "id": "navy-reason",
      "type": "longText",
      "field": "discharge",
      "data": {
        "prompt": "Why did you leave the navy?",
        "ai_instruction": "Shapes the character's flaw and who is after them."
      }
    },
    {
      "id": "stats",
      "type": "statPointBuy",
      "field": "stats",
      "data": {
        "prompt": "Spend 27 points.",
        "ai_instruction": "Use these scores exactly for the matching ability fields.",
        "stats": [
          {"id":"grit","label":"Grit"},
          {"id":"wits","label":"Wits"},
          {"id":"nerve","label":"Nerve"}
        ],
        "budget": 27,
        "minScore": 8,
        "maxScore": 15,
        "defaultScore": 8,
        "costs": [
          {"score":8,"cost":0},
          {"score":9,"cost":1},
          {"score":10,"cost":2},
          {"score":11,"cost":3},
          {"score":12,"cost":4},
          {"score":13,"cost":5},
          {"score":14,"cost":7},
          {"score":15,"cost":9}
        ]
      }
    }
  ],
  "edges": [
    {
      "id": "e1",
      "source": "berth",
      "sourceHandle": "salvage",
      "target": "salvage-prize"
    },
    {
      "id": "e2",
      "source": "berth",
      "sourceHandle": "navy",
      "target": "navy-reason"
    },
    {"id":"e3","source":"salvage-prize","target":"stats"},
    {"id":"e4","source":"navy-reason","target":"stats"}
  ]
}

Placeholders

<image URL>, <video URL> and <audio URL> in the examples below stand for a real Craft-hosted URL. To get one, pick or upload one in the screen's Background section.

The manifest and its parts

manifest

A whole flow: its screens (nodes), the steps between them (edges) and where it starts.

Field Type Required What it is
id string yes The flow's id.
version number yes The format version. Write 1.
title string yes The flow's name, shown to the author.
start string yes The id of the first node.
nodes node[] yes Every screen. Their order here is not the play order.
edges edge[] yes The steps between screens. They set the play order.
settings settings Settings for the whole flow.

node

One screen of the flow.

Field Type Required What it is
id string yes Unique within the flow. Edges point at it.
type string yes Which kind of screen this is.
field string The key the viewer's answer is saved under. Set on screens that ask a question, and only on those.
advance advance When a screen moves on by itself, without the viewer pressing Continue. Screens that ask a question always wait for the viewer.
transition transition How a screen enters. slide (the default) fades in with a slight drift in the direction the viewer is going; fade, zoom and rise are fixed effects; none swaps at once.
typography typography Overrides the flow's typography on this screen only.
audio media ref A sound that plays over the flow's music, which is turned down while this screen is up.
data Record<string, any> The screen's own settings. Each screen type takes its own.
{
  "id": "title",
  "type": "cover",
  "advance": {"mode":"timer","seconds":5},
  "transition": "fade",
  "data": {
    "eyebrow": "Coriolis Station, day 4,211",
    "title": "COLD STATIC",
    "backgroundFill": "linear-gradient(160deg, #14233a 0%, #070a10 72%)"
  }
}

advance, transition, typography and audio are optional on every step. Leave out what you don't need.

edge

A step from one screen to the next.

Field Type Required What it is
id string yes Unique within the flow.
source string yes The node it leaves from.
sourceHandle string The option id this edge follows, when it is one branch of a single-choice question. Left out on a plain edge.
target string yes The node it goes to.
{"id":"e1","source":"title","target":"silence"}
{
  "id": "e4",
  "source": "approach",
  "sourceHandle": "quiet",
  "target": "quiet-beat"
}

advance

When a screen moves on by itself, without the viewer pressing Continue. Screens that ask a question always wait for the viewer.

Value What it does
{ "mode": "manual" } Waits for the viewer to continue. The default.
{ "mode": "timer", "seconds": number } Continues on its own after seconds.
{ "mode": "media" } Continues when the screen's background video ends.
{"mode":"timer","seconds":5}

A step without advance waits for the player, a video step too: give it { "mode": "media" } to move on when its clip ends. The editor does that for a new video step. A timer on a question step is ignored.

transition

How a screen enters. slide (the default) fades in with a slight drift in the direction the viewer is going; fade, zoom and rise are fixed effects; none swaps at once.

Values: "slide", "fade", "zoom", "rise", "none".

"fade"

typography

Fonts and text size. Set for the whole flow in its settings; a screen can override any part of it.

Field Type Required What it is
headingFont string The font for titles, by name.
bodyFont string The font for body text, by name.
size number, 50–200 Text size as a percentage of normal (100).
weight number, whole number, 100–900 Font weight, 100 (thin) to 900 (black).
{"headingFont":"Cinzel","size":110}

A font name is a name from Craft's font list, the same fonts a project theme offers. A name not on the list falls back to the default font.

settings

Settings for the whole flow.

Field Type Required What it is
music music One track that plays across the whole flow without restarting between screens.
typography typography The fonts every screen uses unless it sets its own.
generationInstructions string Guidance for whatever the flow's answers are used to make. The flow itself never reads it.
{
  "music": {
    "track": {"url":"<audio URL>","kind":"audio"},
    "loop": true,
    "volume": 0.6
  }
}

In a creation flow, generationInstructions reaches the AI only when the character type has no generation instructions of its own, both when a player makes a character and when the AI drafts a new file of that type. Set them on the type instead where you can.

music

One track that plays across the whole flow without restarting between screens.

Field Type Required What it is
track media ref The audio to play.
loop boolean Start again when the track ends.
volume number, 0–1 From 0 to 1. Full volume when left out.

In the app, the track is picked from the music in your studio.

media ref

A picture, video clip or sound used by a flow.

Field Type Required What it is
url string yes Where the media is hosted.
kind "image" | "video" | "audio" yes What the media is.
focalPoint object The point to keep in view when the picture is cropped, from 0 to 1 across (x) and down (y).
overlayUrl string A picture drawn over the image, such as a logo.
animation object A looping animated version of the picture, kept from its image.

focalPoint: the point to keep in view when the picture is cropped, from 0 to 1 across (x) and down (y).

Field Type Required What it is
x number, 0–1 yes Across, from the left edge.
y number, 0–1 yes Down, from the top edge.

animation: a looping animated version of the picture, kept from its image.

Field Type Required What it is
kind "animated_gif" | "generated_video" yes Where the animation came from.
posterUrl string yes A still frame shown while it loads.
mp4Url string yes The animation as MP4.
webmUrl string The animation as WebM.
{"url":"<image URL>","kind":"image","focalPoint":{"x":0.5,"y":0.3}}

Every URL must be one Craft hosts.