Skip to content

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.

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 10

In 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.

Four things, and they are the same four in Patter, in the same order, so a game running both engines sees one rule:

  1. Read-only is the story’s promise, declared on the property (writable: false in the shard, the Read-only switch in Storyletter), or on the whole scope (writable: false beside its token, which a property can still override with writable: 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.
  2. The runtime keeps the promise too. If a bundle somehow carries such a write, play() refuses it with '@world.chapter' is read-only and nothing changes. Your resolver’s set is never called for a read-only property.
  3. A resolver with no set makes 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.
  4. 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.

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.

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.

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.

@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.

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.

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.

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 half
const 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.

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.

Open source under the MIT licence, made by .