CREAT3D.ECS.Services.ChunkManagement

IChunkLoadingService

This service's primary responsibility is to load and unload Chunks and by extension through other services, Scenes, EntitySpawns and serialized Entities. It is heavily used during the game initialization process.

Broadcasts Events: ChunkLoadRequestedAsyncTopic, ChunkLoadCompleteAsyncTopic, ChunkUnloadRequestedAsyncTopic, ChunkUnloadCompleteAsyncTopic

Methods

Method Task LoadChunk(Chunk chunk, CancellationToken cancellationToken, bool cacheUnloadedChunks = true)
Description Loads specified Chunk from its default state while first unloading all already loaded Chunks from the game. If cacheUnloadedChunks is true, the Chunks unloaded will keep a serialized state in memory to be serialized to a save file in the next serialization call. Their state is discarded if the boolean is set to false. Nothing happens if the Chunk is already loaded.
Method Task LoadChunkAdditive(Chunk chunk, CancellationToken cancellationToken)
Description Loads specified Chunk from its default state if not already loaded without unloading current Chunks. The Chunk's Scenes are loaded first, followed by any EntitySpawns associated with those Scenes. Nothing happens if the Chunk is already loaded.
Method Task LoadChunksFromSave(Chunk[] chunks, EntityPacketCollection[] entities, bool containsEncodedPackets, CancellationToken cancellationToken, bool cacheUnloadedChunks = true)
Description Loads specified Chunks from their corresponding supplied EntityPacketCollections while first unloading all already loaded Chunks from the game. Chunks which are already loaded are ignored together with their corresponding EntityPacketCollection. If cacheUnloadedChunks is true, the Chunks unloaded will keep a serialized state in memory to be serialized to a save file in the next serialization call. Their state is discarded if the boolean is set to false. The containsEncodedPackets boolean is meant to instruct how the EntityPacketCollections deserialize. Packet encoding reduces save file size by storing a packet's type as an integer instead of serializing its Type as a string value, but adding new packets will break the indexing and corrupt the save file. For more robust save files, set encoding to false. An EntityPacketCollection must deserialize with the same setting it was serialized.
Method Task LoadChunksFromSaveAdditive(Chunk[] chunks, EntityPacketCollection[] entities, bool containsEncodedPackets, CancellationToken cancellationToken)
Description Loads specified Chunks from their corresponding supplied EntityPacketCollections without unloading current Chunks. Chunks which are already loaded are ignored together with their corresponding EntityPacketCollection. The Scenes belonging to all Chunks being loaded are loaded before their serialized Entities are restored. The containsEncodedPackets boolean is meant to instruct how the EntityPacketCollections deserialize. Packet encoding reduces save file size by storing a packet's type as an integer instead of serializing its Type as a string value, but adding new packets will break the indexing and corrupt the save file. For more robust save files, set encoding to false. An EntityPacketCollection must deserialize with the same setting it was serialized.
Method Task UnloadChunk(Chunk chunk, bool includeUnloadableChunks, CancellationToken cancellationToken, bool cacheUnloadedChunks = true)
Description Unloads specified Chunk from the game. Nothing happens if the Chunk is not currently loaded. If cacheUnloadedChunks is true, the Chunk unloaded will keep a serialized state in memory to be serialized to a save file in the next serialization call. The state is discarded if the boolean is set to false. The includeUnloadableChunks boolean is used to override the Chunk's neverUnload setting. Setting the boolean to true will unload the Chunk even if it's set to never unload. Entities associated with the Chunk are destroyed before its Scenes are unloaded.
Method Task UnloadAllChunks(bool includeUnloadableChunks, CancellationToken cancellationToken, bool cacheUnloadedChunks)
Description Unloads all loaded Chunks from the game. If cacheUnloadedChunks is true, the Chunks unloaded will keep a serialized state in memory to be serialized to a save file in the next serialization call. The state is discarded if the boolean is set to false. The includeUnloadableChunks boolean is used to override the neverUnload setting of the Chunks. Setting the boolean to true will unload all Chunks even if some are set to never unload.
Method Task UnloadChunks(bool includeUnloadableChunks, CancellationToken cancellationToken, bool cacheUnloadedChunks = true, params Chunk[] chunks)
Description Unloads all specified Chunks from the game. Chunks set to neverUnload are skipped unless includeUnloadableChunks is true. If cacheUnloadedChunks is true, the Chunks unloaded will keep a serialized state in memory to be serialized to a save file in the next serialization call. The state is discarded if the boolean is set to false. The includeUnloadableChunks boolean is used to override the neverUnload setting of the Chunks. Setting the boolean to true will unload all specified Chunks even if some are set to never unload.