Mutations¶
Responsibility¶
The mutation subsystem defines mutation types and branches, prerequisites and conflicts, categories, variants, enchantments, attacks, body changes, activation, acquisition, removal, and how traits modify a character.
Entry points¶
Read src/mutation.h, src/mutation.cpp, and src/mutation_data.cpp. JSON loads into
mutation_branch and related registries; character application and UI live in focused mutation
and character files.
Data ownership¶
Registries own immutable mutation definitions. A Character owns acquired trait state,
variants, activation and charges; caches derived from traits belong to the character and must
be invalidated through normal mutation APIs.
Dependencies¶
Mutations depend on JSON IDs, body parts, enchantments, effects, vitamins, items, martial arts, spells, character stats, events, and save migration.
Lifecycle¶
Definitions load, check, and finalize; mutation selection resolves prerequisites/conflicts and category rules; character state applies or removes the trait; active mutations process costs; the result persists with the character.
Invariants¶
Referenced IDs resolve; prerequisite/conflict graphs remain valid; trait state and derived body/stat caches agree; activation costs cannot underflow; and variant identity survives save round trips.
Extension points¶
Prefer mutation JSON, EOC, enchantment, and existing mutation effects. Native code is warranted only for a reusable behavior not expressible by data, with graph validation and character tests.
Serialization¶
Definitions deserialize from data; acquired traits and their state serialize in the character save. New durable state needs defaults and migration for old trait representations.
Tests¶
Use mutation tests plus character modifier, body, enchantment, vitamin, effect, and save-related tests. Cover acquire/remove symmetry and every prerequisite/conflict edge changed.
Performance¶
Trait-derived calculations occur in character update and UI paths. Invalidate narrow caches when the mutation set changes instead of rescanning every definition each turn.
CCB divergence¶
CCB mutation data and legacy mod IDs are compatibility boundaries. Upstream mutations require dependency-graph, body-part, and save review against the CCB data set.
Technical debt¶
Mutation effects span data, character caches, UI, and hard-coded hooks. New work should migrate reusable behavior toward declarative contracts without silently changing existing traits.