Partidas, IS blob y espectadores

Cómo iniciar partidas con el estado inicial correcto y sincronizar a quienes entran tarde.

Iniciar una partida en bonk.io requiere más que pulsar "iniciar": el host envía el estado inicial de la física (el IS blob) y la configuración del juego. La biblioteca se ocupa del envío, pero tú debes aportar el blob correcto.

Iniciar y detener

room.startGame({ is: isBlob, gs: { bal: { 0: 0, 5: 1, 7: 2 } } });
room.stopGame();

Opción	Qué es
`is`	El estado inicial de la física (una cadena LZ-String).
`gs`	Sobrescrituras de la configuración de juego (`Partial<GameSettings>`), como `bal`.

El servidor devuelve el blob sin cambios a todos los clientes. Un blob vacío hace que el motor de física no arranque: los jugadores no aparecen en el campo y el juego parece atascado cargando.

El IS blob

El IS blob codifica las posiciones de aparición, las rotaciones y qué cuerpos existen en la partida. Depende de dos factores:

El mapa. Un blob capturado en un mapa no sirve en otro.
El número de jugadores activos. El blob de 1v1 (2 jugadores) no sirve para 2v2 (4 jugadores).

Blobs por defecto

Para el mapa de fútbol por defecto y algunos modos, la biblioteca incluye blobs ya preparados:

import { getFootballDefaultBlob, getGamemodeDefaultBlob } from 'bonktools';

getFootballDefaultBlob(2);              // 1v1
getFootballDefaultBlob(4);              // 2v2
getGamemodeDefaultBlob('football', 2);  // por modo de juego

Para mapas que varían por sala (classic, arrows, etc.), usa la caché por mapa.

Caché por mapa

import { MapBlobCache } from 'bonktools';

const cache = new MapBlobCache('./map-blob-cache.json');

const blob = cache.getForMap(room.currentMap, 4);   // blob de este mapa para 4 jugadores
if (!blob) { /* capture um (veja abaixo) */ }
cache.setForMap(room.currentMap, 4, capturedBlob);

Capturar un blob

La forma fiable es capturarlo de una sesión real. La biblioteca incluye una utilidad:

bash

BONK_USERNAME=tu_usuario BONK_PASSWORD=tu_contraseña npx bonktools-capture-is https://bonk.io/123456abcde

Entra en la sala como espectador y espera. Cuando un host real inicia una partida en el navegador, imprime el blob en el formato BONK_INITIAL_STATE=..., listo para pegar en tu .env o en la caché por mapa. Captura un blob por cada número de jugadores activos que pienses usar.

El campo `bal`

bal indica qué cuerpo controla cada jugador, con la forma { playerId: bodyIndex }.

// bot (id 0) sin cuerpo; jugadores 5 y 7 con cuerpos 1 y 2
room.startGame({ is, gs: { bal: { 0: 0, 5: 1, 7: 2 } } });

Usa siempre el mapeo explícito. Con bal: [], los cuerpos se asignan en orden ascendente de id, y si hubo jugadores que entraron y salieron los ids tienen huecos: un jugador del equipo azul puede aparecer en el lado rojo.

Jugadores que entran con una partida en curso

Cuando un jugador entra, el host debe entregarle los datos iniciales. Hay dos paquetes posibles, y el cliente solo acepta uno:

Situación	Paquete enviado
Sala en el lobby	`INFORM_IN_LOBBY`
Partida en curso	`INFORM_IN_GAME` (lleva el estado de la partida)

La biblioteca elige sola: si se inició una partida con startGame({ is }) y sigue activa, el nuevo jugador recibe INFORM_IN_GAME en lugar de INFORM_IN_LOBBY, y ve la partida sin reiniciarla para los demás.

Si tu bot reinicia la partida justo después de que alguien entre (como hace la sala 24/7 para completar equipos), todo funciona: el jugador recibe el paquete correcto y luego el inicio de la nueva partida.