unity-addressables-design

Every LoadAssetAsync or InstantiateAsync call returns a handle with refcount 1 that must be released via Addressables.Release or Addressables.ReleaseInstance. Forgetting to release keeps the AssetBundle in memory indefinitely, and using GameObject.Destroy on an instantiated instance does not decrement the refcount.

Addressables 2.9.1 removed all non-Async APIs like LoadAsset and Instantiate, replaced IList<object> multi-key overloads with IEnumerable, and added SceneReleaseMode for scene bundle lifetime control. LegacyResourcesLocator, DiagnosticEvent, and RegisterDiagnosticCallback were also removed.

Unity 6 ships Addressables 2.9.1, which removed every [Obsolete] non-Async method such as LoadAsset, Instantiate, LoadScene, and Initialize. Replace each with its Async counterpart and switch IList<object> key arguments to IEnumerable overloads.

WaitForCompletion is unsupported on WebGL and throws because the JS backend cannot synchronously pump async operations. Use await handle.Task or the Completed event instead, and guard any WaitForCompletion usage with platform conditionals.

Call CheckForCatalogUpdates first to get only the stale catalog locator IDs, then pass that list to UpdateCatalogs instead of updating everything. On 2.9.1 you can also pass autoCleanBundleCache true to remove orphaned bundles in the same call.

AssetReference caches its OperationHandle, so calling LoadAssetAsync twice without releasing throws an active-handle InvalidOperationException. Either call ReleaseAsset between loads or use Addressables.LoadAssetAsync with ref.RuntimeKey for independent concurrent loads.