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+.
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.pyIf 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
| File | What it does |
|---|---|
sim_bridge/bridge.mjs | The bridge: a Node process that runs bonk.io's physics and talks to Python |
bonk_ia/ambiente.py | The environment: turns the game into an exercise (play, observation, points) |
bonk_ia/features.py | What the AI sees (same as the room's features.ts) |
bonk_ia/recompensas.py | How the AI earns points (rewards) |
bonk_ia/adversarios.py | Scripted opponents |
bonk_ia/politica.py | Exports to policy.json and runs old models (self-play) |
bonk_ia/decisao.py | The axis-by-axis decision (same as the room's) |
treinar.py, avaliar.py, testar_ponte.py | The 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.
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":[]}────────────────────────────────| Command | What it does |
|---|---|
reset | Starts 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} |
step | Presses each player's keys ({"id": keys}) and advances frames frames. Returns the state and the goals scored |
close | Shuts down |
The whole bridge is under 90 lines:
// 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
| Field | Content |
|---|---|
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") |
scores | score by team id (2 red, 3 blue) |
ftu | frames 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:
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.