Kaboom.js Deep Dive [ARCHIVADO]

🎯 Resumen Ejecutivo

Kaboom.js es un micro-framework JavaScript para crear juegos 2D en el navegador. Desarrollado originalmente por Replit, está diseñado con una filosofía radical: menos configuración, más creación. Con solo ~50 KB (gzip), ofrece un sistema de componentes intuitivo, física básica, manejo de escenas, audio, input y animaciones — todo desde una API concisa que importa funciones al scope global.

La versión actual es la v3000.0.1 (también conocida como "Kaboom 3000"), un rewrite completo que mantiene la simplicidad pero con mejoras en rendimiento y consistencia. Es la tecnología que impulsa nuestro primer juego Frog Jumper.

🚀 1. Alcance y Capacidades

Kaboom.js puede hacer mucho más de lo que su tamaño sugiere. Estas son sus capacidades principales:

🎮

Juegos 2D Completos

Platformers, shooters, puzzles, RPGs top-down, runners infinitos, juegos de ritmo. Cualquier género 2D es viable.

MUY CAPAZ

🧱

Sistema de Componentes

Arquitectura basada en composición: sprite(), pos(), area(), body(), health(), etc. Es como jugar con LEGO.

FORTALEZA CLAVE

🎨

Renderizado Canvas 2D

API nativa del navegador. Sprites, rectángulos, círculos, polígonos, textos, líneas y shaders básicos.

CANVAS 2D

🎵

Audio Integrado

Reproduce sonidos y música con play(), control de volumen, loop, velocidad, detune. Formatos WAV, MP3, OGG.

COMPLETO

🎬

Animaciones de Sprites

Spritesheets con sliceX/sliceY, atlas de sprites, animaciones con play() y stop(), control de frames.

BÁSICO-MEDIO

🗺️

Tilemaps

Crea niveles desde strings con addLevel(). Define símbolos que mapean a componentes. Ideal para prototipar rápido.

PROTOTIPADO

1.1 Física y Colisiones

Kaboom incluye física básica con gravedad configurable via setGravity(). El componente body() añade caída por gravedad, saltos con .jump(), y detección de suelo con .isGrounded(). Las colisiones usan AABB (Axis-Aligned Bounding Box) mediante el componente area().

// Física básica en Kaboom.js
const player = add([
    sprite("bean"),
    pos(80, 40),
    area(),        // collider AABB
    body(),        // gravedad + salto
])

setGravity(1600)

onKeyPress("space", () => {
    if (player.isGrounded()) {
        player.jump(800)
    }
})
    

1.2 Gestión de Escenas

El sistema de escenas permite organizar el juego en pantallas independientes: menú principal, gameplay, game over, configuración. Cada escena es una función que se activa con go("nombre").

// Sistema de escenas
scene("game", () => {
    // lógica del juego
    const player = add([ sprite("bean"), pos(100, 100) ])
})

scene("lose", (score) => {
    add([ text("Game Over: " + score), pos(center()), anchor("center") ])
    onKeyPress(() => go("game"))
})

go("game")  // iniciar
    

1.3 Input Completo

Kaboom maneja teclado, mouse y touch de forma unificada: onKeyPress(), onKeyDown(), onClick(), onMouseMove(), onTouchStart(), etc. También soporta input de gamepad vía la API del navegador.

1.4 Cámara y Efectos Visuales

Control de cámara con camPos(), camScale(), camRot(). Efectos como shake() para vibración de pantalla, flash() para destellos, y shaders personalizados con loadShader() + shader() component.

1.5 Sistema de Partículas

Aunque no tiene un sistema de partículas dedicado, addKaboom() genera explosiones visuales predefinidas. Para partículas custom se pueden crear objetos pequeños con lifespan() y comportamientos personalizados.

1.6 Timers y Tweening

wait() para delays, loop() para acciones periódicas, tween() para animaciones suaves entre valores. Todo integrado en el game loop de Kaboom.

// Timers y tweening
wait(2, () => spawnEnemy())

loop(1, () => {
    add([ sprite("coin"), pos(rand(0, width()), 0), "coin" ])
})

// Animar posición suavemente
await tween(player.pos, mousePos(), 0.5,
    (p) => player.pos = p,
    easings.easeOutBounce
)
    

⚠️ 2. Limitaciones y Fronteras

Conocer las limitaciones es tan importante como conocer las capacidades. Estas son las fronteras de Kaboom.js:

Solo Canvas 2D: No usa WebGL nativamente. El renderizado es puramente Canvas 2D API, lo que limita el número de sprites simultáneos antes de que baje el FPS. ~500-1000 sprites es el límite práctico en dispositivos móviles.
Física simple (AABB): Las colisiones son cajas alineadas a los ejes. No hay soporte nativo para círculos, polígonos convexos, ni física de cuerpo rígido (como Box2D o Matter.js). Rotaciones con colisiones precisas requieren trabajo manual.
Sin 3D: Es estrictamente 2D. No hay proyección 3D, cámaras perspectiva, ni modelos. Para 3D se necesita Three.js u otra biblioteca.
Sin multiplayer nativo: No incluye networking. Para multiplayer se debe integrar manualmente con Socket.io, WebRTC u otra solución.
Sin exportación nativa: Los juegos corren en el navegador. No hay exportador a .exe, .apk o .ipa nativos. Se puede usar wrappers como Electron o Capacitor, pero no es nativo.
Animaciones limitadas: Sprite sheets con frames secuenciales, pero sin skeletal animation (Spine, DragonBones), sin blending de animaciones, y sin sistema de estados de animación complejo.
Sin editor de niveles: Los tilemaps se definen como strings o JSON manualmente. No hay editor visual integrado ni herramienta de diseño de niveles.
Comunidad pequeña: Comparado con Phaser o Unity, la comunidad es reducida. Menos tutoriales, plugins de terceros, y recursos pre-hechos.
Documentación dispersa: La v3000 cambió mucho de la API. Algunos ejemplos antiguos no funcionan. La documentación oficial es buena pero no exhaustiva.
Scope global por defecto: Al llamar kaboom(), todas las funciones se importan al scope global. Puede causar colisiones con otras librerías. Se puede usar global: false pero es menos conveniente.
Sin sistema de UI avanzado: Texto básico, rectángulos y círculos. No hay botones pre-diseñados, sliders, scroll views, ni layouts complejos. Todo UI debe construirse manualmente.
Audio sin efectos DSP: Reproduce archivos pero no aplica efectos de audio en tiempo real (reverb, delay, ecualización). Para eso se necesita Web Audio API manual o Tone.js.

⚠️ Cuándo NO usar Kaboom.js

Si tu proyecto requiere: física compleja con rotaciones, más de 1000 objetos simultáneos, gráficos 3D, multiplayer en tiempo real como feature principal, exportación nativa a móvil, animaciones esqueléticas, o un editor de niveles visual — Kaboom.js no es la herramienta adecuada. Considera Phaser 4, Godot Web, o Unity WebGL en su lugar.

📦 3. Uso de Recursos

Kaboom.js carga recursos de forma asíncrona antes de iniciar el juego. Aquí está todo lo que necesitas saber sobre assets:

3.1 Sprites

La función principal es loadSprite(). Soporta PNG, JPG y GIF estáticos.

// Cargar un sprite simple
loadSprite("bean", "sprites/bean.png")

// Cargar desde URL externa
loadSprite("apple", "https://kaboomjs.com/sprites/apple.png")

// Spritesheet con animaciones
loadSprite("hero", "sprites/hero.png", {
    sliceX: 4,   // 4 columnas
    sliceY: 1,   // 1 fila
    anims: {
        idle: { from: 0, to: 0 },
        run:  { from: 1, to: 3 },
        jump: { from: 3, to: 3 },
    },
})

// Usar el sprite
const player = add([
    sprite("hero", { anim: "idle" }),
    pos(100, 100),
])

player.play("run")   // reproducir animación
player.stop()         // detener
player.frame = 2        // frame específico
    

3.2 Sprite Atlas

Para múltiples sprites en una sola imagen (optimización de draw calls):

// Atlas manual
loadSpriteAtlas("sprites/dungeon.png", {
    "hero": {
        x: 128, y: 68,
        width: 144, height: 28,
        sliceX: 9,
        anims: {
            idle: { from: 0, to: 3 },
            run:  { from: 4, to: 7 },
            hit:  8,
        },
    },
    "enemy": {
        x: 0, y: 100,
        width: 32, height: 32,
    },
})

// Atlas desde JSON (exportado de TexturePacker, etc.)
loadSpriteAtlas("sprites/dungeon.png", "sprites/dungeon.json")
    

3.3 Aseprite

Soporte nativo para archivos de Aseprite (editor de pixel art popular):

loadAseprite("player", "sprites/player.png", "sprites/player.json")

const player = add([ sprite("player"), pos(100, 100) ])
player.play("walk")  // usa los nombres de animación de Aseprite
    

3.4 Sonidos y Música

Kaboom distingue entre sonidos (efectos) y música (loops largos), aunque ambos usan la misma API subyacente.

// Cargar assets de audio
loadSound("shoot", "sounds/shoot.wav")
loadSound("jump", "sounds/jump.mp3")
loadMusic("bgm", "music/level1.ogg")

// Reproducir efecto de sonido
play("shoot")

// Reproducir música con opciones
const music = play("bgm", {
    volume: 0.8,
    loop: true,
    speed: 1.0,
})

// Controlar música en tiempo real
music.paused = true      // pausar
music.speed = 1.2        // cambiar velocidad (pitch)
music.detune = -100     // afinar medio tono abajo
music.volume = 0.5       // volumen

// Volumen global
volume(0.7)
    

Formatos soportados: WAV (sin compresión, mejor para efectos cortos), MP3 (universal, con algo de latencia), OGG (open source, buen balance). El navegador determina qué formatos puede reproducir.

3.5 Fuentes Tipográficas

// Fuente TTF/OTF
loadFont("frogblock", "fonts/frogblock.ttf")

// Bitmap font (para pixel art)
loadBitmapFont("04b03", "fonts/04b03.png", 6, 8)

// Bitmap font con caracteres custom
loadBitmapFont("icons", "fonts/icons.png", 16, 16, {
    chars: "♥♦♣♠⚔🛡"
})

// Usar fuente cargada
add([ text("¡Hola!", { font: "frogblock", size: 32 }) ])
    

3.6 Shaders Personalizados

Kaboom permite cargar shaders GLSL para efectos visuales personalizados:

// Shader completo (vertex + fragment)
loadShader("outline",
    `vec4 vert(vec2 pos, vec2 uv, vec4 color) {
        return def_vert();
    }`,
    `vec4 frag(vec2 pos, vec2 uv, vec4 color, sampler2D tex) {
        return def_frag() * vec4(0, 0, 1, 1);
    }`,
    false
)

// Solo fragment shader desde archivo
loadShader("invert", null, "/shaders/invert.glsl", true)

// Aplicar a un objeto
add([
    sprite("bean"),
    shader("outline"),
])

// Post-processing (aplica a toda la pantalla)
usePostEffect("invert")
    

3.7 JSON y Datos

// Cargar JSON (configuraciones, niveles, etc.)
loadJSON("level1", "data/level1.json")

// Acceder después de cargar
onLoad(() => {
    const data = getData("level1")
    debug.log(data.title)
})
    

3.8 Estructura Recomendada de Carpetas

mi-juego/
├── index.html
├── src/
│   └── main.js
├── assets/
│   ├── sprites/
│   │   ├── player.png
│   │   ├── enemy.png
│   │   └── tiles.png
│   ├── sounds/
│   │   ├── jump.wav
│   │   ├── shoot.mp3
│   │   └── explosion.ogg
│   ├── music/
│   │   └── level1.ogg
│   ├── fonts/
│   │   └── pixel.ttf
│   └── data/
│       └── levels.json
    

3.9 Generación Procedural de Assets

Como Kaboom corre en el navegador, puedes generar sprites en tiempo real con Canvas API antes de cargarlos:

// Generar un sprite procedural
function createProceduralSprite(width, height, drawFn) {
    const c = document.createElement("canvas")
    c.width = width
    c.height = height
    const ctx = c.getContext("2d")
    drawFn(ctx, width, height)
    return c.toDataURL()
}

// Crear un círculo degradado como sprite
const orbUrl = createProceduralSprite(64, 64, (ctx, w, h) => {
    const grad = ctx.createRadialGradient(w/2, h/2, 0, w/2, h/2, w/2)
    grad.addColorStop(0, "#fff")
    grad.addColorStop(1, "#00f0ff")
    ctx.fillStyle = grad
    ctx.beginPath()
    ctx.arc(w/2, h/2, w/2, 0, Math.PI * 2)
    ctx.fill()
})

loadSprite("orb", orbUrl)
    

💡 Tip: loadRoot()

Usa loadRoot("https://cdn.tusitio.com/assets/") para establecer una URL base para todos los assets. Esto facilita cambiar entre entornos (dev/staging/prod) y usar CDNs.

📊 4. Comparativa Rápida

Característica	Kaboom.js	Phaser 4	Canvas Vanilla
Tamaño (gzip)	~50 KB	~345 KB	0 KB
Curva de aprendizaje	Baja	Media	Alta
Render	Canvas 2D	WebGL / Canvas	Canvas 2D
Física	AABB básica	Arcade / Matter.js	Manual
Spritesheets	● Sí	● Sí	✗ Manual
Tilemaps	● Básico	● Avanzado	✗ Manual
Escenas	● Sí	● Sí	✗ Manual
Audio	● Sí	● Sí	● Web Audio API
Shaders	● Básico	● Avanzado	● WebGL
Partículas	● Básico	● Avanzado	✗ Manual
Tweening	● Sí	● Sí	✗ Manual
Mobile/Touch	● Sí	● Sí	● Manual
Comunidad	Pequeña	Grande	Nativa
Documentación IA	⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (skills)	⭐⭐⭐⭐⭐

🎯 5. Veredicto

¿Para qué proyectos es ideal Kaboom.js?

Kaboom.js brilla en proyectos donde la velocidad de desarrollo y la simplicidad superan la necesidad de features avanzados. Es la herramienta perfecta para:

Prototipos rápidos: Validar una mecánica de juego en horas, no días.
Game jams: 48-72 horas es suficiente para un juego completo y pulido.
Juegos arcade 2D: Shoot 'em ups, platformers simples, puzzles, runners.
Experiencias interactivas web: Micro-juegos, demos, presentaciones gamificadas.
Aprendizaje: Entender conceptos de game dev sin la sobrecarga de un motor grande.
Juegos con assets mínimos: Procedural, geométricos, o con pocos sprites.

⚠️ Cuándo elegir otra herramienta

Si tu juego necesita física compleja, 1000+ objetos simultáneos, gráficos 3D, multiplayer como feature principal, o exportación nativa — Phaser 4, Godot o Unity serán mejores opciones. Kaboom.js es un micro-framework, no un motor completo.

💡 Veredicto del Gaming Lab

Kaboom.js es nuestra elección para Fase 1 del laboratorio: prototipos ágiles, aprendizaje de mecánicas, y juegos arcade. Su API concisa nos permite iterar rápidamente con Kimi CLI. Para Fases 2-4 (juegos más ambiciosos), migraremos progresivamente a Phaser 4 y Three.js, pero el conocimiento adquirido con Kaboom (componentes, escenas, game loop) será directamente transferible.

🎮 6. Caso de Estudio: Frog Jumper

Nuestro primer juego, Frog Jumper, demuestra las capacidades reales de Kaboom.js:

Física: Gravedad, salto con body() y colisiones AABB con obstáculos.
Spawning procedural: Obstáculos generados con wait() recursivo y alturas aleatorias.
Escenas: Pantalla de juego y pantalla de game over con transición.
Score: Contador incremental con onUpdate() y renderizado de texto.
Feedback visual: shake() y addKaboom() al colisionar.
Input: Teclado (space) y touch/mouse con onKeyPress() y onClick().
Sin assets externos: Todo se dibuja con rect(), sprite() básico y colores.

El juego completo cabe en ~100 líneas de JavaScript. Esa es la promesa de Kaboom.js: de la idea al juego funcional en el menor tiempo posible.

📚 Referencias

Kaboom.js Official Website — kaboomjs.com
Kaboom.js GitHub Repository — github.com/replit/kaboom
Kaboom.js Intro Tutorial — kaboomjs.com/doc/intro
Kaboom.js Setup Guide — kaboomjs.com/doc/setup
Kaboom.js Playground — kaboomjs.com/play
Kaboom.js v3000 Release Notes — github.com/replit/kaboom/releases
Replit Kaboom Template — replit.com/@replit/Kaboom
HTML5 Canvas API MDN — developer.mozilla.org/Web/API/Canvas_API
Web Audio API MDN — developer.mozilla.org/Web/API/Web_Audio_API
Aseprite — Editor de sprites y animaciones — aseprite.org
TexturePacker — Generador de sprite atlases — codeandweb.com/texturepacker
Frog Jumper — Nuestro juego en Gaming Lab — gaming.testing.vulpik.com/kaboom/

💥 KABOOM.JS DEEP DIVE