SDK reference
Every function, room method, event and type in the ball2d package.
The ball2d package has two entries. Both expose the same room API; they differ in how a room starts and who may start it.
| Entry | Runs in | Starts a room with |
|---|---|---|
ball2d/node | Node.js 24+ (Bun compatible) | An account API key |
ball2d | A page served by a Ball2D deployment | The browser admission policy, never an API key |
npm install ball2dImporting an entry does not create a room, start a process or register a global. Nothing happens until you call createRoom().
Functions
Admit and start a room, then resolve with its controller.
validateStadium()Parse stadium text without opening a room.
readReplay()Decode a recording made by a room.
RoomAdmissionErrorThe error thrown when the service refuses a room.
Conventions
These rules hold across the whole room API.
Commands run in order
Methods that change the room return a Promise and run in the order you call them. Await a command before you read the state it changes:
await room.setPlayerTeam(player.id, 1);
room.getPlayer(player.id)?.team; // 1Up to 256 commands can wait at once. A command beyond that rejects without dropping the ones already accepted. After close(), pending and new commands reject.
Reads are synchronous
Getters such as getPlayerList() and getState(), and the recording controls, return immediately. Values you pass in and objects you get back are copies: changing a returned player object does not change the room.
Events are properties
Assign a function to an event property such as onPlayerJoin. Each event has one handler; assigning again replaces it. Handlers run with the room as this. If a handler throws, the error goes to onError and the room keeps running.
Player IDs are stable
A player keeps the same ID for as long as they are in the room, and a departed player's ID is not reused in that room. IDs are public identifiers, not physics slots or account identities.