Physics and discs

Ball2D simulates discs on a 2D pitch at 60 ticks per second. The ball, the players and any moving objects in a stadium are all discs with the same properties: position, speed, radius, mass, damping, bounciness, gravity, color and collision flags.

Find a disc

During a match, disc 0 is the ball. The stadium's other discs follow, then the players on the pitch in roster order. Spectators have no disc, and in the lobby there are none at all.

The simplest reads don't need indices:

const ball = room.getBallPosition(); // { x, y } or null
// null for spectators
const player = room.getPlayerDiscProperties(id);

Change a disc

Patches change only the fields you pass:

// Heavier, slower ball.
await room.setDiscProperties(0, {
  invMass: 0.5,
  damping: 0.98,
});

// Freeze a player for a penalty.
await room.setPlayerDiscProperties(id, {
  xspeed: 0,
  yspeed: 0,
  invMass: 0,
});

The whole patch is validated before anything changes. setDiscProperties() lists every field and its range.

Collisions

Two discs collide when one's cMask shares a bit with the other's cGroup. CollisionFlags names the bits:

const { ball, red, blue, wall } = room.CollisionFlags;

// Ghost mode: the red goalkeeper passes through blue players.
const keeper = room.getPlayerDiscProperties(id);
await room.setPlayerDiscProperties(id, {
  cMask: keeper.cMask & ~blue,
});

Changes and the match

Disc changes apply immediately, even while paused, and every player sees them. They last until the next kickoff reset or stadium load puts discs back in position, so reapply lasting changes in onPositionsReset and onGameStart.