Restore
Applying a save back onto live Unity objects under an explicit policy, with every disagreement reported rather than guessed at.
The other direction#
Capture writes live objects into a document. Restore applies that document back onto live objects, over the same field plan — so what is saved and what is restored cannot drift apart.
class="tok-com">// 1. Load the slot as the document it holds.
var loaded = await NexusForgePersistence.Load<DataNode>(class="tok-str">"player", schemaVersion);
class="tok-com">
// 2. Apply it, on the main thread, under a stated policy.
var ok = UnityObjectApplier.TryRestore(loaded.Value.Data, out var report, PersistenceRestorePolicy.CreateDefault());The component does both steps for you: RestoreNow(), RestoreAsync(), or Restore when this attaches in the Inspector. Restoring is always explicit — loading a file never overwrites game state by itself.
Every disagreement is a decision#
| Question | Values | Default |
|---|---|---|
| A saved object has no live object | Report, Ignore, ReconstructThroughFactory, Fail | Report |
| A live field is absent from the save | LeaveLiveValue, ResetToDefault, Report | LeaveLiveValue |
| A field cannot be applied at all | Report, Fail, Ignore | Report |
| A stored value does not fit its field | Report, ResetToDefault, Fail | Report |
| A stored reference resolves to nothing | ClearAndReport, KeepLiveValue, Clear, Fail | ClearAndReport |
| Two live objects claim one identity | ReportAndSkip, UseFirstAndReport, Fail | ReportAndSkip |
| A prefab key cannot be satisfied | Report, Warning, Fail | Report |
Presets: CreateDefault(), CreateLenient() (restore what is there, stay quiet about known gaps) and CreateStrict() (stop at the first disagreement, for test scenes and strict game modes). One extra switch, StopOnPolicyFailure, decides whether a Fail policy halts the batch.
Every issue in UnityRestoreReport carries what happened, why, and what to do. A missing object, for example, reports the identity it could not find and names RegisterPersistentObject, an injected resolver, or the prefab factory as the three ways forward.
What gets restored#
Everything capture writes: scalars, strings, dates, Guid, TimeSpan, decimals, enums (by name), nullables, Unity value types, animation curves and gradients, arrays, List<T>, HashSet<T>, Queue<T>, Stack<T>, Dictionary<TKey,TValue>, nested objects with parameterless constructors, GameObject transforms and identity-based references.
Honest limits#
- A reference is a pointer, not a copy. Restoring an object does not restore the objects it points at; capture them too if their state matters.
- Nested objects need a parameterless constructor. Without one, the restore says so and suggests
[PersistIgnore]or a custom path. - Several components of one type on one object share one entry — the save records components by type.
- A component that no longer exists on a matched object is reported as a warning.
- Restoring is main-thread only and refuses elsewhere, exactly like capture.
- Nothing is created, cleared or overwritten without a policy saying so, and every decision appears in the report.
Next#
- References — how identity resolution actually works.
- Prefabs — reconstruction through your own factory.
- Persistent IDs — the identity everything else depends on.
Something wrong on this page? Every page here describes behaviour that is checked in the repository. If a page and the package disagree, the package wins.
Report a documentation problem · Frequently asked questions · Troubleshooting