Referencia
Errores y solución de problemas
Síntomas comunes, causas y cómo resolverlos.
Los jugadores no pueden moverse durante la partida
Síntoma: la partida empieza, pero los discos se quedan quietos en el spawn (claros y sin nombre).
Causa común: la sala está bloqueada (lockTeams()) y el inicio de la partida se envió con gs.tl = false.
Solución: usa la versión 0.1.4 o superior, que envía gs.tl según el estado real del bloqueo. Si montas el TRIGGER_START a mano, rellena gs.tl con el valor de room.state.teamsLocked.
Un jugador que entra durante la partida se queda atascado en el lobby
Causa: el host envió INFORM_IN_LOBBY y luego INFORM_IN_GAME (o al revés). El cliente solo acepta un paquete de datos iniciales.
Solución: desde la 0.1.2 la biblioteca envía solo INFORM_IN_GAME cuando hay una partida activa iniciada con startGame({ is }). Si inicias partidas por otro camino, pasa el is para que la sala sepa que hay una partida en curso.
La partida empieza, pero los jugadores no aparecen en el campo
Causa: el IS blob está vacío o no corresponde al mapa/número de jugadores.
Solución: captura un blob para cada combinación (consulta Partidas, IS blob y espectadores) y usa un bal explícito.
rate_limit_tl, rate_limit_cot y otros
Causa: demasiados comandos en poco tiempo. El servidor los rechaza y avisa con un status-message.
Solución: espacia las llamadas. Un lockTeams() repetido ya envía una sola vez y reintenta solo si lo rechazan.
El enlace de la sala no se abre
Causa: en versiones anteriores a la 0.1.3, los ids de sala con menos de 6 dígitos llegaban sin ceros a la izquierda (por ejemplo 6813vnxpi en lugar de 006813vnxpi).
Solución: actualiza la biblioteca; room.shareLink ya viene completo.
RoomCreationTimeoutError o RoomJoinTimeoutError
El servidor no respondió a tiempo (por defecto: 10 s). Comprueba la red y las credenciales e inténtalo de nuevo. Aumenta timeoutMs en redes lentas.
room-dead con status-room_full
Cuando el bot aún no estaba en la sala, significa que está llena (terminal). Si ya estaba, el aviso solo indica que otro jugador fue rechazado.
Errores de TypeScript procedentes de node_modules/bonktools
Si compilas con skipLibCheck: false, el index.d.ts del paquete puede mostrar errores sobre socket.io-client y eventemitter3. Deja skipLibCheck: true (el valor por defecto de tsc --init); con él, los tipos funcionan por completo.
El anti-AFK marca a todo el mundo
El movimiento viene de los frames de input por WebRTC. Si las pestañas de los jugadores están en segundo plano, o WebRTC no llegó a conectar, no llega ningún frame. Consulta las limitaciones del anti-AFK y comprueba que se está emitiendo peer-input.
Los jugadores no se mueven después de que alguien sale y otros entran
Causa: blob capturado con ids de otra sesión (el IS blob guarda un disco por id de jugador).
Solución: usa la versión 0.2.0 o superior y genera el estado con ScoreTracker.buildInitialState (o remapInitialStatePlayers para un blob solo capturado).
El juego a veces no se renderiza (pantalla oscura) al iniciar
Causa: el is se codificó con LZString.compressToBase64. El cliente decodifica con decompressFromEncodedURIComponent y trunca el estado cuando aparecen / o = (RangeError: Illegal offset en PSON).
Solución: actualiza a la 0.2.0 (encodeInitialState usa el alfabeto correcto) y no envíes blobs codificados con otra herramienta en base64 normal.
El perdedor va al spec en vez de jugar de nuevo
Causa común: fue marcado como AFK por pasar 12 s sin pulsar tecla al final de la partida. Solución: en la 0.2.0 una tecla mantenida cuenta como actividad y, en partidas terminadas por puntos, la inactividad final se ignora. En pruebas, usa BONK_DEBUG=1 para desactivar el AFK automático.
La sala juega 1v1 aunque haya muchos jugadores
Causa: sin BONK_MAXTEAMSIZE en el .env la app antigua asumía 1. Solución: define BONK_MAXTEAMSIZE=2 (ahora el valor por defecto es 2).
Preguntas frecuentes
¿Necesito una cuenta de bonk.io? Para alojar salas 24/7, sí: usa una cuenta registrada.
¿En qué sistemas funciona? Es Node.js (20.18.1 o superior), sin navegador ni dependencias nativas del juego. El desarrollo y las pruebas se hicieron en Windows.
¿Puedo ejecutar varias salas? Sí, con BonkSession. Una sola cuenta puede mantener varias salas, respetando el throttle.
¿Es oficial? No. Es un proyecto independiente, sin afiliación con bonk.io.
¿Dónde informo de un problema? Abre una issue en el repositorio de la biblioteca.