Skip to content

The shards

A project is made of nine kinds of file. Every one is JSON5 with trailing commas, and every expression is stored as plain source text, never as a syntax tree. Eight of them are yours. The ninth, the installation contract, is written by a venue’s server.

File Name Holds
project <name>.storyletproj settings, host scope (@world, …) and @story declarations, coverage drivers, export config
project map map.storyletmap, at the root the project map: its zone group, each zone’s outline, the zone properties, the pictures and the frames
box box.storyletbox the card template, @box properties, the ranking toggle, whether the box is timed, and whether it uses the project map
tags tags.storylettags the box’s own tag groups: their tags and each tag’s properties
hands hands.storylethands hand templates and hands
deck <name>.storyletdeck the cards, and the deck’s own gate and @deck properties
view view.storyletview the canvases: where cards sit on a deck’s node canvas, and the box’s colour on the map
map map.storyletmap, in a box where the box’s hands stand on the project map, and nothing else
notes notes.storyletnotes comment threads: one per box, and one at the root for the project, its map and its zones
contract contracts/<installation>.storyletcontract what a venue this project is installed at depends on. Not yours: the server writes it

The two map.storyletmap files are told apart by their schema tag: storylets/projectmap@0 at the root, storylets/map@0 in a box. The map’s pictures live in an assets/ folder at the root of the project.

A project folder: the .storyletproj file at the root, beside the project map's map.storyletmap, the project's notes.storyletnotes and an assets folder for the map's pictures; then one folder per box containing box.storyletbox, tags.storylettags, hands.storylethands, an optional view.storyletview and map.storyletmap, and a decks folder holding one .storyletdeck file per deck. Beside the project, a storylet-dist folder holds the compiled .storyletsc bundle. the-village.storylets/ the project: a folder, opened as one document the-village.storyletproj settings, @world and @story, export config map.storyletmap the project map: zones, outlines, pictures notes.storyletnotes comments on the project and its map assets/ the map's pictures village/ one folder per box box.storyletbox card template, @box, ranking, uses the map tags.storylettags the box's own tag groups hands.storylethands hand templates and hands view.storyletview card positions and the box's colour map.storyletmap where this box's hands stand on the map decks/ arrival.storyletdeck one file per deck: the cards live inside ../storylet-dist/the-village.storyletsc the compiled bundle your game loads

A deck is one file and a box is one folder, so two people adding decks to the same box add different files and never meet. That’s most of why everyday edits merge on their own, and Version control has the rest.

Positions live apart from content, in two shards of each box’s own, and neither holds anything about what a thing is.

view.storyletview is the one shard you can ignore. It holds where a card sits on a deck’s node canvas, the frames drawn round them, and the box’s colour on the map. Delete the file and you lose a layout and a colour choice, never content. The colour is colour, a number from 0 to 11 naming a slot in the theme’s palette rather than a hex value, so it follows light, dark and the colour themes.

A box’s map.storyletmap holds where its hands stand on the project map. That one is not safe to lose, because the positions leave the project: they ship in the bundle when you export with the map, and they’re where a screen or a kiosk stands. Which zone a hand is in isn’t recorded here, since that’s the hand’s own tag binding, in hands.storylethands.

Because of that split, two people arranging the same canvas can only produce a position conflict, never a content conflict.

The root map.storyletmap is different: the zones are content, because cards and hands use them. See The project map below.

Before October 2026 a map belonged to one box, held in its tags shard with the pictures in the box’s own assets/ folder, and boxes that shared a map each kept a copy. Such a project doesn’t compile until it’s moved on. Earlier still, before September 2026, the positions lived inside view.storyletview; those are no longer read, and storyletengine format drops them. Storyletter offers the upgrade when you open a project with per-box maps, and storyletengine format does the same from the command line (see Projects made before the project map).

Inside a box folder the file names are fixed: box, tags, hands, view, map and notes, with the decks in decks/.

One per project, at the root. It holds everything that isn’t specific to a box.

{
schema: "storylets/project@0",
project: {
id: "proj_village",
name: "The Hamlet",
version: "0.1.0",
},
coverage: {
drivers: {
"@world.time_of_day": {
cadence: "sometimes",
kind: "recurring",
values: [
"night",
],
},
},
},
export: {
bundle: "../storylet-dist/the-hamlet.storyletsc",
metadata: "full",
},
scopeRegistry: {
scopes: [
{
declarations: [
{
default: "day",
name: "time_of_day",
type: "enum",
values: [
"day",
"night",
],
},
],
token: "world",
},
],
version: 1,
},
settings: {
playAdvancesTurns: 1,
},
story: {
properties: [
{
default: "arrival",
name: "act",
stages: [
"arrival",
"act-1",
"act-2",
],
type: "quality",
},
],
},
templates: {},
}

scopeRegistry declares your game’s own state, its host scopes, in the shape Patter uses: each scope a token (world, or another such as player, which content reads as @world.x and @player.x) and its declarations. A scope may carry writable: false, which makes every property in it read-only to the story unless the property says otherwise. A scope with no declarations is opaque: any name, unchecked. A token can’t be one of the engine’s own (story, box, deck, hand) or another engine’s. Leave the block out when the game has none. A project written before host scopes has a world block instead (world: { properties: [...] }), which still loads and compiles as the scope world; storyletengine format moves it into scopeRegistry. story declares the story’s own globals.

A declaration anywhere except a host scope may also carry shared, the sharing axis for projects that run several flows. true is one value across every flow, and false is a copy per flow. Absent means the scope default (@story shared; box, deck, hand, and tag properties per-flow). A host scope takes no flag, because it is the game’s own state and always shared, and the compiler refuses the flag there.

Beside it, and independent of it, durable says the value outlives a run, meaning the installation’s memory when it’s also shared, and one player’s pocket when it isn’t. The engine never reads it. Whoever runs the engine lifts and restores durable values at a run boundary. A host scope takes no flag here either, and for the same reason.

settings.play is "solo", "shared", or "venue" (absent means "solo"). It sets the play ladder, which decides how much of itself Storyletter shows. It is authoring configuration and is never compiled into the bundle. A project that contains more than its rung shows is a validation warning naming the rung.

export names where the compiled bundle goes (bundle) and whether author metadata rides along (metadata: "full") or is stripped for size ("stripped"). Two optional switches sit beside them, both off unless set: map: true carries the project map’s drawing in the bundle (see the bundle), and packAssets: true makes a .storyletpack carry the map’s pictures (see pack).

settings.playAdvancesTurns is the default number of turns a play advances its box’s clock. A host can override it per call.

coverage.drivers configures the coverage harness, keyed by property reference. Only a host scope’s properties (@world.x, @player.x) are drivable, because every other scope is written by play itself. A driver’s kind is initial (rolled once per playthrough) or recurring (re-rolled per turn at its cadence), and values is the pool it draws from. This block never reaches the bundle.

templates is the configuration bag for templates of play, keyed by template name. The core validates only what it knows about.

gameScopes (optional, usually absent) names the game’s shared scopes folder, relative to the folder holding the project file: gameScopes: "../../shared/game-scopes". You rarely need it. Every tool finds a game-scopes/ folder on its own by looking in the project folder and then each folder above it, stopping at the root of your repository, so this is only for a folder that search wouldn’t reach. A path that doesn’t exist is an error. Storyletter writes it for you when you share scopes into a folder outside the search. It never reaches the bundle.

patter (optional) names the Patter project this one is paired with, relative to the folder holding the project file: patter: "../story/the-hamlet.patter". With it, validate checks each card against the scene of the same name in that project’s published bundle. A path that doesn’t exist is a warning, not an error, since a writer may have the cards without the dialogue. It never reaches the bundle.

patterBoxes (optional, beside patter) lists, by box id, the boxes your game performs through the paired Patter project. With it, validate checks only those boxes, and also reports a card in them that has no scene. It never reaches the bundle.

validation.warnUnreadWrites (optional) also warns when an outcome writes state that nothing reads. It’s off unless set, because content is often written ahead of the cards that will read it. The other half, a condition reading state nothing writes, always warns. It never reaches the bundle.

Where the game shares its scopes and its game.scopes.json declares @world (or another scope the project declares), the project’s declarations of it in scopeRegistry are a synced copy of those. Storyletter rewrites the copy from the shared file whenever it saves, so the project still compiles when it’s packed or checked out on its own. The shared file wins, and validate warns if the two ever differ.

The card shape and the ranking toggle. It’s small and changes rarely. In a team this file is usually owned by the lead, because changing a field’s name or type reshapes every card in the box.

{
schema: "storylets/box@0",
box: {
fields: [
{
default: "",
name: "scene",
type: "text",
},
],
gameId: "village",
id: "b_village",
outcomeFields: [
{
default: "",
name: "after",
type: "text",
},
],
properties: [],
purpose: "Every story beat in and around the village.",
ranking: {
specificity: true,
},
title: "Village",
},
}

fields is the card template, what every card in this box carries. Fields are data for your game (a scene id, an animation reference, a text key). The engine never interprets them and expressions can’t read them. outcomeFields is the same again for outcomes, what an outcome in this box may carry, declared the same way, for the line your game shows after a press without spending a card on it. Leave it out when you have none.

A field’s type is one of text, multiline, number, boolean, enum, flags and quality, the list Patter’s game data uses (string is read as text). A field’s default is optional: left out, the type’s own holds (false, 0, "", the first enum value, no flags, the first stage), and build writes it onto the declaration in the bundle. One you give must fit its type; an enum field’s may be "", none chosen. An enum or flags field lists its values, and a quality field lists its stages, at least two, in order. A card’s value for a quality field must be one of those stages. The bundle carries the values exactly as the cards wrote them, so a field a card leaves out arrives missing; the field helpers fill it in from the declaration’s default. properties is the @box scope. ranking.specificity is the one per-box ranking toggle.

An optional turn says your game moves this box’s clock, so plays in it advance nothing:

turn: {}, // the game ticks it: a calendar, a day at a time
turn: { seconds: 60 }, // or a timed box: one turn a minute of the run

With seconds, a whole number of seconds, one or more, this is a timed box: a turn is a length of time, and a card’s redraw: 30 reads as thirty minutes. See Dealing. Leave turn out and a turn is a play, which is the ordinary box.

An optional cardDefaults is the Card template’s dealing rules: what a card in this box takes when it sets none of its own (redraw, weight, inOneHand, acrossHands). It’s live, so changing it changes every card that hasn’t set its own.

usesMap: true puts the box on the project map. Its hands may then be bound to the map’s zones and its cards filed to them. Leave it out and the box can’t name the map at all; a reference to it from a box that isn’t on the map is an error.

A box’s own tag groups and their tags. Tags are declared values, so a typo is a validation error, not a card that never deals. A tag may carry properties of its own.

{
schema: "storylets/tags@0",
groups: [
{
gameId: "area",
id: "d_zone",
purpose: "Where in the town.",
tags: [
{
gameId: "docks",
id: "v_docks",
properties: [
{
default: 0,
name: "danger",
type: "number",
},
],
},
{
gameId: "market",
id: "v_market",
},
],
},
],
}

A group’s name is unique within its box, not project-wide, so two boxes can each declare a zone group. Tag names are unique within their group, and unique within their box as well, because a tag’s properties are addressed as value.<box>/<tag>.<name>, which qualifies by box and no further, so two groups in one box that both name a tag docks leave the second one with no address of its own. Rename one of them, or pin a distinct gameId on one. Validation warns about it in this release and refuses it in the next. Ids are unique across the whole project.

A group may also carry boundBy, a @story or @world property reference ("@story.act") whose value names one of the group’s tags by gameId. The engine binds the group to that tag every time a hand is dealt, as if the hand had chosen it, so an axis driven by state, such as an act or a difficulty band, needs no condition on every card. A hand’s own binding wins. The property has to be a string or an enum. required: true turns the group’s wildcard round: a card that names no tag in it is unavailable wherever the group is bound.

The project map’s names are reserved across the whole project. No box may have a group with the map’s group name, or a tag with a zone’s name, because those names mean one thing everywhere, and place can’t name the map’s group. A box’s own group can’t be a map: there’s one map, and it’s in the project map shard.

One file at the root of the project, map.storyletmap, holds the project map. This one is from the Village example, shortened:

{
schema: "storylets/projectmap@0",
group: {
gameId: "zone",
id: "d_0001",
properties: [
{
default: "quiet",
name: "haunting",
stages: [
"quiet",
"restless",
"screaming",
],
type: "quality",
},
],
purpose: "Where in the world a beat belongs.",
tags: [
{
gameId: "lair",
id: "v_0003",
templates: {
spatial: {
polygon: [
{ x: 870, y: -1559 },
{ x: 871, y: -1069 },
{ x: 1754, y: -1067 },
{ x: 1750, y: -1554 },
],
},
},
},
// ... village, forest, mountain, cave
],
templates: {
spatial: {
backgrounds: [
{ file: "lair.jpg", id: "g_bglair", x: 870, y: -1559, width: 884, height: 492 },
// ...
],
map: true,
},
},
},
}

group is the zone group, the same shape as a group in a tags shard. Its tags are the zones, each with its outline under templates.spatial.polygon. Its properties are declared once for every zone, and a zone’s own starting values sit in its values, as on any tag. A zone property is one value for every box on the map; shared still decides whether it’s one value for every flow too. templates.spatial.backgrounds are the pictures behind the map, each naming a file in the project’s assets/ folder. An optional frames list holds the map’s frames, which never reach the bundle.

A box joins the map with usesMap: true in its box shard. Its hands and cards then name the zones by id, exactly as they name a box’s own tags:

// a hand in hands.storylethands
chosen: { d_0001: "v_0004" }, // stands in the village zone
// a card in a deck
tags: { d_0001: ["v_0003"] }, // can come up anywhere in the lair

Each box keeps where its hands stand in its own map.storyletmap, keyed by hand id:

{
schema: "storylets/map@0",
map: {
sites: {
h_000b: { x: 446, y: -803 },
h_000c: { x: 839, y: -25 },
},
},
}

sites is the format’s word for those positions. Only a box on the map ships them: positions left in a box that isn’t on the map are a warning, because they aren’t drawn or shipped.

Comments on the map itself, or on a zone, are kept in the root notes.storyletnotes; a comment on a hand stays in its box’s notes.

Hand templates, and the hands made from them.

{
schema: "storylets/hands@0",
hands: [
{
chosen: {
d_zone: "v_village",
},
gameId: "the-inn",
id: "h_inn",
slots: 2,
template: "t_whats_happening",
title: "The Inn",
},
],
templates: [
{
chooses: [
"d_zone",
],
gameId: "whats-happening",
id: "t_whats_happening",
properties: [],
purpose: "The main lens: which story beat happens at a location now. One hand per location.",
slots: 3,
},
],
}

A template sets bindings (tags fixed for every hand that uses it), chooses (the tag groups each hand fills in for itself), one shared condition, a default slots, and the properties every hand carries. Templates are author-side only, and your game never names one.

A hand is either made from a template (template, plus a chosen entry for every group the template lists in chooses) or written out in full (a rule object with its own bindings, condition and slots). It’s one or the other. A hand made from a template can override only slots; everything else comes from the template.

Every slots, on a template, a rule or a hand, is a whole number from 0 up or "unbounded". A hand’s own slots overrides its template’s or its rule’s, so one hand can hold everything while the others keep the template’s cap. A hand-level "unbounded" needs Storylet Engine 1.1.0 or later.

A hand’s gameId is the name deal is called with from game code, so renaming one is a breaking change beyond the project’s own borders. The merge driver warns when a merge renames one. A hand with no gameId of its own gets one derived from its title.

The scaffolded starter hand shows the written-out form:

{
gameId: "whats-next",
id: "h_w7w0n4vm",
purpose: "The starter hand: deal it to see what could happen now.",
rule: {
bindings: {},
slots: "unbounded",
},
title: "What's next?",
}

A chosen value is normally a tag id. It can instead be a property reference, and then the hand moves with the property. The engine resolves the reference each time the hand is asked and binds the group to the tag the value names.

{
gameId: "the-elder",
id: "h_elder",
template: "t_npcs_you_can_talk_to",
chosen: {
d_zone: "@hand.zone",
},
properties: [
{
default: "village",
name: "zone",
shared: true,
type: "enum",
values: ["village", "forest", "mill"],
},
],
}

Move the Elder with setProperty("hand.the-elder.zone", "forest") and the next deal follows, so forest-tagged cards become available at the Elder’s hand, and village-tagged ones leave it. There is no other verb. A shared: true declaration like the one above makes the move a world fact, so every flow sees the Elder in the forest; leave the flag off and each flow moves its own copy, which is how a party gets a “what is around me” hand that follows them about.

The reference may be @hand.<name> (a property this hand or its template declares), @story.<name>, or @world.<name>. It has to be a string or an enum, because the value has to be able to name a tag. A value that names no tag in the group leaves the group unbound for that hand, which is a wildcard rather than an empty hand, and the deal says so on its trace. A hand written out in full does the same thing with a rule binding. place is the one group this never applies to, because it’s the hand’s own name.

One file per deck. It carries the deck’s own identity, its optional gate condition, its @deck properties, and its cards. It may also carry shared, which makes every card in the pile scarce across flows unless a card says otherwise (one of each in the world, rather than one each per participant). It may also carry durable, which makes every redraw: never card in it stay played past the end of the run.

{
schema: "storylets/deck@0",
deck: {
gameId: "arrival",
id: "k_arrival",
properties: [],
purpose: "A newcomer finds their footing.",
title: "Arrival",
},
cards: [
{
condition: "@act == \"arrival\"",
fields: {
scene: "scn_gate",
},
gameId: "arrive-at-the-gate",
id: "c_arrive",
outcomes: [
{
changes: {
"@story.act": "advance(@story.act)",
},
fields: {
after: "The gate swings shut behind you.",
},
gameId: "step-through",
id: "c_arrive_o",
title: "Step through the gate",
},
],
priority: 10,
purpose: "The road ends at a weathered gate; smoke rises from the Inn beyond.",
redraw: "never",
tags: {
d_zone: [
"v_village",
],
},
title: "Arrive at the Village Gate",
},
],
}

Reading a card top to bottom:

  • condition gates whether the card is available at all. @act is short for @story.act.
  • fields fills in the box’s card template. Here the game reads scene and plays it.
  • priority is the first ranking key. It can be a number or an expression.
  • redraw is the cooldown policy in this box’s own turns: always, never, or a number. Absent, the card takes its box’s Card template default (cardDefaults), or always.
  • weight (absent here, so 1) is how often the card comes up beside cards of equal rank.
  • inOneHand (absent here, so 1) is how many slots of one hand it may fill at once.
  • acrossHands (absent here, so "one") says whether several hands may hold it at once, counted within one playthrough: "one" or "any". It replaces copies, which the compiler refuses, and storyletengine format rewrites as acrossHands. Each of these three, absent, takes the box’s Card template default too.
  • shared makes the card scarce across flows, one goblin in the whole world rather than one each. Absent, it takes its deck’s flag, so the usual place to write it is on a deck whose whole pile is scarce. On the card it’s the override for a single unique card sitting in an ordinary deck. sharedCopies is then how many hands may hold it anywhere, so sharedCopies: 5 is five in the world, one to a customer.
  • durable says this card’s redraw: never spend survives the run, for whoever played it, or for everyone when the card is also shared. Absent, it takes its deck’s flag, exactly as shared does. On any other redraw it means nothing past the run, and the compiler warns.
  • tags maps group ids to tag ids. An absent group is a wildcard, so this card would match any binding of any other group the box declares. Exclusions are written as conditions over @hand, not as negative tags.
  • outcomes are the choices. Each has a changes map from a fully-qualified @scope.name target to an expression, plus an optional condition that gates it. When the box declares outcomeFields, an outcome fills them in a fields map of its own, exactly as the card fills the card template. Here after is the line the game shows once the gate is stepped through. The engine hands it over with the outcome and never reads it. A card may have no outcomes at all, such as a notice, a headline on a screen, or a codex entry, whose whole job is to be shown. Your game plays one with no outcome once it has shown it, so it still counts as played, rests by its redraw and leaves its hand; nothing is written. Such a card may leave the outcomes key out altogether, which reads as an empty list.

The same shape is used everywhere state is declared: @world, @story, @box, @deck, @hand, and on a tag. A tag group can declare properties too, and then every tag in the group has them. The group says what the property is, and each tag carries only its own starting value in values. That’s the shape to reach for when “every zone has a haunting level” is what you mean, and it’s what keeps a zone added later from quietly arriving without one.

Field Notes
name referenced as @scope.name; lower case, unique in its scope
type boolean, number, string, enum, flags or quality (which to use)
default optional: left out, the type’s own holds (false, 0, "", the first enum value, no flags, the first stage), and build writes it into the bundle, so a declared property always has a value. One you give must fit the type
values for enum and flags. On a TAG, values means something else: this tag’s starting values for the properties its group declares
stages for quality: the ladder, in order, lowest first; at least two, each named once, and a default, when given, must be one of them
shared not on a host scope. true is one value across every flow, false a copy per flow; absent takes the scope default
durable not on a host scope. The value outlives a run; the engine never reads it
writable host scopes (@world, …) only. false makes the property read-only to the story: a condition may read it, an outcome that writes it is a compile error. The game still moves it through its resolver. Default: its scope’s writable, else true
purpose author metadata

Card template fields use the same shape. The difference is what they’re for. A property is state the expressions read and write, and a field is data handed to your game.

A project running at a venue (a museum floor, a park, a show) depends on names that live outside it. Stations are bound to particular hands, a scheduler ticks particular timed boxes, a clock drives particular properties, and the crew read particular card fields. Rename one of those and the venue breaks, quietly, after the change has shipped.

So the venue writes down what it depends on, one file per installation, in a contracts/ folder beside the project shard:

contracts/the-park.storyletcontract
{
schema: "storylets/contract@0",
by: "Storylet Server 0.1.0",
boxes: {
street: { turn: 60 }, // the scheduler ticks these
},
fields: [
"prompt", // the crew and the bridges read these
"cue",
],
hands: [
"the-well", // stations are bound to these
"the-forge",
],
installation: "the-park",
properties: [
"world.time_phase", // the clock drives these
"story.visits",
],
revision: 12,
}

Everything in it is by gameId, and a property is written the way listProperties() prints it, with no @. A property may instead be written as { path: "story.visits", type: "number" }, and then a type change is caught as well as a rename. A tag property whose tag name two boxes share carries the box too (value.harbour/docks.danger), which is the address the engine takes for it; the short form there would provision the venue against a name its own engine refuses. A project playing at two venues has two of these files; two files naming the same installation is an error.

storyletengine validate treats a break as an error: a contracted hand that no longer exists, a contracted box whose turn is no longer that many seconds, a contracted property that has gone or changed type, a contracted field no box declares any more. Each one names the venue, so the message says who cares. storyletengine contract show lists what each installation depends on. The contract itself never reaches the compiled bundle. The server does not need its own contract back, it needs the bundle to still honour it.

The server that writes this does not exist yet. Until it does, a project either has no contract at all (which is the normal state, and nothing changes) or one written by hand.

Open source under the MIT licence, made by .