Script events
A script is a set of functions Craft calls at given moments. Each entry below is one of them: when it is called, what it gets and what it may change.
Whatever calls it, a run follows the same rules:
- All or nothing. Every file and current-state change a run makes is checked when it is made and saved together when the run ends. A thrown error, a limit, or a file someone else saved while it ran saves nothing. In a game, a run changes that game's own copies of files; the world's files stay as built.
- One file, one object. A file reached twice in a run, by a lookup or an
include, is the same object, so files can be compared with
===orincludes. - 3 seconds, its file reads and changes included, for the whole run, scripts it calls included.
- Randomness isn't kept.
Math.random()gives a new answer on every run, so a replayed or restarted run can roll differently. The game's own rolls are kept (see game.roll).
When the GM runs it
run
Runs the script with its input, typed from its fields. May be async; return plain JSON.
run(input: { [field]: its value }, context: ScriptContext): unknown
Its second argument (ScriptContext):
| Field | Type | What it is |
|---|---|---|
game |
Game |
The world's files and current state: look files up, read them, create and change them, and read and change the current state. Every change saves together when the run ends, or none does. |
async run({ character, item }, { game }) {
const hero = await game.files("Character").get(character, { include: ["inventory"] });
if (!hero) throw new Error("No character " + character);
// …
return { equipped: "Leather Gloves" };
}
When it is called:
- In the GM's turn, when what is happening fits the script's
beforeNarrationTrigger. The GM runs it with input that fits its fields; an input that doesn't fit, or a name no script has, comes back to the GM to fix, and players see nothing. - After the story, when the script has
afterNarrationTriggerand the turn met it, unless the GM already ran it that turn. Its changes show after the story, with no words of their own. - When the player rolls, if the run asked them to with
game.askPlayerToRoll(): the run starts over with the same input, its earlier rolls give back the same dice, and the ask answers with the player's roll. - In a test run, by hand (see Testing).
What the GM gets back: the result, a line for each change the script
saved ("Snowshoes: equipped false → true") and what it changed in the
current state, which the GM narrates and doesn't record again. A thrown
error comes back as the script's refusal, in its own words. With
waitsForPlayer: true, or after asking the player to roll, the GM's turn
ends with the run.
Take { game } only when the script reads or changes files: a script
without it changes nothing, and the GM records what its result means.
On the script's card
card
The script's own card: what players see where it ran (with visibility "player") and the editor's test run shows. Gets run()'s result and the input; returns a json-render spec, { root, elements }, whose props can bind { "$state": "/result/..." }. Return null for the default card.
card?(result: any, input: { [field]: its value }): ScriptCardElement | ScriptCardTree | ScriptCardSpec | null | undefined
card(result, input) {
return { type: "Frame", props: { eyebrow: "Loot", title: result.found } };
}
Runs after a successful run, in the same run's time, with its result and
the input (defaults filled in). It gets no game and changes nothing. A
card that can't be drawn, or a card that throws, never fails the run:
players see no card, and a test run says why. Only a "player"
script's card is shown. Components, props and limits are in
Cards.
actions
Runs on a tap. Check what the tap asks against the result and the files (never trust params for a price), throw to refuse with a reason the card shows, and return the card's next result (or nothing to keep it).
run(input: any, context: ScriptActionContext): unknown
Its second argument (ScriptActionContext):
| Field | Type | What it is |
|---|---|---|
game |
Game |
The world's files, as run() gets them; every change saves together or none does. |
result |
any |
What the card was last drawn from: run()'s result, or the last action's. Read-only. |
actions: {
buy: {
input: { item: { type: "string" } },
async run({ item }, { game, result }) {
const offer = result.stock.find((piece) => piece.id === item);
if (!offer) throw new Error("That's gone.");
const me = await game.playerCharacter();
if (!me) throw new Error("Join the game to buy.");
if ((me.gold ?? 0) < offer.price) throw new Error("You need " + offer.price + " gp.");
await me.update({ gold: me.gold - offer.price });
return { ...result, stock: result.stock.filter((piece) => piece.id !== item) };
},
},
},
Runs on the server when a player presses a button on the card that names
the action, with no GM turn. Only a script with card and
visibility: "player" can have actions, and only someone playing a
character in the game can press them. Its input is the press's params, checked
against the action's fields. It returns the card's next result, or nothing
to keep it; the card is drawn again from it with run's input, for every
player. The GM hears each press, and what it changed, at the start of the
next turn.
An action can't change the current state; only a GM turn does that. Never trust a press: how to check one, bindings, the card's own state, confirms and tiles' buttons are in Cards.
startsTurn
Start the Game Master's next turn once a press works (default false), with the pressed Button's label as the player's turn: for a pick-one choice that moves the story on. Only while the card is the newest thing in the story, and only the first such press on it. Leave it off for an action players press many times, like a shop's Buy.
startsTurn?: boolean
choose: { input: { path: { type: "string" } }, run: chooseRun, startsTurn: true },
The GM's turn starts with the pressed button's label (or its turn prop)
as the player's words. Labels, when a press starts a turn and when it
doesn't are in "Starting the GM's turn" in Cards.
From another script
scripts
The world's other scripts, by name: const loot = await scripts.rollLoot({ tier: 2 }).
const loot = await scripts.rollLoot({ tier: 2 });
The call's input is checked against the other script's fields, and a bad one
throws. The called script shares the caller's game and changes, its time
counts toward the caller's, and its card is never drawn. Call scripts by
name only, never scripts[name].