Gondwana.EngineState Class Reference

Represents the complete serializable state of the game engine, including assets, scenes, sprites, audio resources, and custom data. This class provides functionality to save and load engine state to/from files with support for selective state management, compression, and merge operations. The state can be persisted as JSON and optionally compressed using GZip compression. More...

Public Member Functions
void	SaveToFile (string path, bool compress=false, EngineStateParts parts=EngineStateParts.All)
	Saves the current engine state to a file in JSON format with optional compression and selective state component inclusion. The saved state can later be loaded using LoadFromFile or merged using MergeFromFile.

Static Public Member Functions
static void	LoadFromFile (string path, bool compressed=false, EngineStateParts parts=EngineStateParts.All)
	Loads engine state from a file, replacing the current engine state with the saved state. This method clears existing state components before loading, providing a clean slate for the loaded data. Dependencies between state parts (such as tilesheets depending on asset files) are automatically handled.
static void	MergeFromFile (string path, bool compressed=false, bool overwriteExisting=false, EngineStateParts parts=EngineStateParts.All)
	Loads engine state from a file and merges it with the current engine state, optionally overwriting existing items with matching identifiers. Unlike LoadFromFile,.

Properties
static JsonSerializerSettings	JsonSerializerSettings [get, set]
	Gets or sets the JSON serializer settings used for serializing and deserializing engine state. These settings are configured to handle type information, preserve object references, and produce indented (human-readable) JSON output. The default configuration uses automatic type name handling and preserves all object references to maintain complex object graphs.
IEnumerable< AssetsFile >	AssetsFiles [get]
	Gets the collection of all loaded asset files (resource archives) currently registered with the engine. Asset files contain packed game resources such as images, audio, and data files that have been loaded into memory. This property provides a snapshot of the current asset files for serialization purposes.
IDictionary< string, Tilesheet >	Tilesheets [get]
	Gets a dictionary of all registered tilesheets, keyed by their unique identifiers. Tilesheets contain tile graphics and metadata used for rendering tile-based game worlds. This property provides access to the current tilesheet registry for serialization and state management.
Dictionary< string, Cycle >	Cycles [get]
	Gets the dictionary of all registered animation cycles, keyed by their unique identifiers. Animation cycles define sprite animation sequences including frame data, timing, and playback behavior. This property provides direct access to the cycle registry for serialization purposes.
List< Scene >	Scenes [get]
	Gets the list of all scenes currently registered with the engine. Scenes represent distinct game locations or levels, containing layers, entities, and scene-specific data. This property provides direct access to the scene collection for serialization and state management.
List< Sprite >	Sprites [get]
	Gets the list of all active sprites currently managed by the sprite manager. Sprites are visual game entities that can be positioned, animated, and rendered on screen. This property provides direct access to the sprite collection for serialization purposes.
Dictionary< string, AudioResource >	SoundResources [get]
	Gets the dictionary of all registered audio resources, keyed by their unique identifiers. Audio resources include sound effects, music tracks, and their associated playback settings such as volume, pan, and looping behavior. This property provides access to the audio resource registry for serialization and state management.
TypedValueBag	ValueBag = new() [get, set]
	Stores extensible, project-specific state data associated with this engine state.

Detailed Description

Represents the complete serializable state of the game engine, including assets, scenes, sprites, audio resources, and custom data. This class provides functionality to save and load engine state to/from files with support for selective state management, compression, and merge operations. The state can be persisted as JSON and optionally compressed using GZip compression.

Member Function Documentation

LoadFromFile()

void Gondwana.EngineState.LoadFromFile ( string path, bool compressed = false, EngineStateParts parts = EngineStateParts::All )

static

Loads engine state from a file, replacing the current engine state with the saved state. This method clears existing state components before loading, providing a clean slate for the loaded data. Dependencies between state parts (such as tilesheets depending on asset files) are automatically handled.

Parameters

path	The file path from which to load the engine state. The file must exist and contain valid serialized engine state data in JSON format.
compressed	If true, the file is expected to be GZip-compressed and will be decompressed before deserialization. If false, the file is read as plain text JSON. Default is false.
parts	Specifies which parts of the engine state should be loaded from the file. Use bitwise flags from EngineStateParts to select specific components. Note that dependencies are automatically included (e.g., loading tilesheets will also load asset files). Default is EngineStateParts.All.

MergeFromFile()

void Gondwana.EngineState.MergeFromFile ( string path, bool compressed = false, bool overwriteExisting = false, EngineStateParts parts = EngineStateParts::All )

static

Loads engine state from a file and merges it with the current engine state, optionally overwriting existing items with matching identifiers. Unlike LoadFromFile,.

this method does not clear existing state before loading, allowing incremental state updates and data patching scenarios.

Parameters

path	The file path from which to load the engine state. The file must exist and contain valid serialized engine state data in JSON format.
compressed	If true, the file is expected to be GZip-compressed and will be decompressed before deserialization. If false, the file is read as plain text JSON. Default is false.
overwriteExisting	If true, items from the loaded state will replace existing items with the same identifiers (such as scene IDs or sprite nicknames). If false, existing items are preserved and only new items from the loaded state are added. Default is false.
parts	Specifies which parts of the engine state should be merged from the file. Use bitwise flags from EngineStateParts to select specific components. Dependencies are automatically included. Default is EngineStateParts.All.

SaveToFile()

void Gondwana.EngineState.SaveToFile	(	string	path,
		bool	compress = false,
		EngineStateParts	parts = EngineStateParts::All )

Saves the current engine state to a file in JSON format with optional compression and selective state component inclusion. The saved state can later be loaded using LoadFromFile or merged using MergeFromFile.

Parameters

path	The file path where the engine state should be saved. The directory must exist and be writable. If the file already exists, it will be overwritten.
compress	If true, the JSON output will be compressed using GZip compression, reducing file size at the cost of additional processing time. If false, the JSON is written as plain text. Default is false.
parts	Specifies which parts of the engine state should be included in the saved file. Use bitwise flags from EngineStateParts to select specific components, or use EngineStateParts.All to save the complete state. Default is EngineStateParts.All.

Property Documentation

AssetsFiles

IEnumerable<AssetsFile> Gondwana.EngineState.AssetsFiles

get

Gets the collection of all loaded asset files (resource archives) currently registered with the engine. Asset files contain packed game resources such as images, audio, and data files that have been loaded into memory. This property provides a snapshot of the current asset files for serialization purposes.

Cycles

Dictionary<string, Cycle> Gondwana.EngineState.Cycles

get

Gets the dictionary of all registered animation cycles, keyed by their unique identifiers. Animation cycles define sprite animation sequences including frame data, timing, and playback behavior. This property provides direct access to the cycle registry for serialization purposes.

JsonSerializerSettings

JsonSerializerSettings Gondwana.EngineState.JsonSerializerSettings

staticgetset

Gets or sets the JSON serializer settings used for serializing and deserializing engine state. These settings are configured to handle type information, preserve object references, and produce indented (human-readable) JSON output. The default configuration uses automatic type name handling and preserves all object references to maintain complex object graphs.

Scenes

List<Scene> Gondwana.EngineState.Scenes

get

Gets the list of all scenes currently registered with the engine. Scenes represent distinct game locations or levels, containing layers, entities, and scene-specific data. This property provides direct access to the scene collection for serialization and state management.

SoundResources

Dictionary<string, AudioResource> Gondwana.EngineState.SoundResources

get

Gets the dictionary of all registered audio resources, keyed by their unique identifiers. Audio resources include sound effects, music tracks, and their associated playback settings such as volume, pan, and looping behavior. This property provides access to the audio resource registry for serialization and state management.

Sprites

List<Sprite> Gondwana.EngineState.Sprites

get

Gets the list of all active sprites currently managed by the sprite manager. Sprites are visual game entities that can be positioned, animated, and rendered on screen. This property provides direct access to the sprite collection for serialization purposes.

Tilesheets

IDictionary<string, Tilesheet> Gondwana.EngineState.Tilesheets

get

Gets a dictionary of all registered tilesheets, keyed by their unique identifiers. Tilesheets contain tile graphics and metadata used for rendering tile-based game worlds. This property provides access to the current tilesheet registry for serialization and state management.

ValueBag

TypedValueBag Gondwana.EngineState.ValueBag = new()

getset

Stores extensible, project-specific state data associated with this engine state.

The value bag allows games or engine extensions to persist arbitrary structured data (such as NPC state, quest progress, or custom subsystem data) without modifying the core EngineState schema.

Values are accessed using strongly-typed ValueKey<T> instances to ensure compile-time safety while preserving a flexible serialized representation.

// Define keys once (typically in a static class)
static readonly ValueKey<Dictionary<string, int>> NpcHitPoints =
    new("npc.hitpoints");
 
// Store values
engineState.ValueBag.Set(NpcHitPoints, new Dictionary<string, int>
{
    ["npc.guard"] = 12,
    ["npc.merchant"] = 8
});
 
// Retrieve values
var hp = engineState.ValueBag.Get(NpcHitPoints, new Dictionary<string, int>());