Skip to content

Game.SaveGameSystem

Assembly: Game
Namespace: Game.Serialization

Type: public class SaveGameSystem

Base: GameSystemBase

Summary:
System that coordinates a single save-game serialization pass. SaveGameSystem orchestrates the serialization update phase and the subsequent write job, exposing a simple async API (RunOnce) that completes when the write work has finished. It holds the output Stream, a serialization Context, and an optional NativeArray of referenced content. The system caches references to the game's UpdateSystem and WriteSystem and is normally disabled; it is enabled only for the duration of a RunOnce operation.

Fields

  • private TaskCompletionSource<bool> m_TaskCompletionSource
    Used internally to implement the async RunOnce() API. A TaskCompletionSource is created when a save run starts and its result is set when the write step completes.

  • private UpdateSystem m_UpdateSystem
    Cached reference to the game's UpdateSystem. The system calls m_UpdateSystem.Update(SystemUpdatePhase.Serialize) to trigger serialization of world state.

  • private WriteSystem m_WriteSystem
    Cached reference to the WriteSystem that performs the actual write job. SaveGameSystem inspects m_WriteSystem.writeDependency to detect when the write work has finished.

  • private bool m_Writing
    Internal flag indicating whether the save sequence has already started the writing stage (true) or is still triggering the serialize update (false).

  • private Context m_Context
    Serialization Context used during the save process. Note: the context is disposed when replaced via the context property setter and also on OnDestroy.

Properties

  • public Stream stream { get; set; }
    Stream where save data will be written. This should be set before calling RunOnce() and typically disposed by the caller after the save completes.

  • public Context context { get; set; }
    Serialization Context for the current save. The setter disposes the previous Context instance (m_Context.Dispose()) before assigning the new one. The context is also disposed in OnDestroy.

  • public NativeArray<Entity> referencedContent { get; set; }
    Optional NativeArray containing Entities that should be treated as referenced content during serialization. If created and assigned, it will be disposed in OnDestroy.

Constructors

  • public SaveGameSystem()
    Parameterless constructor. The type includes a [Preserve] attribute on methods and the constructor in the original source to prevent stripping; no special initialization occurs here — initialization is done in OnCreate.

Methods

  • protected override void OnCreate() : System.Void
    [Preserve] Called when the system is created. Caches references to UpdateSystem and WriteSystem via base.World.GetOrCreateSystemManaged() and sets base.Enabled = false so the system is idle until RunOnce is invoked.

  • protected override void OnDestroy() : System.Void
    [Preserve] Called on system destruction. Disposes m_Context and, if referencedContent.IsCreated, disposes referencedContent. Calls base.OnDestroy().

  • public async Task RunOnce() : System.Threading.Tasks.Task
    Creates a TaskCompletionSource, enables the system (base.Enabled = true), and awaits the TaskCompletionSource.Task. The TaskCompletionSource is completed when the write job finishes (see OnUpdate). Use this method to start a single save operation and await its completion.

  • protected override void OnUpdate() : System.Void
    [Preserve] Core update logic invoked while the system is enabled. Behavior:

  • If m_Writing is true: check m_WriteSystem.writeDependency.IsCompleted. If completed, call Complete() on the dependency, set m_Writing = false, disable the system (base.Enabled = false), and set the TaskCompletionSource result to true (completing RunOnce).
  • If m_Writing is false: set m_Writing = true and call m_UpdateSystem.Update(SystemUpdatePhase.Serialize) to trigger serialization which schedules the write job (the write job's dependency is tracked in m_WriteSystem).

Usage Example

// Example usage from a game/mod context: configure the SaveGameSystem, then await a single save run.
[Preserve]
public async void SaveToFile(string path, Context saveContext, NativeArray<Entity> referencedEntities)
{
    // Obtain the system from the World (example using Default world; adapt to your mod's world)
    var world = Unity.Entities.World.DefaultGameObjectInjectionWorld;
    var saveSystem = world.GetOrCreateSystemManaged<Game.Serialization.SaveGameSystem>();

    // Configure the system
    saveSystem.stream = System.IO.File.OpenWrite(path);
    saveSystem.context = saveContext;
    saveSystem.referencedContent = referencedEntities;

    // Run a single save operation and await completion
    await saveSystem.RunOnce();

    // Cleanup the stream after save completes (context/referencedContent disposed by system's OnDestroy or managed by caller)
    saveSystem.stream.Dispose();
}

Additional notes: - Ensure you set stream and context before calling RunOnce(). The context property will dispose any previously assigned Context instance automatically. - The system relies on WriteSystem.writeDependency to detect job completion — the WriteSystem is expected to schedule/own the job that writes serialized data. - referencedContent, if created and assigned, will be disposed by OnDestroy; if you allocate it for a single save you can also dispose it yourself after completion if appropriate. - Because the system enables itself only during a RunOnce call, you can call RunOnce multiple times to perform separate save operations.