Craft

Rolls and effects

When a script plays part of the game for the GM (a spider's bite, a trap, a dragon's breath), players should see it happen, not just find the hit points gone. A script can roll dice the table sees, show a blow or a spell landing, and put a reaction over someone's head. These moments play on the map and in the story at the point the script made them, just like the GM's own rolls. They show on the game screen.

Rolls are for games with dice. Effects and reactions need no dice, so they work just as well in diceless games.

You don't need to write the code yourself. Ask Orbit ("make the attack script show the roll and the damage on the map") and it adds them to your script.

How a moment shows

Each moment shows exactly where the script made it, in order with what the script changes. If a script rolls the attack, rolls damage, then lowers the target's hit points, players see the swing, then the damage dice, then the hit points drop, all before the GM's next words. A miss shows the roll and nothing after it.

A roll gets the same dice card in the story that the GM's own rolls get: who rolled, at whom, the dice, the total against the number to beat, and Hit or Miss. The GM is told each moment as a line ("Roll: Giant Wolf Spider 1 1d20+3 = 19 vs AC 15 at Kaelen Drevic (Bite)"), so its story matches what the table saw.

A battle map mid-attack: claw marks rake across Kaelen Drevic's token while the d20 over Giant Wolf Spider 1 shows 16 and a pill reads 19 vs 15

Two cards in the story: Giant Wolf Spider 1's Bite rolled 1d20+3, 16 + 3 = 19, marked Hit vs AC 15; then 5 damage, with 15 hit points left

Outside a game (a test run) nothing plays: the test lists each moment as one of those lines, with what the run would change. A test run has no scene, so its current state is empty: a moment that names someone throws NOT_IN_CURRENT_STATE there, unless the run brought them into the current state first. Try those moments in a game.

Rolling dice

const hit = await game.roll("1d20+3", {
  by: "Giant Wolf Spider 1",
  at: "Kaelen Drevic",
  reason: "Bite",
  against: { value: 15, label: "AC 15" },
  kind: "attack",
  delivery: "claw",
});
if (hit.success) {
  // A natural 20 rolls the damage dice twice.
  const damage = await game.roll(hit.natural === 20 ? "2d6+1" : "1d6+1", {
    by: "Giant Wolf Spider 1",
    at: "Kaelen Drevic",
    reason: "Bite damage",
    kind: "damage",
    delivery: "claw",
  });
  // lower Kaelen's hit points by damage.total
}
  • The dice use Craft's dice notation: 1d20+5, 2d20kh1+3 for advantage, 1d8+2+1d6 for two kinds of damage. Write dice only, with no words for damage types.
  • game.roll rolls for real. Use it instead of Math.random() for any roll players should see, and roll quietly in plain code (or with show: "none") what they needn't watch, like ten goblins' initiative.
  • The roll gives back the total, every die's face, the kept d20 (natural), and success: whether it met the number in against (that number or higher, or that number or lower with succeedsOn: "or_lower"). A roll against no number is always a success. For a critical hit or miss, check natural yourself.
  • A save works the same way: roll for whoever saves, against the DC, with kind: "save". The card stamps whether it held.

Two cards in the story: Kaelen Drevic's Constitution save vs poison rolled 1d20+2, 6 + 2 = 8, marked Failed vs DC 11; then 8 damage from 2d6, with 12 hit points left

Asking the player to roll

Players roll their own character's dice. When a script needs the player's roll, it asks with game.askPlayerToRoll, which takes the same options as game.roll and answers the same way:

const hit = await game.askPlayerToRoll("1d20+7", {
  by: "Brannoch Ironvale",
  at: "Goblin Minion 1",
  reason: "Longsword (attack 1 of 2)",
  against: { value: 12, label: "AC 12" },
  kind: "attack",
  delivery: "strike",
});
  • In a game where the GM asks players for their rolls, the script stops there. The GM's reply ends with the player's roll button, showing what the roll is for and the number to beat.
  • When the player rolls, their dice land on the map and the script runs again from the top with the same input. Each game.roll it made before asking gives back the same dice, and askPlayerToRoll answers with the player's roll.
  • Nothing the script changed before asking is saved until the player has rolled.
  • Asking ends the GM's turn, even for a script without waitsForPlayer.
  • A script that catches errors must let one whose code is WAITING_FOR_PLAYER through.
  • A choice made with Math.random() before asking isn't given back. If the script then asks something else, the player is asked again.
  • Where no player is asked (a test run, a card's action, a game where players don't roll their own dice) the dice are rolled for them and shown as an ordinary roll.

Effects and reactions

await game.effect({
  by: "Ghost Mantis 1",
  at: "Garrun Haskvale",
  what: "Scything claws from nowhere",
  delivery: "claw",
});
await game.react({ by: "Garrun Haskvale", as: "anger" });
await game.react({ by: "Kaelen Drevic", as: "alert" });
  • An effect is something landing with no roll of its own: an attack that always hits, falling rocks, a spell that needs no save. It needs at (who it lands on) and what (a short caption). by is who it comes from: leave it out when it comes from the place itself, like a trap. Give at a list of names to catch several people, like a dragon's breath.
  • A reaction is a small icon over someone's head. It needs by (who reacts) and as (the icon).

Claw marks rake across Garrun Haskvale's token on the battle map, with the Ghost Mantis nearby

Two cards in the story: Ghost Mantis to Garrun Haskvale, a physical claw, Scything claws from nowhere; then Garrun Haskvale takes 6 damage

An anger icon over Garrun Haskvale and an alert icon over Kaelen Drevic on the battle map

Where a moment shows

show says where a moment goes. It is one of "all", "map", "none":

  • "all" (the default): on the map and as its own row in the story.
  • "map": on the map only. Use it when the script's own card already shows the roll, so the story doesn't show it twice.
  • "none": nowhere. It still happens (the dice are rolled, the hit points go down), but players don't see it play out.
// The initiative card shows every roll, so the map plays them on its own.
const init = await game.roll("1d20+2", { by: "Goblin 1", reason: "Initiative", show: "map" });
// A recharge roll no one needs to see.
await game.roll("1d6", { reason: "Breath recharge", show: "none" });
// A change to the current state takes it too, for the row it makes.
await game.currentState.update(change, { show: "map" });

Each call sets its own show. There is no setting for a whole script, so you can tell what a call shows from the call itself.

How a moment looks

A few words on the moment's options pick how it looks on the map: a roll takes kind, delivery, projectile, element and approach, and an effect delivery, projectile and element. A reaction has none: its as is its look.

await game.roll("1d20+6", { by: "Kar", at: "Ogre", kind: "attack", delivery: "bolt", element: "fire" });

Worlds name their weapons, skills and spells their own way, so you translate: a "Hellfire Lance" is a bolt of fire, a plasma rifle a shot of fire, a Hack check is tinker. Every word is optional. What you leave out is read from the roll's reason (English words only), and a roll nothing can be read from shows its dice and nothing more.

The map uses each word only where it shows, by the roll's kind:

Kind Look words the map uses
attack delivery, projectile, element
damage delivery, projectile, element
heal delivery, projectile, element
save element
check approach
contest approach
chance none: the dice alone

An effect uses its delivery, projectile and element. A projectile is drawn only when the delivery flies (shot, thrown, bolt, or a burst sent across the room). A plain weapon (no element, or physical) is drawn solid, in steel and wood; only an element glows.

Roll kinds

kind on a roll: what the roll is. It is more than a look: it sets how the roll plays out and what its card stamps (Hit or Miss for an attack, whether a save, a check or a contest succeeded, and nothing for damage, heal and chance, which are amounts or luck), and so whether its card can stamp Crit or Fumble. Only an attack draws a line to its target.

Word What it is
attack To hit someone: the blow travels and lands or misses.
damage How much harm, usually after an attack.
heal How much healing.
save Someone resisting something: a ward that holds or breaks.
check A skill or an attempt: the dice and its approach's flourish.
contest One side's effort against another's: a tug between them.
chance Luck, a table, initiative: the dice alone.

attack: the blow travels and lands, with Hit, Miss or Crit

damage: the total over the roller, then the harm on the target

heal: a green glow on whoever is healed

save: a ward around the saver that holds or breaks

check: the dice and Pass or Fail

contest: a tug between the two sides

chance: the dice alone

Deliveries

delivery on a roll or an effect: how it travels from whoever sent it to whoever it lands on.

Word What it is
strike A weapon in hand: a slash.
claw Teeth, claws, fists: three quick swipes.
shot Anything fired: a streak straight to them.
thrown Something thrown: it tumbles on an arc.
bolt A spell or power sent at them: a glowing bead with a tail.
beam A ray: a line that holds and flickers.
arc Lightning jumping to them.
wave A push out from the roller: a cry, a psychic or sonic wave.
spray Breath, a cone, a jet from the roller.
burst An explosion or area at them.
touch A hand laid on them.

strike: a weapon in hand, a slash

claw: three quick swipes

shot: a streak straight to the target

thrown: something tumbling on an arc

bolt: a glowing bead with a tail

beam: a line that holds and flickers

arc: lightning jumping across

wave: rings pushing out from the sender

spray: a cone or jet from the sender

burst: an explosion on the target

touch: a glow where a hand is laid

Projectiles

projectile on a roll or an effect: what the map draws flying, whatever the world calls the weapon. A javelin is a thrown shaft, a pistol a shot slug, a grenade a burst sent as a ball. Left out, it is read from the reason ("Javelin attack" flies as a shaft), or the delivery's own is used (a shot is an arrow, a throw a spinning blade, a bolt a glowing bead).

Word What it is
shaft A long thin shaft, point first: arrows, bolts, javelins, spears, harpoons.
blade A short shape spinning end over end: axes, knives, shuriken, boomerangs.
ball A round body on an arc: rocks, grenades, flasks, cannonballs, globs.
slug A tiny fast tracer: bullets, pellets, needles, flechettes.
missile A body with a smoke trail: rockets, missiles, mortar shells.
bead A glowing orb: spells, plasma, energy.
line A line that reaches out and snaps back: whips, chains, grapples, tentacles, tongues.
swarm Many small things weaving in: insects, bats, drones, magic missiles, shrapnel.

Elements

element on a roll or an effect: what it is made of. It sets the colour, the mark beside the wound and the sound.

Word What it is
physical Blades, blunt blows, plain force: drawn solid, with no glow.
fire Fire and heat.
cold Frost and ice.
lightning Electricity.
acid Acid and corrosion.
poison Poison and venom.
shadow Necrotic, void, curses, decay.
light Radiant, holy, lasers.
mind Psychic, charm, dread.
arcane Force, raw magic.
sonic Thunder, sound.
nature Thorns, stone, wind.
life Healing.

physical: a plain blow

fire: flame orange

cold: icy blue

lightning: yellow

acid: lime green

poison: deep green

shadow: purple

light: gold

mind: pink

arcane: indigo

sonic: cyan

nature: earthy amber

life: green-teal

Approaches

approach on a check or a contest: what kind of effort it is, for the badge and the flourish around the roller.

Word What it is
sneak Stealth, hiding: the roller fades.
notice Perception, spotting: a ring scans out.
search Investigating, searching a place.
read Reading a person: insight, empathy, sensing a lie.
persuade Persuasion, diplomacy.
deceive Lying, disguise, bluffing.
intimidate Threats, menace.
perform Music, acting, a show.
force Strength: lifting, climbing, breaking, grappling.
agility Acrobatics, balance, dodging.
endure Toughing it out: cold, poison, a forced march.
know Lore, history, recalling what one knows.
tinker Locks, traps, machines, crafting, hacking.
tend Medicine, first aid.
wild Survival, animals, tracking.
magic Arcana, sensing or working magic.

sneak: a closed eye, the roller fades

notice: an eye, with a ring scanning out

search: a magnifier

read: a watching eye

persuade: a speech bubble with a heart

deceive: a mask

intimidate: a spiky burst

perform: music notes

force: a fist

agility: a gust of wind

endure: a shield with a heartbeat

know: an open book

tinker: a gear

tend: a first-aid kit

wild: a paw

magic: a sparkle

Reactions

as on a reaction: the icon over someone's head.

Word What it is
alert They notice: "!"
question Puzzled, unsure: "?"
love Fondness, attraction, gratitude: a heart.
anger Rage, offence: angry brows.
fear Fright: wide, worried eyes.
joy Delight, relief: a beaming face.
sleep Asleep, drowsy, knocked out: a moon with Zs.
idea A realisation: a spark.
sad Grief, disappointment: a sad face.
silence Nothing to say: "…"

alert: an exclamation mark

question: a question mark

love: a heart

anger: angry brows

fear: wide, worried eyes

joy: a beaming face

sleep: a moon with Zs

idea: a spark

sad: a sad face

silence: three dots

Limits and errors

  • Every name (by, at) must be someone in the current state, spelled as it is there (case doesn't matter). Anyone else throws an error with the code NOT_IN_CURRENT_STATE, which lists who is there.
  • A word not on the lists above, dice that can't be read, or an effect with no at or what throws SCHEMA_VALIDATION. So does an older version's option (from, who), with a message that says what to write instead.
  • One run can show at most 40 moments. More throws LIMIT_EXCEEDED.
  • One roll can roll at most 100 dice, of at most 1,000 sides. More throws LIMIT_EXCEEDED.
  • at names at most 30 people, and a reason or what is cut at 200 characters.

The calls

game.roll

game.roll(dice: string, options?: RollOptions)

Rolls dice and shows the roll on the map and in the story, with its dice card, where the script made it: game.roll("1d20+5", { by: "Goblin 1", at: "Riven", reason: "Scimitar attack", against: { value: 14, label: "AC 14" } }).

Option Type Required What it is
by string Who rolls, by their current-state name; leave out for a roll no one in the scene makes.
at string | readonly string[] Who it is at or for: the target, or everyone an area catches.
reason string What the roll is for, a few words ("Scimitar attack").
against number | { value: number; label?: string; succeedsOn?: "or_higher" | "or_lower" } The number it is against: 14, or { value: 14, label: "AC 14" }; succeedsOn "or_lower" for a roll-under rule.
kind kind word What kind of roll it is: "attack", "save", "damage"… It sets the roll's stamp (hit or miss, resisted or failed), and an amount (damage, healing) gets none.
approach approach word What kind of effort a check or a contest is, for its badge and flourish: "sneak", "persuade", "tinker".
show "all" | "map" | "none" Where the roll shows: "all" (the default), "map" (no row in the story) or "none".
delivery delivery word How it travels from who it comes from to who it lands on.
projectile projectile word What the eye sees flying, for a shot, a throw or a bolt: a javelin is "shaft", a pistol "slug".
element element word What it is made of, which sets its colours and sound: "fire", "cold", "physical" for a plain weapon.

It returns:

Field Type Required What it is
total number yes The kept dice added up, with the modifiers.
faces number[] yes Every die's face, dropped dice included.
natural number The kept face of the first d20, for natural 1s and 20s.
dice string yes The dice as rolled ("1d20+5").
success boolean yes Whether it met the number it was against (on the side succeedsOn says); true for a roll against none.

against takes succeedsOn: "or_lower" for a roll-under system: the roll succeeds at the number or under it.

game.askPlayerToRoll

game.askPlayerToRoll(dice: string, options?: RollOptions)

Asks the player to roll for their own character, and answers with their dice as roll() does: game.askPlayerToRoll("1d20+5", { by: "Riven", at: "Goblin 1", reason: "Longsword attack", against: { value: 13, label: "AC 13" } }). In a game the run stops here and the GM's reply ends with the dice in front of the player; once they roll, the run starts over with the same input, its earlier roll() calls give back the same dice, and this call answers with the player's roll. Nothing the run did before it is kept until then. Let a WAITING_FOR_PLAYER error through a catch. Where no player is asked (a test run, the assistant) the dice are rolled for them.

Option Type Required What it is
by string Who rolls, by their current-state name; leave out for a roll no one in the scene makes.
at string | readonly string[] Who it is at or for: the target, or everyone an area catches.
reason string What the roll is for, a few words ("Scimitar attack").
against number | { value: number; label?: string; succeedsOn?: "or_higher" | "or_lower" } The number it is against: 14, or { value: 14, label: "AC 14" }; succeedsOn "or_lower" for a roll-under rule.
kind kind word What kind of roll it is: "attack", "save", "damage"… It sets the roll's stamp (hit or miss, resisted or failed), and an amount (damage, healing) gets none.
approach approach word What kind of effort a check or a contest is, for its badge and flourish: "sneak", "persuade", "tinker".
show "all" | "map" | "none" Where the roll shows: "all" (the default), "map" (no row in the story) or "none".
delivery delivery word How it travels from who it comes from to who it lands on.
projectile projectile word What the eye sees flying, for a shot, a throw or a bolt: a javelin is "shaft", a pistol "slug".
element element word What it is made of, which sets its colours and sound: "fire", "cold", "physical" for a plain weapon.

It returns:

Field Type Required What it is
total number yes The kept dice added up, with the modifiers.
faces number[] yes Every die's face, dropped dice included.
natural number The kept face of the first d20, for natural 1s and 20s.
dice string yes The dice as rolled ("1d20+5").
success boolean yes Whether it met the number it was against (on the side succeedsOn says); true for a roll against none.

game.effect

game.effect(options: EffectOptions)

Shows something landing on people with no roll: an auto-hit, a hazard, a spell's effect.

Option Type Required What it is
by string Who it comes from, by their current-state name; leave out when it comes from the place itself.
at string | readonly string[] yes Who it lands on.
what string yes What happened, a few words for the caption ("Scimitar hits").
show "all" | "map" | "none" Where it shows: "all" (the default), "map" (no row in the story) or "none".
delivery delivery word How it travels from who it comes from to who it lands on.
projectile projectile word What the eye sees flying, for a shot, a throw or a bolt: a javelin is "shaft", a pistol "slug".
element element word What it is made of, which sets its colours and sound: "fire", "cold", "physical" for a plain weapon.

game.react

game.react(options: ReactOptions)

Shows someone reacting: a bead over their head.

Option Type Required What it is
by string yes Who reacts, by their current-state name.
as reaction word yes The reaction shown over their head.
show "all" | "map" | "none" Where it shows: "all" (the default), "map" or "none".