Objects, scenes and things gone for good

Identity is one name across every loaded scene#

An object PersistKit should remember carries a PersistKit Identity: a short id — campfire, player-ship — that your game chose and that stays the same next run. That id is one namespace across everything that is loaded: the main scene, every scene loaded additively, and objects kept across scene loads with DontDestroyOnLoad.

Two objects in two different scenes claiming one id is not "two objects with the same name" — it is a save that cannot be answered, and PersistKit refuses it (PK-REF-003) rather than picking one. An id must be unique in the whole running game, not just in the scene it was typed into; a prefix does that job (camp-1-chest).

An object is found wherever it is now#

• An object in an additively loaded scene is found exactly like one in the main scene.
• An object kept with DontDestroyOnLoad keeps its identity and is still found after the scene it was made in has been unloaded.
• A scene that is not loaded cannot be searched: the load reports PK-REF-001 and returns your default. It never invents an object and never edits the save file to "fix" it.

A level you leave and come back to#

Unloading a scene destroys its objects, and their ids go with them: a load while the scene is unloaded reports PK-REF-001. When the scene is loaded again with the same objects and the same ids, the same save resolves again — the save file is not involved, which is why coming back is cheap. PersistKit never re-creates a scene object, because it never created one in the first place: the game decides what is loaded.

Destroyed objects are reported, never resurrected#

• A scene object the game destroyed is simply not in the loaded scenes any more, so a load reports PK-REF-001.
• A destroyed part of an object is reported, and the rest of the object is still restored — the part is never added back.
• An object the game destroyed and then saved is left out of the write, and Persist.SaveInstances says so.

Objects the game made from a prefab#

Persist.Spawn is the only thing PersistKit ever creates, and it creates it from a key in the asset registry:

var crate = Persist.Spawn(class="tok-str">"crate", class="tok-str">"crate-3", parent);   // made, with a stable id
Persist.SaveInstances(class="tok-str">"crates", myCrates);               // the whole set, places included
Persist.LoadInstances(class="tok-str">"crates", parent, into);           // found by id and reused, or made again

Nothing is created twice (an id already in the scene is reused, so loading the same save twice leaves one object), a load makes the set match the save rather than adding to it, and a prefab this build does not have is reported by key and skipped while the rest of the set still comes back.

Retired objects: gone for good#

A save lists what was in the world when it was written, which cannot say "and this one is gone for ever". The player smashed the crate; loading the save must not rebuild it. That is what retiring an id is for:

Persist.Retire(class="tok-str">"crate-7");        // the destruction is permanent
Destroy(crate);

Persist.LoadInstances(class="tok-str">"crates", parent, into);
class="tok-com">//   class="tok-str">"1 instance had been retired, so it was not made again"

The list is a small note beside the save, in the slot the game is using, so deleting or renaming a slot takes it with the slot. A retired id is skipped by LoadInstances and refused by Spawn with PK-INSTANCE-001, and SaveInstances leaves a retired object out of the write. A retire that could not be written is reported as a failure — the object is retired for this run, and the message says a later run could bring it back, rather than pretending the note is on disk.

What is verified#

Every behaviour on this page runs in the package's PlayMode suite (LifecyclePlayModeTests): an id in an additive scene, a scene unloaded and visited again, DontDestroyOnLoad across an unload, two scenes claiming one id, a retired instance staying gone through a load, unretiring, a retired instance left out of the next save, retiring across a restart, forgetting the list without deleting the save, and a damaged list believed line by line. The current counts are on Platforms and limitations.

Known limits in this version#

• Retiring applies to instances PersistKit creates. A scene object needs no tombstone: the scene the game loads decides whether it exists.
• The retired list belongs to one slot. A save per chapter means a retired list per chapter.
• Ordering is the game's job. Load a save after the scenes it needs are loaded, or you get honest PK-REF-001 reports instead of a half-restored world.
• A retired id needs unretiring before it can be used again — a new object should get a new id.
• No Addressables dependency, and none is needed: a prefab is found by registry key, a scene object by identity.