Craft

Agent Tools

Your Game Master and your assistant, Orbit, each have their own set of tools: the actions they can take while they reply. Knowing what those actions are helps you understand what each one can do, and what happens when it's working.

The Game Master's tools

The Game Master never edits your files by hand. It asks for what it needs in plain words ("What is Kael's Dexterity?", "Sara takes 6 damage"), and its tools find the right files, check the change and write it. That keeps the GM's attention on the story.

The only switch is the Roll tool, on the Game Master's profile in the Game Master place. It's on by default.

research

Answers questions about your world and the game so far: who or what something is, a value on a sheet, how people, places and groups are connected, what happened earlier in the game, where places are and how far apart they are. A question that starts with "Tracker:" ("Tracker: Heat") reads that tracker as it stands.

It searches your world's files and summaries of earlier play, then keeps only the pieces the answer needs, so the GM gets the facts rather than whole files. Hidden files are never searched. See The Research Tool.

create

Makes a new file the moment the story introduces someone or something that should last: a named character, place, item, faction or event. The GM describes it in a sentence, and the tool picks the file type and folder, fills in the sheet and saves it. New characters, places and items get their picture the same way (see The Craft Image Bank).

update

Records every change in a turn: damage and healing, coins spent, items gained, someone moving across the map, a tracker ticking up, the party arriving somewhere new. Each change is a short instruction ("HP -6", "Moves to within 5 ft of Kael"). The tool edits only the fields it should and updates the scene and its trackers to match. The What changed card under the GM's reply lists what it changed.

currentState

Shows the whole current state: where the party is, who's on the map and where, and every tracker. It changes nothing.

list and read

list shows what exists, such as every tavern in a city or every file of a type. read opens one file, or only the fields the GM asks for, with everything its sheet works out (see Computed Fields).

gmRollDice

The Game Master's own dice: enemies' attacks and saves, damage, rolls the player shouldn't see, random tables. The roll happens in code, never in the model's head, and comes back with every die and the total. When the roll is against a number (against), the result also says whether it hit or missed, passed or failed. The roll shows up as a dice card in the reply and plays out on the map. 

gmRollDice({
  reason: "Goblin attacks Mira with a shortbow",
  diceExpression: "1d20+4",
  against: { label: "AC", value: 14 },  // optional, the number the roll is against
  fileName: "Goblin.monster",  // optional, shows the goblin's portrait on the card
})

With the Roll tool off, the GM rolls for your character with gmRollDice too.

askPlayerToRoll

When the Roll tool is on, this is how the Game Master asks you to roll for your own character: checks, saves, attacks, dice pools. The GM narrates up to the roll, shows you what's at stake and the dice, and waits. Your roll comes back as your next turn, and the GM tells you how it went. 

askPlayerToRoll({
  reason: "Notice the hidden door",
  diceExpression: "1d20+3[WIS]",
  skillName: "Perception",      // optional, shown on the roller
  against: { label: "DC", value: 13 },  // optional, shown on the roll request
  targetCharacterSlug: "mira",  // optional, which character is rolling
})

The number a roll is against

Both dice tools take an optional against: what your rules call the number (label), the number itself (value), and which side of it succeeds (succeedsOn). The verdict on the dice card and the map is read from it. The GM leaves it out for damage, healing and other rolls that measure how much rather than whether.

  • "or_higher", the default: meeting or beating the number succeeds, like AC 14, DC 15 or 8+ on 2d6.
  • "or_lower": rolling at or under the number succeeds, like d100 under a skill or 3d6 under an attribute. 
askPlayerToRoll({
  reason: "Search the study",
  diceExpression: "1d100",
  skillName: "Spot Hidden",
  against: { label: "Spot Hidden", value: 45, succeedsOn: "or_lower" },
})

A roll of 23 on that request is stamped Pass: the dice card shows "Spot Hidden ≤45" and the map "23 vs ≤45". The GM picks the side from your rules, so say it plainly in an always on GM Instruction (see Roll-under systems).

Both dice tools take the same dice notation, so your game's mechanics live in the diceExpression:

  • 2d6+3: dice with flat modifiers
  • 4d6kh3, 2d20kl1: keep the highest or lowest N dice
  • 6d6[Pool]: label a dice group so it can be read on its own
  • 1d6[Action]+2d10[Challenge]+3[Wits]: several labeled groups and modifiers in one roll
  • 4dF+2: Fate/Fudge dice (each die lands -1, 0, or +1)
  • 1d20-1d6: subtract one group from another

The GM reads the dice by your game's rules: counting successes in a pool, or comparing action dice to challenge dice. The total is just a convenience sum.

Building your own system? Put your core roll in an always on GM Instruction, such as "resolve checks with 1d6[Action]+2d10[Challenge] plus a stat modifier". The GM rolls whatever your rules call for. If your always on instructions name dice but never a d20, its d20 rolls are refused and it rolls your dice instead.

See The Game Master for GM Instructions and Dice and Rolling for how rolls look in play.

Orbit's tools

Orbit, your assistant, works on the files directly: it reads, writes and reorganises them for you while you build. See Orbit, Your Personal Assistant.

read

Looks at what's saved in your project: open a single item, peek at a folder's contents, or pull in several things at once. This is how Orbit finds your files, settings, GM Instructions and the rest of your world.

write

Creates something new or replaces what's already there: new files, new file types, edits to existing ones, or changes to settings, including your GM Instructions, player options and trackers.

When Orbit adds a file and your project has automatic cover images turned on, a cover image is created for that file.

update

Changes only part of an entry instead of redoing the whole file, such as one line on a character sheet or the title of a file. Orbit uses this when a small fix is enough, instead of a full rewrite with write.

bash

A general-purpose way to search, organise and manage your files:

  • List folders and search for text across files
  • Move or rename files and folders
  • Move files to the trash, and make new folders
  • Read or set a game start's starting location and characters

map

Draws and edits maps on your location files: adding areas, pins, and tokens, linking them to other locations, or marking a pin or area as an exit (a door, stairs, a gate) that leads to another location. This is the tool behind requests like "sketch the kingdom's borders on the world map." See Maps and Locations for how maps work.

linkedLocations

Reads and edits how a location sits among the others, beside its map. It can show a location's transport, the place it is inside and every location linked to it; make a location a transport (a ship, a caravan) or turn that off; and link or unlink two locations, saying how they relate and the way between them. This is the tool behind requests like "put a cellar under the kitchens, down a ladder." See Exits and Linked Locations.

viewImage

Looks at an image on a file (a portrait, a map's background) so Orbit can see what it actually shows, such as where the river runs before it places pins. Only models that can see images get this tool.

generateImage

Creates an image from a prompt, following your project's style instructions. Orbit has this tool only while image generation is turned on for the chat.

askUserQuestion

Puts a multiple-choice question (or a few) in front of you and waits until you answer, so Orbit can carry on with your choice. You can pick from short labeled options or type your own answer.

revert

Rolls a file, or a file type's schema, layout, and settings, back to an earlier version from its history. Useful when an edit went wrong: ask Orbit to undo it rather than rebuilding the old content by hand. Reverting always asks for your approval first, and so does clearing a file type's layout. See Version History and Retention for how versions work.

subagent

Spawns parallel helper agents for wide, repetitive jobs, like updating dozens of files at once instead of one at a time. See Assistant Subagents.

Orbit in a game

Inside a game, Orbit can also read the latest game messages, so it can answer questions about what just happened, and the game's current state at /current-state.json: where the party is, who's on the map, and the trackers. It can change the trackers the way you can on the trackers panel: set a value, change a tracker's setup, add one or take one out, and the GM hears about it at the start of your next turn. It can change who's on the map the way you can on the map: move someone, put a character, creature or someone new on it, take someone off, resize them or set their side. Where the party is changes with a turn: tell the GM where you go, or set out from the map.

PreviousTrackersNextThe Research Tool