These tables describe format version 1.12. A file can contain more fields than they list, so ignore any field you don’t know. Fields marked optional can be missing.
Every card (Beat, Character, Setting, Structure Card, Spark, Arc, relationship) has an id, a fixed type and a created time in ISO 8601, and most also have a modified time. Ids are opaque strings. Colors are hex strings such as "#d4a755". The fields sequence, stackedOn and stackOrder are ordering keys: read the order from storyOrder instead, and read every other array in the order it’s written.
| Key | Type | Meaning |
|---|
version | string | The format version of the file, such as "1.12". See Versions and Compatibility. |
minVersion | string | The oldest format version that reads this file completely. |
exportedAt | time | When the file was written. |
savedBy | object, optional | The Throughline installation that wrote the file: { "id", "name"? }, where name is the writer’s name. |
guide | object | Rules and lookup maps for software and AI models. See The guide block. |
storyOrder | array of ids | Every Beat id in story order. |
project | object | See Project. |
beats | array | See Beats. |
characters | array | See Characters. |
worlds | array | The Settings. See Settings. |
structures | array | See Structure Cards. |
sparks | array | See Sparks. |
arcs | array | See Arcs. |
relationships | array | See Relationships. |
recycledItems | array | See Recycling bin. |
Throughline writes the guide fresh with every save and ignores it when it opens a file.
| Field | Type | Meaning |
|---|
about | string | One paragraph on what the file is. |
rules | array of strings | The Story Model Rules. |
legacyFieldsIgnore | array of strings | Fields from older versions to ignore. |
characterNames | object | Character id to name. |
beatTitles | object | Beat id to title, in story order. |
beatNumbers | object | Beat id to Beat number, counting from 1. |
| Field | Type | Meaning |
|---|
title | string | The project title. |
logline | string | The logline. Can be empty. |
editorMode | string, optional | "screenplay" or "rich". Missing means "rich". |
screenplayLanguage | string, optional | "en" or "de". Missing means "en". Decides how Throughline prints scene headings and script terms. |
authorName, creditLine, sourceInfo | string, optional | The title page: author, credit line ("Written by") and source ("Based on the novel by …"). |
authorCompany, authorAddress, authorCity, authorCountry, authorEmail, authorPhone | string, optional | Contact details on the title page. |
dialogueNumbering, sceneNumbering | object, optional | { "enabled", "nextNumber" }, when the writer numbers dialogue or scenes. |
people | array, optional | The people Beats can be assigned to: { "id", "name", "placeholder"?, "claimedBy"? }. |
replacements | array, optional | A history of Replace All actions, oldest first: { "find", "replace", "options", "by", "at" }. |


The Beat editor shows title, summary, chips, sleeveId, intExt, timeOfDay and status.
| Field | Type | Meaning |
|---|
title | string | The Beat title. |
summary | string, optional | A short summary. |
contentJson | object, optional | The script. See Read the script. |
content | string | A plain-text copy of the script, for search and previews. |
status | string | "draft", "done" or "no-print" (“Don’t Print”: left out of most exports and off every Arc). |
chips | array | The cast: { "type": "character", "id" } per Character. |
sleeveId | id or null | The Beat’s Setting. |
intExt | string, optional | "INT", "EXT" or "INT/EXT". |
timeOfDay | string, optional | Free text for the scene heading, such as "NIGHT". |
sceneNumber | string, optional | The printed scene number, such as "42A". Not the Beat number. |
stackedOn | id, optional | The Beat or Structure Card this Beat is stacked on. |
assignedTo | id, optional | An entry in project.people. Missing means nobody. |


| Field | Type | Meaning |
|---|
name | string | The name. |
color | string | The color. |
summary | string | Who the Character is. Can be empty. |
want | string | What they want. Can be empty. |
need | string | What they need. Can be empty. |
flaw | string | The flaw in their way. Can be empty. |
notes | string | Free notes. Can be empty. |
constellation | object, optional | Their place on the Constellation: { "x", "y", "overrides"? }, where overrides are { "beatId", "x", "y" } positions at single Beats. |
| Field | Type | Meaning |
|---|
title | string | The location. It’s the middle part of the scene heading. |
color | string | The color. |
description | string | The description. Can be empty. |
stackedOn | id, optional | The Setting this one is stacked on, such as the house a room belongs to. |
| Field | Type | Meaning |
|---|
title | string | The title, such as "Inciting Incident". |
guidance | string | What this part of the story has to do. |
color | string | The color. |
The Beats stacked on a Structure Card fulfill it.
| Field | Type | Meaning |
|---|
content | string | The idea. Its first line is the name of the card it can become. |
| Field | Type | Meaning |
|---|
name | string, optional | The plotline. Empty means “Fortune” on the default Arc and “Unnamed” on others. |
color | string, optional | The color. |
posPole, negPole | string, optional | The poles at charge +1 and -1. Empty means “good fortune” and “bad fortune”. |
isDefault | boolean, optional | true for the whole-story Arc, which contains every Beat. |
beatIds | array of ids, optional | The member Beats. |
points | array, optional | { "beatId", "charge", "x"?, "width"? } per Beat. charge runs from -1 to +1, and x and width place the card on the timeline. Skip entries for Beats that aren’t members. |
shapeIds | array of strings, optional | The Story Shapes the writer compares this Arc with, such as "man-in-hole". |
shapeOverrides | object, optional | The writer’s edited Story Shape curves. See Story Model Rules. |
There’s one relationship per pair of Characters.
| Field | Type | Meaning |
|---|
aId, bId | id | The two Characters. aId sorts before bId. |
aToB | string | How aId feels about bId, such as "distrusts". Can be empty. |
bToA | string | How bId feels about aId. Can be empty. |
startBeatId | id, optional | The Beat where the relationship starts. Missing means from the beginning. |
overrides | array, optional | Changes at single Beats: { "beatId", "aToB"?, "bToA"?, "dissolved"? }. See Relationships at a Beat. |
Deleted cards, kept so the writer can restore them. They aren’t part of the story.
| Field | Type | Meaning |
|---|
type | string | "beat", "character", "world" or "structure". |
name | string | The card’s name when it was deleted. |
deletedAt | time | When it was deleted. |
data | object | The deleted card. Its id is data.id. |
shapeRefs | object, optional | A deleted Beat’s Arc and Constellation data, kept for a restore. |