Write a storyboard

From an empty file to a storyboard that validates, draws and embeds, in four steps.

1. A cast

A cast says who can appear and what they look like. Two characters are enough:

{
  "what": "The cast of my first storyboard.",
  "characters": [
    { "id": "rae", "name": "Rae", "kind": "human", "pronouns": "they/them", "role": "the one asking",
      "look": { "skin": "#d8a47f", "hair": "curly", "hairColour": "#3b2a20", "shirt": "#2563eb", "trousers": "#1f2937", "accessory": "glasses" } },
    { "id": "bot", "name": "Bot", "kind": "agent", "pronouns": "it/its", "role": "the one answering", "look": { "colour": "#0f766e" } }
  ]
}

The other fields a character can carry (stands_for, personality, wants, fears, line) are shown on a series' shelf and model sheet; the drawing reads only kind and look. Hair is short, long, curly, bun, beanie or bald; the accessory is glasses, headphones, lanyard or none.

2. A storyboard

{
  "slug": "my-first-storyboard",
  "title": "My first storyboard",
  "subtitle": "Three panels.",
  "status": "draft",
  "by": "you, today",
  "scenes": [
    { "kind": "cover", "title": "My first storyboard", "subtitle": "Three panels.",
      "cast": [ { "who": "rae", "pose": "wave", "mood": "happy" }, { "who": "bot", "pose": "wave", "mood": "happy" } ] },
    { "kind": "scene", "setting": "office", "caption": "A question",
      "cast": [ { "who": "rae", "x": 0.25, "pose": "think", "mood": "thinking", "says": "Is a panel really just JSON?" },
                { "who": "bot", "x": 0.75, "pose": "point", "mood": "happy", "says": "Every stroke of it.", "flip": true } ],
      "props": [ { "kind": "laptop", "x": 0.5, "y": 760, "scale": 1.2 } ] },
    { "kind": "punchline", "setting": "none", "punchline": "Change a line, redraw the panel.",
      "cast": [ { "who": "rae", "x": 0.2, "pose": "arms-up", "mood": "excited" } ] }
  ]
}

What the numbers mean: a panel is 1600 by 1000, the floor is at 900, x is 0 to 1 across the panel, a prop's y is in panel units (the line it stands on). flip turns a character to face left. max is the bubble's wrap width in characters (default 24); lift raises a bubble that would collide with another.

3. Validate it

formats.js runs the same checks every site's build does, in Node or a browser:

const F = require('./formats.js');            // from https://api.storyboards.sgit.ai/v0/v0.1/v0.1.0/formats.js
const errors = F.validate(storyboard, cast);   // [] when good
// a storyboard using the security props: F.validate(storyboard, cast, { props: F.PACKS.security })

An unknown character, kind, pose, mood, setting or prop is an error with the panel number in it. So is an evidence panel with neither a quote nor bars, a cover with no title, or a graph edge naming a node that does not exist.

4. See it, and put it on a page

Put the two in one bundle, { "storyboard": ..., "cast": ..., "packs": [] }, serve it anywhere that sends access-control-allow-origin (GitHub Pages does), and:

<script src="https://api.storyboards.sgit.ai/v0/v0.1/v0.1.0/embed.js" defer></script>
<sg-storyboard src="https://example.org/my-first-storyboard.bundle.json"></sg-storyboard>

The markdown script and the graph come from the same file: F.toMarkdown(storyboard, cast) and F.toGraph(storyboard, cast). To see every kind, setting and prop drawn before you pick one, open the gallery.

The house rules the origin sites follow

They are not enforced by the kit, but they are why the storyboards on storyboards.sgit.ai can be trusted: a line a character says is the storyboard's own words and the panel says so ("not_a_quote": true); an evidence panel quotes its source word for word; note says what the panel is for; characters use the pronouns their cast file gives.