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
sourceHandleset to that option'sid. - Branches meet again by pointing at the same step.
- A choice with
multipleset 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.