Recursive AI

Load game assets asynchronously in C#

onegame is a free, open-source game engine for .NET from Recursive AI. MIT or Apache-2.0, no editor required.

Load a model off the calling thread on Windows, Linux or macOS. Path loading is not yet available on mobile or the browser.

Terminal
dotnet add package RecursiveAI.OneGame.Host

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OneGame.Host;
 
using var assets = new Assets();
var level = assets.LoadModel(
    "art/level.gltf", background: true);
while (!level.Ready.IsCompleted)
{
    assets.Update();
    await Task.Delay(1);
}
await level.Ready;
Console.WriteLine(level.Value.Nodes.Length);
level.Release();
Text
1

Prints the node count. art/level.gltf is the small scene in the download; its complete contents are below.

Unzip the example, then dotnet run.

The full program

The console example prints a loading state, finishes the load outside a game host, and reads Value only after Ready succeeds. It then deliberately loads a missing model. A failed background load faults Ready with an AssetException; the catch prints its code and the finally releases the handle.

The input is an original, freely reusable scene with one named node and no mesh, buffers or images. Save this as art/level.gltf to run the snippet at the top:

JSON
{"asset":{"version":"2.0"},"scene":0,"scenes":[{"nodes":[0]}],"nodes":[{"name":"LevelRoot"}]}

It exercises model decoding without a GPU or a window. Replace it with your level model when integrating the loading state into a game.

C#
using OneGame.Host;
 
using var assets = new Assets(new FileAssetSource(["."]));
var level = assets.LoadModel("art/level.gltf", background: true);
Console.WriteLine("Loading...");
try
{
    while (!level.Ready.IsCompleted)
    {
        assets.Update();
        await Task.Delay(1);
    }
    await level.Ready;
    Console.WriteLine($"Ready: {level.Value.Nodes.Length} node(s)");
}
catch (AssetException error)
{
    Console.WriteLine($"Failed: {error.Code}");
}
finally
{
    level.Release();
}
Console.WriteLine($"Cached assets: {assets.Items.Count()}");
 
var missing = assets.LoadModel("art/missing.gltf", background: true);
try
{
    while (!missing.Ready.IsCompleted)
    {
        assets.Update();
        await Task.Delay(1);
    }
    await missing.Ready;
}
catch (AssetException error)
{
    Console.WriteLine($"Missing model: {error.Code}");
}
finally
{
    missing.Release();
}

dotnet run prints:

Text
Loading...
Ready: 1 node(s)
Cached assets: 0
Missing model: not_found

Variations

Before level.Release() in the snippet at the top, load the same path again. This prints True: both references share a handle. Release the extra reference too.

C#
var again = assets.LoadModel("art/level.gltf");
Console.WriteLine(ReferenceEquals(level, again));
again.Release();

The short answer

To load game assets asynchronously in C#, call assets.LoadModel(path, background: true), keep drawing a loading state, and wait for Ready before using the model. In a onegame host, completed loads are finished each frame. A console or other custom host must call assets.Update() itself. The example above does that while yielding between updates, then awaits Ready so failures reach the catch block.

The important distinction is between requesting a handle and having a usable model. Returning from LoadModel is not the signal to enter the level. The asset guide documents both the completion task and the per-frame update requirement.

How do I load game assets asynchronously in C#?

Start with a model path relative to a content root. The full program uses an explicit FileAssetSource(["."]), so its root is the working directory. The short snippet uses the default source; in this console example it finds the same art directory. Absolute paths and paths containing .. are not allowed.

The background option moves file reading and decoding onto another thread. Keep the returned handle in your loading-screen state instead of requesting it again every frame. The host finishes completed work during its updates. Once IsReady is true, the success path can use Value; awaiting Ready also lets you handle a failed request explicitly.

Do not put the example’s polling loop inside a game frame callback. That loop is for this standalone console. In a game, return from the callback while loading and let subsequent frames continue to update assets and draw the screen. There is no need to manufacture a percentage: the documented handle exposes readiness, not a byte-progress value.

Why does asynchronous asset loading still block?

Reading Value before the asset is ready waits for it. Moving the load to the background and immediately reading Value therefore defeats the loading screen. Checking readiness must happen before the first use, not after a renderer has already asked for the model.

Likewise, outside the host an unfinished completion task needs the update pump. Awaiting Ready without arranging for updates is not the complete standalone loading pattern. The full program calls Update, yields briefly and repeats until the task completes. Its delay is a polling choice, not a load-duration guarantee.

How do I handle a failed background asset load?

Catch AssetException around the awaited completion. The missing-file case in the program prints not_found, rather than entering the success path and trying to read a model that does not exist. Keep error UI separate from ready UI, and retain the error code if you need to tell the player what failed.

Release each reference when that screen or level no longer needs it. Repeated loads of the same path return the same cached handle and add a reference; reaching zero removes the asset from the cache. The example’s Cached assets: 0 line is the result after its successful handle is released, not an instruction to clear the entire game’s cache.

A .gltf file can have buffers and images beside it; keep those files with the model. The tiny scene above needs none. For deployment, the asset guide says path loading is available on desktop; mobile and browser builds need the documented embedded-art route instead.

All onegame recipes