BoundAssetBundle
assets/bound-asset-bundle.ts:42An AssetBundle bound to a specific AssetLibrary — the callable form you actually load and read assets through.
Obtain one from AssetLibrary.use. Every method delegates to the underlying library, scoped to the bundle's namespace, but with one crucial difference: BoundAssetBundle.get (and its siblings) accept only the keys the bundle declared. A typo or an undeclared key is a compile error here, where the untyped AssetLibrary.get would have thrown at runtime — and only on the code path that happened to call it.
The recommended pattern is to bind the bundle, load it eagerly at a coarse boundary, then resolve individual assets at registration time (e.g. when registering a prefab) rather than at spawn time, so any residual runtime miss surfaces deterministically at startup instead of when a particular object first appears.
Example
const lvl = game.assets.use(level1);
await lvl.load(); // eager, whole-bundle
const zombieTexture = lvl.get('zombie'); // typed; resolve at registration
// ... later, on level exit:
await lvl.unload();Constructors
constructor(_library: AssetLibrary, _bundle: AssetBundle<E>): BoundAssetBundle<E> Parameters
-
_libraryAssetLibrary -
_bundleAssetBundle<E>
Accessors
namespace: string The namespace this bundle's assets live in — the same one passed to defineAssetBundle.
Methods
get(key: AssetBundleKey<E>): Asset Fetches a loaded asset by one of the bundle's declared keys.
The key argument is typed to the bundle's key union, so an unknown key
fails compilation. At runtime this is exactly
AssetLibrary.get scoped to the bundle's namespace, including its
ErrorCode.ASSET_NOT_FOUND throw if the bundle was never loaded.
Parameters
-
keyAssetBundleKey<E>
Throws
EngineError with code ErrorCode.ASSET_NOT_FOUND when the bundle has not been loaded.
getAs(key: AssetBundleKey<E>, type: AssetConstructor<T>): T Fetches a declared-key asset and asserts its concrete type, returning it
typed — the typed-bundle counterpart to AssetLibrary.getAs, so a
prefab can write bundle.getAs('player', ImageAsset) with neither a
stringly-typed key nor an unchecked cast.
Parameters
-
keyAssetBundleKey<E> -
typeAssetConstructor<T>
Returns
T The stored asset, typed as T.
Throws
EngineError with code ErrorCode.ASSET_NOT_FOUND when the bundle has not been loaded.
EngineError with code
ErrorCode.ASSET_TYPE_MISMATCH when the stored asset is not an
instance of type.
getNullable(key: AssetBundleKey<E>): null | Asset The non-throwing counterpart to BoundAssetBundle.get: returns the
asset for a declared key, or null if the bundle isn't loaded.
Parameters
-
keyAssetBundleKey<E>
has(key: AssetBundleKey<E>): boolean Reports whether a declared key is currently loaded.
Parameters
-
keyAssetBundleKey<E>
Returns
boolean load(options: AssetBundleLoadOptions): Promise<readonly Asset[]> Loads every entry in the bundle into its namespace, in parallel. This is the eager, coarse-grained preload the bundle model is built around — call it once at a loading boundary, then read assets by key.
Idempotent at the entry level: already-loaded entries resolve immediately (see AssetLibrary.load). Resolves once every entry has settled.
Parameters
-
optionsAssetBundleLoadOptions
Throws
The same EngineError codes as AssetLibrary.load, surfaced from whichever entry failed.
unload(): Promise<void> Unloads the entire bundle, freeing every entry's underlying resource. Equivalent to AssetLibrary.unloadNamespace for the bundle's namespace; the canonical "leaving this level" call.
Returns
Promise<void> A promise that resolves once every resource is freed.