Craft

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 === or includes.
  • 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 afterNarrationTrigger and 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].