test/Documentation/addressable-manager.md

AddressableManager Public API

AddressableManager is a Unity MonoSingleton wrapper around Unity Addressables. It initializes the Addressables system, loads selected asset types, caches loaded handles, and exposes methods for delayed or immediate release.

This document lists only the public functions from Assets/PerfectWorld/Scripts/Addressable/AddressableManager.cs.

bool IsInitialized()

Returns whether the Addressables initialization callback has completed successfully.

Use this when another system needs to quickly check if AddressableManager is ready before requesting assets. It returns true only after Addressables.InitializeAsync() finishes with AsyncOperationStatus.Succeeded.

If initialization fails, this method remains false.

UniTask WaitUntilInitializedAsync()

Waits until AddressableManager has finished initializing Unity Addressables.

If initialization has already completed, this returns UniTask.CompletedTask immediately. Otherwise, it waits on the internal initialization completion source that is resolved by the Addressables initialization callback.

Call this before loading assets from systems that may start before Addressables is ready.

Example usage:

await AddressableManager.Instance.WaitUntilInitializedAsync();

Task<TextAsset> LoadTextAssetAsync(string assetPath)

Loads a TextAsset asynchronously through Unity Addressables.

assetPath must match a valid Addressables key, normally the asset address. The method first increases the internal reference count for this path and removes the path from the delayed-release list so the asset will not be released while it is being used again.

If the text asset was already loaded and the cached handle is still valid, the method returns the cached TextAsset immediately. If no valid cached handle exists, it calls:

Addressables.LoadAssetAsync<TextAsset>(assetPath)

After loading completes, the handle is stored in the text asset cache and the loaded TextAsset is returned.

If loading throws an exception, the method logs an error and returns null.

Important behavior:

• The loaded asset is cached by assetPath.
• Repeated calls for the same valid path reuse the cached handle.
• The method may return null when the asset cannot be loaded.
• Release is not automatic after loading. Call a release method when the asset is no longer needed.

Task<GameObject> LoadPrefabAsync(string assetPath)

Loads a prefab asynchronously through Unity Addressables and returns it as a GameObject.

assetPath must match a valid Addressables key for a GameObject prefab. Before loading, the method removes the path from the delayed-release list. It then calls KeyExists(assetPath, typeof(GameObject)); if the key is considered missing, it logs a warning and returns null.

If the prefab is already cached and the cached handle is valid, the method returns the cached prefab immediately. Otherwise, it calls:

Addressables.LoadAssetAsync<GameObject>(assetPath)

After loading completes successfully, the handle is stored in the prefab cache and the prefab GameObject is returned.

If the Addressables operation reports an exception, or if an exception is thrown while loading, the method logs the failure and returns null. In the Unity Editor, failed paths are added to an invalid-path cache so later KeyExists checks can reject them quickly.

Important behavior:

• This loads the prefab asset itself, not an instantiated scene object.
• Callers that need an instance should instantiate the returned prefab separately.
• The loaded prefab handle is cached by assetPath.
• The method may return null when the key does not exist or loading fails.

Task<AudioClip> LoadAudioClipAsync(string assetPath)

Loads an AudioClip asynchronously through Unity Addressables.

assetPath must match a valid Addressables key for an audio asset. The method removes the path from the delayed-release list before checking the cache.

If the audio clip is already cached and the cached handle is valid, the method returns the cached AudioClip immediately. Otherwise, it calls:

Addressables.LoadAssetAsync<AudioClip>(assetPath.Trim())

After loading completes successfully, the handle is stored in the audio cache and the loaded AudioClip is returned.

If the Addressables operation reports an exception, or if an exception is thrown while loading, the method logs the failure and returns null.

Important behavior:

• The Addressables load uses assetPath.Trim().
• The cache key is the original assetPath string.
• Repeated calls for the same cached path can return immediately.
• The method may return null when loading fails.

bool TryGetCachedAudioClip(string assetPath, out AudioClip clip)

Attempts to retrieve an already loaded AudioClip from the internal audio cache without starting a new Addressables load.

If assetPath is null or empty, the method returns false and sets clip to null.

If the audio cache contains a valid handle for assetPath and the handle has a non-null result, the method assigns that cached AudioClip to clip and returns true.

If no valid cached audio clip exists, the method returns false and leaves clip as null.

Use this when a caller wants to play audio immediately if it is already loaded, while avoiding an async load path.

void ReleaseAsset(string assetPath)

Marks an asset path for delayed release.

This method does not immediately call Addressables.Release. Instead, it records a timestamp in the delayed-release dictionary. During Update, once the configured timeout has elapsed, the manager force releases the asset by path.

If the same path is released multiple times before it is force released, the earliest release timestamp is kept.

Important behavior:

• This is a delayed release request.
• The asset remains cached until the release timeout expires.
• If the asset is loaded again before timeout, load methods remove it from the delayed-release list.
• The path must match the same key used to cache the asset.

void ForceReleaseAsset(string assetPath)

Immediately releases a cached asset by path.

The method checks the prefab cache first, then the text asset cache, then the audio cache. If the path exists in one of those caches and the stored handle is valid, it calls:

Addressables.Release(handle)

After releasing, the method removes the path from the matching cache. For audio assets, it also logs that the audio asset was force released.

Important behavior:

• This releases immediately, unlike ReleaseAsset(string assetPath).
• Only one matching cache entry is released because the method uses an if / else if chain.
• If the path is not found in any cache, the method does nothing.

void ReleaseAsset(AsyncOperationHandle<GameObject> handle)

Releases a specific GameObject Addressables operation handle directly.

If the provided handle is valid, the method calls:

Addressables.Release(handle)

This overload does not remove entries from AddressableManager's internal prefab cache because it does not know which assetPath the handle belongs to. Prefer releasing by assetPath when the asset was loaded through AddressableManager and should also be removed from its cache.

void ReleaseAllAssets()

Immediately releases all cached prefab and audio assets.

The method iterates through the prefab cache and releases each valid prefab handle. It then clears the prefab cache. After that, it iterates through the audio cache, releases each valid audio handle, and clears the audio cache.

Important behavior:

• This releases prefab and audio caches.
• It does not currently release cached text assets from _loadedTextAssets.
• It logs "AddressableManager: Released all assets" after completing.
• OnDestroy calls this method automatically.

bool IsAssetLoaded(string assetPath)

Checks whether a prefab asset path is currently loaded in the prefab cache.

The method returns true only when _loadedPrefabAssets contains assetPath and the stored handle is valid.

Important behavior:

• This checks only loaded prefab assets.
• It does not check cached text assets.
• It does not check cached audio assets.

static bool KeyExists(object key, System.Type type = null)

Checks whether an Addressables key exists.

In non-editor builds, the method iterates through all loaded Addressables resource locators and calls:

locator.Locate(key, type, out var locations)

It returns true when a locator finds at least one matching resource location. If no locator finds a match, it returns false.

The optional type parameter can restrict the lookup to a specific asset type, such as typeof(GameObject).

In the Unity Editor, this method currently returns true unless the key string exists in the manager's _invalidAssetPaths set. That means editor behavior is based on paths that previously failed to load, not a full catalog lookup.

Important behavior:

• Runtime builds perform a locator-based catalog lookup.
• Editor builds use the invalid-path cache.
• LoadPrefabAsync uses this method before attempting to load a prefab.
• Passing a type helps avoid matching an address that exists for a different asset kind.