//CREAT3D.ECS.Services.GameManagement//
===== ISaveGameService =====

This service's primary responsibility is to save and load the current [[Game]] state. It serializes the game header and [[Chunk]] [[Entity]] data into a compressed save file, restores Chunks from saved [[EntityPacketCollection|EntityPacketCollections]], and falls back to default [[Chunk]] loading when saved [[Chunk]] data is not found. It also manages cached unsaved Chunk state so unloaded Chunks can still be included in the next save operation.

**Broadcasts Events:** [[SaveFileLoadRequestedAsyncTopic]], [[SaveFileLoadCompleteAsyncTopic]], [[SavedChunkLoadRequestedAsyncTopic]], [[SavedChunkLoadCompleteAsyncTopic]], [[SaveFileSerializationRequestedAsyncTopic]], [[SaveFileSerializationCompleteAsyncTopic]]

=== Methods ===
^Method | Task<bool> **TryLoadGame**(string path, CancellationToken cancellationToken) |
^Description | Attempts to load a saved [[Game]] from the specified file path. Returns false if the file does not exist, if the game header cannot be deserialized, or if no valid Chunks can be found to load. When loading succeeds, the service determines which Chunks should be loaded, loads them from the save file or default state, marks the game as initialized, and returns true. If the saved game does not contain a loaded Chunk list, the configured starting Chunks are used instead. |

^Method | bool **TryFetchGameHeader**(string path, out [[Game]]? game) |
^Description | Attempts to read and deserialize only the [[Game]] header from the specified save file. Returns false if the file does not exist or the header cannot be read from the archive. Returns true and outputs the deserialized [[Game]] if successful. |

^Method | Task **LoadChunks**(string path, CancellationToken cancellationToken, params [[Chunk]][] chunks) |
^Description | Loads the specified Chunks from a save file when saved data exists, or from their default state when it does not. Already loaded Chunks are skipped. For each [[Chunk]], the service first checks whether an unsaved cached [[EntityPacketCollection]] exists for the Chunk, then attempts to read the Chunk binary from the save archive. If cached or saved entity data is found, the [[Chunk]] is loaded additively from that [[EntityPacketCollection]]. If no saved data is found for the Chunk, the Chunk is loaded additively from its default state. |

^Method | Task<bool> **TrySaveCurrentGame**(string path, CancellationToken cancellationToken, bool updateLoadedChunkList = true) |
^Description | Attempts to serialize and save the current [[Game]] state to the specified file path. Returns false if the current game state cannot be serialized. When serialization succeeds, the service collects binary data for the game header, all currently loaded Chunks, and all cached unsaved Chunks. If a save file already exists, the service replaces the game header and updated Chunk entries while preserving unrelated existing archive entries. If the file does not exist, a new save archive is created. Once writing completes, cached unsaved Chunk state is cleared. The updateLoadedChunkList boolean controls whether the current game's loaded [[Chunk]] list is refreshed from the currently loaded Chunks before serialization. |