---
title: "Load game assets asynchronously in C#"
url: https://recursiveai.org/onegame/cookbook/load-game-assets-in-background/
description: "Load a glTF model in the background with onegame, finish it through Assets.Update, await Ready, handle missing files and release the asset handle."
version: "2.0.0"
---

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

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneGame.Host) · [GitHub](https://github.com/recursive-ai-oss/onegame) · [Docs](https://recursiveai.org/onegame/docs/) · [Download example (.zip)](https://recursiveai.org/onegame/cookbook/load-game-assets-in-background/load-game-assets-in-background.zip)

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

```shell
dotnet add package RecursiveAI.OneGame.Host
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/onegame/cookbook/load-game-assets-in-background/load-game-assets-in-background.zip), 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.

```csharp
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.

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

## Related recipes

- [Build a game UI screen](https://recursiveai.org/onegame/cookbook/game-ui-screen/)
- [Declare gameplay input actions](https://recursiveai.org/onegame/cookbook/input-actions/)

## 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](https://recursiveai.org/onegame/docs/assets/) 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](https://recursiveai.org/onegame/docs/assets/#where-files-come-from-and-platform-limits) says path loading is available on desktop; mobile and browser builds need the documented embedded-art route instead.
