Your game's state
The story asks questions about your game. Is it night, does the player have the key, how
much gold? The answers live in host scopes: sets of properties your game owns and the
story’s conditions read. @world is the common one, and it’s usually the first thing you wire
up after loading a bundle. A game can declare others beside it, such as @player for the
player’s own state, and everything on this page holds for each of them.
Everything on this page is the same in all four runtimes. Only the spelling changes.
Declaring it
Section titled “Declaring it”Host scopes are declared on the project, in Project Settings: each one a token (world,
player) and its properties, each with a name, a type, and a default. Declaring is the
designer’s half. It tells the editor which names exist, so a
condition can be checked as it’s written and a typo is caught when the bundle is published,
not in your game.
Your game doesn’t declare anything. It fills in what’s already declared.
A game with more than one editing tool (Storyletter and Patterpad, say) keeps its scopes in
one place instead: game.scopes.json in its
shared scopes folder. Storyletter’s
Host scopes settings then edit that file, and each project keeps a synced copy so it still compiles
on its own.
@world.is_night boolean default false@world.gold number default 0@world.chapter string default "one" read-only@player.hp number default 10In the project shard they sit under scopeRegistry, in the same shape Patter uses:
scopeRegistry: { version: 1, scopes: [ { token: "world", declarations: [{ name: "is_night", type: "boolean", default: false }] }, { token: "player", declarations: [{ name: "hp", type: "number", default: 10 }] }, { token: "fx" }, ],}A scope with no declarations is opaque: it takes any name and any value, and nothing
about it is checked. Use one for state you’d rather not list, and declare the rest.
Read-only
Section titled “Read-only”Four things, and they are the same four in Patter, in the same order, so a game running both engines sees one rule:
- Read-only is the story’s promise, declared on the property (
writable: falsein the shard, the Read-only switch in Storyletter), or on the whole scope (writable: falsebeside its token, which a property can still override withwritable: true). A condition can still read@world.chapter; an outcome that sets it is a compile error, so a card cannot move the game’s clock by mistake. - The runtime keeps the promise too. If a bundle somehow carries such a write,
play()refuses it with'@world.chapter' is read-onlyand nothing changes. Your resolver’ssetis never called for a read-only property. - A resolver with no
setmakes the whole of that scope read-only to the story, whatever the declarations say. That is the game’s policy rather than the story’s promise, and both apply. - Your game is never bound by it, resolver or none. The promise is the story’s, not the
game’s.
setProperty("world.chapter", ...)writes, whether you bound a resolver or let the engine keep its stand-in bag, and so do the coverage driver and the CLI’s--set, which exist to move exactly these values. The examiner still shows the property as read-only, because that is what the flag means: read by the story, moved by the game.
There’s no write-only, because a declared property can always be read by the story. If the game holds a value the story shouldn’t see, don’t declare it.
A name that isn’t declared can’t be referenced. The compiler refuses @world.isNight if
nothing declares isNight. Property names are lower case (see the format),
and so are tokens.
Binding it
Section titled “Binding it”Host scopes live on the engine, and every flow sees the same values. They’re the game’s own state, and the game is one thing however many playthroughs run over it. You bind them in one map of token to resolver when you build the engine, so conditions read your live game state directly:
const engine = new Engine(bundle, { hostScopes: { world: { get: (name) => game.world[name], set: (name, value) => { game.world[name] = value; } }, player: { get: (name) => game.player[name] }, },});Bind any of them, or none. A declared scope you leave out, the engine backs itself from the declared defaults, as a property it saves, which is fine for most games. A game running more than one engine registers its scopes once in its registry instead, and hands the registry to each engine (Running it with Patter).
A token is case-sensitive. Binding one the bundle doesn’t declare is reported through
onError as a set-up problem, hostScopes binds "Player", which this bundle doesn't declare: it declares "player", and a scope's token is case-sensitive, and the declared scope is
backed by the engine as if you’d bound nothing. The world option earlier runtimes took has
gone: passing it is reported the same way, and binds nothing.
Writing it from your game
Section titled “Writing it from your game”Before you deal, tell the flow what’s true:
flow.setProperty("world.is_night", true);flow.setProperty("world.gold", 120);flow.setProperty("player.hp", 7);
const dealt = flow.deal("tavern-encounters");The path form is world.is_night, not @world.is_night. The @ belongs to the
expression language a designer writes in; the API takes a plain path. The paths are:
| Path | Reaches |
|---|---|
world.<name> |
your game’s state |
<token>.<name> |
any other host scope, such as player.hp |
story.<name> |
the story’s own global state |
box.<box>.<name> |
a box’s properties |
deck.<deck>.<name> |
a deck’s properties |
hand.<hand>.<name> |
a hand’s properties |
value.<tag>.<name> |
a tag’s own properties, or a zone’s on the project map (see below when two boxes share a tag name) |
The owner is named by the name you gave it. A box, deck, hand, or tag is addressed by the same
gameId you write in a shard and read on a card. So the Elder’s zone is
hand.the-elder.zone, and the docks’ danger is value.docks.danger.
Two boxes may name a tag the same way. Box, deck, and hand names are unique across a
project, but a tag’s name only has to be unique within its group, and a group’s within its
box, so a harbour box and a cellar box can each have a docks. Where that happens, say which
box: value.harbour/docks.danger. The slash sits inside the owner segment, so the address
still has its three parts. You can always write the long form, whether or not you need it. The
short one is refused where it would name two tags at once, and the refusal tells you both
addresses to choose from. A project whose tag names happen to be unique sees none of this.
A zone of the project map has one address, value.<zone>.<name>,
such as value.docks.danger. A zone belongs to the project, not to a box, so it’s one value
whichever box’s hand is dealt there, and there’s no box to name: value.harbour/docks.danger
for a zone is refused, and the refusal gives the address that works. No box’s tag may share
a zone’s name, so the short form always names the zone.
getProperty reads the same paths, and listProperties() returns every declared property
with its path, type, current value and default. That list is what the in-engine
examiners are built from.
When to write it
Section titled “When to write it”Write before you deal. A card’s condition is evaluated at the moment you deal or peek,
against the state as it stands then. Set @world.is_night after dealing and the hand you
already have won’t change; the next deal will.
For the same reason, a dealt card doesn’t carry its outcomes’ availability. Ask
outcomes(card, hand) when you’re about to show them and you get the current answer. A card
can sit in a hand for many turns while your game moves underneath it.
Which way state flows
Section titled “Which way state flows”@world is yours, and the story reads it. An outcome can write it too: “playing this card
makes the player poorer” is a normal thing to want. So treat @world as shared, and read it
back after a play if your game holds its own copy.
If you’d rather the story never touched a value, keep it in your own code and push it in with
setProperty. Nothing forces you to declare state you don’t want written.
Shared or per flow
Section titled “Shared or per flow”Every property is either shared (one value across every flow) or a copy per flow,
set on the declaration with a shared flag, never by a different name. In Storyletter it’s
the Shared tick-box on the property, shown once Play is set to Shared world in
Project Settings, and the row says whose the value is, such as One value for every guest.
or Each guest has their own. The defaults follow the scopes:
| Scope | Default |
|---|---|
@world and every host scope |
always shared (the game owns it, not the player) |
@story |
shared |
| box, deck, hand, tag, and zone properties | a copy per flow |
A zone property is always one value for every box on the map; shared decides only whether
it’s also one value for every flow. A single-flow game never notices any of this. With
several flows, the narrow scopes are where
personal experience lives (this participant’s danger in the docks), while @story and any
property flagged shared is the world every flow moves together. Flows meet only through
shared state. There’s no message-passing between them, and no flow can read another’s copies.
Cards can be shared too. The same word on a deck (or a single card) makes the cards themselves scarce across flows rather than the state they read, so there’s one goblin in the whole world, to whoever finds it first. That’s How a deal is decided.
Durable: state that outlives a run
Section titled “Durable: state that outlives a run”Sharing says whose a value is. durable says how long it lasts. It sits beside shared
on the same declarations, and the two are independent:
| run-scoped (the default) | durable: true |
|
|---|---|---|
| shared | world truth for this run: the act, the well opened | the installation’s memory: trolls defeated since it opened |
| per flow | this visit: my danger in the docks | the player’s pocket: visits, allegiance, what they earned |
durable is a compile error on @world, and on any host scope, for the reason shared is.
A host scope is the game’s own state, and how long the game keeps it is the game’s business.
A card can be durable too, on the deck or on the card, and it means one thing. Its
redraw: never spend survives the run. Only never can (a finite cooldown is an absolute
turn of a box’s clock, and the clock resets with the run), so durable on any other redraw is
a compile warning.
Carrying it to the next run
Section titled “Carrying it to the next run”Each half has one call to take it and one to put it back. Take both before the run ends, and put them back into the next run’s fresh engine:
// At the end of a run.const memory = engine.saveDurable(); // the installation's memory: the shared halfconst pocket = flow.saveDurable(); // one player's pocket: their flow's half
// At the start of the next one.const next = new Engine(bundle);next.loadDurable(memory);const alice = next.openFlow("alice", { durable: pocket });The two halves have the same shape, and it’s plain JSON, so keep them however your game keeps things: the memory beside the installation, a pocket beside its player.
{ "schema": "storylets/durable@1", "content": { "project": "the-village", "version": "1.4.0", "hash": "3f9c2a1b" }, "values": { "hand.the-elder.met": true, "story.visits": 3 }, "spent": ["the-lost-ring"]}values is keyed by the same paths getProperty takes, and spent lists the durable
one-shots that have been played, by the card’s name. A pocket carries only the per-flow half
and a memory only the shared half. Nothing run-scoped goes in either.
A flow opened with its pocket starts as any new flow does, on its own seed with its clocks at
zero, with the pocket’s values in and its spent cards spent. durable can’t be given with
restore, because a restore already carries the flow’s durable values. A half from another
project is refused.
A durable half is meant to cross builds, so putting one back says what didn’t make it.
loadDurable returns the same report loadGame does, and openFlow hands it to
onRestoreReport:
| The half holds | The report lists it in | What happens |
|---|---|---|
| a value at a path this build doesn’t declare durable on that side | droppedProperties |
not written |
| a value its declaration no longer takes | retypedProperties |
the property takes its default |
| no value for a durable declaration | defaultedProperties |
the property takes its default |
| a spend for a card that’s gone, or no longer a durable one-shot | droppedSpent (the memory), droppedCooldowns (a pocket) |
not spent |
A renamed property is a new property with its default and an old value with nowhere to go. The report names the old path, and the value is still in the half you kept, so whether to carry it over by hand is your call.
Saving it
Section titled “Saving it”saveGame() returns the whole run: the shared state once (with anything a shared one-shot has
taken out of the world), then every flow’s own state, turn counters, cooldowns, board contents,
and random stream position. The same run always saves the same text, in every runtime: the
registry’s values are written engine-wide first, then each flow’s in flow order.
loadGame(envelope) restores it, rebuilding every flow, so
re-take your handles with getFlow, never openFlow, which would replace the restored flow
and its dealt hand (see JavaScript, Save and load).
A load is deliberately forgiving about content that has moved underneath a save, which is what
lets a save survive an edit, and is also what hides the cost of one. So it tells you what it
did. loadGame returns a report of everything it dropped, defaulted, or reset, and
previewLoad(envelope) computes the same report without applying anything. saveFlow(id) and
openFlow(id, { restore }) do the same for one flow, for a playthrough that steps away and
comes back.
A game that loads its own registry can ask it to refit: a saved value that no longer fits its
declaration, an enum value or a stage you’ve since deleted, goes back to its default rather than
reaching a condition that can’t hold it. Each engine tells you its share through its onRefit
hook (OnRefit, "on_refit"), with what the save held; without one, it’s a warning.
A host scope your game binds is deliberately not in the envelope. It’s your game’s state
(the engine only borrows it), so your game saves it, next to the envelope. A self-backed one is
different: nobody else holds those values, so the engine’s own registry stores them and they ride
in the save. A game running Patter and the Storylet Engine side by side keeps every property,
its host scopes included, in one registry and saves it once, so nothing is written twice. The
.storyletsave file format carries a bound world’s values beside the envelope, and play-helpers
ships a ready-made container for games with no world state of their own (see
JavaScript, Save and load). Put the saved world back before
the engine loads, not after: the load checks every card it puts back in a hand against the
world, and drops one whose condition no longer holds. Each runtime’s load helper does this for
you when you hand it your world.
- The API, in one table: every call, in one place.
- Your engine’s page is JavaScript, Unity, Unreal, or Godot.
- Dev tools: the examiner that shows you these properties live while the the game runs.
Open source under the MIT licence, made by Ian Thomas.