Tungdv
202 lines
9.1 KiB
Markdown
202 lines
9.1 KiB
Markdown
# 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:
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```csharp
|
|
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.
|