Scripts
A script is a JavaScript file the GM runs during play. It turns a rule into code that comes out the same way every time: a weighted encounter table, what an ability does, equipping an item, a loot or name generator, a price or travel-time calculation. The GM decides when a script runs, the script decides what happens, and the GM tells the story of its result. A script can also read and change the world's files and the current state itself, show rolls and effects on the map, and draw a card players can press.
Instructions ask the GM to carry out each step in its head while it tells a story. That is slow, and it's where mistakes creep in. A script takes that load off the GM: it gets the right input, the script does the math, the rolls and the bookkeeping, and the GM spends its attention on the story.
How it is used
- Scripts run only in worlds where they are on. A game started from such a world has its scripts too.
- The GM sees every script by name in a short list at the start of its
context, each with the first sentence of its
beforeNarrationTrigger. The trigger check also suggests a script when itsbeforeNarrationTriggerfits the player's move, with its input the first time. When one fits what is happening, the GM reads that script's description and input, runs it, and narrates the result. It never reads the code. - A script that changes things makes the changes itself. The GM is told what it changed and doesn't record those changes again. A script that only returns a result (a table roll) changes nothing: the GM records what the result means.
- A script can run after the story. One with
afterNarrationTriggeris checked once the GM has told the turn ("a full day passes"), and run then if the turn met it. - Players see what you choose. A player script (the default) is
named while it runs, and shows a card where it ran when you design one,
with buttons that run the script's actions. A GM-only script
(
visibility: "gm") shows players only what it changed. - Scripts are hidden from the AI's context. No search or research finds a script's code. They are not hidden from people: treat a world's scripts as readable by anyone who can see the world, and keep no secrets in them that would spoil play.
- Computed fields can't call scripts.
When to use a script vs a procedure
A good rule of thumb: if part of the instructions reads like a procedure (step one, step two, then check this), it probably belongs in a script. Keep instructions for tone, style and judgment calls.
Use a script:
- for logic you can write out clearly: if A, do B; if C, do D;
- for bookkeeping that happens in that moment: spend a slot, pay a price, hand out loot, tick a clock;
- to start or update trackers, such as rolling initiative into a turn order;
- to show rolls, effects and reactions on the map;
- for interactive cards: a shop, a loot screen, a level-up;
- to give the GM a tool it will use again and again.
Use a procedure for longer, looser work:
a framework for running a whole fight, or a situation with too much nuance
for code. The two work together: a fight procedure can tell the GM to run
attack for each blow.
Making a script
- The Script type, once. Scripts are files of the locked Script type. If the world has none yet, pick Script in a New File menu: the first time, it makes the Script type and a Scripts folder, then a new script from a starter table.
- The file name is the script's name, camel-cased:
a script named Road Encounter is run as
roadEncounter. Keep scripts in a Scripts folder. Two scripts can't share a name ("Road Encounter" and "road-encounter" are bothroadEncounter), and a world can have at most 30 scripts. - Write it. The file exports one
defineScript({ ... }): what the script does, when to run it, its input and itsrunfunction. Keys are camelCase (beforeNarrationTrigger) and values of more than one word snake_case (cardOrder: "card_first"). See Defining a script. - Check and test it. 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. Then test it with a normal case and an edge case: open the Test tab under the code, fill in the input and press Run (⌘/Ctrl+Enter). See Testing.
To change one, edit it in the script editor and save.
Doing it well
- Write
beforeNarrationTriggerfor the GM, situation first. The GM sees only its first sentence beside the script's name, every turn. "The party makes camp in the wilds" works; "travel" doesn't. - Say plainly what it does in
description. The GM reads it before it runs the script. If it changes files or starts a tracker, say so ("starts the Fight tracker"): a GM that tries to start that tracker itself is told to run the script instead. - Take names or slugs as input, and look files up. The GM passes what it sees: a name, a slug or a guess at one. Looking the file up finds it all the same.
- Return what the GM needs to tell it, in words.
{ encounter: "A pack of wolves" }, not a row number. - Throw to refuse, in words a player understands. "Kael has no spell slots left" stops the run, saves nothing, and the GM tells it.
- Decide outcomes in
beforeNarrationTrigger, do the paperwork inafterNarrationTrigger. A script that decides what happens (an attack, an encounter) must run before the story is told. Advancing a clock or awarding XP can wait forafterNarrationTrigger. A worked XP award and level-up: designing progression. - One script per rule, and small ones that call each other. A loot table can be its own script that an encounter script calls.
- Keep the rules in the script. Prices, recipes and DCs belong in constants at the top of the file, so a fix reaches every game.
- Show what players should watch. Roll with the game's dice for any roll players should see, and let quiet rolls (ten goblins' initiative) stay in the code.
- Read only what the script needs. Look up the files it works on by
name. When it needs the files a field refers to, load them with the
lookup's
include, and when it needs a list of files, ask for them together withgetMany(), rather than looking each one up inside a loop: a loop of lookups is slow and slows the turn it runs in. - Keep the code plain. Work a value out once and reuse it.
- Let the instructions point at it. A tracker only scripts change still needs its tracker definition, with instructions that name the scripts that keep it ("kept by the startCombat and endTurn scripts").
Mistakes
- A vague
beforeNarrationTrigger. The GM never runs the script, or runs it at the wrong moment. Put the situation in the first sentence. - A script that decides the outcome in
afterNarrationTrigger. The story is already told by then, so the result arrives too late. - Too many
afterNarrationTriggerscripts. Each turn the check asks about at most ten of them, in name order, so the rest never run after the story. - A file type named wrong.
game.files("Itme")makes the script invalid, and the GM skips it. Use the names the world has. - Comparing names by hand. Checking an input against a file's
$namemisses "Leather Gloves" given as "leather-gloves". Look the file up and compare files. - Catching every error. A run that asked the player to roll stops with
WAITING_FOR_PLAYER; acatchthat swallows it breaks the roll. - A result that isn't plain JSON. A Map, a Date or
NaNfails the run. - Expecting part of a failed run to save. A thrown error, a limit or a file someone else saved meanwhile saves nothing at all.
Reference
- Script cards: The card a player-visible script draws in the story, its buttons and actions, its own state, and every card component.
- Defining a script: The source of a script: defineScript() and each of its keys, input fields, results, calling other scripts and the limits.
- Script events: When Craft calls a script's functions: run when the GM runs it, card after a player script runs, actions when a card's button is pressed, and calls from other scripts.
- The game API: What run(input, { game }) can do: look files up, read and change them, read and change the current state, show rolls and effects, and the errors a call throws.
- Rolls and effects: Rolls, effects and reactions a script shows on the map and in the story, asking the player to roll, and the words that pick how each one looks.
- Testing scripts: Test runs: how to run a script by hand, what a dry run shows, and how to read what comes back.
- Script versions: Which version of scripts a script is written for, why you never write it, and what happens when scripts change.