Use the AI

Download the models

Every model trained by BonkTools (football and mbappa; attacker, defender and goalkeeper), the file formats and the test cases to check your implementation.

Downloads

Football

ModelFileTest casesStatus
Attacker / 1v1 (182 million steps, observation v2)football-1x1.policy.jsoncasesThe one that played in the 1v1 rooms and as the attacker in the 2v2 room
Goalkeeper (22.4 million steps, "gk1" observation)football-goleiro.policy.jsoncasesExperimental: in the simulator it concedes fewer goals than our rule-based goalkeeper (8.2% vs 11.5% of plays), but it never went to the room (the rule-based goalkeeper played there)

Mbappa ("Mbappa Clean" map, classic engine)

ModelFileTest casesStatus
Attacker (53.6 million steps, observation v3)mbappa-atacante.policy.jsoncasesThe one that played in the mbappa 1v1 room and as the attacker in the 2v2
Goalkeeper (200 thousand steps, observation v3)mbappa-goleiro.policy.jsoncasesExperimental: a network trained for the 2v2 room's goalkeeper. It stayed in testing and didn't go to the room (there the goalkeeper used the attacker's network + safety rules)
Defender (4.5 million steps, observation v1)mbappa-defensor.policy.jsoncasesExperimental: a specialist trained only on defensive plays, to play as a pair with the attacker. It didn't improve the pair and didn't stay in the room

To get started quickly

FileWhat it is
sala-exemplo.zipReady-made room with the "challenge the AI" mode (MODO=ia) using the football attacker; it also includes the code for the other models (src/ia/)
ia-kit.zipPython training kit to train your own

License: MIT. Use, modify and redistribute; just keep the license notice and don't claim to be affiliated with bonk.io.

Football: attacker / 1v1

The policy.json format

json
{
  "format": "bonktools-rl-policy/1",
  "obsSize": 39,
  "obsVersion": 2,
  "actionTable": [0, 4, 6, 2, 10, 8, 9, 1, 5, 16, 20, 22, 18, 26, 24, 25, 17, 21],
  "activation": "tanh",
  "layers": [
    { "in": 39,  "out": 256, "w": "<base64>", "b": "<base64>" },
    { "in": 256, "out": 256, "w": "<base64>", "b": "<base64>" },
    { "in": 256, "out": 18,  "w": "<base64>", "b": "<base64>" }
  ],
  "timesteps": 182053103,
  "exportedAt": "2026-09-29T16:48:34Z"
}
FieldMeaning
obsSize, obsVersionHow many numbers the network expects (39 = observation version 2)
actionTableThe 18 actions as bonk.io keys: left 1, right 2, up 4, down 8, kick 16
layersThe layers: w are the weights (out × in, row by row) and b the bias, as little-endian float32 encoded in base64
activationtanh in the hidden layers; the last one is linear (it gives 18 "scores", the logits)

For each layer: y = W·x + b, and tanh(y) if it is not the last. The 18 final scores say how much the AI "wants" each action.

Test cases

json
{
  "state":  { "ball": {...}, "discs": [null, {...}, {...}], "ftu": 37 },
  "selfId": 1, "oppId": 2, "mirror": false,
  "obs":    [0.12, -0.4, ...],      // the 39 expected numbers
  "logits": [1.23, -0.5, ...],      // the 18 expected scores
  "prev":   5,                      // previous decision (or null)
  "decided": 3,                     // the action decided axis by axis
  "bits":   2                       // the keys to press (already mirrored if mirror)
}

Build the observation from state, run the network, decide with prev and compare. The observation must match exactly (values are rounded to float32 before the ±2 clamp); the scores, up to the 4th decimal place.

As the attacker in 2v2

The same model played as the attacker in the 2v2 room (the AI next to a goalkeeper). It sees the game as a 1v1: on each decision, the "opponent" is the human closest to the ball. With the ball in its own half, a simple rule held the attacker forward, without fighting the goalkeeper for the ball.

Football: goalkeeper

Same format (bonktools-rl-policy/1) and the same axis-by-axis decision, but with another observation: "gk1" (obsVersion 101, 27 numbers), on the goalkeeper's axis (its own goal is on the left). It includes the goalkeeper, the ball, the two opponents closest to the ball, the teammate (the attacker) and the prediction of where the ball crosses the goal line.

ts
// goleiro-rl.ts
import { teamMirror } from './features.js';

/**
 * "gk1" observation of the RL-trained football GOALKEEPER (obsVersion 101, 27 numbers), exactly as in training.
 * Check against the test cases published with the model. Goalkeeper's canonical axis (its OWN goal is on the left).
 */
export const GK_OBS_VERSION = 101;
export const GK_OBS_SIZE = 27;

const CENTER_X = 33.18;
const CENTER_Y = 22.73;
const LINE_X = 2 * CENTER_X - 64.0 + 1.6; // goalkeeper's line, 1.6 in front of its own goal
const HALF_W = 33.0;
const HALF_H = 22.7;
const PLAYER_MAX_SPEED = 11.7;
const BALL_MAX_SPEED = 20.0;

interface Body { x: number; y: number; xv?: number; yv?: number; kickReady?: boolean }
export interface GkState { ball?: Body | null; discs?: Array<Body | null | undefined> | null }

export function gkObs(state: GkState, gk: number, team: number, humans: number[], bot: number | null): Float64Array {
  const m = teamMirror(team);
  const get = (i: number | null): Body | null => (i !== null && i >= 0 ? state.discs?.[i] ?? null : null);
  const c = (b: Body | null | undefined): [number, number, number, number] =>
    !b ? [CENTER_X, CENTER_Y, 0, 0] : m ? [2 * CENTER_X - b.x, b.y, -(b.xv ?? 0), b.yv ?? 0] : [b.x, b.y, b.xv ?? 0, b.yv ?? 0];
  const me = get(gk);
  const [sx, sy, sxv, syv] = c(me);
  const [bx, by, bxv, byv] = c(state.ball);
  const px = (x: number): number => (x - CENTER_X) / HALF_W;
  const py = (y: number): number => (y - CENTER_Y) / HALF_H;
  const o: number[] = [px(sx), py(sy), sxv / PLAYER_MAX_SPEED, syv / PLAYER_MAX_SPEED, me?.kickReady ? 1 : 0,
    px(bx), py(by), bxv / BALL_MAX_SPEED, byv / BALL_MAX_SPEED,
    (bx - sx) / 10, (by - sy) / 10, Math.min(Math.hypot(bx - sx, by - sy), 40) / 10];
  const hs = humans.map((h) => {
    const [hx, hy, hxv, hyv] = c(get(h));
    return [Math.hypot(hx - bx, hy - by), hx, hy, hxv, hyv] as const;
  });
  hs.sort((a, b) => a[0] - b[0]);
  while (hs.length < 2) hs.push([40, CENTER_X + 20, CENTER_Y, 0, 0]);
  for (const [d, hx, hy, hxv, hyv] of hs.slice(0, 2)) {
    o.push((hx - bx) / 10, (hy - by) / 10, hxv / PLAYER_MAX_SPEED, hyv / PLAYER_MAX_SPEED, Math.min(d, 40) / 10);
  }
  const [tx, ty] = c(get(bot));
  o.push(px(tx), py(ty));
  const cross = predictCross(bx, by, bxv, byv, Math.max(sx, LINE_X));
  if (cross) o.push(1, (cross[0] - CENTER_Y) / HALF_H, Math.min(cross[1], 3) / 3);
  else o.push(0, 0, 1);
  return Float64Array.from(o, (v) => Math.max(-5, Math.min(5, Math.fround(v))));
}

const BALL_Y_MIN = 7.79;
const BALL_Y_MAX = 37.67;

/** Reflects y off the top/bottom walls (the ball bounces). */
function reflectY(y: number): number {
  const lo = BALL_Y_MIN, span = BALL_Y_MAX - BALL_Y_MIN;
  const t = (((y - lo) % (2 * span)) + 2 * span) % (2 * span);
  return lo + (t <= span ? t : 2 * span - t);
}

/** (y, time) at which the ball crosses x = xLine heading for the goal; null if it isn't coming. */
export function predictCross(bx: number, by: number, bxv: number, byv: number, xLine: number): [number, number] | null {
  if (bxv > -1.0 || bx <= xLine) return null;
  const t = (bx - xLine) / -bxv;
  return [reflectY(by + byv * t), t];
}

To play: decide(policy.logits(gkObs(state, goalkeeperId, team, opponentIds, teammateId)), previous) and actionToBits(action, teamMirror(team)), with the same policy.ts as the attacker.

The test cases include state, gk, team, humans (opponents), bot (teammate), obs, logits, prev, decided and bits.

Mbappa: attacker, goalkeeper and defender

Mbappa is a different game: the "Mbappa Clean" map on bonk.io's classic engine (side view, gravity, jumping, a very bouncy ball, cage goals). The recipe is the same (PPO, curriculum, self-play, real physics), but with a different observation and different actions.

The bonktools-rl-mbappa/1 format

Same as football, with two differences:

  • actions instead of actionTable: 18 triples [horizontal, vertical, heavy]. Horizontal: 0 none, 1 ←, 2 →. Vertical: 0 none, 1 ↑ (jump), 2 ↓ (fall fast in the air). Heavy: hold X.
  • Decision by argmax (the highest-scoring action), once every 100 ms.
VersionNumbersWhat it sees
v1 (the defender)26Ball, me and the opponent (position, velocity, on the ground, heavy, alive) and the ball relative to me, to the opponent and to both cages
v238v1 + where the ball will land, ball prediction at 0.3 s and 0.6 s, and a memory (keys from the previous decision, how long ↑ has been held, how long in the air)
v3 (attacker and goalkeeper)43v2 + both X meters, whether the opponent is heavy and whether the ball is on top of one of the cages

Canonical axis: the agent always attacks to the right. In mbappa, blue is the one mirrored (in football it's red).

The code

ts
// mbappa.ts
import { readFileSync } from 'node:fs';

/**
 * The mbappa AI ("Mbappa Clean" map, bonk.io's classic engine) running in plain JS: the exact training observation
 * (v1: 26 numbers; v2: 38, with ball prediction and memory; v3: 43, + both X meters, the opponent's X and the ball
 * on top of one of the cages) and the network (tanh MLP, argmax). Check against the test cases published with each
 * model: a different observation would make the bot play badly without any error.
 */

/** Classic engine state: positions in game units, y grows downward. */
export interface ClassicState {
  ball: { x: number; y: number; xv: number; yv: number };
  /** `heavy` = holding X; `stamina` = X meter (0..1000: spends 10/frame while held, recharges 5). */
  discs: Record<string, { x: number; y: number; xv: number; yv: number; team: number; heavy: boolean; stamina?: number }>;
  scores: (number | null)[];
  ftu: number;
}

export const MBAPPA_POLICY_FORMAT = 'bonktools-rl-mbappa/1';
const TEAM_BLUE = 3;
const MIRROR = 73.0;
const GROUND = 43.1;
const LEFT_LINE = 8.9;
const RIGHT_LINE = 64.1;
const ATTACK: [number, number] = [RIGHT_LINE + 1.5, 40.0];
const DEFEND: [number, number] = [LEFT_LINE - 1.5, 40.0];
const LEFT = 1, RIGHT = 2, UP = 4, DOWN = 8, HEAVY = 16;
const FPS = 30;
const BALL_GROUND = 43.4;
const BALL_GRAVITY = 20.0;
export const MBAPPA_OBS_SIZES: Record<number, number> = { 1: 26, 2: 38, 3: 43 };
const STAMINA_MAX = 1000;
const ROOF_X = 9.5, ROOF_Y = 34.6; // ball on the roof of the left cage (canonical axis)
/** X meter (0..1); without the field, full (as in training). */
const staminaOf = (d: { stamina?: number }): number => Math.min(Math.max((typeof d.stamina === 'number' ? d.stamina : STAMINA_MAX) / STAMINA_MAX, 0), 1);

/** Player memory (v2): keys from the last step, frames holding ↑, frames in the air. */
export interface MbappaMemory {
  keys: number;
  upFrames: number;
  airFrames: number;
}
export const newMemory = (): MbappaMemory => ({ keys: 0, upFrames: 0, airFrames: 0 });
export function updateMemory(m: MbappaMemory, keys: number, frames: number, airborne: boolean): void {
  m.keys = keys;
  m.upFrames = keys & UP ? m.upFrames + frames : 0;
  m.airFrames = airborne ? m.airFrames + frames : 0;
}

type Body = { x: number; y: number; xv: number; yv: number };
const predictBall = (b: Body, t: number): [number, number] => [b.x + b.xv * t, Math.min(b.y + b.yv * t + 0.5 * BALL_GRAVITY * t * t, BALL_GROUND)];
function landingTime(b: Body): number {
  const dy = BALL_GROUND - b.y;
  if (dy <= 0) return 0;
  return (-b.yv + Math.sqrt(b.yv * b.yv + 2 * BALL_GRAVITY * dy)) / BALL_GRAVITY;
}
const canon = (x: number, xv: number, mirrored: boolean): [number, number] => (mirrored ? [MIRROR - x, -xv] : [x, xv]);
export const onGround = (d: { y: number; yv: number }): boolean => d.y >= GROUND - 0.15 && Math.abs(d.yv) < 0.5;
const clip = (v: number): number => Math.max(-5, Math.min(5, v));

/** Observation from `me`'s point of view (team `team`), on the canonical axis (the agent always attacks to the right). */
export function buildObs(state: ClassicState, me: number, opp: number, team: number, mem: MbappaMemory | null = null, version = 1): number[] {
  const mirrored = team === TEAM_BLUE;
  const b = state.ball;
  const [bx, bxv] = canon(b.x, b.xv, mirrored);
  const by = b.y, byv = b.yv;
  const d = state.discs[String(me)];
  const o = state.discs[String(opp)];
  const W = 36.5, H = 10.0, V = 30.0;
  let mx: number, mxv: number, my: number, myv: number, mheavy: number, mground: number;
  if (d) {
    [mx, mxv] = canon(d.x, d.xv, mirrored);
    my = d.y; myv = d.yv; mheavy = d.heavy ? 1 : 0; mground = onGround(d) ? 1 : 0;
  } else {
    mx = bx; mxv = 0; my = GROUND; myv = 0; mheavy = 0; mground = 1;
  }
  let ox: number, oxv: number, oy: number, oyv: number, oground: number, alive: number;
  if (o) {
    [ox, oxv] = canon(o.x, o.xv, mirrored);
    oy = o.y; oyv = o.yv; oground = onGround(o) ? 1 : 0; alive = 1;
  } else {
    ox = MIRROR - mx; oxv = 0; oy = GROUND; oyv = 0; oground = 1; alive = 0;
  }
  const [ax, ay] = ATTACK;
  const [dx, dy] = DEFEND;
  const base = [
    (bx - 36.5) / W, (by - GROUND) / H, bxv / V, byv / V,
    (mx - 36.5) / W, (my - GROUND) / H, mxv / V, myv / V, mheavy, mground,
    (bx - mx) / W, (by - my) / H, (bxv - mxv) / V, (byv - myv) / V,
    (ox - mx) / W, (oy - my) / H, oxv / V, oyv / V, oground, alive,
    (ox - bx) / W, (oy - by) / H,
    (ax - bx) / W, (ay - by) / H,
    (dx - bx) / W, (dy - by) / H,
  ];
  if (version >= 2) {
    const cb = { x: bx, y: by, xv: bxv, yv: byv };
    const tLand = landingTime(cb);
    const [lx] = predictBall(cb, tLand);
    const [p3x, p3y] = predictBall(cb, 0.3);
    const [p6x, p6y] = predictBall(cb, 0.6);
    const m = mem ?? newMemory();
    let left = !!(m.keys & LEFT), right = !!(m.keys & RIGHT);
    if (mirrored) [left, right] = [right, left];
    base.push(
      (lx - mx) / W, Math.min(tLand, 3.0) / 1.5,
      (p3x - mx) / W, (p3y - my) / H, (p6x - mx) / W, (p6y - my) / H,
      (right ? 1 : 0) - (left ? 1 : 0), m.keys & UP ? 1 : 0, m.keys & DOWN ? 1 : 0, m.keys & HEAVY ? 1 : 0,
      Math.min(m.upFrames / FPS, 1.0), Math.min(m.airFrames / FPS, 2.0) / 2.0,
    );
  }
  if (version >= 3) {
    base.push(
      d ? staminaOf(d) : 0, o ? staminaOf(o) : 0, o && o.heavy ? 1 : 0,
      bx < ROOF_X && by < ROOF_Y ? 1 : 0, bx > MIRROR - ROOF_X && by < ROOF_Y ? 1 : 0,
    );
  }
  return base.map((v) => clip(Math.fround(v)));
}

/** Game keys for the move (canonical axis; mirrored: ← and → swap). */
export function keysFor(action: number, actions: readonly (readonly [number, number, boolean | number])[], mirrored: boolean): number {
  const [h, v, heavy] = actions[action]!;
  let k = 0;
  if (h === 1) k |= mirrored ? RIGHT : LEFT;
  else if (h === 2) k |= mirrored ? LEFT : RIGHT;
  if (v === 1) k |= UP;
  else if (v === 2) k |= DOWN;
  if (heavy) k |= HEAVY;
  return k;
}

interface LayerJson {
  in: number;
  out: number;
  w: string;
  b: string;
}
export interface MbappaPolicyJson {
  format: string;
  obsSize: number;
  obsVersion?: number;
  actions: [number, number, boolean][];
  activation: string;
  layers: LayerJson[];
  timesteps?: number;
  exportedAt?: string;
}

function floats(b64: string, n: number): Float32Array {
  const buf = Buffer.from(b64, 'base64');
  if (buf.length !== n * 4) throw new Error(`política inválida: ${buf.length / 4} valores, esperado ${n}`);
  const out = new Float32Array(n);
  for (let i = 0; i < n; i++) out[i] = buf.readFloatLE(i * 4);
  return out;
}

export class MbappaPolicy {
  readonly actions: [number, number, boolean][];
  readonly timesteps: number;
  readonly obsVersion: number;
  private readonly layers: { in: number; out: number; w: Float32Array; b: Float32Array }[];
  private mem = newMemory();
  private lastKeys: number | null = null;

  constructor(json: MbappaPolicyJson) {
    if (json.format !== MBAPPA_POLICY_FORMAT) throw new Error(`formato de política desconhecido: ${String(json.format)}`);
    if (json.activation !== 'tanh') throw new Error(`ativação não suportada: ${json.activation}`);
    this.actions = json.actions;
    this.timesteps = json.timesteps ?? 0;
    const byOrder = Object.entries(MBAPPA_OBS_SIZES).find(([, n]) => n === json.obsSize)?.[0];
    this.obsVersion = json.obsVersion ?? Number(byOrder ?? 1);
    if (MBAPPA_OBS_SIZES[this.obsVersion] !== json.obsSize) throw new Error(`política com ${json.obsSize} entradas: observação desconhecida`);
    this.layers = json.layers.map((l) => ({ in: l.in, out: l.out, w: floats(l.w, l.in * l.out), b: floats(l.b, l.out) }));
    if (this.layers[0]?.in !== json.obsSize) throw new Error('política inválida: a primeira camada não bate com obsSize');
  }

  static load(path: string): MbappaPolicy {
    return new MbappaPolicy(JSON.parse(readFileSync(path, 'utf8')) as MbappaPolicyJson);
  }

  /** The most likely move (argmax of the logits). */
  act(obs: readonly number[]): number {
    let x = Float32Array.from(obs);
    this.layers.forEach((l, li) => {
      const y = new Float32Array(l.out);
      for (let o = 0; o < l.out; o++) {
        let s = l.b[o]!;
        const row = o * l.in;
        for (let i = 0; i < l.in; i++) s += l.w[row + i]! * x[i]!;
        y[o] = li < this.layers.length - 1 ? Math.tanh(s) : s;
      }
      x = y;
    });
    let best = 0;
    for (let i = 1; i < x.length; i++) if (x[i]! > x[best]!) best = i;
    return best;
  }

  /** New match: resets the memory. */
  resetMemory(): void {
    this.mem = newMemory();
    this.lastKeys = null;
  }

  /**
   * The keys ACTUALLY sent this step, when whoever uses the network replaced its move (mbappa 2v2 room: the
   * attacker leaves the play to the goalkeeper): the next step's memory records what the player did, as in training.
   */
  noteKeys(keys: number): void {
    this.lastKeys = keys;
  }

  /**
   * Keys for `me` (team `team`) in this state, called every `frames` frames (100 ms = 3, the training step): the
   * memory records the previous decision's keys and whether the player is in the air now (same order as in training).
   */
  keys(state: ClassicState, me: number, opp: number, team: number, frames = 3): number {
    if (this.obsVersion >= 2 && this.lastKeys !== null) {
      const d = state.discs[String(me)];
      updateMemory(this.mem, this.lastKeys, frames, !!d && !onGround(d));
    }
    const k = keysFor(this.act(buildObs(state, me, opp, team, this.mem, this.obsVersion)), this.actions, team === TEAM_BLUE);
    this.lastKeys = k;
    return k;
  }
}

Usage: policy.keys(state, me, opponent, team) every 3 frames (100 ms) returns the keys to press and handles the memory by itself. Call resetMemory() on every new match.

Mbappa test cases

Each case has state (ClassicState format), me, opp, team, mem ([keys, framesHoldingUp, framesInAir]), obs, action (the argmax) and bits (the keys). Build the observation with buildObs(state, me, opp, team, {keys, upFrames, airFrames}, version), run act() and compare.