Skip to content

t1k:cocos:playable:asset-management

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: assets, AssetsManager, cache, loading, resource

/t1k:cocos:playable:asset-management

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.

AssetsManager (singleton)
├── _cache: Map<string, Asset> ← "path_TypeName" → Asset
└── _loadingPromises: Map<string, Promise> ← deduplication guard

Cache 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/.

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 shorthands
const prefab = await am.loadPrefab("prefab/UI/GameHUD");
const sprite = await am.loadSprite("sprites/logo");
const audio = await am.loadAudio("BGM"); // prepends "audio/" automatically
const tex = await am.loadTexture("textures/bg");
const json = await am.loadJson("data/config");
// Load entire directory
const frames = await am.loadDir("sprites/icons", SpriteFrame);
const all = await am.loadDir("prefab/enemies"); // untyped
// Parallel preload
await 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 queries
am.isCached("prefab/UI/GameHUD", Prefab); // boolean — ALWAYS pass the type
am.getCachedAsset("prefab/UI/GameHUD", Prefab); // Prefab | null
am.getCacheSize(); // number of cached entries
// Release (decrements Cocos ref count)
am.releaseAsset("prefab/UI/GameHUD", Prefab); // ALWAYS pass the type
am.releaseAll(); // full cache flush — use on scene exit

type 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.

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
]);

loadAudio(name) automatically prepends "audio/":

await am.loadAudio("BGM"); // loads resources/audio/BGM.mp3
await am.loadAudio("SFX_Tap");

Do not include "audio/" in the name — it will double-prefix.

loadAsync(type, id) loads from prefab/UI/{id} — kept for backward compatibility. Prefer loadResource() for new code.

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();
}
AssetsManagerresources.load() direct
CacheYes — reuses assetNo — loads again
DedupYes — shared promiseNo — parallel loads
Type safetyTyped genericsTyped generics
Use caseAll runtime loadsAvoid — use AssetsManager
  • 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
  • Passing "audio/BGM" to loadAudio() — 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", but releaseAsset does no prefixing of its own. So releaseAsset("BGM", AudioClip) is a silent no-op; the release call needs the very prefix loadAudio forbids 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 to prefab/UI/ prefix
  • 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.decRef explicitly when releasing dynamic loads.
  • assetManager.loadRemote’s callback can hang the wrapping promise instead of rejecting it — this is Cocos’s built-in cc.assetManager global (not this skill’s own AssetsManager singleton), commonly wrapped in new Promise((resolve, reject) => assetManager.loadRemote(...)) to convert its callback into an awaitable call. A throw inside that callback does not propagate out of loadRemote — it is swallowed, and the promise never settles. Wrap any synchronous work in the callback body (e.g. SpriteFrame.createWithImage(asset)) in its own try/catch that calls reject() explicitly. Separately, the 3.8.7 typings declare the callback’s asset parameter non-nullable even though it IS null on some failure paths where error is also null — under strict: false (the common playable-template tsconfig) nothing warns at compile time, so guard for null explicitly before using the asset.
  • A folder preload does not fetch texture bytes, and an atlas page has no path. preloadDir loads prefab and import JSON only; preload an atlas page by ImageAsset uuid. Detail: references/preload-truth.md.