codebase-state-structure

To add a persistent field to GameState, you add the field to the relevant sub-struct like PlayerState, apply serde attributes for defaults, and bump the SAVE_VERSION constant to maintain save compatibility. This ensures old saves deserialize correctly with the new layout.

The serde skip attribute excludes transient runtime fields from the persistent serialization process, preventing unnecessary data bloat in save files. It marks fields that should rebuild dynamically, such as spatial indices, instead of being stored on disk.

You must bump SAVE_VERSION whenever the serialization layout of GameState changes, including adding, removing, or altering persistent fields in sub-structs like WorldState. This version bump signals the save system to handle migration or compatibility checks for existing saves.

Spatial index rebuild patterns use lazy initialization to reconstruct the spatial index from serialized data only when the game world requires spatial queries at runtime. This avoids serializing derived data while ensuring the WorldState spatial structure is ready for gameplay.

Gameplay data is centralized in the GameState model and decomposed into sub-structs like PlayerState, WorldState, and NarrativeEngine. Each struct holds specific runtime and persistent fields, distributing responsibilities across the game architecture for organized access.

Yes, modifying the event emission pipeline or message capping invariants requires updating the NarrativeEngine files to reflect the changes. This ensures the narrative state correctly processes and stores gameplay events during serialization.