# Engine core How `loadRuleset`, `computeSheet`, `listOptions` and `applyChanges` behave. The calls' inputs and outputs are in [engine-interface.md](https://opencharacterformat.org/spec/engine-interface/) and [`../schemas/engine/`](https://github.com/pixelqueue/opencharacter/tree/main/packages/spec/schemas/engine/). This chapter fixes the algorithms, so every engine computes the same sheet from the same character. Parts marked **PROVISIONAL** may change once more games are modeled. ## loadRuleset Input: pack releases in load order (later packs win). Output: a ruleset, or errors. 1. **Check the packs.** - Each pack's `specVersion` must not be newer than the engine's (`spec-version-unsupported`). - A pack may appear only once (`duplicate-pack`). - Every dependency must be loaded and in range (`missing-dependency`). A dependency may appear anywhere in the load order. - **Families**: a pack not yet expanded (inline, homebrew) has its rules and content expanded with the families it sees (its own and its dependencies' declared values, by name, its own first): family keys, and `fields` that name a `viewFields` set. Each family's values for formulas are its pack's, then each loaded pack's additions (a qualified family name) in load order; `fieldOf` reads an added value's fields in the pack that added it. Problems are `invalid-family`. 2. **Merge the rules.** - Fields, content types, situational choices, result bands, actions, rules-level choices and constraints are keyed by qualified ID (`pack:id`), so packs never collide. Content type names are qualified too, and a type name resolves like any reference. - Tags are the union of all packs' tags. - Settings merge key by key; a later pack overrides an earlier one, and the override is reported in `conflicts`. - Display groups and field hints from later packs override earlier ones with the same ID. - Creation starts are concatenated in load order into the ruleset's `creation`; a later start with the same `id` replaces the earlier one in its place. Each `action` is qualified (`unknown-reference` when it names no rules action), and every parameter the action requires must be in the start's `params` (`missing-param`, data: `param`, `creation`, `pack`). `random` defaults to false. - Template fields are keyed by name. A name another pack declared earlier must have the same `type`, `of` and `values`, else `template-field-mismatch` (data: `field`, `packs`: the earlier pack, then the later); the later declaration replaces the earlier. Their `id` and `set` defaults are qualified in the declaring pack. - Link slots are keyed by qualified ID. A slot whose `pack` is loaded too must declare only fields of that pack and its dependencies, each with the same type, else `link-field-mismatch` (data: `link`, `field`, `pack`). - A follow-up's `create` needs `while` and no `on`, `becomes`, `action`, `changes` or `to`, else `invalid-create-offer` (data: `followUp`, `pack`). Its `link` is qualified like a destination's, and its `start` resolves, once every pack's starts are merged, to the ruleset's start with that `id` (and, when qualified, that `pack`), kept as `:` (`unknown-reference` otherwise). When the slot's `pack` is loaded too, the start's pack must be it or one of its dependencies, else `link-start-mismatch` (data: `link`, `start`, `pack`). 3. **Resolve content.** Every reference in a pack resolves in that pack, then its dependencies, nearest first (`unknown-reference` if nothing matches). After loading, every content ID, type name, field ID and action ID in the ruleset is qualified. This includes the values of `id` and `set` item fields of a content type or of `field`, and their declared defaults (resolved in the content type's pack). A template's values for its base type's fields and for template fields resolve in the template's pack. - **`extends`:** start from the parent item (itself resolved first; `circular-extends` on a loop, `maxExtendsDepth` at most). Then apply the item's own properties: scalars and objects key by key, arrays (`tags`, `effects`, `choices`, …) replaced whole. - **`override`:** the same merge, applied to the target item in place, in load order. When two packs override the same property of the same item, the later one wins and the pair is reported in `conflicts`. - **`hides`:** hidden items stay in the ruleset, marked `hidden: true`. Queries skip them. - **Destinations:** a `to: { link }` names a slot visible from the pack, qualified at load. Changes sent to a link are the linked character's, so their fields and copy types must be qualified IDs already (`unknown-reference` otherwise) and are not resolved in the ruleset. - **Choice tags:** each static tag of a choice step's `tags` and of an `option` effect's `{ choices }` target must be declared by its pack or that pack's dependencies (a tag also declares the tags above it), else `unknown-tag` (data: `tag`, `pack`). Other tags are checked by the build only. - **Tag members:** each tag a declaration's `members` names (a field's, an item field's, a state key's, a parameter's) is checked the same way, and the declaration gets `tagOptions`: the ruleset's declared tags, with the tags above each, that `members` takes, sorted ([rules-and-fields.md](https://opencharacterformat.org/spec/rules-and-fields/#which-tags-a-field-takes)). 4. **Resolve content-only queries.** A query whose `where` reads only `item` is evaluated once against every non-hidden item of its type. Its result (sorted qualified IDs) is stored in the ruleset. Queries that read the character run later. The rules' and items' `standardCopies` queries are always content-only (a `where` that reads anything else is a `formula-error`, cause `unknown-name`). Two items they match whose derived instance IDs are the same are `duplicate-id` (data: `id`, `items`). 5. **Check formulas.** Every formula must parse and type-check as in the build ([formulas.md](https://opencharacterformat.org/spec/formulas/)), resolving field names in its pack and that pack's dependencies. Otherwise the error is `formula-error`: - `data.cause`: the formula error code (`formula-syntax`, `unknown-name`, `type-mismatch`, …); - `data.pack` and `data.formula`; - `path`: the document the formula is in (`/packs//rules` or `/packs//content/`). Formulas are checked once the earlier steps succeed. Loops between formulas (`circular-formula`) are left to the build and to `computeSheet`. The ruleset is plain JSON. Formulas may be kept as text and parsed when first used; the result must be the same. ## A character's homebrew A character file may carry its own homebrew ([characters.md](https://opencharacterformat.org/spec/characters/#homebrew)). Every call that takes a character (`computeSheet`, `listOptions`, `applyChanges`, `startAction`, `continueAction` for the paused action's character, `upgrade`) loads it on top of the ruleset it is given, then works on the result. A character without `homebrew` uses the ruleset as given. 1. **Check what homebrew may not do.** A content item with `override`, or rules with `settings`, is `homebrew-not-allowed` (data: `property`). More content items and rules-level definitions than `maxHomebrewItems` is `safety-limit-exceeded`. 2. **Load it as a pack.** The section is a pack release with the ID `homebrew`, the character's `specVersion`, and every pinned pack the ruleset has as a dependency, in pin order. The loadRuleset steps run for the ruleset's packs plus this one: merge, resolve references (in the homebrew, then in each pinned pack and its dependencies, in pin order), re-resolve content-only queries so homebrew items join them, and check the homebrew's formulas. Its formulas written as text count against `maxHomebrewFormulas`. 3. **Errors.** If anything fails, the call returns `homebrew-error` and computes nothing: one error per load error, with `data.cause` the load code (`unknown-reference`, `formula-error`, `homebrew-not-allowed`, `safety-limit-exceeded`, …), `data.detail` that error's data, and `path` pointing into the character (`/homebrew/content/0`, `/homebrew/rules`; `/homebrew` when the load error has no document). computeSheet returns empty values with the errors; the other calls return their failure. Engines MAY cache the layered ruleset by the homebrew's content and the pins; the result must be the same as loading it fresh. The ruleset must therefore keep what is needed to load more on top: the reference engine keeps the pack releases it was loaded from (`sources`). ## The character as engines see it `computeSheet` and the other calls work on these views of a character. ### Copies and `self` A **copy** is an entry in `features` or `inventory`. Its view as `self`: | Property | Value | | ---------------- | ------------------------------------------------------------------------------------------------------------------------- | | `self.id` | The entry's `id` | | `self.equipped` | The entry's `equipped`, default `false` | | `self.quantity` | The entry's `quantity`, default 1 | | `self.templates` | Qualified IDs of the templates: saved, then kept | | `self.` | Each state key declared by the content type, the item or its templates: the entry's value, or the declaration's `default` | A state key with no saved value and no default is absent (`has(self.key)` is false). In the copy's own actions (their `available` and steps, for actions defined on its content type or item and the rules actions they `use`) and in its follow-ups, `self` also has the copy's [computed values](#computed-values) as `self.`. Content picked or granted on the copy sees the copy's computed values there too, since its `self` is that copy. A roll effect's `roll.self` doesn't have them. ### Items and `item` The item a copy holds, as `item`, is the base item merged with the copy's templates: | Property | Value | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `item.id` | The base item's qualified ID | | `item.type` | The content type's name, unqualified (`weapon`) | | `item.tags` | The base item's tags, then each template's (less its `removeTags`) | | `item.` | Each item field, read by its declared type. `integer`, `decimal`, `boolean` and `dice` fields are formulas evaluated with `item` (the base item) and `character` bound. A dice field becomes a dice value. A field the item doesn't set takes its declared `default`, read as if the item had written it in the content type's pack; with no default it is absent | A template's `fields` are merged over the base item's: each template in the copy's order replaces the values it gives, a field of the base item's content type or a template field. Its values are read like an item's own, with `base` bound to the base item alone, in the template's pack. A template's `null` removes the field: it is absent (no `default` applies) unless a later template sets it again. A template field the content type doesn't declare and no template sets takes its declaration's `default` (read in the declaring pack), else is absent; this holds for every item's `item`, with or without templates. Everywhere a copy's `item` is read (effects, actions, state bounds and defaults, computed values, the candidates of a choice step over copies and its `steps..item`, display groups) and in `copy.fields`, the fields are these merged ones. In a template's formulas, `item` is the merged item and `base` is the base item alone; its field values also see `prior`, the item as merged before it. A template's `removeTags` take tags away in template order before its `tags` are added. The templates are the copy's saved ones, then those content keeps on it ([content.md](https://opencharacterformat.org/spec/content/#kept-templates)). ### `character` `character.creating` is the file's `creating`, false when absent. `character.inventory` and `character.features` are lists of copies. Each is `{ id, item, type, equipped, quantity, state }`, with `item` the qualified ID and `type` the content type name. `character.applied` is the file's `applied` entries in file order. Each is `{ id, source, active, state }`: `source` the qualified content ID, `active` the saved flag (default true), `state` the saved values, each state key the source's content type or item declares read by its type, with the declaration's `default` when unsaved. It is **raw**: an entry an immunity blocks is listed as saved, so reading it never depends on the decision it feeds, and activation conditions may read it. The copy aggregates (`countCopies`, `sumCopies`, `maxCopies`, `minCopies`) see each copy as the `copy` root: these keys plus `tags`, `templates` and `fields` (the item fields, as in `item`), inventory first, then features ([formulas.md](https://opencharacterformat.org/spec/formulas/#over-copies)). ### Links The calls that compute the sheet (`computeSheet`, `listOptions`, `applyChanges`, `startAction`) take optional `links`: by qualified slot ID, a **view** of the character filling the slot, `{ id, values }`. Link values are inputs, like parameters: the engine reads them and never computes the other character. - A slot is **filled** when the character file links it (`links` in the file) or the app passes a view for it. The view's `id` is the passed one, else the saved one. - Formulas read `links.` ([formulas.md](https://opencharacterformat.org/spec/formulas/#context-roots)), where `` resolves in the formula's pack, then its dependencies. A filled slot's view is `id` plus each declared field, nested at the dots of its field ID (`links.crew.upgrades.mastery`). An empty slot is absent: `has(links.crew)` is false. - A declared field takes the passed value whose field ID, without its pack, is the declared ID: an app may pass computeSheet's values as they are (`fitd-crew:tier`) or bare IDs. With no such value it reads its `default`; with no default it is absent, so a formula guards it with `has()`. A saved link with no view passed reads the defaults. - A value of the wrong type, or two passed values with the same field ID, is `invalid-link-value` in `errors` (data: `link`, `field`, `expected`), and the default is used. - A saved link or a passed view for a slot no loaded pack declares is `unknown-link` in `errors`; the rest computes. - Link reads add no dependency edges, so they can't form a `circular-formula`. ### Standard copies The rules and content items may declare `standardCopies` ([content.md](https://opencharacterformat.org/spec/content/#standard-copies)). The engines see the character with them: - **Which.** The rules' standard items are the matches of the rules' queries, in load order, then declaration order, each query's matches sorted, each item once. An item's are the matches of its own queries, held while it has an activation. They are found in rounds: activate with the rules' copies; add the copies of every item now active, in activation order, that aren't there yet; activate again, until a round adds none (at most `maxChoiceDepth` rounds). A copy added in a round stays for that computation. The templates content keeps on copies are found in the same rounds: each round also adds, for every active `keepsTemplates` entry whose `when` holds, its template on each matching copy that hasn't it. The rounds end when a round adds neither a copy nor a kept template. - **Instance ID:** the item's qualified ID with the colon and dots as hyphens. - **Saved or not.** An entry with a standard copy's ID and item is that copy, saved, in its place in the file. An entry with its ID and another item is `duplicate-id` (path: the entry's `id`) and is left out. Each unsaved copy is an entry `{ id, item }` after the file's entries of its list (`inventory` for carried types, else `features`), in the order above. - **Formula state defaults**. Every copy's state keys whose `default` is a formula and that have no saved value, an unsaved standard copy's and a hand-written or saved copy's alike, are evaluated as `addItem` evaluates them (`item` the copy's item with its templates, saved and kept; input fields only; in the content type's pack) and held on the sheet's entry as `state`, so `self`, `character.inventory` and `copy.state` read them; one that fails to evaluate leaves its key absent. A saved value is read as saved, and the file isn't changed. Everything else (activation, `self`, `character.inventory`, `countCopies`, copy queries, actions, listOptions paths) sees standard copies as entries like any other. ## Activation Content is **active** when it has an **activation**: a reason to apply its effects, grants and choices. Each activation records its content, its `self` (a copy, or none), its **owner copy**, and its scope (`holder` or `applied`): | Source | `self` and owner | Scope | | --------------------------------------------------- | ---------------------------------------------------- | ------- | | An entry in `features` | the entry | holder | | An entry in `inventory` | the entry | holder | | A template on an active inventory or features entry | the entry | holder | | A grant of active content, whose `when` holds | the granting activation's owner | holder | | A picked content option of an applicable choice¹ | the owner of the choice | holder | | A picked inline option | the owner of the choice | holder | | An `applied` entry with `active` not `false` | none (`self` is the applied entry: `id` and `state`) | applied | | A `scope: applied` grant of applied content² | none (`self` is the granting entry) | applied | | The rules (always-on effects, rules-level choices) | none | holder | ¹ Unless the choice says `activate: false`: its picks run the choice's `effects` and are otherwise inactive. ² While its content is active as applied content, unless an immunity blocks it (below). A grant without `scope` (or `scope: holder`) of applied content isn't followed, and a `scope: applied` grant of held content isn't either. An applied entry's `self` is `id` plus its state keys, read as in `character.applied`: declared keys by their type, with their `default` when unsaved. **Activation conditions** decide what is active: grant `when`, choice `when`, and an immunity's `when` and query `where`. They are evaluated before any field is computed, so they may read only `self`, `item`, `character` (its `applied` list included, which is raw), `entry` in an immunity's query, the character functions, and the raw values of **input fields** (saved value, or default). Effects are not applied to those values. A condition that reads a derived field is rejected by the build (`type-mismatch`). **PROVISIONAL.** This keeps activation free of loops: a class grants features by `self.level`, never by a computed field. Activation is found by walking from the copies, the `applied` list and the rules. Each grant and pick is followed once; the same content reached twice by different paths is two activations. Grants and choices nest at most `maxChoiceDepth` deep. **Applied grants**. An applied activation follows its content's grants with `scope: applied` (the content type's, then the item's) whose `when` holds, an activation condition with `self` the entry. Each granted content is activated with scope `applied`, the same entry (its ID is the activation's `entry`) and `self`, and `item` the granted content; its own `scope: applied` grants are followed in turn. Granted activations come right after their entry's, depth first, as a copy's grants follow the copy. **Immunities**. Content and the rules may declare `immuneTo`: applied content the character can't be affected by, as `items` or a `query`, with an optional `when`. Immunities are decided during activation, in this order: 1. The holder activations are found first: the rules, then the copies with their templates, grants and picks. 2. Each holder activation's immunities with `scope` `holder` (the default; the rules' have no scope) whose `when` holds become **active**, in activation order, then the order they are written in. 3. Of the `applied` entries with `active` not `false`, one whose source matches an active holder immunity is **blocked**. The others are **candidates**. A candidate's immunities are its source's immunities with `scope: applied` whose `when` holds, and a candidate **blocks** every other applied entry (never itself) whose source one of them matches, whether that entry comes before or after it in `applied`. 4. The candidates are decided in rounds until none is undecided. Each round: 1. Every undecided candidate whose blockers (the candidates that block it) are all blocked, or that has none, becomes active. 2. Only if step 1 made none active: every undecided candidate has an undecided blocker, so some of them block each other in a cycle. The earliest undecided candidate (in `applied` order) that blocks itself through a chain of undecided candidates becomes active. 3. Every undecided candidate that an active candidate blocks is blocked. Each round decides at least one candidate, so the rounds end, and the result depends only on the `applied` order. Once all are decided, the active candidates are activated in `applied` order and their immunities become active. A blocked entry is not activated, so none of its effects, grants or choices apply, and its immunities block nothing. 5. **Applied grants**. A candidate's immunities (step 3) include those of the content its applied grants reach, except grants an active holder immunity blocks. While an active entry is activated, each content its applied grants reach is **blocked** when it matches an active holder immunity or an immunity of another active candidate, as an entry whose source it were would be (the query's `entry` is the granting entry). A blocked grant is not activated, nor what it grants; the entry that grants it stays active. It is reported `immune` with `data: { entry, item }`: the granting entry and the granted content. So an applied immunity blocks a matching entry wherever it is in the list, and order matters only between entries that block each other: two that do are decided for the earlier one, and a longer cycle for its earliest member, whose blockers in the cycle then don't count against it. Petrified blocks poisoned whether it comes before or after it; once petrified is removed, the poisoned entry still in the list applies again (the poison was suspended). A source **matches** an immunity when it is in `items` (qualified at load; `unknown-reference` otherwise), or when it is of the query's `type` and the query's `where` holds with `item` bound to the source's item (hidden or not). `when` and the query's `where` are activation conditions, evaluated with the immunity's activation bound (`self`, `item`, `character`, `links`), `item` rebound to the candidate's source in `where`, and `entry` bound there to the candidate entry: `id` and its state keys, as its `self`. So a query can match by who applied a condition (`entry.by`), and a `when` can read `character.applied` (an immunity that lapses while the holder is unconscious). A blocked entry stays in the file; `toggleEffect` and `removeEffect` work on it as before, and it applies again once the immunity goes away. Each blocked entry is reported as `immune`, once per matching immunity ([Pending choices and issues](#pending-choices-and-issues)). **Effects on a set of fields** ([effects.md](https://opencharacterformat.org/spec/effects/#targets)). An effect whose target is `{ fields: { where } }` is one instance per field its query matches, in ruleset field order, each with that field as its target. Everything on this page that says "an effect on a field" applies to each instance: stacking, competing (option ID `<…>@`), breakdowns, `effects` and dependencies. A field whose tags are computed is matched when it is computed: its tags are evaluated first (a failure, an undeclared tag or a loop is the field's error), and an instance whose `where` doesn't hold for them doesn't exist on this sheet, so it neither stacks nor appears in `effects`. **Content type effects and grants.** Wherever an item is active, its content type's effects (minus those the item `suppress`es) and grants apply first, then the item's own. Their competing-option keys are `#type.`. **Choice keys.** An activation reads its choices' picks from its tree. The tree's own item (the entry's item, or a picked option) uses bare choice IDs. A template or granted content in the same tree uses `/`, and its choice paths use that key. ## computeSheet ### Effects The **effect instances** are every effect of every activation whose scope matches the activation's scope (`holder` effects for holder activations, `applied` effects for applied ones), plus each choice's `effects` once per pick (with `pick` bound). An instance's source is `{ type: item | template | rules, id, entry? }`. - Situational effects are not part of the sheet; they apply only when an action rolls. - Effects targeting rolls are listed in `effects`, but they apply only when an action rolls. - Effects targeting incoming changes apply only in `applyChanges`. ### Field values Each field's value is computed on demand and remembered. To compute field F: 1. **Base value.** - An input field takes its saved value, or its `default`. - A derived field with a `formula` evaluates it. - Any other field starts at its `default`, or empty: `[]` for sets, `0` for numbers, `false` for booleans, `''` for strings, enums and IDs, and a dice value with no dice (written `0`) for dice. No field type starts as `null`. 2. **Grants:** for a set field, each active `grant` instance whose `when` holds adds its members. - An `item` grant adds a qualified ID. - A `tag` grant adds a tag. - A `field` grant adds a qualified field ID. - A `query` grant adds every match. - A `formula` grant adds the formula's value. - The result is sorted and has no duplicates. 3. **Set:** - **Collect.** Gather the active `set` instances on F whose `when` holds. - **Stack.** Apply [stacking](#stacking). - **Pick one.** If several remain, they are **competing options**: - **Option IDs:** each option's ID is `#`, the effect's index in its content's `effects` list (or `#` when the effect has one). Two copies of the same content share their option IDs, so a pick can't tell them apart; the earlier copy applies. **PROVISIONAL.** - **Recommended:** the option chosen by the field's `recommend`, or else by `settings.competing.recommend`. `highest` and `lowest` compare values, with ties going to the earlier instance. `first` and `last` use instance order. - **Applied:** the first option, in instance order, whose ID is in the input's `competing` list, otherwise the recommended one. IDs that name no option are ignored. - **Reported:** one `competing` entry `{ field, op: set, options, recommended, applied }`. - The applied value replaces the base. 4. **Add:** the sum of the active `add` instances' values, after stacking. 5. **Multiply:** multiply by each active `multiply` instance's value, in instance order. For an `integer` field, round after each multiplication with the effect's `rounding`, else the field's `rounding`, else `settings.rounding` (default `floor`). 6. **atLeast / atMost:** raise to the highest active `atLeast`, then lower to the lowest active `atMost`. 7. **Round and clamp.** - An `integer` field's decimal result that doesn't come from `multiply` (a formula, or an `add` with a decimal value) is rounded with the field's `rounding`, or else `settings.rounding` (default `floor`). - A derived value outside the field's `min`/`max` is clamped. - For an input field, `min`/`max` check only the saved value. A saved value outside them is reported in `errors` (`out-of-range`) and clamped before effects apply. Effects may then take the final value past them. **Instance order** is the order activations are found: 1. The rules. 2. `features`, then `inventory`, in file order. Each copy is followed by its templates, its grants and its picks, depth first. 3. `applied`. Within one content item, effects keep their written order. An effect's `when` and `value` may read other fields. A field reached again while it is still being computed is a **loop**: every field in the loop gets `error: circular-formula`. A field that reads a field with an error gets that error too. Every other field still calculates. `breakdown` lists, in application order, each instance that changed the value: `{ op, value, source }`. `tags` lists the field's tags on this sheet: its written tags, then those its `{ formula }` entries give ([rules-and-fields.md](https://opencharacterformat.org/spec/rules-and-fields/#tags-from-a-formula)), each once: the tags effects on sets of fields, field parameters and allocate steps match it by. When its computed tags fail (the field then has `error`), it lists the written ones. A field with no tags has none. An app lists a field parameter's options before a roll by these tags. `name` is the value of the field's `nameFrom` string field ([rules-and-fields.md](https://opencharacterformat.org/spec/rules-and-fields/#fields-the-player-names)) when it is a non-empty string (one of only spaces counts as empty), as saved; absent otherwise. The field's text formats it as `{name}`. ### Stacking Instances on the same target with the same `stackKey` form a group. The reserved key `source` means the instance's source content ID, so two instances from the same item share it. Each group is reduced by the policy for its key (`settings.stacking.keys`, else `settings.stacking.default`, else `addAll`): - **`addAll`:** all count. - **`highestOnly`:** only the highest value counts, ties going to the earlier instance. Dice values compare by average (a die averages (sides + 1) / 2, a Fate die 0); a number is its own average. - **`lowestOnly`:** the reverse of `highestOnly`. - **`playerChooses`:** the instances become competing options, as for `set`, with the highest recommended. The group is its own `competing` entry, with its `op` and `stackKey` (the key as written, so `source` for the reserved key), and is picked independently of the field's other groups. Only `computeSheet` reads picks: incoming-change effects, and the sheets that `listOptions`, `applyChanges` and actions compute, keep the recommended option. Instances that don't count are listed in `effects` with `suppressed: true`. Instances without a `stackKey` always count. ### Pending choices and issues For each activation's choices, and the rules-level choices: - **Not applicable:** the choice's `when` is false. - Its picks are reported as `choice-not-applicable`. - Its picked options are not activated. - **Applicable:** the choice's `pick` gives `min` and `max` (an exact count sets both). - With fewer picks than `min` (and `required` not `false`), the choice is **pending**. - With more than `max`, the issue is `too-many-picks`. - **The order of `pending`** is a pre-order walk of the activations: the rules-level choices first, then each activation's own choices in declaration order, each followed at once by the choices of the content and inline options picked in it (in the same order, recursively), then those of the other activations it reaches (its templates and grants), in activation order. A starting rogue is asked its four skills before the Expertise the class grants, and its racket's skill right after the racket, before the class's later choices. A choice step over pending choices, and `finishCreation`'s `too-few-picks` issues, follow the same order. - **`pending`** is the open entries of [the choice list](#the-choice-list), in the same order, each as `{ path, min, max, picked, slot }`, `picked` the number of picks. - **Choice issue IDs:** `choice-not-applicable`, `too-many-picks` and `option-not-eligible` carry `id: /`, where the owner is the content ID of the item that declares the choice (or `rules`), and `source` is the owner's activation. - **Slots**: a slotted choice is one choice per slot, each keyed `-` and gathered in list order where the choice is declared, with `slot` bound in its formulas ([content.md](https://opencharacterformat.org/spec/content/#choice-slots)). Each is pending, applicable or not, and reported on its own, under its key. A pending slot carries `slot: { choice, number }`, the declared ID (whose prompt names it) and the slot's number. computeSheet, `listOptions` and `applyChanges`' `choose` and `unchoose` see the same choices. **Rules issues**, all reported in `issues`: - `prerequisite-not-met`, for each prerequisite of active content (and of picked inline options) that is false, unless the grant or choice that activated it waives them (`waivePrerequisites`). - `id` is the qualified owner plus the prerequisite ID (`5e-srd-5.1:classes.fighter/multiclass`). - `source` is the activation. - `no-eligible-option`, for each pending choice of active content that says `requiresOption` and has no eligible option not yet picked, as `listOptions` lists them. - `id` is the qualified owner plus the choice ID; `data` is `{ path }`. - `source` is the owner's activation. listOptions' trial sheet for an option reports it with the option's prerequisites. - `constraint-failed`, for each rules constraint whose `check` is false; a constraint with `copies` for each copy it fails on, in copy order, with `data.entry`. - `id` is the constraint's qualified ID. - `data` is its evaluated `data`. - `option-not-eligible`, for a picked option that no longer matches its choice's query, and for a picked value that fails its choice's `where` or that its formula no longer lists, and for a pick that fails its choice's `eligible`. - `content-hidden` covers hidden content picked in a choice with `activate: false` too; it belongs to the choice's owner. - `content-hidden`, for owned or picked hidden content. - `immune`, for each blocked `applied` entry and each active immunity its source matches: the holder's, then the active candidates' in `applied` order ([Activation](#activation)). - `id` is the immunity's qualified owner plus its ID (`5e-srd-5.1:features.monk.purity-of-body/poisoned`); for the rules', its pack plus its ID (`5e-srd-5.1:listed`). - `source` is the immunity's activation (for the rules', `{ type: rules, id }` with the same `id`). - `data` is `{ entry, item }`: the applied entry's ID and its source. **More issues**: - `already-picked`, for each pick of an option already picked earlier (in activation order) in another choice with the same `unique` group, unless the option is `repeatable` content. `data` names the earlier choice's path. A local key is the declaring pack's group and a qualified one that pack's; with `uniqueScope: owner`, only the choices of the same owner activation share the group. - `out-of-limits`, for a field whose final value is outside its `limits`. `id` is the field, and `data` is `{ field, limit, value, bound }`. - `too-many-copies`, for a content type whose copies exceed its `copies.max`, and for an item whose copies exceed its type's `copies.perItem` ([Copy limits](#copy-limits)). **Order.** Each issue belongs to an activation: a prerequisite or hidden content to the activation of its content, a choice issue (`choice-not-applicable`, `too-many-picks`, `option-not-eligible`, `already-picked`) to the activation that owns the choice, an `immune` issue to the immunity's activation, and a constraint or a rules immunity to the rules, which come first. A `too-many-copies` issue belongs to the rules too; a `no-eligible-option` issue to the activation that owns the choice. Issues are listed by activation order, then by kind: `prerequisite-not-met`, `no-eligible-option`, `constraint-failed`, `too-many-copies`, `choice-not-applicable`, `too-many-picks`, `option-not-eligible`, `already-picked`, `content-hidden`, `immune`. Issues of the same activation and kind keep the order their prerequisites, constraints, choices and picks are written in; `too-many-copies` issues go by type in ruleset order, a type's `max` issue before its items' in the order of their first copy; `immune` issues follow the `applied` order, then the order the immunities are written in. `out-of-limits` issues belong to no activation and come last, in field order. ### Actions An action is available when its `available` formula (if any) is true. Two kinds of action are listed in `actions`: - **Content actions:** the actions of each activation that has an item: its content type's actions, then the item's own, then its templates'. A holder activation lists those with `scope: holder` (the default); an applied entry's activation those with `scope: applied`, with the entry's ID as `entry` and no `source`. Its actions run with `item` the source's item and `self` the entry (`id` and its state keys, as its effects see it, without computed values). Content an entry grants with `scope: applied` lists its `scope: applied` actions with the entry's ID as `entry` and the content's qualified ID as `source`. - An activation with an owning copy is listed with the copy's `entry`. An action of content picked in a choice or granted to the copy, rather than the copy's own item, also carries `source`: that content's qualified ID. Several picks can then use the same shared action. - An activation with no owning copy (the rules' picks and everything nested in them) is listed with `source` and no `entry`. Its actions run with `item` bound to the content and no `self`, as for rules-level activations' effects. - Each action is listed once per `(action, entry, source)`, so the same content reached by two paths with no copy is listed once. - **Rules actions:** shared actions that no content type or item `use`s, listed without an `entry`. An item action written as `use` is listed under the used action's qualified ID. An action defined inline on an item is listed as `#`. **Order:** content actions come first, in activation order, each activation's actions in the order above. Rules actions follow, in definition order: packs in load order, then each pack's rules files in path order. ### Computed values After every field, each copy's computed values ([content.md](https://opencharacterformat.org/spec/content/#computed-values)) are worked out, copies in instance order (`features`, then `inventory`, in file order), each copy's names in declaration order: the content type's, then the item's and each template's, a later declaration replacing an earlier one with the same name in its place. - A formula resolves names in the pack that declared it (an override's in the overriding pack) and sees `item` and `self` as the copy's effects do, every field (fields never read computed values, so they are all computed first), `character`, `links` and the character functions. `self` has the copy's computed values declared before this one, each as worked out; one that failed is absent. A replacement keeps the replaced name's place, so the values after it read the replacement, and it reads only what comes before the name. - An `integer` value must be an int, a `decimal` value a number (an int becomes a decimal), a `boolean` value a bool and a `string` value a string. - A formula that fails, or gives a value of another type, gives no value and the error `formula-error` (data: `entry`, the copy's instance ID; `name`; `cause`, the formula error code or `type-mismatch`). `copies` maps each copy that has any computed values to `{ : value }`. The same values are `self.` in the copy's actions and follow-ups ([Copies and `self`](#copies-and-self)); an engine may compute them on demand, with the same result. `copyNames` maps each copy whose item or content type has `nameFrom` ([content.md](https://opencharacterformat.org/spec/content/#per-copy-state)) to the value of that state key, when it is a non-empty string (not only spaces); an item's `nameFrom` replaces its type's. Copies without one are left out. ### The activation list `activations` lists every content activation ([Activation](#activation)), in instance order: the rules-level picks, then each copy with its templates, grants and picks, depth first, then the active applied entries with their applied grants. Each is `{ item, entry?, via, scope?, parent?, keptBy?, path? }`: - `item`: the content's qualified ID (the base item; a template is its own activation). - `entry`: the owner copy's instance ID, or for applied content the applied entry's ID; absent for content picked or granted at the rules level. - `via`: how it was reached: `copy` (a `features` or `inventory` entry), `template` (on a copy), `grant` (granted by active content, its `when` holding), `pick` (a content option of an applicable choice that activates its picks) or `applied` (an `applied` entry, or a `scope: applied` grant of one). - `scope`: `applied` for applied activations; absent for holder ones. - `parent`: the index in this list of the activation that granted it, owns the choice it was picked in, or owns the template: the nearest listed one, so content picked in an inline option's choice has the inline option's owner. Absent for copies, applied entries and content picked or granted at the rules level. - `keptBy`: for a template content keeps on the copy, the index of the activation that keeps it (the first, when several do). Absent for a saved template. - `path`: for a pick, the choice path of the pick (`change.schema.json#/$defs/choicePath`), the picked option last, as `pending` and change paths name it. Inline options, the rules and applied entries an immunity blocks (which aren't activated) aren't listed, nor are the picks of a choice with `activate: false`. A content group's `from: own` members are the holder activations whose item is of the group's type ([display-hints.md](https://opencharacterformat.org/spec/display-hints/)); a template's activation is part of its copy's member. ### The choice list `choices` lists every applicable choice ([Pending choices and issues](#pending-choices-and-issues)), answered or not, in the order of `pending`: the rules-level choices, then each activation's own choices in declaration order, each followed by the choices of what it picked, then those of the activations it grants. Inline options' choices and choices with `activate: false` are listed like any other, and a slotted choice is one entry per applicable slot. A choice that isn't applicable isn't listed (its picks are `choice-not-applicable` issues). Each is `{ path, owner, id, slot?, type?, min, max?, picks, open }`: - `path`: the choice path (`change.schema.json#/$defs/choicePath`), as `choose`, `unchoose` and `listOptions` take it. - `owner` and `id`: as a choice step's `needs.choice` ([engine-actions.md](https://opencharacterformat.org/spec/engine-actions/)): the qualified key root of the choice's owner (the content ID, `:rules` for a rules-level choice, and for a choice nested in an inline option the owner's root plus `.choices..options.