Custom memories#

A Memory captures one aspect of a game object's state through the Remember component. Use one to save a Unity or third-party component that your code doesn't own.

A Memory has two classes#

The outer class captures state, while a nested Data class restores the captured values:

using System;
using UnityEngine;
using VisualScript.Icons;
using VisualScript.Runtime;

[Title("Rigidbody")]
[Image(typeof(IconPhysics), ColorTheme.Type.TextLight)]

[Serializable]
public class MemoryRigidbody : Memory
{
    [Serializable]
    public class Data : Memory.Data
    {
        [SerializeField] private Vector3 m_Velocity;
        [SerializeField] private Vector3 m_AngularVelocity;

        public Data()
        { }

        public Data(Rigidbody body)
        {
            this.m_Velocity = body.linearVelocity;
            this.m_AngularVelocity = body.angularVelocity;
        }

        public override Awaitable OnLoad(GameObject gameObject)
        {
            Rigidbody body = gameObject.Get<Rigidbody>();
            if (body != null)
            {
                body.linearVelocity = this.m_Velocity;
                body.angularVelocity = this.m_AngularVelocity;
            }

            return AwaitableUtils.DontAwait;
        }
    }

    protected override string Title => "Rigidbody";

    public override Memory.Data OnSave(GameObject gameObject)
    {
        Rigidbody body = gameObject.Get<Rigidbody>();
        return body != null ? new Data(body) : new Data();
    }
}

After Unity compiles the file, Rigidbody appears in the Remember component's memory dropdown. OnSave captures linear and angular velocity, and Data.OnLoad restores them when the game object still has a Rigidbody.

The Data class#

Everything the memory needs to restore state goes in Data, and it must be serializable by Unity.

Data must be self-contained

The save system writes Data to disk and reads it back in a future session. Values that depend on the original runtime state won't identify the same objects afterward. These include live object references, coroutines, and indices into runtime lists.

Store values, IDs, and names. Resolve them back to live objects in OnLoad.

A parameterless constructor is required for deserialization.

OnLoad is asynchronous#

OnLoad returns an Awaitable, so a Memory can wait for a scene or asset to load, or for a system to become ready.

Return AwaitableUtils.DontAwait when the work is synchronous, which is the common case.

Defensive restoring#

The object being restored may differ from the saved version. A component may have been removed, the prefab may have changed, or the save may come from an older release. Handle those cases when restoring state:

Null-check every component you fetch.
Leave existing state unchanged when saved data is missing.
Check that indices and counts are still valid before using them.

A Memory that throws during load aborts the load. Prefer leaving one property unchanged when its source component or data is missing.

Cost#

Every Memory adds to the save file and to load time. Save the minimum that reproduces the state:

Save	Don't save
Values that gameplay changed	Values that never change
State that can't be recomputed	Anything derivable from other saved state
IDs and names	Live references

Memory or ISaveLoad?#

Choose based on who owns the component and whether designers should opt into saving it:

Write a	When
Memory	The state lives on a component you don't own, or should be opt-in per object.
ISaveLoad	It's your own component or asset and should always save itself.

A designer adds a Memory to a Remember component. A type implementing ISaveLoad controls its own registration, so it can participate without that per-object setup.

Checklist#

[Serializable] on both the memory and its Data.
Data holds only serializable, session-independent values.
Data has a parameterless constructor.
OnLoad null-checks and never throws.
Title returns a readable dropdown label.

Where to go next#

ISaveLoad — save your own components and assets directly.
Memories — inspect the built-in set and designer workflow.
Save lifecycle — place Memory capture and restoration in the full operation order.