# Actions at run time How `startAction` and `continueAction` run an action: building and rolling each roll, choices, branches, proposed changes and outcomes, pausing at checkpoints, and replaying from answers. Action definitions are in [dice-and-actions.md](https://opencharacterformat.org/spec/dice-and-actions/); call shapes are in [`../schemas/engine/`](https://github.com/pixelqueue/opencharacter/tree/main/packages/spec/schemas/engine/). **PROVISIONAL** where marked. ## Starting an action `startAction` input: `ruleset`, `character`, `action` (`id`, `entry?`, `source?`, `followUp?`), `params`, `situational`, `policy`, `links` (the views filling the link slots; [engine-core.md](https://opencharacterformat.org/spec/engine-core/#links)), `participants` (the other characters taking part, by role; below), `answers` (answers to replay, one per pause; [Replaying from answers](#replaying-from-answers)) and, outside the JSON shape, an optional **dice function**. 1. **Find the action.** - A rules action has its qualified ID (`5e-srd-5.1:saving-throw`). - An action defined on an item is `#`. - An action reached through a content type or an item's `use` is listed under the used action's ID with the copy's `entry`; it runs with that copy's `item` and `self`. - An action of picked or granted content also names that content as `source`; it runs with that content's `item` and the owning copy's `self`. - An action of content with no owning copy (picked in a rules-level choice, or nested in such a pick) is named by `source` alone, with no `entry`; it runs with that content's `item` and no `self`. - The action must appear in `computeSheet`'s `actions` for this character, with the same `entry` and `source`; otherwise the result is `unknown-action`. - **`followUp`**: the offer the run takes up, an `id` from computeSheet's `offers` for this character, as the offer's `action` gives it; otherwise the result is `unknown-follow-up`. For an ephemeral offer, the finished run's `proposedChanges` end with `{ to: self, step: '', change: { type: clearFollowUp, id } }`, so applying them deletes the stored entry in the same batch. A run that fails, pauses for good or whose changes are never applied clears nothing. A derived offer needs no clearing: the action's changes end its condition. 2. **Parameters.** Each declared parameter takes the app's value. A `use` that fixes a parameter wins over the app's value. Missing required parameters are `missing-param`; wrong types are `wrong-type`. - A **field parameter** (`type: id, of: field`) takes a field ID, qualified or local to the action's pack. A field outside its `where` set is `invalid-option`. Formulas see `params.` as `{ id, type, tags, value }`: the field view its `where` sees (the qualified ID, the field's type and its tags on the sheet, written and computed, `[]` if none) and the field's computed value. - A **content parameter with `where`** (`type: id, of: `) takes an item ID, qualified or local to the action's pack. An ID that isn't an item of the type, or whose item doesn't match `where` (`item` the candidate, the character's fields, `action.item` and `action.self` the action's own), is `invalid-option` (data: `param`, `option`). Formulas see `params.` as the qualified ID. 3. **Situational choices.** `situational` maps qualified situational IDs to values. Missing choices take their `default`. Formulas see `situational.` by local ID. A choice whose `available` is false must be left at its default (false for a boolean); selecting it is `situational-unavailable` (data: `situational`). Availability is checked once, when the action starts, against the character as given; changes the action proposes don't affect it. 4. **Participants**. `participants` maps the roles the action declares to lists of views (`{ id, values }`), each taken by the app from that character's own computed sheet. - A role the action doesn't declare, or a count outside the role's `min` (default 0) and `max` (default unbounded), is `invalid-participants` (data: `role`). A role not given has no participants. - A view `id` used twice across the call is `duplicate-id` (data: `id`). - Each declared field reads the view's value with the same field ID, its pack prefix ignored, as a link's does ([engine-core.md](https://opencharacterformat.org/spec/engine-core/#links)); undeclared values are ignored. A value of the wrong type, or two values with one field ID, is `invalid-link-value` (data: `role`, `id`, `field`, `expected`): an action has no way to report it and go on, so it fails. - The participant may use any pack set: the engine reads only the view. - `participants.` is the role's views in input order; a view is `id` plus each declared field, nested at the dots, with its default when the view lacks it, else absent. A nested action (an `action` step) has the participants the step passes on (below), else none: its roles are `[]`. 5. **Run the steps** in order, as below. `when: false` skips a step. Each step reads the character as given, or with `sheet: proposed` the [proposed sheet](#the-proposed-sheet). The **context** of a formula in an action: - `item` and `self`: the copy's views (absent for a rules action run without an entry; content without an entry has `item` and no `self`); for an applied entry's action, `item` is its source and `self` the entry (`id` and its state keys); - `character` and `links`; - `params`; - `situational`; - `participants.`, and in an `each` step `participant`; - `steps.`: results of earlier steps; - `flags.`: set by branches and by picked choice options. Fields, `character`, `item` and `self` are read from the step's sheet: the character as given, or the proposed sheet (below). Where `item` and `self` are rebound to something else (a choice step's candidates, a formula a change passes on), the action's own context is `action`: `action.item` and `action.self` (absent when the action has none) and `action.step`, the current step's `{ id, tags }`, its tags evaluated. ## The proposed sheet An action proposes changes and never applies them. A step with `sheet: proposed` (default `given`) reads the character as those changes would leave it: 1. **Building it.** Before the step evaluates anything, `when` included, the engine takes the character as given and applies to it, in order, every change proposed so far in this call with `to: self` and no `character`: from earlier steps, from nested actions, from a parent action that runs this one through an `action` step, and from earlier picks of the same choice step. They are applied as one `applyChanges` batch, not strict, with the call's links; the sheet is then computed with those links. Changes for a role, a target or a link are never applied: they belong to another character. Follow-ups the batch would trigger are neither listed nor run; the proposed character's stored follow-ups are never read. 2. **What reads it.** Every formula and source of the step: fields, `character`, the character functions (`countCopies`, `sumFields`, …); `self` and `item`, the action's own copy as it is on that sheet (absent if a change removed it); a choice step's content, copies and added options, and the `where`, `prefer` and `recommend` over them; an allocate step's fields, their values and `max`; a roll step's parts and roll effects (the effects active on that sheet). `params`, `situational` (decided when the action starts), `participants`, `links`, `flags` and `steps` don't change. 3. **Per pick.** A choice step with `sheet: proposed` builds the sheet again before each pick, since each pick proposes its changes at once. `picks` still counts the step's picks. 4. **Errors.** A batch that fails (a `choose` on a copy that isn't there, a `finishCreation` proposed before the step while issues remain, an adjust whose incoming-change effects would roll dice, since the batch has no dice function) fails the action with `proposed-changes-failed` (data: `step`, the step's path, and `error`, the batch's error with its `path`). Only a pack bug reaches it. 5. **Replay.** The proposed sheet follows from the inputs and the recorded answers, so a replay rebuilds it exactly; `state` keeps its shape. An engine may cache the sheet per count of proposed changes. Nested steps decide for themselves: a `branch` with `sheet: proposed` reads it in its cases' `when` and `flags`, and each step in its arms reads its own `sheet`. ## Computed tags Every tags list with `{ formula }` entries (a roll step's, a roll part's, an action step's, a roll effect's added item's, a proposed change's) is evaluated when its step runs, in order: a literal tag is itself; a formula giving a string is one tag, and one giving a list of strings is each of them, in order, in its place (none for an empty list). A tag already in the list isn't added again. A computed tag that isn't declared (by the ruleset's packs, a tag declaring the tags above it) fails the action with `unknown-tag` (data: `tag`); a value that is neither a string nor a list of strings with `type-mismatch`. ## Roll steps A roll step is built, then rolled, then classified. ### Building the roll 1. **Parts.** Each part whose `when` holds becomes roll items: - **`dice`** evaluates to a dice value. Each dice term becomes a dice item, and a non-zero flat part becomes a flat item. - **`value`** becomes a flat item. - **`field`** names a field: a flat item with that field's value and source. A part that reads a numeric field (a `field` part, or a `value` that is a single field reference: the parts whose source is the field) **carries** that field's `add` instances that have a `stackKey` and counted on the sheet, for step 2. Items take the part's `source` (default: the field for a single-field `value` or `field`; otherwise the item or rules the action belongs to) and the part's `tags`, with computed tags evaluated. A part with `multiplied: false` marks its items `multiplied: false`, its `ifEmpty` dice included. 2. **Roll effects.** The candidates are: - the character's active instances whose target is `rolls` and whose tags match one of the step's tags (computed tags evaluated); - the effects of the selected situational choices. A boolean choice is selected when true; an integer or enum choice when it differs from its default. An instance with `from: self` applies only to rolls made by its own copy: its source entry is the action's entry. Each effect's `when` sees `roll` (`item`, `self`, `tags`) and the action context, `participants` and `participant` included, with `item`, `self` and the content's other roots the effect's own, as an option effect's are: the Bracers of Archery's `self` is the bracers' copy, whichever weapon attacks. The action's own item, copy and step are `action.item`, `action.self` and `action.step`. Stacking applies, by stack key as in the sheet, with the parts' carried instances: - For each stack key that some `add` roll effect of this roll has (`source` meaning each source's own group, as on the sheet), the group is the roll's `add` effects with that key **plus** every part's carried instances with that key. It is reduced by the key's policy, as on the sheet (`playerChooses` takes the recommended option, as everywhere but computeSheet). - A roll effect that doesn't count adds no item, as before. - A carried instance that doesn't count any more comes off its part's item: the item's value is lowered by the instance's value, and the item lists it in `dropped` (`{ source, value }`, [roll-item.schema.json](https://github.com/pixelqueue/opencharacter/blob/main/packages/spec/schemas/roll-item.schema.json)). Carried instances whose key no roll effect has stay in the field's value untouched, so a roll without keyed roll effects is built exactly as before. A carried instance can only lose: the roll's group holds every instance the sheet's held, so one the sheet suppressed is suppressed again. The value comes off the field's final value, so a field whose keyed effects are later multiplied or bounded gets the drop after those; typed-bonus fields are sums, where the two agree. - **`add`** adds an item: dice or flat, with the effect's source and evaluated `tags`. With `multiplied: false`, its items, dice and flat, are marked `multiplied: false`. - **`rollModifier`** collects one modifier; they apply in the order below. `multiply` modifiers stack by key, compared by `factor`. - **`atLeast`** and **`atMost`** (without `tally`) bound the total once it is rolled (below). - **`set`** with `parts` replaces parts, before anything above reads them (below). **2a. Replaced parts**. For each part, the counted `set` effects whose `parts` tags match its items' tags are stacked by key; of those left, the one `settings.competing.recommend` names (default `highest`, by value) replaces the part's items with its value's items, carrying the part's tags. Their source is the effect, or the field when the value is a single field reference, which the item then reads (it carries that field's keyed instances, as in step 1). The first new item lists the replaced items, as built, in `replaces`. This happens before the carried instances and `add` effects of step 2 are worked out. **2b. Die steps**. Each dice item from a part moves along d4, d6, d8, d10, d12 by the sum of the counted `stepDie` modifiers that reach it (all, or those whose `parts` match; stacking by key, compared by `steps`), stopping at the ends. Other sizes stay. The item records `steppedFrom`. 3. **Pool dice.** Each `poolDice` adds `count` dice to its part's first dice item (the part named by `part`, else the first dice part). In effect order, each added die records the effect as its face `source`. 4. **Empty pools.** A dice part whose first dice item has 0 dice after pool dice is replaced by its `ifEmpty` dice, if it has one. `empty` is then true. 5. **Advantage and disadvantage.** Count the sources of each kind. A `noAdvantage` modifier sets the advantage count to 0, and a `noDisadvantage` the disadvantage count. Then apply `settings.rollModifiers.advantage`: - **`cancel`** (default): with both, nothing; otherwise one extra die of the present kind. - **`net`:** the difference gives the kind and the number of extra dice. - **`stack`:** one die per source. Both kinds at once is the error `conflicting-roll-modifiers`. The extra dice go on the roll's **main dice item**, its first dice item. If that item has no keep or drop modifier, it gains keep-better: `keepHighest` (or `keepLowest` when the step says `better: low`) of its count before the extra dice, reversed for disadvantage. If it already has one, only its count grows. 6. **Multiply dice:** each `multiplyDice` multiplies the count of every dice item except those marked `multiplied: false`. 7. **Reroll, minimum face, explode:** each adds its dice modifier (`reroll`/`rerollOnce` at `below` or less, `minimum`, `explode`) to every dice item that doesn't have one of that type. 8. **Given faces**: the first counted `setFaces` on an item (the main dice item, or the first dice item of a part its `parts` match) gives it its first faces, evaluated now; one not on the die is `invalid-face`. ### Rolling Dice items are rolled in order, each by the formula language's rules ([formulas.md](https://opencharacterformat.org/spec/formulas/#rolling-dice-values)), with faces from the checkpoint. - **Given faces**: an item's given faces are its first, before any face from the checkpoint, and are marked `set: true`. The checkpoint asks only for the rest: the need's `dice` counts exclude them, and a roll with nothing left to ask doesn't pause or record an answer (later dice, a reroll or an explosion, are asked for as usual). The log entry's `faces` lists only supplied faces. - **Faces:** under an automatic policy, faces come from the dice function. When paused, the app supplies one face per die (see [Checkpoints](#checkpoints-and-the-policy)). A roll with no dice items is not a checkpoint: no policy applies, it never pauses, it takes and records no answer, and its log entry has `by: engine` and no `faces`. - **Multiply**: each item's value (a dice item's rolled value with its sign, a flat item's value), except the items marked `multiplied: false`, is multiplied by every counted `multiply` factor in turn, in effect order. A result whose value before was an integer rounds after each multiplication by the effect's `rounding`, else `settings.rounding` (default `floor`). Faces are unchanged; the item's `value` is the multiplied value and its `factor` the product of the factors. Tallies aren't multiplied. - **Result:** the roll's total is the sum of every item's value (multiplied), a dice item counting with its term's sign. A `split` change sums the same values per tag. - **Bounds**: the highest counted `atLeast` roll effect raises the total, then the lowest counted `atMost` lowers it. Stacking applies per op. The bounded total is `total`, and the band reads it; the items and faces are unchanged. - **The step's result** (`steps.`): - `total`; - `faces`: every face of every dice item, in roll order, dropped and rerolled included; - `kept`: kept faces; - `empty`; - `items`: the itemized roll; - `tallies`: each roll tally visible from the action's pack, by name (below); - `bounds`: each bound that changed the total, in order, `{ source, op, value }` (`[]` if none), and `unbounded`, the total before them; - `band`: the first band of `bands` whose `when` holds, with `roll` bound to this result. A set with a `value` evaluates it once first, with `roll` bound to this result, and its bands see it as `roll.value`; - `bandValue`: that value, when the step's set has one (the log entry records it too); - `bandSet`: the qualified ID of the band set the step classified by (`5e-srd-5.1:attack`), when the step has `bands` and a band held. An app names the band `bands...name` in the set's pack. - **Roll tallies**: after the roll, each declared tally is summed from the roll effects that target it (`target: { rolls, tally }`) and match the roll as other roll effects do: from 0, every `add` in instance order, then the highest `atLeast`, then the lowest `atMost`. Stacking applies per tally and op, as for other roll effects. Tallies never change `total`, `faces` or `kept`. A tally nothing added to is 0. ### Classifying an earlier roll again A roll step with `of` builds and rolls nothing and is not a checkpoint: 1. **The roll.** `of` is a path relative to the action (the running action's own prefix added): a roll step of the action, or of an action it ran (`check/roll`). In an `each` step, when the path's first step is an `each` step over the same role, it names that step's run for the current participant (`check[1]/roll`). A roll that didn't run (its step was skipped, or isn't reached yet) leaves the step without a result, as a false `when` does. At load, the path's first step must be a step of the action (`unknown-reference`, kind `step`). 2. **The result** is the earlier roll's `total`, `faces`, `kept`, `empty`, `items`, `tallies`, `bounds` and `unbounded`, with `band`, `bandValue` and `bandSet` worked out afresh by the step's `bands` in the step's band context (its flags, `params`, `steps`, `participants`, and in an `each` step `participant` and the participant's flags). A `split` may read it as it would the earlier roll. 3. **The log** gets an entry `{ step, action, kind: dice, by: engine, of, items, total, band?, bandSet?, bandValue?, summary }`, `of` the earlier roll's full path; no `faces`. Its summary is worked out as for any roll step, before the band. ### The roll summary Every roll step has a **summary**: what the roll is rolled against, worked out when the roll is built, before any face is rolled, in the step's band context (the running action's `flags`, `params`, `steps`, `participants`, `situational`, fields and the rest: everything but `roll`). It is output only: replay never reads it, and it never fails the action. ```yaml summary: bandSet: mothership-1e:check # the step's band set, qualified; absent when it has none value: # a set with `value`: that formula, resolved bands: # the bands that can still hold, in the set's order - band: success when: roll.total < 34 && roll.total < 90 # the condition, resolved tests: # when it's a conjunction of plain comparisons of the roll - { of: roll.total, compare: lt, value: 34 } - { of: roll.total, compare: lt, value: 90 } flags: { target: 34 } # the running action's flags at the step, as data ``` - **Resolving a condition.** Each maximal subexpression of a band's `when` (or the set's `value`) that doesn't read `roll` is evaluated and replaced by its value as a literal, and the tree is printed back with the standard printer, as a proposed change's action-time values are ([Changes steps](#other-steps)): strings quoted, lists as list literals, dice values in dice notation. Literal guards then decide as evaluation would: `false && x` is `false` and `true || x` is `true`; `true && x`, `false || x`, `x && true` and `x || false` are `x`; `c ? a : b` with a literal `c` is the taken branch; `!` of a literal is its negation. A subexpression that fails to evaluate, or gives a map (no literal), is left as written. - **Which bands.** The set's bands in order, leaving out each whose resolved condition is `false` (it can't hold) and stopping after the first whose resolved condition is `true` (no later band can be reached). A set whose first band holds regardless of the roll (a `rolled` band when there's no DC) is summarized as that one band. - **Structured tests.** When a band's resolved condition is `true`, `tests` is `[]`. When it is a conjunction (`&&`) of comparisons each between a roll path (`roll.total`, `roll.value`, `roll.unbounded` or `roll.kept[]`) and a number literal, `tests` lists them in order, the roll path on the left (`34 > roll.total` is `{ of: roll.total, compare: lt, value: 34 }`). `compare` is a code: `lt` (`<`), `le` (`<=`), `gt` (`>`), `ge` (`>=`), `eq` (`==`). Any other condition (`!=`, `%`, `||`, arithmetic on the roll, a function of the faces) has `when` only. - **Wording.** The engine outputs codes and data, never display text. An app words a band's tests with the pack's optional `bands...condition` text (ICU arguments `value`, the first test's value, and `value1`, `value2`, … for each test in order), else the spec's `compare.` text ([`i18n/en.yaml`](https://github.com/pixelqueue/opencharacter/blob/main/packages/spec/i18n/en.yaml), argument `value`) per test. - **Flags.** The running action's flags (of the action `needs.action` and the log entry's `action` name) at the step, each as data as `outcome.data` reports values (a dice value in dice notation); `{}` when there are none. Present on every roll, banded or not. Enclosing actions' flags aren't repeated: a panic check a save runs has the panic check's own. - **Where it appears.** At a dice pause, `needs.summary`, for the roll the pause is for (a pause for more dice mid-roll carries the same one); on each roll log entry, a dice-less roll's included, `summary`, the same one. **Previewing a roll.** No call previews a roll. To show what a roll is against before the player rolls, an app starts the action with `policy: { dice: 'pause' }`, reads `needs.summary` from the first dice pause and drops the paused result; startAction is pure, so nothing changes. Params, participants and situational choices count as they would. The preview summarizes the first roll the run reaches (an earlier roll in a nested action comes first, named by `needs.action`); a choice step with no usable recommendation, an allocation or a handoff before it pauses first; and a target set after the dice (Fate's opposition, read by a dice-less step) appears only in that step's log entry. A pack that wants the target in the preview sets it in a flag before the roll. ## Other steps - **choice:** see [Choice steps](#choice-steps). - **allocate:** see [Allocate steps](#allocate-steps). - **branch:** the first case whose `when` holds, else `else`. Its `flags` are evaluated and set, then its steps run. A nested step's path is `/`. With `each`, it runs per participant and its flags are per participant ([Each steps](#each-steps)). - **changes:** a change with `forEach` is first repeated: its formula is evaluated to a list (`type-mismatch` otherwise), and the change is resolved once per element, in list order, with `x` bound to the element; an empty list proposes nothing. Each copy counts toward `maxActionSteps`. A change whose `when` is false (for each element, with `forEach`) is skipped. Each other proposed change is resolved: - formulas are evaluated (`value`, `by`); - a computed field (`field: { formula }`, `set` and `adjust` only) is evaluated to a string (`type-mismatch` otherwise) and qualified against the action's pack, as a literal field is. For `to: self` or a role it must name a field of the ruleset (`unknown-field`) that is an input (`not-input-field`), else the action fails (data: `field`: the string as computed, or for `not-input-field` the qualified ID). For a link it must be a qualified ID (`unknown-field` otherwise) and is passed on unchecked, as a literal one is; - `entry: self` becomes the action's entry; `entry: { formula }` is evaluated to an instance ID (anything but a non-empty string is `type-mismatch`) and passed on as written, for the actor, a role, a target or a link alike: the character receiving the change checks it as it would a written ID (`unknown-id`, …). `path.entry` may be computed the same way; - an `addItem` entry object is resolved: `item` is evaluated to a content ID and qualified against the action's pack; `quantity`, `equipped` and each `state` value are evaluated; `templates` are qualified; a pick's `option` given as `{ formula }` is evaluated to a string or number (`type-mismatch` otherwise), the rest of `choices` passed on as written. Without an `id`, the copy gets `-`, the smallest `n` ≥ 1 that the character and the action's earlier `addItem` changes don't use, so a replay gives the same IDs. An `item` that names no content, or a template, is the error `unknown-reference` (data: `id`); - an `applyEffect` has its `source` evaluated to a content ID and qualified against the action's pack, as an `addItem`'s `item` is (no content, or a template, is `unknown-reference`, data: `id`); `active` is evaluated to a boolean (`type-mismatch` otherwise) and each `state` value evaluated; `id` is passed on as written. Without `id`, the action picks none: applyChanges gives the entry its ID on the character receiving it ([engine-core.md](https://opencharacterformat.org/spec/engine-core/#applychanges)), so a change for a target needs no knowledge of the target's file. A `toggleEffect`'s `active` is evaluated the same way; - an `equip`'s `equipped` is evaluated to a boolean (`type-mismatch` otherwise), for the copy `entry` names or for every copy `copies` matches; an `applyTemplate`'s or `removeTemplate`'s `template` is evaluated to a content ID and qualified as `source` is, but must name a template (`unknown-reference` otherwise, data: `id`). `setExtension` can't be proposed: extension data is an app's; - an `offerFollowUp` names its follow-up: one the content declares (or its content type) whose added option or added changes propose it, else the content defining the action (`#`), else the rules (a local ID qualified against the action's pack). It is resolved to `{ type: offerFollowUp, followUp, source?, params? }`: the qualified follow-up ID (`#`, `:#`, `:`), the content's source as computeSheet names it, and `params` evaluated (one giving `null` left out). It is proposed `to: self` whatever the step's `to`. A follow-up the owner doesn't declare, or a derived one, is `unknown-reference` (data: `followUp`); - `entry: picked`, in a choice step's `changes` over copies, becomes the picked instance ID; - a `choose` or `unchoose` resolves its `path`: `path.entry` like `entry` (`self`, `picked` or an instance ID; left out for a rules-level choice) and `path.choice` as written, or, given as a formula, evaluated to a list of strings (`type-mismatch` otherwise); `option` is evaluated; - a change aimed at copies (`copies: { type, where }`) has its `type` qualified against the action's pack and is passed on with `where`; its `by` or `value` is evaluated now unless it reads `self` or `item`, in which case it is passed on as a formula for applyChanges to evaluate per copy. A string value evaluated now is passed on as a quoted string literal; - a change aimed at applied entries (`applied: { where, limit? }`: a `removeEffect`, `toggleEffect`, `setState` or `adjustState`) is passed on the same way: `where` and a `by` or `value` that reads `self` or `item` as formulas, `limit` as written; - a formula that reads `batch` is passed on too: a `by` or `value` under `copies` or `applied`, and an `applyEffect`'s `state` value, which is passed on as `{ formula }` for applyChanges to evaluate with `item` the source's item, the receiving character's fields and `batch` ([engine-core.md](https://opencharacterformat.org/spec/engine-core/#what-the-batch-did)); - a formula passed on (`copies.where`, `applied.where`, a `by` or `value` that reads `self`, `item` or `batch`, and an `applyEffect` state value that reads `batch`) may read fields, `self`, `item` and `character`, and also `steps`, `flags`, `params` and `action`. Those four are substituted now: each maximal name or member path rooted at one of them (index expressions inside the path included) is evaluated in the action and replaced by its value as a literal, and `has()` by `true` or `false`. The tree is then printed back with the standard printer: strings quoted, lists as list literals, dice values in dice notation. A formula that reads none of them is passed on as written. A map has no literal, so a path to one is `type-mismatch`. A path that fails (a flag no case set is `no-such-key`) fails the action like any formula error, unless a substituted `has()` guards it: when a guard that is now a literal (`false && …`, `true || …`, `false ? … : …`, `!` of one) skips the operand holding the failed path, that operand is dropped with the guard (`has(flags.x) ? item.k == flags.x : true` becomes `true`), as evaluation would skip it. The returned change holds only names applyChanges knows, so a log shows the value (`'arrows'`), not the name (`flags.ammo`); - fields are qualified; - tags are evaluated. A `split` adjust becomes one change per tag group; its field is always written out (a computed one is a load error, `formula-error` with cause `type-mismatch`). The result is appended to `proposedChanges` as `{ to, step, change }`, where `step` is the path of the `changes` step (`deal`, `panic/stress`); the changes of one split adjust share it. **Releasing held changes**. A step with `release` first proposes changes `hold` action steps hold, then its own `changes`, if any. For each step in `release.steps`, in order, each of its held changes in the order held: when `where` is given it is evaluated with `change` bound to the change's `change` record (as `proposedChanges` lists it, `tags` `[]` when it has none); a change it holds for is released, one it doesn't stays held. A step that didn't run, or holds nothing, gives none. With `combine: true`, released `adjust` changes whose `by` is a number and that are equal in everything else (their `to`, `character` and the rest of the change, `tags` in order) are merged: the first keeps its place with `by` the sum (decimals kept to six places), the others go. Each released change keeps its `step`. **Routing.** `to` is `self` (default), `target`, a declared role, or `{ link: }`. - A change for a link carries `to: { link: }` and, when the slot is filled, `character`: the linked character's ID. An empty slot's changes are proposed without `character`. Fields, copy types and `addItem` items in a change sent to a link are the linked character's qualified IDs and are passed on as written; its formulas are evaluated as usual, in the actor's context. - A change for a role (`target` included) carries `to: ` and `character`, the participant's view `id`: in an `each` step over that role, the current participant; elsewhere, the step's changes are resolved once and proposed to each participant in turn, all of the step's changes for the first, then for the next. With no participants they are proposed once without `character`, as before. Their fields and content are resolved in the action's pack, as for `self`, except that a field, content ID (an `addItem`'s `item`, an `applyEffect`'s `source`) or copy type qualified with a pack the ruleset doesn't load is passed on as written, as for a link: the participant's own `applyChanges` checks it. A local or bare ID still resolves in the actor's pack, and an unknown ID of a loaded pack is still `unknown-reference`. The build checks such references against the named pack when the repo has it. - The app applies each change to that character with `applyChanges`, so its own incoming-change effects, absorbing and overflow apply there. - **Changes content adds**: a changes step's `tags` (computed entries evaluated when it runs, with the tags `action` steps running the action add after them, as for roll and choice steps) are matched by content's `changes` effects (`target: { steps: [], from? }`, [effects.md](https://opencharacterformat.org/spec/effects/#targets)). After the step's own `release` and `changes`, each active `changes` instance whose source is a content item or a template, whose target tags match one of the step's (a tag matches itself and the tags below it), whose `from: self` (if any) names the action's own copy, and whose `when` holds, proposes its `changes`, in instance order, `to` its value's `to`, else the step's. Its formulas see what an added option's see: `item` and `self` the content carrying the effect (`entry: self` its copy), the action's own as `action.item`, `action.self` and `action.step` (the step's evaluated tags), and the action's `params`, `situational`, `steps`, `flags`, `participants` and, in an `each` step, `participant`. They are resolved as the step's own changes are, at the step's path (per participant in an `each` step), and held by a `hold` action step like any other. A step with no `changes` and no `release` (only `tags`) is a place content adds to; without matching content it proposes nothing. - **action:** runs the used action with the evaluated `params`, the same character, entry, source and situational choices. Its steps' log entries are nested under `/`. Its outcome is `steps..result` and `steps..data`. Its proposed changes are appended to the parent's; with `hold: true` they are taken off again once it ends and held under the step, after any earlier run's, until a changes step releases them (above). The proposed sheet is then worked out afresh, without them. A pause holds nothing: a replay holds them again. With `as: participant` the step is a [handoff](#handoffs) instead. It also has: - **Parameters.** Each `params` formula is evaluated in the parent's context; one giving `null` leaves its parameter out, as if the app hadn't given it (an optional one takes its default or stays absent, a required one is `missing-param`). A field parameter given an object with a string `id` (a field parameter's view, `params.skillA`) takes that `id`. A dice value is passed as its canonical dice notation (`2d6 + 1`), which a `dice` parameter reads back as dice: a bomb's damage passes whole to the bomb Strike. A handoff's and a follow-up's `params` carry dice the same way. A handoff's and a follow-up's `params` leave out a `null` the same way. - **`source`.** Evaluated to a string (`type-mismatch` otherwise) and qualified against the action's pack as a content ID (kept as written when nothing matches). The action is `use` if it names a rules action, else `#` (an action the content or its type defines). The step reads `computeSheet`'s `actions` for the character on the step's sheet and takes the listing with that action and that `source`, the one with the parent's `entry` first; it runs as `startAction` would run that listing, with its `entry` and `source`. No such listing is `unknown-action` (data: `action`, `source`), so the used action's `available` must hold. Without `source` (or `entry`), the used action runs with the parent's entry and source, as before, and its `available` isn't checked: a helper action only other actions run declares `available: false`, so `computeSheet` never offers it. - **`entry`**. Evaluated to a string, an instance ID (`type-mismatch` otherwise). The step takes the listing of `computeSheet`'s `actions`, for the character on the step's sheet, with the action `use` (as above) and that `entry`, and with that `source` when the step gives one too (with neither, the listing has no `source`); it runs as `startAction` would run that listing: that copy is `self` and its item `item`. No such listing (no such copy, the copy doesn't list the action, or its `available` is false) is `unknown-action` (data: `action`, `entry`, and `source` when given). Not on a handoff: its used action runs on another character, whose copies the actor doesn't know. A replay reads the same listing again. - **`participants`.** Each formula is evaluated to a list of strings (`type-mismatch` otherwise). Each must be the `id` of a participant of the running action, in any role (`invalid-participants`, data: `role`, the nested role). The nested action's roles are then built from those views as the app passed them, exactly as in [Starting an action](#starting-an-action) step 4: an undeclared role, or a count outside the role's `min` and `max`, is `invalid-participants`; an ID twice in the nested call is `duplicate-id`; each declared field is read from the view. Roles it doesn't give are `[]`. - **`tags`.** Evaluated in the parent's context and added, after their own and without repeats, to the evaluated tags of every roll step and choice step of the used action and of the actions it runs in turn (those add their own `tags` after these). Everything that reads those steps' tags sees them: roll effects, situational choices' effects, a choice step's added options and `action.step.tags`, and policy rules. Allocate steps don't get them. - **`situational`**. Maps situational choice IDs (qualified at load against the action's pack, as fields are; an unknown one is `unknown-reference`, kind `situational`) to formulas, each evaluated in the parent's context. The used action, and the actions it runs in turn, see the running action's situational values with these in their place, as if the app had selected them: formulas read them as `situational.`, and a selected choice's effects apply to the rolls it is offered for. A value that doesn't fit the choice's type (a boolean, an integer, or one of an enum's `values`) is `wrong-type` (data: `target`, the qualified ID, and `expected`). Availability isn't checked: the pack says so. Not on a handoff (schema), where the participant's player answers their own. - **outcome:** evaluates `result` (a string) and `data`, then finishes the action. Steps after it don't run. When the action declares `results`, a result that isn't listed (or, for `{ bands: }`, isn't a band of that set) is the error `undeclared-result` (data: `result`), for a nested action too. An action that ends without an outcome step finishes with `outcome: {}`. ## Each steps A `roll`, `choice`, `changes`, `action` or `branch` step with `each: ` runs once per participant of the role, in input order: - `participant` is bound to the current view, and `when` is evaluated for each participant. With no participants the step doesn't run, and `steps.` is absent. - The run for participant `i` has the path `[]` (`saves[1]`); its checkpoints, nested steps and log entries use it (`check[0]/check`). Policy `rules` match it by tags and by that path. - `steps.` is the list of per-participant results in participant order, null for a participant whose `when` was false. Inside a later `each` step over the same role, it is the current participant's result instead, absent when that participant was skipped. Inside the step's own run for participant `i`, `steps.` is the list of the results of runs `0` to `i - 1`, null where `when` skipped one, and absent in the first run. A `split` in such a step reads the current participant's roll. - A `branch` step with `each` picks its case per participant and keeps its `flags` per participant: inside a later `each` step over the same role, and in the case's own steps, `flags.` is the current participant's value (absent where the branch set none); elsewhere it is the list in participant order, null for a participant the branch's `when` skipped or whose case doesn't set it. A flag a step sets without `each` later replaces the list. The case's steps run within the participant's run, at `[]/`; their results are lists by participant, as an `each` step's, and they may not have an `each` of their own (`unknown-role` at load). Cast-spell's outcome per target is one such flag. - `outcome` steps don't take `each`; `maxActionSteps` counts each run. ## Handoffs An `action` step with `each: ` and `as: participant` is **handed off**: the participant runs the used action on its own character, and the engine doesn't run it. 1. Its `params` are evaluated in the actor's context. The used action (`use`, qualified at load) must exist in the ruleset (`unknown-action`), and types them: a missing required one is `missing-param`, a wrong type `wrong-type`. 2. Its `participants`, when given, are evaluated as an `action` step's ([above](#other-steps)), except that an ID may also be the running character's own `id` (`character.id`). The used action's roles check them: an undeclared role, a count outside the role's `min` and `max`, or an ID that is neither a participant of the running action nor the running character is `invalid-participants` (data: `role`); an ID twice is `duplicate-id`. 3. Without a recorded answer, the action **pauses** with `needs`: `kind: handoff`, `step` (the indexed path), `action` (the defining action), `participant` (`{ role, id }`) and `run: { action, params, participants? }`, `participants` the evaluated IDs by role (only the roles given). A handoff always pauses: the policy doesn't apply. 4. The app runs `run.action` on the participant's own character, with that character's packs, situational choices, policy and dice, and with a view of each character `run.participants` names (from that character's own computed sheet, as for `startAction`), and answers `continueAction` with the finished `outcome` (`{ result?, data? }`). A `result` the used action doesn't declare is `answer-mismatch`. If the participant's packs lack the action, what the app runs instead is its business. 5. The step's result is `steps..result` and `.data`, as for a nested action. The handed-off run's proposed changes are the participant's, for the app to apply; the actor sees only the outcome. ## Choice steps A choice step has one source of options (a fourth, pending choices, is [below](#choice-steps-over-pending-choices)): | `options` | Offers | Option ID | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------ | | a list `[{ id, when?, changes?, to?, flags? }]` | the written options whose `when` holds, in written order | the written `id` | | `{ content: { type, where? } }` | the ruleset's content of `type` (qualified against the action's pack), by qualified ID, hidden content left out | the qualified content ID | | `{ copies: { type, where? } }` | the character's copies of `type`, inventory then features, each in file order | the instance ID | - **Added options**. A step with `tags` also offers, after its source's options, the options content adds: each of the character's active `option` effects (in instance order, as for roll effects) whose target tags match one of the step's evaluated tags ([tag matching](https://opencharacterformat.org/spec/effects/#tag-matching)), whose `from: self`, if given, names the action's entry, and whose `when` holds. Its ID is `#