bernatmv/unity-addressables-design
gamedev-unity/skills/unity-skills/skills/addressables-design/SKILL.md
Source-anchored design rules for Unity Addressables across two versions — 1.22.3 on Unity 2022 and 2.9.1 on Unity 6 — covering initialization, async operation handles, asset/scene loading, catalog updates, content download, AssetReference, and version migration. Use when writing or reviewing Addressables code, loading assets/scenes asynchronously, setting up hot-update or catalog refresh, or migrating between versions, even if the user just says "可寻址" or "热更". 为 Unity Addressables 提供源码锚定的设计规则(覆盖两个版本,Unity 2022 用 1.22.3、Unity 6 用 2.9.1;含初始化、异步操作句柄、资源/场景加载、目录更新、资源下载、AssetReference、版本迁移);当用户要编写或审查 Addressables 代码、异步加载资源/场景、配置热更新或目录刷新时使用。
development
Updated Jul 18, 2026
$ install --global
skillsauthnpx skillsauth add bernatmv/ai-rules unity-addressables-designInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jul 18, 2026, 4:27 AM14.7s9 files scanned
SKILL.md
- name:
- unity-addressables-design
- description:
- Source-anchored design rules for Unity Addressables across two versions — 1.22.3 on Unity 2022 and 2.9.1 on Unity 6 — covering initialization, async operation handles, asset/scene loading, catalog updates, content download, AssetReference, and version migration. Use when writing or reviewing Addressables code, loading assets/scenes asynchronously, setting up hot-update or catalog refresh, or migrating between versions, even if the user just says "可寻址" or "热更". 为 Unity Addressables 提供源码锚定的设计规则(覆盖两个版本,Unity 2022 用 1.22.3、Unity 6 用 2.9.1;含初始化、异步操作句柄、资源/场景加载、目录更新、资源下载、AssetReference、版本迁移);当用户要编写或审查 Addressables 代码、异步加载资源/场景、配置热更新或目录刷新时使用。
Addressables - Design Rules
Advisory module. Every rule is distilled from Unity Addressables source at two versions:
- 1.22.3 —
[email protected](Unity 2022, min 2019.4) - 2.9.1 —
com.unity.addressables@8460f1c9c927(Unity 6, min 2023.1)
Each rule cites a concrete file/line so the reasoning is auditable and the AI does not improvise against stale memory.
Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).
When to Load This Module
Load before writing or reviewing any of:
Addressables.InitializeAsync()/LoadContentCatalogAsync()bootstrap codeLoadAssetAsync<T>/LoadAssetsAsync<T>/InstantiateAsyncand their handle releaseLoadSceneAsync/UnloadSceneAsync— especially withSceneReleaseMode(2.9.1)CheckForCatalogUpdates→UpdateCatalogs→CleanBundleCachepatch flowGetDownloadSizeAsync/DownloadDependenciesAsync/ClearDependencyCacheAsyncAssetReference/AssetReferenceT<T>field declarations and load/release- Any code that calls
WaitForCompletion()or usesAsyncOperationHandledirectly - Migration from 1.22.3 to 2.9.1 — removed APIs, changed overload signatures
Version Difference Matrix
| Area | 1.22.3 (Unity 2022) | 2.9.1 (Unity 6) |
|------|---------------------|-----------------|
| Non-Async variants (LoadAsset, Instantiate, LoadScene, etc.) | [Obsolete] — compile warning | Removed — compile error |
| IList<object> multi-key overloads | Present | Replaced by IEnumerable |
| SceneReleaseMode enum | Does not exist | New — controls bundle lifetime on scene unload |
| LoadSceneAsync releaseMode param | Absent | SceneReleaseMode.ReleaseSceneWhenSceneUnloaded default |
| LoadAssetsAsync<T>(string key, ...) | Does not exist | New string-key overload |
| UpdateCatalogs(bool autoCleanBundleCache, ...) | Does not exist | New overload |
| LegacyResourcesLocator / LegacyResourcesProvider | Present | Removed |
| DiagnosticEvent / DiagnosticEventCollector | Present | Removed |
| ResourceManagerEventCollector | Present | Removed |
| ResourceManager.RegisterDiagnosticCallback() | [Obsolete] | Removed |
| InitializationOperation property | [Obsolete], returns default | Removed |
| BinaryCatalogInitializationData | Does not exist | New |
| CachedFileProvider | Does not exist | New |
Critical Rule Summary
| # | Rule | Version | Source anchor |
|---|------|---------|---------------|
| 1 | All non-Async variants (LoadAsset, Instantiate, LoadScene, UnloadScene, GetDownloadSize, DownloadDependencies, Initialize, LoadContentCatalog) are [Obsolete] in 1.22.3 and removed in 2.9.1. Always use the *Async form. | Both | Addressables.cs:1.22.3:862-2226, Addressables.cs:2.9.1 (absent) |
| 2 | Every AsyncOperationHandle returned by a Load/Instantiate call MUST be released via Addressables.Release(handle). Forgetting leaks the AssetBundle in memory indefinitely — even after the scene unloads. | Both | AsyncOperationHandle.cs:2.9.1:178-203 |
| 3 | WaitForCompletion() blocks the calling thread synchronously. On WebGL it is unsupported and throws. Never call it on the main thread in production; use await handle.Task or the Completed event instead. | Both | AsyncOperationHandle.cs:2.9.1:178-203 |
| 4 | LoadSceneAsync in 2.9.1 adds SceneReleaseMode releaseMode (default ReleaseSceneWhenSceneUnloaded). If a Single-mode load unloads your additive scene and you need the bundle to stay alive, pass OnlyReleaseSceneOnHandleRelease and release the handle manually. | 2.9.1 | ISceneProvider.cs:2.9.1:14-26, Addressables.cs:2.9.1:1914 |
| 5 | Multi-key overloads changed from IList<object> to IEnumerable in 2.9.1. The old IList<object> overloads no longer exist — pass IEnumerable or string[]. | 2.9.1 | Addressables.cs:2.9.1:1148,1566,1636 |
| 6 | LegacyResourcesLocator and LegacyResourcesProvider were removed in 2.9.1. Do not reference them in code targeting Unity 6. | 2.9.1 | Runtime/ResourceLocators/ (absent in 2.9.1) |
| 7 | ResourceManager.RegisterDiagnosticCallback() was [Obsolete] in 1.22.3 and removed in 2.9.1. Use the Addressables Profiler window instead. | 2.9.1 | ResourceManager.cs:1.22.3:353 (absent in 2.9.1) |
| 8 | Catalog update flow is strictly ordered: CheckForCatalogUpdates → UpdateCatalogs. In 2.9.1, UpdateCatalogs(bool autoCleanBundleCache, ...) can auto-clean stale bundles in one call. | Both | Addressables.cs:2.9.1:2092-2147 |
| 9 | AssetReference.LoadAssetAsync<T>() returns a handle that must be released via assetRef.ReleaseAsset(), NOT Addressables.Release(handle). Mixing the two causes double-release exceptions. | Both | AssetReference.cs:1.22.3:44-46 |
| 10 | InitializationOperation property (1.22.3) is [Obsolete] and returns default. Do not await it. Use await Addressables.InitializeAsync() instead. | 1.22.3 | Addressables.cs:1.22.3:981-982 |
Sub-doc Routing
| Sub-doc | When to read |
|---------|--------------|
| INIT.md | InitializeAsync / LoadContentCatalogAsync / catalog loading order / autoReleaseHandle semantics |
| HANDLES.md | AsyncOperationHandle<T> lifecycle — Completed, WaitForCompletion, Release, IsDone, Status, OperationException, ref-counting |
| LOADING.md | LoadAssetAsync, LoadAssetsAsync (all overloads + version diff), MergeMode, InstantiateAsync, ReleaseInstance |
| SCENE.md | LoadSceneAsync / UnloadSceneAsync / SceneInstance.ActivateAsync / SceneReleaseMode (2.9.1) / activateOnLoad=false pattern |
| UPDATE.md | CheckForCatalogUpdates → UpdateCatalogs flow / autoCleanBundleCache (2.9.1) / CleanBundleCache / ResourceLocatorInfo |
| DOWNLOAD.md | GetDownloadSizeAsync / DownloadDependenciesAsync / ClearDependencyCacheAsync / DownloadStatus struct |
| ASSETREF.md | AssetReference / AssetReferenceT<T> / LoadAssetAsync / ReleaseAsset / OperationHandle property / IsDone guard |
| PITFALLS.md | 30 concrete hallucination pitfalls with version tags + legacy API migration section |
Routing to Other Modules
- Asmdef layout for Addressables consumers → load asmdef
- Async orchestration across multiple Addressables operations → load async
- Architecture-level decisions (Addressables vs YooAsset, group strategy) → load architecture
- Performance review of load/release hot paths → load performance
Version Scope
This document targets two versions:
- 1.22.3 — shipped with Unity 2022 LTS. Contains
[Obsolete]non-Async variants still present for migration. - 2.9.1 — shipped with Unity 6 (2023.1+). All
[Obsolete]APIs removed. NewSceneReleaseMode, binary catalog format,AutoGroupGenerator.
When a rule applies to only one version it is tagged [1.22.3] or [2.9.1]. Untagged rules apply to both.
Migration Notes (hallucination shield)
| Legacy API | Status | Replacement | Source |
|------------|--------|-------------|--------|
| Addressables.Initialize() | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.InitializeAsync() | Addressables.cs:1.22.3:862-864 |
| Addressables.LoadAsset<T>(key) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.LoadAssetAsync<T>(key) | Addressables.cs:1.22.3:992-1007 |
| Addressables.LoadAssets<T>(keys, cb, mode) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.LoadAssetsAsync<T>(keys, cb, mode) | Addressables.cs:1.22.3:1242-1276 |
| Addressables.Instantiate(key, ...) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.InstantiateAsync(key, ...) | Addressables.cs:1.22.3:1892-1972 |
| Addressables.LoadScene(key, ...) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.LoadSceneAsync(key, ...) | Addressables.cs:1.22.3:2090-2106 |
| Addressables.UnloadScene(handle, ...) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.UnloadSceneAsync(handle, ...) | Addressables.cs:1.22.3:2180-2226 |
| Addressables.GetDownloadSize(key) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.GetDownloadSizeAsync(key) | Addressables.cs:1.22.3:1547 |
| Addressables.DownloadDependencies(key) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.DownloadDependenciesAsync(key) | Addressables.cs:1.22.3:1608 |
| Addressables.InitializationOperation | [Obsolete] in 1.22.3, removed in 2.9.1 | await Addressables.InitializeAsync() | Addressables.cs:1.22.3:981-982 |
| LoadResourceLocationsAsync(IList<object> keys, ...) | Present in 1.22.3, removed in 2.9.1 | LoadResourceLocationsAsync(IEnumerable keys, ...) | Addressables.cs:2.9.1:1148 |
| GetDownloadSizeAsync(IList<object> keys) | Present in 1.22.3, removed in 2.9.1 | GetDownloadSizeAsync(IEnumerable keys) | Addressables.cs:2.9.1:1566 |
| DownloadDependenciesAsync(IList<object> keys, mode, ...) | Present in 1.22.3, removed in 2.9.1 | DownloadDependenciesAsync(IEnumerable keys, mode, ...) | Addressables.cs:2.9.1:1636 |
| LegacyResourcesLocator / LegacyResourcesProvider | Present in 1.22.3, removed in 2.9.1 | Use Addressables groups for all assets | Runtime/ResourceLocators/LegacyResourcesLocator.cs:1.22.3 |
| ResourceManager.RegisterDiagnosticCallback(...) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables Profiler window | ResourceManager.cs:1.22.3:353 |
| DiagnosticEvent / DiagnosticEventCollector | Present in 1.22.3, removed in 2.9.1 | Addressables Profiler / custom IProfilerEmitter | Runtime/ResourceManager/Diagnostics/:1.22.3 |
When in doubt, read the cited source — not your memory.
Related Skills
bernatmv/seo-keyword-research
development
VerifiedTrustedCommunity
Keyword research and validation with real search-demand data — never ship keywords from intuition alone. Probes Google Autocomplete per language (free, no account) to prove demand and discover the exact phrasing people type, checks SERPs for winnability, and uses Keyword Planner/Ahrefs/Semrush exports when the user has access. Activates when: choosing or reviewing SEO keywords, meta keywords, page titles, article topics or slugs, landing page copy targeting search, App Store/ASO keyword fields, multilingual keyword sets, 'what should we rank for', 'keyword analysis', or auditing why a page doesn't rank. Also invoke it as a validation pass whenever another skill or task produces a keyword list.
SKILL.mdUpdated Jul 25, 2026
bernatmv/unity-yooasset
development
VerifiedTrustedCommunity
Automate YooAsset hot-update and asset bundles — build bundles, run Editor simulate builds, manage Collector groups, analyze BuildReport, and validate runtime. Use when building or simulating YooAsset bundles, configuring collectors, or validating hot-update assets, even if the user just says "热更" or "打AB包". 自动化 YooAsset 热更新与资源包(构建 bundle、编辑器模拟构建、管理 Collector 分组、分析 BuildReport、运行时校验);当用户要构建或模拟 YooAsset 资源包、配置 collector、或校验热更资源时使用。
SKILL.mdUpdated Jul 18, 2026
bernatmv/unity-yooasset-design
development
VerifiedTrustedCommunity
Source-anchored design rules for YooAsset v2.3.18 — initialization, default-package shortcuts, play modes, asset handles, loading, updates, filesystem, build, and pitfalls. Use when writing or reviewing YooAsset code, initializing packages, loading assets via handles, setting up hot-update/download, or choosing a play mode, even if the user just says "热更" or "资源包". 为 YooAsset v2.3.18 提供源码锚定的设计规则(初始化、默认包快捷方式、运行模式、资源句柄、加载、更新、文件系统、构建、陷阱);当用户要编写或审查 YooAsset 代码、初始化 package、用句柄加载资源、配置热更/下载、或选择运行模式时使用。
SKILL.mdUpdated Jul 18, 2026
bernatmv/unity-yaml-editing
data-ai
VerifiedTrustedCommunity
Last-resort guidance for safely hand-editing Unity serialized YAML (.unity/.prefab/.asset/.meta/ProjectSettings) — reference/fileID repair, GUID safety, and merge-conflict fixes. Use when REST cannot reach the change and YAML must be hand-edited — fixing m_Script GUIDs, broken fileID references, .meta files, or merge conflicts, even if the user just says "场景文件打不开" or "引用丢了". 安全手编 Unity 序列化 YAML(.unity/.prefab/.asset/.meta/ProjectSettings)的最后手段(引用/fileID 修复、GUID 安全、合并冲突修复);当 REST 无法触达、必须手编 YAML 时使用——修复 m_Script GUID、断裂 fileID 引用、.meta 文件或合并冲突。
SKILL.mdUpdated Jul 18, 2026