Craft

Defining a script

A script's file is plain JavaScript. Tables and helpers can sit at the top, and the file ends with one export default defineScript({ ... }):

// Tables and helpers can live at the top of the file.
const ENCOUNTERS = {
  forest: [
    { weight: 3, result: "Nothing but birdsong" },
    { weight: 2, result: "A pack of wolves" },
    { weight: 1, result: "A wounded knight" },
  ],
  swamp: [
    { weight: 2, result: "Bog lights" },
    { weight: 1, result: "A hungry crocodile" },
  ],
};

function pickWeighted(rows) {
  const total = rows.reduce((sum, row) => sum + row.weight, 0);
  let roll = Math.random() * total;
  for (const row of rows) {
    roll -= row.weight;
    if (roll < 0) return row;
  }
  return rows[rows.length - 1];
}

export default defineScript({
  description: "Rolls a wilderness encounter for the region the party is in.",
  beforeNarrationTrigger: "The party travels or camps in the wilds.",
  input: {
    region: { type: "string", enum: ["forest", "swamp"], description: "Where the party is" },
    night: { type: "boolean", default: false },
  },
  run({ region, night }) {
    const encounter = pickWeighted(ENCOUNTERS[region]).result;
    return { encounter, night, loot: scripts.rollLoot({ tier: night ? 2 : 1 }) };
  },
});

The rules of the source

  • One export. The file must export default defineScript({ ... }) and export nothing else. defineScript and scripts are reserved names.
  • No imports, network, timers or eval. Ordinary JavaScript works: Math, JSON, array and string methods, classes, closures. Math.random() gives randomness.
  • The result is plain JSON: objects, arrays, strings, numbers, true/false and null. undefined becomes null; a Map, a Date or NaN fails the run.
  • Refuse by throwing: throw new Error("Kael has no spell slots left") stops the run, nothing it changed is saved, and the GM sees the message.
  • console.log output shows in test runs only, never to the GM or players.
  • Don't start a script with a // $craft line. That first line is kept for the identity line the CLI writes; when the rest of it is JSON, most saves drop it.
  • Don't write version. Craft records which version of scripts a script is written for by itself (see Versions).

API conventions

Every name a script writes or reads follows the same few rules, so you can guess one before you look it up:

  • Keys are camelCase: beforeNarrationTrigger, game.playerCharacter(), succeedsOn, cardOrder.
  • Values of more than one word are snake_case, never with dashes: succeedsOn: "or_lower", cardOrder: "card_first", a card's bgImageFit: "tile_x". One-word values ("attack", "enemy", "map") are just the word. The error codes are constants in capitals, NOT_IN_CURRENT_STATE, WAITING_FOR_PLAYER and the rest at the end of the game API.
  • The world's own words keep their spelling. Files' slugs and names, file type and field names, tracker names and the names of people in the current state are the world's, not the API's: game.files("Item").get("silver-ring").
  • Whoever acts is by on every roll, effect and reaction, and how one looks on the map is written on its options (kind, delivery, …: rolls and effects).

These are the names of version 2, the version a new script is written for. An older script keeps the names it was written with and keeps running; Versions has what changed.

Input fields

input maps each field name to a small JSON Schema. A field is required unless it has optional: true or a default. Write the input out as plain values: no variables, calls or computed keys, since it is read without running the script. That goes for every part of it, an enum included, and for each action's input too: enum: SIZES (a constant) is refused, enum: ["small", "large"] is fine. Every caller's input is checked against it, and defaults are filled in before run sees it.

Field Type What it is
type "string" | "number" | "integer" | "boolean" | "array" | "object" What kind of value it takes.
description? string What to pass, in a few words; the Game Master reads it.
enum? readonly (string | number | boolean)[] Strings and numbers: the only values it takes.
default? unknown The value a call that leaves the field out runs with; it must pass the field's own checks.
optional? boolean true: a call may leave it out, and run() gets no value for it.
items? ScriptInputField Arrays: the field every item must be.
properties? { [field: string]: ScriptInputField } Objects: its fields, by name, each written the same way.
minimum? number Numbers: the smallest value allowed.
maximum? number Numbers: the largest value allowed.
minLength? number Strings: the fewest characters allowed.
maxLength? number Strings: the most characters allowed.
minItems? number Arrays: the fewest items allowed.
maxItems? number Arrays: the most items allowed.

Each type takes only its own keys: enum, minLength and maxLength for strings; enum, minimum and maximum for numbers and integers; items, minItems and maxItems for arrays; properties for objects. A default must pass the field's own checks.

A choice in the middle of a rule (spend Luck after a miss, push on or stop) is an input too: luck: { enum: ["never", "onMiss"] }, applied after the dice. One rule is one script; don't split it into scripts the GM has to call in turn.

Calling another script

scripts.rollLoot({ tier: 2 }) runs the script named rollLoot with that input, checked against its fields, and returns its result. await it when that script's run is async. Call scripts by name only, never scripts[name]. Calls share the caller's game and its changes.

A call to a script that doesn't exist yet is allowed while you write, so you can write the caller first. Until the script it calls exists and is valid, the caller is invalid too, and the GM skips it.

Limits

What Limit
Scripts in a world 30
A script's source 64 KB
description 1,000 characters
beforeNarrationTrigger 500 characters
afterNarrationTrigger 500 characters
Time a run gets, its game calls included 3 seconds
Memory a run gets 16 MB
A result 64 KB
console.log output in a run 16 KB
Lookups in a run (every get(), each key of a getMany() and currentLocation(), found or not, and every file an include brings in) 100
create() and update() calls in a run 30
Files computed fields' load() reads in a run (apart from the lookups) 1000
game.currentState.update() calls in a run 20
People brought into the current state in a run 30
People, trackers or details named in one change 30
Details on one person 20
A tracker's text field, a list item or its note, or a detail's text, in the current state 160 characters
A tracker's or someone's name in the current state 60 characters
A field's or detail's label, or the words someone is out of action in 40 characters
time 80 characters
purpose 300 characters
Rolls, effects and reactions in a run 40
A card 32 KB and 200 elements
A card's own starting state 4 KB
Actions on one script's card 20

What Craft checks

When a script is saved, Craft parses it and reports each problem with its line: a syntax error, a defineScript() key it doesn't take (version included, and an older version's name such as when, whose message gives today's), a missing description or run, an input field that isn't valid, a file type the world doesn't have, actions without both card and visibility: "player", a card component or prop value written out that isn't allowed, and (version 2) a file tile's text written out past its length: a button's label or reason over 60 characters, a detail or badge over 80. Text worked out while the script runs is checked when its card is drawn. craft check runs the same checks. It also checks the world's scripts together: two scripts with the same name are both invalid, and so is a script that calls one that is missing or invalid. The editor marks each problem on its line and lists it in the Errors tab. You can save a script with problems, but the GM skips it until they are fixed.

The keys

Each key defineScript() takes. run, card and actions are the functions Craft calls: they are in Events.

What the GM reads

description

What the script does. The Game Master reads it.

Type Required Limit
string yes at most 1,000 characters

The GM reads it with the input fields before it runs the script. Say what it does and what it changes, plainly: "Rolls a wilderness encounter for the region the party is in."

beforeNarrationTrigger

When the Game Master should run it, before it tells the turn.

Type Required Limit
string no at most 500 characters
beforeNarrationTrigger: "The party makes camp in the wilds.",

The GM sees its first sentence beside the script's name every turn (a long one is cut short), and runs the script that fits before it tells what happens. Be specific: "The party makes camp in the wilds", not "travel". (Version 1 called it when.)

afterNarrationTrigger

What in the story has it run after the Game Master tells it (opt in): a check after each turn asks whether the turn met it, and runs the script if so. For scripts the story doesn't wait on, like advancing a clock or awarding XP, never ones that decide what happens.

Type Required Limit
string no at most 500 characters
afterNarrationTrigger: "A full day passes in the story.",

The script runs after the story only if the GM didn't already run it that turn, and the check asks about at most ten such scripts a turn, in name order. Use it for scripts the story doesn't wait on: advance a clock, award XP, close out a fight. A script that decides what happens goes in beforeNarrationTrigger. See run. (Version 1 called it after.)

How it runs

visibility

Who sees it run in play: the players too (the default) or the GM alone.

Type Required
"gm" | "player" no

"player", the default, suits a purchase, an attack, anything players should see the rule decide. "gm" suits a secret table, hidden odds or a morale check. To set it, click the Visible to players pill in the editor's toolbar (it reads Hidden from players when off), which writes visibility into the source for you. It is how the run is shown, not a secret: the run's input and result reach the players' browsers either way.

cardOrder

Where the card players see goes beside what the run did on the map: "together" (the default) shows it with that moment, its result as the blow lands; "card_first" shows the card first, then the map plays (a table roll, then the bandits it called up stepping out).

Type Required
"together" | "card_first" no

Only matters for a "player" script whose run also plays on the map. Use "together" for an attack or a spell, "card_first" when the card decides what happens next (an encounter table, a summon). A run with nothing on the map shows its card where it ran. See Cards.

waitsForPlayer

End the Game Master's turn as soon as this script has run (default false): the GM writes nothing after it, and the player answers next. For scripts that wait on the player, like a shop whose card they buy from.

Type Required
boolean no
waitsForPlayer: true,

The GM is told to say everything first and run it last. A run that failed doesn't end the turn.

What it takes

input

The input fields, by name.

Type Required
{ [field: string]: ScriptInputField } no
input: {
  character: { type: "string", description: "The character's slug or name" },
  tier: { type: "integer", minimum: 1, maximum: 3, default: 1 },
  tags: { type: "array", items: { type: "string" }, optional: true },
},

Leave it out for a script that takes nothing.