The main-thread requirement comes from the participants, not the router

Every framework participant resolves owners through StableIdOwners.Find<T>(), which calls Object.FindObjectsByType. Unity restricts that to the main thread and throws if called elsewhere — so an off-thread Capture or Restore fails loudly rather than corrupting anything.

The coordinator itself holds no state and touches nothing thread-bound beyond serialising the envelope. That distinction matters if you write a participant over pure data: the constraint is inherited from what a participant reads, not intrinsic to the routing.

If serialisation cost is the concern, the string is the boundary — write it to disk on a background thread once you have it.

A half-applied section is not a refused one, and must not be carried over

Currency, Inventory and Status Effects all restore owner by owner, so any of them can apply three wallets and refuse the fourth. Filing that alongside a genuine refusal would invite you to pull the lever in §5 — omit the participant from the next capture so its section survives — which writes the whole section back, returning the three wallets that did load to what they held before, and discarding everything the player has done since.

So the two are separate lists. Unapplied is safe to carry because nothing in it was applied. PartiallyApplied is kept for diagnostics and backup only: it is the last intact record of state that is now half-overwritten, and recovering from it means reloading, because a partial restore has no undo.

Writing your own participant: throw an ordinary exception if you applied nothing — a version guard should run before you touch anything, which is what makes that true. Throw RevSavePartialRestoreException if you mutated something first.

A refused section is kept, but keeping it is not the same as preserving it

Unrecognised and Unapplied are deliberately separate lists. An unrecognised section belongs to a system this build does not have, and carrying it over always works. An unapplied one belongs to a system that is installed and refused the data — nearly always a payload from a newer build, after a version downgrade.

Carrying an unapplied section into the next capture will not resurrect it, because there is one section per key and the participant that refused it is still live and still captures. Current state winning is the right default: the alternative discards the session the player just finished in favour of data this build cannot read. The collision is reported, so the loss is never silent.

The lever, when you would rather keep the newer data: leave that participant out of the next capture. Nothing then claims the key, the section carries over as an ordinary unrecognised passenger, and it survives intact for whenever that build comes back. The cost is that the system does not save for the rest of the session — which is the honest trade, and yours to make.

The lever is safe because Unapplied only ever holds sections that were applied in full or not at all. A section that got halfway is deliberately kept out of it — see §4.

A displaced section is handed back, because that copy is the last one

When a passenger does lose its key, the section is returned in report.Displaced rather than only mentioned in a message. For one carried out of Unapplied that copy is the only one left: it is not in the save being written, and the save it came from is about to be overwritten by it. Stash it before you commit the file if it matters — recovering it afterwards is not possible.

It has its own status for the same reason. Skipped and Displaced were once one value, and they are opposites — a participant with nothing to write is the commonest non-event in a capture, while a displacement is data ceasing to exist. Reported alike, the only notice of a real loss read exactly like a no-op.

It does not fail the capture. One section per key is the rule rather than a fault, and the save produced is complete and valid — marking it failed would report correct work as broken and train you to ignore the flag. ToString() names the count in its header so a logged summary cannot read as a bare "OK".

Spawned objects need an id you choose

In a player build a spawned instance has no serialized id, so one is generated in Awake — a different one every launch. It is unique within the session, which is enough to capture, and useless afterwards, because nothing next session claims that id. Anything saved against it is silently unrestorable.

Call AssignId with something your game derives from durable data — a spawn table entry, a room and slot index, a quest id, a server key — before the object's state is captured.

One spawn path behaves differently in the editor than in a build

Id generation runs from Reset and OnValidate in the editor, and from Awake in a build — two separate branches. They agree everywhere except one case, and both behaviours are measured rather than assumed:

• AddComponent<StableId>() at runtime gets an id in both. Reset runs on AddComponent, in play mode as well as edit mode, and Awake covers the build.
• Instantiate never generates one. OnValidate does not fire on Instantiate. So a prefab whose id is blank produces a clone with no id in the editor — invisible to every participant, saved and restored as though it were not there — while the same spawn in a build gets a throwaway id from Awake, and is captured under an id nothing will ever claim again.

Neither outcome is useful, and testing in the editor will not show you the build's version of it. In practice this is a corner: a prefab only stays blank if nobody ever selected it in the Inspector, because doing so stamps an id into the asset — after which every instance shares that one id instead, which is the collision below and much the likelier problem.

Either way the fix is the same — AssignId at spawn time.

A section that matched nothing is reported, not counted as a clean load

One saved owner missing is ordinary and stays silent: a save outlives the objects it was taken from, and a level that no longer contains an enemy should not fail to load because of it.

All of them missing is a different event. The section applied to nothing, every other signal said the load succeeded, and the symptom the developer sees is a game full of default state with nothing anywhere to explain it. The usual causes are a scene that is not the one the save was taken in, and ids that have changed since — a runtime-spawned object gets a fresh id every launch unless StableId.AssignId is called with one of your own.

Reported as a plain refusal rather than a partial one, because nothing was applied: the section still describes exactly what the save held, so it stays in Unapplied and stays carryable.

Health, Currency, Inventory and Status Effects all do this. Crafting reports the equivalent per job — see §10.

HealthSnapshot is three fields, and that is the whole guarantee

Max, Current, Dead. Nothing else. A character saved mid-fight behind a shield comes back with the right health and no shield — silently, and reported as a successful load, because from the save system's point of view nothing failed.

This is Health's contract, not a save-system limitation: HealthSystem.RestoreSnapshot documents that it does not restore shields, regen timers or rule state. The participant cannot widen it without inventing a second, competing definition of health state.

If shields matter to your game, restore them through whatever granted them — a status effect via the Status Effects participant, or your own participant. See §11.

A snapshot that cannot be true is refused rather than clamped

RestoreSnapshot takes what it is given and clamps it, and documents that supplying something consistent is the caller's job. This participant is that caller.

It matters because of how a truncated file reads: an entry that lost its snapshot deserialises to all-zero, which clamps to Max = 1, Current = 0 — a character left alive on one hit point, with the load reporting success and nothing anywhere saying why. Entries whose max is zero or less, or whose current health falls outside 0..Max, are therefore reported and skipped instead. No capture can produce either, so one in a payload means the save was edited or truncated.

Dead is not checked against Current. The pairing looks inconsistent at zero health and is not: whether an object at zero is dead belongs to its death rules, which RestoreSnapshot restores none of. Rejecting a combination the live system can legitimately hold would refuse real saves in order to catch tampered ones.

A restore sets what the save contains, and removes nothing

The gap above is closed on the capture side. The other direction is deliberate and framework-wide: a participant applies onto existing state rather than clearing it first, so a currency the save never mentioned keeps whatever balance it has now.

In practice that means a currency first acquired after the save was written survives loading that save. If your game needs a load to be the whole truth for a wallet, zero it yourself before restoring — the same call ClearAll() makes for status effects.

A balance that cannot be applied does not pass quietly

Currency refuses a snapshot line carrying a blank id or a negative amount, so such a line cannot be restored. Leaving it out is correct; leaving it out silently is not — the player's wallet comes back lighter than they saved it and the load still reports success.

Those lines are counted and reported with the refusals, which marks the section Failed. Because invalid currency ids are rejected at construction, a line like this in a real payload means the save was edited or corrupted, not that the participant was set up wrong.

Blankness is judged the way Currency judges it. A CurrencyId normalises whitespace to empty, so " " is blank to Currency and non-empty to a naive string check. The line is tested through the id it will become, because the cost of the disagreement is not one dropped line: CurrencyPersistence.Restore validates a whole snapshot before applying any of it, so a bad line that gets that far refuses every balance in the same wallet — silently, and without being counted as unreadable at all.

A dropped job is a real loss, so it reaches the report

CraftingService.RestoreJobs returns void and drops a job it cannot identify with a log line — so before this, an asset rename cost the player an in-flight craft in complete silence, with the load reporting success.

The loss is not just the job. A craft consumes its inputs and its currency when it starts, so those were already spent when the save was written, and Crafting does not refund a job it drops.

Both resolvers belong to the participant, which is what lets it count the drops and put them in the report. The section is marked PartiallyApplied rather than Failed, because the live job list was already replaced by the time anything could be dropped — the one exception is a restore that found nothing in flight to clear and landed nothing, which is genuinely a no-op.

Resistance is applied again on every load, and it compounds

Step 2 above is not skipped for a restore. TimeRemaining ends up Duration × DurationScale, and that scale comes from the IStatusResistance providers on the target. So a poison saved with 20 seconds left, restored onto a target with 0.5× poison resistance, comes back with 10. Save and load again and it is 5.

Correct for a fresh application, wrong for a restore — the saved time already had the resistance in it when it was first applied. The multiplier is clamped to 0..1, so this only ever shortens: a save scummer walks their own debuffs toward zero rather than inflating them, which is the harmless direction but still not what the save said.

There is no hook to suppress it — the scaling happens inside the controller, past the point the participant hands the effect over. Divide by the resistance in your factory if it matters, or restore statuses before whatever grants it.

Restores are not uniformly silent, and this row used to say they were

The guarantee here read "Participants write state directly — no Died, no Revived, no HealthChanged", which is Health's contract stated as if it were the framework's. It is true of two participants and false of the other four, because a participant restores through whatever API its system exposes and most of those APIs raise on a write:

The advice does not change: reconcile from LoadCompleted. What changes is what you may assume in the meantime. A listener that treated "no event" as proof no load was happening was relying on a guarantee that only Health and Attributes ever offered — and the reason the row gave for the silence, that firing death events during a load would spawn VFX, is exactly what a Status Effects restore does today.

It is not a defect in the four. Restoring through the public API is what makes a restored status re-establish itself, a restored wallet respect its caps, and a restored container refuse what it cannot hold. Suppressing those events would mean a second write path per system, with its own bugs. What a listener can read instead is RevSaveRestore.InProgress, which is true for anything a restoring participant raises synchronously — see the note below for what it does and does not cover.

Slot and folder names are validated rather than made safe

A slot becomes a file name and the folder name becomes a directory, so both arrive from game code and reach a real path. Quietly rewriting "../../ProjectSettings" into something harmless would mean the caller's slot and the file no longer correspond, which surfaces much later as a load that silently finds nothing. Rejecting is the honest failure.

The folder name is the one exception, and for a specific reason: RevSaveManager builds its default store from a serialized inspector field, so an exception out of a property getter on the first save would be a far worse failure than saves landing in Saves with an error explaining why.

Order matters, and is yours to decide — unless a participant decides for itself

Participants are captured and restored in the order you supply them, stably sorted by IRevSaveOrdered for any participant that declares a position. Where two participants touch the same state — a shield status and Health's shield — the outcome depends on that order, and the coordinator will not detect or resolve the interaction for you.

The one such pair inside the framework now answers itself: CraftingSaveParticipant declares RevSaveOrder.Late, so it restores after Inventory and Currency wherever you listed it. A participant of your own that writes into another system's state should declare its position the same way. See §10.

Restore reads your list, not the file. That is what makes this an actual lever: the order inside a save was fixed by whichever build wrote it, from a participant list that may no longer exist, with carried-over sections appended after the live ones. Driving restore off the file would leave you reordering your list to no effect and no way to discover why. A section whose key no participant claims is still reported — routing does not depend on order, only sequencing does.