Persistent IDs

Why identity is the foundation#

A save records which object a value belongs to. If that identifier changes between runs, the save points at the wrong thing — a weapon with the wrong stats, a door keyed to a boss. Unity's InstanceID changes between runs and builds, so it is never used. Identity comes from PersistentId:

public string id;                          // plain field, if you generate it yourself
class="tok-com">// or, add the component the package ships:
class="tok-com">//   NexusForge > Persistent Identity

PersistentIdentityBehaviour stores an object's id in the scene or prefab, so it travels with the object. It is also what prefab instances adopt when they are reconstructed — see Prefabs.

Validating identity before it hurts#

NexusForge → Persistence → Validate Persistent Identities scans prefabs and open scenes and reports:

The same checks appear as findings in the Inspector's validation panel while you work, in the package's one diagnostics format, so there is a single place to look rather than two.

Duplicate identity at restore time#

If two live objects claim one identity, restore does not pick one silently. The default policy is ReportAndSkip: it reports the ambiguity and skips the entry, leaving the game in control. UseFirstAndReport and Fail are the other options. See Restore.

Next#

• References — turning an id back into a live object.
• Prefabs — how a reconstructed instance adopts its identity.
• Supported types — identity-based references in the field plan.