t1k:cocos:playable:asset-management
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: assets, AssetsManager, cache, loading, resource
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:asset-managementAssetsManager
Section titled “AssetsManager”Singleton wrapping Cocos resources.load() with a memory cache and in-flight deduplication. Critical for playable ads where the build.sizeBudgetMB size budget demands careful asset reuse. See t1k-cocos-playable-object-pool for how ObjectPoolManager delegates to this class.
Architecture
Section titled “Architecture”AssetsManager (singleton)├── _cache: Map<string, Asset> ← "path_TypeName" → Asset└── _loadingPromises: Map<string, Promise> ← deduplication guardCache key format: "${path}_${type.name}" e.g. "audio/BGM_AudioClip".
The singleton is eager: AssetsManager._instance = new AssetsManager() runs at module scope,
and static get instance() just returns it with no lazy init. So instance is never null and
never throws — but importing the module constructs it, and there is no hook to run before it
exists. Do not write a if (!AssetsManager.instance) guard; it is dead code.
All assets loaded from resources/ folder (Cocos runtime bundle). Paths are relative to assets/resources/.
Key APIs
Section titled “Key APIs”const am = AssetsManager.instance;
// Generic typed load (with cache + dedup)const prefab = await am.loadResource("prefab/UI/GameHUD", Prefab);const sprite = await am.loadResource("sprites/logo", SpriteFrame);const texture = await am.loadResource("textures/bg", Texture2D);const json = await am.loadResource("data/config", JsonAsset);
// Convenience shorthandsconst prefab = await am.loadPrefab("prefab/UI/GameHUD");const sprite = await am.loadSprite("sprites/logo");const audio = await am.loadAudio("BGM"); // prepends "audio/" automaticallyconst tex = await am.loadTexture("textures/bg");const json = await am.loadJson("data/config");
// Load entire directoryconst frames = await am.loadDir("sprites/icons", SpriteFrame);const all = await am.loadDir("prefab/enemies"); // untyped
// Parallel preloadawait am.preloadResources([ { path: "prefab/UI/GameHUD", type: Prefab }, { path: "audio/BGM", type: AudioClip },]);
// Bundle loading (for split bundles)const bundle = await am.loadBundle("game-assets");
// Cache queriesam.isCached("prefab/UI/GameHUD", Prefab); // boolean — ALWAYS pass the typeam.getCachedAsset("prefab/UI/GameHUD", Prefab); // Prefab | nullam.getCacheSize(); // number of cached entries
// Release (decrements Cocos ref count)am.releaseAsset("prefab/UI/GameHUD", Prefab); // ALWAYS pass the typeam.releaseAll(); // full cache flush — use on scene exittype is optional in the signatures of releaseAsset and isCached, and omitting it is a silent
no-op rather than an error. Both build the key as type ? path + '_' + type.name : path, while
loadResource always stored it under path_TypeName — so the bare-path lookup misses every time.
isCached("prefab/UI/GameHUD") returns false for an asset that IS cached, and
releaseAsset("prefab/UI/GameHUD") frees nothing and returns undefined either way. Pass the type.
Deduplication Behaviour
Section titled “Deduplication Behaviour”Concurrent calls with the same path+type share one Promise. The second caller awaits the same network request — no double load. Promise entry is removed from _loadingPromises on resolve or reject.
// Both calls share one load operation:const [a, b] = await Promise.all([ am.loadPrefab("prefab/Coin"), am.loadPrefab("prefab/Coin"), // hits dedup guard, returns same promise]);Audio Path Convention
Section titled “Audio Path Convention”loadAudio(name) automatically prepends "audio/":
await am.loadAudio("BGM"); // loads resources/audio/BGM.mp3await am.loadAudio("SFX_Tap");Do not include "audio/" in the name — it will double-prefix.
Legacy API
Section titled “Legacy API”loadAsync(type, id) loads from prefab/UI/{id} — kept for backward compatibility. Prefer loadResource() for new code.
Workflow: Common Tasks
Section titled “Workflow: Common Tasks”Preload all assets during loading state:
await AssetsManager.instance.preloadResources([ { path: "prefab/UI/WinView", type: Prefab }, { path: "prefab/UI/LoseView", type: Prefab }, { path: "audio/BGM", type: AudioClip }, { path: "audio/SFX_Win", type: AudioClip },]);Load and instantiate a prefab:
const prefab = await AssetsManager.instance.loadPrefab("prefab/UI/Tutorial");const node = instantiate(prefab);node.parent = this.node;Load sprite for dynamic UI:
const frame = await AssetsManager.instance.loadSprite("sprites/avatars/hero");this.avatarSprite.spriteFrame = frame;Release on scene exit to free memory:
onDestroy(): void { AssetsManager.instance.releaseAll();}AssetsManager vs Direct resources.load()
Section titled “AssetsManager vs Direct resources.load()”AssetsManager | resources.load() direct | |
|---|---|---|
| Cache | Yes — reuses asset | No — loads again |
| Dedup | Yes — shared promise | No — parallel loads |
| Type safety | Typed generics | Typed generics |
| Use case | All runtime loads | Avoid — use AssetsManager |
Memory Management for the Size Budget
Section titled “Memory Management for the Size Budget”- Call
releaseAll()on scene/level transitions - Use
getCacheSize()to monitor cached count during development - Prefer
loadDir()for icon sheets — one call, all frames cached - AudioClips are the largest single-asset risk;
releaseAsset()per clip after playback if one-shot
Common Mistakes
Section titled “Common Mistakes”- Passing
"audio/BGM"toloadAudio()— results in path"audio/audio/BGM"(not found) - Releasing an audio clip without the
audio/prefix —loadAudio("BGM")stores it under the key"audio/BGM_AudioClip", butreleaseAssetdoes no prefixing of its own. SoreleaseAsset("BGM", AudioClip)is a silent no-op; the release call needs the very prefixloadAudioforbids you from passing in:releaseAsset("audio/BGM", AudioClip). The asymmetry is easy to miss because neither call complains. - Not awaiting
loadResource()before accessing the asset — returns unresolved Promise - Calling
releaseAll()while assets are still referenced by active nodes — Cocos ref-counts drop to 0 and GC destroys them mid-use - Using
loadAsync()(legacy) for new prefabs — path is hardcoded toprefab/UI/prefix
Hard rules
Section titled “Hard rules”- Bundle remote URLs require crossOrigin headers — silent CORS fails on iOS Safari (in-app webview).
- Atlas packing strategy affects load order — a single 10MB atlas blocks first frame; split sub-atlases per scene.
- Asset GC is not deterministic — call
Asset.decRefexplicitly when releasing dynamic loads. assetManager.loadRemote’s callback can hang the wrapping promise instead of rejecting it — this is Cocos’s built-incc.assetManagerglobal (not this skill’s ownAssetsManagersingleton), commonly wrapped innew Promise((resolve, reject) => assetManager.loadRemote(...))to convert its callback into an awaitable call. Athrowinside that callback does not propagate out ofloadRemote— it is swallowed, and the promise never settles. Wrap any synchronous work in the callback body (e.g.SpriteFrame.createWithImage(asset)) in its owntry/catchthat callsreject()explicitly. Separately, the 3.8.7 typings declare the callback’s asset parameter non-nullable even though it ISnullon some failure paths whereerroris alsonull— understrict: false(the common playable-template tsconfig) nothing warns at compile time, so guard fornullexplicitly before using the asset.- A folder preload does not fetch texture bytes, and an atlas page has no path.
preloadDirloads prefab and import JSON only; preload an atlas page byImageAssetuuid. Detail:references/preload-truth.md.