Library

Score and winner (football)

ScoreTracker finds points and the winner of football matches without a browser, and builds the initial state with the game's own code.

bonk.io never tells the host the score or the winner through any packet: GAME_END arrives with no data and clients return to the lobby on their own when a match ends. ScoreTracker solves this without a browser and without taking a slot in the room.

How it works

The game is deterministic: every client simulates the same match from the same initial state and the same inputs. ScoreTracker:

  1. downloads the game's own physics files from bonk.io (on first run) and keeps them in cacheDir. They are not part of the package;
  2. runs the football physics in a worker, isolated from the rest of your process;
  3. feeds the simulation with the match's initial state (GAME_START) and the players' inputs (packet 7, with the frame of each key);
  4. emits an event for every point and when a team reaches the limit.

The result matches the clients exactly: in tests with real matches, positions and score agreed frame by frame.

Usage

ts
import { ScoreTracker } from 'bonktools';

const score = new ScoreTracker(room, { cacheDir: '.cache/bonk-client' });

score.on('score', ({ team, scores }) => {
  room.chat(`point for team ${team}! score: blue ${scores[3]} x ${scores[2]} red`);
});
score.on('match-winner', ({ team }) => {
  console.log('team', team, 'won'); // 2 red · 3 blue
});
score.on('error', (e) => console.error('tracking disabled:', e));

await score.start();
EventPayloadWhen
ready—The simulator has loaded
score{ team, scores, frame }A team scored (scores is indexed by team id)
match-winner{ team, scores, frame }A team reached maxScore (once per match)
errorErrorLoading or simulation failed; tracking stops
OptionDefaultDescription
cacheDir<tmp>/bonktools-clientWhere to keep the downloaded client files
maxScorethe match's gs.wlPoints to win (the room's "rounds")
clientBaseUrlhttps://bonk.io/js/Where the client files come from
tickMs / lagFrames100 / 6Simulation step and lag (200 ms) so inputs can arrive

score.tracking tells whether the current match is being followed. Use it to keep a plan B (for example, asking for the winner in chat) when tracking is not active.

Building the initial state with the game itself

buildInitialState(players) builds the IS blob of a football match with the game's code (createNewState). It does not depend on captured blobs and works for any number of players and any id:

ts
const is = await score.buildInitialState([
  null,                      // index 0: the bot
  { id: 1, team: 3 },        // blue
  { id: 2, team: 2 },        // red
]);
room.startGame(is ? { is } : undefined);

players is an array indexed by player id; only teams 2 (red) and 3 (blue) get a disc. It returns null when the simulator isn't ready: in that case use a captured blob (see Matches and IS blob).

Limitations

  • Football only. Other modes are ignored.
  • The winner is a team, not a player: the game doesn't say who touched the ball last.
  • Memory. The worker loads the whole client (a few hundred MB in the worst case). On very small VMs, evaluate it before turning it on.
  • Network. The packet with the inputs must reach the host; late inputs make the simulation go back to a checkpoint and redo the frames.