Eigener Raum

Dein Raum, Schritt für Schritt

Lade das Beispielprojekt herunter, verstehe seinen Aufbau und bring deinen Fußballraum in wenigen Minuten online.

In diesem Pfad baust du einen kompletten Fußballraum, so wie die BonkTools-Räume funktionierten: Pick mit Kapitänen, automatischer Spielstand, Befehle und Admins, Spielaufzeichnung, Discord und sogar ein Modus „Fordere die KI heraus“. Alles nur mit der Bibliothek bonktools.

Jede Seite in diesem Reiter erklärt einen Teil. Diese hier zeigt das Gerüst und wie die Teile miteinander reden.

1. Projekt herunterladen

sala-exemplo.zip herunterladen und entpacken. Du brauchst Node.js 20.18 oder neuer (nodejs.org).

bash
cd sala-exemplo
npm install
cp .env.example .env     # unter Windows: copy .env.example .env
npm run dev

Nach ein paar Sekunden zeigt das Terminal:

text
sala no ar: https://bonk.io/123456abcde

(„sala no ar“ = „Raum ist online“.) Öffne den Link im Browser und tritt bei. Fertig: Du bist in deinem Raum.

2. Aufbau des Projekts

text
sala-exemplo/
├── .env              Geheimnisse und Einstellungen (nicht in git!)
├── src/
│   ├── index.ts      startet den Raum und erstellt ihn neu, wenn er abstürzt
│   ├── config.ts     Name, Passwort, Teamgröße, Tore, Admins
│   ├── sala.ts       verbindet alles: Begrüßung, Chat, Spielstand, Pick, Rec, Discord
│   ├── pick.ts       Pick-System
│   ├── comandos.ts   Chatbefehle und Admins
│   ├── chat.ts       teilt lange Nachrichten (der bonk-Chat schneidet bei ~95 Zeichen ab)
│   ├── rec.ts        zeichnet jedes Spiel in replays/*.bkrp auf
│   ├── discord.ts    Discord-Webhook und -Bot
│   └── ia/           die KI (siehe Reiter „Künstliche Intelligenz“)
└── replays/          die aufgezeichneten Spiele

Die Idee ist einfach: Jede Datei kümmert sich um eine Sache, und sala.ts („Raum“) verbindet sie alle mit den Ereignissen des Raums. Du willst den Pick ändern? Fass nur pick.ts an. Ein neuer Befehl? Nur comandos.ts oder sala.ts.

3. Die Konfiguration

Alles, was sich von Raum zu Raum ändert, steht in config.ts und wird aus der .env gelesen:

ts
// config.ts
// Alles, was sich von Raum zu Raum ändert, steht hier (und die Geheimnisse in der .env).
export const config = {
  sala: {
    nome: process.env.SALA_NOME ?? 'Mein Raum | Pick 2v2',
    senha: process.env.SALA_SENHA ?? '',
    maxJogadores: 8,
    oculta: process.env.SALA_OCULTA === '1',
  },
  /** Spieler pro Team: 1 = 1v1, 2 = 2v2, 3 = 3v3. */
  tamanhoTime: Number(process.env.TAMANHO_TIME ?? 2),
  /** Tore zum Sieg. */
  gols: Number(process.env.GOLS ?? 3),
  /** bonk.io-Namen mit Zugriff auf die Admin-Befehle. */
  admins: (process.env.ADMINS ?? '').split(',').map((n) => n.trim().toLowerCase()).filter(Boolean),
};
Variable in der .envWas sie ändert
SALA_NOME, SALA_SENHAName und Passwort des Raums
SALA_OCULTA=1Versteckt den Raum in der öffentlichen Liste (gut zum Testen)
TAMANHO_TIMETeamgröße: 1 = 1v1, 2 = 2v2, 3 = 3v3
GOLSTore zum Sieg
ADMINSNamen der Konten, die !kick, !ban... nutzen dürfen

4. Den Raum starten und am Leben halten: index.ts

ts
// index.ts
import 'dotenv/config';
import { BonkSession } from 'bonktools';
import { config } from './config.js';
import { SalaIA } from './ia/sala-ia.js';
import { MinhaSala } from './sala.js';

const session = new BonkSession({
  auth: process.env.BONK_USERNAME
    ? { type: 'registered', username: process.env.BONK_USERNAME, password: process.env.BONK_PASSWORD ?? '' }
    : { type: 'guest', guestName: 'MinhaSalaBot' },
});

// Die BonkSession erstellt den Raum selbst neu, wenn er abstürzt. Jeder neue Raum ist ein neues BonkRoom-Objekt:
// deshalb wird die Logik bei 'room-added' aufgebaut (und abgebaut, wenn der Raum verschwindet).
const salas = new Map<string, { destroy(): void }>();
session.on('room-added', (localId) => {
  const entry = session.rooms.get(localId);
  if (!entry) return;
  for (const [id, sala] of salas) if (!session.rooms.has(id)) { sala.destroy(); salas.delete(id); }
  console.log('sala no ar:', entry.room.shareLink);
  // MODO=ia: Raum "Fordere die KI heraus"; sonst der Pick-Raum
  salas.set(localId, process.env.MODO === 'ia' ? new SalaIA(entry.room, process.env.IA_MODELO) : new MinhaSala(entry.room));
});
session.on('room-removed', (localId) => { salas.get(localId)?.destroy(); salas.delete(localId); });
session.on('room-dead-terminal', ({ reason }) => console.error('a sala morreu de vez:', reason));

await session.startFromConfig({
  rooms: [{
    id: 'minha-sala',
    name: config.sala.nome,
    password: config.sala.senha,
    maxPlayers: config.sala.maxJogadores,
    mode: 'f', // football
    rounds: config.gols,
    hidden: config.sala.oculta,
  }],
  // Abstand zwischen Raumerstellungen (wichtig bei mehreren Räumen auf einem Konto)
  throttle: { maxConcurrentRooms: 1, roomCreationDelayMs: 3_000, roomCreationJitterMs: 2_000 },
});

// Strg+C / systemd stop: schließt den Raum sauber.
for (const sig of ['SIGINT', 'SIGTERM'] as const) process.on(sig, () => void session.destroy().then(() => process.exit(0)));

Drei wichtige Ideen:

  1. BonkSession statt createRoom. Die Session erstellt den Raum selbst neu, wenn er abstürzt (Internet, Neustart des bonk-Servers). Siehe 24/7-Sessions und Wiederverbindung.
  2. Die Logik entsteht bei room-added. Wird der Raum neu erstellt, ist er ein neues BonkRoom-Objekt. Deshalb erstellen wir bei jedem room-added ein neues MinhaSala und zerstören das alte; sonst laufen die Timer des alten Raums ewig weiter.
  3. Sauber beenden. Bei Strg+C (oder wenn der Server den Prozess stoppt) schließt session.destroy() den Raum ordentlich.

5. Die Teile verbinden: sala.ts

ts
// sala.ts
import { ScoreTracker, TEAM_BLUE, TEAM_RED, type BonkRoom } from 'bonktools';
import { falar } from './chat.js';
import { Comandos, acharJogador, ehAdmin } from './comandos.js';
import { config } from './config.js';
import { PonteDiscord, avisarWebhook, limpar } from './discord.js';
import { Pick } from './pick.js';
import { Gravador } from './rec.js';

const NOME_TIME: Record<number, string> = { [TEAM_BLUE]: 'azul', [TEAM_RED]: 'vermelho' };

/** Alles, was der Raum macht, auf einem BonkRoom aufgebaut. Ein neues Objekt für jeden (neu) erstellten Raum. */
export class MinhaSala {
  private readonly tracker: ScoreTracker;
  private readonly pick: Pick;
  private readonly gravador: Gravador;
  private readonly comandos = new Comandos();
  private discord: PonteDiscord | null = null;
  private fimTimer: NodeJS.Timeout | null = null;

  constructor(private readonly room: BonkRoom) {
    // Auto-Wertung: simuliert die Spielphysik und meldet Tore und Sieger (nur Fußball).
    this.tracker = new ScoreTracker(room, { cacheDir: '.cache/bonk-client' });
    this.pick = new Pick(room, config.tamanhoTime, async (escalacao) => {
      const is = await this.tracker.buildInitialState(escalacao); // der richtige Anfangszustand für diese Spieler
      if (!is) return false;
      room.startGame({ is });
      return true;
    });
    this.gravador = new Gravador(room, this.tracker);

    this.registrarComandos();
    room.enableAntiAfk(); // 12 s ohne Bewegung oder Chat = AFK

    room.on('player-join', (p) => {
      falar(room, `bem-vindo, ${p.userName}! digite !ajuda para ver os comandos`);
      this.pick.entrou(p.id);
    });
    room.on('player-leave', (p) => this.pick.saiu(p.id));
    room.on('player-afk', (id) => this.pick.parado(id));
    room.on('chat-message', (m) => this.chat(m.id, m.message));

    this.tracker.on('score', ({ team, scores }) => falar(room, `GOL do ${NOME_TIME[team]}! azul ${scores[TEAM_BLUE]} x ${scores[TEAM_RED]} vermelho`));
    this.tracker.on('match-winner', ({ team, scores }) => {
      const texto = `o time ${NOME_TIME[team]} venceu! (${scores[TEAM_BLUE]} x ${scores[TEAM_RED]})`;
      falar(room, texto);
      this.discord?.enviar(`🏆 ${texto}`);
      if (process.env.DISCORD_WEBHOOK) void avisarWebhook(process.env.DISCORD_WEBHOOK, `🏆 ${texto}`);
      // wartet den Siegbildschirm des Spiels ab (4 s) und rotiert
      this.fimTimer = setTimeout(() => this.pick.fimDePartida(team), 4_000);
    });
    this.tracker.on('error', (e) => console.error('[placar] desligado:', e.message));
    void this.tracker.start();

    if (process.env.DISCORD_TOKEN && process.env.DISCORD_CANAL) void this.ligarDiscord(process.env.DISCORD_TOKEN, process.env.DISCORD_CANAL);
  }

  private chat(id: number, texto: string): void {
    if (id === this.room.state.myId) return;
    const nome = this.room.state.players.get(id)?.userName ?? '?';
    this.discord?.enviar(`**${limpar(nome)}**: ${limpar(texto)}`);
    if (this.pick.mensagem(id, texto)) return; // Kapitän wählt
    this.comandos.tratar(this.room, id, texto, (r) => falar(this.room, r));
  }

  private registrarComandos(): void {
    const room = this.room;
    this.comandos
      .registrar('ajuda', { ajuda: 'lista os comandos', executar: (c) => c.responder(this.comandos.ajuda(ehAdmin(room, c.id))) })
      .registrar('afk', { ajuda: 'entra/sai do AFK', executar: (c) => c.responder(this.pick.alternarAfk(c.id)) })
      .registrar('discord', { ajuda: 'link do Discord', executar: (c) => c.responder('entre no nosso Discord: discord.gg/SEU-CONVITE') })
      .registrar('kick', {
        ajuda: 'expulsa: !kick nome', soAdmin: true,
        executar: (c) => {
          const alvo = acharJogador(room, c.args[0] ?? '');
          if (alvo === null) return c.responder('jogador não encontrado');
          room.kickPlayer(alvo);
        },
      })
      .registrar('ban', {
        ajuda: 'bane: !ban nome', soAdmin: true,
        executar: (c) => {
          const alvo = acharJogador(room, c.args[0] ?? '');
          if (alvo === null) return c.responder('jogador não encontrado');
          room.banPlayer(alvo);
        },
      });
  }

  private async ligarDiscord(token: string, canal: string): Promise<void> {
    try {
      this.discord = await PonteDiscord.conectar(token, canal);
      // von Discord in den Raum, mit dem Namen des Verfassers
      this.discord.aoReceber = (autor, texto) => falar(this.room, `[discord] ${autor}: ${texto}`);
      this.discord.enviar(`sala no ar: ${this.room.shareLink}`);
    } catch (err) {
      console.error('[discord] não conectou:', err);
    }
  }

  destroy(): void {
    if (this.fimTimer) clearTimeout(this.fimTimer);
    this.pick.destroy();
    this.gravador.destroy();
    this.tracker.stop(); // beendet die Simulation (Worker) dieses Raums
    this.discord?.destroy();
  }
}

Achte auf das Muster: sala.ts hört auf die Ereignisse (player-join, chat-message, score...) und reicht sie weiter an den, der für das jeweilige Thema zuständig ist. Es weiß nicht, wie der Pick funktioniert; es sagt dem Pick nur, dass jemand beigetreten ist.

Der Ablauf eines Spiels:

text
Spieler tritt bei ─► pick.entrou() ─► bildet die Teams ─► tracker.buildInitialState() ─► room.startGame()
                                                                                          │
ScoreTracker simuliert die Physik ─► 'score' (Tor) ─► Chat                                │
                                  └► 'match-winner' ─► wartet 4 s ─► pick.fimDePartida() ◄┘
                                                                      └► Rotation und nächstes Spiel

6. Allein testen

Für die Grundlagen brauchst du keine Freunde:

  • Öffne den Raum in zwei Browser-Tabs (einem normalen und einem privaten; jeder tritt als ein Spieler bei).
  • Nutze beim Testen SALA_OCULTA=1, damit niemand mitten im Test in deinem Raum landet.
  • Der automatische Spielstand lädt beim ersten Mal die Spieldateien herunter (Ordner .cache/); das erste Spiel kann ein paar Sekunden länger dauern.

Nächste Schritte