Craft

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 stay keeps it on. A later page changes how a staying picture looks with imageChanges, 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 mobile spot, then the member's mobile default, 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.