Room.launch & options

A room is a Node program built on the @disko-game/room package. The package does the heavy lifting: networking, the game engine and the physics run inside it, in a fast native part that comes prebuilt. Your code just starts a room and reacts to what happens in it.

It needs Node.js 22 or later and ES modules:

npm install @disko-game/room

What launching does

Room.launch(options) does everything needed to open a room, in an order chosen so that nothing half-ready is ever visible to players:

The game loads before the room is listed, so players never find a room that has no game. If any step fails, launch rejects with a DiskoError and cleans up everything it had started.

import { Room } from "@disko-game/room";

// The library reads no environment variables: pass everything as options.
const { ROOM_ID, ROOM_TOKEN } = process.env;

if (!ROOM_ID || !ROOM_TOKEN) {
  throw new Error("Set ROOM_ID and ROOM_TOKEN from the dashboard");
}

const room = await Room.launch({
  // Identity and game
  id: ROOM_ID,
  token: ROOM_TOKEN,
  name: "Friday league",
  game: "gabriel/arena@1.4.2",
  players: { name: "display" },

  // Directory and admission
  description: "Weekly matches. Be kind.",
  public: true,
  guests: false,
  capacity: 16,

  // Network: defaults shown
  listen: "0.0.0.0:4433",
});

console.log(`Room ${room.id} is live at ${room.link}`);

The package never reads environment variables itself. Read your own configuration and pass it as options. The room template's main.js does this with ROOM_ID, ROOM_TOKEN, GAME, and the optional LISTEN and PUBLIC_URL. It targets the production disko services; DISKO_PROFILE=local targets a local stack, and DISKO_API_URL, DISKO_REGISTRY_URL and DISKO_PLAY_URL override single services.

import host from "./room.js";

// Production entry. The room id and hosting token come from the dashboard;
// GAME is a release such as "gabriel/arena@1.0.0".
const { ROOM_ID, ROOM_TOKEN, GAME, LISTEN, PUBLIC_URL } = process.env;

if (!ROOM_ID || !ROOM_TOKEN || !GAME) {
  console.error(
    "Set ROOM_ID and ROOM_TOKEN from the dashboard, and GAME to a release such as gabriel/arena@1.0.0",
  );
  process.exit(2);
}

await host({
  id: ROOM_ID,
  token: ROOM_TOKEN,
  game: GAME,
  ...(LISTEN ? { listen: LISTEN } : {}),
  ...(PUBLIC_URL ? { publicUrl: PUBLIC_URL } : {}),
});

The same host function runs in a test room when you copy it into a game project as server.js.

The options are grouped below. Each table lists the default and the rules a value must follow.

Identity and game

Directory and admission

Network

Operations

Unknown option keys reject with invalid_option, so typos are never ignored.

The Room object

The Room that launch resolves to is your handle on the running room.

Its properties always show the current state: id, url, link (the play.disko.ooo/?room=<id> link you share), state, game, players, and the directory settings name, description, public, guests, location and capacity.

To change settings while the room runs, use setName, setDescription, setPublic, setGuests and setLocation. Directory changes show up for players within about 200 ms.

Every method returns a Promise that settles once the change has been applied, and changes to one room apply in the order you make them. A setter checks its value like the matching launch option and rejects with invalid_option. After close(), every method rejects with closed.

The room also has permissions, actions, options and bans; see Permissions & moderation. Every member is in the @disko-game/room reference.

Errors

Rejections are DiskoError with a code: invalid_option, invalid_state, invalid_message, invalid_event, unauthorized, game_not_found, game_removed, game_invalid, game_build_failed, game_start_failed, registry_unavailable, listen_failed, certificate_invalid and closed. game_invalid and game_build_failed carry problems, each linking to its error page. The code is stable; the message is not. See DiskoErrorCode for what each code means.