Use the AI
How our AI works
An AI that learned to play football on bonk.io by itself, playing millions of matches against itself, with the game's real physics.
The "| IA | BONKTOOLS |" rooms had a player that wasn't a person: an artificial intelligence that learned football from scratch. Nobody programmed "go to the ball and kick". It learned by trial and error, playing millions of plays, and kept getting better on its own.
This tab teaches everything: how it works, how to download the ready-made model, how to put it in your room and how to train your own AI.
The idea in one sentence
The AI looks at the game (39 numbers), picks a key (18 options), and gets points when it does something good (a goal) and loses points when it does something bad (conceding). After millions of attempts, it learns to do what earns the most points.
This is called reinforcement learning (RL). The algorithm we use is PPO, the same one used for Rocket League bots and in many games.
The pieces
┌───────────── TRAINING (Python, on your PC or a server) ───────────────┐
│ │
│ REAL bonk.io physics ◄── Node bridge ──► environment (Gymnasium) │
│ (the lib's PhysicsSimulator) │ observation + points │
│ ▼ │
│ PPO (stable-baselines3) │
│ │ │
└────────────────────────────────────────────────┼──────────────────────┘
▼
policy.json (the AI's "brain", ~430 KB)
│
┌───────────── ROOM (Node, no Python) ───────────┼──────────────────────┐
│ ScoreTracker ─► game state ─► observation ─► network ─► keys ─► room │
└───────────────────────────────────────────────────────────────────────┘- The real physics. The
bonktoolslibrary runs the game's own physics, without a browser and much faster than real time. The AI trains in the same game it will play. - The environment turns the game into an "exercise" the AI understands: a play starts, it decides every 100 ms, the play ends with a goal.
- PPO adjusts the neural network to repeat what earned points.
policy.jsonis the trained network. It runs in plain JavaScript inside the room: no Python and no graphics card needed.
What the AI "sees"
At each decision, the AI receives 39 numbers (the "observation"), all from its own point of view and always as if it attacked to the right (when it plays red, the field is mirrored):
- its own position and velocity, the ball's and the opponent's;
- where the ball is relative to it, to the opponent and to both goals;
- distances to the posts and walls;
- whether the ball is between it and the opponent's goal (it can shoot) or whether it is between the ball and its own goal (it is defending);
- whether it and the opponent can kick right now;
- how long until the kickoff is released.
The details are in What the AI sees and how it earns points.
What the AI "does"
18 actions: 9 directions (including standing still) × kick or not. Every 100 ms it picks one. That is similar to a human player's pace: nobody changes keys 30 times per second.
How it learned
Training is a curriculum, like at school: it starts easy and gets harder.
| Stage | Exercise | Passes when |
|---|---|---|
| 1 | Empty goal: ball anywhere, idle opponent far away | Scores in 80% of plays |
| 2 | Idle opponent in the way | Scores in 70% of plays |
| 3 | Real game: scripted opponent or an older version of itself | Never ends: it keeps improving |
Playing against older versions of itself (self-play) is what makes the AI keep getting better: the opponent levels up together with it.
Numbers of the published model
| Training steps | 182 million (each step = 100 ms of play ≈ 210 days of ball rolling) |
| Network | 39 → 256 → 256 → 18 (tanh), ~430 KB |
| Against the strongest script | 95 goals, 2 conceded in 100 plays (with the room's "eyes") |
| Against humans | Gives beginners a hard time; experienced players find the holes and win most matches (see What we learned) |
| Cost | Zero API spend: CPU only. We trained on free Oracle machines and an ordinary PC |
Where to go next
- Just want to use the AI? Download the model and follow Put the AI in your room.
- Want to train yours? Start at Setting up the training environment.
- Want to understand the mistakes and successes before starting? Read What we learned: it saves weeks.