Improving file types
An audit looks for the places where a type's data model fights Craft: values typed by hand that could be worked out, rules written into one type that belong to another, and presentation built by expressions instead of the layout. The goal is a smaller type where each value is stored once, worked out once and shown by the layout, with every player's choices and current values kept. A good refactor usually makes the schema much smaller, and adding a new class or item afterwards means adding data, not fields.
This guide builds on file types, references and computed fields and layouts. What a schema change does to existing files is in changing a type.
Sort every field
Put each field in one of four kinds before you change anything:
| Kind | What it is | Where it belongs |
|---|---|---|
| Stored state | A choice or a changing fact that can't be worked out | The file's stored content |
| Shared definition | Rules or content many files share | The file that owns it (a class, an item, a feature), reached by a reference |
| Worked-out value | Follows from stored state and definitions | A top-level computed field |
| Presentation | Labels, icons, dot strings, colors, grouping | The layout |
Ask of each field: if this value disappeared, could it be worked out from other data? If yes, it should usually not be stored.
What to look for in the schema
| When you see | Replace it with |
|---|---|
| A total, modifier or bonus typed in by hand | A computed field |
Level thresholds written into an expression (level < 5 ? 2 : …) |
Progression rows on the file that owns the rule |
item1, item2, item3 |
A list with a maxItems cap |
| Many slots that mean different things | One object keyed by slot name (armor, main hand) |
| The same read repeated for each slot or row | One read over the list or object, with map, sum or values |
| A used, max, remaining and display field per resource | One stored state map and one computed list |
| A stored flag, a computed modifier and a display field per skill | One stored map keyed by skill and one computed list |
| One list per level or category | One stored list and a computed grouping |
| An expression that builds dots, badges or sentences | Typed numbers, flags and lists, shown by the layout |
Copies of a referenced file's fields (className, hitDieLabel) |
Nothing, or one computed details object |
A hand-built { name, referenceId } object |
A normal reference field |
A list of { item: <reference> } with no other data in the row |
A plain list of references |
| Branches on a class's or item's name | Data on the class or item files, picked by reference or stable key |
| Bonuses under a different name on every type | One shared shape, such as modifiers, on every type that gives one |
What to look for in the layout
A cleaner schema behind a clumsy sheet is half an audit. Check the layout in the same pass:
| When the layout has | Replace it with |
|---|---|
| Numbered copies of the same block | One repeat over the list |
| A display string (checkbox glyphs, dots) shown as text | The typed field on Toggle, Dots or TrackBoxes |
| A plain number for something that changes in play (HP, uses, ammo) | Stepper, Dots or Progress, so a change is one tap |
| Conditions or tags as text | ConditionToggles or BadgeList |
| References shown as text or a plain table | FileReferenceGrid |
| Ability scores and modifiers laid out by hand | DerivedStatGrid |
| Bindings to fields the audit removes or renames | Bindings to the fields that replace them |
Keep the layout's structure and style, and propose the component that fits each field. Reviewing a layout has the full review.
Breakages that show no error
These give wrong values without a visible error. Look for them on purpose:
- "Could not migrate" fields. When old formula fields were converted
to expressions, a formula that couldn't be translated faithfully became a text
field showing "Could not migrate this formula automatically" with the
original formula in it. That formula, the field's name and where the
layout shows it are the spec: rebuild it as data on the owning type
plus a real expression, or remove it. A field whose expression is only
nullis the same kind of leftover. - Draft references. A reference saved as a bare slug that matched no file points at nothing, so every computed value that loads it falls back to its default. Fix those first, by saving the slug again once the target exists, before judging any expression that reads them (see unresolved references).
- A declared type that doesn't match the result. A field typed as
text whose expression gives a number is
nullwhen read. Make the type match what the expression gives. - A "one or none" shortcut feeding arithmetic. An expression like
rows.length == 1 ? rows.at(0) : …gives the whole list once there are two rows, and the sum built on it quietly becomesnull. Add per row instead:sum(rows ?? [], row => …). - A field read straight off a reference.
$self.armor.bonusis alwaysnull; read throughload($self.armor)?.bonus. A schema saved before this was checked may still have one, and its next save is refused until it is fixed. - A reference read off a loaded file.
load()reads one level deep:load(load($self.class)?.feature)is alwaysnull. When the character needs a feature's fields, give the character its own reference to that feature, or keep the data the character needs on the class itself.
Patterns
The examples below are short. Fuller ones are in the expression language and the layout spec. For designing a new system rather than refactoring an old one, see designing a game system.
Tables as data
Store a level table as rows on the file that owns the rule, and pick the last row that applies:
{
"proficiencyBonus": {
"type": "number",
"expression": "(load($self.class)?.proficiencyByLevel ?? []).filter(row => (row.level ?? 0) <= ($self.level ?? 1)).at(-1)?.bonus ?? 2"
}
}
The class file holds "proficiencyByLevel": [{ "level": 1, "bonus": 2 }, { "level": 5, "bonus": 3 }].
Spell slots, resource maximums, experience thresholds and feature
unlocks work the same way.
Definitions apart from current values
A class owns its resources (rage, ki, spell slots), each with a stable
key, a name and a maximum by level. The character stores only what is
left, in one map keyed the same way: "resourceState": { "rage": { "current": 1 } }.
One computed resources list joins the two, and the layout repeats over
it and sends each edit to /resourceState/{key}/current. When an old
schema stored a used counter, convert it on purpose (often
current = maximum - used) and check it at the character's level.
One map and one list for a family
Eighteen skills don't need eighteen flags, eighteen modifiers and
eighteen display fields. Store one map of what the player chose
(skillProficiencies) and compute one skills list from the skill
definitions. Put the definitions on a rules file when there is one, or
write them into the expression for a fixed set. The layout repeats one
row with a toggle that edits the map.
Lists and slots
Use a list when entries share a role (portentDice, knownSpells,
items with a cap). Use an object when slots mean different things
(armor, mainHand, offHand), and add them up without naming each:
sum(values($self.equipment ?? {}), item => load(item)?.modifiers?.speed ?? 0).
Choose the shape from what the data means, not to shorten an expression.
Rules live on the type that owns them
- Classes own hit dice, proficiencies, spell progression, resources and class features.
- Subclasses own their features and resources.
- Species own movement, senses, traits and modifiers.
- Equipment owns its slot and a modifier shape shared with every other type that gives a bonus.
- Features own their action type, description and minimum level.
The character keeps references and its own current values. Logic uses stable keys or references, never display names: a name is content someone can edit.
A shared shape for bonuses
Give every type that grants a bonus the same modifiers field. Then one
computed activeModifiers list can gather them from species, class,
feats and gear, and each total reads that list, instead of the
character knowing a different field name for every source.
References in their plain form
Declare a reference on the field itself:
{ "boat": { "type": "string", "referencedFileTypeSlug": "boat" } }.
Use a plain list of references unless a row has its own data, such as a
quantity, notes or an equipped flag.
Running an audit
- Read before judging. Read the type's schema and layout, and the schemas of every type its expressions load. Count its files: open the type's folder, or group the file list by type. Read one to three typical files, and check their references are stored references, not drafts.
- Check the numbers. Work out one or two non-trivial computed values by hand from the stored fields, including a file where a list the expression adds up has two or more rows. A value that doesn't add up is a breakage, not a style point.
- Sort and list. Sort every field, then go through both tables and the breakage list above.
- Design the definitions first. Settle shared shapes (
modifiers,resources, level rows) on the owning types, and make sure every field an expression loads exists on each target type. - Design the smallest stored state. Keep inputs, choices, references and state maps. Write an old-to-new mapping for every stored field you rename or merge.
- Report and ask once. Say what is broken or clumsy and what each fix gives, in plain words and outcomes first ("armor class will work itself out", "the sheet goes from 120 fields to 68"), with the exact number of files the change touches. Recommend one plan and ask one yes-or-no question.
- Change the schema, layout and files together. Move every file's stored values by the mapping, and never copy computed or display-only values into stored fields. A change that only adds, removes or rewrites computed fields usually changes no file: confirm it on the typical files. For many files, follow bulk work.
- Check values, not looks. For each rewritten expression, compare a file's value with one worked out by hand, on a file for each branch. Try the lowest, middle and highest level, empty lists, missing references, a changed class or item, and a level going down. Then check the final schema matches the plan: everything meant to go is gone, and nothing was added beyond it.
Ask Orbit to audit a type ("audit my character sheet"). It reports what it found and how many files it would change, and waits for your yes.
Final checklist
- Every field is sorted into one of the four kinds.
- No worked-out value is stored or required.
- No presentation is built by an expression.
- Level tables are rows of data on the type that owns them.
- Repeated fields are a list or a keyed object.
- Types loaded by expressions share the fields those expressions read.
- Every read of another file goes through
load(), one level deep. - Logic uses stable keys or references, never display names.
- Definitions and current values are kept apart.
- References are declared directly, and stored references aren't drafts.
- Every expression's declared type matches what it gives, with deliberate defaults for missing values.
- No "Could not migrate" or
nullplaceholder fields remain. - Every renamed or merged stored field was moved in every file.
- The layout repeats over lists, edits play-time values in one tap and binds no display strings.
- Each rewritten value was checked against one worked out by hand.
- The final schema matches the approved plan.
Mistakes
- Translating a bad model into new syntax. Rewriting
item1 + item2 + item3as an expression keeps the numbered fields. Fix the shape first. - Keeping every field to be safe. Display-only and copied fields go; keeping them invites later expressions to depend on them.
- Changing the schema and leaving the files. Files keep their old values under old names until they are moved.
- Copying computed values into stored fields during a migration. They are dropped, or worse, drift.
- A menu of technical options instead of a plan. The person who asked builds worlds, not schemas. Recommend one plan in plain words.