Skip to content

Game State Runtime Map

Version stamp: 2026-06-24 19:55:57 +04:00

This page documents the current live state owners in the Godot/C# runtime. It is based on the implementation files listed below, not only on design intent.

State Scopes

Scope Lifetime Owner Purpose
Hub session Current hub scene/session GuildHubState Available recruits, selected recruits, selected contract, active hub panel, rerolls
Expedition/run From expedition launch until return/wipe GameState, ExpeditionStateService, NavigationManager Party state, inventory, gold, relics, room map JSON, depth/kill tracking
Combat room Current combat scene CombatBoard plus extracted services Live combatants, initiative, AP, conditions, hazards, zones, rewards
Meta progress Disk-backed, across launches MetaProgressService / PlayerMetaProgress Foothold, unlocked classes/features/floors, quests, guild XP, mastery, runic scrolls, guild seals

Expedition Launch Reset

ExpeditionRoot.InitializeExpedition() creates a fresh expedition from RunLaunchContext, initializes ExpeditionStateService, then calls GameState.SetExpeditionParty().

SetExpeditionParty() is the hard boundary between hub selection and run state. It:

  • Replaces GameState.ExpeditionParty.
  • Clears party state dictionaries, inventory, equipment snapshots, relics, pending camp bonuses, and saved room map JSON.
  • Resets run reward counters: elite kills, boss defeated, max depth reached.
  • Sets starting gold to 500.
  • Creates a PartyMemberState entry for each selected recruit, preserving identity fields such as Id, class, name, race, visual variant, powers, equipment, HP, XP, and recovery charges.

This means a new expedition intentionally discards previous run-scoped state. Meta progress is not reset here.

Party Persistence

Party room-to-room persistence lives in GameState and is written through PartyRunState.

Important containers:

  • PartyStateById: canonical mutable per-party-member run snapshot.
  • PartyInventory: shared 20-slot carried inventory.
  • PartyXpById, PartyWeaponById, PartyArmorById, PartyEquipmentById: compatibility/index snapshots used by combat and equipment flows.
  • ExpeditionParty: launch-order party list, useful for identity/order, but not always the freshest mutable character data.

PartyRunState.SaveCharacterState() writes the live combatant back to PartyMemberState, including:

  • Name, class, race, visual variant.
  • Level, XP, talents, learned powers.
  • Current/max HP.
  • Recovery charges.
  • Ability scores.
  • Weapon, armor, and equipment slots.
  • Derived display stats such as AC, Fortitude, Reflex, Will, speed, and AP.

CombatBoard.SavePartyRunState() calls SaveCharacterState() for every party member after important room transitions. Individual powers, healing, equipment changes, damage, and reward flows also call back into this save path when they mutate persistent party data.

Read live character data from PartyStateById

Some UI builders still iterate GameState.ExpeditionParty for stable ordering, but should read mutable values from PartyStateById. ExpeditionStatusViewModelBuilder already follows this pattern because the launch combatants are not guaranteed to reflect later combat results.

Inventory And Gold

The shared backpack is GameState.PartyInventory, normalized by EquipmentManager.EnsurePartyInventory() to the configured 20-slot limit. Reward, chest, merchant, forge, apothecary, mastery start-run item grants, and loot pickup flows add through inventory helpers so full-inventory failure can be handled.

Gold is run-scoped on GameState.Gold. It is reset to 500 at expedition launch, then changed by rewards and room economy systems. Guild currencies such as Guild Seals and Guild XP are meta progress and live under PlayerMetaProgress / guild mastery state instead.

Navigation has two layers:

  • NavigationRunState is the in-memory navigation model for the current map/session: current node, revealed/scouted/cleared nodes, opened/traversed edges, history, act index, depth, and optional room dungeon data.
  • GameState.RoomDungeonJson stores the serialized room-map JSON so the dungeon map can be restored across combat scene reloads.

NavigationManager.EnsureRoomDungeon() restores RoomDungeonJson when the saved layout version matches; otherwise it generates a new room dungeon from the run seed. PersistRoomDungeon() writes the current map back into GameState.RoomDungeonJson.

RoomFlowController updates GameState.MaxDepthReachedThisRun when rooms are entered. MetaSaveService uses that tracked depth as a guard so return/wipe rewards use the deepest reached room even if another caller reports a lower value.

Relics And Camp Bonuses

Run relic ownership is GameState.RelicRunState.

  • Active relic IDs persist for the expedition.
  • ActiveRelicState.TriggerCountThisCombat resets on combat start.
  • ActiveRelicState.TriggerCountThisRoom resets on room start.
  • HasTriggeredThisRun persists until the expedition is cleared/reset.

Pending camp bonuses live in GameState.PendingCampBonus and are consumed by the next combat start. Training-room sessions skip the normal persistent paths.

Combat State And Sync Points

CombatBoard owns the active room's live combat state and delegates many responsibilities to focused services. On _Ready(), it binds directly to the GameState collections for party/inventory persistence and initializes PartyRunState with those references.

Key sync points:

  • Combat setup reads persisted party members through PartyRunState.GeneratePartyFromRecruits().
  • Damage, healing, power effects, and consumable/item use call SaveCharacterState() when party members change.
  • Reward flow passes callbacks for inventory add and party state save.
  • Equipment overlays call GameState.SyncEquipment() after out-of-combat equipment edits.
  • Victory bookkeeping increments EliteKillsThisRun or sets BossDefeatedThisRun on GameState.

Training room mode is explicitly non-persistent. TrainingRoomSession.IsActive bypasses party save/equipment sync, rewards, navigation, quest writes, and normal expedition progression.

Meta Progress

MetaProgressService loads and saves PlayerMetaProgress at:

<Godot user data dir>/eternal_guild_progress.json

If the file is missing or invalid, it falls back to content/meta/default_progress.json. On load, it merges default unlocked classes into older saves so newly default-unlocked classes are available without resetting progress.

PlayerMetaProgress currently stores:

  • Guild foothold level and highest foothold reached.
  • Guild rank/currency/xp and Guild Seals.
  • Unlocked classes, items, item properties, hub features, and floors.
  • Completed quests and typed main-quest progress.
  • Active contract slot count.
  • Guild Mastery state and Guild XP state.
  • Runic Scroll progress.

MetaSaveService is the end-of-run writer. On expedition return or wipe it:

  • Awards run renown/Guild XP from first expedition, boss defeat, elite kills, and first depth-3 reach.
  • Awards Guild Seals from boss/elite kills and reached depth.
  • Unlocks the Guild Forge after the first boss defeat.
  • Updates foothold level on return based on survivor count, or resets foothold on wipe.
  • Saves through MetaProgressService.SaveProgress().

Current Caveats

  • Mid-expedition state is held in autoload/runtime memory, not fully serialized to disk as a resumable run save.
  • ExpeditionParty should be treated as party identity/order plus launch snapshot; use PartyStateById for current HP, XP, level, recovery charges, equipment, and variants.
  • RoomDungeonJson persists the room-map JSON through combat scene reloads, but it is reset at expedition launch and after some floor/flow transitions.
  • Debug training mode intentionally bypasses persistence and progression.

Source Files

  • game/scripts/GameState.cs
  • game/expedition/scripts/ExpeditionRoot.cs
  • game/expedition/scripts/ExpeditionState.cs
  • game/combat/scripts/PartyRunState.cs
  • game/combat/scripts/models/PartyMemberState.cs
  • game/combat/scripts/CombatBoard.cs
  • game/combat/scripts/RoomFlowController.cs
  • game/navigation/scripts/NavigationManager.cs
  • game/navigation/scripts/NavigationRunState.cs
  • game/navigation/scripts/room/RoomDungeonRunState.cs
  • game/meta/scripts/MetaProgressService.cs
  • game/meta/scripts/PlayerMetaProgress.cs
  • game/meta/scripts/MetaSaveService.cs
  • game/relics/scripts/RelicRunState.cs
  • game/relics/scripts/ActiveRelicState.cs
  • game/hub/scripts/GuildHubState.cs
  • game/guild_mastery/scripts/GuildMasteryState.cs
  • game/guild_mastery/scripts/GuildXpState.cs