Skip to content

Format Reference

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.

KeyTypeMeaning
versionstringThe format version of the file, such as "1.12". See Versions and Compatibility.
minVersionstringThe oldest format version that reads this file completely.
exportedAttimeWhen the file was written.
savedByobject, optionalThe Throughline installation that wrote the file: { "id", "name"? }, where name is the writer’s name.
guideobjectRules and lookup maps for software and AI models. See The guide block.
storyOrderarray of idsEvery Beat id in story order.
projectobjectSee Project.
beatsarraySee Beats.
charactersarraySee Characters.
worldsarrayThe Settings. See Settings.
structuresarraySee Structure Cards.
sparksarraySee Sparks.
arcsarraySee Arcs.
relationshipsarraySee Relationships.
recycledItemsarraySee Recycling bin.

Throughline writes the guide fresh with every save and ignores it when it opens a file.

FieldTypeMeaning
aboutstringOne paragraph on what the file is.
rulesarray of stringsThe Story Model Rules.
legacyFieldsIgnorearray of stringsFields from older versions to ignore.
characterNamesobjectCharacter id to name.
beatTitlesobjectBeat id to title, in story order.
beatNumbersobjectBeat id to Beat number, counting from 1.
FieldTypeMeaning
titlestringThe project title.
loglinestringThe logline. Can be empty.
editorModestring, optional"screenplay" or "rich". Missing means "rich".
screenplayLanguagestring, optional"en" or "de". Missing means "en". Decides how Throughline prints scene headings and script terms.
authorName, creditLine, sourceInfostring, optionalThe title page: author, credit line ("Written by") and source ("Based on the novel by …").
authorCompany, authorAddress, authorCity, authorCountry, authorEmail, authorPhonestring, optionalContact details on the title page.
dialogueNumbering, sceneNumberingobject, optional{ "enabled", "nextNumber" }, when the writer numbers dialogue or scenes.
peoplearray, optionalThe people Beats can be assigned to: { "id", "name", "placeholder"?, "claimedBy"? }.
replacementsarray, optionalA history of Replace All actions, oldest first: { "find", "replace", "options", "by", "at" }.

The Beat editor: title, summary, two cast avatars, the Setting "ROYAL BEDCHAMBER", INT selected, the time of day "NIGHT", and the status "Done"The Beat editor: title, summary, two cast avatars, the Setting "ROYAL BEDCHAMBER", INT selected, the time of day "NIGHT", and the status "Done"

The Beat editor shows title, summary, chips, sleeveId, intExt, timeOfDay and status.

FieldTypeMeaning
titlestringThe Beat title.
summarystring, optionalA short summary.
contentJsonobject, optionalThe script. See Read the script.
contentstringA plain-text copy of the script, for search and previews.
statusstring"draft", "done" or "no-print" (“Don’t Print”: left out of most exports and off every Arc).
chipsarrayThe cast: { "type": "character", "id" } per Character.
sleeveIdid or nullThe Beat’s Setting.
intExtstring, optional"INT", "EXT" or "INT/EXT".
timeOfDaystring, optionalFree text for the scene heading, such as "NIGHT".
sceneNumberstring, optionalThe printed scene number, such as "42A". Not the Beat number.
stackedOnid, optionalThe Beat or Structure Card this Beat is stacked on.
assignedToid, optionalAn entry in project.people. Missing means nobody.

The Character editor: name, color, summary, Want, Need, Flaw and NotesThe Character editor: name, color, summary, Want, Need, Flaw and Notes

FieldTypeMeaning
namestringThe name.
colorstringThe color.
summarystringWho the Character is. Can be empty.
wantstringWhat they want. Can be empty.
needstringWhat they need. Can be empty.
flawstringThe flaw in their way. Can be empty.
notesstringFree notes. Can be empty.
constellationobject, optionalTheir place on the Constellation: { "x", "y", "overrides"? }, where overrides are { "beatId", "x", "y" } positions at single Beats.
FieldTypeMeaning
titlestringThe location. It’s the middle part of the scene heading.
colorstringThe color.
descriptionstringThe description. Can be empty.
stackedOnid, optionalThe Setting this one is stacked on, such as the house a room belongs to.
FieldTypeMeaning
titlestringThe title, such as "Inciting Incident".
guidancestringWhat this part of the story has to do.
colorstringThe color.

The Beats stacked on a Structure Card fulfill it.

FieldTypeMeaning
contentstringThe idea. Its first line is the name of the card it can become.
FieldTypeMeaning
namestring, optionalThe plotline. Empty means “Fortune” on the default Arc and “Unnamed” on others.
colorstring, optionalThe color.
posPole, negPolestring, optionalThe poles at charge +1 and -1. Empty means “good fortune” and “bad fortune”.
isDefaultboolean, optionaltrue for the whole-story Arc, which contains every Beat.
beatIdsarray of ids, optionalThe member Beats.
pointsarray, 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.
shapeIdsarray of strings, optionalThe Story Shapes the writer compares this Arc with, such as "man-in-hole".
shapeOverridesobject, optionalThe writer’s edited Story Shape curves. See Story Model Rules.

There’s one relationship per pair of Characters.

FieldTypeMeaning
aId, bIdidThe two Characters. aId sorts before bId.
aToBstringHow aId feels about bId, such as "distrusts". Can be empty.
bToAstringHow bId feels about aId. Can be empty.
startBeatIdid, optionalThe Beat where the relationship starts. Missing means from the beginning.
overridesarray, optionalChanges 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.

FieldTypeMeaning
typestring"beat", "character", "world" or "structure".
namestringThe card’s name when it was deleted.
deletedAttimeWhen it was deleted.
dataobjectThe deleted card. Its id is data.id.
shapeRefsobject, optionalA deleted Beat’s Arc and Constellation data, kept for a restore.