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:

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:

FieldWhat it is
c.idid of who typed it
c.nomename of who typed it
c.argswords after the command (!kick ana → ['ana'])
c.roomthe 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.

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

ts
.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

ts
// 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

CommandHow
!mute nameKeep 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 Nameroom.setRoomName(c.args.join(' ')) (admin only)
!statusWins and goals of whoever asked: see how to count them in Recording matches
!bbroom.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.