Documentación de la API del motor

El juego es un script Lua (main.lua) con 3 callbacks que cumple, y una
API de funciones que llama. Naming estándar en inglés, estilo Playdate/PICO-8:
acrónimos cortos y consistentes. El juego nunca toca el hardware.

Callbacks (lo que el juego implementa)

Callback	Cuándo se llama	Obligatorio
init()	Una vez, al cargar el juego	recomendado
update(dt)	Cada frame (30/60 fps)	sí
onButton(n)	Al pulsarse el botón n	no

function init()
    -- cargar sprites, niveles, estado inicial
end

function update(dt)
    -- lógica + dibujo
end

function onButton(n)
    -- reaccionar a un botón concreto
end

---

Módulo GRAPHICS

clear(color)

Rellena toda la pantalla de un color RGB565.

clear(0x0000)   -- negro

rect(x, y, w, h, color)

Rectángulo relleno (esquina + tamaño).

line(x0, y0, x1, y1, color)

Línea (Bresenham).

text(str, x, y, color[, scale])

Texto con fuente bitmap 5×7 (mayúsculas + dígitos). scale = ampliación.

textWidth(str[, scale]) -> px

Ancho del texto en píxeles, para centrarlo.

text("GAME OVER", (480 - textWidth("GAME OVER", 2)) / 2, 150, 0xFFFF, 2)

spr(id, x, y[, flip])

Dibuja un sprite registrado. flip = espejo horizontal.

sprSize(id) -> width, height

Dimensiones del sprite, para colisiones.

mode7(groundId, camX, camY, angle, horizon[, camH[, focal]])

Plano de suelo con perspectiva (estilo SNES Mario Kart).
- groundId: sprite que es la textura del suelo (cuadrada, potencia de 2).
- camX, camY: posición de la cámara en el mundo.
- angle: hacia dónde mira, en radianes.
- horizon: fila donde empieza el suelo (arriba queda intacto).
- camH: altura de la cámara. focal: longitud focal.

clear(0x001F)                        -- cielo azul
mode7(track, camX, camY, angle, 100) -- suelo del horizonte hacia abajo
spr(car, 240, 160)                   -- el coche encima

---

Módulo INPUT

Función	Devuelve	Significado
btn(n)	true/false	Botón n mantenido
btnp(n)	true/false	Botón n pulsado justo ahora (flanco)

Botones estándar:

n	Botón
0	A
1	B
2	Up
3	Down
4	Left
5	Right

if btnp(0) then
    -- saltar solo en el momento exacto de pulsar A
end

---

Módulo TIME

dt() -> seconds

Segundos desde el frame anterior. Úsalo siempre para mover cosas.

x = x + speed * dt()   -- píxeles por segundo, no por frame

---

Módulo RESOURCES (loader, no el juego)

Función	Uso
registerSprite(id, width, height, ptr)	Registra un sprite en PSRAM (la usa el loader)

---

Colores RGB565 de referencia

Nombre	Valor
Black	0x0000
Blue	0x001F
Green	0x07E0
Red	0xF800
White	0xFFFF
Yellow	0xFFE0
Magenta (transparente)	0xF81F
Cyan	0x07FF

Reglas de oro

1. dt() para todo movimiento — nunca movimientos por frame fijo.
2. Magenta = transparente en los sprites.
3. El orden de dibujo es el orden de llamadas — fondo primero.
4. El suelo de mode7 debe ser cuadrado y potencia de dos (64, 128, 256…).