Biblioteca

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

ts
room.startGame({ is: isBlob, gs: { bal: { 0: 0, 5: 1, 7: 2 } } });
room.stopGame();
OpciónQué es
isEl estado inicial de la física (una cadena LZ-String).
gsSobrescrituras 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:

ts
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

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

ts
// 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ónPaquete enviado
Sala en el lobbyINFORM_IN_LOBBY
Partida en cursoINFORM_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.

Generar el estado inicial (y trampas del IS blob)

En lugar de capturar blobs, usa ScoreTracker.buildInitialState(players) (consulta Puntuación y ganador): genera el estado de la partida de fútbol con el propio código del juego, para cualquier cantidad de jugadores y cualquier id. Lo que aprendimos del formato:

  • El IS blob guarda un disco por id de jugador (players y discs son arrays indexados por id). Un blob capturado solo sirve para los ids de la sesión en que se capturó: con otros ids el disco se queda quieto en el spawn. remapInitialStatePlayers reescribe los ids; buildInitialState ya genera el estado correcto.
  • El formato es PSON → base64 → LZString.compressToEncodedURIComponent, con las mayúsculas/minúsculas de las primeras 101 letras invertidas. El cliente decodifica con decompressFromEncodedURIComponent (alfabeto URI-safe): compressToBase64 emite / y = y el cliente trunca la decodificación (el juego no se renderiza, de forma intermitente).
  • El base64 interno no puede llevar relleno =, y el número de bytes debe ser múltiplo de 3 (encodeInitialState se encarga).
  • gs.bal no mapea cuerpos: es el balance de cada jugador (-100 a 100). Con el estado generado, deja el valor por defecto.
  • Los blobs de 2 y 4 jugadores de getFootballDefaultBlob se decodifican como basura; no los uses.