State-design hierarchy
Can current units, leaders, recruits, or objects answer the question?
├── yes → query current game state
└── no
├── need one fact? → scalar variable
├── need ordered progress? → counter + completion flags
├── need unit XP/type/traits? → store the unit
├── need a permanent ability/attack? → unit object or recruit-list change
└── need temporary search data? → working variable, clear immediately
Cross-scenario branch and party state
| Name | Scope | Representation | Purpose | Cleanup |
|---|---|---|---|---|
wesfolk_leader_store | 01 → 02 | Stored unit | Preserve Wesfolk leader XP/state | Consumed and cleared in 02 |
have_lady | 02 → 07 | Boolean | Whether Lady Outlaw is currently in the party | Cleared after Jessene reconstruction |
lady_store | 02/05 → 07 | Stored unit | Preserve absent companion type/XP/variation | Cleared in 07 |
escape_choice | 03 → route/05 | Scalar | Select 04a or 04b | Cleared in 05 prestart |
last_done | 04 or 17 → next hub/arc | String | Identify most recently completed route/quest | Cleared after convergence |
jessica_store | 19 → 20/21 fallback | Stored unit | Remove canonical Jessene and restore later | Cleared after unstore |
Ka’lian hub state
| Name | Scope | Representation | Purpose | Cleanup |
|---|---|---|---|---|
num_done | 15 → 16 loop | Counter | Number of completed quests | Cleared at final Ka’lian visit |
the_dragon | 15/17a → 16 | Boolean | Dragon quest completion | Cleared at final Ka’lian visit |
a_beach | 15/17b → 16 | Boolean | Lizard Beach completion | Cleared at final Ka’lian visit |
troll_hole | 15/17c → 16 | Boolean | Troll Hole completion | Cleared at final Ka’lian visit |
cursed_isle | 15/17d → 16 | Boolean | Cursed Isle completion | Cleared at final Ka’lian visit |
Scenario-local objective and phase state
| Name | Scope | Representation | Purpose | Cleanup |
|---|---|---|---|---|
Have_Ruby | 06 | Boolean | Join lich-death and chest conditions | Cleared at victory |
previous_ai_position | 08 | String state machine | Clearwater allied posture | Cleared at victory |
First_Ship / Second_Ship / Third_Ship | 08 | Booleans | Boarding windows | Cleared on departure or victory |
lich_free | 09 | Boolean | Dormant lich faction activated | Cleared at scenario end |
have_book | 09 | Boolean | Gate Haldric’s sewer exit | Cleared at scenario end |
dragon_awake / dragon_dead | 17a | Booleans | Boss phase and completion | Cleared before hub return |
got_enemies / got_treasure | 17a | Booleans | Full-clear and cave reward state | Cleared before hub return |
queen_awake | 17d | Boolean | Switch Cursed Isle objective | Cleared at victory |
chest_obtained | 19 | Boolean | Random chest recovery | Cleared at victory |
Dynamic director working state
| Name | Scope | Representation | Purpose | Cleanup |
|---|---|---|---|---|
random | 04a / 17c / 17d | Scalar | Choose randomized setup permutation | Cleared after setup/victory |
triggered_scorpion_locs | 04a | Array/container | Prevent repeat swamp ambushes | Cleared at victory |
possible_serpent_locs / serpent_loc_i | 14 | Location array/index | Choose fair serpent spawn | Cleared after spawn |
side_N_top_enemy_count | 19 | Per-side scalar | Approximate peak army strength | Cleared after trigger |
side_N_undead_backup_triggered | 19 | Per-side boolean | Allow one wave per front | Cleared at victory |
undead_spawns_so_far | 19 | Counter | Choose global wave composition | Cleared at victory |
next_corpse_spawn_turn / next_skeleton_spawn_turn | 22 | Future-turn scalar | Randomize recurring pressure | Cleared after firing |
wc_loc / skele_loc / skele_from / skele_type | 22 | Working values | Place recurring undead | Cleared after spawn |
Presentation and extraction state
| Name | Scope | Representation | Purpose | Cleanup |
|---|---|---|---|---|
stored_Jessene | 18 | Temporary stored copy | Create Jessene in Hiding duplicate | Cleared inside cutscene |
aethyr_store | 21 | Temporary type store | Animate Aethyr entrance | Cleared immediately |
last_orc_leader | 22 | Stored unit | Preserve surviving witness for escape | Consumed during victory |
escape_boat | 22 | Coordinate container | Select side-specific ship route | Consumed during victory |
haldric_s | 23 | Stored unit | Animate current Haldric type into epilogue | Cleared after unstore |
Objects and recruit lists are also state
| State mechanism | Campaign example |
|---|---|
| Permanent unit object | Ruby of Fire and Storm Tridents |
| Object removal | Scenario 19 removes ruby_of_fire from Haldric |
| Persistent recruit-list change | Wesfolk, Peasant, and merfolk recruitment unlocks |
| Current-unit query instead of flag | Scenario 10 checks whether either wizard leader remains |
| Unit overlay | Aethyr visibly carries the forged treaty |
Cleanup review checklist
- Every temporary random number, location array, and stored copy has a named cleanup site.
- Cross-scenario storage is cleared only after a successful unstore or reconstruction.
- Branch flags survive until all consumers have run.
- State that can be derived from units is not duplicated in a boolean.
- Objects and recruit access are tested after advancement and save/load.
The machine-readable atlas is bundled at assets/state-lifecycle.json.