Scenes and assets

The engine's scene manager loads a scene's declared assets through the runtime's asset coordinator before the scene becomes active.

Configure the catalog

Place assets.json in the Vite project's public/ directory:

{
  "version": 1,
  "assets": [
    {
      "id": "hero-model",
      "kind": "model",
      "path": "models/hero.glb"
    }
  ]
}

Resolve the catalog relative to the document so the same application code can run under the web and desktop platform guides:

const runtime = await Runtime.create("canvas", {
  assets: {
    catalog: new URL("assets.json", document.baseURI)
  }
});

The asset package's game developer guide shows how to create typed references and declare scene.assets.

Load the initial scene

Pass the scene to runtime.load(). Its assets are prepared before the runtime starts:

await runtime.load({
  scene: new GameScene()
});

Additional references can share the same startup boundary:

await runtime.load({
  assets: [sharedUiReference],
  scene: new GameScene()
});

Additional assets load before the scene. See the Runtime.load() reference for the full startup order.

Change scenes

Gameplay code requests later scenes from SceneManager:

const load = runtime.world.sceneManager.loadScene(
  new BattleScene(),
  {
    activation: "manual"
  }
);

SceneManager prepares scene.assets in the background and updates the returned SceneLoad; await load.done waits until it is ready. Call load.allowActivation() when a manually controlled load may replace the active scene. Activation occurs at a frame boundary.

The engine's SceneManager documentation defines the load states, progress events, cancellation, and activation gates.

Start an explicit batch

Code outside a scene transition can load a fixed set of references through the world's coordinator:

const batch = runtime.world.assetCoordinator.loadBatch(
  [iconReference],
  {
    onProgress(progress) {
      console.log(progress.completed, progress.total);
    }
  }
);

await batch.done;

Each batch owns its totals, failures, status, and completion promise. The asset package's AssetLoadBatch reference describes retries and overlapping batches.