Smart Reference

version 2.1.0

DocFX Build and Publish GitHub release (latest by date) openupm Unity Asset Store

Summary

Smart Reference is a Unity plugin that enables lazy loading asset references in ScriptableObject and MonoBehaviour. In Unity, referencing assets directly creates implicit dependencies. When the MonoBehaviour or ScriptableObject is loaded, all referenced assets are loaded immediately, which can lead to slow startup times and unnecessary memory usage, especially in data driven projects.

Smart Reference solves this by allowing you to reference assets without loading them upfront, while keeping the same editor workflow. Assets are only loaded when you use them at runtime.

Quick Start

1. Replace direct Unity references with SmartReference<T>

In the Inspector, SmartReference looks and behaves like a normal object reference.

using UnityEngine;
using SmartReference.Runtime;

public class MonsterData : ScriptableObject
{
    public SmartReference<GameObject> prefab;
    public SmartReference<Sprite> icon;
    public string description;
}

2. Initialize Smart Reference at startup

Choose the loader that matches your project setup.

using SR = SmartReference.Runtime.SmartReference;

SR.InitWithAddressablesLoader();

Resources

using SR = SmartReference.Runtime.SmartReference;

SR.InitWithResourcesLoader();

Custom Loader

using SR = SmartReference.Runtime.SmartReference;

SR.InitWithCustomLoader(new MyCustomLoader());

Initialization must happen once, before any SmartReference is accessed.

3. Load assets when needed

var prefab = await monsterData.prefab.LoadAsyncUniTask();
Instantiate(prefab);

Asynchronous Loading with Awaitable (Unity 2023.2+ / Unity 6, no dependency)

var prefab = await monsterData.prefab.LoadAsyncAwaitable();
Instantiate(prefab);

Each call returns a new Awaitable, which must only be awaited once.

Asynchronous Loading with C# Async/Await

var prefab = await monsterData.prefab.LoadAsyncTask();
Instantiate(prefab);

Asynchronous Loading with Callbacks

monsterData.prefab.OnAsyncLoadComplete += go =>
{
    Instantiate(go);
};
monsterData.prefab.LoadAsync();

Synchronous Loading

var prefab = monsterData.prefab.Value;
Instantiate(prefab);

Value loads the asset on first access. You can also call Load() ahead of time and read Value later.

4. Keep references up to date in builds

Smart Reference stores the asset path next to its GUID. Before each player build, the paths of all references in assets, prefabs and scenes are updated, so moved or renamed assets still load. You can also run it from Tools > SmartReference > Update All References.

Addressables content builds don't run player build callbacks. To update references before them, create Assets > Create > Addressables > Content Builders > SmartReference Packed Mode, add it to Build and Play Mode Scripts in your Addressables settings, and select it as the build script.

Supports

If you have questions or feedback:

Thank you for your support!