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

text
          ┌───────────── 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 │
          └───────────────────────────────────────────────────────────────────────┘
  1. The real physics. The bonktools library 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.
  2. 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.
  3. PPO adjusts the neural network to repeat what earned points.
  4. policy.json is 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.

StageExercisePasses when
1Empty goal: ball anywhere, idle opponent far awayScores in 80% of plays
2Idle opponent in the wayScores in 70% of plays
3Real game: scripted opponent or an older version of itselfNever 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 steps182 million (each step = 100 ms of play ≈ 210 days of ball rolling)
Network39 → 256 → 256 → 18 (tanh), ~430 KB
Against the strongest script95 goals, 2 conceded in 100 plays (with the room's "eyes")
Against humansGives beginners a hard time; experienced players find the holes and win most matches (see What we learned)
CostZero API spend: CPU only. We trained on free Oracle machines and an ordinary PC

Where to go next