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.


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+3for advantage,1d8+2+1d6for two kinds of damage. Write dice only, with no words for damage types. game.rollrolls for real. Use it instead ofMath.random()for any roll players should see, and roll quietly in plain code (or withshow: "none") what they needn't watch, like ten goblins' initiative.- The roll gives back the total, every die's face, the kept d20
(
natural), andsuccess: whether it met the number inagainst(that number or higher, or that number or lower withsucceedsOn: "or_lower"). A roll against no number is always a success. For a critical hit or miss, checknaturalyourself. - A save works the same way: roll for whoever saves, against the DC, with
kind: "save". The card stamps whether it held.

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.rollit made before asking gives back the same dice, andaskPlayerToRollanswers 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
codeisWAITING_FOR_PLAYERthrough. - 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) andwhat(a short caption).byis who it comes from: leave it out when it comes from the place itself, like a trap. Giveata 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) andas(the icon).



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. |







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. |











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. |













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. |
















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: "…" |










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 codeNOT_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
atorwhatthrowsSCHEMA_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. atnames at most 30 people, and areasonorwhatis 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". |