Train the AI

Setting up the training environment

Install the kit, understand the bridge between Python and bonk.io's real physics, and check everything is wired up.

In this track you train your own football AI. You don't need a graphics card or any paid service: just a computer with Node.js and Python. With 4 parallel simulations, an ordinary PC trains about 750 steps per second (each step = 100 ms of play).

1. Download and install the kit

Download ia-kit.zip and unzip it. You'll need Node.js 20.18+ and Python 3.10+.

bash
cd ia-kit
cd sim_bridge && npm install && cd ..

python -m venv .venv
# Windows:  .venv\Scripts\activate
# Linux/mac: source .venv/bin/activate
pip install -r requirements.txt     # gymnasium, stable-baselines3, torch (CPU), numpy, tensorboard

python testar_ponte.py

If it ends with OK — a ponte com a física funcionou. ("the bridge to the physics works"), everything is ready.

2. What's in the kit

FileWhat it does
sim_bridge/bridge.mjsThe bridge: a Node process that runs bonk.io's physics and talks to Python
bonk_ia/ambiente.pyThe environment: turns the game into an exercise (play, observation, points)
bonk_ia/features.pyWhat the AI sees (same as the room's features.ts)
bonk_ia/recompensas.pyHow the AI earns points (rewards)
bonk_ia/adversarios.pyScripted opponents
bonk_ia/politica.pyExports to policy.json and runs old models (self-play)
bonk_ia/decisao.pyThe axis-by-axis decision (same as the room's)
treinar.py, avaliar.py, testar_ponte.pyThe commands you run: train, evaluate, test the bridge

3. The bridge: Python talking to the physics

Training is in Python (that's where the AI libraries are), but bonk.io's physics is JavaScript. The bridge solves this: Python opens a Node process and the two exchange one line of JSON at a time.

text
Python  ──{"cmd":"reset","players":[null,{"id":1,"team":3},{"id":2,"team":2}],"seed":42}──►  Node
        ◄──{"ok":true,"state":{"ball":{...},"discs":[null,{...},{...}],"ftu":120}}───────────
        ──{"cmd":"step","actions":{"1":18,"2":0},"frames":3}─────────────────────────────►
        ◄──{"ok":true,"state":{...},"frame":3,"goals":[]}────────────────────────────────
CommandWhat it does
resetStarts a play. players is the lineup (index = id). overrides (optional) puts the ball and players wherever you want: {"ball":{"x":..,"y":..,"xv":0,"yv":0},"discs":{"1":{"x":..,"y":..}},"ftu":0}
stepPresses each player's keys ({"id": keys}) and advances frames frames. Returns the state and the goals scored
closeShuts down

The whole bridge is under 90 lines:

js
// bridge.mjs
// Bridge between the physics simulator (Node, `PhysicsSimulator` from `bonktools`) and the
// Gymnasium environment (Python, `bonk_ia/ambiente.py`). Protocol: one JSON request per line on stdin, one
// JSON response per line on stdout. Strictly request/response — the caller waits for the response
// to each line before sending the next one (no pipelining of several in-flight requests).
//
// Commands:
//   {"cmd":"reset","players":[null,{"id":1,"team":3},{"id":2,"team":2}],"seed":123}
//     -> {"ok":true,"state":{...}}
//   {"cmd":"reset",...,"overrides":{"ball":{"x":..,"y":..,"xv":..,"yv":..},"discs":{"1":{...}},"ftu":0}}  (optional)
//   {"cmd":"step","actions":{"1":2,"2":0},"frames":3}   (frames optional, default 1)
//     -> {"ok":true,"state":{...},"frame":N,"goals":[...]}
//   {"cmd":"close"}
//     -> {"ok":true}  (the process exits right after)
// Errors: {"ok":false,"error":"message"}
import readline from 'node:readline';
import { PhysicsSimulator } from 'bonktools';

const sim = new PhysicsSimulator();
let started = false;

// Only the fields the Python environment uses — the full game state is much bigger, and serializing/parsing
// all of it on every step was a big share of the per-step cost.
function compact(state) {
  if (!state) return state;
  const body = (b) => (b ? { x: b.x, y: b.y, xv: b.xv, yv: b.yv } : null);
  return {
    ball: body(state.ball),
    discs: (state.discs || []).map((d) => (d ? { ...body(d), team: d.team, kickReady: d.kickReady } : null)),
    scores: state.scores,
    ftu: state.ftu,
  };
}

function send(obj) {
  process.stdout.write(JSON.stringify(obj) + '\n');
}

const rl = readline.createInterface({ input: process.stdin, terminal: false });

// `readline` fires 'line' for every already-buffered line without waiting for the previous handler
// to finish — if we didn't serialize here, a 'close' arriving right after a slow 'reset'
// would kill the process (process.exit) before the 'reset' response was written. A queue of
// promises guarantees each line is only processed after the previous line's response
// has been sent, honoring the request/response protocol even if stdin arrives all at once.
let queue = Promise.resolve();

rl.on('line', (line) => {
  queue = queue.then(() => handleLine(line));
});

async function handleLine(line) {
  const trimmed = line.trim();
  if (!trimmed) return;

  let req;
  try {
    req = JSON.parse(trimmed);
  } catch {
    send({ ok: false, error: 'linha não é JSON válido' });
    return;
  }

  try {
    if (req.cmd === 'reset') {
      if (!started) {
        await sim.start();
        started = true;
      }
      const state = await sim.reset(req.players, req.seed, undefined, req.overrides);
      send({ ok: true, state: compact(state) });
    } else if (req.cmd === 'step') {
      const result = await sim.step(req.actions, req.frames || 1);
      send({ ok: true, state: compact(result.state), frame: result.frame, goals: result.goals });
    } else if (req.cmd === 'close') {
      sim.close();
      send({ ok: true });
      process.exit(0);
    } else {
      send({ ok: false, error: `comando desconhecido: ${String(req.cmd)}` });
    }
  } catch (err) {
    send({ ok: false, error: err instanceof Error ? err.message : String(err) });
  }
}

The game state

FieldContent
ball{x, y, xv, yv}: ball position and velocity
discs[id]{x, y, xv, yv, team, kickReady}: each player (their physical body is a "disc")
scoresscore by team id (2 red, 3 blue)
ftuframes until the kickoff is released (~120 = 4 s; keys are ignored before that)

The field is about 66 × 45 units: players move in x from 1 to 65.4 and y from 1 to 44.5 (y grows downward), the right goal is at x ≈ 64 and the center at (33.18; 22.73). A player runs up to ~11.7 units/s and a kick leaves at ~24.

4. Faster: several simulations at once

Each environment has its own bridge (a Node process). treinar.py sends the step to all of them before reading the responses, so the simulations run in parallel with a single Python:

bash
python treinar.py --envs 4     # 4 bridges: use 2, 4 or 8 (they divide the PPO batch evenly)

Rule of thumb: one environment per processor core.

Next step

Understand what the AI sees and how it earns points before changing anything, then go to Train and export.