Skip to content

IAssetLoader Interface

Unified async asset loading with caching. All asset types (textures, sounds, music, fonts) go through one service. Inject IAssetLoader into your scene or system constructor. No content pipeline, no build step: drag files into your assets folder and load them.

public interface IAssetLoader

Derived
↳ AssetLoader

Remarks

Scoped lifetime: When resolved from a scene's DI scope (the default registration), all loaded assets and manifests are tracked and released automatically when the scope is disposed during scene transitions. Manual Release* and Unload calls are still supported for mid-scene cleanup but are no longer required.

Cancellation: Cancelling the CancellationToken passed to a GetOrLoad*Async call stops the caller's await but does not abort the underlying I/O. Because multiple callers and manifest preloads can share a single in-flight load, the load runs to completion and the result is cached normally. To remove a cached asset, use the corresponding Release* method or Unload(AssetManifest).

Direct-load reference counting: Each GetOrLoad*Async call increments a per-key direct reference count. Call the corresponding Release* method once for each GetOrLoad*Async call to release the asset. The asset is freed only when both the direct count and all manifest references reach zero. If a GetOrLoad*Async call fails (the returned task faults or is cancelled), the reference count is rolled back automatically; only successful loads count.

Methods
GetOrLoadFontAsync(string, int, CancellationToken) Returns a cached font, loading it on first request. The (path, size) pair is the cache key; the same file at different sizes is two separate entries.
GetOrLoadMusicAsync(string, CancellationToken) Returns cached music, loading it on first request.
GetOrLoadSoundAsync(string, CancellationToken) Returns a cached sound effect, loading it on first request.
GetOrLoadTextureAsync(string, TextureScaleMode, CancellationToken) Returns a cached texture, loading it on first request. The (path, scaleMode) pair is the cache key; the same file at different scale modes is two separate entries.
PreloadAsync(AssetManifest, IProgress<AssetLoadProgress>, CancellationToken) Resolves all AssetRef<T> fields declared on manifest in parallel, reporting progress as each asset completes. Call this in OnLoadAsync. Assets are safe to access from OnEnter onwards.
ReleaseFont(string, int) Decrements the direct-load reference count for the given font. Each call to GetOrLoadFontAsync(string, int, CancellationToken) adds one direct reference; call this method once per load to release it. The font is unloaded and its resources are freed only when both the direct count and all manifest references reach zero. Has no effect if the font was only loaded via a manifest.
ReleaseMusic(string) Decrements the direct-load reference count for the given music. Each call to GetOrLoadMusicAsync(string, CancellationToken) adds one direct reference; call this method once per load to release it. The music is unloaded and audio resources are freed only when both the direct count and all manifest references reach zero. Has no effect if the music was only loaded via a manifest.
ReleaseSound(string) Decrements the direct-load reference count for the given sound effect. Each call to GetOrLoadSoundAsync(string, CancellationToken) adds one direct reference; call this method once per load to release it. The sound is unloaded and audio resources are freed only when both the direct count and all manifest references reach zero. Has no effect if the sound was only loaded via a manifest.
ReleaseTexture(string, TextureScaleMode) Decrements the direct-load reference count for the given texture. Each call to GetOrLoadTextureAsync(string, TextureScaleMode, CancellationToken) adds one direct reference; call this method once per load to release it. The texture is unloaded and GPU resources are freed only when both the direct count and all manifest references reach zero. Has no effect if the texture was only loaded via a manifest.
Unload(AssetManifest) Resets all AssetRef<T> fields on manifest and decrements internal reference counts. Assets whose count reaches zero are unloaded from the cache and their GPU/audio resources are freed. Assets still referenced by another tracked manifest or by a direct GetOrLoad*Async call remain cached. In-flight loads for keys that reach zero will be cancelled and their native resources will be disposed automatically.
UnloadAll() Unloads all cached assets and frees GPU/audio resources. Manifests: Any AssetManifest instances previously passed to PreloadAsync(AssetManifest, IProgress<AssetLoadProgress>, CancellationToken) are unloaded and their AssetRef<T> fields are reset. Assets still referenced by other scopes remain cached.