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:
- 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; - runs the football physics in a worker, isolated from the rest of your process;
- feeds the simulation with the match's initial state (
GAME_START) and the players' inputs (packet7, with the frame of each key); - 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
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();| Event | Payload | When |
|---|---|---|
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) |
error | Error | Loading or simulation failed; tracking stops |
| Option | Default | Description |
|---|---|---|
cacheDir | <tmp>/bonktools-client | Where to keep the downloaded client files |
maxScore | the match's gs.wl | Points to win (the room's "rounds") |
clientBaseUrl | https://bonk.io/js/ | Where the client files come from |
tickMs / lagFrames | 100 / 6 | Simulation 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:
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.