Skip to content
Ball2DDocs

Room and eventsRoom

Physics

Read and change the discs that make up the match, including the ball and players.

Everything that moves is a disc. During a match, disc indices list the stadium's discs first, with the ball at index 0, then the players on the pitch in roster order. Spectators have no disc. In the lobby there are no discs: reads return null or 0 and changes do nothing.

Positions and sizes use stadium units, with the origin at the centre of the pitch.

CollisionFlags

property
room.CollisionFlags: Readonly<Record<string, number>>
readonly

Bit flags for cMask and cGroup: a disc collides with another when its cMask shares a bit with the other's cGroup.

FlagValue
ball1
red2
blue4
redKO8
blueKO16
wall32
kick64
score128
c0 … c31 << 28 … 1 << 31
all63
JavaScript
const { ball, red, blue, wall } =
  room.CollisionFlags;
// The ball passes through players;
// it collides with walls only.
await room.setDiscProperties(0, {
  cMask: wall,
});

getDiscCount()

method
room.getDiscCount(): number

Returns

numberStadium discs plus players on the pitch; 0 in the lobby.

getDiscProperties()

method
room.getDiscProperties(discIndex: number): HostDiscProperties | null

Parameters

discIndexnumberrequired
Index from 0 (the ball) to getDiscCount() - 1.

Returns

HostDiscProperties | nullThe disc's properties, or null for an invalid index or in the lobby.

JavaScript
const ball = room.getDiscProperties(0);
if (ball)
  console.log(
    'Ball speed',
    Math.hypot(ball.xspeed, ball.yspeed),
  );

setDiscProperties()

method
room.setDiscProperties(discIndex: number, properties: DiscPropertyPatch): Promise<void>

Changes a disc immediately, even while the match is paused. The whole patch is validated first: an invalid field rejects with Invalid disc property: <name> and nothing changes. Ranges:

FieldsRange
x, y, xspeed, yspeed, xgravity, ygravity−8192 to 8192
radius0.5 to 100
bCoeff−1 to 8192
invMass, damping0 to 8192
color0x000000 to 0xffffff, or -1 for transparent
cMask, cGroup32-bit integers

A change that would make collisions too expensive for the room, such as shrinking many discs, rejects with Stadium collision complexity exceeds the room budget. With an invalid index or in the lobby, the call does nothing.

Parameters

discIndexnumberrequired
Index of the disc to change.
propertiesDiscPropertyPatchrequired
Fields to change. Omitted or null fields keep their value; unknown fields are ignored.

Returns

Promise<void>

JavaScript
// Drop the ball back on the centre spot.
await room.setDiscProperties(0, {
  x: 0,
  y: 0,
  xspeed: 0,
  yspeed: 0,
});

getPlayerDiscProperties()

method
room.getPlayerDiscProperties(playerId: number): HostDiscProperties | null

Parameters

playerIdnumberrequired
Player ID.

Returns

HostDiscProperties | nullThe player's disc, or null for spectators, unknown players and in the lobby.

setPlayerDiscProperties()

method
room.setPlayerDiscProperties(playerId: number, properties: DiscPropertyPatch): Promise<void>

Changes a player's disc by player ID, so you don't need to work out its index. Spectators and unknown players are ignored.

Parameters

playerIdnumberrequired
Player ID.
propertiesDiscPropertyPatchrequired
Fields to change, as for setDiscProperties().

Returns

Promise<void>

JavaScript
// A giant goalkeeper for the red team.
await room.setPlayerDiscProperties(keeper.id, {
  radius: 30,
  invMass: 0.2,
});