PersistentEntity

[DisallowMultipleComponent]
public sealed class PersistentEntity : NetworkBehaviour

Put this on a prefab or a scene object to make the entity outlive the process that simulates it. The worker's NebulaPersistence checkpoints every authoritative entity that carries one, and brings it back when a worker gains the lease of the container it was saved in.

What is saved: the entity's prefab (or scene id), its pose in its container, every PersistAttribute NetworkVariable and whatever each behaviour writes in NetworkBehaviour.WritePersistentState (see PersistentStateCodec). What identifies it across runs and workers is Key, which travels with the entity through handover, so a save written by one worker is the same record the next worker updates.

Fields

CheckpointSeconds

public float CheckpointSeconds;

Seconds between checkpoints of this entity. 0 = NebulaConfig.PersistenceCheckpointSeconds.

PersistPose

public bool PersistPose = true;

Save the entity's pose in its container, and put it back there on restore.

PersistVelocity

public bool PersistVelocity;

Save the entity's velocity as well (a rolling barrel, a drifting ship).

Properties

Key

public string Key { get; set; }

Stable identity of this entity in the store. Settable by game code until the first save (a player's inventory chest, a record the game restores by name); after that it is fixed, because the record in the store is keyed by it.

LastSavedAt

public float LastSavedAt { get; }

Time.unscaledTime of the last accepted checkpoint, 0 when never saved in this process.

IsDirty

public bool IsDirty { get; }

Something changed since the last checkpoint: the entity is due a save at the next opportunity.

HasBeenSaved

public bool HasBeenSaved { get; }

A record for this entity has been written (here or by the worker that handed it over).

LastSavedVersion

public ulong LastSavedVersion { get; }

Store version of the last record this process wrote or received with the handover. Informational.

Methods

MarkDirty

public void MarkDirty();

Ask for a checkpoint soon (coalesced with every other change since the last save).

EnsureKey

public string EnsureKey();

The key this entity saves under, generating one the first time it is needed: scene:<sceneId> for a scene object, <prefab>:<guid> for anything spawned from a prefab.

WriteHandoverState

public override void WriteHandoverState(NetworkWriter writer);

The identity travels with authority: the next worker updates the same record instead of writing a second one.

ReadHandoverState

public override void ReadHandoverState(NetworkReader reader);

WritePersistentState

public override void WritePersistentState(NetworkWriter writer);

Saves the entity's extent when it was set at runtime (NetworkIdentity.ExtentChangedAtRuntime), so a structure edited since it spawned comes back measured by its edited box (docs/entity-extents.md D7). Writes nothing otherwise, so an entity with an authored extent, or none, saves the record it always did.

ReadPersistentState

public override void ReadPersistentState(NetworkReader reader);

Restores the runtime extent WritePersistentState saved, before the entity spawns.

ToString

public override string ToString();