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.defineScriptandscriptsare 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.
undefinedbecomes null; a Map, a Date orNaNfails 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.logoutput shows in test runs only, never to the GM or players.- Don't start a script with a
// $craftline. 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'sbgImageFit: "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_PLAYERand 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
byon 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.