Reference Fields

A reference field points from one file to another. Think of a character wearing a piece of armor, knowing a spell, belonging to a faction, or standing in a location. The character stores the link. The armor, spell, faction, or location stays in its own file.

References keep your project consistent. If you rename the linked file, the reference still points to the same file. You also get a picker instead of typing file names by hand.

When to use a reference

• Has or owns: a character has a weapon, a faction owns a region, or a shop sells an item.

• Knows or is part of: a wizard knows a spell, an NPC belongs to a guild, or a quest belongs to a story arc.

• Something you want to reuse: if the same thing appears in more than one file, it probably wants to be its own file.

Single references and lists of references

Use a single reference when the file should point at one thing. A character might have one current location, one faction, or one equipped helmet.

Use a list of references when the file should point at many things. A character might have known spells, inventory items, active conditions, or relationships with other characters.

To make a list of references, add a List field and set the item type to Reference.

Choosing target file types

Most reference fields should target one file type. For example, a knownSpells field usually points only at Spell files.

A reference can also target multiple file types. Use this when the picker should show files from different types at the same time, like weapons and armor in one equipment list.

You can add a separate filter for each target type, so the same reference field can show Armor where equipSlot is head and Weapons where category is melee.

Filtering the picker

A reference filter narrows what the picker shows. The files still exist in your project, but the picker only offers the ones that match the rules you set.

Use fixed filters when the rule is always the same.

Examples

• Show only Item files where equipSlot is feet.

• Show only Spell files where level is 0.

• Show only Gear files where cost is less than 50.

Use dynamic filters when the rule depends on the file you are editing.

Examples

• On a Character file, show only Spell files where level is less than or equal to this character's level.

• On a Character file, show only Item files where cost is less than or equal to this character's gold.

• On a Location file, show only Encounter files where terrain matches this location's terrain.

• On a Character file, show only Feat files whose class matches this character's class — a filter can compare two reference fields, and it matches when they point at the same file.

In the editor, dynamic filters are the ones that compare against this file's fields. When the field being compared is a list — say each Feat lists several classes — use the includes rule instead: show only feats whose classes list includes this character's class.

Filters shape the picker, but they never break existing data: a reference that stops matching its filter later (the character changes class) stays in place — the picker just won't offer new out-of-rule choices.

Multiple file types or an enum filter?

If the files share the same shape and only differ by a few fields, prefer one file type with an enum field and filters. For example, guards, merchants, and nobles can be one NPC type with a role enum.

If the files are meaningfully different, prefer separate file types and a reference that can target more than one. For example, weapons need damage and range, while armor needs armor class and equip slots. Weapon and armor are also conceptually very different, so they could be considered different enough to be separate types.

Rule of thumb: the more the fields differ between file types, the more separate types make sense. The more they overlap, the more an enum plus filters will feel simpler.

A worked example: a character's spells and inventory

Here is how the pieces fit together for the most common relationship in any game project — a character and the things they know and carry.

• Spells and items are their own file types. A Spell has a level, a class reference, and rules text; an Item has weight and cost. Each spell and item exists exactly once in the project.

• The character stores only links. On the Character type: a class Reference field pointing at Class files, a knownSpells List of References pointing at Spell files, and an inventory List whose rows pair an Item reference with a quantity Number — because the quantity belongs to the relationship ("Mira carries three potions"), not to the item itself.

• Filters keep the pickers honest. Give knownSpells a dynamic filter: only Spell files whose class matches this character's class, and level at most this character's level. The spell picker now offers exactly what this character could legally learn.

• The sheet renders the links as cards. In the layout, a FileReferenceGrid shows the inventory with quantity badges and a built-in add/remove picker; another shows known spells. (See Designing Layouts.)

• Computed fields read through the links. Total carry weight multiplies each row's quantity by the referenced item's weight; edit the item file once and every character's total updates.

The payoff: renaming a spell fixes every character sheet that knows it, editing an item's cost updates every shop that sells it, and no fact about a spell or item is ever written twice.

What it looks like in use

Reference fields show as a picker. Start typing to search the matching files. Existing references appear with their name and image when one is available. Click a reference to open the linked file inline.

Pairing with expressions

Once references are in place, expression fields can read values from the linked files with load(...). A character can calculate armor class from the currently equipped armor, or total inventory weight from a list of item references.

For examples, see Computed Fields.