bonktools

Reference

Errors and troubleshooting

Common symptoms, causes and how to fix them.

Players can't move during the match

Symptom: the match starts, but the discs stay still at spawn (pale and nameless).

Common cause: the room is locked (lockTeams()) and the match start was sent with gs.tl = false.

Fix: use version 0.1.4 or later, which sends gs.tl according to the real lock state. If you build TRIGGER_START by hand, fill gs.tl with the value of room.state.teamsLocked.

A player who joins mid-match is stuck in the lobby

Cause: the host sent INFORM_IN_LOBBY and then INFORM_IN_GAME (or the other way round). The client only accepts one initial-data packet.

Fix: since 0.1.2 the library sends only INFORM_IN_GAME when there is an active match started with startGame({ is }). If you start matches some other way, pass the is so the room knows a match is in progress.

The match starts, but players don't appear on the field

Cause: the IS blob is empty or doesn't match the map/number of players.

Fix: capture a blob for each combination (see Matches and IS blob) and use an explicit bal.

rate_limit_tl, rate_limit_cot and others

Cause: too many commands in a short time. The server refuses and warns with a status-message.

Fix: space out the calls. A repeated lockTeams() already sends only once and retries by itself if refused.

Cause: in versions before 0.1.3, room ids with fewer than 6 digits came without leading zeros (for example 6813vnxpi instead of 006813vnxpi).

Fix: update the library; room.shareLink now comes complete.

RoomCreationTimeoutError or RoomJoinTimeoutError

The server didn't answer in time (default: 10 s). Check the network and the credentials and try again. Increase timeoutMs on slow networks.

room-dead with status-room_full

When the bot wasn't in the room yet, it means the room is full (terminal). If it already was, the notice only indicates that another player was refused.

TypeScript errors coming from node_modules/bonktools

If you compile with skipLibCheck: false, the package's index.d.ts may show errors about socket.io-client and eventemitter3. Keep skipLibCheck: true (the tsc --init default); with it, the types work fully.

Anti-AFK flags everyone

Movement comes from input frames over WebRTC. If the players' tabs are in the background, or WebRTC didn't connect, no frame arrives. See the anti-AFK limitations and check that peer-input is being emitted.

Frequently asked questions

Do I need a bonk.io account? To host 24/7 rooms, yes: use a registered account.

What systems does it run on? It is Node.js (20.18.1 or later) with no browser and no native game dependencies. Development and testing were done on Windows.

Can I run several rooms? Yes, with BonkSession. A single account can keep several rooms, respecting the throttle.

Is it official? No. It is an independent project, with no affiliation with bonk.io.

Where do I report a problem? Open an issue in the library repository.