Asset references | PersistKit 1.0.0 documentation

The asset registry — how a save file points at a Sprite, a ScriptableObject or a prefab and finds it again in a player build.

Why a table is needed#

A save file cannot hold a Unity object, and it cannot hold an asset path (a path is an editor idea and does not exist in a player build), or a GUID (nothing at run time can turn one back into an asset without a table), or an instance id (that changes every time the game runs). So the table is the honest answer:

text

save file        the registry                 the build
---------        -------------                ---------
"lantern"   ->   "lantern" -> Lantern.prefab -> the asset itself

The key is authored data, so it is the same in every build and on every machine.

Setting one up#

Tools → PersistKit → Asset Registry. The registry asset is created the first time you ask for it, in the folder the runtime looks in: Resources/PersistKit/PersistKit Asset Registry.
Select an asset in the Project window and Tools → PersistKit → Register Selection in the Asset Registry, or press Register this asset on the field that holds it. A short key is suggested from the asset's name.
That key is what a save file will hold.

A game that keeps its assets somewhere else — an Addressables catalog, a manager object, its own settings file — can assign PersistKitAssetRegistry.Instance before the first save, and nothing in Resources is looked at. That is the whole seam: one property.

Using it#

csharp

Persist.Save(class="tok-str">"selected-skin", spriteAsset);

Sprite skin = Persist.LoadReference<Sprite>(class="tok-str">"selected-skin", null);

if (skin == null)
{
    Debug.LogWarning(Persist.LastResult);   // PK-REF-005: this build cannot resolve that key
}

The kind of asset you ask for has to be the kind that was saved: asking for a Sprite when the key holds a prefab is refused with PK-VALUE-001, not cast to something plausible.

When a key cannot be resolved#

Code	What it means	What to do
`PK-REF-004`	The asset has no key	Register it: press Register this asset, or add it to the registry
`PK-REF-005`	This build's registry has no such key, or the entry is empty	The asset was left out of the build, or the registry in this build is a different one
`PK-REF-006`	One key names two assets, or one asset has two keys	Keep one key per asset: the editor validation lists the pair
`PK-REF-007`	That key is not something that can be made into a scene object	It was used where a prefab was expected

The editor validation pass (Tools → PersistKit → Validate Scene and References) reports all four, plus saved asset keys this project cannot resolve.

Next#

Saving objects the game spawned
Prefabs and Addressables — see the note below
Error codes

Addressables#

Not supported The package resolves assets through the registry, which works with a plain Resources folder or with any table you supply through PersistKitAssetRegistry.Instance. An Addressables-aware resolver of your own can be set through that same property; PersistKit does not ship one, and does not depend on the Addressables package.