Grants
A grant answers a question a plain selection can’t: when a player picks this component, what becomes theirs? It is the identity-assignment escape hatch — picking a role card during a setup phase can hand that player the card, the matching pawn, and a starting position, all at once.
The motivating case is role selection. A perSeat, component-targeted selection
over the role cards, with grant.ownership assigning the picked card to the
player, grant.matchProperty: 'role' binding the pawn whose properties.role
matches, grant.placeAt sending the role card to the player’s role area, and
grant.matchPlaceAt sending the pawn to its start city. The components carry a
shared properties.role so the card and pawn can be matched.
A grant only lives on a component selection (targets: 'component') — a zone
outline has no component identity to assign. It is a deliberately narrow tool;
reach for it only when picking is the identity choice.
How to edit in the Studio
Grants are authored as part of a component-targeted selection on the Layout
tab’s phase inspector. Because they bind on a component’s properties, make sure
the components you want matched (e.g. each role’s card and pawn) share the same
property key/value first — see component rendering
for where component properties live.
Fields
All fields sit under a selection’s grant object, which is itself (.optional()):
| Field | Type | What it does |
|---|---|---|
ownership | boolean (.optional()) | Set the picked component’s ownerId to the selecting player. Requires the selection’s scope: 'perSeat' (a shared pick has no single owner) |
placeAt | { zone, cell? } (.optional()) | Move the picked component to this zone (and optional grid cell) |
matchProperty | string (.optional()) | Also grant every sibling component whose properties[matchProperty] equals the picked component’s value for that key (e.g. 'role' binds the matching pawn) |
matchPlaceAt | { zone, cell? } (.optional()) | Move the property-matched siblings to this zone (and optional cell). Requires matchProperty — no match key, no siblings to place |
Two rules the schema enforces: a grant is rejected unless its selection
targets: 'component'; ownership is rejected unless scope: 'perSeat'; and
matchPlaceAt is rejected without a matchProperty to match on.
Related
- Selections — grants ride on a component selection
- Phases — the staged context a granting selection runs in