createRoom()

createRoom() validates your settings, asks the service to admit the room, loads the engine, connects to signaling and resolves once the service has confirmed your process as the host. It rejects if any step fails, and cleans up everything it started.

Node.js

function

createRoom(config: NodeRoomConfig, creation?: CreateRoomOptions): Promise<NodeRoom>

The whole startup must finish within 15 seconds. A missing or malformed API key is reported before any other setting, and before the engine or network are touched.

Failure	Rejects with
Missing or malformed `apiKey`	`TypeError: A valid API key is required.`
`serviceOrigin` is not HTTPS and not your own machine	`TypeError`
An invalid room setting	`Error` naming the setting
The service refuses the room	`RoomAdmissionError`
Startup takes longer than 15 seconds	`DOMException` named `TimeoutError`
`creation.signal` aborts during startup	The signal's `reason`

Parameters

configNodeRoomConfigrequired

Room settings plus your apiKey. See NodeRoomConfig.

creationCreateRoomOptions

Optional. Pass { signal } to cancel startup.

Returns

Promise<NodeRoom>Resolves with the running room once host authority is confirmed.

host.mjs

import {
  createRoom,
  RoomAdmissionError,
} from 'ball2d/node';

try {
  const room = await createRoom({
    apiKey: process.env.BALL2D_API_KEY,
    roomName: 'Evening football',
    noPlayer: true,
    maxPlayers: 12,
    public: true,
  });
  console.log(room.roomLink);
} catch (error) {
  if (error instanceof RoomAdmissionError) {
    console.error(error.status, error.message);
  } else throw error;
}

Cancel a slow start

const room = await createRoom(config, {
  signal: AbortSignal.timeout(10_000),
});

NodeRoomConfig

Import fromball2d/node

interface NodeRoomConfig extends RoomConfig

serviceOriginstring

The Ball2D service to use. Defaults to https://ball2d.com. Must be HTTPS, except http://localhost, http://127.0.0.1 and http://[::1] for local development, and must not include a path, query or credentials. A custom origin must serve a matching Ball2D deployment.

apiKeystringrequired

Your API key: b2d_ followed by 64 lowercase hexadecimal characters. Sent only to serviceOrigin.

NodeRoom

Import fromball2d/node

type NodeRoom = Room & { readonly closed: Promise<void>; }

The value createRoom() resolves with in Node.js: every Room property, method and event, plus closed.

closed

property

room.closed: Promise<void>

readonly

Resolves after the room has closed and your process has released everything the host used: the simulation, peer connections and the service authorization. Await it before exiting so the room is not left waiting for its connection to time out.

It rejects only if closing the peer transport itself fails.

JavaScript

room.close();
await room.closed;
process.exit(0);

Settings

RoomConfig

Import fromball2d

Settings shared by both entries. Unknown keys are rejected, so a typo fails at startup instead of being ignored.

interface RoomConfig

noPlayerboolean

When false (the default), the host takes a player slot as player 0, an admin named by playerName. Set true for a room run entirely by code. sendChat() needs the host player.

playerNamestring

Name of the host player, 1–24 characters. Defaults to Host. Used only when noPlayer is false.

roomNamestring

Name shown in the room list, 1–64 characters. Defaults to Headless Room.

maxPlayersnumber

Players the room admits, including the host player. An integer; values outside 2–30 are clamped. Defaults to 12.

passwordstring

Password players must enter to join, up to 64 characters. Empty or omitted means no password. Change it later with setPassword().

publicboolean

List the room publicly on ball2d.com. Defaults to false: the room is reachable only through its link.

stadiumstring

Stadium **source text** to start with, not a stadium name. Omit it to start with the default arena, then call setDefaultStadium() to pick a bundled stadium by name.

geoRoomGeo

The location advertised in the room list. Omit it and the service uses the location it sees. Advertising only; it does not choose where the room runs.

CreateRoomOptions

Import fromball2dball2d/node

interface CreateRoomOptions

signalAbortSignal

Cancels startup only. Close the returned room explicitly after it opens.

RoomGeo

Not exported by name; reach it through the values that return it.

interface RoomGeo

Public discovery location; never a routing or authorization claim.

codestringrequired

Two-letter country code, such as DE. Case-insensitive.

latnumberrequired

Latitude, from −90 to 90.

lonnumberrequired

Longitude, from −180 to 180.

Browser

createRoom() in the browser

function

createRoom(config?: RoomConfig, options?: CreateRoomOptions): Promise<Room>

The browser entry hosts a room from a page served by a Ball2D deployment. It uses the service, engine and stadium files of the page's own origin, follows the browser admission policy and never takes an API key. See Browser entry.

Parameters

configRoomConfig

Optional room settings. See RoomConfig. An apiKey is rejected as an unknown setting.

optionsCreateRoomOptions

Optional. Pass { signal } to cancel startup.

Returns

Promise<Room>Resolves with the running room.

page.js

import { createRoom } from 'ball2d';

const room = await createRoom({
  roomName: 'Practice',
});