GameObjects and components

What capture produces#

For each GameObject you assign, the framework records:

• the object's identity (PersistentId), never its InstanceID;
• its transform — local position, rotation and scale;
• every supported component on it, by type.

class="tok-com">// The component does this for you; this is the same call it makes.
var projection = projector.Project(gameObject);   // main thread only

Unity's GetInstanceID is never used for identity: it changes between runs and builds, so a save that relied on it would point at the wrong object after a restart.

Including and excluding fields#

The default is to include the public, serialisable surface. Two attributes change that explicitly:

public sealed class PlayerState : MonoBehaviour
{
    public int health;
    public Vector3 spawnPoint;

    [PersistIgnore] public float debugTimer;   // reported as class="tok-str">"left out on purpose"
    [PersistField] private int privateScore;   // included deliberately
}

Refusals instead of silent loss#

If something in the assigned set cannot be persisted, the capture is unusable (IsUsable == false) and the reason is reported with what happened, why, and what to do instead. A save that quietly lost a field is worse than a save that refused, because the player finds out later.

How much is captured#

• Reflection results are cached per component type per session, not recomputed per save.
• A capture depth limit bounds how deep nested objects go; anything deeper is refused rather than followed forever.
• A capture of around forty objects stays well inside a frame budget, which the test suite measures.

Next#

• ScriptableObjects — persisting assets rather than scene objects.
• Supported types — exactly what can hold a value.
• Unsupported types — what is refused, and the suggested alternative.