unity-addressables
Skill3 starsChanged 3 months agoMITView on GitHub
Use when managing asset loading — Addressables vs Resources vs direct references, async loading patterns, memory management, group strategies, and content update workflows.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- MRCalderon3D/everything-game-dev-codetheir own version, first seen Oct 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- MRCalderon3D/everything-game-dev-code★ 105same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- animation-workflowSkill
- component-designSkill
- data-modelingSkill
- prefab-architectureSkill
- prefab-workflowSkill
- scene-architectureSkill
- scene-authoringSkill
- tool-referenceSkill
- unity-ai-behaviorSkill
- unity-architectSkill
- unity-audioSkill
- unity-ecsSkill
- unity-inputSkill
- unity-networkingSkill
- unity-performanceSkill
- unity-reviewerSkill
- unity-shaders-hdrpSkill
- unity-shaders-urpSkill
- unity-testingSkill
- unity-uiSkill
- unity-vfxSkill
- unity-workflowSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Do NOT activate for in-scene prefab wire-up where the asset is always needed and always loaded — that belongs to hades:prefab-architecture.
- Distinctive: line 24
Before making recommendations, gather project-specific context so advice is calibrated to the actual codebase.
- Very specific: line 27
Call search_by_name("*AddressableAsset*") — finds AddressableAssetSettings, AddressableAssetGroup, and AddressableAssetData files.
- Very specific: line 28
Call graph_query(edgeKind: "references", edgeTargetNamePattern: "AssetReference", edgeTargetKind: "Class") — locates MonoBehaviours with …
- Very specific: line 31
Call get_project_summary() — reveals total asset count, scene count, and build targets.
- Very specific: line 34
Call recall_memory("addressables asset loading memory") — retrieves any documented group strategies, memory budgets, or loading decisions …
- Very specific: line 35
If a new decision is reached, call propose_memory_update to persist the strategy for future reference.
- Distinctive: line 38
No AddressableAssetSettings found → evaluate whether the project warrants adopting Addressables before advising on group design.
- Distinctive: line 76
No content update path after ship.
- Distinctive: line 81
Only reach for Addressables when you genuinely need the extra control.
- Very specific: line 119
Every AsyncOperationHandle that loads an asset must be released.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Unity Addressables
Deep decision framework for asset loading and memory management in Unity. Covers when to adopt Addressables over Resources or direct references, group design, async loading with AsyncOperationHandle, memory lifecycle (load → use → release), ref-counting patterns, and content update workflows via CCD. Untracked handles are the most common source of memory leaks in Addressables projects.
When to Apply
Activate when the conversation involves:
- Deciding whether to use Addressables, Resources, or direct serialized references for an asset
- Loading or instantiating an asset at runtime from a path or label
- Tracking and releasing
AsyncOperationHandleinstances to avoid memory leaks - Designing Addressable groups (by scene, feature, update frequency)
- Preloading assets before a scene or gameplay segment begins
- Streaming downloadable content or supporting remote catalogs
- Diagnosing unexpectedly high memory from loaded-but-unreleased assets
Do NOT activate for in-scene prefab wire-up where the asset is always needed and always loaded — that belongs to hades:prefab-architecture. For questions about how scenes themselves are structured and loaded, see hades:scene-architecture.
Project Context Check
Before making recommendations, gather project-specific context so advice is calibrated to the actual codebase.
- Check if Addressables is already in use:
- Call
search_by_name("*AddressableAsset*")— finds AddressableAssetSettings, AddressableAssetGroup, and AddressableAssetData files. If none exist, the project has not adopted Addressables yet; adjust the scope of advice accordingly. - Call
graph_query(edgeKind: "references", edgeTargetNamePattern: "AssetReference", edgeTargetKind: "Class")— locates MonoBehaviours withAssetReferencefields, indicating Addressables is already wired into gameplay code.
- Call
- Assess project scale:
- Call
get_project_summary()— reveals total asset count, scene count, and build targets. Addressables provide the most value in large projects (many assets) or projects with remote content. Small prototypes rarely justify the setup cost.
- Call
- Check documented asset strategy:
- Call
recall_memory("addressables asset loading memory")— retrieves any documented group strategies, memory budgets, or loading decisions the team has already made. - If a new decision is reached, call
propose_memory_updateto persist the strategy for future reference.
- Call
- Adapt recommendations based on findings:
- No AddressableAssetSettings found → evaluate whether the project warrants adopting Addressables before advising on group design.
- Small project (< 50 assets, single scene) → direct references or Resources may be the right call; skip Addressables.
- Remote content or DLC in scope → Addressables are mandatory; apply CCD group strategy.
AssetReferencealready in use → extend existing patterns; do not introduce a second loading system.
Decision Framework
DECISION: Addressables vs Resources vs Direct Reference
Does the asset need to be loaded dynamically at runtime
(its identity or timing is not known at author time)?
├── No — the asset is always needed and always known
│ └── Direct serialized reference ([SerializeField] MyType _field)
│ ├── Unity loads it with the scene or prefab automatically
│ ├── Zero runtime loading code required
│ └── Use for: character models, level geometry, UI prefabs, audio clips
│ that are always active when their scene is active
│
└── Yes — the asset is loaded on demand
├── Is the project a prototype or the asset set is tiny (< 20 assets)?
│ └── Resources.Load is acceptable for now
│ ├── Simple; no setup required
│ └── MIGRATE to Addressables before ship — Resources cannot be
│ patched post-launch and bypasses build stripping
│
└── Full game / production / remote content
└── Addressables
├── Large asset catalog (hundreds of assets across many scenes)
├── Need async streaming to avoid load-screen spikes
├── DLC / live content updates via remote catalog
├── Fine-grained memory control (load only what's needed now)
└── Platform build size constraints (on-demand download)Why Resources is problematic at scale:
- Everything in a
Resources/folder is included in every build, regardless of whether the player ever loads it. Build size grows unbounded. Resources.Loadis synchronous — it stalls the main thread.- No content update path after ship. Patches that change a Resource asset require a full binary update.
- Unity's build stripping cannot remove assets inside
Resources/.
Why direct references are underused:
- For assets that are always loaded with a scene, a
[SerializeField]reference is zero-cost after the scene loads. No handle tracking, no release calls, no async state machine. - Only reach for Addressables when you genuinely need the extra control.
DECISION: Group Strategy
Addressable groups map to asset bundles. Group design determines what loads together, how much memory is used at once, and which assets can be updated independently.
How is this asset used?
├── Always needed for a specific scene (level art, terrain, NPCs)
│ └── Per-scene group — one group per major scene
│ Loading the scene label loads exactly what that scene needs.
│
├── Shared across multiple scenes (UI atlas, common SFX, shared materials)
│ └── Shared-content group — one group for cross-scene assets
│ Separate from scene groups to avoid duplicating them into every bundle.
│
├── Loaded based on player action (shop items, cosmetics, streamed levels)
│ └── Feature group — one group per feature or content category
│ (e.g., "Cosmetics", "Shop", "AltLevel_Forest")
│
└── Updated post-launch (live event content, DLC)
└── Remote group — hosted on CDD or custom CDN
Mark the group's Build & Load Path as Remote.
Keep stable core content in local groups; only volatile content goes remote.Bundle granularity rules:
- One asset per group = maximum flexibility, maximum bundle overhead. Use only for very large standalone assets (a full cinematic video, a large music track).
- 10–50 related assets per group = good balance. Related assets load together, bundle count stays manageable.
- Hundreds of unrelated assets in one group = too coarse. One changed asset invalidates the entire bundle download.
- Duplicate assets (same asset referenced from two groups without being extracted to a shared group) bloat build size. Run the Analyze tool in the Addressables window before every release build. Hades has no tool for the Analyze tool, or for Addressables groups/entries/addresses at all - see LIMITATIONS.md; this is a human step.
DECISION: Memory Management and Handle Lifecycle
Every AsyncOperationHandle that loads an asset must be released. Forgetting to release is the primary cause of memory leaks in Addressables projects.
Are you loading an asset?
├── Store the handle — you need it to release later.
│ AsyncOperationHandle<T> handle = Addressables.LoadAssetAsync<T>(key);
│
├── Awaiting the load?
│ └── await handle.Task — or use a coroutine with yield return handle
│
├── Done with the asset?
│ └── Addressables.Release(handle) — decrements internal ref count
│ ├── If ref count reaches 0 → asset is unloaded from memory
│ └── If you lost the handle reference → asset leaks until scene unload
│
└── Instantiating a prefab?
└── Use Addressables.InstantiateAsync — NOT Addressables.LoadAssetAsync + Instantiate
├── InstantiateAsync tracks the instance's lifetime
└── Release with Addressables.ReleaseInstance(gameObject) to unload correctlyRef-counting model:
- Each
LoadAssetAsynccall for the same key increments a counter. - Each
Releasedecrements it. The asset unloads only when the count reaches zero. - Loading the same asset from 10 places without releasing 9 of them keeps it in memory permanently.
- Implication: every load site must own its handle and release it when the owning object is destroyed.
Content Update Workflow (CCD)
For live games that need post-launch asset patches:
Hades has no tool for Addressables groups, the Analyze tool, or content builds - these are human steps. Hades indexes Addressables assets only as generic ScriptableObjects (see LIMITATIONS.md).
- Tag assets that may change as Remote group members (remote Build & Load paths).
- On release build, run
Build → New Build → Default Build Script— produces catalog and bundles. - To update: change assets, run
Build → Update a Previous Build, point at the previous content state binary. - Upload the resulting bundles and updated catalog to your CDN (Unity CCD or custom).
- Clients download the new catalog on startup and load updated bundles from remote on demand.
What cannot be patched via content updates:
- C# code changes — those require a binary update.
- Scene structural changes (if the scene itself is not in an Addressable group).
- Changes to assets in Local groups — those are baked into the binary.
Code Examples
Addressable Asset Loading with Handle Tracking and Release
Full component that loads an asset async, uses it, and releases it correctly on destroy.
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
/// <summary>
/// Loads a single Addressable asset by key (address or label), uses it,
/// and releases the handle when the component is destroyed.
///
/// Pattern: one component owns one handle. Never share handles across owners.
/// </summary>
public class AddressableAssetLoader : MonoBehaviour
{
[Tooltip("Addressable address or label string for the asset to load.")]
[SerializeField] private string _assetKey;
// Store the handle as a field — it must outlive the await so we can release it.
private AsyncOperationHandle<GameObject> _handle;
private GameObject _loadedInstance;
private async void Start()
{
await LoadAndSpawnAsync();
}
private async Task LoadAndSpawnAsync()
{
_handle = Addressables.LoadAssetAsync<GameObject>(_assetKey);
// Await the operation. Does not block the main thread.
await _handle.Task;
if (_handle.Status != AsyncOperationStatus.Succeeded)
{
Debug.LogError($"[AddressableAssetLoader] Failed to load '{_assetKey}': {_handle.OperationException}");
// Release even on failure — Addressables tracks failed ops too.
Addressables.Release(_handle);
return;
}
// Instantiate via normal Unity path after the asset is loaded.
// Note: to release correctly, use Addressables.ReleaseInstance instead if you
// used InstantiateAsync (see the InstantiateAsync example below).
_loadedInstance = Instantiate(_handle.Result, transform.position, Quaternion.identity);
}
private void OnDestroy()
{
// Release the asset reference. If this was the last owner, the asset is unloaded.
// NEVER skip this — it is the primary cause of Addressable memory leaks.
if (_handle.IsValid())
Addressables.Release(_handle);
}
}AssetReference Field with Async Instantiation
AssetReference fields let designers assign Addressable assets directly in the Inspector without hardcoding keys.
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
/// <summary>
/// Demonstrates AssetReference — the designer-friendly way to reference an
/// Addressable asset from the Inspector. No address string required.
///
/// Assign the prefab in the Inspector by dragging an Addressable asset onto
/// the _enemyPrefabRef field.
/// </summary>
public class EnemySpawner : MonoBehaviour
{
[Tooltip("Assign an Addressable prefab asset here — drag from the Project window.")]
[SerializeField] private AssetReferenceGameObject _enemyPrefabRef;
[SerializeField] private int _spawnCount = 5;
[SerializeField] private float _spawnRadius = 10f;
// Track instances so we can release them individually.
private readonly System.Collections.Generic.List<GameObject> _spawnedInstances = new();
public async Task SpawnEnemiesAsync()
{
if (!_enemyPrefabRef.RuntimeKeyIsValid())
{
Debug.LogError("[EnemySpawner] AssetReference is not set or invalid.");
return;
}
for (int i = 0; i < _spawnCount; i++)
{
Vector3 spawnPos = transform.position + Random.insideUnitSphere * _spawnRadius;
spawnPos.y = transform.position.y; // keep on the ground plane
// InstantiateAsync loads the asset AND creates a new instance.
// Each call creates one tracked instance. Release with ReleaseInstance.
AsyncOperationHandle<GameObject> handle =
Addressables.InstantiateAsync(_enemyPrefabRef, spawnPos, Quaternion.identity);
await handle.Task;
if (handle.Status == AsyncOperationStatus.Succeeded)
{
_spawnedInstances.Add(handle.Result);
}
else
{
Debug.LogError($"[EnemySpawner] Spawn {i} failed: {handle.OperationException}");
if (handle.IsValid()) Addressables.Release(handle);
}
}
}
/// <summary>
/// Destroy all spawned instances and release their Addressable references.
/// Call this when the combat encounter ends and enemies are no longer needed.
/// </summary>
public void DespawnAll()
{
foreach (GameObject instance in _spawnedInstances)
{
if (instance != null)
// ReleaseInstance destroys the GameObject AND decrements the ref count.
// Do NOT use Destroy() — it skips the ref-count decrement.
Addressables.ReleaseInstance(instance);
}
_spawnedInstances.Clear();
}
private void OnDestroy() => DespawnAll();
}Asset Preloader (Load Group Before Scene Entry)
Load an entire Addressable label before the player enters a scene to avoid in-gameplay streaming hitches.
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using UnityEngine.ResourceManagement.ResourceLocations;
/// <summary>
/// Preloads all assets with a given Addressable label before scene entry.
/// Attach to a loading screen manager. Call PreloadAsync() with a progress
/// callback to drive a loading bar.
///
/// Example: label "Level_Forest" loads all meshes, textures, and audio
/// required by the Forest level before transitioning.
/// </summary>
public class AddressablePreloader : MonoBehaviour
{
// Track all open handles so we can release them when the scene unloads.
private readonly List<AsyncOperationHandle> _activeHandles = new();
/// <summary>
/// Preload all assets for the given label. Reports progress 0→1 via onProgress.
/// Throws if any asset fails to load.
/// </summary>
public async Task PreloadAsync(string label, Action<float> onProgress = null)
{
// Step 1: Resolve the locations (the list of asset keys under this label).
AsyncOperationHandle<IList<IResourceLocation>> locationHandle =
Addressables.LoadResourceLocationsAsync(label);
await locationHandle.Task;
if (locationHandle.Status != AsyncOperationStatus.Succeeded)
{
Addressables.Release(locationHandle);
throw new Exception($"[AddressablePreloader] Failed to load locations for label '{label}'.");
}
IList<IResourceLocation> locations = locationHandle.Result;
int total = locations.Count;
int loaded = 0;
// Step 2: Load each asset, tracking progress.
var loadTasks = new List<Task>(total);
foreach (IResourceLocation location in locations)
{
AsyncOperationHandle<object> assetHandle =
Addressables.LoadAssetAsync<object>(location);
_activeHandles.Add(assetHandle);
Task trackingTask = assetHandle.Task.ContinueWith(_ =>
{
loaded++;
onProgress?.Invoke((float)loaded / total);
}, TaskScheduler.FromCurrentSynchronizationContext());
loadTasks.Add(trackingTask);
}
await Task.WhenAll(loadTasks);
// Release the location handle — we no longer need the location list.
Addressables.Release(locationHandle);
Debug.Log($"[AddressablePreloader] Preloaded {loaded}/{total} assets for label '{label}'.");
}
/// <summary>
/// Release all handles acquired during preload.
/// Call this when the scene that consumed the preloaded assets is unloaded.
/// </summary>
public void ReleaseAll()
{
foreach (AsyncOperationHandle handle in _activeHandles)
{
if (handle.IsValid())
Addressables.Release(handle);
}
_activeHandles.Clear();
}
private void OnDestroy() => ReleaseAll();
}Memory-Safe Loading with Ref Counting
Pattern for shared assets loaded by multiple owners, using manual ref-counting to ensure the asset unloads exactly once when all owners release it.
using System.Collections.Generic;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
/// <summary>
/// Shared Addressable asset cache with explicit ref-counting.
/// Multiple callers can request the same asset; the underlying handle is shared.
/// The asset is released only when all callers have decremented their ref.
///
/// Usage:
/// var tex = await SharedAssetCache.Instance.AcquireAsync<Texture2D>("UI/PlayerIcon");
/// // ...use tex...
/// SharedAssetCache.Instance.Release("UI/PlayerIcon");
/// </summary>
public class SharedAssetCache : MonoBehaviour
{
public static SharedAssetCache Instance { get; private set; }
private readonly Dictionary<string, AsyncOperationHandle> _handles = new();
private readonly Dictionary<string, int> _refCounts = new();
private void Awake()
{
if (Instance != null && Instance != this) { Destroy(gameObject); return; }
Instance = this;
}
/// <summary>
/// Acquire an asset. Increments the ref count. Caller MUST call Release() when done.
/// Returns null if the load fails.
/// </summary>
public async Task<T> AcquireAsync<T>(string key) where T : UnityEngine.Object
{
if (_handles.TryGetValue(key, out AsyncOperationHandle existing))
{
_refCounts[key]++;
// Await in case a previous caller is mid-load.
await existing.Task;
return existing.Result as T;
}
// First request — load it.
AsyncOperationHandle<T> handle = Addressables.LoadAssetAsync<T>(key);
_handles[key] = handle;
_refCounts[key] = 1;
await handle.Task;
if (handle.Status != AsyncOperationStatus.Succeeded)
{
Debug.LogError($"[SharedAssetCache] Failed to load '{key}': {handle.OperationException}");
_handles.Remove(key);
_refCounts.Remove(key);
if (handle.IsValid()) Addressables.Release(handle);
return null;
}
return handle.Result;
}
/// <summary>
/// Decrement the ref count for this key. Releases the handle when count reaches zero.
/// Every AcquireAsync call must have exactly one matching Release call.
/// </summary>
public void Release(string key)
{
if (!_refCounts.TryGetValue(key, out int count))
{
Debug.LogWarning($"[SharedAssetCache] Release called for unknown key '{key}'.");
return;
}
count--;
if (count <= 0)
{
if (_handles.TryGetValue(key, out AsyncOperationHandle handle) && handle.IsValid())
Addressables.Release(handle);
_handles.Remove(key);
_refCounts.Remove(key);
}
else
{
_refCounts[key] = count;
}
}
private void OnDestroy()
{
foreach (KeyValuePair<string, AsyncOperationHandle> kvp in _handles)
{
if (kvp.Value.IsValid())
Addressables.Release(kvp.Value);
}
_handles.Clear();
_refCounts.Clear();
}
}Addressable Scene Loading
Load and unload a scene via Addressables — required when the scene's assets are in Addressable groups.
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using UnityEngine.ResourceManagement.ResourceProviders;
using UnityEngine.SceneManagement;
/// <summary>
/// Loads and unloads scenes via Addressables.
/// Use this instead of SceneManager.LoadSceneAsync when the scene or its
/// dependencies are in Addressable groups (e.g., the scene is a DLC level).
///
/// Scenes loaded via Addressables must be unloaded via Addressables.UnloadSceneAsync —
/// NOT SceneManager.UnloadSceneAsync — or the bundle stays in memory.
/// </summary>
public class AddressableSceneLoader : MonoBehaviour
{
[SerializeField] private AssetReference _sceneReference;
private AsyncOperationHandle<SceneInstance> _loadHandle;
private bool _isLoaded;
/// <summary>
/// Load the scene additively. Reports progress 0→1 during load.
/// The scene is added on top of the current scene (LoadSceneMode.Additive).
/// </summary>
public async Task LoadAsync()
{
if (_isLoaded)
{
Debug.LogWarning("[AddressableSceneLoader] Scene is already loaded.");
return;
}
_loadHandle = Addressables.LoadSceneAsync(
key: _sceneReference,
loadMode: LoadSceneMode.Additive,
activateOnLoad: true
);
while (!_loadHandle.IsDone)
{
Debug.Log($"[AddressableSceneLoader] Loading... {_loadHandle.PercentComplete:P0}");
await Task.Yield();
}
if (_loadHandle.Status != AsyncOperationStatus.Succeeded)
{
Debug.LogError($"[AddressableSceneLoader] Scene load failed: {_loadHandle.OperationException}");
if (_loadHandle.IsValid()) Addressables.Release(_loadHandle);
return;
}
_isLoaded = true;
Debug.Log("[AddressableSceneLoader] Scene loaded successfully.");
}
/// <summary>
/// Unload the scene and release the bundle reference.
/// MUST be called via this method — do not use SceneManager.UnloadSceneAsync.
/// </summary>
public async Task UnloadAsync()
{
if (!_isLoaded || !_loadHandle.IsValid()) return;
AsyncOperationHandle<SceneInstance> unloadHandle =
Addressables.UnloadSceneAsync(_loadHandle, UnloadSceneOptions.UnloadAllEmbeddedSceneObjects);
await unloadHandle.Task;
if (unloadHandle.Status != AsyncOperationStatus.Succeeded)
Debug.LogError($"[AddressableSceneLoader] Scene unload failed: {unloadHandle.OperationException}");
_isLoaded = false;
}
private async void OnDestroy()
{
if (_isLoaded)
await UnloadAsync();
}
}Anti-Examples
Resources.Load Beyond Prototyping
// BAD — Resources.Load in a shipped title.
// Everything in Resources/ is included in the build regardless of use.
// This single call forces Unity to keep the entire Resources directory in the binary.
// Synchronous — stalls the main thread for the duration of the load.
private void SpawnEnemy(string type)
{
GameObject prefab = Resources.Load<GameObject>($"Enemies/{type}"); // blocks main thread
Instantiate(prefab, transform.position, Quaternion.identity);
}
// GOOD — async Addressable load by key; only loads what's needed when it's needed.
[SerializeField] private string _enemyAddressableKey;
private async void SpawnEnemyAsync(string key)
{
var handle = Addressables.InstantiateAsync(key, transform.position, Quaternion.identity);
await handle.Task;
if (handle.Status != AsyncOperationStatus.Succeeded)
Debug.LogError($"Failed to load enemy '{key}'");
// The spawner or a manager tracks this handle for later release.
}Forgetting to Release Handles (Memory Leak)
// BAD — handle stored locally in a method, handle reference lost after method returns.
// The asset stays in memory forever because its ref count never reaches zero.
// On a level with 50 such calls, 50 assets accumulate across play sessions.
private async void LoadIcon(string key)
{
var handle = Addressables.LoadAssetAsync<Sprite>(key);
await handle.Task;
_iconImage.sprite = handle.Result; // display it
// handle goes out of scope here — asset is now permanently retained.
// NO Addressables.Release(handle) call!
}
// GOOD — store the handle as a field; release it in OnDestroy.
private AsyncOperationHandle<Sprite> _iconHandle;
private async void LoadIcon(string key)
{
_iconHandle = Addressables.LoadAssetAsync<Sprite>(key);
await _iconHandle.Task;
if (_iconHandle.Status == AsyncOperationStatus.Succeeded)
_iconImage.sprite = _iconHandle.Result;
}
private void OnDestroy()
{
if (_iconHandle.IsValid())
Addressables.Release(_iconHandle); // ref count decremented; asset may unload
}Synchronous Load of Large Assets
// BAD — WaitForCompletion() forces the async operation to complete synchronously.
// On a large texture or audio clip, this freezes the game for several hundred
// milliseconds on target hardware — a visible hitch.
private void LoadBackground()
{
var handle = Addressables.LoadAssetAsync<Texture2D>("Backgrounds/ForestBG");
Texture2D tex = handle.WaitForCompletion(); // STALLS main thread
_background.texture = tex;
}
// GOOD — keep the load async; show a loading indicator or transition.
private async void LoadBackgroundAsync()
{
_loadingIndicator.SetActive(true);
var handle = Addressables.LoadAssetAsync<Texture2D>("Backgrounds/ForestBG");
await handle.Task;
_loadingIndicator.SetActive(false);
if (handle.Status == AsyncOperationStatus.Succeeded)
_background.texture = handle.Result;
}Addressables for Tiny Always-Needed Assets
// BAD — using Addressables for a tiny sprite that is always visible and
// always needed (e.g., the player's health bar icon).
// Adds async lifecycle management overhead (handle, await, release) where
// a simple [SerializeField] would load it for free with the scene.
[SerializeField] private string _healthIconKey; // Addressable key
private async void Start()
{
var handle = Addressables.LoadAssetAsync<Sprite>(_healthIconKey);
await handle.Task;
_healthIcon.sprite = handle.Result;
// Now must also track and release handle on destroy... for a 2 KB sprite.
}
// GOOD — direct serialized reference. Unity loads it with the HUD prefab automatically.
// No async code, no handle, no release. Exactly right for always-needed small assets.
[SerializeField] private Sprite _healthIconSprite;
private void Start()
{
_healthIcon.sprite = _healthIconSprite; // zero overhead
}Cross-References
- Related skills:
hades:unity-performance(memory budgets, asset memory cost),hades:scene-architecture(scene-based loading strategies, additive scene patterns),hades:data-modeling(data-driven asset key strategies, ScriptableObject catalogs) - Hades MCP tools used in this skill:
search_by_name— confirm whether Addressables is already set up in the projectgraph_query— locate existing AssetReference usage (edgeKind: "references", edgeTargetNamePattern, edgeTargetKind: "Class")get_project_summary— assess project scale to determine if Addressables is warrantedrecall_memory— documented group strategies and memory decisionspropose_memory_update— record new loading and memory decisions for the team
- Unity docs: Addressables Overview, AsyncOperationHandle, AssetReference, Content Update Workflow, Memory Management
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

