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.
How they sit on disk
Section titled “How they sit on disk”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.
The two arrangement shards
Section titled “The two arrangement shards”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/.
The project shard
Section titled “The project shard”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 box shard
Section titled “The box shard”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 runWith 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.
The tags shard
Section titled “The tags shard”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.
The project map
Section titled “The project map”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.storylethandschosen: { d_0001: "v_0004" }, // stands in the village zone
// a card in a decktags: { d_0001: ["v_0003"] }, // can come up anywhere in the lairEach 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.
The hands shard
Section titled “The hands shard”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 tag group chosen from a property
Section titled “A tag group chosen from a property”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.
A deck shard
Section titled “A deck shard”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:
conditiongates whether the card is available at all.@actis short for@story.act.fieldsfills in the box’s card template. Here the game readssceneand plays it.priorityis the first ranking key. It can be a number or an expression.redrawis 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), oralways.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 replacescopies, which the compiler refuses, andstoryletengine formatrewrites asacrossHands. Each of these three, absent, takes the box’s Card template default too.sharedmakes 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.sharedCopiesis then how many hands may hold it anywhere, sosharedCopies: 5is five in the world, one to a customer.durablesays this card’sredraw: neverspend survives the run, for whoever played it, or for everyone when the card is also shared. Absent, it takes its deck’s flag, exactly asshareddoes. On any other redraw it means nothing past the run, and the compiler warns.tagsmaps 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.outcomesare the choices. Each has achangesmap from a fully-qualified@scope.nametarget to an expression, plus an optionalconditionthat gates it. When the box declaresoutcomeFields, an outcome fills them in afieldsmap of its own, exactly as the card fills the card template. Hereafteris 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 itsredrawand leaves its hand; nothing is written. Such a card may leave theoutcomeskey out altogether, which reads as an empty list.
Property declarations
Section titled “Property declarations”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.
The installation contract
Section titled “The installation contract”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:
{ 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 Ian Thomas.