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).
cd sala-exemplo
npm install
cp .env.example .env # unter Windows: copy .env.example .env
npm run devNach ein paar Sekunden zeigt das Terminal:
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
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 SpieleDie 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:
// 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 .env | Was sie ändert |
|---|---|
SALA_NOME, SALA_SENHA | Name und Passwort des Raums |
SALA_OCULTA=1 | Versteckt den Raum in der öffentlichen Liste (gut zum Testen) |
TAMANHO_TIME | Teamgröße: 1 = 1v1, 2 = 2v2, 3 = 3v3 |
GOLS | Tore zum Sieg |
ADMINS | Namen der Konten, die !kick, !ban... nutzen dürfen |
4. Den Raum starten und am Leben halten: index.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:
BonkSessionstattcreateRoom. Die Session erstellt den Raum selbst neu, wenn er abstürzt (Internet, Neustart des bonk-Servers). Siehe 24/7-Sessions und Wiederverbindung.- Die Logik entsteht bei
room-added. Wird der Raum neu erstellt, ist er ein neuesBonkRoom-Objekt. Deshalb erstellen wir bei jedemroom-addedein neuesMinhaSalaund zerstören das alte; sonst laufen die Timer des alten Raums ewig weiter. - Sauber beenden. Bei
Strg+C(oder wenn der Server den Prozess stoppt) schließtsession.destroy()den Raum ordentlich.
5. Die Teile verbinden: sala.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:
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 Spiel6. 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
- Pick-System: wie
pick.tsgleich große Teams bildet und den Kapitän wählen lässt. - Befehle, Admins und Moderation: bau deine eigenen Befehle.
- Spiele aufzeichnen (Rec): Replays, die sich auf unserer Website öffnen.
- Discord-Integration und Den Raum 24/7 online halten.