unity-addressables-design

Call LoadAssetAsync or InstantiateAsync and always pair it with a matching Release or ReleaseInstance call, since every handle starts with refcount 1 and the bundle only unloads at zero. Never use GameObject.Destroy on instances from InstantiateAsync.

Addressables 2.9.1 removed all obsolete non-Async methods like LoadAsset and Instantiate, replaced IList<object> multi-key overloads with IEnumerable, and added the SceneReleaseMode enum for scene loads. LegacyResourcesLocator and diagnostic event types were also removed.

Unity 6 ships Addressables 2.9.1, which removed every [Obsolete] API from 1.22.3 such as Addressables.Initialize, LoadAsset, and UnloadScene. Replace each with its Async-named equivalent and switch IList<object> key arguments to IEnumerable.

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, reserving WaitForCompletion for editor tests guarded by platform defines.

Call CheckForCatalogUpdates first, then pass the stale catalog list to UpdateCatalogs, releasing all open asset handles beforehand. On 2.9.1, UpdateCatalogs offers an autoCleanBundleCache parameter to remove outdated bundles in one call.

AssetReference caches its OperationHandle, so a second LoadAssetAsync without releasing throws an active-handle InvalidOperationException. Either call ReleaseAsset between loads or load concurrently via Addressables.LoadAssetAsync with ref.RuntimeKey.