Craft

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 null is 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 null when 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 becomes null. Add per row instead: sum(rows ?? [], row => …).
  • A field read straight off a reference. $self.armor.bonus is always null; read through load($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 always null. 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

  1. 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.
  2. 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.
  3. Sort and list. Sort every field, then go through both tables and the breakage list above.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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 null placeholder 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 + item3 as 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.