Addressables-Sample: what Unity's own sample project teaches about reference counting

The disclaimer comes first, and it is the important sentence

The opening paragraph of the README is unusually blunt for a first-party sample. These samples are broken up into projects based on high level functionality, and they are intended as jumping off points for your own development. Then comes the qualifier: they have not been tested, they are not guaranteed to work in your situation, they are just examples to make some concepts easier to understand or to replicate in your own project, and you should use them at your own risk.

That sentence shapes how the repository should be used. It is a concept demonstrator, not a supported project, and the code should be read rather than copied wholesale. The repository layout matches that framing: a `Basic/` directory and an `Advanced/` directory, with no library, no package manifest and no test suite at the root.

The support route is also stated, and it points outside the repository. Bugs go through Unity's regular bug submission process, and questions go to the Unity forum thread for Addressables. There is no issue tracker discussion in the README beyond that, which is a signal that the repository is a distribution point for samples rather than a community project.

Maintenance has been intermittent. The only release listed is 0.7, compatible with Addressables 0.7.x, from 2019-05-10, and the last push to the repository was on 2026-05-06. The sample text also refers to Addressables 0.8 behaviour and to 2019.3 alpha versions of the engine, so the code is written against an old generation of the package.

Reference counting is the whole point of the BasicReference scene

The first project, `Basic/Basic AssetReference`, is described as several sample scenes displaying functionality around the asset reference class, and it is where the mental model starts.

The `Scenes/BasicReference` scene is the simplest example: a reference to spawn and destroy a game object. Each object is instantiated directly via the `AssetReference`, which increments the reference count. Each spawned object carries a script that causes it to release itself after a certain amount of time, which destroys the object and decrements the count.

Then there is the detail that makes the design safe. Any instances still around when the scene closes are automatically released by the scene closing process, even if their self-destruct script were disabled. The count is tied to the lifetime of the scene rather than to the discipline of your spawn code, which is what makes the pattern usable in a real project where objects are spawned from many different places.

The term the README uses for this is the reference count, and the whole project exists to show where it increments and where it decrements. Everything else in the sample set, the alternative instantiation paths, the filtered references, the component references, are variations on the same question: who owns this instance, and who is going to release it.

Why AssetReference keeps its own asset in a member called .Asset

`Scenes/ListOfReferences` demonstrates references used inside a list, and the note attached to it explains a race condition that is easy to hit and hard to diagnose.

The key feature is that once an `AssetReference` is loaded it keeps a member called `.Asset`. The README says you would not want to use the on-complete callback to save off the asset in this example, because the loads may not complete in the same order as they were triggered. It is useful, the note says, that the reference keeps up with its own loaded asset.

That is the point: the reference is the handle, and the asset is a property of the handle. If you keep your own copy keyed by index or by name, a completion that arrives out of order writes to the wrong slot, and the bug appears as the wrong texture on the wrong object under load. Reading `.Asset` from the reference that requested it cannot be mismatched.

The scene also demonstrates a mismatch of another kind, and the README is explicit that it is a mistake rather than a feature. Here the objects are instantiated via the traditional `GameObject.Instantiate`, which does not increment the Addressables reference count. These objects still call into Addressables to release themselves, but since they were not instantiated via Addressables, the release only destroys the object and does not decrement the count. The consequence is spelled out: the manager of these AssetReferences must release them in `OnDestroy`, or the reference count survives the closing of the scene.

So the sample teaches two lessons at once. Keep the asset on the reference, and be careful about who incremented the count.

FilteredReferences shows a release behaviour that is scheduled to change

`Scenes/FilteredReferences` shows the various filtering options on the `AssetReference` class, and it also shows an alternative loading pattern to the one used in the other scenes, using the `Asset` property rather than the completion callback. The README recommends using `Asset` for ease of load and warns that you could theoretically use it to poll completion, but that you would never find out about errors in that usage.

The interesting part is what happens on release. The sample loads via the `AssetReference` but instantiates via Unity's built-in method, so the reference count is incremented once, for the load, and not for the instance. The objects created are then destroyed with `Addressables.ReleaseInstance` even though they were not created that way.

The README then describes what is coming. As of version 0.8, this will throw a warning, but it will still delete the asset. And in the future, the stated intent is to make the method not destroy the asset, or to print a warning, and instead return a boolean so you can destroy manually if needed.

That is a scheduled API change to a method whose current behaviour is silently wrong in an obvious way. The sample is dated here, and the note is a promise that the behaviour will be tightened.

Subobjects load their parent first, in the editor and at runtime

`Scenes/SubobjectReference` covers references with sub objects, and the explanation is short and precise.

An `AssetReference` contains a main asset, referred to as `editorAsset`, and an optional sub object. Certain reference types, for example references to sprite sheets and sprite atlases, can use sub objects. If the reference uses a sub object, then it loads the main asset during edit mode and loads the sub object during runtime.

The scene demonstrates both halves: loading a sprite from a sprite sheet as a main asset, and loading a sprite as a sub object during runtime. The reason the two are separated is a consequence of how sub objects are stored. A sprite inside an atlas is not an independent asset on disk, it is an entry inside a larger one, so the runtime has to bring in the whole thing and then select the part, while in the editor the reference needs the container to resolve the entry.

This is the kind of detail that the API reference states and the sample makes concrete, and it is a common source of confusion for people moving from a plain asset reference to a sprite atlas reference.

Additive scene loading, and who cleans up the instances

The scene loading project is a small, complete demonstration of the scene side of Addressables.

`Scenes/Bootstrap` is the scene to start with, and from it you can transition to the other scenes. A button labelled "Transition to Next Scene" opens a new scene non-additively, which closes the current scene. Another button, "Add Object", instantiates an addressable prefab into the scene, and the point of that button is to show that these items do not need `ReleaseInstance` called on them: if you use the Profiler, you will see they get cleaned up on scene close.

`Scenes/Foundation` is the scene you transition to from Bootstrap, and its "Load" buttons open other scenes additively while the "Unload" buttons unload scenes that have been additively loaded. `Scenes/ItemScenes` holds scenes that contain only items and no code, whose purpose is to be additively loaded by the Foundation scene. That separation of an empty scene from a scene that drives it is the standard way to test additive loading, and it makes the lifetime of each loaded scene visible in the UI rather than implied.

The combination of the two projects is the lesson: instances and scenes have two different lifetime mechanisms, and the scene closing process releases what it owns, which is why the BasicReference scene can rely on it and why the ListOfReferences scene cannot, since those objects were instantiated outside Addressables.

A generic ComponentReference will not serialize without a concrete subclass

The component reference example creates an `AssetReference` that is restricted to having a specific component, and the reason it needs two classes rather than one is the most transferable lesson in the repository.

`Samples/Addressables/1.19.19/ComponentReference/ComponentReference` defines `ComponentReference<TComponent>`, which inherits from `AssetReference`. It is generic and does not specify which components it might care about, and a concrete child of this class is required for serialization to work. At edit time it validates that the asset set on it is a GameObject with the required component, and at runtime it can load or instantiate the GameObject and then return the desired component. The API matches the base class, `LoadAssetAsync` and `InstantiateAsync`.

`Scripts/ColorChanger` provides the component type chosen to care about, and the note explains why the file also contains a concrete version of the ComponentReference. If your game code only specified a `ComponentReference<ColorChanger>`, it could not serialize or show up in the inspector, and the concrete `ComponentReferenceColorChanger` is what makes the serialization and the inspector UI work.

The release rule is specific as well. Releasing a `ComponentReference<TComponent>` should be done through the `ReleaseInstance()` method in the `ComponentReference<TComponent>` class, and the README points to the implementation of that method to understand the requirements for releasing an instance directly.

The `Scenes/SampleScene` puts it together, with a Spawner game object that alternates between spawning a direct reference prefab and an addressable one, where both the direct reference and the addressable component reference can only be set to one of the prefabs carrying the `ColorChanger` component.

Where this sample is the wrong thing to build on

The first limitation is stated by the project itself: these samples have not been tested and are not guaranteed to work in your situation. A repository that says this in the first paragraph is not a foundation, and the natural use is to read it.

The second is age. The only listed release is 0.7, from 2019, the text discusses version 0.8 behaviour as a future, and the sprite demo notes are tied to 2019.3 alpha and to a backport to 2019.2 and 2018.4. The Addressables package has moved on since. The ref counting model in the samples is still the right model, but the specific method behaviour the README describes, in particular the `ReleaseInstance` on a non-Addressables instance, is explicitly scheduled to change, so a project built on the current description would be building on a behaviour that is documented as going away.

The third is the licence. The repository records no licence identifier, and there is no licence file in the layout, which is `Basic/`, `Advanced/` and the README. Copying code from a repository with no stated licence terms is a question for a legal review, not a technical one, and it applies even to a first-party sample.

The fourth is the sprite demo, which comes with a warning of its own. The README records that an engine bug causing a crash when loading out of sprite sheets forced the demo to be removed, that it is back in 2019.3 alpha, and that if your game crashes or you get warnings about "gfx" not on main thread, you do not have a fixed version of the platform. A sample that documents its own crash conditions is a sample to read, not to ship.

Editorial conclusion

Adopt this repository as a reference when you are learning the Addressables package, especially the parts that are hard to infer from the API documentation: why an AssetReference keeps its own asset, what happens when you instantiate an object outside Addressables, and how release behaves when the scene closes. Do not adopt it as a starting template for a shipping project, because the README states the samples have not been tested and are not guaranteed to work in your situation. Before you copy any of it, check the `AssetReference` semantics in the version of the package you actually use, since the release behaviour described here is explicitly scheduled to change in a later version.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. Unity-Technologies/Addressables-Sample on GitHub