Skip to content

Saving Asset References

PlayMaker can save references to project assets such as Sprite, AudioClip, Material, and other UnityEngine.Object assets.

This is configured in PlayMakerSaveSettings with the Asset References option.

This page builds on the main Save System guide.

Asset references are different from scene references:

  • Scene objects and components are saved by scene/object identity.
  • Assets are saved by an asset key and resolved later through an asset reference strategy.

Note

Asset reference saving is intended for asset types derived from UnityEngine.Object, but not for GameObject or Component scene references.

Asset Reference Modes

Open your save settings asset and find Asset References.

You can choose one of three modes:

Mode What it does
None Disables runtime support for asset-backed variable references. Use this if you only save scene objects and primitive values.
Registry Uses PlayMaker's built-in asset registry. Assets are saved by generated asset id and resolved through the registry at runtime.
Custom Lets your project provide its own IAssetReferenceStrategy implementation in code.

What Gets Saved

When PlayMaker saves an asset reference, it stores a stable asset key inside the save file rather than embedding the asset itself.

In the built-in registry workflow, that key is a generated asset id based on the asset's GUID and local file id. At load time, PlayMaker looks up that id in the registry and resolves the asset using the entry's load mode.

This keeps save files small and allows the same saved value to resolve back to the correct asset later.

Registry Mode

Choose Registry when you want a built-in workflow with no custom runtime serializer code.

Step 1: Create or open PlayMakerSaveSettings

Create the settings asset if you do not already have one:

Assets -> Create -> PlayMaker -> Save System Settings

Place it in a Resources folder so PlayMaker can load it automatically at startup.

Step 2: Set Asset References to Registry

This enables the built-in AssetRegistryReferenceStrategy.

Step 3: Add assets to the registry

Only assets in the registry can be saved and loaded by the built-in asset reference system.

You can:

  • Add entries manually
  • Use Add Matching to scan for assets by path pattern
  • Use Replace Registry to rebuild the list from the current filter
  • Use Remove Duplicates to clean repeated asset ids
  • Use Refresh Registry Paths after moving or renaming assets

Step 4: Pick a load mode for each entry

Each registry entry has its own runtime load mode:

Load Mode When to use it
Direct Reference Best for small projects. Simple setup, but the registry stores direct asset references.
Resources Best when the asset is in a Resources folder and should be loaded by its Resources path.
Custom Best when your project resolves assets through its own runtime key or loading system.

Note

The current inspector exposes Direct Reference, Resources, and Custom for registry entries. AddressableKey exists in code but is not exposed in this inspector yet.

Registry tips

  • Resources entries must point to assets inside a Resources folder.
  • Sub-assets in Resources are saved as path:subAssetName.
  • Custom registry entries require your project to assign AssetRegistryReferenceStrategy.CustomKeyResolver.
  • If an asset is missing from the registry, PlayMaker cannot capture it in Registry mode.

Custom Mode

Choose Custom if your project already has its own asset lookup system and you want full control over capture and restore.

In this mode, your project must assign ObjectReferenceSerializer.AssetReferenceStrategy in code before save/load happens.

For the API details and implementation example, see Save System API.

When To Use Which Approach

  • Use None if you are only saving numbers, strings, booleans, and scene references.
  • Use Registry if you want a built-in PlayMaker workflow for assets like sprites, audio clips, and materials.
  • Use Custom if your game already uses its own catalog, database, addressable key, or content pipeline.

Troubleshooting

The asset does not restore after loading

Check the following:

  • The settings asset is inside a Resources folder
  • Asset References is set to the intended mode
  • The asset type is supported by the chosen strategy
  • In Registry mode, the asset exists in the registry
  • In Resources mode, the generated path still matches the asset's current location
  • In Custom mode, your bootstrap assigns ObjectReferenceSerializer.AssetReferenceStrategy before load happens

The reference saves in the Editor but not in a build

This usually means the runtime resolver cannot find the asset in the player. For example:

  • A Direct Reference asset was stripped or not included as expected
  • A Resources asset is not actually under a Resources folder
  • A custom resolver depends on editor-only APIs

See also: Save System and Save File Viewer.