bonktools

24/7 room

Reference 24/7 room

The complete football bot, built only with the library. Use it as a base for yours.

The repository includes apps/bonk-room, a football bot that runs 24 hours a day. It was built only with the bonktools library, so it works as a practical example of everything the lib offers: sessions with reconnection, events, teams, lock, anti-AFK and match sync.

What it does

  • Creates and maintains a football room, recreating it if it goes down.
  • Builds the teams automatically, always with the same size.
  • Picks captains and lets the captain choose players by typing the number in chat.
  • Rotates the champion at the end of each match: the winner stays on blue.
  • Handles AFK (!afk and idle detection) and never picks someone who is AFK.
  • Locks the teams: only the bot moves players.
  • Shows the match to late joiners without restarting it.

The complete rules are in Teams, captains and picking.

How to run

bash
git clone https://github.com/brenoluizdev/BonkTools-Core-repo.git
cd BonkTools-Core-repo
pnpm install
pnpm --filter @bonktools/core build

cd apps/bonk-room
cp .env.example .env                        # fill in BONK_USERNAME and BONK_PASSWORD
cp bonk-room.example.json bonk-room.json    # adjust the room name, mode and rounds
pnpm dev

The room link shows up in the log (sala ativa).

Environment variables

VariableDescription
BONK_USERNAME, BONK_PASSWORDThe bonk.io account that hosts the room
BONK_GAMEMODEfootball (default), classic, arrows, death arrows, grapple or vtol
BONK_MAXTEAMSIZEPlayers per team (1 = 1v1, 2 = 2v2...). Basis of every team calculation.
BONK_ROUNDSRounds per match
BONK_INITIAL_STATEFallback IS blob (see Matches and IS blob)
BONK_BLOB_CACHE_PATHPath of the per-map blob cache
NODE_ENVdevelopment (formatted logs) or production (JSON, ideal for PM2)

Room configuration

bonk-room.json:

json
{
  "room": {
    "id": "my-room",
    "name": "My Bonk Room",
    "password": "",
    "maxPlayers": 6,
    "mode": "b",
    "rounds": 3,
    "hidden": true,
    "map": "<map LZ-String blob>"
  },
  "throttle": {
    "maxConcurrentRooms": 1,
    "roomCreationDelayMs": 3000,
    "roomCreationJitterMs": 2000
  },
  "initialStates": { "2": "<IS blob 1v1>", "4": "<IS blob 2v2>" }
}

Code structure

FileRole
src/index.tsLogger, configuration, BonkSession with reconnection
src/example-bot.tsExampleBot: wires room events to the controller
src/pick/PickController.tsTeams, captains, picking, rotation, AFK and commands
src/config.tsValidation (zod) of the configuration and environment reading
examples/antiAfk.tsAnti-AFK in ~10 lines using only the lib

Tests

bash
pnpm --filter bonk-room test

Besides the team-flow and AFK scenarios, there is a fuzz with hundreds of random sequences of joins, leaves, AFK and picks. At every match start it checks that the teams have the same size, never exceed maxTeamSize and have nobody AFK on the field.

Production

Run with NODE_ENV=production for JSON logs and use a process manager (PM2, systemd or a container) to restart the process if it dies. BonkSession already takes care of recreating the room when it goes down; the manager takes care of the process.