Core Concepts

Asset References separates the stable identifier used by gameplay logic from the Unity asset assigned in the project. Game Creator selectors, variables, and custom code use a Reference ID; the repository owns the asset, metadata, load mode, and runtime lookup state behind that ID.

Reference IDs

A Reference ID is the shared name used by selectors, serialized fields, variables, C# calls, and usage scanning. Use readable, stable IDs such as:

audio-hit-impact
prefab-boss-enemy
sprite-ui-key-icon
material-slime
scene-dungeon-entry

Moving the assigned asset in Unity should not require changing every usage of its Reference ID. Renaming the ID is a separate maintenance operation and should be followed by a usage audit.

Direct and Streamed modes

Mode	Repository data	Documented runtime behavior
Direct	Serialized Unity asset reference	Cached and resolved synchronously.
Streamed	Addressables registration metadata	Loaded through the Addressables-backed loader when required.

Start with Direct mode and choose Streamed mode intentionally for large or optional content that needs an explicit loading lifecycle.

Enabled state

Disabled entries retain their ID and metadata in the editor but are skipped when the runtime cache is initialized. Disable an entry when its naming history and usages still matter; remove it when the ID should no longer exist.

Only one enabled entry may use a given ID.

Metadata

Display Name, Category, Tags, Notes, and Type Override help designers find and understand entries. They do not replace the stable Reference ID. Categories provide broad grouping; tags provide workflow-specific filtering and can also become Addressables labels for Streamed entries.

Resolution lifecycle

1. A selector, variable, Instruction, Condition, Event filter, or script supplies an ID.
2. The runtime cache looks for an enabled entry.
3. A Direct entry resolves from its serialized asset.
4. A Streamed entry may load through Addressables according to its preload policy.
5. Resolution, loading, release, or missing-reference events can notify interested workflows.
6. A Streamed handle is released according to its release policy or an explicit call.

See Streaming and Addressables and C# API for synchronous and asynchronous resolution behavior.

Project assets, not scene instances

Asset References is intended for project assets and prefabs. Use Game Creator Alias when a scene object needs an ID.