The visual novel document
A visual novel is one JSON document. The editor saves it on every change, and the same rules check it everywhere it is saved. Every entry below is read from those rules, so the fields, values and limits are exactly what a story accepts.
A complete document
{
"version": 2,
"pages": [
{
"id": "p-001",
"kind": "sceneHeading",
"title": "Kestrel Bay",
"subtitle": "The night the lanterns went out",
"background": {
"imageUrl": "https://media.craftrpgs.com/example/harbor-night.webp",
"mobileImageUrl": "https://media.craftrpgs.com/example/harbor-night-tall.webp",
"label": "The harbor at night"
}
},
{
"id": "p-002",
"kind": "narration",
"text": "Rain needles the harbor. Past the breakwater, the last lantern gutters."
},
{
"id": "p-003",
"kind": "dialogue",
"text": "You came back. I told the tide you would.",
"speaker": { "type": "cast", "castId": "oracle", "expressionId": "oracle-thoughtful" }
},
{
"id": "p-004",
"kind": "dialogue",
"text": "*Listen.* The water is counting something.",
"speaker": { "type": "cast", "castId": "oracle", "x": 62, "mobile": { "x": 60 } },
"images": [
{
"id": "drowned-lantern",
"url": "https://media.craftrpgs.com/example/lantern.webp",
"alt": "A drowned lantern, still glowing",
"x": 20,
"y": 42,
"width": 18,
"aspectRatio": 0.75,
"rotation": -8,
"mobile": { "x": 22, "y": 30, "width": 30 },
"stay": { "throughPageId": "p-005" }
}
]
},
{
"id": "p-005",
"kind": "handout",
"style": "letter",
"title": "Harbormaster's note",
"text": "Close the bay at dusk.\n\nDo **not** answer the bells.",
"imageChanges": [{ "imageId": "drowned-lantern", "opacity": 0.6 }]
},
{
"id": "p-006",
"kind": "dialogue",
"text": "Up here the bells never stop.",
"speaker": { "type": "custom", "name": "Bell-ringer", "role": "character" },
"background": {
"imageUrl": "https://media.craftrpgs.com/example/bell-tower.webp",
"transition": "cut"
}
}
],
"chapters": [
{ "id": "ch-harbor", "title": "The Harbor", "startPageId": "p-001" },
{ "id": "ch-tower", "title": "The Bell Tower", "startPageId": "p-006" }
],
"music": [
{
"id": "cue-rain",
"title": "Rain on Slate",
"url": "https://media.craftrpgs.com/example/rain-on-slate.mp3",
"startPageId": "p-001",
"endPageId": "p-005",
"volume": 0.5
}
],
"assets": {
"speakers": [
{
"id": "oracle",
"name": "The Oracle",
"role": "character",
"imageUrl": "https://media.craftrpgs.com/example/oracle.webp",
"cutoutUrl": "https://media.craftrpgs.com/example/oracle-cutout.webp",
"placement": { "position": "right", "mobile": { "x": 62, "scale": 0.9 } },
"expressions": [
{
"id": "oracle-thoughtful",
"name": "thoughtful",
"imageUrl": "https://media.craftrpgs.com/example/oracle-thoughtful.webp",
"cutoutUrl": "https://media.craftrpgs.com/example/oracle-thoughtful-cutout.webp"
}
]
}
],
"backgrounds": [
{ "id": "bg-harbor", "url": "https://media.craftrpgs.com/example/harbor-night.webp", "label": "The harbor at night" }
],
"music": []
},
"settings": { "textReveal": "word" }
}
What carries over from page to page
A page holds only what changes on it:
- The backdrop stays until a page sets a new one. A hidden page's backdrop doesn't carry.
- Music plays from a cue's first page through its last.
- A picture is on its own page only, unless its
staykeeps it on. A later page changes how a staying picture looks withimageChanges, never where it is. - Where a cutout stands is decided field by field. On the wide stage:
the page's own spot, then the cast member's default, then the centre at
normal size. On a phone held upright: the page's
mobilespot, then the member'smobiledefault, then whatever the wide stage settled on. So a story nobody placed for phones reads the same on them, and a page that moves someone sideways keeps their usual size.
Every page, chapter, cue, member, expression and picture has an id: any
unique string up to 64 characters. Readable ids (p-012, oracle,
oracle-wary) keep a story easy to edit. Keep the ids a story already
has, because lines point at members by id, and chapters, cues and staying
pictures point at pages.
The story
Document
The whole story: its pages in order, its chapters and music, its cast, and its settings.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
version |
2 |
yes | The format's version. | ||
pages |
page[] |
yes | at most 2,000 | The pages, in reading order. The last one is the ending. | |
chapters |
chapter[] |
yes | at most 200 | The chapters, in order. | |
music |
music cue[] |
yes | at most 200 | The music cues. | |
assets |
assets |
{"backgrounds":[],"speakers":[],"music":[]} |
The story's cast, and the backdrops and tracks the editor offers to pick from. | ||
settings |
settings |
{"textReveal":"word"} |
Settings for the whole story. |
The first chapter must start on the first page; one is added on save when it doesn't.
Pages
Page
One page of the story: what the reader sees between two clicks. A page owns only what changes on it; the backdrop, the music and staying pictures carry on from the pages before.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
id |
string |
yes | at most 64 characters | Unique in the story. Chapters, music cues and staying pictures point at pages by id. | |
kind |
"dialogue" | "narration" | "readAloud" | "handout" | "sceneHeading" | "scene" | "video" |
yes | What sort of page it is (one entry each below). | ||
text |
string |
"" |
at most 8,000 characters | What the page says, in light Markdown: **bold**, *italics*, and a blank line between paragraphs. |
|
title |
string |
at most 200 characters | A scene heading's or a handout's title. | ||
subtitle |
string |
at most 200 characters | A scene heading's second line. | ||
style |
"letter" | "note" | "inscription" | "book" |
How a handout looks. | |||
hidden |
boolean |
false |
Keeps the page in the document but out of the story. Its backdrop doesn't carry forward. | ||
speaker |
cast speaker | custom speaker |
Who says the page: a cast speaker or a custom one. | |||
background |
background |
A change of backdrop. Set it only on the page where the backdrop changes: every later page keeps it. | |||
textPosition |
"bottom" | "center" |
"bottom" |
Where the text sits: in the box at the bottom, or centred. | ||
transition |
"fade" | "slide" | "none" |
"fade" |
How the page comes in. | ||
videoUrl |
media URL |
A video page's clip (mp4 or webm). | |||
mobileVideoUrl |
media URL |
A clip made for a phone held upright. Without it, phones play videoUrl. |
|||
audio |
narration clip |
The narration readers hear as the page opens: generated from the page's words, uploaded, or brought along from the game. The app writes it. | |||
images |
picture[] |
at most 12 | Pictures placed on this page, back to front. | ||
imageChanges |
picture change[] |
at most 48 | Changes to how pictures staying from earlier pages look. | ||
source |
{ messageId?, uiMessageId? } |
The game message the page was made from. The export writes it; leave it as it is. |
Dialogue page
"kind": "dialogue". Someone speaks: their name and portrait head the text box, and their cutout stands on the stage.
Give it a speaker: without one it reads as narration.
{ "id": "p-010", "kind": "dialogue", "text": "Counting what?", "speaker": { "type": "cast", "castId": "wren" } }
Narration page
"kind": "narration". The narrator's prose. A speaker puts their name on it.
A story made from a game turns each paragraph of the GM's prose into
one. A speaker names them without making it a line of dialogue.
Read-aloud page
"kind": "readAloud". Boxed text for a moment that should land.
Use it sparingly, for a moment the reader should stop on.
Handout page
"kind": "handout". A document the reader holds: a letter, a note, an inscription or a page of a book.
Takes a title and a style: letter, note, inscription or book.
The narration reads the title first.
Scene heading page
"kind": "sceneHeading". A centred title card that opens a scene.
Takes a title and an optional subtitle. Open each chapter on one, and
set the new scene's background on it. It has no narration.
Scene page
"kind": "scene". The stage itself, with the text as a caption along the bottom. A speaker stands someone there silently.
The text is a caption and may be empty. A story made from a game gets one for every scene image the game made. It has no narration.
Video page
"kind": "video". A clip playing over the stage, with the text as its caption.
Takes videoUrl, and mobileVideoUrl for a phone held upright. Each
layout plays the other's clip when it has none. Pictures staying from
earlier pages sit out a video page and come back after it. It has no
narration.
Background
A change of backdrop. Set it only on the page where the backdrop changes: every later page keeps it.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
imageUrl |
media URL | null |
yes | The backdrop. null clears the stage to plain. |
||
mobileImageUrl |
media URL |
A tall (9:16) version for a phone held upright, which would otherwise crop the wide one to a narrow slice. Without it, phones show imageUrl. |
|||
label |
string |
at most 200 characters | A short name for the backdrop. | ||
transition |
"fade" | "cut" |
"fade" |
How the new backdrop comes in. |
Picking a different wide backdrop in the editor clears the phone one, since it was made for the old image.
Narration clip
The narration readers hear as the page opens: generated from the page's words, uploaded, or brought along from the game. The app writes it.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
url |
media URL |
yes | The clip. | ||
textHash |
string |
at most 64 characters | A fingerprint of the words the clip was made from, so a page whose words changed shows its narration as out of date. Unset on uploaded clips, which never go out of date. | ||
voiceId |
string |
at most 64 characters | The voice the clip was made in. | ||
durationSeconds |
number |
0 to 3600 | The clip's length in seconds. Auto play waits for it. | ||
generatedAt |
string |
at most 40 characters | When the clip was made. | ||
speechId |
string |
The app's record of the clip. |
Leave it alone and never write one. Changing a page's words makes a generated clip out of date; the editor marks it and can make it again.
Speakers and the cast
Cast speaker
A line said by a member of the cast. The name, role, voice and art all come from the member, so changing the member changes every line they say.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
type |
"cast" |
yes | Always "cast". |
||
castId |
string |
yes | at most 64 characters | The id of the cast member saying the line. | |
expressionId |
string |
at most 64 characters | The id of the expression the member wears on this line. Unset, they wear their base art. | ||
position |
"left" | "center" | "right" |
Left, centre or right of the stage. x wins over it. |
|||
x |
number |
0 to 100 | The cutout's centre, as a percentage of the stage width. Wins over position. |
||
y |
number |
-40 to 40 | A lift above where the cutout rests, as a percentage of the stage height. 0 rests. | ||
scale |
number |
0.4 to 1.8 | The cutout's size: 1 is the normal height. | ||
mobile |
{ position?, x?, y?, scale? } |
The spot on a phone held upright, field by field (position, x, y, scale). Unset fields follow the desktop spot. |
|||
showStandee |
boolean |
true |
Whether the speaker's cutout stands on the stage. | ||
showPortrait |
boolean |
true |
Whether the speaker's portrait shows in the text box. |
Set showStandee or showPortrait to false to hide the cutout or the
portrait on one line. The placement fields (position, x, y,
scale, mobile) place the speaker on this page only; leave them out to
stand them on their default spot.
Custom speaker
A one-off speaker written on the line itself, with its own name and art. It never joins the cast, even when a member has the same name.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
type |
"custom" |
yes | Always "custom". |
||
name |
string |
yes | at most 120 characters | The name shown on the line. | |
role |
"gm" | "player" | "character" |
gm for the narrator, player or character for anyone else. |
|||
imageUrl |
media URL |
The portrait shown in the text box. | |||
cutoutUrl |
media URL |
A transparent cutout that stands on the stage. | |||
position |
"left" | "center" | "right" |
Left, centre or right of the stage. x wins over it. |
|||
x |
number |
0 to 100 | The cutout's centre, as a percentage of the stage width. Wins over position. |
||
y |
number |
-40 to 40 | A lift above where the cutout rests, as a percentage of the stage height. 0 rests. | ||
scale |
number |
0.4 to 1.8 | The cutout's size: 1 is the normal height. | ||
mobile |
{ position?, x?, y?, scale? } |
The spot on a phone held upright, field by field (position, x, y, scale). Unset fields follow the desktop spot. |
|||
showStandee |
boolean |
true |
Whether the speaker's cutout stands on the stage. | ||
showPortrait |
boolean |
true |
Whether the speaker's portrait shows in the text box. |
Use it for someone who speaks once. Anyone who speaks twice belongs in the cast, so their art and voice live in one place.
Placement
Where a cutout stands. The fields at the top are the wide stage's (a computer, a tablet, a phone held sideways); mobile holds a phone held upright's. Every field is optional: an unset one follows the layer below.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
position |
"left" | "center" | "right" |
Left, centre or right of the stage. x wins over it. |
|||
x |
number |
0 to 100 | The cutout's centre, as a percentage of the stage width. Wins over position. |
||
y |
number |
-40 to 40 | A lift above where the cutout rests, as a percentage of the stage height. 0 rests. | ||
scale |
number |
0.4 to 1.8 | The cutout's size: 1 is the normal height. | ||
mobile |
{ position?, x?, y?, scale? } |
The spot on a phone held upright, field by field (position, x, y, scale). Unset fields follow the desktop spot. |
On a phone held upright the left and right presets hug the edges of a
narrow stage. A mobile.x near 35 or 65 and a scale near 0.9 keep faces
on screen.
{ "position": "left", "mobile": { "x": 36, "scale": 0.9 } }
Cast member
One member of the cast: the only place their name, role, voice and art live. Lines point at them by id.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
id |
string |
yes | at most 64 characters | What lines name in castId. |
|
name |
string |
yes | at most 120 characters | The name shown on every line they say. | |
role |
"gm" | "player" | "character" |
gm for the narrator (the Game Master), player or character for everyone else. |
|||
imageUrl |
media URL |
The portrait shown in the text box. | |||
cutoutUrl |
media URL |
A transparent cutout that stands on the stage. | |||
voiceId |
string |
at most 64 characters | The voice their lines are narrated in. | ||
placement |
placement |
Where they stand on every page that doesn't place them. A page can still move them; this is what it moves them from. | |||
expressions |
expression[] |
[] |
at most 32 | The looks their lines can wear. |
A member's role is how the editor labels them: gm reads as the
narrator, player and character as characters. Removing a member in the
editor turns their lines into custom speakers with the same name and art.
Expression
A named look a cast member can wear on a line. It swaps both their portrait and their cutout. A portrait it lacks falls back to the member's own; a cutout it lacks, to a neutral expression's, then the member's own.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
id |
string |
yes | at most 64 characters | What a line names in expressionId to wear it. Lines keep wearing it when it is renamed. |
|
name |
string |
yes | at most 40 characters | What the look is: angry, thoughtful, wary. One named neutral is the member at rest. |
|
imageUrl |
media URL |
The portrait with this look. | |||
cutoutUrl |
media URL |
The cutout with this look. |
A line with no expressionId wears the member at rest: their own
portrait (a neutral expression's when they have none), and a neutral
expression's cutout before their own. So give a member a neutral look
only when it is how they should stand on every plain line.
Pictures
Picture
A picture placed on a page: a prop, a note, a sign. It belongs to its page alone unless it has a stay. The frame at the top is the wide stage's; mobile changes any of it for a phone held upright.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
id |
string |
yes | at most 64 characters | Unique on its page. A later page placing a picture with the same id takes it over from there. | |
url |
media URL |
yes | The image. | ||
alt |
string |
at most 200 characters | Describes the picture for readers who can't see it. | ||
layer |
"front" | "back" |
"front" |
In front of the speaker's cutout, or behind it. | ||
flipX |
boolean |
Mirrored left to right, in both layouts. | |||
flipY |
boolean |
Upside down, in both layouts. | |||
opacity |
number |
0.1 to 1 | How solid it is, in both layouts: 1 (or unset) is solid, lower lets the backdrop show through. | ||
stay |
"scene" | { throughPageId } |
Keeps the picture on the pages after its own, exactly where it is: "scene" until the backdrop changes, or { "throughPageId": "<page id>" } through that page. Unset, it is on its own page only. |
|||
x |
number |
yes | -50 to 150 | The centre, as a percentage of the stage width. | |
y |
number |
yes | -50 to 150 | The centre, as a percentage of the stage height. | |
width |
number |
yes | 1 to 300 | The width, as a percentage of the stage width. The height follows from aspectRatio. |
|
aspectRatio |
number |
yes | 0.05 to 20 | Width divided by height (1.5 for 3:2). Changing it squashes or stretches the picture. | |
rotation |
number |
0 |
-180 to 180 | The turn, in degrees clockwise. | |
mobile |
{ x?, y?, width?, aspectRatio?, rotation? } |
The frame on a phone held upright, field by field (x, y, width, aspectRatio, rotation). Unset fields follow the wide stage's. |
A page's own pictures are drawn back to front; pictures staying from
earlier pages are drawn behind them. Place a prop that stays through a
conversation once, with a stay, rather than copying it onto every page.
Picture change
Changes how a picture staying from an earlier page looks from this page on: its size, shape, turn, fade, flips or layer, never its place. It lasts until another page changes the same thing.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
imageId |
string |
yes | at most 64 characters | The id of the picture staying from an earlier page that this page changes. | |
onlyHere |
boolean |
The change is this page's alone: the next page looks as the pages before left it. | |||
width |
number |
1 to 300 | The width, as a percentage of the stage width. The height follows from aspectRatio. |
||
aspectRatio |
number |
0.05 to 20 | Width divided by height (1.5 for 3:2). Changing it squashes or stretches the picture. | ||
rotation |
number |
-180 to 180 | The turn, in degrees clockwise. | ||
opacity |
number |
0.1 to 1 | How solid it is: 1 is solid. | ||
flipX |
boolean |
Mirrored left to right. | |||
flipY |
boolean |
Upside down. | |||
layer |
"front" | "back" |
In front of the speaker's cutout, or behind it. | |||
mobile |
{ width?, aspectRatio?, rotation? } |
The phone layout's width, aspectRatio and rotation. |
The change applies to a picture kept on with stay; for any other picture
it does nothing. One change per picture on a page. A different image is a
new picture, not a change.
{ "imageId": "drowned-lantern", "width": 24, "onlyHere": true }
Chapters, music and settings
Chapter
A named part of the story. The first chapter must start on the first page.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
id |
string |
yes | at most 64 characters | Unique among the chapters. | |
title |
string |
yes | at most 120 characters | The chapter's name, shown in the reader's chapter list. | |
startPageId |
string |
yes | at most 64 characters | The page it starts on. It runs until the next chapter starts. |
Music cue
A track that plays over a run of pages. Where cues overlap, the one that started latest plays.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
id |
string |
yes | at most 64 characters | Unique among the cues. | |
title |
string |
"" |
at most 160 characters | The track's name. | |
url |
media URL |
yes | The track. | ||
startPageId |
string |
yes | at most 64 characters | The page it starts playing on. | |
endPageId |
string | null |
null |
at most 64 characters | The last page it plays on. null plays until the next cue starts or the story ends. |
|
volume |
number |
0.6 |
0 to 1 | How loud, from 0 to 1. |
Use tracks from the studio.
Assets
The story's cast, and the backdrops and tracks the editor offers to pick from.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
backgrounds |
saved backdrop[] |
[] |
at most 500 | Backdrops the editor offers when the scene changes. | |
speakers |
cast member[] |
[] |
at most 500 | The cast. | |
music |
saved track[] |
[] |
at most 500 | Tracks the editor offers for music. |
Keep the backdrops and tracks a story uses here, so they can be picked again in the editor.
Saved backdrop
A backdrop saved for the editor's scene picker. Pages don't point at it: a page's backdrop holds its own url.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
id |
string |
yes | at most 64 characters | Unique among the saved backdrops. | |
url |
media URL |
yes | The image. | ||
label |
string |
at most 200 characters | A short name for it. |
Saved track
A track saved for the editor's music picker. Cues don't point at it: a cue holds its own url.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
id |
string |
yes | at most 64 characters | Unique among the saved tracks. | |
title |
string |
yes | at most 160 characters | The track's name. | |
url |
media URL |
yes | The track. |
Settings
Settings for the whole story.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
textReveal |
"word" | "instant" |
"word" |
How text appears: word by word, or all at once. | ||
narration |
narration settings |
How the story is read aloud. It is set in the app. |
Narration settings
How the story is read aloud. It is set in the app.
| Field | Type | Required | Default | Limits | What it is |
|---|---|---|---|---|---|
voiceId |
string |
at most 64 characters | The narrator's voice, also used by any speaker without a voice of their own. | ||
voices |
"cast" | "single" |
"cast" |
cast reads each line in its speaker's own voice, single reads everything in the narrator's. |
The narrator's voice also reads every custom speaker's lines.