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):

TabWhat for
RoomsInstall 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 IntelligenceHow our AI works, download the model, put the AI in your room and train your own AI from scratch.

Where to start

  1. Never written a bonk bot? Start with Installation and first bot: in 5 minutes you have a room answering !ping.
  2. 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.
  3. Want an AI playing? Download the ready-made model and follow Put the AI in your room.

How the pieces fit together

text
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 browser

The 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).