Navigation

The three render tiers (goto, update, action) and when to use each.

Reference: Navigation macros: (goto:), (update:), (action:), and transitions.

Navigation: goto, update, action

Every link calls one of three navigation macros. Choosing the right one keeps the UI feeling responsive and avoids unnecessary rebuilds.

Macro	Rebuilds	When to use
(goto: PassageName)	Everything	Moving to a new location; major scene change
(update: PassageName)	text + options zones	Continuing a conversation; showing new dialog
(action: PassageName)	Only zones the passage writes to	Stat/item reactions; effects that don't change the scene

@zone(options)
(link: "Leave the bar")[(goto: MainStreet)]          // scene change
(link: "Ask about the rumors")[(update: Bar_Rumors)] // continue conversation
(link: "Pocket the coin")[(action: Player_TakeCoin)] // silent side effect

When in doubt: use (update:) for anything that changes what the player reads, (action:) for anything that just changes a number or inventory.

What goes inside a link body

When the player clicks a link, everything in the [...] block executes. Two things have special behavior:

A (set: $global to expr) preEffect is evaluated at render time, while temp variables are still in scope, then applied to state at click time. This is how you capture a temp variable from a loop before it expires:

// (set:) captures _id at render time; everything else fires at click
(link: "Equip")[
    (set: $world.invSelectedItem to _id)
    (action: _Inv_EquipWeapon)
]

One navigation macro goes at the end: (goto:), (update:), (action:), (modal-open:), or (modal-close:).

All other macros ((add:), (notify:), etc.) defer to click time. Temp variables are no longer in scope by then, so promote them to globals with a (set:) preEffect if you need them:

// No temp vars — (pay:) and (notify:) both fire at click time
(link: "Buy a round")[(pay: 5)(notify: "You spend 5 gold.")(action: Bar_BuyRound)]

// With temp var — capture it first, use the global at click time
(link: "Equip")[
    (set: $world.invSelectedItem to _id)
    (action: _Inv_EquipWeapon)
]

:: _Inv_EquipWeapon
(add: $equip.weapon, $world.invSelectedItem)
(notify: (get: $item, $world.invSelectedItem, "name") + " equipped.")
(modal-close:)

An inline reveal happens when a link body has no navigation macro: it executes at click, and its content replaces the link in place.

(link: "Inspect the painting")[
    A pastoral scene. Someone has drawn a mustache on the shepherd.
]