Getting started
Introduction
BonkTools is now an open project: everything we used in our rooms, taught so you can build your own.
BonkTools kept football rooms running 24 hours a day on bonk.io: a pick room with captains, automatic scoring, replays on the website, Discord integration and rooms against an artificial intelligence we trained ourselves.
Now the project has changed focus. Instead of running our own rooms, we are opening up what we learned so anyone can build theirs: the library, a complete example room, the AI model ready to download and a step-by-step guide to training your own AI.
What you will find here
The documentation has two tabs (at the top of the sidebar):
| Tab | What for |
|---|---|
| Rooms | Install the library and build your room: project structure, pick system, commands and admins, match recording, Discord and how to keep it online 24/7. Plus the full library reference. |
| Artificial Intelligence | How our AI works, download the model, put the AI in your room and train your own AI from scratch. |
Where to start
- Never written a bonk bot? Start with Installation and first bot: in 5 minutes you have a room answering
!ping. - Want a complete room? Go straight to Your room, step by step. It has a ready-made project to download, and each following page explains one part of it.
- Want an AI playing? Download the ready-made model and follow Put the AI in your room.
How the pieces fit together
your room (your code: pick, commands, rec, Discord, AI...)
└── bonktools (library, npm)
BonkSession several rooms, reconnection, a single account
└── BonkRoom state, events, teams, lock, anti-AFK
└── BonkTransport connection to the bonk.io server
ScoreTracker / PhysicsSimulator the game's REAL physics, no browserThe library talks to bonk.io directly through the game protocol, without opening a browser: each room is just a lightweight connection. The ScoreTracker runs the game's own physics to know the score, and it is the same physics we use to train the AI.
What you should know first
- Basic TypeScript/JavaScript. The examples are in TypeScript and run on Node.js 20 or newer.
- Basic Python, only if you are going to train your own AI.
- A bonk.io account is recommended for rooms that stay online (as a guest it also works, with limitations).