Craft

Script versions

Scripts outlive the Craft that runs them: a world written today is played next year. So Craft records which version of scripts each script is written for, and keeps running it the way it was written.

What a version is

The version covers everything a script is written against: the keys of defineScript(), the game calls and what they return, the error codes, card components and their props, and the limits.

  • This Craft runs version 1 and 2. A new script is written for version 2.
  • A version changes only with a breaking change: a call renamed, a result reshaped, a limit tightened, anything a saved script would now fail on or read differently.
  • What only adds keeps the version. A new call, a new component, a new optional key or a looser limit is open to every script on the version it lands in, and old scripts keep running as written.

You never write it

The version is stored with the script file, not in its source. Writing version in defineScript() is an error that says so.

  • A new script records the newest version when it is created, and every later edit keeps it.
  • A copy (paste, a package install, a clone, an import of an exported file) keeps the version of what it copies.
  • A script that records none is version 1.
  • Source pasted into a new script takes the newest version, whatever it was written for.

When a new version comes

The new version runs beside the old one: each script runs through the API it was written for, until it is moved over. Scripts on both versions call each other in the same run. A script never moves to a new version by itself.

A script written for a version this Craft doesn't run is marked invalid, with a message naming both versions, and the GM skips it rather than run it wrong.

Seeing a script's version

The script editor shows the version beside the script's status ("Script API v1"), and a folder that lists scripts says how many of the world's scripts are on an older version. Orbit's listings show it too.

Upgrading a script

Upgrading rewrites a script for the newer version and records the new version with it, as one saved version of the file. It changes only what it can be sure of: options written out in the call, renamed keys and values. Some scripts need more than that, such as options built in a variable. Orbit finishes those for you: it upgrades the script, makes the changes the upgrade couldn't, tests it, and tells you what changed. You never need to change code yourself.

In the script editor, Upgrade to v2 shows every change before anything is saved, your unsaved edits included; then run a test. For a script that needs more, the button is Upgrade with Orbit, which opens a chat where Orbit does it. Upgrade all, beside the count of older scripts, upgrades every script it can on its own and hands the rest to Orbit in one chat. You can also ask Orbit to upgrade a script.

Reverting a script to an earlier saved version brings back that version's API with its code. A game gets an upgraded world script when the world publishes and the game pulls it; until then the game keeps running it as it was.

What changed in version 2

Version 1 Version 2
when, after beforeNarrationTrigger, afterNarrationTrigger
cardOrder: "card-first" cardOrder: "card_first"
game.player() game.playerCharacter()
game.effect({ from, ... }) game.effect({ by, ... })
game.react({ who, as }) game.react({ by, as })
a card's bgImageFit: "tile-x" / "tile-y" "tile_x" / "tile_y"
.catch(…) or .then(…, handler) on a game call left out: the handler never ran

A multi-word value is snake_case in both versions, so succeedsOn's "or_higher" and "or_lower" don't change. How a roll or an effect looks (kind, delivery, projectile, element, approach) is written on its options in both versions too.

A game call that fails throws where it's made, before it returns a promise, so a .catch() written on it never ran: get() already answers null for a file that isn't there, and anything else still stopped the script. Version 2 refuses one, and the upgrade takes it out, which changes nothing a run does. To handle a failed call, wrap it in try { await … } catch (error) { … }.

In version 2, a roll's result also gives success. A version 1 roll's result is unchanged.

New in version 2: game.messages() reads the game's chat since its last compaction ({ id, turn, role, character, text, createdAt }). Version 1 has no equivalent, so there is nothing to upgrade.