# Game State Architecture

## Purpose

The game separates authoritative gameplay state from rendering and runtime
resources. The same snapshot-and-command boundary supports the in-process
single-player server and a WebSocket deterministic-lockstep client/server.

## Architecture Overview

The architecture has six layers:

1. `GameState` is the aggregate root for persistent, authoritative state.
2. `InternalGameServer` owns `GameState`, advances the local simulation, handles commands, and produces immutable snapshots.
3. `ClientLocationState` owns per-client `LocationLocalState` records, including camera orientation. Graphical hosts own this state; it is never replicated.
4. Runtime objects hold rendering resources. `Character` and `Location` read immutable server snapshots by stable ID, while `InteractiveObject` still uses a transitional non-owning binding to server-owned state. `Location` also translates local input, scripts, and collision results into semantic server commands.
5. Client-facing systems such as `MenuManager` read immutable snapshots and submit typed commands through `IGameServer`.
6. Protocol-v2 WebSocket hosts assign preconfigured player slots and exchange
   one initial state followed by ordered 100 ms tick bundles.

```text
Input / UI
    | typed GameCommand
    v
IGameServer
    |
    v
InternalGameServer ---- owns ----> GameState
    |                                  |
    | update                           | stable state objects
    v                                  v
Location / Character / InteractiveObject runtime
    |
    v
Renderer

IGameServer ---- immutable GameSnapshot ----> UI and other clients
```

## Authoritative State Model

### `GameState`

`GameState` is the top-level state object. It contains:

- Campaign ID and current location ID.
- Day, night, dawn, and darklands flags.
- A map of campaign-level players keyed by stable player ID.
- A map of typed `LocationGameState` records keyed by location ID.
- Inventory, money, player-health HUD values, quests, tutorial progress, chat data, taxi state, and script-global values.

Live `Location` pointers and rendering objects are no longer stored in `GameState`.
Embedded state models such as `Inventory` and `QuestJournal` contain only value
data and deterministic operations; they do not retain runtime callbacks.

### Campaign-level players

Player `CharacterState` objects are stored in `GameState::players`. The current single-player game uses the ID `"player"`.

The player state is no longer owned by a `Character` or duplicated as a separately authoritative state for each loaded location. This permits additional player IDs to be introduced later without changing the aggregate ownership model.

Every player, including the one controlled by the current client, remains in this
same authoritative collection. `IGameServer::localPlayerId()` identifies which
entry is local to a particular client connection; it is not a separate state
object.

`LocationGameState` does not retain a player pointer or back-reference to `GameState`.
Its update boundary receives `GameState::players` by reference, allowing character
lookup and simulation to treat every campaign player by stable ID.

### `LocationGameState`

Each location record owns:

- One `LocationNetworkState`.
- NPC `CharacterState` objects keyed by configured ID.
- `InteractiveObjectState` objects keyed by configured ID.
- Trigger-zone enabled/inside flags.
- Teleport-zone active flags.
- Serialized dialogue runtime state.
- Serialized Lua runtime globals.

World-mode flags (`darklands`, `night`, and `dawn`) exist only at the aggregate
`GameState` level. Location rendering and scripts read those values from the
top-level snapshot rather than maintaining per-location mirrors.

State objects use `shared_ptr` internally to keep addresses stable for the
remaining local runtime bindings. These pointers never appear in public snapshots.

### Stable identity

- Locations use campaign configuration IDs.
- Players use keys from `GameState::players`.
- NPCs use required location-local configuration IDs.
- Interactive objects use required location-local configuration IDs.
- Trigger and teleport zones use their configured IDs.

Missing, empty, duplicate, and reserved IDs are content errors. Runtime references,
Lua APIs, snapshots, and persistence all use these IDs rather than configuration
array positions.

## Server Interface

`IGameServer` is the public state boundary. It exposes:

- `snapshot()` for an immutable, revisioned `GameSnapshot`.
- `submit()` for typed `GameCommand` values.
- `update()` for advancing a local fixed tick or polling a remote implementation.
- `save()` and `load()` for server-side persistence.

No public method returns a mutable state pointer or reference.

### Snapshots

`GameSnapshot` and its nested snapshot types are value-only read models. They contain no renderer objects, runtime `Location` pointers, mutable references, or active callbacks.

Snapshots include:

- Campaign and world-mode state.
- All players.
- Locations, NPCs, interactive objects, triggers, and teleports.
- Inventory item IDs.
- Quest views.
- Tutorial, chat, taxi, money, and health data.
- Script-global values.

Snapshots have a monotonically increasing revision. `InternalGameServer` caches the current immutable snapshot and rebuilds it only after the authoritative state changes.

### Commands

`GameCommand` is a C++17 `std::variant` of semantic command types. Current commands cover:

- World mode and current location.
- Player health and money.
- Tutorial progression and flags.
- Chat history and unread state.
- Taxi state.
- Inventory additions and removals.
- Quest status, objective completion/visibility, and active-objective changes.
- Script globals.
- Character transforms, attack targets, navigation destinations, stopping,
  facing, replanning, health, damage, death reset, attack combos, and animation
  metadata. Character position, facing angle, home position, face target, and
  enabled state use separate semantic commands; no whole-character commit
  command is exposed.
- Interactive-object activation.
- Trigger-zone state.
- Quest-definition reloads.

The remote implementation serializes destination intent from clients, while
the server emits connection-lifecycle presence commands. The server derives the
character and location from the assigned connection slot; arbitrary state
mutation commands are not accepted from the network.
`SetCharacterEnabledCommand` is consumed by the server and replicated to every
client in the ordered tick bundle when a slot connects or disconnects.

### Presentation events

`IGameServer::drainEvents()` returns value-only events produced by successful
authoritative mutations. Inventory add/remove and quest unlock/complete/fail/
objective-complete events contain stable IDs only. `Game` drains these events and
performs local tutorial, toast, and audio presentation through `MenuManager`.
Loading and persistence restoration clear pending events and remain silent.

## Internal Server

`InternalGameServer` is the current `IGameServer` implementation. It:

- Exclusively owns the aggregate `GameState`.
- Executes typed commands against authoritative state.
- Advances the active location simulation in exact 100 ms ticks.
- Builds and caches immutable snapshots.
- Delegates save/load serialization to the aggregate state model.

`LocalGameServerHost` is the graphical client's integration adapter. It owns loaded
runtime `Location` objects, forwards simulation events to them, and synchronizes
dialogue, Lua, trigger, and teleport auxiliary state. `Game` uses the explicit
`IGameServerHost` lifecycle interface and is no longer a friend of
`InternalGameServer`. The standalone server does not compile this adapter.

Location loading has two phases. `LocationContentLoader` parses renderer-free
`LocationDefinition` data, and `LocationGameState::setup()` creates/reconciles
authoritative NPC, interactive-object, navigation, taxi, trigger, teleport, and
animation state. The graphical `Location::setup()` runs afterward and only builds
presentation objects from that definition and the prepared state. Lua and dialogue
runtime behavior remains client-side.

### Animation and combat

Logical animation frame clocks live in `CharacterState`. The renderer-free content
loader reads animation frame metadata before authoritative entities are created.
Runtime `Character` construction only loads models for presentation and does not
submit metadata mutations back to the server.

`CharacterState::update()` returns value-only events containing arrival Lua function
names, attack impacts, navigation requests, and death-animation completion.
`LocationGameState` applies queued damage after every character has advanced.
Navigation replans are consumed by `InternalGameServer` as deterministic
simulation consequences rather than being resubmitted by presentation code.
Runtime `Character` objects only pose loaded models and produce audio, particles,
and presentation callbacks.

### Character state operations

Gameplay operations mutate the authoritative `CharacterState`, not the runtime
`Character`:

- `setTarget()` normalizes the destination, avoids redundant requests, stores the
  optional Lua arrival function name, and asks the authoritative `LocationNetworkState` to
  call `planPathExceptMyself()`.
- `forceReplan()` recalculates the current requested destination using the same
  location navigation state.
- `stopInPlace()` clears navigation and any pending arrival function.
- `stopAndRotateToTarget()`, `resetPlayerAfterDeath()`, `setHp()`, and
  `tryAttackCombo()` update their respective state directly.

`InternalGameServer::submit()` resolves the character and location, then invokes
these operations for the corresponding semantic command. The runtime `Location`
provides convenience methods for submitting those commands from input, scripts,
collision handling, and presentation-event processing.

## Runtime and Visual Object Bindings

Runtime visual objects do not own their authoritative state objects.

- `Location` keeps its `IGameServer` reference, stable location ID, and a shared
  `LocationLocalState` supplied by the graphical host. It resolves its immutable
  `LocationNetworkState` view from `IGameServer::snapshot()`, while rendering and
  camera input access the local state directly.
- `Character` keeps only its `IGameServer` reference plus stable entity and location IDs. It resolves the player-first character view from `IGameServer::snapshot()`.
- `InteractiveObject` keeps a private non-owning reference to its `InteractiveObjectState`; its configured object name is its stable ID.

`Character::stateSnapshot()` and `Location::stateSnapshot()` return aliasing
`shared_ptr` views. Each pointer addresses a state copy inside a `GameSnapshot`,
while shared ownership keeps that whole immutable snapshot alive. Update, input,
editor, and draw operations capture one such pointer and use it consistently
throughout the operation. A missing or unloaded entity produces an empty pointer
and presentation or input work is skipped.

The authoritative state objects are owned by `GameState` or `LocationGameState`.
The internal server advances them before publishing a new snapshot revision.
Runtime input, scripts, and collision handling submit semantic commands that invoke
authoritative character and location operations. Location commands cover pending
interaction targets, navigation switching and area changes, editor obstacles, and
taxi reset. Camera orientation is deliberately not a server command. No
whole-location commit command is exposed.

Navigation target selection, replanning, stopping, facing, death reset, health
assignment, and attack-combo clock changes are implemented by `CharacterState`.
`Character` no longer exposes gameplay mutation helpers or a generic state mutation
callback. Character construction is presentation-only; frame ranges are already
present in `CharacterState` after content setup. It focuses on model posing,
rendering, audio, particles, and runtime callbacks.

Death-animation and health-change callbacks remain runtime-only on `Character`.
Arrival behavior is represented solely by the serialized Lua function name in
`CharacterState`; `Location` resolves and invokes that name through `ScriptEngine`
when it consumes the arrival event.

`Location` owns presentation-only runtime characters for all non-local entries in
`GameSnapshot::players`. It reconciles them by stable ID as snapshots change,
reuses the local-player assets and animation set, and includes them in all render,
shadow, lighting, animation, damage, and name-tag passes. The local entry is
excluded using `IGameServer::localPlayerId()` because its visual is already owned
by `Game`.

`GameObjectLoader` now:

1. Receives immutable object/NPC definitions parsed by `LocationContentLoader`.
2. Resolves already-prepared authoritative entities by stable ID.
3. Constructs meshes, textures, VBOs, `InteractiveObject`, and `Character`
   presentation wrappers without creating or overwriting authoritative state.

Configuration remains the source of visual assets, animation paths, meshes, textures, and fixed tuning data.

## State Update Flow

Render frames and simulation ticks are separate:

1. SDL input and UI presentation use the real elapsed render-frame time.
2. A local host accumulates `steady_clock` elapsed time and runs zero or more
   exact 100 ms simulation ticks. A remote host polls transport every frame but
   advances only from contiguous server tick messages.
3. Commands assigned to tick `N` are applied in server sequence order before
   simulation tick `N`.
4. The server freezes location character observations and updates every player,
   NPC, taxi, and interactive object with exactly 100 ms. An empty player
   collection remains valid.
5. Attack impacts are queued and applied only after all characters advance.
   Navigation recovery is applied inside the deterministic state path.
6. The server invalidates its cached snapshot and advances its revision.
7. Runtime locations consume the completed tick's value-only events and perform
   rendering, audio, particles, and supported presentation callbacks.
8. Rendering can occur between ticks and never changes authoritative tick time.

Commands that update bound character or object state do not reload the whole location. This avoids replaying dialogue-node effects or Lua callbacks.

## Campaign and Location Lifecycle

Only one location is normally loaded as a runtime object.

### Campaign loading

When a campaign starts:

- Existing campaign state and runtime locations are cleared.
- Quest definitions are loaded.
- The graphical single-player host requests a campaign-level `"player"` state and
  creates its visual wrapper.
- A standalone host may deliberately create no players; locations continue to tick.
- The battle-zone test bot is an explicit host option rather than an unconditional
  campaign side effect.

### Location loading

When a location is loaded:

- `LocationContentLoader` parses a renderer-free `LocationDefinition`.
- `LocationGameState::setup()` creates or reconciles navigation, taxi, NPC,
  interactive-object, trigger, teleport, and animation state.
- Saved mutable fields are overlaid on configuration defaults by stable ID.
- `Location::setup()` builds static and entity visuals from the prepared definition
  without mutating authoritative state.
- The shared campaign player is attached.
- Runtime visuals are created for other player IDs currently present in the
  snapshot and are subsequently spawned or removed as snapshots change.
- Dialogue, Lua, trigger/teleport visuals, and presentation callbacks are initialized.
- The runtime `Location` is owned and registered by `LocalGameServerHost`;
  `InternalGameServer` remains headless.

### Location unloading

When leaving a location:

- Auxiliary runtime state is captured.
- The visual/runtime `Location` is destroyed.
- Its typed `LocationGameState` remains in `GameState`.

The player state remains campaign-level and survives location changes.

## Save and Load Schema

Authoritative persistence uses one strict, versioned schema. `schemaVersion` is
required and unsupported versions are rejected rather than migrated. A
single-player save is a separate versioned envelope containing `networkState`
(the authoritative `GameState` JSON) and `localState` (the client-local location
map). Lockstep sends that authoritative document only in `initial_state`; later
messages contain numbered command bundles.

- Campaign players are stored once in an ID-keyed `players` object.
- Locations are keyed by location ID.
- Each location stores NPC and interactive-object state in ID-keyed objects.
- Pending interaction targets and character references use stable IDs.
- Immutable content such as meshes, initial taxi configuration, and object
  definitions is reconstructed from campaign configuration.
- Configuration is loaded first and mutable saved state is overlaid in place.
  Snapshot-backed runtime objects then resolve the resulting state by stable ID.

Old user save slots are intentionally unsupported. Bundled start-state snapshots
must be regenerated with `Game::saveInitialState()` whenever the schema changes.

## UI, Scripts, Dialogue, and Quests

### UI

`MenuManager` no longer holds `GameState&` or a mutable `Inventory*`.

It now:

- Reads inventory, quests, tutorial state, chat, money, health, location, and world mode from `GameSnapshot`.
- Submits typed commands for mutations.
- Continues to own presentation-only UI trees, screen state, textures, and callbacks.

### Scripts

Lua remains an in-process single-player runtime. Character, inventory, quest, and
campaign-global bindings submit semantic commands through `Location`; the server
invokes operations on centrally owned state. Snapshot queries provide global
values, inventory counts, item presence, and synchronous quest validation for the
existing Lua API. NPC,
interactive-object, trigger-zone, and teleport-zone bindings address entities by
configured ID. Other object and global-state bindings remain trusted local
integrations.

Each location script registers initialization, enter, and exit callbacks.
Initialization runs only when the location has no retained state; loading the Lua
file again for rendering does not repeat state-resetting setup. Enter and exit
callbacks continue to run for every location transition.

The scalar Lua runtime state for each location is stored under `LocationGameState::scriptGlobals`. Multiplayer location scripts are expected to be empty, so remote script execution is intentionally outside the current scope.

### Dialogue and cutscenes

Dialogue runtime state is captured in each `LocationGameState`. Dialogue global
flags use snapshot getter and command setter callbacks rather than retaining a
mutable map pointer. Dialogue and cutscene rendering remain local presentation
systems.

Dialogues and cutscenes are outside the planned multiplayer gameplay mode, but their existing single-player save and callback behavior is retained.

### Quests, inventory, and tutorial

These callback-free state systems remain part of `GameState` for single-player
compatibility. UI access, mutations, and presentation notifications cross the
server interface. They can remain empty or disabled in multiplayer mode as planned.

## Multiplayer Lockstep

Protocol v2 uses server-sequenced deterministic lockstep:

- The server assigns a connection to a preconfigured campaign player slot.
- Player slots are disabled in the authoritative initial state. A successful
  connection schedules `SetCharacterEnabledCommand(enabled=true)` for the next
  lockstep tick; disconnect schedules the corresponding `enabled=false` command.
- Connection receives one authoritative state at a completed tick plus its
  assigned player ID, tick duration, input delay, and compatibility fingerprint.
- Destination input is normalized and scheduled two ticks in the future.
- The server broadcasts every numbered tick, including empty ticks. Clients
  buffer out-of-order messages and advance only contiguous tick IDs.
- All replicas apply the same globally sequenced commands before one exact
  100 ms update.
- Post-tick canonical hashes exclude persistence timestamps and local
  presentation state. A mismatch is diagnosed but not automatically repaired.

No wall-clock timestamp participates in simulation. `steady_clock` paces the
server and local render accumulator only, so different machine clocks do not
affect command placement or state. The current missing-packet policy is to stall;
there is no prediction or rollback.

Current boundaries remain:

- client intent is limited to `SetCharacterDestinationCommand`; server presence
  changes use `SetCharacterEnabledCommand` in tick bundles;
- player characters must already exist in the initial state and campaign slot
  list; dynamic spawning and reconnect history are not implemented;
- authentication and automatic checkpoint resynchronization are absent;
- multiplayer Lua/dialogue shared behavior is unsupported;
- deterministic compatibility targets identical executable and content builds.
  Floating-point simulation is not guaranteed bit-identical across platforms.

## Platform Build Integration

The new state and server files are registered in:

- `proj-windows/CMakeLists.txt`
- `proj-linux/CMakeLists.txt`
- `proj-web/CMakeLists.txt`
- `proj-android/app/jni/src/CMakeLists.txt`

The refactor uses portable C++17 and introduces no Windows-only gameplay code.

The standalone target lives under `server/`. It links the authoritative state,
campaign, content-definition, and portable resource sources only; SDL, OpenGL,
audio, Lua, dialogue presentation, and rendering sources are absent. It can prepare
a selected campaign/location with zero players. The Windows server adds
Boost.Beast transport and runs a fixed 100 ms lockstep loop; other platforms
continue to compile the portable state core without that transport.

The Windows Debug target was verified with:

```powershell
cmake --build proj-windows/build --config Debug --target ShadowOverBishkekDemo -- /m
```

## Important Constraints

- Runtime C++ callbacks are not part of `CharacterState` or public snapshots;
  serializable Lua arrival function names are state data.
- `InteractiveObjectState` animation callbacks are also removed from public snapshots.
- Character target and attacker references use stable IDs (`"player"` or a unique
  location-local NPC ID).
- Some top-level values remain mirrors for compatibility, notably player health used by the HUD and scripts.
- Dialogue and Lua are synchronized as auxiliary location state rather than fully networked subsystems.
- `IGameServerLifecycle` is the graphics-free campaign/location administration
  boundary. `LocalGameServerHost` adds client-only runtime construction and
  auxiliary-state synchronization without making `Game` a server friend.
- Empty player maps are valid. Player-specific interactions remain inactive until
  a player entity is added.
- Pathfinding priority queues use cell index as a stable secondary key.
- Gameplay randomness must be seeded and serialized; the `random_device` battle
  bot is disabled for multiplayer sessions.
- A lockstep compatibility fingerprint must match before the client accepts the
  initial state.

## Main Files

- `src/GameState.h` / `src/GameState.cpp` — aggregate state and top-level persistence.
- `src/LocationState.h` / `src/LocationState.cpp` — separate local camera and authoritative network location records, plus single-player persistence composition.
- `src/LocationGameState.h` / `src/LocationGameState.cpp` — authoritative typed location state, simulation, and ID-keyed persistence.
- `src/content/LocationDefinition.h` / `.cpp` — renderer-free content definitions,
  parsing, and animation metadata loading.
- `src/game_server/IGameServer.h` — public snapshot and command contract.
- `src/game_server/IGameServerLifecycle.h` — graphics-free campaign/location lifecycle.
- `src/game_server/InternalGameServer.h` / `.cpp` — in-process authoritative implementation.
- `src/game_server/LocalGameServerHost.h` / `.cpp` — graphical-client runtime adapter.
- `src/game_server/NetworkProtocol.h` / `.cpp` — protocol-v2 messages,
  lockstep timeline, validation, and canonical hashes.
- `src/game_server/WebsocketGameServer.h` / `.cpp` and
  `WebsocketGameClient.h` / `.cpp` — slot assignment, input scheduling, tick
  broadcasting, buffering, and replica advancement.
- `src/Game.h` / `src/Game.cpp` — application host, campaign lifecycle, and runtime wiring.
- `src/Location.h` / `src/Location.cpp` — loaded location runtime, command routing,
  interactions, collisions, scripts, and presentation-event consumption.
- `src/Character.h` / `src/Character.cpp` — passive character presentation resolving
  immutable `CharacterState` snapshots by stable ID.
- `src/CharacterState.h` / `src/CharacterState.cpp` — deterministic character
  simulation, navigation operations, combat state, and logical animation clock.
- `src/items/InteractiveObject.h` / `.cpp` — visual object runtime bound to central object state.
- `src/items/GameObjectLoader.h` / `.cpp` — presentation builders for prepared definitions.
- `src/MenuManager.h` / `src/MenuManager.cpp` — snapshot-driven UI and command submission.