Lookups

A lookup is a calculated field that copies a value from a related entity onto this one. The classic shape: show this character’s homeland by reading the homeland field on their parent character.

Lookups are useful when one entity’s information naturally belongs to another, and you want it to appear on both without typing it twice.

A few use-cases:

• A child character displays their parent’s homeland.
• A faction-member character displays the faction’s founding date.
• A spell displays its school’s alignment.
• A vehicle displays its owner’s current location.

When to use a lookup

Use a lookup when the answer is one specific value, on one specific related entity. Compare:

You want to…	Use
Pull the homeland field from one related character	Lookup
Sum the value field across many owned items	Aggregation
Compute a number from this entity’s own fields	Formula
Stitch values into a sentence	Template

If you’d write the answer with a single word like “the parent’s”, that’s a lookup. If you’d write it with “the count of” or “the sum of”, that’s an aggregation.

Setting up a lookup

1. Make sure the relationship type you’ll walk along actually exists in your world.
2. Add the field that’ll hold the result. Match the type of the source field — if you’re copying a name, make it text; if you’re copying a date, make it a date.
3. Open Management → Entity Types, pick the type, switch to Behaviours, click Add Behaviour.
4. Choose Auto-calculate, target the field you just made.
5. Pick Lookup as the calculation kind.
6. Define the path (the relationship to walk along) and the field to retrieve (which field on the destination entity).
7. Save.

The path: walking along relationships

A lookup walks one or more steps along relationships. Each step (called a “hop”) is a relationship type plus a direction.

For most lookups, one hop is all you need:

Goal	Hop
Parent’s homeland	PARENT_OF (incoming — I am the child)
Faction’s founding date	MEMBER_OF (outgoing — I belong to the faction)
Spell school’s alignment	BELONGS_TO_SCHOOL (outgoing)

Direction matters

Each hop has a direction:

• Outgoing — the link points away from this entity (e.g. I belong to the faction).
• Incoming — the link points toward this entity (e.g. the faction has me as a member).

Same relationship can read either way depending on whose side you’re on. The relationship PARENT_OF is outgoing from the parent’s perspective, incoming from the child’s.

If you’re not sure which direction you want, think about who creates the relationship. If clicking “Set parent” on a character creates a PARENT_OF link from parent to child, then from the child’s perspective the relationship is incoming.

Multi-hop lookups

You can chain hops if you need to. For example, “my parent’s faction”:

1. First hop: PARENT_OF, incoming (I’m the child).
2. Second hop: MEMBER_OF, outgoing (the parent belongs to the faction).

The lookup walks these in order. Each hop’s destination becomes the start of the next hop. The maximum useful depth is 2 — anything deeper gets fragile and slow.

The field to retrieve

After the path arrives at a destination entity, you tell the lookup which field on that destination to copy.

The picker shows fields on this entity’s type, which is a UI limitation — the validator accepts any field name. Just type the identifier of the field on the destination type. If the destination is a Faction, and you want its founding_date, type founding_date.

The result is whatever value is in that field on the destination entity. If the destination has nothing in that field, the lookup result is empty.

Worked examples

Show the parent character’s homeland

• Path: one hop, PARENT_OF, incoming (I’m the child).
• Field: homeland.

Result: whatever’s in the parent character’s homeland field. If the character has no parent linked, or the parent’s homeland is empty, this field is empty.

Show a faction member’s founding date

• Path: one hop, MEMBER_OF, outgoing (I belong to the faction).
• Field: founding_date.

Result: the founding date of the faction this character belongs to.

Show a vehicle’s owner’s location

• Path: one hop, OWNED_BY, outgoing (I’m owned by someone).
• Field: current_location.

Result: whatever location the owner has set as theirs.

A self-referential warning

Some lookup paths walk in a circle and end up back at this same entity. The most common case:

• One hop: MARRIED_TO (a symmetric relationship).
• Field: name.

Walking out via MARRIED_TO from a married character leads back to themselves. The lookup result resolves to the entity’s own name — almost certainly not what you wanted.

The editor flags this with an amber warning. Save is still allowed (you might be testing), but you usually want to add another hop or use a different relationship.

Tips and gotchas

Lookups don’t aggregate. A lookup picks one related entity. If the relationship has many matches, the lookup uses the first one it finds and ignores the rest. If you want all of them, use an Aggregation with LIST.

Match the field type. If the source field is a number, the destination field on this entity should be a number too. Putting a number into a text field works but loses things like comparison and aggregation.

Validation rejects unknown relationships. The editor checks every hop’s relationship name against your world’s relationship types. Typos and bogus names are rejected at save time, not at display time.

Empty source fields propagate. If the related entity exists but has nothing in the looked-up field, your lookup field is empty. Use coalesce(lookup_field, "Unknown") in a downstream formula if you need a fallback.

Where to go next

Aggregations When you want a count, sum, or summary across many related entities.

Relationships The connections lookups walk across.

Common Pitfalls Why the field is empty when you expected a value.