Skip to content

Library

Create and join rooms

createRoom, joinRoom and every configuration option.

Create a room: `createRoom()`

Returns a BonkRoom that is already connected and active. It only resolves after receiving the room link from the server.

ts

import { createRoom } from 'bonktools';

const room = await createRoom({
  auth: { type: 'registered', username: '...', password: '...' },
  desiredState: {
    roomName: 'My Room',
    password: '',      // empty string = no password
    maxPlayers: 6,
    mode: 'b',
    rounds: 3,
  },
  hidden: false,       // shown in the public list
  timeoutMs: 10_000,   // rejects with RoomCreationTimeoutError if it takes longer
});

console.log(room.shareLink); // https://bonk.io/123456abcde

`createRoom()` options

Field	Type	Default	Description
`auth`	`AuthOptions`	—	Authentication strategy (required)
`desiredState`	`DesiredRoomState`	—	Room configuration (required)
`hidden`	`boolean`	`false`	Hides the room from the public list
`minLevel`	`number`	`0`	Minimum level to join
`maxLevel`	`number`	`999`	Maximum level to join
`timeoutMs`	`number`	`10000`	Maximum time to receive the room link
`protocolVersion`	`number`	`49`	bonk.io protocol version
`reconnectPolicy`	`ReconnectPolicyOptions`	defaults	Reconnection policy (see 24/7 sessions)

`DesiredRoomState`

ts

interface DesiredRoomState {
  roomName: string;
  password: string;       // '' = no password
  maxPlayers: number;     // 1–8
  mode: string | number;  // 'b', 'ar', 'ard', 'sp', 'v', 'f'...
  engine?: string;        // 'b', 'f'...
  rounds: number;
  map?: string | null;    // LZ-String blob of the map
}

Room link

The link has the form https://bonk.io/<6-digit id><bypass>. The library pads the id with leading zeros (ids below 100000 produce links like 006813vnxpi).

Join a room: `joinRoom()`

ts

import { joinRoom } from 'bonktools';

const room = await joinRoom('https://bonk.io/123456abcde', {
  auth: { type: 'registered', username: '...', password: '...' },
  role: 'host',     // 'host' (team 1) or 'spectator' (team 0)
  password: '',     // room password, if any
});

The library parses the URL, resolves the server through autojoin.php and connects. It resolves after receiving the room state, or rejects with RoomJoinTimeoutError.

It also accepts an already resolved address, with no HTTP call:

ts

const room = await joinRoom(
  { server: 'b2seattle1', joinId: '...', bypass: 'abcde' },
  { auth, role: 'spectator' },
);

Errors

ts

import { RoomCreationTimeoutError, RoomJoinTimeoutError } from 'bonktools';

try {
  const room = await createRoom({ auth, desiredState });
} catch (err) {
  if (err instanceof RoomCreationTimeoutError) {
    // the room link did not arrive within timeoutMs
  }
}

See also Errors and troubleshooting.