Build your room
Commands, admins and moderation
A chat command router, admins that cannot be impersonated, and kick/ban from the chat.
Chat commands (!afk, !discord, !kick name...) are how players and admins talk to the bot. The comandos.ts ("commands") file in the example project is a small router: you register a command and it handles the rest.
Registering a command
In sala.ts:
this.comandos
.registrar('afk', { ajuda: 'toggles AFK', executar: (c) => c.responder(this.pick.alternarAfk(c.id)) })
.registrar('discord', { ajuda: 'Discord link', executar: (c) => c.responder('join our Discord: discord.gg/YOUR-INVITE') });(registrar = register, ajuda = help text, executar = run.) Each command receives a context c with:
| Field | What it is |
|---|---|
c.id | id of who typed it |
c.nome | name of who typed it |
c.args | words after the command (!kick ana → ['ana']) |
c.room | the room, to call kickPlayer, setTeam... |
c.responder(text) | replies in the chat (splits long text by itself) |
!ajuda ("help") lists the commands the person can use: admins also see the admin ones.
Admins: never trust the name alone
On bonk.io, guests can use any name. If your bot trusts only the name, anyone can join as a guest with the owner's name and become admin. That is why the example's rule is: name on the list and a registered account.
export function ehAdmin(room: BonkRoom, id: number): boolean {
const p = room.state.players.get(id);
return !!p && !p.guest && config.admins.includes(p.userName.toLowerCase());
}Admin commands
A command with soAdmin: true ("admins only") answers "admins only" to everyone else:
.registrar('kick', {
ajuda: 'kicks: !kick name', soAdmin: true,
executar: (c) => {
const alvo = acharJogador(room, c.args[0] ?? '');
if (alvo === null) return c.responder('player not found');
room.kickPlayer(alvo);
},
})acharJogador ("find player") searches by the beginning of the name, case-insensitively: !kick ana finds Ana_123. The bot never finds itself.
The full code
// comandos.ts
import type { BonkRoom } from 'bonktools';
import { config } from './config.js';
export interface Contexto {
room: BonkRoom;
id: number; // who typed it
nome: string;
args: string[];
responder: (texto: string) => void;
}
interface Comando {
ajuda: string;
soAdmin?: boolean;
executar: (ctx: Contexto) => void;
}
/** Command router: "!name arg1 arg2". To create a new command, just register it. */
export class Comandos {
private readonly lista = new Map<string, Comando>();
registrar(nome: string, comando: Comando): this {
this.lista.set(nome.toLowerCase(), comando);
return this;
}
/** Returns true if the message was a command (and has been handled). */
tratar(room: BonkRoom, id: number, mensagem: string, responder: (t: string) => void): boolean {
if (!mensagem.startsWith('!')) return false;
const [nomeCmd = '', ...args] = mensagem.slice(1).trim().split(/\s+/);
const cmd = this.lista.get(nomeCmd.toLowerCase());
if (!cmd) return false;
const nome = room.state.players.get(id)?.userName ?? '';
if (cmd.soAdmin && !ehAdmin(room, id)) {
responder('esse comando é só para admins');
return true;
}
cmd.executar({ room, id, nome, args, responder });
return true;
}
ajuda(admin: boolean): string {
return [...this.lista].filter(([, c]) => admin || !c.soAdmin).map(([n]) => `!${n}`).join(' ');
}
}
/**
* Admin = name on the list AND a registered account. Guests can use ANY name,
* so never trust a guest's name alone.
*/
export function ehAdmin(room: BonkRoom, id: number): boolean {
const p = room.state.players.get(id);
return !!p && !p.guest && config.admins.includes(p.userName.toLowerCase());
}
/** Finds a player by the start of their name ("!kick ana" finds "Ana_123"). */
export function acharJogador(room: BonkRoom, busca: string): number | null {
const b = busca.toLowerCase();
for (const [id, p] of room.state.players) if (id !== room.state.myId && p.userName.toLowerCase().startsWith(b)) return id;
return null;
}Command ideas
| Command | How |
|---|---|
!mute name | Keep the id in a Set and, in chat() in sala.ts, ignore (and don't forward to Discord) messages from anyone in it |
!placar (score) | Keep the last scores from the score event and reply with it |
!senha new (password) | room.setRoomPassword(c.args[0] ?? '') (admin only) |
!nome New Name | room.setRoomName(c.args.join(' ')) (admin only) |
!status | Wins and goals of whoever asked: see how to count them in Recording matches |
!bb | room.kickPlayer(c.id): the player leaves by themselves |
Anti-flood
bonk.io chat has a messages-per-second limit, and the server may block your room if it talks too much. A few rules that avoid headaches:
- Group messages. Instead of a "welcome" for each person who joins, put the names that joined in the last 3 seconds in a single line.
- One line per event. The pick announcement fits in two lines; a goal, in one.
- Per-player limit. If someone sends 10 commands in 5 seconds, ignore the next ones for a while.