Skip to content

Loading Assets

All assets are loaded through IAssetLoader, which caches results and manages lifetimes automatically.

Inject IAssetLoader

public class GameScene : Scene
{
    private readonly IAssetLoader _assets;

    public GameScene(IAssetLoader assets) => _assets = assets;
}

Loading by Type

Textures

// Default (linear filtering — smooth scaling)
var texture = await _assets.GetOrLoadTextureAsync(""assets/images/background.png"", cancellationToken: ct);

// Nearest filtering — sharp pixel art
var pixelArt = await _assets.GetOrLoadTextureAsync(
    ""assets/images/player.png"",
    TextureScaleMode.Nearest,
    ct);

The (path, scaleMode) pair is the cache key — the same file at different scale modes is cached separately.

Sound Effects

var jump = await _assets.GetOrLoadSoundAsync(""assets/audio/jump.wav"", ct);
Audio.PlaySound(jump);

Music

var theme = await _assets.GetOrLoadMusicAsync(""assets/audio/theme.ogg"", ct);
Audio.PlayMusic(theme);

Fonts

var font = await _assets.GetOrLoadFontAsync(""assets/fonts/ui.ttf"", size: 16, ct);
Renderer.SetDefaultFont(font);

The (path, size) pair is the cache key — the same file at different sizes is cached separately.

Releasing Assets

Assets loaded through a scoped IAssetLoader are released automatically when the scene unloads. For manual control:

// Release a specific texture
_assets.ReleaseTexture(""assets/images/player.png"");

// Release with scale mode (if loaded with non-default)
_assets.ReleaseTexture(""assets/images/player.png"", TextureScaleMode.Nearest);

// Release other types
_assets.ReleaseSound(""assets/audio/jump.wav"");
_assets.ReleaseMusic(""assets/audio/theme.ogg"");
_assets.ReleaseFont(""assets/fonts/ui.ttf"", size: 16);

// Release everything
_assets.UnloadAll();

Loading with Progress

Report progress to a loading screen:

protected override async Task OnLoadAsync(CancellationToken ct, IProgress<float>? progress = null)
{
    _texture = await _assets.GetOrLoadTextureAsync(""assets/images/player.png"", cancellationToken: ct);
    progress?.Report(0.33f);

    _sound = await _assets.GetOrLoadSoundAsync(""assets/audio/jump.wav"", ct);
    progress?.Report(0.66f);

    _music = await _assets.GetOrLoadMusicAsync(""assets/audio/theme.ogg"", ct);
    progress?.Report(1.0f);
}

Supported Formats

Extension Type Loader
.png .jpg .jpeg .bmp .tga .gif .webp Texture GetOrLoadTextureAsync
.wav .mp3 .flac .aac Sound GetOrLoadSoundAsync
.ogg Music GetOrLoadMusicAsync
.ttf .otf Font GetOrLoadFontAsync

Next Steps