Designing progression
Craft has no leveling of its own. The GM has no rule for XP or level-ups: a character advances only by the rules the world writes, and the GM follows those. Progression is built from the same pieces as any other mechanic: stored fields on the sheet, tables on the files that own them, computed fields for what follows from the level, GM instructions for when XP is earned, and a script for the level-up itself. This guide says which piece does which job and how they fit.
The pieces have their own docs: references and computed fields, GM instructions, scripts and script cards. The general pattern (a rule, a home for the state, a view, a procedure) is in Building a world. The rest of a system (core roll, combat, resources): designing a game system.
Choose the model
Decide first what moves a character forward and who moves it. Each model stores different things:
| Model | What the sheet stores | What moves it |
|---|---|---|
| XP thresholds | XP, and the level (stored or computed) | XP awarded for what happens; the level follows the table |
| Milestones | The level only | The GM raises it at story moments the world names |
| Spending points | Points unspent, and what was bought | Points earned in play; the player spends them on a card or by hand |
| Ranks or tiers | A rank, often an enum | A rule naming what earns the next rank |
| Advancement by use | A count or a mark per skill | A rule saying when a use counts, and what a full count brings |
Pick one. A world can mix two (XP for levels, points for skills), but each extra track is another rule the GM has to follow every session.
Where each piece lives
| Piece | Where it goes |
|---|---|
| XP, level, unspent points, the choices made | Stored fields on the character's sheet |
| The level table (XP per level, HP per level, slots by level) | Rows on the file that owns the rule: the class, or a rules file |
| What follows from the level (proficiency, maximums, what is unlocked) | Computed fields on the sheet |
| When XP is earned, and how much | A GM instruction, or a script that runs after the story |
| The level-up's steps and choices | A player script with a card, or a procedure when the choices need judgment |
| Levels across the party | Read from each sheet, never copied |
The character's fields go in the file type's Schema tab. GM instructions go in the world's Game Master place (the crowned die on the workspace's left rail).
There is no guided level-up screen like character creation's creation flow: a script's card is the level-up's screen.
Store the level, or compute it from XP
Both work. Each costs something:
- A computed level follows XP exactly and can't drift. But nobody can set it: not the player, not the GM, not Orbit. It moves only when XP does, so a milestone or a "start at level 3" means changing XP to match. And a reference filter can't read it: filters see only stored fields, so a schema with a picker filtered by a computed level is refused.
- A stored level can be raised by hand, by the GM, at a milestone or by a script, and pickers can filter by it. But something has to raise it: a rule or a script. Everything that follows from it should be computed, so the level is the only number that changes.
For a level-up with choices (a stat to raise, a feature to pick), store the level and raise it with the level-up script. For pure XP thresholds with nothing to choose, a computed level is simpler:
{
"level": {
"type": "number",
"expression": "(load($self.class)?.levels ?? []).filter(row => row.xp <= ($self.xp ?? 0)).at(-1)?.level ?? 1"
}
}
Either way, store what can't be worked out again: a rolled hit point gain, a stat the player chose to raise. Those are stored fields the level-up changes, never computed ones.
Progression tables as data
Keep each table as rows on the file that owns it, one row per level, and pick the row with an expression. A class file holds:
{
"levels": [
{ "level": 1, "xp": 0, "proficiency": 2 },
{ "level": 2, "xp": 300, "proficiency": 2 },
{ "level": 3, "xp": 900, "proficiency": 2 },
{ "level": 4, "xp": 2700, "proficiency": 2 },
{ "level": 5, "xp": 6500, "proficiency": 3 }
]
}
The character reads it with a stored level:
{
"proficiencyBonus": {
"type": "number",
"expression": "(load($self.class)?.levels ?? []).filter(row => row.level <= ($self.level ?? 1)).at(-1)?.proficiency ?? 2"
},
"nextLevelXp": {
"type": "number",
"expression": "(load($self.class)?.levels ?? []).find(row => row.level == ($self.level ?? 1) + 1)?.xp"
}
}
nextLevelXp is empty at the top of the table, and needs a row for
every level. Scripts read it too, so the thresholds live in one place.
One table read by many fields beats thresholds written into ternaries
(level < 5 ? 2 : 3): adding a level, or a class with its own pace, is
then new rows, not new expressions. More on the pattern:
Tables as data and
the expression language.
Unlocking abilities and spells
Give each thing that unlocks the level it needs, and let the level do the rest:
Features of a class are rows on the class, each with a
minLevel. A computed list on the character keeps those it has reached:(load($self.class)?.features ?? []).filter(f => (f.minLevel ?? 1) <= ($self.level ?? 1)). Keep them as rows when the character needs their fields: an expression can't load a file that a loaded file points at.Spells, feats and talents with their own files get a
minLevelfield (and a class reference when they belong to a class). The character's picker filters on both:{ "fileTypeSlug": "spell", "filter": [ { "op": "eq", "left": { "scope": "target", "path": "class" }, "right": { "scope": "source", "path": "class" } }, { "op": "lte", "left": { "scope": "target", "path": "minLevel" }, "right": { "scope": "source", "path": "level" } } ] }Both sides must be stored fields. A filter only narrows what the picker offers: a reference that fails it (added by hand, or before the character changed class) still saves. A rule that must hold goes in the level-up script, which can refuse. See Filters.
The sheet shows a section from a level with a visible condition on the level (
{ "$state": "/level", "gte": 5 }), or a repeat over the computed list. Layouts see computed values, so this works with either kind of level. See Visibility and Repeats.
Earning XP
Say exactly what earns XP and how much. Left to the GM's judgment, awards come out uneven from one session to the next. Two ways:
A situational instruction for a moment the story shows: "When the party wins a fight or finishes a quest". The GM reads it on that turn and changes the XP fields itself.
{ "when": "situational", "trigger": "When the party wins a fight or finishes a quest", "body": "Award XP to each character who took part: 50 for an easy win, 150 for a standard one, 400 for a hard one, 800 for a deadly one. Add it to their XP." }A script that runs after the story, for an exact award every time. An award never changes what happens, so it waits for
afterNarrationTrigger: the GM tells the turn first, and the script runs if the turn met its moment. A script that decides what happens goes inbeforeNarrationTriggerinstead.// XP for each kind of win. const XP_BY_CHALLENGE = { easy: 50, standard: 150, hard: 400, deadly: 800 }; export default defineScript({ description: "Gives each character named XP for a fight won or a quest finished, by how hard it was, and says who now has the XP for their next level.", afterNarrationTrigger: "The party wins a fight or finishes a quest.", input: { characters: { type: "array", items: { type: "string" }, description: "Each party member's name or slug" }, challenge: { type: "string", enum: ["easy", "standard", "hard", "deadly"] }, }, async run({ characters, challenge }, { game }) { const gained = XP_BY_CHALLENGE[challenge]; const ready = []; for (const name of characters) { const hero = await game.files("Character").get(name); if (!hero) continue; await hero.update({ xp: (hero.xp ?? 0) + gained }); if (hero.nextLevelXp != null && hero.xp >= hero.nextLevelXp) ready.push(hero.$name); } return { gained, readyToLevelUp: ready }; }, });The script's result tells the GM who can level up.
"Character"is the world's character type: use its own name.
A trigger names a moment in the story, never a number. The check that brings situational instructions in reads the story, not the sheets, so "When a character reaches 2,700 XP" never fires. For a milestone, name the moment: "When the party completes a chapter's main quest, each character gains a level."
The level-up itself
A level-up with exact steps (add the level, roll hit points, pick a stat) is a player script with a card. The GM runs it, the card shows what changed, and the player makes the choices on the card's buttons, which run the script's actions without a GM turn:
// The die each level adds to max HP.
const HIT_DIE = "1d8";
export default defineScript({
description: "Raises a character one level when their XP has reached their next level: adds the level, rolls max HP, then the player picks a stat to raise by 1 on the card. Refuses when they haven't the XP.",
beforeNarrationTrigger: "A character with the XP for their next level rests, or the player asks to level up.",
visibility: "player",
waitsForPlayer: true,
input: {
character: { type: "string", description: "The character's name or slug" },
},
async run({ character }, { game }) {
const hero = await game.files("Character").get(character);
if (!hero) throw new Error("No character called " + character + ".");
if (hero.nextLevelXp == null) throw new Error(hero.$name + " is at the highest level.");
if ((hero.xp ?? 0) < hero.nextLevelXp) {
throw new Error(hero.$name + " needs " + hero.nextLevelXp + " XP for the next level.");
}
const level = (hero.level ?? 1) + 1;
const hp = await game.roll(HIT_DIE, { reason: hero.$name + ": hit points for level " + level });
await hero.update({ level, maxHp: (hero.maxHp ?? 0) + hp.total });
return { id: hero.$id, name: hero.$name, level, hpGained: hp.total, raised: null };
},
card(result) {
const stats = ["might", "finesse", "wit"];
return {
type: "Frame",
props: { eyebrow: "Level up", title: result.name + " reaches level " + result.level, icon: "star" },
children: [
{ type: "Hero", props: { label: "Level", value: result.level, tone: "critical", caption: "+" + result.hpGained + " max HP" } },
{
type: "Steps",
props: {
items: [
{ label: "Roll hit points", detail: "+" + result.hpGained, status: "done" },
{ label: "Raise one stat by 1", detail: result.raised ?? "", status: result.raised ? "done" : "current" },
],
},
},
{
type: "Actions",
props: {},
children: stats.map((stat) => ({
type: "Button",
props: { label: "+1 " + stat, variant: "choice", selected: result.raised === stat, disabled: result.raised !== null },
on: { press: { action: "raise", params: { stat } } },
})),
},
],
};
},
actions: {
raise: {
input: { stat: { type: "string", enum: ["might", "finesse", "wit"] } },
async run({ stat }, { game, result }) {
if (result.raised) throw new Error(result.name + " already raised " + result.raised + ".");
const hero = await game.files("Character").get(result.id);
if (!hero) throw new Error(result.name + " is gone.");
await hero.update({ stats: { ...hero.stats, [stat]: (hero.stats?.[stat] ?? 0) + 1 } });
return { ...result, raised: stat };
},
},
},
});
- The script changes only stored fields: the level, max HP, the stat. Proficiency, unlocked features and the next threshold are computed, so they follow at once.
- It refuses when the rule isn't met. A thrown error saves nothing, and the GM tells the player why.
- The action checks for itself. A player can press an old card again:
the
raisedflag in the result stops a second raise. More on trusting a press, picks held on the card before a Confirm (points to spend), and a card that starts the GM's turn: Actions. - The GM hears each press at the start of the next turn, with what it changed.
To check it, open the Test tab under the code, fill in the input and press Run (⌘/Ctrl+Enter), once at the lowest level, once in the middle and once at the top of the table.
Use a procedure instead when a level-up needs judgment more than steps: a new title the story grants, a talent that must fit what the character did. The procedure says what changes and what the player chooses, and the GM carries it out.
The party's progress
- Show levels from the sheets. A tracker field that lists people
(records, a turn order) can show a value read live from each person's
sheet (
show), so a party roster can show Level beside each name with nothing copied. See Field kinds. - Never copy XP into a tracker. A copy needs a second change at every award and drifts.
- A count that belongs to no one sheet is a tracker: the party's shared renown, milestones reached together. See Trackers.
In play
- Players can change it by hand. A level or XP raised on the sheet (or by asking Orbit in the game) is told to the GM once, at the top of the next turn, and the GM plays from the new values. Computed fields follow the change.
- A game keeps the world it started from. A new table row, a changed field or a fixed rule reaches a game already running only when its owner pulls the update. See Game sync.
Mistakes
- Leaving the amounts to the GM. "Award XP when appropriate" gives different awards every session. Write the numbers.
- Thresholds in ternaries.
level < 5 ? 2 : 3hides the table in an expression. Keep rows on the class. - Filtering a picker on a computed level. Refused when the schema is saved. Filter on a stored level.
- Storing what follows from the level. A stored proficiency bonus drifts from the level the first time someone forgets it. Compute it. Only what was rolled or chosen is stored.
- Awarding XP in
beforeNarrationTrigger. The GM then stops for it before it tells the turn. An award doesn't change what happens: give itafterNarrationTrigger. - A trigger on a number. "When XP reaches 900" never fires: the check doesn't read sheets.
- Numbered fields per level (
spells1tospells9). Use one list with a level on each entry. - A level-up action that trusts the card. Re-read the sheet in the action, and refuse a second press.
Checklist
- One model is chosen, and what moves it is written down.
- XP, the level (if stored) and every rolled or chosen value are stored fields; everything that follows from them is computed.
- Each table is rows on the file that owns it, one row per level.
- What earns XP, and how much, is in a GM instruction or an
afterNarrationTriggerscript. - The level-up is a player script with a card, or a procedure, and refuses when the rule isn't met.
- Pickers that gate by level filter on a stored level.
- The level-up is tested at the lowest, a middle and the highest level.