Loading & switching games

A room runs one game at a time, but it doesn't have to be the same game all day. A room can switch games while players stay connected, which is how a room offers a choice of games or updates to a new release without kicking anyone out.

Where a game comes from

The game option of Room.launch, and room.load, accept three kinds of source:

Use a registry release in production. The two local forms are for development and testing: they skip the registry and its access checks, and ignore the game address in their game.json. All three go through the same checks as publishing, so a game that loads locally will also publish. Relative paths resolve from the current directory.

Switching games

room.load(game, options?) replaces the running game with another. The switch is all-or-nothing: the new game is fully prepared before it takes over, so if anything goes wrong, nothing changes for the players.

On success, load resolves to the new game's { reference, path, digest } once it's Ready. On failure it rejects with a DiskoError (game_not_found, game_removed, game_invalid, game_build_failed or game_start_failed), and the previous game keeps running:

try {
  // Players stay connected; the new game starts fresh once it is Ready.
  const loaded = await room.load("gabriel/hockey@2.0.0");
  console.log(`now running ${loaded.reference} (${loaded.digest})`);
} catch (error) {
  if (!(error instanceof DiskoError)) {
    throw error;
  }

  // The previous game keeps running. `game_invalid` and `game_build_failed`
  // carry the problems.
  console.error(`switch failed: ${error.code}`, error.problems ?? []);
}

// A local project directory, built in memory like `disko publish --dry-run`.
await room.load({ path: "../arena" });

// A local archive, for example from `disko publish --dry-run --out`.
await room.load({ path: "./arena-1.4.2.tgz" });

options.players sets the new game's name policy, as the players launch option does for the first game. It does not carry over: without it, the new game uses { name: "display" }. room.game always describes the loaded game, including the permissions it declares.

Access and deprecation

A room can only load releases its owner is allowed to read, and that's checked every time, so taking away access takes effect on the next load.

• A room re-authorizes every registry load, even from its cache. A private release the room's owner cannot read fails with game_not_found, the same as a missing one; a release taken down fails with game_removed.

• Revoking access never stops a room already running that game.

• A deprecated release loads normally; the warning appears in game-loaded and the log:

room.on("game-loaded", ({ reference, deprecation }) => {
  if (deprecation !== null) {
    console.warn(`${reference} is deprecated: ${deprecation.message}`);
  }
});

See Private games & sharing.