Antes de empezar

Este libro te enseña a programar. Da por hecho que nunca has escrito una línea de código en tu vida, y no da por hecho que quieras ser programador — solo que quieres hacer un juego.

Cada lección termina con algo que puedes ejecutar y con lo que puedes jugar. No se deja nada para luego: no hay capítulos de teoría antes de que aparezca la primera imagen en pantalla. Escribirás tu primer programa que funciona en unos diez minutos, y tendrá cinco líneas.

Singe es un motor de juegos. Con él puedes hacer cualquier cosa que puedas hacer con cualquier otro motor, en dos dimensiones o en tres, y la mayor parte de este libro trata justo de eso. Lo que lo distingue es que también puede reproducir vídeo FMV («full motion video») como el mundo en el que ocurre el juego, que es como funcionaban los juegos de laserdisc de los salones recreativos y que casi nada más hace bien. Es una posibilidad, no una obligación: un juego solo reproduce vídeo si lo pide, y nada de lo que escribas en las trece primeras lecciones se acercará a eso.

El lenguaje es Lua, que Singe usa para todo. A Lua lo eligió gente que tenía que enseñárselo a artistas y diseñadores, y se nota. No hay puntos y coma que olvidar, ni tipos que declarar, ni compilador contra el que pelear. Cuando te equivocas, Singe te dice el archivo, la línea y lo que no ha entendido.

Lo que necesitas

  • Singe. Un archivo. Ponlo en una carpeta en algún sitio donde puedas volver a encontrarlo.

  • Un editor de texto. El Bloc de notas, TextEdit en modo de texto normal, Notepad++, VS Code o cualquier otro que guarde texto plano. Un procesador de textos no sirve: guarda un formato que no ves, y Singe no puede leerlo.

  • Nada más. No necesitas un laserdisc, ni un archivo de vídeo, ni un programa de dibujo, ni arte de ningún tipo. Toda la primera parte lo dibuja todo por sí misma, y de la segunda parte en adelante las imágenes, los sonidos, el vídeo y los modelos que necesitas vienen con el libro o con el motor. Lo que necesitas aparece más abajo.

Cómo leer este libro

Escribe el código a mano. No lo copies y pegues. Escribirlo es más lento, y de eso se trata: cometerás pequeños errores, y arreglarlos es como aprendes a leer lo que te dice el ordenador. Cada lección tiene una sección Pruébalo con cambios que hacer, y esos cambios importan tanto como la lección.

Si una lección sale mal y no ves por qué, el script terminado de cada lección está en la carpeta learn que viene con este libro, con el nombre de su lección: 01-hello.singe, y así sucesivamente. Léelo solo después de haberlo intentado.

Cómo están organizadas tus carpetas

La primera lección lo prepara y todas las siguientes lo dan por hecho, así que vale la pena verlo una vez ahora.

Tienes una carpeta de trabajo con tu copia de Singe dentro. Cada lección crea una carpeta nueva dentro de ella, con el nombre del script que contiene.

singe/                 <- tu carpeta de trabajo, con Singe dentro
    Singe/             <- el motor pone aquí sus propios archivos
    data/              <- y todo lo que guardan tus juegos
    hello/
        hello.singe
    rocks/
        rocks.singe
        art/

Una lección se ejecuta desde la carpeta de trabajo nombrando su carpeta, así que Singe rocks ejecuta rocks/rocks.singe. Esa forma corta funciona porque la carpeta y el script tienen el mismo nombre. Es la misma forma que tiene un juego instalado de verdad, y por eso el libro la usa desde la primera lección en lugar de poner orden más adelante.

Lo que viene con este libro

De la segunda parte en adelante, las lecciones usan imágenes y sonidos. Están en la carpeta art que viene con el libro, y tú copias esa carpeta en la carpeta de la lección en la que estés trabajando, sin cambiarle el nombre. Hay una nave, una roca, un disparo, una estrella, cuatro fotogramas de alguien caminando y dos ruidos. art/README.txt los enumera con sus tamaños.

El propio Singe pone el resto. La primera vez que ejecutas algo, el motor extrae una carpeta llamada Singe en tu carpeta de trabajo, y en ella hay un vídeo, una fuente, dos modelos 3D y un clic. Las lecciones que los necesitan usan los que ya están en tu disco, así que no hay nada que buscar ni nada que comprar. Nada de ello es bonito. Todo es real, y cambiarlo por algo mejor suele ser cuestión de cambiar el nombre de un archivo.

Este no es el libro de Forge

Forge, una herramienta aparte con un libro propio, crea un juego describiéndolo en lugar de programándolo. Es otro camino hacia otro sitio, para quien no quiere escribir código en absoluto. Si has venido a aprender a programar, estás en el sitio adecuado. No necesitas Forge ni su libro, y este no se apoya en él.

La Referencia de Singe es la referencia: cada función, cada argumento, cada valor de retorno y el modelo de programación que hay detrás. No es un tutorial ni intenta serlo. Empezarás a echar mano de ella hacia la lección seis, y al final de este libro la usarás más que este libro. Viene en la misma descarga que este.

La serie

Treinta y una lecciones en cuatro partes. Cada una necesita la anterior y nada más.

Primera parte: las ideas. Sin arte, sin vídeo, sin nada que instalar. Dibujas con las formas y el texto que ya tiene el motor, y aprendes de qué está hecho un programa.

  1. Hola — un script, una función, una cadena y algo en pantalla.

  2. Números que cambian — variables, aritmética y hacer que algo se mueva.

  3. Tomar decisiones — if, comparaciones y leer los controles.

  4. Otra vez — for y while, y dibujar cien de algo.

  5. Tus propias funciones — argumentos, valores de retorno y por qué molestarse.

  6. Listas de cosas — tablas, ipairs, añadir y quitar.

  7. Un juego — todo lo visto hasta ahora, jugable, en unas ciento veinte líneas.

  8. Cuando algo sale mal — leer errores, debugPrint y recargar con F5.

Segunda parte: un juego de verdad. Arte, sonido y la forma que toma un juego terminado.

  1. Imágenes — sprites, cargar, dibujar y fotogramas.

  2. Sonido — efectos, música y cuándo cargar cada cosa.

  3. Chocar con cosas — colisiones, el kit de juego y las zonas de impacto.

  4. Puntuación, vidas y fin de partida — estado, guardar y volver a empezar.

  5. Una carpeta de juego — games.dat, arte para el menú y ejecutar desde él.

Tercera parte: vídeo. Reproducir imágenes filmadas como el mundo del juego, y las convenciones de las recreativas que surgieron a su alrededor. Sáltate esta parte si tu juego no quiere vídeo; nada de lo que viene después depende de ella.

  1. Reproducir vídeo — el disco, los fotogramas, saltar y esperar.

  2. La otra forma de escribirlo — el modelo con hilo («threaded»), y por qué le va bien al vídeo.

  3. Ramificaciones — elecciones, caminos y la forma de un juego de vídeo con ramificaciones.

  4. Pistolas de luz — apuntar, disparar y la calibración que necesita una recreativa.

  5. Quick-time events — indicaciones, ventanas de tiempo y puntuar la sincronización del jugador.

Cuarta parte: todo lo demás. Cada lección se sostiene sola; hazlas en el orden que quieras.

  1. Texto con buen aspecto — fuentes, calidad y medir.

  2. Menús y pantallas — la GUI, los documentos y el estilo.

  3. Subtítulos — y por qué son un sistema aparte.

  4. Hacia el 3D — escenas, cámaras y coordenadas.

  5. Modelos y luz — glTF, materiales y animación.

  6. Física — cuerpos, fuerzas, articulaciones y cuándo no usarlos.

  7. Partículas — emisores, y cómo hacer una explosión.

  8. Personajes que se mueven solos — navegación y búsqueda de caminos.

  9. Música y MIDI — pistas, soundfonts e instrumentos.

  10. En línea — cuentas, tablas de récords y el catálogo.

  11. Guardar datos — bases de datos, tablas y las preguntas que les haces.

  12. Publicarlo — empaquetar, parchear, licencias y la publicación.

  13. En una recreativa — controles, menús de servicio, bezels y las cosas que solo importan en hardware de verdad.

Lección 1: Hola

La lección terminada

Eso es lo que tendrás al final de esta lección. No es gran cosa a la vista. También es un programa que has escrito tú, funcionando en un motor de juegos de verdad, y todo lo demás de este libro se construye sobre las cinco líneas que lo hicieron.

Prepara tu carpeta de trabajo

Crea una carpeta para guardarlo todo, llamada singe o como quieras, y pon dentro tu copia de Singe. Esta es tu carpeta de trabajo, y cada lección de este libro pone una carpeta nueva dentro de ella. La crearás una vez y no volverás a pensar en ella.

Dentro de la carpeta de trabajo, crea una carpeta llamada hello, y dentro de ella un archivo llamado hello.singe.

singe/                 <- tu carpeta de trabajo, con Singe dentro
    hello/
        hello.singe

Tanto anidamiento no es una manía. Singe trata la carpeta desde la que lo ejecutas como el sitio donde viven los juegos, una carpeta por juego, y también guarda allí sus propios archivos. Tu juego va en su propia carpeta, un nivel más abajo. De la lección dos en adelante, cada lección es otra carpeta junto a hello.

Dos cosas sobre los nombres. La parte que va después del punto, .singe, es como Singe sabe que esto es un script. Y en la mayoría de los ordenadores que no son Windows, las mayúsculas cuentan: Hello.singe y hello.singe son dos archivos distintos. Acostúmbrate desde ya a escribir los nombres exactamente.

Que la carpeta y el script tengan el mismo nombre también importa, y enseguida verás por qué.

Abre hello.singe en tu editor de texto. Está vacío. Es lo correcto.

Escribe esto

function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    return OVERLAY_UPDATED
end

Guárdalo.

No te preocupes todavía por lo que significa nada de esto. Vale la pena fijarse en dos cosas antes de ejecutarlo, porque se cumplirán en todos los programas que escribas.

La primera es que los espacios al principio de las tres líneas del medio están ahí a propósito. No le hacen nada en absoluto al programa — Singe lo ejecutaría exactamente igual sin ellos — pero te muestran de un vistazo que esas tres líneas van dentro de la cosa que empieza con function y termina con end. Todos los programadores lo hacen. Hazlo desde el primer día y nunca tendrás que aprenderlo más tarde.

La segunda es el orden de las líneas. Ocurren de arriba abajo, una tras otra, como los pasos de una receta. Es lo más importante de un programa, y casi todo lo que confunde a un principiante viene de olvidarlo.

Ejecútalo

Abre una terminal, ve a tu carpeta de trabajo — no a la carpeta hello que hay dentro — y escribe el nombre de la carpeta que quieres ejecutar:

Singe hello

En Windows es Singe.exe hello. Si tu copia de Singe está en otro sitio, escribe la ruta hasta ella, por ejemplo ../Singe hello.

Por eso la carpeta y el script comparten nombre. Cuando le das una carpeta, Singe busca dentro un script que se llame igual. Ponles nombres distintos y obtendrás Error: Unable to locate the game., que es el motor diciendo que ha buscado y no ha encontrado nada que reconozca. Siempre puedes ser explícito y escribir Singe hello/hello.singe, que hace lo mismo.

Se abre una ventana negra con la palabra Hello! cerca de la esquina superior izquierda. Pulsa Esc o Q para salir.

Habrán pasado dos cosas que no has pedido, y las dos son normales. En tu carpeta de trabajo han aparecido unas carpetas llamadas Singe y data, junto a hello: la primera es el motor desempaquetando los archivos que necesita, y la segunda es donde irá todo lo que guarden tus juegos. Deja las dos en paz. Y la ventana es casi toda negra, porque no has dibujado nada aparte de seis caracteres.

Qué acaba de pasar

Ahora las cinco líneas, de una en una.

function onOverlayUpdate()

function empieza un grupo de instrucciones y le da un nombre. Todo lo que hay desde aquí hasta el end que le corresponde le pertenece. Esta se llama onOverlayUpdate, y los paréntesis vacíos después del nombre tendrán sentido en la lección cinco.

Ese nombre no lo eliges tú. Singe busca una función con exactamente ese nombre y la llama unas sesenta veces por segundo, para siempre, para que tengas ocasión de dibujar. Si lo escribes onoverlayupdate u onOverlayUpdated, Singe no la encontrará, tu ventana se quedará negra y nada te dirá que te has equivocado. Esa es la primera lección de verdad: el ordenador hace lo que escribiste, no lo que querías decir.

Una función que escribes tú y que llama el motor es un callback. No la llamas tú, y no puedes decidir cuándo se ejecuta; la escribes, y Singe te devuelve la llamada cuando hay algo que hacer. Todos los nombres de este libro que empiezan por on son callbacks, y hay uno para casi todo lo que puede pasar: un botón pulsado, una tecla escrita, un sonido que termina, el disco que llega a un fotograma. onOverlayUpdate es el de dibujar, y es el único sitio donde se permite dibujar.

    overlayClear()

Esto también es una función, pero no una que tengas que escribir tú: la proporciona Singe, junto con varios cientos más, y tú la estás llamando. Llamar a una función significa decir su nombre seguido de paréntesis. Esta deja la pantalla limpia.

Va primero porque dibujar no sustituye lo que había antes, sino que dibuja encima. Primero limpias, luego dibujas, siempre.

    overlayPrint(2, 2, "Hello!")

Otra llamada, y a esta hay que decirle tres cosas, que van dentro de los paréntesis separadas por comas. Las cosas que le das así a una función se llaman argumentos.

Las dos primeras son números: cuánto hacia la derecha y cuánto hacia abajo. La tercera es el texto que hay que imprimir, y va entre comillas dobles porque así es como le dices al ordenador que Hello! es un trozo de texto y no el nombre de algo. Al texto entre comillas se le llama cadena, y usarás cadenas constantemente.

Tarde o temprano querrás poner unas comillas dobles dentro de una cadena, y la forma obvia no funciona: las segundas comillas terminan la cadena antes de tiempo, y te sale el mismo error unfinished string que verás al final de esta lección. Hay dos formas de evitarlo, y vale la pena conocer las dos.

    overlayPrint(2, 2, "She said \"hello\" to me.")
    overlayPrint(2, 4, 'She said "hello" to me.')

La primera pone una barra invertida delante de cada comilla que forma parte del texto. La barra invertida dice «el siguiente carácter es parte de la cadena, no su final», y las dos juntas se llaman secuencia de escape. La segunda usa comillas simples para marcar los extremos de la cadena, lo que deja las comillas dobles libres para ser texto normal. Lua acepta cualquiera de los dos tipos de comillas, siempre que la cadena termine con el mismo tipo con el que empezó.

Esas dos líneas imprimen exactamente lo mismo. Usa la que se lea mejor, que suele ser la de comillas simples cuando el texto está lleno de comillas dobles.

Los dos números no son píxeles. overlayPrint es el texto sencillo del propio motor, y cuenta en celdas de carácter: (0, 0) es la esquina superior izquierda del todo, (1, 0) es una letra a la derecha, y (0, 1) es una línea más abajo. Así que (2, 2) está dos letras hacia dentro y dos líneas hacia abajo. Otras formas de dibujar texto sí cuentan en píxeles, y las verás en la lección diecinueve.

    return OVERLAY_UPDATED

return devuelve una respuesta a quien haya llamado a la función. Singe le hace a tu onOverlayUpdate una pregunta cada vez que la llama: ¿has cambiado algo? OVERLAY_UPDATED significa que sí, así que ponlo en pantalla.

OVERLAY_UPDATED no lleva comillas porque no es texto. Es un nombre que Singe ya le ha dado a un valor, para que puedas escribir algo que se pueda leer en lugar de un número que tendrías que recordar.

end

El final que corresponde a la function. Cada function tiene exactamente uno, y olvidarlo es el error más común que existe.

Pruébalo

Cambia una cosa cada vez, guarda y vuelve a ejecutarlo. Ese ciclo — cambiar, ejecutar, mirar — es todo el trabajo.

  1. Mueve el texto. Cambia overlayPrint(2, 2, "Hello!") por overlayPrint(10, 5, "Hello!"). Luego prueba (0, 0). Luego prueba (200, 2), y averigua por qué ha desaparecido.

  2. Di otra cosa. Pon tu nombre entre las comillas.

  3. Di dos cosas. Añade una segunda línea overlayPrint debajo de la primera, con otro número de fila y otro texto. Nada te impide tener tantas como quieras.

  4. Quita la limpieza. Borra la línea overlayClear() y ejecútalo. No cambia nada, porque todavía no se mueve nada en tu pantalla. Vuelve a ponerla de todos modos. En la lección dos importará muchísimo, y este es un buen momento para ver que algunos errores esperan antes de morder.

Rómpelo a propósito

Los principiantes pasan más tiempo leyendo mensajes de error que leyendo libros de programación, así que quitémonos ya el primero de encima.

Borra las comillas de cierre después de Hello!, para que la línea quede overlayPrint(2, 2, "Hello!), y ejecútalo. Singe se niega a arrancar y dice:

Error running script:  hello/hello.singe:3: unfinished string near '"Hello!)'

Léelo desde la izquierda. hello/hello.singe es qué archivo: la carpeta y luego el script que hay dentro. 3 es qué línea. El resto es lo que ha ido mal, en este caso un trozo de texto que se abrió y nunca se cerró. Ve a la línea tres, vuelve a poner las comillas y funciona.

Casi todos los errores que verás tienen esa forma: un archivo, una línea y una queja. La queja a veces está escrita para alguien que ya sabe Lua, pero el archivo y la línea siempre son correctos, y nueve de cada diez veces la línea basta.

Deja de reiniciarlo

Ya has arrancado Singe a mano cinco o seis veces. Deja de hacerlo. Ejecútalo así:

Singe -R hello

-R le dice a Singe que vigile tu script. Guarda un cambio en tu editor y el juego se reinicia solo un momento después con tu cambio dentro, sin cerrar la ventana. Si guardas un error, se imprime el error y la ventana se queda vacía hasta que guardes el arreglo.

Usa -R durante el resto de este libro.

Lo que has aprendido

  • Un programa es un archivo de instrucciones que ocurren en orden, de arriba abajo.

  • Una function agrupa instrucciones bajo un nombre y se detiene en su end.

  • onOverlayUpdate es un nombre que Singe busca y llama muchas veces por segundo, y es donde va todo lo que dibujas.

  • Llamar a una función significa escribir su nombre y unos paréntesis. Lo que va dentro de los paréntesis es un argumento.

  • Una función que el motor llama por ti, en lugar de una que llamas tú, es un callback. onOverlayUpdate es uno.

  • El texto entre comillas dobles es una cadena.

  • Limpia la pantalla antes de dibujar en ella.

  • Un error te dice el archivo y la línea. Empieza por ahí.

La próxima vez

Tu Hello! se queda donde lo pusiste y nunca se mueve. Para que se mueva, necesitas un sitio donde guardar un número que cambia — una variable — y de eso trata toda la lección dos.

Lección 2: Números que cambian

La lección terminada

En la lección uno pusiste una palabra en la pantalla y allí se quedó. Al final de esta lección, esa misma palabra irá deslizándose por la ventana, dará la vuelta cuando llegue a un borde, y lo hará gracias a cuatro números que el programa cambia sesenta veces por segundo.

Por el camino conocerás la idea que hace tropezar a más principiantes que ninguna otra: dónde pones algo decide cuánto tiempo vive.

Empieza una carpeta nueva

Crea una carpeta llamada numbers junto a tu carpeta hello, y dentro de ella un archivo llamado numbers.singe. Escribe en él el programa de la lección uno, o copia hello.singe y cámbiale el nombre — cualquiera de las dos cosas vale, y escribirlo otra vez no es tiempo perdido.

function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    return OVERLAY_UPDATED
end

Ejecútalo con Singe -R numbers y déjalo funcionando. El -R del final de la lección uno significa que no tendrás que volver a arrancarlo durante el resto de esta lección; guarda el archivo y la ventana se pone al día sola.

Cuenta los fotogramas

La lección uno decía que Singe llama a onOverlayUpdate unas sesenta veces por segundo. Es fácil de decir y difícil de creer, así que cuéntalas.

function onOverlayUpdate()
    frames = 0
    frames = frames + 1
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    overlayPrint(0, 0, "frame " .. frames)
    return OVERLAY_UPDATED
end

Guárdalo. En la esquina superior izquierda aparece frame 1, y se queda en frame 1 para siempre.

Es decepcionante, y también es lo más útil de esta lección, así que no lo arregles todavía. Mira lo que has escrito y piensa en el orden de las líneas, que según la lección uno era lo más importante de un programa.

Singe llama a onOverlayUpdate. La primera línea pone frames a cero. La segunda le suma uno, y queda en uno. Lo imprimes, devuelves la respuesta y la función se acaba. Luego Singe la llama otra vez, y lo primero que pasa es que frames vuelve a ponerse a cero.

No estás contando fotogramas. Estás contando hasta uno, sesenta veces por segundo.

Saca la línea

Saca la línea frames = 0 de la función y ponla encima, ella sola, antes de la palabra function.

frames = 0


function onOverlayUpdate()
    frames = frames + 1
    overlayClear()
    overlayPrint(2, 2, "Hello!")
    overlayPrint(0, 0, "frame " .. frames)
    return OVERLAY_UPDATED
end

Guárdalo. El número sube, deprisa, y no para.

No ha cambiado nada más. La única diferencia es dónde está la línea, y esa es toda la idea. Las líneas que están dentro de una función ocurren cada vez que se llama a la función. Las líneas que están fuera de todas las funciones ocurren una vez, cuando Singe lee tu archivo, antes de que empiece el juego.

frames = 0 tenía que ocurrir una vez. Estaba ocurriendo sesenta veces por segundo, y borraba el trabajo de la línea de debajo.

Todo lo que se mueva que escribas tendrá esta forma. Prepara el número fuera, cámbialo dentro.

Qué acaba de pasar

Ahí dentro hay tres piezas de código nuevas. Aquí están por separado.

frames = 0

Esto se inventa un nombre, frames, y pone el número cero detrás de él. Un nombre con un valor detrás es una variable, y se llama así porque el valor puede variar — cambiar mientras el programa se ejecuta.

El = no es el signo igual del colegio. No dice que frames sea igual a cero; dice mete cero en frames, y siempre funciona en esa dirección, de derecha a izquierda. Los programadores lo llaman asignación, y vale la pena decir la línea en voz alta de esa forma mientras la escribes: «frames recibe cero».

El nombre lo eliges tú. Puede ser casi cualquier cosa que empiece por una letra y no tenga espacios, y debería decir qué es la cosa. frames es un buen nombre. f es uno malo, y dentro de una semana no te lo agradecerás.

    frames = frames + 1

Esta es la línea que hace que la gente se pare y se quede mirando, porque como afirmación aritmética no tiene sentido: nada es igual a sí mismo más uno.

No es una afirmación aritmética. Recuerda que = mete el lado derecho en el nombre de la izquierda, y léela en ese orden, primero la derecha. Calcula frames + 1 con lo que haya en frames ahora mismo. Luego vuelve a meter el resultado en frames. Si frames tenía seis, el lado derecho da siete, y el siete va a frames.

Sumarle uno a una variable así es algo que escribirás miles de veces.

El + es lo que esperas, y también los otros tres: - resta, * multiplica y / divide. No hay ninguna tecla x para multiplicar, y por eso el asterisco hace ese trabajo.

    overlayPrint(0, 0, "frame " .. frames)

overlayPrint quiere texto, y frames es un número, no texto. Los dos puntos unen los dos y entregan el resultado como una sola cadena: los cinco caracteres frame, un espacio, y luego tantas cifras como necesite el número.

Esos dos puntos son el operador de unión, y vale la pena conocer su nombre de verdad porque los mensajes de error lo usan: unir cadenas se llama concatenación.

Fíjate en el espacio dentro de las comillas, antes de la de cierre. Sin él te sale frame6. Lua une exactamente lo que le das y no añade nada por su cuenta.

Lua convierte un número en texto por ti cuando lo unes así a una cadena, y por eso no has tenido que hacer nada especial. No lo hace con todo. Si alguna vez intentas unir algo que no es ni texto ni número, Lua se detiene con un error, y la forma de evitarlo es tostring, que convierte cualquier cosa en texto:

    overlayPrint(0, 0, "frame " .. tostring(frames))

Esa línea hace exactamente lo mismo que la anterior. No necesitas tostring para los números. Lo necesitarás en la lección tres.

Haz que se mueva

Ya tienes todo lo que necesitas para mover la palabra. La palabra se dibuja donde tú digas, tienes una forma de guardar un número de un fotograma a otro, y tienes una forma de cambiarlo.

Dale a la columna su propia variable fuera de la función, y súmale algo dentro.

frames = 0
wordX  = 0


function onOverlayUpdate()
    frames = frames + 1
    wordX = wordX + 1
    overlayClear()
    overlayPrint(wordX, 2, "Hello!")
    overlayPrint(0, 0, "frame " .. frames)
    return OVERLAY_UPDATED
end

Guárdalo. La palabra sale disparada por el lado derecho y no vuelve nunca.

Se movía una columna en cada fotograma, sesenta veces por segundo, así que cruzó toda la ventana en más o menos un segundo. Hazla más lenta sumando menos de una columna entera:

    wordX = wordX + 0.25

Ahora tarda cuatro fotogramas en moverse una columna, y la palabra avanza despacito. wordX casi siempre es un número como 12.75, que no es ninguna columna, y Singe lo resuelve tirando todo lo que va después del punto cuando dibuja: 12.75 se dibuja en la columna doce. Guardar la fracción en la variable es justo lo que te permite moverte más despacio que una columna por fotograma. El número es más fino que la pantalla.

¿Dónde está el borde?

La palabra sigue marchándose. Para darle la vuelta tienes que saber dónde está el borde derecho, y podrías averiguarlo contando: un juego sin vídeo recibe por defecto un mundo de 720 por 480, el overlay en el que dibujas es la mitad, 360 por 240, y las letras de la fuente de consola integrada miden seis píxeles de ancho, así que hay sesenta columnas.

No lo hagas. Pregúntale al motor.

lastColumn = overlayGetWidth() // CELL_WIDTH - string.len(word)

overlayGetWidth y overlayGetHeight son otras dos funciones que proporciona Singe, como overlayPrint. No reciben nada y devuelven un número: el ancho y el alto de la superficie de dibujo. En la lección uno viste a return devolver un valor, y este es el otro extremo — una función que llamas puede darte algo, y aquí estás haciendo cuentas con lo que te ha dado.

Los números que te dan están en píxeles, y overlayPrint cuenta en celdas de carácter, así que tienes que dividir. overlayGetFontWidth te dice cuántos píxeles de ancho tiene una celda, y overlayGetFontHeight cuántos de alto, así que nunca tienes que saberte la respuesta. Las dos barras significan divide y tira la fracción, porque un tercio de celda no es un sitio donde se pueda imprimir. La barra simple de siempre te daría una fracción, y una fracción de celda tampoco es un sitio.

string.len cuenta los caracteres de una cadena, y está ahí para que la palabra dé la vuelta cuando su última letra llegue al borde, y no la primera. Pruébalo sin él y verás seis caracteres deslizarse hacia la nada.

Las mayúsculas de CELL_WIDTH, que guarda lo que te da overlayGetFontWidth, son una costumbre, no una regla. A Lua le da igual, pero un nombre en mayúsculas es como los programadores dicen «este es un número que pongo una vez arriba y no vuelvo a tocar», y es mucho mejor que tener un 6 suelto a mitad de un archivo que nadie sabe explicar un mes después.

Dale la vuelta

Moverse en el otro sentido no cuesta nada: en lugar de sumar 0.25 en cada fotograma, suma -0.25. Así que guarda la cantidad en una variable propia y cámbiale el signo cuando la palabra llegue a un borde.

    if wordX > lastColumn then
        wordX = lastColumn
        speedX = -speedX
    end

Eso es una decisión, y las decisiones son toda la lección tres, así que créetelo sin más durante una lección. Léelo en voz alta: si wordX ha pasado de lastColumn, entonces haz las dos líneas sangradas; si no, sáltatelas. El end lo cierra, igual que end cierra una función.

La primera línea clava la palabra justo en el borde, para que una palabra rápida no se lo salte. La segunda es el cambio de signo. -speedX es menos lo que tenga speedX, así que si tenía 0.25 ahora tiene -0.25, y sumar -0.25 en cada fotograma lleva la palabra de vuelta por donde vino. Cuando llega al borde izquierdo, el if correspondiente le vuelve a cambiar el signo, y vuelve a ser 0.25.

Dos más como esos para los bordes de arriba y de abajo, y la palabra rebota por toda la ventana.

Todo junto

CELL_WIDTH  = overlayGetFontWidth()
CELL_HEIGHT = overlayGetFontHeight()
TOP_ROW     = 2

word   = "Hello!"
wordX  = 0
wordY  = TOP_ROW
speedX = 0.25
speedY = 0.125
frames = 0

lastColumn = overlayGetWidth() // CELL_WIDTH - string.len(word)
lastRow    = overlayGetHeight() // CELL_HEIGHT - 1


function onOverlayUpdate()
    frames = frames + 1
    wordX = wordX + speedX
    wordY = wordY + speedY

    if wordX < 0 then
        wordX = 0
        speedX = -speedX
    end

    if wordX > lastColumn then
        wordX = lastColumn
        speedX = -speedX
    end

    if wordY < TOP_ROW then
        wordY = TOP_ROW
        speedY = -speedY
    end

    if wordY > lastRow then
        wordY = lastRow
        speedY = -speedY
    end

    overlayClear()
    overlayPrint(0, 0, "frame " .. frames)
    overlayPrint(wordX, wordY, word)
    return OVERLAY_UPDATED
end

TOP_ROW mantiene la palabra fuera de las dos líneas de arriba, para que nunca garabatee encima del contador de fotogramas. lastRow lleva un - 1 en lugar de un string.len, porque una palabra tiene muchos caracteres de ancho pero siempre una sola línea de alto.

Fíjate en que toda la mitad de arriba del archivo se ejecuta una vez y toda la mitad de abajo sesenta veces por segundo, y en que puedes distinguir cuál es cuál mirando la sangría. Para eso eran los espacios.

Pruébalo

  1. Cambia las velocidades. Prueba speedX = 1 y speedY = 1. Luego prueba 0.05 para las dos. Luego haz una mucho mayor que la otra.

  2. Cambia la palabra. Pon una palabra mucho más larga entre las comillas — lo bastante larga para llenar un tercio de la ventana — y fíjate en que el rebote de la derecha sigue ocurriendo en el sitio correcto. Es string.len haciendo su trabajo.

  3. Quita la limpieza. Borra la línea overlayClear(). La lección uno prometió que esto importaría algún día, y hoy es ese día: la palabra deja un rastro por toda la ventana y no borra nada, porque dibujar siempre ha dibujado encima de lo que había. Vuelve a ponerla.

  4. Que no vaya de lado. Pon speedX = 0 y ejecútalo. Averigua por qué ahora la palabra no sale nunca de la columna cero, y por qué el if del borde izquierdo no salta nunca.

  5. Rompe el contador de fotogramas a propósito. Vuelve a meter la línea frames = 0 dentro de la función, encima de frames = frames + 1. Mira cómo el contador se queda en uno mientras la palabra sigue moviéndose perfectamente. Luego averigua por qué a la palabra no le afecta.

Rómpelo a propósito

Cambia los dos puntos de la línea del contador de fotogramas por un signo más, para que quede así:

    overlayPrint(0, 0, "frame " + frames)

Guárdalo. La ventana se cierra, Singe se detiene y la terminal dice:

Error executing function 'onOverlayUpdate':  numbers/numbers.singe:42: attempt to add a 'string' with a 'number'

seguido de varias líneas que empiezan por stack traceback:, que de momento puedes ignorar.

Léelo como te enseñó la lección uno: el archivo, la línea y luego la queja. La línea 42 es la que has cambiado. La queja dice que a Lua le pidieron sumar una cadena a un número, y sumar es cosa de números. + y .. se parecen sobre el papel y hacen trabajos totalmente distintos: el signo más es aritmética, .. es pegamento.

Vale la pena conocer este por el sitio donde ha aparecido. El error de la lección uno detuvo Singe antes de que tu juego llegara a arrancar, porque Lua no podía ni leer el archivo. Este es una línea perfectamente legible que solo falla al ejecutarse, así que la ventana se abrió, el juego funcionó y murió en el primer fotograma. Los dos tipos te dicen el archivo y la línea. En cualquier caso, empieza por ahí.

Lo que has aprendido

  • Una variable es un nombre con un valor detrás, y el valor puede cambiar.

  • = significa «mete el lado derecho en el nombre de la izquierda», no «es igual a».

  • frames = frames + 1 calcula primero el lado derecho y luego lo guarda.

  • +, -, * y / hacen la aritmética que esperas; // divide y tira la fracción.

  • .. une texto, y de paso convierte un número en texto.

  • Una línea dentro de onOverlayUpdate se ejecuta en cada fotograma. Una línea fuera de todas las funciones se ejecuta una vez, antes de que empiece el juego.

  • Todo lo que tenga que recordar algo de un fotograma a otro tiene que vivir fuera.

  • overlayGetWidth y overlayGetHeight te dicen el tamaño de la superficie de dibujo, así que nunca tienes que adivinarlo.

  • overlayClear importa en cuanto algo se mueve.

La próxima vez

La palabra se mueve, pero se mueve sola y nada de lo que hagas le afecta. En la lección tres coges los cuatro bloques if que usaste sin más, aprendes lo que dicen de verdad y los apuntas a las teclas de flecha en lugar de a los bordes de la pantalla. La caja que manejas por la ventana al final de la lección es el jugador del juego que construyes en la lección siete.

Lección 3: Tomar decisiones

La lección terminada

Todo lo que has escrito hasta ahora hace lo mismo en cada fotograma. La palabra de la lección dos se movía quisieras o no, y lo único que la hacía dar la vuelta eran cuatro bloques de código que tuviste que creerte sin más.

Esta lección trata de esos cuatro bloques, como es debido. Al final de ella tu programa hará preguntas, actuará según las respuestas y — como la pregunta más interesante que puede hacer un juego es «¿qué está haciendo el jugador?» — estarás manejando una caja por la ventana con las teclas de flecha. Guarda esa caja. Es el jugador del juego que construyes en la lección siete.

Empieza una carpeta nueva

Una carpeta llamada decisions, dentro un archivo llamado decisions.singe, y Singe -R decisions ejecutándose en una terminal. Igual que la última vez.

Lo que dice de verdad un if

Aquí está el bloque de la lección dos por separado.

if wordX > lastColumn then
    wordX = lastColumn
end

Cuatro partes. La palabra if. Una pregunta. La palabra then. Y un cuerpo de líneas que solo se ejecutan cuando la respuesta a la pregunta es sí, cerrado con end.

La pregunta es wordX > lastColumn, y el > es el que hace el trabajo de verdad. Compara los dos números que tiene a cada lado y da una respuesta que es verdadero o falso. Esas dos palabras no son texto ni son números; son valores por derecho propio, llamados booleanos, y un booleano es lo único que le interesa a un if.

La sangría es la misma idea que en la lección uno: las líneas de dentro van sangradas para que veas de un vistazo qué pertenece al if, y el end se alinea con el if que lo abrió. Lua lo ejecutaría sin los espacios. Tú no podrías leerlo.

Hay seis comparaciones como esta y las usarás todas.

a < b

a es menor que b

a > b

a es mayor que b

a ⇐ b

a es menor o igual que b

a >= b

a es mayor o igual que b

a == b

a es lo mismo que b

a ~= b

a no es lo mismo que b

Las dos últimas son con las que hay que tener cuidado, por motivos distintos.

~= significa «no es igual a». La mayoría de los lenguajes lo escriben !=, y si has visto algún programa antes, tus dedos escribirán != y Lua lo rechazará. La virgulilla está en tu teclado junto al 1 o debajo del #, según dónde vivas.

== son dos signos igual, y no es una errata por uno. Es uno de los errores más comunes en programación, y vale la pena pararse en él un momento.

En la lección dos aprendiste que un signo igual significa mete el lado derecho en el nombre de la izquierda. Eso es algo que haces. Cambia algo.

Dos signos igual significan ¿son iguales estas dos cosas? Eso es una pregunta que haces. No cambia nada, y devuelve verdadero o falso.

lives = 3
if lives == 3 then

La primera línea pone lives a tres. La segunda pregunta si vale tres. Trabajos distintos, símbolos distintos, a un carácter de distancia. Lua te pillará si los confundes, y verás el error que usa al final de esta lección.

Cuando la respuesta es no

Un if solo no hace nada en absoluto cuando la respuesta es falsa. Muchas veces quieres que en ese caso pase otra cosa, y eso es else.

if lives > 0 then
    message = "Ready"
else
    message = "Game Over"
end

Se ejecuta exactamente uno de esos dos cuerpos, nunca los dos, nunca ninguno, así que message siempre acaba guardando una de las dos cadenas y nunca nada.

Cuando hay más de dos posibilidades, elseif las encadena.

if score >= 10000 then
    rank = "ace"
elseif score >= 5000 then
    rank = "pilot"
elseif score >= 1000 then
    rank = "rookie"
else
    rank = "passenger"
end

Lua prueba las preguntas desde arriba y se para en la primera que es verdadera. Una puntuación de 6000 no es mayor que 10000, así que prueba la siguiente, que es verdadera, así que rank pasa a ser pilot y las otras dos preguntas no se llegan a hacer. Eso último importa: el elseif de 1000 también es verdadero para una puntuación de 6000, y nunca se llega a él, y por eso el orden va de mayor a menor.

Todo el bloque necesita exactamente un end, da igual cuántas partes elseif tenga. Es una sola decisión, no cuatro.

Verdadero, falso y nada de nada

No hace falta comparar dos cosas para obtener un booleano. Puedes guardar uno.

paused = false

Es una variable como cualquier otra, y el valor que tiene es el propio booleano false, escrito sin comillas porque no es la palabra «false», es la idea. Lo mismo pasa con true. Una variable que guarda uno de los dos puede ir directamente en un if sin ninguna comparación:

if paused then

Léelo como «si está en pausa». Se entiende mejor que if paused == true, que hace lo mismo dando un rodeo, y los programadores con experiencia te mirarán raro si lo escribes.

Tres palabras unen y dan la vuelta a estas respuestas.

if alive and not shielded then
if coins > 0 or freePlay then

and es verdadero cuando lo son los dos lados. or es verdadero cuando lo es cualquiera de los dos, o los dos. not convierte verdadero en falso y falso en verdadero. Se leen como el inglés y, cosa rara en programación, significan lo mismo que en inglés.

Hay un valor más que conviene conocer, y es el que produce los errores más confusos de tu primer año.

overlayPrint(0, 0, "lives " .. tostring(lives))

Si nunca has metido nada en lives, eso imprime lives nil. Lua no se queja de un nombre que no ha visto nunca; te da nil, que es su palabra para aquí no hay nada. No es cero y no es una cadena vacía. El cero es un número que querías guardar. nil es la ausencia de un valor.

Ya te has encontrado con nil dos veces sin que nadie te lo dijera. frames = frames + 1 sin la línea frames = 0 encima falla porque le pediste a Lua que sumara uno a nada. Y un callback mal escrito también es nil, y por eso un onOverlayUpdate mal escrito te da una ventana negra y ningún error: Singe busca el nombre, no encuentra nada y sigue tan tranquilo con lo suyo.

tostring está en esa línea porque .. no une un booleano ni un nil con nada. Los números te los convierte; estos no. Esa era la promesa del final de la lección dos, y ahora tienes para qué usarlo.

Por último, la regla que lo ata todo, porque if acepta cualquier cosa que le des, no solo verdadero y falso:

En Lua todo es verdadero salvo false y nil.

El cero es verdadero. Una cadena vacía es verdadera. Solo esos dos no lo son, y una vez que lo sabes, if movingLeft then se lee perfectamente tanto si movingLeft guarda true como false, o si nunca le has dado valor.

Leer los controles

Es hora de preguntarle algo al jugador. Para eso hace falta un callback nuevo.

function onInputPressed(what)
    if what == SWITCH_RIGHT then
        boxX = boxX + 10
    end
end

onInputPressed es el segundo callback que escribes, y funciona exactamente como describía la lección uno: tú lo escribes, Singe lo llama. A onOverlayUpdate se le llama con un temporizador. A este se le llama cuando pasa algo — cuando el jugador pulsa cualquier cosa que el motor reconoce.

La diferencia con onOverlayUpdate es la palabra que hay dentro de los paréntesis. Singe tiene que decirte qué control se ha pulsado, así que le da un valor a la función, y what es el nombre con el que has elegido recibirlo. La lección uno llamaba argumentos a las cosas que le pasas a una función; desde dentro, el nombre que recoge uno es un parámetro. El nombre es tuyo: llámalo what, llámalo button, llámalo k. Singe lo rellena igual.

SWITCH_RIGHT es un nombre que el motor ya le ha dado a un valor, como OVERLAY_UPDATED en la lección uno. No tienes que cargar nada para usarlo; Singe los define todos antes de que se ejecute tu script. Hay uno para cada cosa que tiene una recreativa: SWITCH_LEFT, SWITCH_RIGHT, SWITCH_UP, SWITCH_DOWN, de SWITCH_BUTTON1 a SWITCH_BUTTON4, SWITCH_START1, SWITCH_COIN1 y más. La tabla de Constantes del motor de la referencia cubre toda la familia, que va de SWITCH_UP a SWITCH_RECORD. A propósito, no se llaman «la tecla de flecha derecha», porque llega el mismo SWITCH_RIGHT tanto si el jugador ha pulsado una tecla de flecha como si ha empujado un joystick o el stick de un mando. Escribes el juego una vez y funciona con los tres.

Añade ese callback, dale a boxX un valor inicial fuera de las funciones y dibuja algo en boxX. Pulsa la flecha derecha. La caja salta diez píxeles cada vez que la pulsas.

Ha pasado, y está pasando

Mantén pulsada la tecla de flecha. No pasa nada más.

A onInputPressed se le llama una vez, al bajar la tecla, y no otra vez hasta que la sueltas y la vuelves a pulsar. No hay repetición de teclas. Eso es justo lo correcto para algunas cosas — disparar, echar una moneda, elegir una opción de un menú — y justo lo incorrecto para caminar, que tiene que seguir pasando mientras la tecla esté pulsada.

Son dos preguntas realmente distintas. Ha pasado es un evento, y te enteras una vez. Está pasando es un estado, y dura. Singe te avisa de los eventos, y la forma de convertir eventos en estado es recordarlos tú.

Dos callbacks y una variable entre los dos.

movingRight = false


function onInputPressed(what)
    if what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_RIGHT then
        movingRight = false
    end
end

onInputReleased es el tercer callback, y es el reflejo del segundo: Singe lo llama cuando la tecla vuelve a subir, con el mismo valor SWITCH_. Entre los dos consiguen que movingRight diga la verdad sobre lo que está haciendo el dedo del jugador en este momento.

Todavía no se ha movido nada, y de eso se trata. Pulsar y moverse son ahora dos trabajos separados. El movimiento va donde va todo el trabajo de cada fotograma.

function onOverlayUpdate()
    if movingRight then
        boxX = boxX + BOX_SPEED
    end
    ...

Ahora la caja se desliza suavemente mientras la tecla esté pulsada, a una velocidad que controlas tú, y la aritmética vuelve a estar en la única función que se ejecuta sesenta veces por segundo, que es donde debe estar. Esta forma — los eventos ponen indicadores, el fotograma actúa según los indicadores — es como casi todos los juegos manejan sus controles, y la volverás a usar en cada lección que tenga un jugador.

Dibujar una caja

overlayBox recibe dos esquinas: el borde izquierdo y el de arriba del rectángulo, y luego el derecho y el de abajo.

colorForeground(255, 220, 0)
overlayBox(boxX, boxY, boxX + BOX_SIZE, boxY + BOX_SIZE)

Dibuja un contorno, cuatro líneas de un píxel de grosor, no un rectángulo relleno. En las llamadas de dibujo del overlay no hay ningún rectángulo relleno. Cuando más adelante quieras un bloque sólido hay formas de conseguirlo, y la lección nueve tiene la habitual.

Sus números son píxeles, no celdas de carácter. Esto pilla a la gente, porque overlayPrint en la lección dos contaba en celdas de seis por trece píxeles y todo lo demás en Singe cuenta en píxeles. overlayPrint es el raro; el resto de las llamadas de dibujo — overlayBox, overlayLine, overlayCircle, overlayEllipse y overlayPlot — trabajan todas en los mismos píxeles que da overlayGetWidth.

colorForeground pone el color, con tres números de 0 a 255: cuánto rojo, cuánto verde, cuánto azul. Los tres a 255 es blanco, todos a 0 es negro, y (255, 220, 0) es un amarillo cálido. Fíjate en que no es un argumento de overlayBox. Es un ajuste: lo cambias, y todo lo que dibujes después sale en el color nuevo hasta que lo vuelvas a cambiar. overlayPrint vuelve a ser la excepción — la fuente de consola trae sus propios colores de serie y no te hace caso.

Todo junto

BOX_SIZE  = 20
BOX_SPEED = 2

width  = overlayGetWidth()
height = overlayGetHeight()
maxX   = width - BOX_SIZE - 1
maxY   = height - BOX_SIZE - 1

boxX = width // 2
boxY = height // 2

movingLeft  = false
movingRight = false
movingUp    = false
movingDown  = false


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    elseif what == SWITCH_UP then
        movingUp = true
    elseif what == SWITCH_DOWN then
        movingDown = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    elseif what == SWITCH_UP then
        movingUp = false
    elseif what == SWITCH_DOWN then
        movingDown = false
    end
end


function onOverlayUpdate()
    if movingLeft and not movingRight then
        boxX = boxX - BOX_SPEED
    elseif movingRight and not movingLeft then
        boxX = boxX + BOX_SPEED
    end

    if movingUp and not movingDown then
        boxY = boxY - BOX_SPEED
    elseif movingDown and not movingUp then
        boxY = boxY + BOX_SPEED
    end

    if boxX < 0 then
        boxX = 0
    elseif boxX > maxX then
        boxX = maxX
    end

    if boxY < 0 then
        boxY = 0
    elseif boxY > maxY then
        boxY = maxY
    end

    overlayClear()

    if movingLeft or movingRight or movingUp or movingDown then
        colorForeground(255, 220, 0)
    else
        colorForeground(80, 160, 255)
    end

    overlayBox(boxX, boxY, boxX + BOX_SIZE, boxY + BOX_SIZE)
    overlayPrint(0, 0, "x " .. boxX .. "  y " .. boxY)
    return OVERLAY_UPDATED
end

Hay cuatro cosas ahí dentro que merecen una segunda mirada.

movingLeft and not movingRight está ahí porque un jugador puede mantener pulsadas las dos flechas a la vez. Sin el not, las dos se pelearían y la caja temblaría o se iría hacia un lado; con él, si mantienes pulsadas las dos no gana ninguna y la caja se queda quieta, que es lo que espera un jugador.

maxX se calcula una vez arriba, con overlayGetWidth como en la lección dos, y el - 1 es porque el último píxel de la superficie es uno menos que su ancho. Quita el - 1 y el borde derecho de la caja se sale de la superficie y desaparece, porque Singe tira sin quejarse todo lo que dibujas fuera del overlay.

Los bloques que limitan la posición usan elseif en lugar de dos bloques if separados. La caja no puede salirse por el borde izquierdo y por el derecho a la vez, así que hacer la segunda pregunta cuando la primera era verdadera es trabajo perdido.

Y la decisión del color es un if cuyo único trabajo es elegir un valor. Amarillo mientras el jugador está haciendo algo, azul mientras no, que es una forma gratis de ver que tu manejo de la entrada funciona de verdad.

Pruébalo

  1. Cambia la velocidad. BOX_SPEED = 1 y BOX_SPEED = 8. Con ocho, fíjate en lo que hace el límite cuando empujas la caja contra una esquina.

  2. Muestra tus indicadores. Añade una línea a onOverlayUpdate: overlayPrint(0, 1, "left " .. tostring(movingLeft)). Mantén pulsada y suelta la flecha izquierda y mira cómo cambia. Luego quita el tostring y lee el error que te da Lua.

  3. Que vaya más rápido con un botón pulsado. Añade un indicador running controlado por SWITCH_BUTTON1 en los dos callbacks de entrada, y usa un if en onOverlayUpdate para moverte el doble de BOX_SPEED mientras sea verdadero.

  4. Marca el centro. Dibuja una segunda caja, pequeña, en el centro de la ventana, que cambie de color cuando la caja del jugador se solape con ella. Necesitarás and para unir cuatro comparaciones, y es más difícil de lo que parece. Que te salga un poco mal es normal; la lección once lo hace como es debido.

  5. Quita lo de soltar. Borra toda la función onInputReleased y ejecútalo. La caja da un paso y luego no para nunca. Averigua qué línea no se alcanza nunca ahora.

Rómpelo a propósito

Busca el bloque que limita la posición y cambia el < de su primera comparación por un solo signo igual, para que quede así:

    if boxX = 0 then

Guárdalo. La ventana se queda ahí vacía y la terminal dice:

Error running script:  decisions/decisions.singe:57: 'then' expected near '='

Este es el error del que avisaba toda la sección sobre ==, y el mensaje es un buen ejemplo de un error que es totalmente exacto y totalmente inútil si te lo tomas al pie de la letra. Lua no te está pidiendo que añadas la palabra then. Lua llegó hasta if boxX, esperaba a continuación una comparación o un then, y se encontró =, que no puede ser ninguna de las dos cosas.

Siempre que veas 'then' expected después de un if, busca un = simple que debería ser doble. Casi siempre es eso.

Fíjate en dónde ha aparecido este: el juego ni siquiera llegó a empezar, igual que con la cadena sin terminar de la lección uno, porque Lua no podía leer el archivo. El error del contador de fotogramas de la lección dos pasó durante la ejecución. Los errores en la forma de tu código te paran antes de que empiece el juego. Los errores en lo que hace tu código esperan a que se ejecute.

Lo que has aprendido

  • if question then …​ end ejecuta un cuerpo solo cuando la respuesta es verdadera.

  • else da el otro caso, y elseif encadena más; gana la primera pregunta verdadera y las demás no se llegan a hacer.

  • Las comparaciones son <, >, ⇐, >=, == y ~=.

  • = mete un valor en un nombre. == pregunta si dos cosas son iguales.

  • true y false son valores, y puedes guardarlos en variables.

  • and, or y not unen y dan la vuelta a esas respuestas.

  • nil es lo que obtienes de un nombre al que nunca has dado valor, y no es cero.

  • Todo es verdadero salvo false y nil.

  • onInputPressed y onInputReleased son callbacks que Singe llama con un valor SWITCH_ cuando el jugador pulsa o suelta un control.

  • Una pulsación es un evento y ocurre una vez; guarda el estado en una variable y actúa según él en cada fotograma.

  • overlayBox dibuja un contorno en píxeles, y colorForeground es un ajuste, no un argumento.

La próxima vez

Una caja es fácil. Cien estrellas no lo son, al menos no tal como has escrito las cosas hasta ahora, porque escribir cien líneas overlayPlot no es el plan ideal para una tarde. La lección cuatro trata del bucle: decirle al ordenador que haga lo mismo muchas veces, con algo distinto en cada vuelta, que es lo que hace posible llenar una pantalla de cualquier cosa.

Lección 4: Otra vez

La lección terminada

Has dibujado una palabra y una caja. Un juego necesita cien cosas: estrellas, ladrillos, balas, las filas de un menú. Escribir cien líneas no es la respuesta, y si lo fuera, tendrías que escribir otras cien en cuanto quisieras ciento una.

Esta lección es la respuesta. Al final de ella, un campo de estrellas irá bajando lentamente por tu ventana, y todas y cada una las dibujarán las mismas cinco líneas de código.

Empieza una carpeta nueva

Una carpeta llamada repeating, dentro un archivo llamado repeating.singe, y Singe -R repeating ejecutándose en una terminal.

Cuarenta puntos

Escribe esto y ejecútalo.

function onOverlayUpdate()
    overlayClear()
    colorForeground(255, 255, 255)

    for star = 1, 40 do
        overlayPlot(star * 8, 100)
    end

    return OVERLAY_UPDATED
end

Una fila de cuarenta puntos blancos que cruza el centro de la ventana.

overlayPlot es la llamada de dibujo más sencilla que hay: pone un píxel en el color de primer plano actual, y es justo lo que pide una estrella. Todo lo interesante aquí son las tres líneas que la rodean.

    for star = 1, 40 do

Eso dice: haz lo que sigue cuarenta veces, y en cada vuelta, star guarda un número distinto — uno la primera vez, dos la segunda, cuarenta la última. Los dos extremos cuentan, así que 1, 40 son de verdad cuarenta vueltas y no treinta y nueve. Esta forma es un bucle, y este en concreto es un bucle for numérico.

star es un nombre que te inventas, igual que te inventaste frames en la lección dos, y el bucle lo rellena por ti. No le das valor tú, y no deberías cambiarlo dentro del bucle. Solo existe entre el for y su end; pide su valor después y obtendrás nil.

El do es obligatorio y es fácil olvidarlo. Si lo quitas, Lua dice 'do' expected near, seguido de lo que haya encontrado en su lugar, que será lo primero de la línea siguiente.

        overlayPlot(star * 8, 100)

El cuerpo. Esto es lo que se ejecuta cuarenta veces, y es la misma línea cada vez — lo que cambia es star, así que el primer punto cae en una x de 8, el segundo en 16 y el último en 320. Un bucle solo sirve de algo cuando el cuerpo hace algo con el número del bucle, y lo primero que buscarás siempre es hacer cuentas con él.

El cuerpo va sangrado un paso más que el for, por el mismo motivo por el que has sangrado todo lo demás hasta ahora.

    end

Cierra el bucle. Ya conoces tres cosas que necesitan un end: function, if y for. Todas funcionan igual, se anidan unas dentro de otras, y la sangría es cómo llevas la cuenta de qué end va con qué.

Contar de más de uno en uno

El bucle cuenta de uno en uno salvo que le digas otra cosa. Añade un tercer número y contará de ese en ese.

    for x = 0, overlayGetWidth() - 1, 10 do
        overlayPlot(x, 100)
    end

Léelo como desde, hasta, de cuánto en cuánto. Este va 0, 10, 20, y así sucesivamente, y se para en el último píxel de la superficie o antes, lo que dibuja una línea de puntos de lado a lado sea cual sea el tamaño de la ventana. Es la misma fila de puntos de antes, descrita según dónde van y no según cuántos hay.

El paso puede ser negativo, y entonces cuenta hacia atrás.

    for countdown = 10, 1, -1 do

Diez, nueve, ocho, hasta uno. Con un paso negativo el segundo número es el suelo en vez del techo, que es lo que esperarías, y equivocarse de signo da un bucle que no se ejecuta nunca: for i = 10, 1 do sin paso cuenta hacia arriba desde diez hacia uno, ya ha pasado el final antes de empezar y no hace nada. Ningún error, ninguna salida. Si un bucle tuyo parece no ejecutarse nunca, comprueba primero la dirección.

El paso también puede ser una fracción, aunque lo querrás menos a menudo de lo que crees.

Un bucle dentro de otro

El cuerpo de un bucle es código normal, y el código normal puede contener un bucle.

    for row = 0, overlayGetHeight() - 1, 20 do
        for column = 0, overlayGetWidth() - 1, 20 do
            overlayPlot(column, row)
        end
    end

Eso dibuja una cuadrícula de puntos por toda la ventana. Ponlo en tu onOverlayUpdate en lugar de la fila y míralo, porque vale la pena tener claro cómo se ejecuta ahora, y no en la lección once, cuando algo dependa de ello.

El bucle de fuera se ejecuta una vez con row a 0. Dentro de eso, todo el bucle de dentro se ejecuta de principio a fin — dieciocho columnas, dieciocho puntos, una fila de la cuadrícula. Solo cuando el bucle de dentro ha terminado pasa el de fuera a row a 20 y vuelve a ejecutar entero el bucle de dentro.

Así que el cuerpo del bucle de dentro se ejecuta dieciocho por doce veces, que son doscientas dieciséis, en doce vueltas del de fuera. Esa multiplicación es la razón de que los bucles anidados sean la forma de llenar un rectángulo de cualquier cosa, y también la razón de que debas echar un vistazo a los números antes de anidar tres.

Fíjate en que la posición de cada punto necesita las dos variables del bucle: column para lo horizontal y row para lo vertical. Ese es el patrón. Si el cuerpo de dentro solo usa la variable de dentro, el bucle de dentro está dibujando lo mismo una y otra vez en el mismo sitio, y has escrito una forma lenta de hacerlo una vez.

Cuando no sabes cuántas veces

Un bucle for necesita saber cuántas veces antes de empezar. A veces no lo sabes, y entonces quieres el otro tipo.

    x = 0
    while x < overlayGetWidth() do
        overlayPlot(x, 100)
        x = x + 10
    end

Un bucle while comprueba una pregunta antes de cada vuelta, exactamente la pregunta que haría un if, y sigue mientras la respuesta sea verdadera. Cuando la respuesta es falsa, se para y continúa con la línea que va después del end. Si la respuesta es falsa ya la primera vez, el cuerpo no se ejecuta nunca.

Ese ejemplo dibuja la misma línea de puntos que el for con un paso de diez, y necesita tres líneas para hacer lo que for hacía en una, así que usa for para eso. Esta es la diferencia que decide:

  • Usa for cuando sabes el número de vueltas antes de empezar. Cuarenta estrellas. Uno de cada diez píxeles a lo ancho. Cada fila de una cuadrícula.

  • Usa while cuando estás esperando a que algo se haga verdadero y no puedes decir de antemano cuánto tardará. Repartir cartas hasta que se acabe la baraja. Seguir preguntando hasta que el jugador escriba algo válido. Recorrer una lista hasta encontrar lo que buscabas.

Un while tiene tres partes y tienes que escribir las tres tú: preparar la variable antes del bucle, comprobarla en el while y cambiarla dentro del cuerpo. El bucle for hace las tres por ti, y por eso es el que debes usar cuando encaja. Olvida la tercera parte en un while y la pregunta no deja nunca de ser verdadera, que es lo que harás a propósito al final de esta lección.

Una estrella hecha de su propio número

Ahora el campo de estrellas, y un problema que da forma al resto de la primera parte.

Cada estrella necesita su propia x y su propia y, y no tienes forma de guardar cien variables separadas — escribir star1X, star2X y así hasta cien es peor que escribir las cien líneas que querías evitar. Así que no las guardes. Calcula cada una a partir de lo único que hace a una estrella distinta de sus vecinas: su número.

        starX = (star * 37) % width

El % es el último de los operadores aritméticos y es el resto: lo que sobra después de dividir. Quince entre cuatro es tres y sobran tres, así que 15 % 4 es 3. Su propiedad útil es que el resultado nunca puede ser tan grande como el número de la derecha, así que el resto entre width siempre es una posición en algún sitio de la pantalla, por mucho que crezca el lado izquierdo.

La estrella 1 va a 37, la 5 a 185, la 10 a 10 — 370 ha pasado de 360, ha dado la vuelta y ha vuelto a aparecer por la izquierda. Se elige treinta y siete porque no comparte ningún factor con 360, que es lo que impide que las estrellas caigan en rayas ordenadas; prueba con 36 y verás el problema enseguida.

La deriva hacia abajo es el mismo truco con un número que crece con el tiempo.

drift = 0


function onOverlayUpdate()
    drift = drift + 1
    ...
        starY = (star * 61 + math.floor(drift * layer * 0.5)) % height

drift vive fuera de la función y sube en cada fotograma, exactamente igual que frames en la lección dos. Sumarlo a la y de cada estrella mueve todo el campo hacia abajo a la vez, y el % devuelve arriba una estrella que se cae por abajo, para siempre, gratis.

math.floor tira la fracción de un número y devuelve la parte entera que queda por debajo: math.floor(7.9) es 7. La lección dos señaló que Singe hace eso por ti cuando dibuja, y es verdad, pero hacerlo tú significa que el número con el que trabajas es el número que aparece en pantalla. Eso importará en la lección siete, cuando dos cosas tengan que ponerse de acuerdo sobre si se están tocando.

Fíjate en que ese layer es una segunda variable de bucle. Las estrellas se dibujan con un bucle dentro de otro, y el de fuera no es una fila de una cuadrícula sino una distancia: tres capas de estrellas, cada una con su propia velocidad y su propio brillo, que es lo que hace que un campo plano de puntos parezca tener profundidad.

El azar

Las estrellas titilan. Titilar significa un brillo un poco distinto en cada fotograma, y «un poco distinto» es math.random.

        shade = math.random(60, 90) + layer * 55
        colorForeground(shade, shade, shade)

math.random(60, 90) devuelve un número entero de 60 a 90, los dos incluidos, elegido de nuevo cada vez que la llamas. Llámala sin ningún argumento y obtendrás en cambio una fracción entre 0 y 1, que es la forma que debes usar cuando quieres que algo pase una vez de cada cinco. No tienes que preparar el generador; Lua lo hace cuando arranca Singe.

Sumar layer * 55 saca las capas cercanas del rango oscuro, así que las estrellas lejanas siguen débiles y las cercanas son casi blancas. El mismo rojo, verde y azul, como explicaba la lección tres, es un tono de gris.

Como shade se elige otra vez en cada fotograma para cada estrella, cada estrella parpadea por su cuenta, lo que a sesenta fotogramas por segundo se ve como un titileo y no como un fallo.

Todo junto

LAYERS          = 3
STARS_PER_LAYER = 40
ACROSS_STEP     = 37
DOWN_STEP       = 61
LAYER_SHIFT     = 13
LAYER_SPEED     = 0.5
LAYER_BRIGHT    = 55

width  = overlayGetWidth()
height = overlayGetHeight()

drift = 0


function onOverlayUpdate()
    drift = drift + 1
    overlayClear()

    for layer = 1, LAYERS do
        for star = 1, STARS_PER_LAYER do
            starX = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
            starY = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
            shade = math.random(60, 90) + layer * LAYER_BRIGHT
            colorForeground(shade, shade, shade)
            overlayPlot(starX, starY)
        end
    end

    return OVERLAY_UPDATED
end

Ciento veinte estrellas, dibujadas por cinco líneas, y el archivo es más corto que el de la lección tres.

También es hasta donde llega este enfoque, y vale la pena ser sincero sobre el porqué mientras lo tienes delante. Cada estrella de ahí es una fórmula. De una estrella no se recuerda nada: no puedes hacer una más brillante que su vecina y que se quede así, no puedes derribar una del cielo y no puedes hacer que el jugador recoja una, porque no hay ningún sitio donde apuntar que le ha pasado algo. La estrella diecisiete no es una cosa. Es un número que pasa un momento por una variable llamada star.

En cuanto quieres cien cosas que recuerden cada una algo propio, necesitas un sitio donde poner cien grupos de datos. Eso es la lección seis, y el campo de estrellas es la razón de que exista.

Pruébalo

  1. Más y menos. Prueba STARS_PER_LAYER = 200, luego 4. Luego LAYERS = 8 y fíjate en lo que hace layer * LAYER_BRIGHT con shade cuando el número de capa se hace grande. Los números que admite colorForeground llegan hasta 255.

  2. Cambia el espaciado. Pon ACROSS_STEP a 36 y ejecútalo. Las estrellas caen en rayas, porque 36 cabe en 360 exactamente diez veces. Vuelve a ponerlo a 37 y prueba 71 y 90.

  3. Quita el titileo. Cambia la línea de math.random por un simple shade = layer * 70 y compara. Decide cuál te gusta más; no hay respuesta correcta, y darte cuenta de que tienes una preferencia es parte del trabajo.

  4. Haz que caigan hacia arriba. Un carácter.

  5. Dibuja también la cuadrícula. Vuelve a poner el bucle de la cuadrícula anidada de antes, después de las estrellas, en un color oscuro. Dos bucles anidados en una función, dibujando dos cosas distintas, y el segundo no molesta al primero.

Rómpelo a propósito

Hasta ahora, todos los errores han sido un mensaje. Este no, y precisamente por eso deberías conocerlo cuando lo estás esperando.

Pon esto en tu onOverlayUpdate, justo debajo de overlayClear(), ejecútalo y lee el párrafo siguiente antes de hacer nada más.

    x = 0
    while x < width do
        overlayPlot(x, 100)
    end

Falta la línea que hace avanzar x, así que x se queda en cero, así que x < width no deja nunca de ser verdadero. El bucle da vueltas para siempre, pintando el mismo píxel, y está dentro de onOverlayUpdate, así que onOverlayUpdate no vuelve nunca. Singe está esperando a tu función. No puede dibujar, no puede leer el teclado y no puede salir.

Lo que ves es una ventana que deja de moverse. Esc no hace nada. Q no hace nada. Tampoco se imprime nada.

Ve a la terminal desde la que arrancaste Singe y pulsa Ctrl y C a la vez. Singe detiene tu bucle y te dice dónde estaba:

Stopped:  the script did not return, and Singe was asked to quit.
stack traceback:
	repeating/repeating.singe:20: in function 'onOverlayUpdate'

Puede que lo diga dos veces, con unos segundos de diferencia, antes de salir. Con una basta. La línea 20 es el end de tu while, que es donde el bucle estaba dando vueltas cuando lo detuviste. Quita el bucle, guarda y vuelve a arrancar Singe.

Eso es un informe, no un error. Nada se quejó hasta que lo pediste, porque, para el ordenador, no ha ido nada mal. Pediste un bucle que se ejecutara mientras x fuera menor que el ancho, y eso es exactamente lo que tienes. Este es el único tipo de error en el que los mensajes de error no te pueden ayudar, y la cura es una costumbre: cada vez que escribas un while, escribe la línea que cambia la variable antes de escribir nada más en el cuerpo.

Lo que has aprendido

  • for name = first, last do …​ end ejecuta su cuerpo una vez por cada número desde el primero hasta el último, los dos incluidos.

  • Un tercer número es el paso, y puede ser negativo para contar hacia atrás.

  • La variable del bucle solo existe dentro del bucle, y el cuerpo debería usarla.

  • for necesita un do, y todo bucle necesita un end.

  • Un bucle dentro de otro ejecuta el bucle de dentro entero en cada vuelta del de fuera, y así es como llenas un rectángulo.

  • while question do …​ end repite mientras la pregunta sea verdadera, y tienes que cambiar algo en el cuerpo tú mismo.

  • Usa for cuando sabes cuántas veces, y while cuando estás esperando a que algo se haga verdadero.

  • % es el resto, y mantiene un número que crece dentro de un rango.

  • math.random(a, b) da un número entero de a a b; math.floor tira la fracción.

  • Un bucle que no termina nunca congela todo el juego sin ningún mensaje de error, y Ctrl y C en la terminal es como sales.

La próxima vez

Vuelve a mirar ese onOverlayUpdate. Dibuja estrellas, calcula posiciones, elige colores, y empieza a ser una función que hace cuatro trabajos en lugar de uno. En la lección cinco escribes tus propias funciones, les das argumentos igual que los reciben las funciones de Singe y les sacas respuestas — y el campo de estrellas se convierte en una línea que dice drawStars().

Lección 5: Tus propias funciones

La lección terminada

La lección cuatro terminó con un aviso sobre tu propio programa: onOverlayUpdate calcula dónde van ciento veinte estrellas, decide lo brillante que es cada una, las dibuja y cuenta la deriva, y es una sola función haciendo cuatro trabajos. Y está a punto de recibir un quinto, porque un campo de estrellas sin nada delante no es un juego.

En esta lección lo desmontas. Escribirás tus propias funciones — funciones de las que Singe nunca ha oído hablar y que nunca llamará — y les pasarás el trabajo. Al final, todo el campo de estrellas es una línea que dice drawStars(), vuelve a haber una nave en la parte de abajo de la pantalla, y el programa se lee mejor que cuando hacía menos.

Empieza una carpeta nueva

Una carpeta llamada functions, dentro un archivo llamado functions.singe, y Singe -R functions ejecutándose en una terminal.

Copia en él el programa terminado de la lección cuatro. Aquí lo tienes, sin cambios, y vale la pena ejecutarlo una vez antes de tocar nada:

LAYERS          = 3
STARS_PER_LAYER = 40
ACROSS_STEP     = 37
DOWN_STEP       = 61
LAYER_SHIFT     = 13
LAYER_SPEED     = 0.5
LAYER_BRIGHT    = 55

width  = overlayGetWidth()
height = overlayGetHeight()

drift = 0


function onOverlayUpdate()
    drift = drift + 1
    overlayClear()

    for layer = 1, LAYERS do
        for star = 1, STARS_PER_LAYER do
            starX = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
            starY = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
            shade = math.random(60, 90) + layer * LAYER_BRIGHT
            colorForeground(shade, shade, shade)
            overlayPlot(starX, starY)
        end
    end

    return OVERLAY_UPDATED
end

Tres capas de estrellas bajando por la ventana a tres velocidades. Nada de la primera mitad de esta lección cambia lo que ves. Todo cambia cómo se lee el programa.

Un trabajo, un nombre

Empieza por las dos líneas que ponen una estrella en la pantalla. Encima de onOverlayUpdate, añade esto:

function drawStar(x, y, shade)
    colorForeground(shade, shade, shade)
    overlayPlot(x, y)
end

Luego, en el bucle de dentro, borra esas dos líneas y llama a la función en su lugar:

        for star = 1, STARS_PER_LAYER do
            starX = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
            starY = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
            shade = math.random(60, 90) + layer * LAYER_BRIGHT
            drawStar(starX, starY, shade)
        end

Guarda. La imagen es la misma.

Ya habías escrito funciones antes — onOverlayUpdate es una, y también lo son onInputPressed y onInputReleased de la lección tres — pero son callbacks. Tú las escribes y Singe las llama. drawStar es distinta. Singe no ha oído hablar de ella nunca. Se ejecuta porque tú has escrito su nombre y los paréntesis, igual que llamas a overlayPlot, y nada en el mundo la ejecutará si no lo haces tú.

Ese es todo el truco. A partir de aquí, cuando te descubras pensando «y ahora dibuja una estrella», puedes escribir «dibuja una estrella» y decirlo en serio.

Un parámetro es un nombre, no una cosa

Vuelve a mirar la primera línea de drawStar.

function drawStar(x, y, shade)

Los tres nombres que hay entre los paréntesis son parámetros. Un parámetro es un nombre que la función usa para lo que le haya dado quien la llama. Cuando escribes drawStar(starX, starY, shade), Lua pone en x lo que haya en starX, en y lo que haya en starY, en shade lo que haya en shade, y luego ejecuta la función.

Los nombres no tienen nada que ver entre sí. El número de quien llama se llama starX ahí fuera y x aquí dentro, y funcionaría exactamente igual si lo llamaras across o banana. Dentro de la función solo existen los nombres que hay entre los paréntesis, y guardan copias de lo que ha entrado.

Aquí es donde por fin tienen sentido los paréntesis vacíos de la lección uno.

function onOverlayUpdate()

Nada entre los paréntesis significa que no hay parámetros: el motor no tiene nada que decirle a esta función, así que no hay nada a lo que poner nombre. Compárala con el callback que escribiste en la lección tres.

function onInputPressed(what)

Un parámetro, llamado what. El motor tiene algo que decirle a esta — qué control se ha pulsado — así que hay un nombre donde recogerlo. Llevas usando un parámetro desde la lección tres.

Un parámetro es de verdad la copia propia de la función, y vale la pena comprobarlo por ti mismo una vez. Escribe esto, llámalo desde onOverlayUpdate y quítalo otra vez después:

function half(number)
    number = number // 2
    return number
end

Llámala como half(drift). La función divide entre dos su number y devuelve el resultado, y drift, ahí fuera en onOverlayUpdate, sigue contando como si no hubiera pasado nada. Una función no puede alargar la mano y cambiar las variables de quien la llama a través de un parámetro. Recibe una copia, y lo que haga con la copia es asunto suyo.

Devolver una respuesta

half ha hecho algo que no hacían las funciones que has escrito hasta ahora: ha dado una respuesta. Es la última línea.

    return number

return devuelve un valor a quien llamó a la función, y la llamada se convierte en ese valor. Escribe smaller = half(drift) y Lua ejecuta half, coge lo que half ha devuelto y lo mete en smaller. Conociste return en la lección uno, donde onOverlayUpdate devuelve OVERLAY_UPDATED para responder a la pregunta de Singe sobre si ha cambiado algo. Es la misma palabra haciendo el mismo trabajo, solo que ahora el que pregunta eres tú.

La línea del brillo está pidiendo a gritos ser una función con respuesta. Añade esta:

function shadeFor(layer)
    return math.random(60, 90) + layer * LAYER_BRIGHT
end

Todo el cuerpo es un return, lo que es normal en una función pequeña. Ahora el bucle de dentro puede darle la respuesta directamente a drawStar sin un nombre por medio:

            drawStar(starX, starY, shadeFor(layer))

Una llamada dentro de otra llamada. Lua calcula primero la de dentro, recibe un número de shadeFor y le pasa ese número a drawStar como tercer argumento. Ya has escrito algo así sin darte cuenta: el math.floor(drift * layer * LAYER_SPEED) de la lección cuatro es una llamada cuya respuesta se usa en el acto, en medio de una cuenta más grande.

Dos respuestas a la vez

Las dos líneas de la posición son más difíciles, porque son dos números que se calculan juntos y tendrías que elegir uno para devolverlo. En la mayoría de los lenguajes una función puede devolver un valor, y sacarle dos es un engorro. Lua te deja devolver tantos como quieras.

function starAt(star, layer)
    local x = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
    local y = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
    return x, y
end

Recoges las respuestas poniendo dos nombres a la izquierda, separados por una coma:

            local x, y = starAt(star, layer)

El primer valor va al primer nombre, el segundo al segundo. Si pides menos nombres de los que devuelve la función, los valores que sobran se tiran: local x = starAt(star, layer) te da el número horizontal y pierde el vertical, sin ninguna queja. Si pides más nombres que valores hay, los que sobran son nil.

Olvídate de la palabra local de esos dos bloques un minuto más. Tiene una sección propia más adelante, y es la importante.

El campo de estrellas en una línea

El bucle de dentro tiene ahora tres líneas cortas, y todas tratan de una capa de estrellas. Eso es un trabajo con nombre.

function drawLayer(layer)
    for star = 1, STARS_PER_LAYER do
        local x, y = starAt(star, layer)
        drawStar(x, y, shadeFor(layer))
    end
end

Y el bucle de fuera también es un trabajo con nombre:

function drawStars()
    for layer = 1, LAYERS do
        drawLayer(layer)
    end
end

Funciones que llaman a funciones que llaman a funciones, tres niveles, y cada una son tres o cuatro líneas que puedes tener en la cabeza de una vez. Ahora onOverlayUpdate puede decir lo que es un fotograma:

function onOverlayUpdate()
    drift = drift + 1
    overlayClear()
    drawStars()
    return OVERLAY_UPDATED
end

Esa es la promesa que hizo la lección cuatro al final, cumplida.

Vuelve a poner la nave

Ahora el quinto trabajo, el que habría puesto patas arriba el antiguo onOverlayUpdate. Recupera la caja que manejabas en la lección tres, esta vez como una nave cerca de la parte de abajo de la pantalla que solo se mueve a izquierda y derecha.

Necesita algunos valores propios, arriba con los demás, y los dos callbacks de entrada de la lección tres sin las ramas de arriba y abajo:

PLAYER_WIDTH  = 20
PLAYER_HEIGHT = 6
PLAYER_SPEED  = 3
PLAYER_MARGIN = 6

playerX     = width // 2
playerY     = height - PLAYER_HEIGHT - PLAYER_MARGIN
movingLeft  = false
movingRight = false
function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end

Dibujarla son dos líneas, así que es una función:

function drawPlayer()
    colorForeground(80, 255, 120)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH, playerY + PLAYER_HEIGHT)
end

Moverla es donde la lección da sus frutos. En la lección tres, mantener la caja en la pantalla costaba cuatro líneas de if y elseif por cada dirección. Esa idea — mantener un número entre un mínimo y un máximo — tiene nombre, y el nombre es clamp:

function clamp(value, low, high)
    if value < low then
        return low
    end
    if value > high then
        return high
    end
    return value
end

Tres returns, y como mucho ocurre uno, porque return no solo devuelve una respuesta: detiene la función en seco. No se ejecuta nada de lo que va después. Si el valor está por debajo del mínimo, devuelve el mínimo y para. Si está por encima del máximo, devuelve el máximo y para. Si no, devuelve lo que ha entrado.

function movePlayer()
    if movingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if movingRight then
        playerX = playerX + PLAYER_SPEED
    end
    playerX = clamp(playerX, 0, width - PLAYER_WIDTH - 1)
end

Una función que termina sin un return no devuelve nada, que es nil. Eso es lo correcto para drawPlayer y movePlayer, a las que se llama para hacer algo y no para responder algo. Es un fallo en una función como clamp: quita ese último return value y todas las posiciones del medio del rango vuelven como nil.

Dónde viven los nombres

Todos los nombres que has creado desde la lección dos han sido globales. Un nombre global pertenece a todo el programa: drift, playerX y LAYERS los puede leer y escribir cualquier función del archivo, en cualquier momento, y siguen ahí mientras dure el juego.

Eso suena cómodo, y con seis nombres lo es. El problema empieza con sesenta. Cada nombre global es un nombre que todo el programa ha acordado reservar, así que cuando alguna otra función quiere un sitio donde guardar una posición horizontal y también lo llama starX, los dos son la misma caja, y cada uno escribe encima del número del otro. Cuando un nombre global guarda algo que está mal, cualquier cosa del archivo podría haberlo puesto ahí, y averiguar cuál significa leerlo entero.

La cura es un nombre local. Pon la palabra local delante de un nombre la primera vez que lo uses, y el nombre solo existirá dentro de la function, el bucle o el if donde se escribió.

function starAt(star, layer)
    local x = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
    local y = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
    return x, y
end

Aquí, x e y no son asunto de nadie más. Otra función puede tener su propia x y las dos no se encuentran nunca. Cuando la x de starAt está mal, las tres líneas de arriba son las únicas tres que pueden haberlo hecho. Sin la palabra local, esas dos líneas estarían creando sin hacer ruido dos nombres globales más, que es exactamente lo que han sido starX y starY todo este tiempo.

Ahora viene la parte que sorprende a todo el mundo. Escribe esta función y pon una línea en onOverlayUpdate que te enseñe lo que devuelve:

function countUp()
    local counted = 0
    counted = counted + 1
    return counted
end
    overlayPrint(0, 0, "Count: " .. countUp())

Count: 1, y se queda en Count: 1 mientras dura el juego, aunque a esa función se la llama sesenta veces por segundo y suma uno cada vez. Un nombre local se crea de nuevo cuando empieza la función y desaparece cuando la función termina, así que counted nace valiendo 0, pasa a 1 y muere, sesenta veces por segundo, para siempre. Un nombre local no recuerda. Vuelve a quitar las dos cosas cuando lo hayas visto.

No es un defecto, es justo la idea: a un nombre local no lo puede envenenar la llamada anterior, porque de la llamada anterior no queda nada. Cuando sí necesitas recordar algo entre llamadas — drift y playerX tienen que recordar — el nombre tiene que vivir fuera de todas las funciones. Ponlo arriba del archivo con local delante:

local drift   = 0
local playerX = width // 2

Un local escrito arriba del archivo, fuera de todas las funciones, vive lo mismo que el script y lo pueden ver todas las funciones que hay debajo. Esa última palabra importa: debajo. Un nombre local existe desde su propia línea hacia abajo, así que una función escrita encima de la línea que lo crea no lo puede ver. Lo mismo pasa con las propias funciones en cuanto las marcas como local, y por eso el script terminado está en el orden en que está: primero los valores, luego tus funciones, y los callbacks al final.

Recorre ahora todo el archivo y pon local delante de cada nombre que hayas creado — las constantes en mayúsculas, width y height, drift, los cuatro valores del jugador y cada una de tus funciones. Tres nombres no lo llevan: onInputPressed, onInputReleased y onOverlayUpdate tienen que seguir siendo globales, porque Singe los encuentra por su nombre y un nombre local es invisible desde fuera del archivo.

Sé sincero sobre lo que los nombres locales no arreglan. Si escribes mal un nombre al que le estás asignando algo — movinLeft = true en lugar de movingLeft = true — Lua no se queja. Crea un nombre global nuevecito con tu errata como nombre, le da valor y deja en paz el de verdad. No se mueve nada, no sale ningún error, y te pasas diez minutos mirándolo. Los nombres locales no te salvarán de esa. Leer el nombre dos veces, sí.

Todo junto

Aquí está el programa terminado, con todas las piezas de la lección.

local LAYERS          = 3
local STARS_PER_LAYER = 40
local ACROSS_STEP     = 37
local DOWN_STEP       = 61
local LAYER_SHIFT     = 13
local LAYER_SPEED     = 0.5
local LAYER_BRIGHT    = 55

local PLAYER_WIDTH  = 20
local PLAYER_HEIGHT = 6
local PLAYER_SPEED  = 3
local PLAYER_MARGIN = 6

local width  = overlayGetWidth()
local height = overlayGetHeight()

local drift       = 0
local playerX     = width // 2
local playerY     = height - PLAYER_HEIGHT - PLAYER_MARGIN
local movingLeft  = false
local movingRight = false


local function clamp(value, low, high)
    if value < low then
        return low
    end
    if value > high then
        return high
    end
    return value
end


local function shadeFor(layer)
    return math.random(60, 90) + layer * LAYER_BRIGHT
end


local function starAt(star, layer)
    local x = (star * ACROSS_STEP + layer * LAYER_SHIFT) % width
    local y = (star * DOWN_STEP + math.floor(drift * layer * LAYER_SPEED)) % height
    return x, y
end


local function drawStar(x, y, shade)
    colorForeground(shade, shade, shade)
    overlayPlot(x, y)
end


local function drawLayer(layer)
    for star = 1, STARS_PER_LAYER do
        local x, y = starAt(star, layer)
        drawStar(x, y, shadeFor(layer))
    end
end


local function drawStars()
    for layer = 1, LAYERS do
        drawLayer(layer)
    end
end


local function drawPlayer()
    colorForeground(80, 255, 120)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH, playerY + PLAYER_HEIGHT)
end


local function movePlayer()
    if movingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if movingRight then
        playerX = playerX + PLAYER_SPEED
    end
    playerX = clamp(playerX, 0, width - PLAYER_WIDTH - 1)
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end


function onOverlayUpdate()
    drift = drift + 1
    overlayClear()
    movePlayer()
    drawStars()
    drawPlayer()
    return OVERLAY_UPDATED
end

Hay dos cosas que vale la pena señalar antes de seguir.

local function drawStar(x, y, shade) marca la propia función como local. Tus funciones son nombres como cualquier otro, y pertenecen solo a este archivo. Los tres callbacks siguen siendo globales para que Singe pueda encontrarlos.

Y onOverlayUpdate son ahora seis líneas que dicen lo que es un fotograma: contar la deriva, limpiar la pantalla, mover al jugador, dibujar el cielo, dibujar al jugador, listo. Hace cinco trabajos nombrando cinco cosas que hacen un trabajo cada una, que es la forma de todos los bucles de juego que escribirás.

Una función es el nombre de una idea

A clamp se la llama una vez. Sacarla no ha ahorrado nada de escritura — salieron cuatro líneas, entró una, y en otro sitio apareció una función de nueve líneas. Aun así valía la pena.

Una función no es solo una forma de no repetirte. Es una forma de darle nombre a una idea, para que el código que usa la idea pueda decir el nombre y seguir adelante. «Mantén al jugador entre el borde izquierdo y el borde derecho» es un pensamiento que tuviste una vez. clamp(playerX, 0, width - PLAYER_WIDTH - 1) es ese pensamiento, por escrito. Cuatro sentencias if son el mismo pensamiento desmontado en piezas que tienes que volver a montar en la cabeza cada vez que las lees.

Cuando estés decidiendo si algo merece ser una función, no te preguntes cuántas veces la llamarás. Pregúntate si tiene nombre.

Pruébalo

  1. Cambia el nombre de un parámetro. En drawStar, cambia x e y por across y down, en todos los sitios de dentro de la función. No toques nada de fuera. Ejecútalo. Averigua por qué no se ha roto nada.

  2. Dibújalos al revés. Intercambia drawStars() y drawPlayer() en onOverlayUpdate y mira la nave. Luego vuelve a dejarlos como estaban. Cada una de esas cinco líneas es un trabajo, y su orden en la pantalla es su orden en la función.

  3. Usa clamp con un tono. Cambia shadeFor por return clamp(math.random(60, 90) + layer * 90, 0, 200) y mira las tres capas. Luego quita el clamp y vuelve a mirar: colorForeground te estaba conteniendo los números sin decir nada todo este tiempo, y ahora puedes ver dónde.

  4. Llama a drawStar con dos argumentos. Escribe drawStar(100, 100) en algún sitio de drawLayer y ejecútalo. El error nombra exactamente lo que falta. Léelo antes de volver a poner el tercer argumento.

  5. Mueve una variable local. Coge la línea local drift = 0 y llévala al final del archivo, debajo de todo. Ejecútalo, lee el error y piensa en la palabra «debajo» de la sección anterior.

Rómpelo a propósito

El orden de un archivo con nombres locales importa, y el error que obtienes cuando rompes ese orden no es el que esperas.

Coge la función drawStar entera y llévala al final del script, debajo de onOverlayUpdate. Todo sigue ahí, escrito igual. Ejecútalo:

Error executing function 'onOverlayUpdate':  functions/functions.singe:50: attempt to call a nil value (global 'drawStar')
stack traceback:
	functions/functions.singe:50: in upvalue 'drawLayer'
	functions/functions.singe:57: in upvalue 'drawStars'
	functions/functions.singe:101: in function 'onOverlayUpdate'

Esto tiene un aspecto distinto del error de la lección uno porque es otro tipo de error. El fallo de la lección uno se detectó antes de que se ejecutara el script. Este se detectó mientras se ejecutaba, y por eso Singe nombra la función en la que estaba a medias, y por eso hay un traceback debajo: la lista de quién llamó a quién, lo más reciente primero. La línea 50 está dentro de drawLayer, a la que se llamó desde la línea 57 dentro de drawStars, a la que se llamó desde la línea 101 dentro de onOverlayUpdate. Tus números de línea serán otros si tu archivo no coincide exactamente con el de arriba, y puede que el motor añada debajo una línea o dos por su cuenta. La palabra upvalue es como llama Lua a un nombre local que una función ha tomado prestado del archivo que la rodea; de momento, sáltatela.

Vale la pena aprenderse de memoria la queja en sí. «Attempt to call a nil value» significa que has puesto paréntesis después de un nombre que no guardaba nada. La palabra global delante de drawStar es la parte que lo delata: marcaste drawStar como local, así que cuando Lua leyó drawLayer y no encontró ningún nombre local así por encima, lo único que le quedaba por probar era un nombre global — y tampoco hay ningún nombre global llamado drawStar. Vuelve a poner la función encima del código que la llama y el error se va con ella.

Lo que has aprendido

  • Puedes escribir tus propias funciones, y nada las ejecuta salvo tus propias llamadas.

  • Los nombres que hay entre los paréntesis de una función son parámetros, y son las copias propias de la función de lo que le pasó quien la llamó.

  • return devuelve un valor y detiene la función ahí mismo, y una función que termina sin él devuelve nil.

  • Una llamada puede ser el argumento de otra llamada, y la de dentro ocurre primero.

  • Lua puede devolver más de un valor, y los recoges con varios nombres separados por comas.

  • local crea un nombre que solo existe donde se escribió.

  • Un nombre local dentro de una función se crea de nuevo en cada llamada y no recuerda nada de la anterior.

  • Un nombre local solo se ve por debajo de la línea que lo crea, así que los valores y tus funciones van encima de los callbacks que los usan.

  • Los callbacks siguen siendo globales, porque Singe los encuentra por su nombre.

  • Vale la pena escribir una función cuando lo que hace tiene nombre, aunque la llames una sola vez.

La próxima vez

Tus ciento veinte estrellas siguen siendo ciento veinte copias de tres ideas. En el programa no hay nada que sea una estrella: hay un número y algo de aritmética que convierte el número en una posición. No puedes decir «esta está más cerca, así que cae más deprisa y brilla más», porque no hay ninguna «esta» de la que decirlo, y no puedes dejar que una estrella se caiga por abajo y la sustituya otra nueva, porque ahí no hay nada que quitar.

La lección seis te da lo que guarda una estrella, y luego una forma de guardar ciento veinte y añadir la número ciento veintiuno mientras el juego se ejecuta. Es la lección más útil de esta parte del libro.

Lección 6: Listas de cosas

La lección terminada

Tienes ciento veinte estrellas y ninguna de ellas existe. No hay ninguna estrella en ningún sitio de tu programa: hay un bucle que da ciento veinte vueltas, y en cada vuelta calcula dos números a partir del número de la estrella y de su capa, pinta un píxel y lo olvida todo. Las tres capas están ahí para fingir lo único que ese montaje no puede hacer, que es dejar que una estrella sea distinta de su vecina.

Esta lección te da lo que falta. Aprenderás a guardar una lista de elementos, a hacer un elemento que guarda varios valores con nombre a la vez, y luego a juntar las dos cosas en una lista de elementos que recuerdan cada uno su propia posición, su velocidad y su brillo. Es la lección más larga de esta parte del libro y la que sostiene todo lo que viene después. Tómatela con calma.

Empieza una carpeta nueva

Una carpeta llamada tables, dentro un archivo llamado tables.singe, y Singe -R tables ejecutándose en una terminal. Copia dentro el programa terminado de la lección cinco: el campo de estrellas, la nave y todo lo demás.

Una lista

Añade esta línea al principio de tables.singe, debajo de los otros valores, y las tres llamadas a overlayPrint a onOverlayUpdate, encima del return.

local names = { "Ada", "Grace", "Alan" }
    overlayPrint(2, 2, names[1])
    overlayPrint(2, 3, names[3])
    overlayPrint(2, 4, "There are " .. #names .. " names.")

Ejecútalo. Ada en una línea, Alan en la siguiente, y There are 3 names. debajo.

Las llaves de la primera línea crean una tabla. Una tabla es el único contenedor que tiene Lua, y todo lo que guardes alguna vez en cantidad de más de uno va en una. Aquí guarda tres cadenas en fila, que es la forma a la que la gente llama lista.

Los corchetes de las líneas siguientes sacan un elemento. names[1] es el primer elemento, names[3] es el tercero, y el número entre corchetes se llama índice.

Ese número es donde Lua se separa de casi todos los demás lenguajes que te vas a encontrar. Lua cuenta desde uno. C, Java, Python, JavaScript y casi todos los demás cuentan desde cero, así que su primer elemento es el elemento cero y su tercer elemento tiene el índice dos. El primer elemento de Lua es el elemento uno, y esto es lo único que hace tropezar a los programadores que llegan de otro sitio. Tú no llegas de ningún sitio, así que lo tienes más fácil: el primero es el número uno.

Por cierto, names[0] no es un error. Es nil — el valor de nada de la lección tres — porque ahí no hay nada guardado. Leer un índice que nunca se ha llenado siempre da nil, lo cual es todo un detalle justo hasta que intentas usarlo.

El # delante del nombre de una tabla es el último signo de puntuación nuevo en una temporada. Te da cuántos elementos hay en la lista, así que #names es 3. Como la cuenta y el último índice son el mismo número, names[#names] es siempre el último elemento, por larga que se haga la lista.

Añadir y quitar

Una lista que tienes que escribir entera no le sirve de mucho a un juego. Estas dos llamadas son como cambia una lista mientras se ejecuta el programa.

    table.insert(names, "Katherine")

Eso pone Katherine al final, y #names ahora es 4. table.insert es una función como cualquier otra, y el punto en medio de su nombre significa que vive dentro de una tabla llamada table que pone Lua — una tabla de funciones para trabajar con tablas. No tienes que crearla ni cargarla. Está ahí.

Dale a table.insert tres argumentos y el del medio es dónde poner el elemento nuevo.

    table.insert(names, 1, "Edsger")

Edsger entra por delante, y todo lo que ya estaba se corre para hacerle sitio: Ada era el elemento uno y ahora es el elemento dos. No se sobrescribe nada y no se pierde nada.

Sacar un elemento es lo mismo, pero al revés.

    table.remove(names, 2)

El elemento dos se va, y todo lo que había detrás se corre hacia atrás para cerrar el hueco, así que la lista nunca tiene un agujero en medio. table.remove también te devuelve el elemento que ha sacado, así que local gone = table.remove(names, 2) lo quita y te dice qué era en una sola línea. Si no pones el número — table.remove(names) — saca el último elemento, que es la forma más rápida de usar una lista como una pila.

Pon esas tres llamadas en tu script, de una en una, ejecútalo después de cada una y mira cómo cambia la cuenta de la tercera línea.

Recorrer una lista

Ya conoces una forma de visitar cada elemento, porque la usas desde la lección cuatro:

    for i = 1, #names do
        overlayPrint(2, i + 1, names[i])
    end

Funciona. Empieza en uno, para en la cuenta, usa el contador como índice. Hay una forma mejor, y es la que escribirás de ahora en adelante:

    for i, name in ipairs(names) do
        overlayPrint(2, i + 1, name)
    end

ipairs recorre una lista desde el elemento uno hasta que se acaba, y le da a tu bucle dos cosas en cada vuelta: el índice y el propio elemento. Lo que importa es lo segundo. Con el for numérico obtienes un número y tienes que volver a la tabla con names[i] para saber qué es; con ipairs el elemento ya lo tienes en la mano, con el nombre que hayas puesto en segundo lugar.

También es más difícil equivocarse. for i = 1, #names es un sitio donde equivocarte por uno — empieza en cero e imprimes un nil, para en #names - 1 y pierdes el último — y ipairs no tiene ni un número con el que equivocarse.

La mayoría de las veces no quieres el índice, solo el elemento. Escribe el índice como un solo guion bajo y listo:

    for _, name in ipairs(names) do

_ es un nombre perfectamente normal, y nada en Lua lo trata de forma especial. Es una costumbre que comparten los programadores para decir «aquí llega algo y no lo voy a usar». Cualquiera que lea tu bucle sabe de un vistazo que en él el índice no importa.

Borra ahora los experimentos con names, y con ellos las líneas de overlayPrint. Ya sabes lo que es una lista. Es hora de meter en una algo mejor que una cadena.

Una tabla también puede ser un registro

Una estrella necesita recordar cuatro cosas: dónde está en horizontal, dónde está en vertical, lo rápido que cae y lo brillante que es. Cuatro listas separadas, todas sincronizadas a mano, serían un suplicio. En lugar de eso, crea una tabla y pon nombres dentro.

    local star = {}
    star.x = 40
    star.y = 0
    star.speed = 2
    star.shade = 180

Las llaves vacías crean una tabla vacía. Las cuatro líneas que siguen meten valores en ella con nombres en lugar de números, y el punto es como dices a qué nombre te refieres. star.x se lee «la x de star», y se comporta exactamente como cualquier otra variable: léela, dale un valor, súmale algo.

    star.y = star.y + star.speed

Una tabla usada así — un conjunto fijo de valores con nombre que describen una cosa — es un registro, y los nombres que tiene dentro son sus campos. Es el mismo tipo de tabla que la lista de antes. La única diferencia es que los elementos de una lista se encuentran por número y los campos de un registro se encuentran por nombre, y una misma tabla puede hacer las dos cosas a la vez si algún día lo quieres.

El punto es una abreviatura. star.x y star["x"] significan exactamente lo mismo, y vale la pena verlo una vez: los corchetes aceptan un nombre con la misma alegría que un número, así que una lista y un registro son de verdad una sola idea con dos sombreros. Usa el punto. Se lee mejor.

Un campo al que nunca has dado valor es nil, igual que un índice que nunca has llenado. No hay en ningún sitio una lista de nombres de campo permitidos, y nada comprueba cómo los escribes, así que star.sped no es un error — es nil, y verás lo que pasa después al final de esta lección.

Escribir cuatro líneas para rellenar cuatro campos acaba cansando. Puedes poner los campos dentro de las llaves al crear la tabla:

    local star = {
        x     = 40,
        y     = 0,
        speed = 2,
        shade = 180
    }

La misma tabla, una sola instrucción. Las comas separan los campos, el último no necesita coma detrás, y las líneas están repartidas solo para que se lean con facilidad.

Una lista de registros

Aquí está toda la idea de esta lección en dos líneas:

    local stars = {}
    table.insert(stars, star)

Una lista puede guardar cualquier cosa, y eso incluye una tabla. Así que una lista de registros es una lista de cosas, y cada una recuerda todo sobre sí misma. stars[1] es una estrella entera, y stars[1].y es lo que ha bajado esa estrella por la pantalla. Casi todos los juegos que escribas serán un puñado de listas como esta: los enemigos, las balas, los objetos que se recogen y los bloques que caen.

Hay una cosa sobre las tablas que tienes que saber antes de escribir el código, y pilla a todo el mundo una vez. Pasarle una tabla a una función no la copia. Un número sí se copia — por eso half pudo trocear su number en la lección cinco sin molestar a drift — pero una tabla se comparte. Los dos nombres se refieren a la misma tabla, y un cambio hecho a través de uno se ve a través del otro.

    local star = stars[3]
    star.y = star.y + 1

Eso mueve la tercera estrella de la lista. No una copia de ella: a ella. Esto es exactamente lo que quieres aquí, y es lo que hace que funcione la sección siguiente, pero recuérdalo cuando una función que has escrito cambie algo que no esperabas que cambiara.

Reconstruye el campo de estrellas

Fuera la aritmética. Una estrella está a punto de convertirse en una cosa.

Borra starAt, shadeFor, drawLayer y el viejo drawStar, y con ellos las constantes que usaban: LAYERS, STARS_PER_LAYER, ACROSS_STEP, DOWN_STEP, LAYER_SHIFT y LAYER_SPEED. La variable drift también se va, y con ella la línea de drift del principio de onOverlayUpdate. LAYER_BRIGHT se queda, con un nombre que ya no habla de capas, y se le unen dos valores:

local STAR_COUNT  = 120
local STAR_SHADE  = 55
local BURST_COUNT = 10
local stars = {}

Ciento veinte es lo que tenías: tres capas de cuarenta. La lista empieza vacía, y esto es lo que la llena:

local function newStar(y)
    local speed = math.random(1, 3)
    local star  = {
        x     = math.random(0, width - 1),
        y     = y,
        speed = speed,
        shade = math.random(60, 90) + speed * STAR_SHADE
    }
    return star
end

newStar crea una estrella y te la devuelve. Mira el último campo y compáralo con shadeFor de la lección cinco: la misma suma, con la velocidad de la propia estrella donde antes estaba el número de capa. Las capas no han desaparecido; más bien se han disuelto. Ahora cada estrella elige su propia velocidad, uno, dos o tres píxeles por fotograma, y una estrella que cae más rápido es más brillante, que es toda la ilusión de profundidad y cuesta una línea.

La y inicial es un parámetro porque los dos sitios que llaman a la función quieren cosas distintas. Las estrellas que se crean al empezar el juego deben quedar repartidas por toda la pantalla; las que se crean después entran por arriba.

local function makeStars()
    for number = 1, STAR_COUNT do
        table.insert(stars, newStar(math.random(0, height - 1)))
    end
end

Nada llama todavía a makeStars. Añade una línea al final del todo del archivo, después de todo lo demás y fuera de cualquier función:

makeStars()

Hay más que decir sobre esa línea, y tendrá que esperar al final de la lección. Ahora el dibujo, que se acorta cada vez que lo tocas:

local function drawStar(star)
    colorForeground(star.shade, star.shade, star.shade)
    overlayPlot(star.x, star.y)
end


local function drawStars()
    for _, star in ipairs(stars) do
        drawStar(star)
    end
end

drawStar recibía tres números en la lección cinco y ahora recibe una estrella. Todo lo que necesita saber está dentro de la estrella, que es la razón de tener registros: una sola cosa que pasar de un lado a otro en lugar de cuatro, y ninguna posibilidad de entregarlas en el orden equivocado. Y drawStars ha perdido su bucle sobre las capas, junto con cualquier interés en cuántas estrellas hay o de dónde han salido.

Estrellas que vienen y van

Ahora la parte que el viejo campo de estrellas no podía hacer de ninguna manera. Las estrellas caen cada una a su velocidad, se van por abajo y otras las sustituyen por arriba.

local function moveStars()
    for i = #stars, 1, -1 do
        local star = stars[i]
        star.y = star.y + star.speed
        if star.y >= height then
            table.remove(stars, i)
        end
    end
    while #stars < STAR_COUNT do
        table.insert(stars, newStar(0))
    end
end

Llámala desde onOverlayUpdate, en la línea donde antes estaba drift = drift + 1.

Cada estrella baja según su propia speed, que es la línea que la lección cinco no podía escribir. El while de abajo es el relleno: mientras haya menos de ciento veinte estrellas, crea otra en la parte de arriba de la pantalla. Se ejecuta tantas veces como haga falta y luego se para, que es la herramienta adecuada cuando no sabes cuántas faltan.

La línea for de arriba cuenta hacia atrás, con el paso que viste en la lección cuatro. for i = #stars, 1, -1 visita primero el último elemento y va hacia atrás hasta el elemento uno. No es un adorno. Es la única forma segura de hacer lo que hace este bucle, y la sección siguiente explica por qué.

Nunca quites hacia delante

Escribe el mismo bucle hacia delante y está roto:

    for i = 1, #stars do
        local star = stars[i]
        star.y = star.y + star.speed
        if star.y >= height then
            table.remove(stars, i)
        end
    end

Síguelo a mano con cuatro estrellas, y supón que las estrellas dos y tres han llegado las dos abajo.

  • i es 1. La estrella uno está bien.

  • i es 2. La estrella dos se ha salido por abajo, así que fuera. Todo se corre hacia abajo: la estrella que era la tres ahora es la dos, y la que era la cuatro ahora es la tres.

  • i es 3. Esa es la estrella que antes era la cuatro. La estrella tres no se ha mirado nunca. Quitar el elemento dos la ha bajado al hueco dos, y el bucle ya había pasado por el hueco dos y se había ido.

  • i es 4. Ya no hay elemento cuatro. stars[4] es nil.

Dos fallos distintos por un error pequeño. Se saltan elementos, así que una estrella que había llegado abajo ni siquiera se mira en esta vuelta. Que una estrella sobreviva un fotograma de más no hace daño, pero el mismo bucle sobre una lista de enemigos, donde lo que los mata es que el bucle los mire, es un fallo que perseguirías durante una hora. El segundo fallo hace más ruido. La lista ahora es más corta que la cuenta con la que empezó el bucle, porque #stars se calculó una vez, antes de quitar nada, así que las últimas vueltas del bucle se pasan del final de la lista:

Error executing function 'onOverlayUpdate':  tables/tables.singe:60: attempt to index a nil value (local 'star')
stack traceback:
	tables/tables.singe:60: in upvalue 'moveStars'
	tables/tables.singe:124: in function 'onOverlayUpdate'

«Attempt to index a nil value» significa que has puesto un punto detrás de algo que no guardaba nada. El (local 'star') del final lo nombra: star era nil, así que star.y no tenía dónde mirar.

Ir hacia atrás arregla los dos fallos a la vez, y vale la pena ver por qué en lugar de creértelo sin más. Cuando quitas el elemento i, todo lo que va después de i baja un hueco — y yendo hacia atrás, todo lo que va después de i es todo lo que ya has visitado. Lo que aún está por venir, los elementos desde i - 1 hasta 1, no se ha movido en absoluto. Que la lista encoja a tu espalda tampoco te puede hacer daño, porque vas hacia el elemento uno y el elemento uno siempre está ahí.

La regla, que usarás el resto de tu vida: cuando un bucle pueda quitar elementos de la lista que está recorriendo, recórrela hacia atrás.

ipairs no es una excepción. Quitar elementos en medio de un bucle ipairs sale mal de la misma forma. ipairs es para mirar, y el for hacia atrás es para cambiar.

Añade algunas tú

Una rama más en onInputPressed y podrás ver cómo crece la lista mientras se ejecuta el juego. Va con las otras dos:

    elseif what == SWITCH_BUTTON1 then
        addBurst()
local function addBurst()
    for number = 1, BURST_COUNT do
        table.insert(stars, newStar(0))
    end
end

addBurst va encima de los callbacks, con tus otras funciones. Y para que puedas ver cómo cambia la longitud de la lista, pon la cuenta en pantalla en onOverlayUpdate:

    overlayPrint(0, 0, "Stars: " .. #stars)

Pulsa el botón — la barra espaciadora, a menos que hayas cambiado de dónde viene SWITCH_BUTTON1 — una docena de veces. La cuenta sube de diez en diez con cada pulsación y el cielo se llena, y no se repite mientras lo mantienes pulsado: a onInputPressed se le avisa una vez, cuando el botón baja. Luego mira cómo la cuenta vuelve sola a ciento veinte a medida que las estrellas de más llegan abajo y se quitan, porque el relleno solo completa la lista hasta STAR_COUNT y nunca la recorta.

Ni el dibujo, ni el movimiento, ni el código que las quita han tenido que enterarse de que el número de estrellas había cambiado. Todos trabajan a partir de la lista.

Todo junto

local STAR_COUNT  = 120
local STAR_SHADE  = 55
local BURST_COUNT = 10

local PLAYER_WIDTH  = 20
local PLAYER_HEIGHT = 6
local PLAYER_SPEED  = 3
local PLAYER_MARGIN = 6

local width  = overlayGetWidth()
local height = overlayGetHeight()

local stars       = {}
local playerX     = width // 2
local playerY     = height - PLAYER_HEIGHT - PLAYER_MARGIN
local movingLeft  = false
local movingRight = false


local function clamp(value, low, high)
    if value < low then
        return low
    end
    if value > high then
        return high
    end
    return value
end


local function newStar(y)
    local speed = math.random(1, 3)
    local star  = {
        x     = math.random(0, width - 1),
        y     = y,
        speed = speed,
        shade = math.random(60, 90) + speed * STAR_SHADE
    }
    return star
end


local function makeStars()
    for number = 1, STAR_COUNT do
        table.insert(stars, newStar(math.random(0, height - 1)))
    end
end


local function addBurst()
    for number = 1, BURST_COUNT do
        table.insert(stars, newStar(0))
    end
end


local function moveStars()
    for i = #stars, 1, -1 do
        local star = stars[i]
        star.y = star.y + star.speed
        if star.y >= height then
            table.remove(stars, i)
        end
    end
    while #stars < STAR_COUNT do
        table.insert(stars, newStar(0))
    end
end


local function drawStar(star)
    colorForeground(star.shade, star.shade, star.shade)
    overlayPlot(star.x, star.y)
end


local function drawStars()
    for _, star in ipairs(stars) do
        drawStar(star)
    end
end


local function drawPlayer()
    colorForeground(80, 255, 120)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH, playerY + PLAYER_HEIGHT)
end


local function movePlayer()
    if movingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if movingRight then
        playerX = playerX + PLAYER_SPEED
    end
    playerX = clamp(playerX, 0, width - PLAYER_WIDTH - 1)
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    elseif what == SWITCH_BUTTON1 then
        addBurst()
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end


function onOverlayUpdate()
    overlayClear()
    movePlayer()
    moveStars()
    drawStars()
    drawPlayer()
    overlayPrint(0, 0, "Stars: " .. #stars)
    return OVERLAY_UPDATED
end


makeStars()

Qué acaba de pasar

El programa es más corto que el de la lección cinco y hace algo que la lección cinco ni siquiera podía empezar a hacer. Tres partes merecen una segunda mirada.

makeStars()

Esa única línea al final del todo del archivo no está dentro de ninguna función, y es fácil pasarla por alto. Lua lee tu archivo de arriba abajo cuando Singe lo carga, y una línea en el nivel exterior del archivo se ejecuta en ese mismo momento, una vez, antes de que el motor haya llamado a nada. Todo lo que hay encima son definiciones — aquí hay un valor, aquí hay una función — y esta es la única instrucción que ocurre al cargar. Tiene que ir al final, porque makeStars no existe hasta que se ha leído la línea que la crea.

        local star = stars[i]
        star.y = star.y + star.speed

star es una variable local que se crea de nuevo en cada vuelta del bucle, y guarda la misma tabla que está en la lista — no una copia. Cambiar star.y mueve la estrella que está en la lista. Si las tablas se copiaran, este bucle movería ciento veinte copias por fotograma y nada cambiaría nunca en pantalla.

    for _, star in ipairs(stars) do
        drawStar(star)
    end

Compáralo con la lección cuatro: dos bucles anidados, dos cuentas por estrella, un resto para mantener cada una en la pantalla, y tres capas para fingir la variedad que ahora tienes gratis. El dibujo ya no sabe ni le importa cómo llegaron las estrellas adonde están, cuántas hay ni qué les pasa después. Cada parte del programa hace un trabajo, y la lista es en lo que todas se ponen de acuerdo.

Pruébalo

  1. Hazlo más profundo. Cambia math.random(1, 3) por math.random(1, 6) y STAR_SHADE por 25. Más velocidades, más tonos, un cielo más profundo.

  2. Menos estrellas, ráfaga más grande. Pon STAR_COUNT a 10 y BURST_COUNT a 100, y luego pulsa el botón tres o cuatro veces. Mira cómo sube la cuenta en pantalla, y cronometra cuánto tarda en vaciarse.

  3. Dale a una estrella otro campo. Añade age = 0 a newStar, suma uno a star.age en moveStars y pon stars[1].age en pantalla junto a la cuenta. No hace falta cambiar nada más del programa para que cada estrella lleve un dato nuevo.

  4. Deja de quitarlas. Borra las tres líneas del bloque if star.y >= height de moveStars y ejecútalo. Espera diez segundos, luego lee la cuenta en pantalla y mira el cielo. Averigua cómo pueden ser ciertas las dos cosas a la vez.

  5. Hazlo hacia delante. Cambia for i = #stars, 1, -1 por for i = 1, #stars y ejecútalo hasta que se caiga. Luego vuelve a leer la sección de antes con el error de verdad delante.

Rómpelo a propósito

Escribe mal el nombre de un campo. En moveStars, cambia star.speed por star.sped:

        star.y = star.y + star.sped

Ejecútalo:

Error executing function 'onOverlayUpdate':  tables/tables.singe:60: attempt to perform arithmetic on a nil value (field 'sped')
stack traceback:
	tables/tables.singe:60: in upvalue 'moveStars'
	tables/tables.singe:124: in function 'onOverlayUpdate'

Tus números de línea no serán exactamente estos a menos que tu archivo coincida línea a línea con el de arriba. Lo que lees es el nombre del archivo, el número que va detrás y la queja.

Lee primero el final de la primera línea. field 'sped' es Lua diciéndote qué nombre ha salido vacío, y te está diciendo que era un campo — algo detrás de un punto — y no una variable tuya. «Attempt to perform arithmetic on a nil value» es lo que estaba haciendo cuando se dio cuenta: sumar nil a un número, cosa que no se puede hacer.

No hubo ninguna queja cuando la tabla se creó sin un campo sped, ni en el momento en que lo pediste. Una tabla te da nil por cualquier nombre que no tenga, sin decir nada. El error llega más tarde, en la primera línea que intenta usar la nada que te dieron, y eso puede estar muy lejos de la errata. Cuando veas nil value (field 'something'), busca el sitio donde ese nombre está escrito de otra forma.

Lo que has aprendido

  • Las llaves crean una tabla, el único contenedor que tiene Lua. Una tabla usada como lista guarda elementos en fila, y los corchetes con un índice sacan uno.

  • Lua cuenta desde uno. Casi todos los demás lenguajes cuentan desde cero.

  • #list es cuántos elementos tiene, y list[#list] es el último.

  • table.insert añade un elemento, al final o en la posición que digas; table.remove saca uno y cierra el hueco.

  • Un índice o un campo que nunca se ha llenado es nil, y nada te avisa hasta que lo usas.

  • ipairs recorre una lista y te da el índice y el elemento; _ es la costumbre para un índice que no quieres.

  • Una tabla usada como registro guarda campos con nombre, a los que se llega con un punto.

  • Una lista de registros es como un juego guarda sus enemigos, sus balas y todo lo demás de lo que hay más de uno.

  • Las tablas se comparten, no se copian, cuando las pasas de un lado a otro.

  • Cuando un bucle pueda quitar elementos de la lista que recorre, recórrela hacia atrás.

La próxima vez

Ya tienes todas las piezas de un juego: cosas que se mueven, una nave que responde a los controles, decisiones, bucles, funciones y una lista en la que las cosas pueden entrar y de la que pueden salir mientras el juego se ejecuta.

La lección siete las junta en un juego en el que puedes perder. Te mueves por la parte de abajo de la pantalla, caen bloques desde arriba y tú te apartas de su camino — y los bloques que caen son una lista de registros, creados, movidos y quitados exactamente igual que tus estrellas.

Lección 7: Un juego

La lección terminada

Hace seis lecciones pusiste una palabra en una pantalla negra. Desde entonces has aprendido todas las ideas de las que está hecho un juego pequeño: variables, decisiones, bucles, funciones propias y listas de cosas. Esta lección no enseña ninguna idea nueva. Gasta las que ya tienes.

Vas a construir un juego llamado Dodge. Caen bloques del cielo, tú deslizas una barra por la parte de abajo para apartarte de su camino, y cada bloque que no te da es un punto. Si te dan tres, se acabó. Lo construirás en seis etapas, y todas funcionan: nunca tendrás que escribir cien líneas y cruzar los dedos.

Crea la carpeta

Crea una carpeta llamada dodge, y dentro un archivo llamado dodge.singe. Ejecútalo como llevas ejecutándolo todo desde la lección uno:

Singe -R dodge

Déjalo funcionando en una terminal durante toda la lección. Cada vez que guardes, el juego se reinicia con tu cambio dentro.

Primera etapa: algo que puedes manejar

Escribe esto, guárdalo y manéjalo con las teclas de flecha izquierda y derecha.

dofile("Singe/Framework.singe")

local PLAYER_WIDTH  = 40
local PLAYER_HEIGHT = 8
local PLAYER_SPEED  = 4
local PLAYER_MARGIN = 4

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()
local playerY      = screenHeight - PLAYER_HEIGHT - PLAYER_MARGIN

local playerX    = (screenWidth - PLAYER_WIDTH) / 2
local goingLeft  = false
local goingRight = false


function onInputPressed(what)
    if what == SWITCH_LEFT then
        goingLeft = true
    elseif what == SWITCH_RIGHT then
        goingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        goingLeft = false
    elseif what == SWITCH_RIGHT then
        goingRight = false
    end
end


function onOverlayUpdate()
    if goingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if goingRight then
        playerX = playerX + PLAYER_SPEED
    end
    if playerX < 0 then
        playerX = 0
    elseif playerX > screenWidth - PLAYER_WIDTH then
        playerX = screenWidth - PLAYER_WIDTH
    end

    overlayClear()
    colorForeground(80, 255, 160)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH - 1, playerY + PLAYER_HEIGHT - 1)
    return OVERLAY_UPDATED
end

Cincuenta líneas, y casi nada es nuevo. Hay dos cosas que sí lo son, así que empieza por la primera línea.

dofile("Singe/Framework.singe")

dofile es de Lua y no de Singe, y significa «ve y ejecuta ese archivo, y luego sigue aquí». El archivo que ejecuta es Singe/Framework.singe, uno de los archivos que el motor desempaquetó en tu carpeta de trabajo la primera vez que ejecutaste algo, allá en la lección uno. Ábrelo en tu editor de texto y míralo: es Lua normal, del mismo tipo que lo que llevas escribiendo desde la lección dos, y no tiene nada de mágico.

Ejecutarlo le da a tu script un conjunto de nombres que luego puede usar. Los que usa este libro son estos:

  • DIR, que guarda la carpeta en la que está tu propio script. La lección nueve lo necesita en cuanto un juego carga una imagen, y es la verdadera razón de que esta línea esté aquí.

  • SCANCODE y MODIFIER, nombres para cada tecla de un teclado, para un juego que lee lo que se escribe en lugar de un joystick.

  • De GAMEPAD_0 a GAMEPAD_3 y de MOUSE_0 a MOUSE_3, para una recreativa que tiene enchufado más de uno de algo.

  • Unas cuantas funciones de ayuda cuyos nombres empiezan por util, y las seis llamadas que envían una puntuación a una tabla de récords, que es la lección veintiocho.

  • Otra forma completamente distinta de escribir un juego, que es la lección quince.

Hay una cosa que no te da, y la menciono porque es lo natural suponerlo. SWITCH_LEFT, y cualquier otro nombre que empiece por SWITCH_, viene del propio motor, antes de que se ejecute ningún script. Por eso las lecciones de la tres a la seis podían leer las teclas de flecha sin cargar nada. El framework añade cosas a lo que ya está ahí; no es él quien lo pone.

Este juego en concreto no usa nada del framework. La línea está aquí porque todos los juegos desde la lección nueve hasta el final del libro sí lo necesitan, y porque es como empiezan casi todos los juegos de Singe de verdad. Se lee una vez, al arrancar, y luego te olvidas de él.

La segunda cosa nueva es la forma de tratar las teclas de flecha, porque es lo primero que los principiantes hacen mal.

onInputPressed no mueve al jugador. Pone goingLeft a true, y onInputReleased lo vuelve a poner a false. El movimiento ocurre en onOverlayUpdate, que pregunta «¿está el jugador pulsando la izquierda?» sesenta veces por segundo. Si movieras al jugador dentro de onInputPressed, tendrías un paso por pulsación: Singe envía una pulsación exactamente una vez, cuando la tecla baja, y nunca la repite, cosa que la entrada de onInputPressed en la referencia dice claramente. Mantener pulsada la tecla no haría nada en absoluto.

Así que el callback de pulsación apunta lo que es verdad en el mundo, y la actualización decide qué hacer con ello. Mantén esa separación y tu código de entrada tendrá cinco líneas para siempre.

Los cuatro nombres en mayúsculas son variables normales. Escribir PLAYER_SPEED en mayúsculas es un mensaje para ti y para quien lo lea: esta se fija una vez arriba y no cambia nunca. Nada en Lua lo obliga. Importa porque dentro de un momento habrá diez, y cuando el juego sea demasiado difícil querrás un sitio obvio al que ir a bajar un número.

screenWidth y screenHeight vienen del motor en lugar de escribirse a mano, así que el juego se adapta al tamaño que tenga el overlay. playerY se calcula una vez a partir de la altura: la barra está a PLAYER_MARGIN píxeles del borde de abajo y nunca sube ni baja, así que no hay razón para volver a calcularlo en cada fotograma.

El - 1 de la línea de overlayBox no es una errata. overlayBox dibuja incluyendo las dos esquinas que le das, así que una caja de playerX a playerX + 40 tiene cuarenta y un píxeles de ancho. Restar uno hace que la barra que ves tenga exactamente cuarenta de ancho, lo que importará en la cuarta etapa, cuando algo tenga que decidir si te ha tocado.

Segunda etapa: algo que esquivar

Un bloque, cayendo. Añade dos constantes a la lista de arriba:

local BLOCK_SIZE    = 12
local BLOCK_SPEED   = 1.5

Dos variables más debajo de goingRight:

local blockX     = math.random(0, screenWidth - BLOCK_SIZE)
local blockY     = -BLOCK_SIZE

En onOverlayUpdate, justo encima de la línea overlayClear(), haz que caiga:

    blockY = blockY + BLOCK_SPEED
    if blockY > screenHeight then
        blockX = math.random(0, screenWidth - BLOCK_SIZE)
        blockY = -BLOCK_SIZE
    end

Y debajo de la línea que dibuja al jugador, dibújalo:

    colorForeground(255, 90, 90)
    overlayBox(blockX, blockY, blockX + BLOCK_SIZE - 1, blockY + BLOCK_SIZE - 1)

Guarda. Un cuadrado rojo cae, llega abajo y vuelve a aparecer arriba en otro sitio.

Empieza en -BLOCK_SIZE, que está por encima del borde superior de la pantalla. Una posición negativa no tiene nada de malo: el motor dibuja la parte de la caja que está en el overlay y tira sin decir nada la parte que no. El bloque entra deslizándose en lugar de aparecer de golpe.

BLOCK_SPEED es 1.5, no un número entero, así que blockY pasa la mayor parte de su vida valiendo algo como 83.5. Eso también está bien. Al dibujar se corta la fracción, y conservarla en la variable es lo que permite que el bloque se mueva más despacio que un píxel por fotograma.

Tercera etapa: un cielo lleno de ellos

Un bloque no es un juego. En la lección seis aprendiste a guardar muchos de algo en una lista, y esto es para lo que servía.

Borra blockX y blockY, y pon esto en su lugar:

local blocks     = {}
local spawnTimer = 0

Añade una constante más arriba:

local SPAWN_FRAMES  = 40

Ahora una función que crea un bloque y lo mete en la lista. Ponla encima de onInputPressed:

function spawnBlock()
    local block = {}
    block.x = math.random(0, screenWidth - BLOCK_SIZE)
    block.y = -BLOCK_SIZE
    table.insert(blocks, block)
end

Sustituye el código de caída de la segunda etapa por esto:

    spawnTimer = spawnTimer - 1
    if spawnTimer <= 0 then
        spawnBlock()
        spawnTimer = SPAWN_FRAMES
    end

    for i = #blocks, 1, -1 do
        local block = blocks[i]
        block.y = block.y + BLOCK_SPEED
        if block.y > screenHeight then
            table.remove(blocks, i)
        end
    end

Y sustituye la única línea que dibujaba el bloque por un bucle que los recorre todos:

    for i, block in ipairs(blocks) do
        overlayBox(block.x, block.y, block.x + BLOCK_SIZE - 1, block.y + BLOCK_SIZE - 1)
    end

Guarda. Llueven bloques.

Un bloque es un registro: una tablita con una x y una y dentro, que es como evitas que dos números que van juntos se separen. blocks es una lista de esos registros, que es la forma que tiene el mundo de casi cualquier juego.

spawnTimer cuenta hacia atrás de uno en uno en cada fotograma, y cuando llega a cero nace un bloque y el temporizador se vuelve a cargar. Cuarenta fotogramas son unos dos tercios de segundo. En este juego no hay reloj y no hace falta: onOverlayUpdate es el latido, y contar latidos es una forma perfectamente buena de medir el tiempo.

El bucle de caída va hacia atrás — de #blocks a 1, de uno en uno — porque va quitando cosas. Es la regla de la lección seis, y esta es la primera vez que tienes una razón de verdad para cumplirla. Quita el elemento tres recorriendo hacia delante y todo se corre un puesto hacia abajo, así que el bloque que era el elemento cuatro ahora es el tres y el bucle no lo mira nunca. Yendo hacia atrás, todo lo que se mueve ya se ha tratado.

El bucle de dibujo usa ipairs, porque no quita nada y solo quiere cada bloque por turno.

Cuarta etapa: recibir un golpe

Los bloques te atraviesan. Es hora de darse cuenta.

El motor tiene una función justo para esta pregunta. Cambia la comprobación de dentro del bucle de caída de esto:

        if block.y > screenHeight then
            table.remove(blocks, i)
        end

a esto:

        if collideRects(block.x, block.y, BLOCK_SIZE, BLOCK_SIZE, playerX, playerY, PLAYER_WIDTH, PLAYER_HEIGHT) or block.y > screenHeight then
            table.remove(blocks, i)
        end

Guarda, y lleva la barra contra un bloque que cae. Desaparece.

collideRects recibe dos rectángulos y responde true si se solapan. Cada rectángulo son cuatro números: una esquina, y luego un ancho y un alto — no dos esquinas, que es la otra forma razonable de describir un rectángulo y la que usa overlayBox. La entrada de collideRects en la referencia da el orden, y vale la pena mirarla ahora, porque poner los ocho argumentos en el orden equivocado es el tipo de equivocación que no produce ningún error, solo un juego en el que nada choca nunca con nada.

Podrías escribirla tú. Son cuatro comparaciones, y de verdad que no es difícil. Usa la del motor de todos modos, por tres razones. Es correcta, también en los casos difíciles: un rectángulo sin ancho, dos rectángulos que solo se tocan por un borde. Dice lo que significa, así que la línea se lee como «¿se han solapado estos dos?» en lugar de cuatro comparaciones unidas por and que tienes que descifrar cada vez que vuelves a ella. Y cuando llegues a la lección once, donde las cosas chocan constantemente, ya conocerás la familia: collidePointRect para un clic del ratón, collideCircles para dos cosas redondas y collideSegments para un disparo contra una pared. La referencia las enumera juntas.

Lo único que el motor no puede hacer por ti es decidir qué significa un rectángulo. Aquí el rectángulo del bloque es el bloque entero. En un juego de verdad a menudo quieres que el rectángulo de impacto sea un poco más pequeño que la imagen, para que librarte por poco se sienta como librarte por poco. Eso es una decisión de diseño, y la lección once es donde la tomas.

Quinta etapa: puntuación y vidas

Que te den debería costar algo, y sobrevivir debería valer algo.

Dos constantes más arriba:

local BLOCK_FASTER  = 0.05
local START_LIVES   = 3

Tres variables más, junto a spawnTimer:

local blockSpeed = BLOCK_SPEED
local score      = 0
local lives      = START_LIVES

BLOCK_SPEED es ahora la velocidad a la que empieza el juego, y blockSpeed es la velocidad a la que va ahora mismo. Cambia la línea de caída para que use la variable:

        block.y = block.y + blockSpeed

Luego separa los dos casos, porque ahora hacen cosas distintas:

        if collideRects(block.x, block.y, BLOCK_SIZE, BLOCK_SIZE, playerX, playerY, PLAYER_WIDTH, PLAYER_HEIGHT) then
            table.remove(blocks, i)
            lives = lives - 1
        elseif block.y > screenHeight then
            table.remove(blocks, i)
            score      = score + 1
            blockSpeed = blockSpeed + BLOCK_FASTER
        end

Y muestra los números. Pon esto justo antes del return:

    overlayPrint(1, 1, "SCORE " .. score .. "    LIVES " .. lives)

Guarda, y juega un minuto. Se va poniendo más difícil, y ese es todo el truco: cada bloque que esquivas hace que los siguientes caigan una vigésima de píxel por fotograma más deprisa. A los veinte puntos ya van claramente más rápido. No has tenido que escribir ni una palabra sobre niveles de dificultad.

También verás LIVES llegar a -4, porque todavía nada detiene el juego. Esa es la siguiente etapa, y es la que más importa.

Sexta etapa: fin de partida y volver a jugar

Aquí está la trampa. La forma obvia de añadir una pantalla de fin de partida es una variable llamada gameOver, que se pone a true cuando se acaban las vidas. Luego quieres una pantalla de título antes de la primera partida, así que añades started. Luego quieres una tecla de pausa, así que añades paused. Ahora tienes tres variables de verdadero o falso, ocho combinaciones entre ellas, y cinco de esas combinaciones son disparates que tu código tiene que tener cuidado de no producir nunca. Todos los principiantes escriben este juego al menos una vez, y es donde los juegos pequeños van a morir.

Haz esto en su lugar. Una sola variable guarda lo que está haciendo el juego, como una palabra:

local state      = "waiting"

Vale "waiting" antes de la primera partida, "playing" durante una y "over" cuando se acaban las vidas. Tres estados, una variable y ninguna combinación imposible. Las cadenas no tienen nada de mágico; son palabras que has elegido tú, y tienes que escribirlas igual todas las veces.

Ahora la función que empieza una partida. Cada variable que pertenece a una partida vuelve aquí a su valor inicial, en un solo sitio:

function startGame()
    playerX    = (screenWidth - PLAYER_WIDTH) / 2
    blocks     = {}
    blockSpeed = BLOCK_SPEED
    spawnTimer = 0
    score      = 0
    lives      = START_LIVES
    state      = "playing"
end

Perder la última vida la termina. Dentro de la rama de la colisión, debajo de lives = lives - 1:

            if lives == 0 then
                state = "over"
            end

La barra espaciadora empieza una partida, pero solo cuando no hay una ya en marcha. Añade una rama a onInputPressed:

    elseif what == SWITCH_BUTTON1 and state ~= "playing" then
        startGame()

~= es «no es igual a». state ~= "playing" es verdadero mientras se espera y verdadero cuando se ha acabado, que son justo los dos momentos en los que la barra espaciadora debe empezar una partida. SWITCH_BUTTON1 es la barra espaciadora por defecto, y también el botón A de un mando.

Dos funciones pequeñas ponen las palabras en pantalla. printCentered hace las cuentas una sola vez para que las pantallas de título y de fin de partida no las hagan mal cada una por su lado:

function drawOverText()
    printCentered(7, "GAME OVER")
    printCentered(9, "PRESS SPACE TO PLAY AGAIN")
end


function drawWaitingText()
    printCentered(6, "DODGE THE BLOCKS")
    printCentered(8, "ARROW KEYS TO MOVE")
    printCentered(10, "PRESS SPACE TO START")
end


function printCentered(row, text)
    overlayPrint(math.floor((TEXT_COLUMNS - #text) / 2), row, text)
end

con una constante más arriba:

local TEXT_COLUMNS  = overlayGetWidth() // overlayGetFontWidth()

Por último, la parte importante. Saca de onOverlayUpdate todo lo que dibuja y llévalo a una función llamada drawGame, lleva todo lo que mueve a una función llamada updatePlaying — las dos están en el listado completo de abajo — y deja onOverlayUpdate así:

function onOverlayUpdate()
    if state == "playing" then
        updatePlaying()
    end

    overlayClear()
    drawGame()
    if state == "waiting" then
        drawWaitingText()
    elseif state == "over" then
        drawOverText()
    end

    return OVERLAY_UPDATED
end

Guarda. Tienes un juego: una pantalla de título, una partida, un fin de partida y una forma de volver a empezar.

Vuelve a leer esas trece líneas, porque son la forma de todos los juegos que vas a escribir. El mundo solo se mueve mientras el estado es "playing", así que la pantalla de fin de partida se congela con los últimos bloques colgando justo donde estaban. El mundo se dibuja en cada fotograma sea cual sea el estado, porque la imagen es la misma en los tres; el estado solo decide qué palabras van encima. Y hay exactamente un sitio que toma esa decisión.

Eso es lo que has comprado con la variable state. Cuando añadas una pausa, añadirás una rama a ese if y una línea a onInputPressed, y nada más del juego tendrá que saber nada de ella.

Todo junto

Aquí lo tienes, terminado. Si el tuyo no coincide, vale la pena encontrar la diferencia.

dofile("Singe/Framework.singe")

local PLAYER_WIDTH  = 40
local PLAYER_HEIGHT = 8
local PLAYER_SPEED  = 4
local PLAYER_MARGIN = 4
local BLOCK_SIZE    = 12
local BLOCK_SPEED   = 1.5
local BLOCK_FASTER  = 0.05
local SPAWN_FRAMES  = 40
local START_LIVES   = 3
local TEXT_COLUMNS  = overlayGetWidth() // overlayGetFontWidth()

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()
local playerY      = screenHeight - PLAYER_HEIGHT - PLAYER_MARGIN

local playerX    = (screenWidth - PLAYER_WIDTH) / 2
local goingLeft  = false
local goingRight = false
local blocks     = {}
local blockSpeed = BLOCK_SPEED
local spawnTimer = 0
local score      = 0
local lives      = START_LIVES
local state      = "waiting"


function drawGame()
    colorForeground(80, 255, 160)
    overlayBox(playerX, playerY, playerX + PLAYER_WIDTH - 1, playerY + PLAYER_HEIGHT - 1)
    colorForeground(255, 90, 90)
    for i, block in ipairs(blocks) do
        overlayBox(block.x, block.y, block.x + BLOCK_SIZE - 1, block.y + BLOCK_SIZE - 1)
    end
    overlayPrint(1, 1, "SCORE " .. score .. "    LIVES " .. lives)
end


function drawOverText()
    printCentered(7, "GAME OVER")
    printCentered(9, "PRESS SPACE TO PLAY AGAIN")
end


function drawWaitingText()
    printCentered(6, "DODGE THE BLOCKS")
    printCentered(8, "ARROW KEYS TO MOVE")
    printCentered(10, "PRESS SPACE TO START")
end


function printCentered(row, text)
    overlayPrint(math.floor((TEXT_COLUMNS - #text) / 2), row, text)
end


function spawnBlock()
    local block = {}
    block.x = math.random(0, screenWidth - BLOCK_SIZE)
    block.y = -BLOCK_SIZE
    table.insert(blocks, block)
end


function startGame()
    playerX    = (screenWidth - PLAYER_WIDTH) / 2
    blocks     = {}
    blockSpeed = BLOCK_SPEED
    spawnTimer = 0
    score      = 0
    lives      = START_LIVES
    state      = "playing"
end


function updatePlaying()
    if goingLeft then
        playerX = playerX - PLAYER_SPEED
    end
    if goingRight then
        playerX = playerX + PLAYER_SPEED
    end
    if playerX < 0 then
        playerX = 0
    elseif playerX > screenWidth - PLAYER_WIDTH then
        playerX = screenWidth - PLAYER_WIDTH
    end

    spawnTimer = spawnTimer - 1
    if spawnTimer <= 0 then
        spawnBlock()
        spawnTimer = SPAWN_FRAMES
    end

    for i = #blocks, 1, -1 do
        local block = blocks[i]
        block.y = block.y + blockSpeed
        if collideRects(block.x, block.y, BLOCK_SIZE, BLOCK_SIZE, playerX, playerY, PLAYER_WIDTH, PLAYER_HEIGHT) then
            table.remove(blocks, i)
            lives = lives - 1
            if lives == 0 then
                state = "over"
            end
        elseif block.y > screenHeight then
            table.remove(blocks, i)
            score      = score + 1
            blockSpeed = blockSpeed + BLOCK_FASTER
        end
    end
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        goingLeft = true
    elseif what == SWITCH_RIGHT then
        goingRight = true
    elseif what == SWITCH_BUTTON1 and state ~= "playing" then
        startGame()
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        goingLeft = false
    elseif what == SWITCH_RIGHT then
        goingRight = false
    end
end


function onOverlayUpdate()
    if state == "playing" then
        updatePlaying()
    end

    overlayClear()
    drawGame()
    if state == "waiting" then
        drawWaitingText()
    elseif state == "over" then
        drawOverText()
    end

    return OVERLAY_UPDATED
end

Unas ciento veinte líneas de código, y las has escrito todas de unas pocas en unas pocas.

Qué acaba de pasar

Algunas partes merecen una segunda mirada.

local blocks     = {}
local score      = 0


function startGame()
    score = 0
end

Los datos son local y las funciones no. Son dos decisiones deliberadas y opuestas.

Los datos son local para que pertenezcan a este archivo y nada de fuera pueda meter la mano y cambiarlos. Las funciones son globales para que puedan llamarse unas a otras en cualquier orden: drawOverText se define antes que printCentered y la llama de todos modos, porque un nombre global se busca en el momento de la llamada, y para entonces ya se ha leído todo el archivo. Haz local esas funciones y el archivo tendrá que estar ordenado para que nada se use antes de aparecer, que es una regla con la que tropezarías durante el resto del libro. Tres de los nombres de aquí no tienen elección: onOverlayUpdate y los dos callbacks de entrada tienen que ser globales, porque así es como los encuentra Singe.

Dentro del archivo, el orden es alfabético, con los tres callbacks al final. No es una regla de Lua. Es para que dentro de seis meses puedas encontrar spawnBlock sin leer nada.

    overlayPrint(math.floor((TEXT_COLUMNS - #text) / 2), row, text)

#text es la longitud de una cadena, en caracteres. Conociste # en la lección seis contando los elementos de una lista, y aquí hace el mismo trabajo. "GAME OVER" tiene nueve caracteres, así que en una pantalla de sesenta columnas empieza en la columna veinticinco, lo que deja veinticinco celdas de espacio a su izquierda y veintiséis a su derecha. math.floor tira la fracción, porque no existe la columna veinticinco y media.

TEXT_COLUMNS calcula cuántas celdas de carácter caben a lo ancho de la pantalla. overlayPrint cuenta en celdas mientras que todo lo demás cuenta en píxeles, así que el ancho del overlay se divide entre el ancho de una celda, y overlayGetFontWidth es lo que te lo dice. Dos barras en lugar de una, porque una fracción de columna no es un sitio donde imprimir. Calcúlalo así y el centrado sigue siendo correcto con cualquier tamaño de overlay, que es lo cuarto de Pruébalo.

    colorForeground(255, 90, 90)

colorForeground fija un color que se queda fijado. No es un argumento de overlayBox; es un interruptor que accionas, y todo lo que se dibuja después sale en ese color hasta que lo vuelves a accionar. Por eso drawGame pone el verde, dibuja al jugador, pone el rojo y luego dibuja todos los bloques sin volver a mencionar el color.

No afecta a overlayPrint. La fuente de consola se copia en el overlay tal cual, en sus propios colores, cosa que la entrada de overlayPrint en la referencia dice con todas las letras. El texto en color necesita una fuente cargada, y eso es la lección diecinueve.

Pruébalo

  1. Hazlo más fácil, y luego injusto. Cambia PLAYER_WIDTH a 80 y juega una partida. Luego cámbialo a 12, el mismo tamaño que un bloque. Fíjate en que no has tenido que tocar ni el dibujo ni la colisión para ninguna de las dos cosas.

  2. Que acelere más deprisa. Cambia BLOCK_FASTER de 0.05 a 0.5 y mira cuántos puntos consigues. Luego prueba 0, y pregúntate si el juego sigue mereciendo la pena.

  3. Una vida extra. Devuélvele una vida al jugador cada diez puntos. Todo lo que necesitas ya está en updatePlaying, en la rama que suma a la puntuación.

  4. Juega en grande. Ejecútalo con Singe -R --canvas=1280x720 dodge. El juego se coloca bien, texto centrado incluido, porque le preguntó al motor cuánto medía la pantalla. TEXT_COLUMNS también lo preguntó.

  5. Ponlo en pausa. Añade un cuarto estado, "paused". SWITCH_BUTTON2 debería cambiar entre "playing" y "paused", y nada debería moverse en pausa. Bien hecho, son tres líneas y no tienes que tocar updatePlaying en absoluto.

Rómpelo a propósito

Ve a spawnBlock y borra la línea que da valor a block.y, para que quede así:

function spawnBlock()
    local block = {}
    block.x = math.random(0, screenWidth - BLOCK_SIZE)
    table.insert(blocks, block)
end

Guarda, pulsa la barra espaciadora, y Singe se detiene con esto:

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:97: attempt to perform arithmetic on a nil value (field 'y')
stack traceback:
	dodge/dodge.singe:97: in function 'updatePlaying'
	dodge/dodge.singe:135: in function 'onOverlayUpdate'

La línea 97 es block.y = block.y + blockSpeed. La queja es que algo en esa suma no es un número, y la parte entre paréntesis te dice cuál: field 'y', es decir, la y de dentro de una tabla. No tiene valor, porque nunca se lo diste, y algo sin valor en Lua es nil.

Fíjate en dónde está el error y dónde está la equivocación. El error está en updatePlaying, a cuarenta líneas de spawnBlock, donde no hay nada mal en absoluto. updatePlaying es solo el primer trozo de código con la mala suerte de tocar el destrozo. Esto es lo normal, no la excepción, y seguir ese rastro hacia atrás es una habilidad.

Vuelve a poner la línea. Luego pasa la página, porque la lección siguiente no trata de otra cosa.

Lo que has aprendido

  • Un juego es un mundo que cambia, un mundo que se dibuja y una decisión sobre cuál de las dos cosas hacer — y son tres trozos de código separados.

  • Los callbacks de entrada deberían apuntar lo que está pulsado; la actualización debería decidir qué significa eso.

  • Una lista de registros es la forma de casi cualquier mundo de juego.

  • Quita cosas de una lista recorriéndola hacia atrás.

  • collideRects responde si dos rectángulos se solapan, y la versión del motor es mejor que la tuya porque es correcta, se lee bien y tiene una familia que volverás a ver.

  • Una variable state que guarda una palabra gana a tres indicadores de verdadero o falso, y les sigue ganando a medida que el juego crece.

  • Empieza una partida desde una función que lo reinicia todo, para que la segunda partida sea exactamente igual que la primera.

  • Los números que quizá quieras ajustar van en constantes con nombre al principio del archivo.

  • Construye un juego por etapas que funcionen cada una. Un programa que no ha funcionado nunca es mucho más difícil de arreglar que uno que funcionaba hace cinco minutos.

La próxima vez

Ya has escrito código suficiente para cometer errores interesantes. La lección siguiente es la que ningún libro para principiantes se molesta en incluir: qué dicen de verdad los mensajes de error de Singe, cómo averiguar lo que guarda realmente una variable en lugar de adivinarlo, y cómo partir un problema por la mitad hasta que no le quede ningún sitio donde esconderse.

Lección 8: Cuando algo sale mal

La lección terminada

Has escrito un juego. De aquí en adelante pasarás más tiempo arreglando programas que escribiéndolos, y eso no es señal de que te pase nada malo. Es el trabajo. La diferencia entre alguien que disfruta programando y alguien que lo deja casi nunca es el talento; es si aprendió a leer lo que le dice el ordenador.

Así que en esta lección no hay nada nuevo que construir. Son los cinco mensajes que más verás durante el resto de tu vida, lo que significa de verdad cada uno, y cuatro formas de dar caza a la equivocación que hay detrás. Ten abierto dodge.singe de la lección siete, porque vas a romperlo a propósito varias veces.

Dos tipos de parada

Singe se para por dos razones distintas, y lo dice de dos formas distintas.

Cuando el script ni siquiera llega a arrancar, te sale algo con esta forma:

Error running script:  dodge/dodge.singe:92: 'then' expected near 'spawnBlock'

Lua lee el archivo entero antes de ejecutar ni una palabra, y esto significa que no ha podido entender lo que ha leído. No se ha ejecutado nada en absoluto.

Cuando el script arrancó bien pero algo salió mal después, te sale en cambio esta forma:

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:98: attempt to perform arithmetic on a nil value (global 'blockSped')
stack traceback:
	dodge/dodge.singe:98: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

El juego estaba funcionando. Singe llamó a tu onOverlayUpdate, como hace sesenta veces por segundo, y esta vez la llamada no volvió.

Las dos formas contienen las mismas tres cosas, y son las tres cosas que quieres: un archivo, una línea y una queja. Léelas en ese orden, siempre.

Los números de línea de esta lección son los del listado terminado de la lección siete. Si los tuyos están desviados una o dos líneas, también lo está tu archivo, y nada de lo que hace falta para leer un error depende de que el número coincida.

Los que lo paran antes de empezar

Estos son los fáciles, y también son los que peor sientan, porque la pantalla se queda negra y no hay nada que mirar.

Ve a updatePlaying y borra la palabra then de la línea if spawnTimer ⇐ 0 then. Guarda:

Error running script:  dodge/dodge.singe:92: 'then' expected near 'spawnBlock'

Lua llegó al final de la línea del if, quería la palabra then y en su lugar encontró el principio de la línea siguiente — que es spawnBlock(), y esa es la parte near 'spawnBlock'. «Near» significa «aquí es donde me he dado cuenta», y suele ser lo primero que va después de lo que te has dejado.

Ahora uno más feo. Vuelve a poner then, y en su lugar borra el end de la última línea de spawnBlock. Guarda:

Error running script:  dodge/dodge.singe:148: 'end' expected (to close 'function' at line 58) near <eof>

La línea 148 es el final del archivo, justo después de su última línea. A la línea 148 no le pasa nada. Lua leyó hasta el final del todo — <eof> es como llama al final de un archivo — esperando todavía un end que nunca llegó, y para entonces se había tragado todas las funciones que van después de spawnBlock como si fueran parte de ella.

La mitad útil de ese mensaje es (to close 'function' at line 58), que es donde empieza spawnBlock. Cuando un mensaje señala el final del archivo, créete lo que dice entre paréntesis, no el número de línea. Por esto también importa tanto la sangría: un end que falta es casi invisible en una lista de líneas, y salta a la vista en cuanto todo lo que hay debajo está sangrado un paso de más.

Dos más que vale la pena reconocer, porque te vas a encontrar los dos esta misma semana:

Error running script:  dodge/dodge.singe:41: unfinished string near '"GAME OVER)'

Unas comillas que abriste y nunca cerraste, que ya viste en la lección uno.

Error running script:  dodge/dodge.singe:135: 'then' expected near '='

Ese es if state = "playing" then. Un = da valor a una variable, dos == hacen una pregunta, y Lua no te deja dar valor a una dentro de un if. Parece una queja rara, y siempre significa lo mismo.

Attempt to index a nil value

Este es el que más verás, con mucha diferencia.

Ve a spawnBlock y escribe mal block en la primera línea que lo usa, para que quede blocl.x = math.random(0, screenWidth - BLOCK_SIZE). Guarda y pulsa la barra espaciadora:

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:60: attempt to index a nil value (global 'blocl')
stack traceback:
	dodge/dodge.singe:60: in function 'spawnBlock'
	dodge/dodge.singe:92: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

Indexar es lo que hace el punto. blocl.x significa «entra en la cosa llamada blocl y busca la x que tiene dentro». Eso solo se puede hacer con una tabla.

Nil es como llama Lua a un nombre que no tiene nada detrás. No lo has visto mucho porque has tenido cuidado de darle un valor a todo, pero cualquier nombre que no hayas usado nunca ya es nil, y escribir mal un nombre se inventa uno completamente nuevo.

Así que el mensaje entero dice: has usado un punto en algo que no existe.

La parte entre paréntesis es el regalo. global 'blocl' es el nombre exacto de la cosa que estaba vacía. Búscalo en tu archivo. Si aparece exactamente una vez, es una falta de ortografía, y la has encontrado en diez segundos.

La palabra que va antes del nombre te dice dónde lo buscó Lua:

  • global — un nombre que no tiene local delante en ningún sitio.

  • local — un nombre que declaraste con local en la función en la que estás.

  • field — un nombre detrás de un punto, como la y de block.y.

  • upvalue — un local de más afuera que esta función puede ver, que es lo que son todas las variables de dodge.singe, ya que se declaran al principio del archivo y se usan dentro de funciones.

field es la otra causa habitual, y no es ninguna falta de ortografía. Si escribiste block.hit.when y nunca diste valor a block.hit, te sale attempt to index a nil value (field 'hit'). El punto que falla es el segundo. Lua te dice cuál nombrándolo.

Attempt to call a nil value

Arregla blocl. Ahora escribe mal una función del motor: en drawGame, cambia overlayPrint por overlayPirnt. Guarda:

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:36: attempt to call a nil value (global 'overlayPirnt')
stack traceback:
	dodge/dodge.singe:36: in function 'drawGame'
	dodge/dodge.singe:140: in function 'onOverlayUpdate'

El mismo nil, otro delito. Llamar es lo que hacen los paréntesis, y eso solo se puede hacer con una función. No hay ninguna función llamada overlayPirnt, así que overlayPirnt es nil, así que los paréntesis no tienen nada a lo que llamar.

Esto pasa por cuatro razones, de más a menos frecuente:

  1. Has escrito mal una de tus propias funciones.

  2. Has escrito mal una de las de Singe. Nada en el motor comprueba cómo escribes los nombres cuando se carga el archivo, así que un nombre del motor mal escrito es solo otro nombre que resulta estar vacío, y no te cuesta nada hasta que se ejecuta la línea.

  3. La función no existe en Singe en absoluto — era una suposición razonable, y las suposiciones razonables fallan más o menos la mitad de las veces. La lista de funciones de la referencia es la única forma de estar seguro.

  4. La hiciste local y la llamaste desde algún sitio por encima de donde se declara. Esa es justo la razón de que las funciones de dodge.singe sean globales.

Hay una versión mucho peor de esta equivocación, y te la encontraste en la lección uno sin saberlo: escribe mal un callback y no te sale ningún mensaje. onOverlayUpdated no es un error. Es una función perfectamente válida de la que Singe no ha oído hablar nunca y a la que nunca llamará, así que la pantalla se queda negra y nada se queja. Cuando toda una parte del juego no hace absolutamente nada, sospecha del nombre.

Attempt to perform arithmetic on a nil value

Vuelve a poner overlayPrint. En updatePlaying, escribe mal blockSpeed en la línea de caída, para que quede block.y = block.y + blockSped:

Error executing function 'onOverlayUpdate':  dodge/dodge.singe:98: attempt to perform arithmetic on a nil value (global 'blockSped')
stack traceback:
	dodge/dodge.singe:98: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

La aritmética es +, -, * y /. No se puede sumar la nada a un número. De nuevo los paréntesis nombran la cosa vacía, y de nuevo la causa más común es una errata — pero este tiene una segunda causa que vale la pena conocer, porque es más difícil de ver.

Una variable a la que nunca diste un número es nil, no cero. Si añades un récord al juego y escribes local hiScore al principio sin = 0, guarda nil hasta que algo le dé valor, y el primer hiScore + score detiene el juego. Lua no empieza los números en cero por ti. Los empiezas tú en cero.

Dos parientes cercanos, con la misma causa y la misma cura:

dodge/dodge.singe:37: attempt to concatenate a nil value (upvalue 'hiScore')

.. uniendo una cadena a algo que no está ahí. Verás este cada vez que imprimas una puntuación a la que se te olvidó dar valor — aquí, hiScore añadido a la línea de la puntuación en drawGame, que es la línea 37 ahora que local hiScore está encima.

dodge/dodge.singe:105: attempt to compare nil with number

Ese es if score > hiScore then, puesto debajo de state = "over" para guardar la mejor puntuación cuando acaba una partida, sin nada en hiScore. Fíjate en que este mensaje no nombra nada entre paréntesis. Cuando Lua no puede decirte qué lado estaba vacío, la sección que va después de la siguiente te enseña a averiguarlo.

Un argumento del tipo equivocado

Todos los mensajes hasta ahora venían de Lua. Este viene de Singe, y tiene un aspecto completamente distinto, así que vale la pena conocerlo a propósito.

Supón que quieres ver qué hay en blocks, e intentas imprimirlo. Añade esta línea a drawGame, debajo de la puntuación:

    overlayPrint(1, 3, blocks)
37:overlayPrint:  Argument 3 must be a string.

Ni nombre de archivo, ni traza, ni ningún attempt to nada. Una queja del motor empieza con el número de línea, luego el nombre de la función que se ha negado y luego lo que quería. Aquí a overlayPrint le han dado una tabla donde necesita texto, y se ha parado en lugar de dibujar algo sin sentido.

El mensaje hermano cuenta en lugar de comprobar:

34:overlayBox:  Expected 4 argument(s), got 3.

Eso es un overlayBox al que le falta una esquina. Ese argument(s) tan raro es del motor, no una errata tuya.

Cuando te salga uno de estos, la entrada de esa función en la referencia es la respuesta, y te llevará un minuto. Cada entrada enumera los argumentos en orden, con lo que tiene que ser cada uno. Singe los comprueba porque la alternativa es un juego que funciona durante diez minutos y luego dibuja basura.

Averiguar qué hay de verdad ahí dentro

La mitad de depurar no consiste en leer errores. Es el caso en el que nada se cae y nada funciona: bloques que nunca aparecen, un jugador que no se mueve, una puntuación atascada en cero. Para eso necesitas ver el interior del juego mientras se ejecuta, y hay dos formas.

La primera es debugPrint, que escribe una línea en la terminal desde la que arrancaste Singe. Coge la línea que no consigues entender y pon una encima:

    debugPrint("blocks " .. #blocks .. ", timer " .. spawnTimer)

Ahora estás mirando lo que hay de verdad en lugar de lo que estás seguro de que hay, y en ese hueco es donde viven los fallos. Imprime playerX del mismo modo y también verás la verdad sobre él: se imprime como 160.0, no 160, porque dividir con / en Lua siempre da un número con parte decimal, aunque esa parte sea cero.

Hay dos cosas que te van a morder. La primera es que debugPrint exige texto o un número; dale cualquier otra cosa y detiene el juego igual que hizo overlayPrint. debugPrint(blocks) no te enseñará una lista, y debugPrint("left " .. goingLeft) al principio de updatePlaying tampoco te enseñará un true ni un false:

dodge/dodge.singe:78: attempt to concatenate a boolean value (upvalue 'goingLeft')

tostring es el arreglo. Acepta cualquier cosa y te da texto para ella, así que tostring(goingLeft) es "true" o "false" y la línea funciona.

La segunda es que onOverlayUpdate se ejecuta sesenta veces por segundo, así que un debugPrint dentro de él imprime sesenta líneas por segundo y no puedes leer ninguna. La referencia lo dice en su entrada: la llamada es barata, pero nada la frena.

Antes que nada, pon un interruptor delante de cada línea de depuración que añadas, para poder quitar el ruido sin tener que volver a buscarlas todas:

local DEBUG = true


function debugLog(text)
    if DEBUG then
        debugPrint(text)
    end
end

Cada debugLog del juego obedece a ese único true. Cámbialo a false y el juego se queda callado; vuelve a cambiarlo y todo regresa.

Luego imprime cuando algo pasa, en lugar de en cada fotograma:

            debugLog("hit at y " .. math.floor(block.y) .. ", lives now " .. lives)

O imprime con un temporizador, que cuenta hacia atrás exactamente igual que cuando nacen los bloques:

    reportTimer = reportTimer - 1
    if reportTimer <= 0 then
        debugReport()
        reportTimer = REPORT_FRAMES
    end

La carpeta learn tiene todo esto como 08-when-it-goes-wrong.singe: es el juego de la lección siete con un informe cada dos segundos más o menos, una línea cuando te dan y una línea cuando termina la partida.

La segunda forma de ver el interior es ponerlo en pantalla, que es mejor para cualquier cosa que cambie en cada fotograma, porque sesenta líneas por segundo en una terminal no sirven de nada, pero un número que va cambiando en una esquina es fácil de vigilar:

    if DEBUG then
        overlayPrint(1, 3, "BLOCKS " .. #blocks .. "   PLAYER " .. playerX)
    end

Partir el problema por la mitad

Cuando no ves cuál de veinte líneas está mal, deja de mirar y empieza a quitar.

Pon dos guiones al principio de una línea y Lua ignora el resto. Eso es un comentario, y lo normal es usarlo para dejarte notas, pero el mejor uso es este:

    -- overlayPrint(1, 1, "SCORE " .. score .. "    LIVES " .. lives)

Comenta la mitad de drawGame y ejecútalo. Si el problema sigue ahí, está en la mitad que has dejado. Si ha desaparecido, está en la mitad que has quitado. Vuelve a poner esa mitad y pártela a ella por la mitad. Veinte líneas son cinco rondas de esto, y cada ronda es guardar una vez y mirar una vez.

Funciona con algo más que líneas. Comenta el cuerpo de updatePlaying y los bloques dejan de moverse, lo que te dice si lo que persigues está en el movimiento o en el dibujo. Comenta la rama de collideRects y mira si el juego deja de caerse. Mientras haces esto no intentas arreglar nada. Intentas averiguar dónde no está.

Dar vueltas más deprisa

Todo esto depende de poder probar algo en un par de segundos, y para eso está -R. Lo usas desde la lección uno; esto es lo que hace de verdad, y vale la pena saberlo ahora que vas a apoyarte en él.

Singe vigila cada archivo de script que ha cargado tu juego. Cuando guardas uno, el juego vuelve a empezar desde el principio: todo lo que había creado el script se tira y tu archivo se ejecuta de nuevo, en lo que se tarda en leer el archivo y no en lo que se tarda en arrancar el motor. F5 hace lo mismo cuando quieras, sin guardar nada.

Una tecla que mantienes pulsada durante una recarga se ignora hasta que la sueltas, así que el jugador no se irá corriendo él solo después de una recarga.

Los dos tipos de parada se comportan de forma distinta aquí, y es útil saber cuál estás viendo sin leer el mensaje. Un script que no compila se imprime y Singe sigue vivo: la ventana sigue abierta y vacía, el archivo sigue vigilado, y guardar el arreglo devuelve el juego. Un fallo dentro de un callback — todos los mensajes attempt to y las quejas del motor sobre los argumentos — tumba a Singe, y lo vuelves a arrancar a mano.

Leer una traza

Las líneas que hay debajo de stack traceback: son la lista de funciones que estaban en marcha cuando todo se paró, empezando por la más interna. Aquí está otra vez la de blocl:

	dodge/dodge.singe:60: in function 'spawnBlock'
	dodge/dodge.singe:92: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

Léela de abajo arriba y es una frase. Singe llamó a onOverlayUpdate. En la línea 136, onOverlayUpdate llamó a updatePlaying. En la línea 92, updatePlaying llamó a spawnBlock. En la línea 60, spawnBlock se rindió.

La línea de arriba es donde se rompió. Las líneas de debajo son cómo llegó ahí, y son lo que necesitas cuando la línea de arriba parece inocente. Una función que suma un número a block.y no está mal; una función que metió un bloque en la lista sin una y sí lo está. Solo el rastro une las dos, y el rastro se te imprime todas y cada una de las veces.

La costumbre

Todo lo de arriba es técnica. Esto es la costumbre, y importa más:

Cambia una cosa. Ejecútalo. Mira lo que ha pasado.

Cuando algo no funciona, la tentación es cambiar cuatro cosas a la vez, porque seguro que una de ellas es la buena. Hazlo y dejará de funcionar de una forma nueva, y ahora no sabrás cuál de las cuatro ha sido, ni si dos de ellas se están anulando entre sí. Has hecho el problema más grande y lo has escondido mejor.

Un cambio. Ejecutar. Mirar. Parece más lento. Es lo más rápido que hay, y todos los programadores con experiencia que conozcas lo hacen, exactamente por la razón que estás a punto de descubrir.

Pruébalo

  1. Conócelos a todos. Comete a propósito en dodge.singe cada una de las cinco equivocaciones de esta lección, de una en una, y lee el mensaje antes de arreglarla. Nunca más te darán miedo.

  2. Vigila dónde nacen. Pon dentro de spawnBlock un debugPrint que imprima la x del bloque nuevo. Juega treinta segundos y luego mira los números. ¿Están repartidos por toda la pantalla, o prefieren un extremo?

  3. Apágalo. Cambia DEBUG a false en el script de la lección, y comprueba por ti mismo que no se imprime nada y que el juego no ha cambiado.

  4. Un fallo sin error. En updatePlaying, cambia if spawnTimer ⇐ 0 then por if spawnTimer == 0 then, que parece querer decir lo mismo. Ejecútalo y empieza una partida. No hay ningún error, nada se cae y no cae ni un solo bloque, así que ni siquiera puedes perder. Pon un debugLog dentro de spawnBlock, añade spawnTimer a la primera línea que imprime debugReport y vuelve a jugar. Averigua por lo que dicen, y por lo que uno de ellos no dice nunca, por qué == era la pregunta equivocada.

  5. Rompe el nombre de un callback. Cambia el nombre de onInputPressed por onInputPress y ejecútalo. No se imprime ningún error, nada se cae, el jugador no se mueve y la barra espaciadora no empieza una partida. Luego explícate a ti mismo por qué esa es la equivocación más peligrosa de esta lección.

Lo que has aprendido

  • Los errores tienen un archivo, una línea y una queja. Léelos en ese orden.

  • Error running script significa que no se ha ejecutado nada; la forma con traza significa que estaba funcionando y se paró.

  • nil es un nombre sin nada detrás, y está detrás de la mayoría de los mensajes de error que verás en tu vida.

  • La palabra entre paréntesis nombra la cosa vacía, y dice si era un global, un local, un campo o un upvalue.

  • Un end que falta se señala al final del archivo, y los paréntesis te dicen dónde está de verdad la equivocación.

  • Las quejas del motor tienen otro aspecto: un número de línea, un nombre de función y lo que quería en su lugar.

  • debugPrint te enseña lo que guarda de verdad una variable. tostring hace que cualquier cosa se pueda imprimir, y un interruptor como DEBUG quita el ruido.

  • Comenta una mitad con -- para averiguar en qué mitad está el problema.

  • Un callback mal escrito no produce ningún error, y eso lo hace peor que uno que sí lo produce.

  • Cambia una cosa, ejecútalo, mira.

La próxima vez

Ese es el final de la primera parte. Sabes escribir un juego, y ahora sabes arreglarlo, lo que significa que todo lo que viene a partir de aquí es añadir y no poner cimientos. La segunda parte empieza cambiando esas cajas de colores por imágenes de verdad, y a partir de ahí el juego que has estado construyendo empieza a parecer un juego al que otra persona querría jugar.

Lección 9: Imágenes

La lección terminada

Todo lo que has dibujado hasta ahora lo dibujaste con cajas, líneas y el texto sencillo del propio motor. Fue a propósito: ocho lecciones sin arte eran ocho lecciones en las que nada podía salir mal salvo tu programa. Ahora las cajas se convierten en una nave y unas rocas.

Una imagen que el motor dibuja en el overlay se llama sprite. Esta lección los carga, los dibuja, los mide, los pone en el orden correcto y recorre una imagen que guarda varios fotogramas de una animación. Al final, el juego de la lección siete parece un juego.

El kit de arte

No tienes que dibujar nada. Este libro trae una pequeña carpeta de arte, y todo lo de esta lección y de la siguiente la usa.

Busca la carpeta art que vino con el libro y copia la carpeta entera en la carpeta de esta lección, junto a tu script. Deberías acabar con esto:

singe/                 <- tu carpeta de trabajo
    Singe/
    data/
    rocks/
        rocks.singe
        art/
            spaceship.png
            asteroid.png
            bullet.png
            star.png
            walk.png
            shoot.wav
            boom.wav

Tu arte va dentro de la propia carpeta de tu juego, y la carpeta Singe del motor se queda donde está, fuera, en la carpeta de trabajo. Eso importa dentro de un momento, porque decide cómo nombras un archivo cuando lo cargas.

La carpeta Singe es la que el motor desempaquetó para ti la primerísima vez que lo ejecutaste, allá en la lección uno. Vale la pena saber qué hay dentro, porque esos archivos también puedes usarlos tú y todos los lectores de este libro los tienen:

  • Singe/click.wav — un clic corto, que el menú del propio motor usa para su prueba de sonido.

  • Singe/FreeSansBold.ttf — una fuente TrueType, para la lección diecinueve.

  • Singe/menuIntro.flac — la música que suena en el menú del motor. La usarás en la lección diez.

  • Singe/menuBackground.mkv — un vídeo, para la lección catorce.

  • Singe/DragonModel.glb y Singe/SingeText.glb — dos modelos 3D, para la lección veintitrés.

  • Singe/missing.png — la imagen que dibuja el motor cuando un juego pide una que no encuentra.

Las imágenes del kit son pequeñas a propósito. La nave mide 32 píxeles de ancho y 24 de alto, una roca 24 por 24, un disparo 4 por 10 y una estrella 8 por 8. Suena diminuto hasta que recuerdas lo grande que es en realidad la pantalla, que es lo siguiente que hay que aclarar.

Cuánto mide la pantalla

Sin un vídeo que reproducir, Singe le da a tu juego un lienzo de 720 píxeles de ancho y 480 de alto, y la superficie en la que dibujas — el overlay — mide la mitad en cada dirección: 360 por 240. Singe lo estira para que llene la ventana, así que una nave de 32 píxeles ocupa más o menos una décima parte del ancho de la pantalla, que es aproximadamente lo que ocupa una nave en un juego de recreativa.

Nunca escribas 360 y 240 en tu programa. Pregunta:

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()

Esas dos te dan el tamaño del overlay, y un juego que pregunta es un juego que sigue funcionando cuando alguien lo ejecuta a otro tamaño.

Hay una cosa que no cuenta en esos píxeles: overlayPrint, de la lección uno, cuenta en celdas de carácter. Cada celda mide 6 píxeles de ancho y 13 de alto, así que un overlay de 360 por 240 son 60 columnas por 18 filas de texto. Los sprites van en píxeles, overlayPrint va en celdas, y confundir las dos cosas te puede costar una tarde de desconcierto si te dejas.

Una imagen en pantalla

Empieza un archivo nuevo junto a tu carpeta art y escribe esto.

dofile("Singe/Framework.singe")

local ship = spriteLoad(DIR .. "art/spaceship.png")


function onOverlayUpdate()
    overlayClear()
    spriteDraw(ship, 160, 100)
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(ship)
end

Ejecútalo. Una pequeña nave azul aparece cerca del centro de una pantalla negra, apuntando hacia arriba.

Qué acaba de pasar

Cuatro cosas nuevas, de una en una.

local ship = spriteLoad(DIR .. "art/spaceship.png")

spriteLoad lee un archivo de imagen del disco, lo decodifica y guarda la imagen en memoria. Lo que te devuelve no es la imagen. Es un handle: un número normal y corriente, un resguardo, la forma que tiene el motor de decir «ese». Le devuelves ese número al motor cada vez que quieres hacer algo con la imagen, y nunca necesitas saber ni preocuparte de qué número es.

Imprímelo si quieres — debugPrint(ship) de la lección ocho te enseñará un número pequeño — pero el número en sí no es asunto tuyo, y nada en tu programa debería depender nunca de cuál resulte ser. La única regla es que lo guardes en algún sitio donde puedas volver a cogerlo, que es justo para lo que sirve una variable.

DIR también es nuevo, y resuelve un problema que crea la organización que usas desde la lección uno. Singe busca los archivos a partir de la carpeta en la que estabas cuando lo arrancaste, no a partir de tu script. Lo arrancas desde tu carpeta de trabajo, así que un simple art/spaceship.png hace que el motor busque singe/art/spaceship.png, fuera, junto a la carpeta Singe. Tu arte no está ahí. Está un nivel más abajo, en rocks/art/spaceship.png, con tu script.

DIR cierra ese hueco. Es un trozo de texto que guarda la carpeta en la que está tu script, con la barra ya puesta al final, así que DIR .. "art/spaceship.png" — unir dos trozos de texto con .., cosa que haces desde la primera parte — nombra la imagen correctamente sea cual sea la forma en que se arrancó el juego, y la sigue nombrando correctamente cuando mueves la carpeta entera a otro sitio.

DIR es uno de los nombres que define Singe/Framework.singe, que es para lo que está la línea dofile del principio de tu script. Conociste esa línea y lo que contiene en la lección siete, y este es el momento en que se gana su sitio: sin ella no hay DIR, y sin DIR el motor no encuentra tu nave.

Usa DIR en cada archivo que cargue tu juego, desde aquí hasta el final del libro.

    spriteDraw(ship, 160, 100)

Dibuja el sprite de ese handle, en esa posición. Como todas las llamadas de dibujo, solo funciona dentro de onOverlayUpdate.

La posición es la esquina superior izquierda de la imagen, no su centro. Pide (160, 100) y el píxel de más arriba a la izquierda de la nave cae ahí, y el resto cuelga hacia abajo y hacia la derecha. Esto le pasa a todo el mundo una vez, normalmente cuando intenta centrar algo y le sale desplazado hacia abajo y a la derecha la mitad de su propio tamaño.

Si prefieres dar el centro, dilo:

    spriteDraw(ship, 160, 100, true)

Un cuarto argumento true significa «trata ese punto como el centro». Las dos formas están en la entrada de spriteDraw en la referencia, junto con otras dos que estiran la imagen hasta llenar un rectángulo.

function onShutdown()
    spriteUnload(ship)
end

onShutdown es un callback, como onOverlayUpdate y los dos callbacks de entrada de la lección tres. El motor lo llama una vez, cuando tu juego está terminando. Es donde devuelves lo que cogiste: spriteUnload libera la imagen y tira el handle.

En rigor, podrías no ponerlo. El motor libera todo lo que cargó tu script cuando termina el juego, así que un spriteUnload olvidado no es una fuga. Escríbelo de todos modos. Cuesta una línea, dice qué cosas son de tu programa, y dentro de un momento verás el caso en el que olvidarse de descargar sí importa de verdad.

Un aviso sobre ese handle: una vez que has descargado un sprite, el número está muerto. Dibujar con él no se limita a no dibujar nada: termina tu juego con un error.

La transparencia, y por qué es un PNG

La nave es un triángulo con dos aletas. El archivo en el que vive es un rectángulo, de 32 por 24, porque todos los archivos de imagen son rectángulos. Entonces, ¿qué ha pasado con las esquinas?

Son transparentes. Un PNG puede decir, para cada píxel, lo sólido que es, y las imágenes del kit dicen «aquí no hay nada» para cada píxel que queda fuera de la forma. Singe lo respeta, así que el fondo negro se ve a través de las esquinas y la nave tiene un contorno en lugar de una caja alrededor.

Esta es la razón de que el kit sea PNG y no JPEG. Un JPEG no puede guardar transparencia en absoluto — te daría la nave dentro de una caja gris — y además emborrona los bordes nítidos, que es lo último que necesita el arte pequeño. Para el arte de un juego, PNG. Para una fotografía que llena toda la pantalla y no tiene partes transparentes, JPEG está bien y ocupa mucho menos. La entrada de spriteLoad en la referencia enumera todos los formatos que Singe sabe leer, y son muchos.

Pruébalo tú mismo: cambia el negro por otra cosa dibujando una caja detrás de la nave antes de dibujar la nave. Las esquinas mostrarán lo que haya detrás, que es de lo que se trata.

No cargues mientras dibujas

Este es el error que esta sección existe para evitar. Parece completamente razonable:

function onOverlayUpdate()
    overlayClear()
    local ship = spriteLoad(DIR .. "art/spaceship.png")
    spriteDraw(ship, 160, 100)
    return OVERLAY_UPDATED
end

Ejecútalo y funciona. Dibuja la nave. Nada se queja. No tendrías ningún motivo para pensar que algo va mal.

onOverlayUpdate se ejecuta unas sesenta veces por segundo. Eso son sesenta copias nuevas de la nave cargadas en memoria cada segundo, tres mil seiscientas por minuto, y ni una sola se descarga nunca. El juego funciona de maravilla durante dos minutos, se vuelve más lento, y luego la máquina se queda sin memoria y el juego se muere. Peor aún: se muere durante la demostración y no mientras lo estabas probando.

La regla: carga una vez, dibuja muchas. Cargar es lento y ocupa memoria. Dibujar es rápido y no ocupa nada. Así que spriteLoad va al principio de tu archivo, fuera de todas las funciones, donde se ejecuta una sola vez al empezar el script.

Esto no va solo de sprites. Todos los somethingLoad del motor funcionan así — los sonidos en la lección diez, las fuentes en la lección diecinueve, los modelos en la lección veintitrés. Si te descubres escribiendo Load dentro de una función que se ejecuta en cada fotograma, para y sácalo de ahí.

¿Cuánto mide?

Sabes que la nave mide 32 por 24 porque te lo ha dicho este libro. Tu programa no lo sabe, y no debería tener que saberlo. Pregunta:

local shipWidth  = spriteGetWidth(ship)
local shipHeight = spriteGetHeight(ship)

Ahora puedes mantener la nave dentro de la pantalla, porque la posición más a la derecha en la que puede estar es screenWidth - shipWidth, y ponerla en el centro, porque el centro es (screenWidth - shipWidth) / 2. Ninguna de las dos líneas tiene un número que hubiera que cambiar si alguien volviera a dibujar la nave un poco más grande.

Las dos dan el tamaño tal como se dibujaría el sprite ahora mismo. Si alguna vez escalas o giras un sprite, con spriteScale o spriteRotate, la respuesta cambia para coincidir. Normalmente es lo que quieres, y te sorprenderá exactamente una vez.

El orden de dibujo

Los sprites no se mezclan. Lo de después tapa lo de antes, píxel a píxel, exactamente igual que pegar recortes de papel en una pared. Así que el orden de tus llamadas a spriteDraw es el orden de atrás hacia delante:

    drawStars()
    drawRocks()
    drawShots()
    spriteDraw(shipSprite, shipX, shipY)
    drawHud()

Las estrellas son lo que está más al fondo, así que van primero. La nave está delante de todo lo que hay en la zona de juego. La puntuación va encima de todo. Hazlo al revés y tu nave tan cuidadosamente dibujada se pasará la partida escondida detrás del campo de estrellas, y no habrá ningún error que te lo diga — solo una nave que no puedes ver.

overlayClear sigue yendo lo primero, antes de todo eso. Dibujar nunca sustituye, solo tapa, así que el fotograma empieza vacío cada vez.

Fotogramas

Abre art/walk.png en cualquier visor de imágenes. No es la imagen de una persona. Es la imagen de cuatro personas, una junto a otra: la misma figura en cuatro momentos de un paso, cada una de 24 píxeles de ancho en una tira de 96.

Una imagen que guarda varios fotogramas de una animación es una hoja de sprites, y es como se guarda casi toda la animación 2D. Un archivo, una carga, un handle, y el juego elige qué trozo dibujar.

Crea un segundo archivo, walk.singe, junto al primero:

dofile("Singe/Framework.singe")

local walk      = spriteLoadFrames(4, DIR .. "art/walk.png")
local walkFrame = 1
local walkTick  = 0
local walkX     = 0


function onOverlayUpdate()
    overlayClear()
    walkTick = walkTick + 1
    if walkTick >= 8 then
        walkTick  = 0
        walkFrame = walkFrame + 1
        if walkFrame > 4 then
            walkFrame = 1
        end
    end
    walkX = walkX + 1
    if walkX > overlayGetWidth() then
        walkX = -spriteFrameWidth(walk)
    end
    spriteDrawFrame(walk, walkX, 100, walkFrame)
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(walk)
end

Ejecútalo con Singe rocks/walk.singe. Una figurita cruza la pantalla caminando a paso constante, desaparece por el borde derecho y vuelve a entrar por la izquierda.

spriteLoadFrames es spriteLoad con una cosa más que decir: cuántos fotogramas hay en la tira. La cuenta va primero, antes del nombre del archivo, que es lo contrario de lo que casi todo el mundo supone. Divide el ancho de la imagen entre la cuenta y recuerda los trozos. Cuatro fotogramas en una tira de 96 píxeles son cuatro fotogramas de 24 píxeles de ancho. Equivócate con la cuenta — pon 3, por ejemplo — y tendrás tres trozos de 32 píxeles, cada uno con partes de dos figuras, que es una forma memorablemente tonta de descubrir que has escrito el número equivocado.

spriteDrawFrame dibuja un trozo. Recibe el handle, dónde ponerlo y qué fotograma, en ese orden, y los fotogramas se numeran desde 1: el fotograma 1 es la figura de más a la izquierda y el fotograma 4 la de más a la derecha.

Cuidado con ese 1. En otras partes de la familia de los sprites — spriteSetFrame y spriteGetFrame — los fotogramas se numeran desde 0. Es un accidente histórico, las dos están en la referencia, y este libro usa spriteDrawFrame y cuenta desde 1.

spriteFrameWidth da el ancho de un fotograma, 24 aquí, en lugar de los 96 de la tira entera. spriteFrameHeight es su pareja. Cuando quieras saber cuánto mide de ancho un trozo de una hoja, esas son las dos a las que preguntar, y no spriteGetWidth.

El número de fotograma es un número en una variable como cualquier otro, así que caminar es aritmética:

    walkTick = walkTick + 1
    if walkTick >= 8 then
        walkTick  = 0
        walkFrame = walkFrame + 1
        if walkFrame > 4 then
            walkFrame = 1
        end
    end

Cuenta los fotogramas que van pasando. Cada ocho, pasa a la imagen siguiente, y después de la cuarta imagen vuelve a la primera. Sesenta fotogramas por segundo entre ocho son entre siete y ocho pasos por segundo, lo que para un ciclo de cuatro fotogramas es un paso ligero pero creíble. Cambia el 8 y cambias la velocidad: cuanto más grande, más lento.

Puede que te preguntes por qué cuentas tú, cuando el motor tiene spritePlay para reproducir una animación por ti. Lo tiene, y para un GIF animado es la respuesta correcta, porque un GIF lleva dentro del archivo la duración de cada uno de sus fotogramas. Una tira normal como walk.png no lleva ninguna duración, así que el motor la reproduce tan deprisa como se le permite — cien fotogramas por segundo, veinticinco ciclos completos de paso cada segundo, un borrón. Cuando los fotogramas vienen de una tira, cuenta tú.

El juego recibe su arte

Ahora júntalo todo. El juego de la lección siete movía una caja por la parte de abajo de la pantalla y le dejaba caer otras cajas encima. Cada caja se convierte en una imagen, y ya que estás, la nave recibe algo con lo que disparar.

Los cambios van todos juntos, así que aquí está el script entero. Es más largo que cualquier cosa que hayas escrito, y no tiene nada que no conozcas ya.

dofile("Singe/Framework.singe")

local SHIP_SPEED  = 3
local SHOT_SPEED  = 6
local ROCK_COUNT  = 6
local STAR_COUNT  = 40
local START_LIVES = 3
local HIT_SCORE   = 10

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")
local rockSprite = spriteLoad(DIR .. "art/asteroid.png")
local shotSprite = spriteLoad(DIR .. "art/bullet.png")
local starSprite = spriteLoad(DIR .. "art/star.png")

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()
local shipWidth    = spriteGetWidth(shipSprite)
local shipHeight   = spriteGetHeight(shipSprite)
local rockWidth    = spriteGetWidth(rockSprite)
local rockHeight   = spriteGetHeight(rockSprite)
local shotWidth    = spriteGetWidth(shotSprite)
local shotHeight   = spriteGetHeight(shotSprite)

local shipX   = (screenWidth - shipWidth) / 2
local shipY   = screenHeight - shipHeight - 4
local goLeft  = false
local goRight = false
local rocks   = {}
local shots   = {}
local stars   = {}
local score   = 0
local lives   = START_LIVES
local over    = false


function drawHud()
    overlayPrint(1, 1, "SCORE " .. score)
    overlayPrint(50, 1, "LIVES " .. lives)
    if over then
        overlayPrint(25, 8, "GAME OVER")
        overlayPrint(17, 10, "PRESS 1 TO PLAY AGAIN")
    end
end


function drawRocks()
    for _, rock in ipairs(rocks) do
        spriteDraw(rockSprite, rock.x, rock.y)
    end
end


function drawShots()
    for _, shot in ipairs(shots) do
        spriteDraw(shotSprite, shot.x, shot.y)
    end
end


function drawStars()
    for _, star in ipairs(stars) do
        spriteDraw(starSprite, star.x, star.y)
    end
end


function newRock(rock)
    rock.x     = math.random(0, screenWidth - rockWidth)
    rock.y     = -rockHeight - math.random(0, 160)
    rock.speed = math.random(8, 20) / 10
end


function onInputPressed(what)
    if over then
        if what == SWITCH_START1 then
            startGame()
        end
        return
    end
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        goLeft = false
    elseif what == SWITCH_RIGHT then
        goRight = false
    end
end


function onOverlayUpdate()
    overlayClear()
    updateStars()
    if not over then
        updateShip()
        updateShots()
        updateRocks()
    end
    drawStars()
    drawRocks()
    drawShots()
    spriteDraw(shipSprite, shipX, shipY)
    drawHud()
    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(shipSprite)
    spriteUnload(rockSprite)
    spriteUnload(shotSprite)
    spriteUnload(starSprite)
end


function overlapping(ax, ay, aw, ah, bx, by, bw, bh)
    if ax + aw <= bx then
        return false
    end
    if bx + bw <= ax then
        return false
    end
    if ay + ah <= by then
        return false
    end
    if by + bh <= ay then
        return false
    end
    return true
end


function startGame()
    shipX = (screenWidth - shipWidth) / 2
    score = 0
    lives = START_LIVES
    over  = false
    shots = {}
    for i = 1, ROCK_COUNT do
        rocks[i] = {}
        newRock(rocks[i])
    end
end


function updateRocks()
    for _, rock in ipairs(rocks) do
        rock.y = rock.y + rock.speed
        if rock.y > screenHeight then
            newRock(rock)
        end
        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                over = true
            end
        end
    end
end


function updateShip()
    if goLeft then
        shipX = shipX - SHIP_SPEED
    end
    if goRight then
        shipX = shipX + SHIP_SPEED
    end
    if shipX < 0 then
        shipX = 0
    end
    if shipX > screenWidth - shipWidth then
        shipX = screenWidth - shipWidth
    end
end


function updateShots()
    for i = #shots, 1, -1 do
        local shot = shots[i]
        local gone = false

        shot.y = shot.y - SHOT_SPEED
        if shot.y + shotHeight < 0 then
            gone = true
        end
        for _, rock in ipairs(rocks) do
            if not gone and overlapping(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then
                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
            end
        end
        if gone then
            table.remove(shots, i)
        end
    end
end


function updateStars()
    for _, star in ipairs(stars) do
        star.y = star.y + star.speed
        if star.y > screenHeight then
            star.y = 0
            star.x = math.random(0, screenWidth - 1)
        end
    end
end


for i = 1, STAR_COUNT do
    stars[i] = { x = math.random(0, screenWidth - 1), y = math.random(0, screenHeight - 1), speed = math.random(1, 3) / 4 }
end

startGame()

Las flechas izquierda y derecha dirigen la nave. La barra espaciadora dispara. Cuando las rocas se han llevado tu última vida, 1 empieza una partida nueva.

Vale la pena señalar algunas cosas de ahí dentro.

Las cuatro llamadas a spriteLoad y las ocho medidas están arriba, fuera de todas las funciones, así que ocurren una vez. Todo lo que viene después está escrito en términos de screenWidth, shipWidth y compañía, y no hay ni una cantidad de píxeles a pelo en todo el código del juego.

Las funciones están en orden alfabético, que es una costumbre que vale la pena coger ya. A Lua no le importa lo más mínimo — es para ti, dentro de seis meses, buscando updateShots en un archivo con cuarenta funciones.

Las dos últimas cosas del archivo no son funciones. Son instrucciones normales al final del script: construir el campo de estrellas y luego llamar a startGame para preparar las rocas y poner a cero la puntuación. Se ejecutan una vez, en orden, al cargarse el script, y tienen que ir después de las funciones que usan.

overlapping son las cuatro comparaciones que la lección siete decía que podías escribir tú en lugar de llamar a collideRects, escritas como una función con los mismos ocho argumentos. Dos rectángulos no se tocan si uno está completamente a la izquierda, a la derecha, por encima o por debajo del otro; si ninguna de esas cuatro cosas es cierta, se solapan. La lección once la sustituye por algo que pone el motor, y explica por qué el rectángulo es la forma equivocada para una nave.

Una última nota para cuando leas código de Singe de otras personas. Todas las llamadas de sprites de este libro reciben el handle primero. Singe 2.10 lo ponía al final, y un juego puede pedirle al motor que siga haciéndolo así, de modo que el código que encuentres en internet puede decir spriteDraw(x, y, ship). No lo copies. El handle primero es el orden actual y el que documenta la referencia.

Pruébalo

  1. Centra la nave en su posición. Añade true como cuarto argumento al spriteDraw de la nave. Fíjate en adónde salta la nave, y deduce por la distancia que se ha movido qué ha hecho de verdad el cuarto argumento.

  2. Más rocas. Cambia ROCK_COUNT a 20. Luego a 200. En algún punto entre esos dos el juego deja de ser jugable, y en algún punto mucho más allá el juego empieza a ir más lento. Encuentra los dos.

  3. Agranda la nave. Añade spriteScale(shipSprite, 2) al final del todo del archivo, en la línea de encima de startGame(). Ejecútalo y lleva la nave contra el borde derecho: la nave mide el doble pero sigue parándose donde se paraba la pequeña, y se sale por el borde derecho y por abajo. Averigua por qué, y luego sube esa línea por encima de las llamadas a spriteGetWidth y mira cómo se arregla. La entrada de spriteScale en la referencia explica lo que hace el escalado con las medidas.

  4. Mete al caminante. Carga walk.png en el juego, y dibuja la figura que camina por la parte de arriba de la pantalla como decorado. Necesitarás el conteo de fotogramas del script del paseo, y tendrás que decidir en qué parte de onOverlayUpdate va el dibujo — delante de las estrellas, detrás de las rocas.

  5. Descarga algo que todavía estás usando. Añade spriteUnload(starSprite) al final del archivo, después de startGame(), y ejecútalo. Lee lo que te sale.

Rómpelo a propósito

Las mayúsculas importan, y el arte es donde más muerden. Cambia la carga de la nave para que use una S mayúscula:

local shipSprite = spriteLoad(DIR .. "art/Spaceship.png")

El juego se niega a arrancar:

10:spriteLoad:  Couldn't open rocks/art/Spaceship.png: No such file or directory

Léelo igual que el error de la lección uno, pero fíjate en que la forma es un poco distinta. 10 es la línea. spriteLoad es la función del motor que se ha rendido, en lugar de un nombre de archivo — cuando la queja viene de Singe y no de Lua, esto es lo que te sale. Luego la razón, que aquí son las palabras del propio sistema operativo y cambiará un poco de una máquina a otra.

No such file or directory es el ordenador siendo preciso, no antipático. De verdad no hay ningún archivo llamado Spaceship.png; hay uno llamado spaceship.png, y para una máquina Linux son dos nombres distintos. En Windows, y en la mayoría de los Mac, habría funcionado, lo cual es peor, porque significa que el fallo viaja al ordenador de otra persona y aparece allí por primera vez.

La otra mitad de este error con la que te encontrarás es la carpeta. Si pusiste el kit de arte en el sitio equivocado, o arrancaste Singe desde la carpeta equivocada, el mensaje es exactamente el mismo y el arreglo no. La ruta del mensaje ayuda: es el nombre completo que probó Singe, contado desde la carpeta en la que lo arrancaste, y el rocks/ del principio es la parte que añadió DIR. Comprueba tres cosas, en este orden: si el archivo se llama exactamente como lo escribiste, si está en la carpeta art, y si esa carpeta art está junto a tu script.

Lo que has aprendido

  • Una imagen dibujada en el overlay es un sprite, y se carga con spriteLoad.

  • spriteLoad te devuelve un handle: un número que para el motor significa «esa imagen», y que guardas en una variable.

  • DIR es la carpeta en la que está tu script, y cada archivo que cargue tu juego debería nombrarse con él.

  • spriteDraw(handle, x, y) lo dibuja, desde su esquina superior izquierda, y solo dentro de onOverlayUpdate. Un cuarto argumento true hace que la posición sea el centro.

  • Carga una vez, al principio del archivo. Cargar dentro de onOverlayUpdate se come la memoria hasta que el juego se muere.

  • spriteUnload devuelve una imagen, normalmente desde onShutdown, y después el handle está muerto.

  • El PNG lleva transparencia, y por eso las esquinas de la nave no son cajas negras.

  • spriteGetWidth y spriteGetHeight miden un sprite tal como se dibujaría ahora, así que nunca tienes que escribir su tamaño en tu programa.

  • Los sprites se tapan unos a otros. El orden en que dibujas va de atrás hacia delante.

  • spriteLoadFrames(count, file) corta una tira en fotogramas, y spriteDrawFrame(handle, x, y, frame) dibuja uno de ellos, contando desde 1.

La próxima vez

El juego se ve bien y no suena a nada. En la lección diez los disparos tienen un ruido, las rocas una explosión, y algo suena por debajo de todo — y conocerás tu quinto callback, el que usa el motor para decirte que un sonido ha terminado.

Lección 10: Sonido

La lección terminada

Un juego sin sonido parece roto de una forma difícil de señalar. Los disparos salen y no pasa nada. Las rocas se rompen y no pasa nada. Ponle a cada una de esas cosas un ruido de medio segundo y, de repente, el mismo juego parece hecho de algo.

Esta lección le da a tu juego un disparo, una explosión y música de fondo. Por el camino te presenta tu quinto callback: el que usa el motor para decirte que un sonido ha terminado de sonar.

Un ruido

El kit de arte que copiaste en la lección nueve trae dos sonidos, shoot.wav y boom.wav, y de los dos la explosión es la que mejor se oye. Crea un archivo nuevo junto a tu carpeta art y escribe esto.

dofile("Singe/Framework.singe")

local boom = soundLoad(DIR .. "art/boom.wav")


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        soundPlay(boom)
    end
end


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Press space.")
    return OVERLAY_UPDATED
end


function onShutdown()
    soundUnload(boom)
end

Ejecútalo y pulsa la barra espaciadora tres o cuatro veces, rápido. Los estallidos se amontonan unos encima de otros en lugar de cortarse entre sí.

Mantener pulsada la barra espaciadora te da exactamente un estallido, no un chorro de ellos. Es el mismo comportamiento que viste en la lección tres: una tecla mantenida es una sola pulsación, que se avisa una vez, y el motor tira las repeticiones que manda tu teclado. Por eso, para mover la nave, hace falta onInputReleased y una variable en lugar de contar pulsaciones.

Qué acaba de pasar

La forma es la misma que en la lección nueve: cargar una vez arriba, usar el handle y devolverlo al final.

local boom = soundLoad(DIR .. "art/boom.wav")

soundLoad lee un archivo de audio, lo guarda en memoria y te devuelve un handle — la misma idea que el handle de un sprite, un número que para el motor significa «ese clip». DIR está ahí por la misma razón que en la lección nueve: el sonido vive en la carpeta de tu juego, y el juego tiene que poder encontrarlo desde dondequiera que se haya arrancado Singe.

Todo lo que dijo la lección nueve sobre cargar vale aquí palabra por palabra. Carga arriba del todo del archivo, una vez. Un soundLoad dentro de onOverlayUpdate carga el clip sesenta veces por segundo y no devuelve ninguno, y el juego se muere de eso unos minutos después.

        soundPlay(boom)

Reprodúcelo. Eso es todo lo que hace falta para reproducir un efecto de sonido, y el motor se encarga del resto: el clip empieza, termina y nunca le estorba a tu programa.

Pero soundPlay también devuelve algo, y no es el mismo número que le diste. Cambia la línea y mira:

        local channel = soundPlay(boom)
        debugPrint("clip " .. boom .. " on channel " .. channel)

Pulsa la barra espaciadora rápido media docena de veces y mira los dos números. El número del clip no cambia nunca. El número del canal sube — 0, luego 1, luego 2 — y en cuanto terminan los estallidos anteriores vuelve a bajar y empieza a reutilizar los números bajos.

Esto es lo único del sonido que pilla a todo el mundo, así que vale la pena decirlo despacio. Hay dos tipos distintos de número en juego.

El handle del clip que da soundLoad es la grabación. Solo hay uno. No cambia, no está ni sonando ni callado: es el sonido guardado en memoria, esperando a que lo uses.

El canal que da soundPlay es una reproducción de esa grabación. Singe tiene dieciséis, numerados del 0 al 15, y cada sonido que se oye en este momento está usando uno. Por eso los estallidos se solapan: la segunda pulsación no interrumpió la primera, sino que empezó una segunda reproducción en el siguiente canal libre.

Todo lo que actúa sobre un sonido que puedes oír recibe un canal: soundStop, soundIsPlaying, soundPause, soundResume. Todo lo que actúa sobre la grabación recibe el handle: soundPlay y soundUnload. Si pasas uno donde va el otro, no siempre te saldrá un error, porque 3 es un número de canal válido y también un handle de clip perfectamente bueno — te saldrá silencio, o se parará el sonido equivocado, y eso cuesta mucho más encontrarlo.

Dieciséis son muchos, pero no infinitos. Cuando todos los canales están ocupados, no suena nada y soundPlay devuelve -1 en lugar de un número de canal. Un juego que lanza muchísimos sonidos a la vez debería contar con ello, y vas a escribir uno dentro de un momento.

Volumen

Hay tres volúmenes, y se multiplican entre sí.

El volumen general de los efectos lo abarca todo. soundGetVolume lo lee y soundSetVolume lo cambia, en una escala de 0 a 63.

    soundSetVolume(40)

Resiste. Ese número es del jugador, no tuyo: empieza en lo que pidiera al lanzar el juego, y un juego que lo sobrescribe es un juego que suena demasiado alto en la habitación tranquila de alguien. Cambia el volumen general solo cuando te lo pida el jugador, desde una pantalla de opciones. soundGetVolume existe para que una pantalla de opciones pueda mostrar cuál es ahora en lugar de adivinarlo.

Lo que deberías usar es el volumen del canal, que está por debajo del general. Dale a soundPlay un tercer argumento y solo esa reproducción sonará más baja:

    soundPlay(shootClip, 0, 35)

El 0 del medio es cuántas veces repetirlo, y tienes que ponerlo porque el volumen va detrás. 0 significa reproducirlo una vez. -1 significa repetirlo en bucle hasta que algo lo pare, que es como harías el zumbido de un motor o el viento. La entrada de soundPlay en la referencia enumera los tres argumentos.

El tercer volumen es la distancia, para sonidos colocados en un mundo 3D. Eso queda para la cuarta parte, cuando el juego pase a tres dimensiones.

La música tiene su propio volumen, y va en otra escala. Enseguida hablamos de eso.

Parar y no parar

soundStop recibe un canal y lo corta allí donde esté:

    soundStop(engineChannel)
    engineChannel = -1

Fíjate en la segunda línea. En cuanto un canal se para, el motor puede darle ese mismo número al siguiente soundPlay, así que un número de canal que todavía guardas puede pertenecer ahora a un sonido completamente distinto. Tíralo en el momento en que lo pares. -1 es lo útil que poner ahí, porque es el mismo valor que te da soundPlay cuando no ha podido reproducir nada, así que una sola comprobación cubre los dos casos: if channel >= 0 then.

soundStop es para un sonido que ya no debería sonar — el ruido del motor cuando el motor se rompe, la alarma cuando alguien la atiende. Es la herramienta equivocada para un efecto corto. Una explosión de medio segundo cortada a la décima de segundo suena a error, porque lo es.

Así que, casi siempre, no hagas nada. Deja que termine. Un efecto de sonido que empiezas y en el que no vuelves a pensar termina solo y libera su canal solo, que es exactamente lo que quieres.

Esto vale incluso al final. soundUnload no corta un clip que todavía está sonando: el motor mantiene vivo el audio hasta que se para el último canal que lo usa. Puedes descargar en onShutdown sin preocuparte de haber silenciado algo.

soundIsPlaying(channel) responde si un canal está sonando ahora mismo. Su uso principal no es la curiosidad sino la contención: una alarma que debe sonar una vez, y no volver a empezar cada vez que el juego nota que el peligro sigue ahí.

function raiseAlarm()
    if alarmChannel < 0 or not soundIsPlaying(alarmChannel) then
        alarmChannel = soundPlay(alarmClip)
    end
end

Lee la condición en voz alta: reproduce la alarma si no hay canal de alarma, o si el que tienes se ha parado. Si no, déjala en paz.

El sonido que tartamudea

Aquí está el error. Todo el mundo lo escribe, normalmente en la primera semana después de descubrir el sonido.

Supón que quisieras que la nave siguiera disparando mientras el botón está pulsado, en lugar de una vez por pulsación. Lo harías igual que la dirección: una variable firing que se pone a true en onInputPressed y vuelve a false en onInputReleased, y el disparo se crea en onOverlayUpdate mientras sea verdadera. Es algo perfectamente razonable de querer, y el ruido parece que va justo ahí, con el disparo:

function onOverlayUpdate()
    if firing then
        shots[#shots + 1] = { x = shipX, y = shipY }
        soundPlay(shootClip)
    end
    ...

Lo que sale no es un disparo. Es un traqueteo zumbón, o un tono plano y duro, o un sonido como de una maquinita rompiéndose.

onOverlayUpdate se ejecuta unas sesenta veces por segundo. Mantén el botón un segundo y habrás pedido sesenta reproducciones de un clip que dura más o menos una quinta parte de segundo, cada una empezando encima de la anterior. En cualquier momento hay unas once sonando, cada una un fotograma por detrás de la anterior, y lo que oyes son sesenta copias del mismo ataque amontonadas unas sobre otras.

El arreglo no es un sonido más ingenioso. Es reproducir el sonido donde ocurre el evento y no donde el estado es verdadero:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        soundPlay(shootClip, 0, 35)
    end
end

onInputPressed ocurre una vez, cuando se pulsa el botón. Una pulsación, un disparo, un ruido.

Si de verdad quieres fuego continuo, la respuesta es la misma con otra forma: convierte el propio disparo en un evento. Cuenta fotogramas, exactamente como los contaba el ciclo de caminar en la lección nueve, y crea un disparo solo cada ocho fotogramas. El ruido va con el disparo, así que suena siete u ocho veces por segundo en lugar de sesenta, y eso es una ametralladora y no un traqueteo.

Esa es la regla, y vale la pena llevártela de esta lección: los sonidos van con los eventos, no con las condiciones. Una pulsación, un impacto, una muerte, recoger algo — cada una de esas cosas ocurre una vez y merece un sonido. «El botón está pulsado» y «la nave se mueve» no son eventos; son verdad durante cientos de fotogramas seguidos, y todo lo que reproduzcas a partir de ellos se reproduce cientos de veces.

Cuando un sonido sí pertenece a un estado que dura — un motor, el viento, una sirena — empiézalo una vez con -1 como número de repeticiones, guarda el canal y páralo cuando termine el estado.

El quinto callback

A veces sí necesitas saber cuándo ha terminado un sonido. Escribe esta función y el motor la llamará:

function onSoundCompleted(channel)
end

Ese es tu quinto callback, después de onOverlayUpdate en la lección uno, los dos callbacks de entrada de la lección tres y onShutdown en la lección nueve, y funciona igual que todos ellos: lo escribes tú, nunca lo llamas, y el motor te llama a ti. El channel que te pasa es el canal que acaba de quedarse en silencio — el número que te dio soundPlay cuando lo empezaste.

Salta cuando un clip se acaba, cuando termina la última repetición de un bucle, y cuando paras tú mismo un canal con soundStop. Esto último sorprende a quien usa el callback para encadenar un sonido con el siguiente: parar un canal a propósito también lo da por completado, y si no tienes cuidado el siguiente sonido de la cadena empieza de todos modos.

El juego está a punto de usarlo para algo que merece la pena. Cuando se pierde la última vida, suena la explosión de la nave y el juego se queda quieto — sin GAME OVER, sin que la música se desvanezca — hasta que esa explosión ha terminado de verdad. Entonces todo se para a la vez. Son un puñado de líneas y es la diferencia entre un final y un corte.

La música no es un efecto de sonido

Podrías cargar una canción de tres minutos con soundLoad y reproducirla con soundPlay. No lo hagas. La música tiene su propia familia de llamadas, por razones que importan:

  • La música tiene su propio volumen, separado del de los efectos, para que un jugador pueda bajar la música y seguir oyendo los disparos.

  • No hay límite de dieciséis canales ni número de canal. Un handle es una pieza de música, y la paras, la pausas y la reanudas con ese handle.

  • musicStop puede desvanecer una pieza durante un segundo o dos en lugar de cortarla.

Las llamadas son un reflejo de las que ya conoces:

local theme = musicLoad("Singe/menuIntro.flac")

musicSetVolume(50)
musicPlay(theme, -1)

musicLoad da un handle. musicPlay la empieza, con el mismo número de repeticiones que soundPlay: -1 para siempre. musicStop(theme) la termina, y musicStop(theme, 1500) tarda un segundo y medio en desvanecerla. musicUnload la devuelve.

Ahora, la trampa. El volumen de la música va de 0 a 128, no de 0 a 63. Los efectos de sonido usan una escala y la música otra, el doble de larga, por razones históricas que no consuelan nada cuando tu música sale a la mitad del volumen que querías. Cuando trabajes con música, dobla el número que tenías en mente para un efecto.

La pieza que se carga ahí es la música del menú del propio motor, sacada de la carpeta Singe que el motor desempaquetó en tu carpeta de trabajo la primera vez que lo ejecutaste. Dura diez segundos y se compuso para desvanecerse al final, así que en bucle suena exactamente como un bucle de diez segundos que no para de desvanecerse. Eso está bien para aprender las llamadas y no sirve de nada en un juego terminado, que trae una pieza propia más larga. Cualquiera de los formatos habituales sirve: la sección Música de la referencia los enumera, y Ogg Vorbis o MP3 son las opciones sensatas, porque unos minutos de música en WAV son un archivo enorme.

El juego tiene banda sonora

Abre el juego de la lección nueve. Todo lo de aquí se le añade; no se quita nada.

Cuatro cosas que cargar, arriba, con los sprites:

local shootClip = soundLoad(DIR .. "art/shoot.wav")
local boomClip  = soundLoad(DIR .. "art/boom.wav")
local clickClip = soundLoad("Singe/click.wav")
local theme     = musicLoad("Singe/menuIntro.flac")

Las dos primeras llevan DIR y las dos últimas no, y es a propósito. DIR significa la carpeta de tu juego. Un nombre que empieza por Singe/ significa, en cambio, la carpeta del propio motor, esté donde esté — y por eso dofile("Singe/Framework.singe") ha funcionado desde la lección siete sin DIR tampoco. Tus propios archivos necesitan DIR; los del motor, nunca.

Dos variables nuevas, junto a las demás:

local dying        = false
local deathChannel = -1

dying es el momento entre que se pierde la última vida y que termina la partida: la explosión aún suena y nada se mueve en pantalla.

El disparo recibe su ruido en onInputPressed, justo donde se crea el propio disparo, y el reinicio recibe un clic para que pulsar 1 parezca que ha hecho algo:

function onInputPressed(what)
    if over then
        if what == SWITCH_START1 then
            soundPlay(clickClip)
            startGame()
        end
        return
    end
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
        soundPlay(shootClip, 0, 35)
    end
end

Una roca alcanzada por un disparo estalla, y también una roca que te golpea. En updateShots, junto a la puntuación:

                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
                soundPlay(boomClip, 0, 45)

Y en updateRocks, donde se pierde la vida, la parte interesante:

        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            local channel = soundPlay(boomClip)

            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                dying        = true
                deathChannel = channel
                if channel < 0 then
                    endGame()
                end
            end
        end

Cuando se pierde la última vida, suena la explosión y se guarda su canal. Ahora el juego está en dying, que para todo lo que se mueve pero todavía no dice GAME OVER.

El if channel < 0 es el límite de dieciséis canales, resuelto. Si justo en ese momento todos los canales estuvieran ocupados, no hay explosión ni canal que esperar, y sin esas dos líneas el juego se quedaría en dying para siempre, esperando un sonido que nunca sonó. Esperar algo que no puede llegar es una de las formas más fáciles de colgar un programa, y la protección siempre sale más barata que el fallo.

Ahora el callback nuevo, y la pequeña función que comparte con esa protección:

function endGame()
    dying        = false
    deathChannel = -1
    over         = true
    musicStop(theme, 1500)
end


function onSoundCompleted(channel)
    if channel == deathChannel then
        endGame()
    end
end

El motor llama a onSoundCompleted por cada canal que se para, así que lo primero que hace es comprobar si este es el canal que le importa. Todo lo demás — cada disparo, cada roca — pasa de largo y se ignora.

onOverlayUpdate tiene que quedarse quieto mientras dura la explosión, y eso es una palabra:

    if not over and not dying then
        updateShip()
        updateShots()
        updateRocks()
    end

startGame reinicia las dos variables nuevas y vuelve a empezar la música:

    dying        = false
    deathChannel = -1
    musicSetVolume(50)
    musicPlay(theme, -1)

Y onShutdown devuelve lo que se cargó:

function onShutdown()
    spriteUnload(shipSprite)
    spriteUnload(rockSprite)
    spriteUnload(shotSprite)
    spriteUnload(starSprite)
    soundUnload(shootClip)
    soundUnload(boomClip)
    soundUnload(clickClip)
    musicUnload(theme)
end

Ejecútalo. Dispara a las rocas, deja que una te golpee tres veces y escucha el final: el último estallido suena entero, y solo cuando se ha ido empieza la música a desvanecerse y aparecen las palabras.

El script terminado está en la carpeta learn como 10-sound.singe, por si quieres comparar.

Pruébalo

  1. Baja todavía más el disparo. Cambia el 35 del soundPlay del disparo por 10, y luego por 63. Encuentra el número con el que queda por debajo de las explosiones en lugar de por encima.

  2. Baja la música sin tocar los efectos. Cambia musicSetVolume(50) por musicSetVolume(15). Comprueba que los estallidos suenan exactamente igual de fuerte que antes, que es toda la razón de que la música sea un sistema aparte.

  3. Corta el final. En endGame, cambia musicStop(theme, 1500) por musicStop(theme). Escucha los dos finales dos veces. La diferencia es un número en un argumento, y no es una diferencia pequeña.

  4. Ponle un motor a la nave. Arranca soundPlay(clickClip, -1, 12) en startGame, guarda el canal que te da en una variable propia y páralo en endGame. El clic dura una cincuentava parte de segundo, así que en bucle es un zumbido, que es lo más parecido a un motor que da de sí este kit. Luego vuelve a quitar el soundStop, juega tres partidas seguidas y escucha lo que has construido.

  5. Cuenta los canales. Imprime el número de canal cada vez que explota una roca. Luego sube ROCK_COUNT hasta que exploten varias a la vez, y sigue subiéndolo hasta que veas pasar un -1.

Rómpelo a propósito

Ahora tienes dos escalas de volumen en la cabeza, y tarde o temprano te saldrá de los dedos la equivocada. Añade esta línea suelta, justo debajo de las cuatro líneas de soundLoad y musicLoad:

soundSetVolume(100)

El juego se niega a arrancar:

20:soundSetVolume:  Invalid sound volume value:  100

El número de línea que te sale es la línea en la que de verdad la escribiste, así que puede que el tuyo no sea 20. Luego viene la función que se ha quejado, y el valor del que se ha quejado. El mensaje no te dice cuál es el rango — para eso está la entrada de soundSetVolume en la referencia — pero sí te dice el número que no ha aceptado, y en cuanto sabes que los efectos llegan hasta 63, el arreglo es un número.

100 es un número sospechoso para un volumen, y vale la pena saber por qué lo escribiste. Casi seguro que pensaste en el volumen como un porcentaje, porque todos los controles de volumen que has usado en tu vida llegan a 100. Los de Singe no. Los efectos van de 0 a 63 y la música de 0 a 128, y ninguno es un porcentaje de nada.

Esta es la forma general de un error del motor, a diferencia de los errores de Lua de la lección uno: un número de línea, el nombre de la función del motor que llamaste y una queja sobre los valores que le pasaste. Cuando veas uno, lo siguiente que hay que leer es la entrada de esa función en la referencia.

Lo que has aprendido

  • soundLoad lee un clip y devuelve un handle. Carga una vez, arriba del todo del archivo.

  • soundPlay empieza un clip y devuelve un canal, que es un tipo de número distinto del handle.

  • Singe mezcla dieciséis canales. Cuando están todos ocupados, soundPlay devuelve -1 y no suena nada.

  • Los números de canal se reutilizan. Olvida uno en cuanto lo hayas parado.

  • A los efectos cortos hay que dejarlos terminar en paz; soundStop es para sonidos que ya no deberían sonar.

  • soundUnload no corta un clip que todavía está sonando.

  • Reproduce un sonido donde ocurre el evento, no donde una condición es verdadera, o sonará sesenta veces por segundo.

  • onSoundCompleted(channel) es un callback que el motor llama cada vez que un canal se queda en silencio, por el motivo que sea.

  • La música es un sistema aparte, con sus propios handles, su propio volumen y sin límite de canales.

  • El volumen de los efectos va de 0 a 63. El de la música, de 0 a 128. No son porcentajes.

La próxima vez

Tus rocas reciben un impacto cuando sus rectángulos se solapan, y por eso cuenta incluso un disparo que pasa por una esquina de cielo. En la lección once tendrás las comprobaciones de colisión del propio motor, aprenderás qué es una zona de impacto y descubrirás por qué el rectángulo que rodea una roca redonda tiene la forma equivocada.

Lección 11: Chocar con cosas

La lección terminada

Tu juego de la lección diez funciona. Los disparos rompen rocas, las rocas cuestan vidas y las explosiones suenan donde tienen que sonar. Pero míralo de cerca y verás que hace trampa, en las dos direcciones. Una roca que pasa rozando la punta de un ala te quita una vida. Un disparo que atraviesa el cielo vacío junto a una roca la rompe igualmente.

En un juego, dos cosas se tocan cuando los números dicen que se tocan. Nadie mira las imágenes. Esta lección hace que los números estén de acuerdo con lo que ve el jugador: cambia tu comprobación escrita a mano por la del propio motor, encoge las cajas que se comprueban para que se ajusten a las cosas que hay dentro y te da un interruptor que te enseña esas cajas. La imagen de arriba es el juego con ese interruptor encendido.

Dónde estás

El juego pregunta «¿se tocan estas dos cosas?» exactamente en dos sitios, y los dos usan overlapping, la función que escribiste en la lección nueve. Uno está en updateRocks, donde una roca se encuentra con la nave:

        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then

El otro está en updateShots, donde un disparo se encuentra con una roca:

            if not gone and overlapping(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then

Todo lo de esta lección cambia esas dos líneas y añade unas cuantas funciones pequeñas que las alimentan. Nada más del juego se mueve. El script terminado entero está en learn/11-hitting-things.singe, por si te pierdes.

Léela una vez más

La lección nueve ya hizo esta parte: overlapping es la colisión de rectángulos escrita a mano. Léela una vez más antes de tirarla, porque es la idea entera:

function overlapping(ax, ay, aw, ah, bx, by, bw, bh)
    if ax + aw <= bx then
        return false
    end
    if bx + bw <= ax then
        return false
    end
    if ay + ah <= by then
        return false
    end
    if by + bh <= ay then
        return false
    end
    return true
end

La pregunta «¿se están tocando estas dos cosas?» es difícil de responder directamente y fácil de responder al revés. Dos rectángulos no se tocan cuando uno de ellos está entero a la izquierda del otro, o entero a la derecha, o entero encima, o entero debajo. No hay una quinta forma de fallar. Si no se cumple ninguna de esas cuatro, se tocan.

Cada if es una de las cuatro formas de fallar. ax + aw es el borde derecho del primer rectángulo, así que ax + aw ⇐ bx se lee «el primero termina antes de que empiece el segundo», que es lo que significa «entero a la izquierda» en números. La misma forma tres veces más, para la derecha, encima y debajo, con y y las alturas en lugar de x y las anchuras, y lo único que queda es true.

Esos son los ocho números que necesita cualquier comprobación de colisión: una esquina y un tamaño para cada una de dos cosas. Guarda la forma en la cabeza, porque estás a punto de borrarla.

El motor ya lo tiene

Conociste collideRects en la lección siete, donde atrapaba los bloques que caían en Dodge. La lección nueve escribió la misma comprobación a mano para que pudieras verla por dentro. Ya la has visto por dentro. Borra overlapping y cambia las dos líneas de Dónde estás para que llamen al motor:

        if collideRects(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then
            if not gone and collideRects(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then

Los mismos ocho números, en el mismo orden: la esquina y el tamaño del primer rectángulo, y luego los del segundo. Ejecútalo, y el juego funciona exactamente igual que antes, que es de lo que se trata. La única diferencia está justo en el borde. Tu ⇐ decía que dos rectángulos que se encuentran a lo largo de un borde no se tocan. collideRects dice que sí, y un rectángulo sin anchura o sin altura no toca nada en absoluto. Esos casos incómodos son donde las versiones escritas a mano fallan sin avisar, y son una de las razones para usar la del motor.

collideRects es una de una familia de comprobaciones de colisión, y la familia es una parte de lo que este libro llama el kit de juego: un puñado de funciones sencillas para las cosas que casi todos los juegos tenían que escribirse ellos mismos. Comprobar si dos cosas se tocan es una. Guardar un número para la próxima vez es otra, y es la lección doce. Esperar un rato, llevar un número suavemente de un valor a otro y mostrar cuánto ha tardado cada fotograma son el resto. La referencia le da a cada parte una sección propia: Colisión, Partida guardada, Temporizador, Interpolación y Estadísticas.

Las comprobaciones de colisión son las más sencillas de todas: preguntas sencillas, sin handles que guardar ni nada que preparar o liberar. Y ninguna mueve nada. collideRects te dice que la nave y la roca están en el mismo sitio; qué hacer al respecto lo decides tú, y todo lo interesante de un juego ocurre en esa decisión.

La imagen no es la zona de impacto

La lección diez prometió explicar por qué el rectángulo que rodea una roca redonda tiene la forma equivocada. El rectángulo que rodea la nave también está mal, y por la misma razón.

Dibuja en papel el rectángulo de 32 por 24 de la nave y sombrea la nave. Es un triángulo con dos aletas, así que hay cielo vacío en las dos esquinas de arriba y entre las aletas. La roca es redonda, así que hay cielo vacío en las cuatro esquinas de su cuadrado. Una roca que roza la esquina de arriba del rectángulo de la nave no ha chocado con la nave. Ha pasado volando junto al ala, y un jugador que pierde una vida por eso dirá que el juego ha hecho trampa — y tendrá razón.

Así que la caja que compruebas no es la imagen que dibujas. Es más pequeña, y está dentro de la imagen. Añade tres números a las constantes de arriba del todo de tu archivo:

local SHIP_PAD_X  = 6
local SHIP_PAD_Y  = 5
local ROCK_PAD    = 4

El margen es lo lejos de cada borde que empieza la cosa de verdad. Seis píxeles menos por cada lado de la nave y cinco menos por arriba y por abajo dejan una caja de 20 por 14 en el centro de una imagen de 32 por 24, que es más o menos donde está el casco. Cuatro menos por cada lado de la roca dejan 16 por 16, y eso es casi todo roca.

Las dos cajas son un poco más pequeñas que las cosas que representan, y es a propósito. Una caja un poco demasiado pequeña le da al jugador escapadas por los pelos que parecen habilidad. Una caja un poco demasiado grande le da golpes que parecen trampa. Los jugadores perdonan lo primero y nunca lo segundo.

En lugar de escribir la aritmética en cada comprobación, escríbela una vez para cada tipo de cosa:

function rockBox(rock)
    return rock.x + ROCK_PAD, rock.y + ROCK_PAD, rockWidth - ROCK_PAD * 2, rockHeight - ROCK_PAD * 2
end


function shipBox()
    return shipX + SHIP_PAD_X, shipY + SHIP_PAD_Y, shipWidth - SHIP_PAD_X * 2, shipHeight - SHIP_PAD_Y * 2
end

Los tamaños salen de rockWidth, shipWidth y compañía, las medidas que la lección nueve tomó de las imágenes, así que sigue sin haber ni un tamaño en píxeles a pelo en el código del juego. Vuelve a dibujar la nave más grande y la caja crece con ella.

Cada una de esas funciones devuelve cuatro números a la vez, separados por comas. Una función puede devolver tantos valores como quiera, y la forma de recogerlos es una lista de nombres a la izquierda del =:

function shipHitsRock(rock)
    local sx, sy, sw, sh = shipBox()
    local rx, ry, rw, rh = rockBox(rock)

    return collideRects(sx, sy, sw, sh, rx, ry, rw, rh)
end

Ahora la comprobación de updateRocks se lee como la pregunta que hace:

        if shipHitsRock(rock) then

La aritmética de los márgenes está exactamente en dos sitios, y los números que usa están arriba del todo del archivo, así que puedes ajustar lo justo que se siente el juego cambiando un número en lugar de ir buscando por tus comprobaciones.

Pon las funciones nuevas en su sitio del orden alfabético, como pedía la lección nueve: rockBox después de onSoundCompleted, y luego shipBox y shipHitsRock.

Devolver el fuego

Con eso está hecha la parte de la nave. La otra colisión del juego es con la que devuelves el fuego: cada disparo contra cada roca, en updateShots. Tiene el mismo problema que tenía la nave, en pequeño. Un disparo es un rectángulo de 4 por 10 que se comprueba contra el cuadrado entero de 24 por 24 de la roca, así que un disparo que solo pasa por la esquina vacía junto a una roca la rompe igualmente.

Podrías darle al disparo una caja con márgenes propia. Pero mira antes los números. Quítale márgenes a un disparo de cuatro píxeles de ancho y no queda casi nada, y comprobar un rectángulo entero para saber si una astilla de luz ha tocado algo es más maquinaria de la que merece la pregunta.

Un disparo es casi un punto

Comprueba la punta en su lugar. collidePointRect pregunta si un punto cae dentro de un rectángulo — dos números para el punto, y luego la esquina y el tamaño del rectángulo:

function shotHitsRock(shot, rock)
    local rx, ry, rw, rh = rockBox(rock)

    return collidePointRect(shot.x + shotWidth / 2, shot.y, rx, ry, rw, rh)
end

shot.y es la parte de arriba del disparo y shot.x + shotWidth / 2 es la mitad de su anchura, así que el punto que se comprueba es el centro de la punta del disparo. Ahí es donde un jugador cree que está un disparo. El lado de la roca en esta pregunta usa el mismo rockBox que la nave, así que una roca mide lo mismo le dé lo que le dé.

Va después de shipHitsRock, y la comprobación de updateShots queda así:

            if not gone and shotHitsRock(shot, rock) then

Decidir qué ha pasado

Ninguna de las comprobaciones de colisión hace nada. Responden, y tu código decide. Aquí están los dos sitios que deciden, con sus preguntas nuevas dentro. Primero updateRocks:

        if shipHitsRock(rock) then
            local channel = soundPlay(boomClip)

            newRock(rock)
            lives = lives - 1
            if lives <= 0 then
                dying        = true
                deathChannel = channel
                if channel < 0 then
                    endGame()
                end
            end
        end

Y el bucle de dentro de updateShots:

        for _, rock in ipairs(rocks) do
            if not gone and shotHitsRock(shot, rock) then
                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
                soundPlay(boomClip, 0, 45)
            end
        end

Todo lo que hay debajo de las preguntas es exactamente lo que dejó ahí la lección diez. Una roca que choca con la nave estalla, vuelve arriba y cuesta una vida. Una roca alcanzada por un disparo estalla, vuelve arriba y suma puntos. El disparo también desaparece, y el not gone impide que un disparo rompa dos rocas. Cambia cualquiera de esas cosas y cambias el juego, sin tocar ni una sola comprobación de colisión, que es la razón de que las preguntas y las respuestas se mantengan separadas.

Ejecútalo. Pasa volando cerca de una roca y deja que te roce una aleta: conservas la vida. Dispara justo al lado de una roca y el disparo pasa de largo. Dispara al centro de una y se rompe, igual que siempre.

Ver las cajas

Las zonas de impacto son invisibles, y eso hace que un error en ellas también lo sea. Dibújalas mientras trabajas. Una constante más, arriba del todo:

local SHOW_BOXES  = false

Dos funciones más, que van al principio del todo del orden alfabético:

function drawBox(x, y, width, height)
    overlayBox(x, y, x + width - 1, y + height - 1)
end


function drawBoxes()
    colorForeground(0, 255, 0)
    drawBox(shipBox())
    for _, rock in ipairs(rocks) do
        drawBox(rockBox(rock))
    end
end

Y en onOverlayUpdate, después de dibujar la nave y antes de que la puntuación vaya encima:

    spriteDraw(shipSprite, shipX, shipY)
    if SHOW_BOXES then
        drawBoxes()
    end
    drawHud()

Cambia SHOW_BOXES a true y aparecen contornos verdes sobre el arte, como en la imagen del principio de esta lección. Vuelve a cambiarlo cuando acabes. Un interruptor como este, una palabra arriba del todo de un archivo que enciende una imagen de lo que cree el programa, vale más que cualquier cantidad de mirar fijamente.

Qué acaba de pasar

function rockBox(rock)
    return rock.x + ROCK_PAD, rock.y + ROCK_PAD, rockWidth - ROCK_PAD * 2, rockHeight - ROCK_PAD * 2
end

Cuatro valores de un solo return, separados por comas. Lua devuelve encantado tantos como quieras, y quien llama decide cuántos se queda. Cuando una llamada así es lo último dentro de los paréntesis de otra llamada, se pasan los cuatro, y por eso drawBox(rockBox(rock)) funciona y le da a drawBox sus cuatro argumentos. En cualquier otro sitio de una lista de argumentos, solo sobrevive el primer valor. Esa regla muerde exactamente una vez, y muerde al final de esta lección.

    return collideRects(sx, sy, sw, sh, rx, ry, rw, rh)

collideRects quiere ocho números: esquina y tamaño, esquina y tamaño. Devuelve true o false y no cambia nada. Como la respuesta sale directamente de la función con return, shipHitsRock(rock) se lee como una pregunta allí donde se use.

    return collidePointRect(shot.x + shotWidth / 2, shot.y, rx, ry, rw, rh)

collidePointRect quiere seis: un punto, y luego un rectángulo. El borde cuenta como dentro, así que un disparo justo en el límite acierta. Úsala siempre que uno de los lados de la pregunta sea lo bastante pequeño como para que su tamaño no importe.

    colorForeground(0, 255, 0)
    overlayBox(x, y, x + width - 1, y + height - 1)

Las dos vienen de la lección siete. overlayBox recibe dos esquinas, no una esquina y un tamaño — el único sitio de esta lección donde los números cambian de forma — y el - 1 está porque las dos esquinas se incluyen. colorForeground es un interruptor que se queda puesto, así que todo lo que dibuja drawBoxes sale verde. Los sprites y overlayPrint no le hacen caso, así que el resto del juego se ve igual.

El resto de la familia

collideRects y collidePointRect bastan para la mayoría de los juegos 2D. Las demás están para las formas que los rectángulos describen mal, y cada una es el mismo tipo de pregunta sencilla:

  • collideCircles y collidePointCircle, para cualquier cosa redonda. Un círculo es un centro y un radio.

  • collideRectCircle, para una cosa redonda contra una cuadrada.

  • collidePointPolygon, para una forma con esquinas propias — un dragón, un continente, un botón con forma rara. Le das una lista plana de números x, y, x, y.

  • collideSegments, para dos segmentos de línea que se cruzan.

Si eres sincero, tu roca es redonda, y las comprobaciones de círculos le van mejor que cualquier caja. Los márgenes son la respuesta barata y bastan para la mayoría de los juegos, y por eso van primero. La respuesta exacta es una de las cosas que probar más abajo.

collideSegments importa más de lo que parece. Tu disparo se mueve seis píxeles por fotograma y las rocas tienen dieciséis píxeles de zona de impacto, así que un disparo no puede atravesar una sin que se le compruebe dentro de ella. Haz el disparo lo bastante rápido — cuarenta píxeles por fotograma — y salta de debajo de una roca a encima de ella, sin estar ni una sola vez en el mismo sitio que la roca, y nunca le da a nada. Trazar la línea desde donde estaba el disparo hasta donde está ahora, y preguntarle a collideSegments si esa línea cruza un borde, es la cura. Las cosas lentas no la necesitan.

Hay un callback de colisión en Singe, onCollision, y no es para esto. Pertenece al motor de física 3D: cuerpos con masa que caen y rebotan unos contra otros en tres dimensiones y te dicen dónde se han tocado y con qué fuerza. Lo conocerás en la lección veinticuatro. Nada del overlay avisa por sí solo, y nada lo necesita. Tus rocas están en una lista, sabes cuántas hay, y preguntar es barato.

Y cuando quieras saber no solo si dos cosas se han encontrado, sino dónde debería acabar la que se mueve — deslizándose a lo largo de una pared en lugar de quedarse clavada dentro de ella — las llamadas de colisión no responden a eso, a propósito. Singe incluye una biblioteca llamada bump justo para ese trabajo, y la sección Bibliotecas incluidas de la referencia dice cómo usarla.

Pruébalo

  1. Quita los márgenes. Pon ROCK_PAD a 0 y juega un minuto. Luego ponlo a 8 y vuelve a jugar. Con uno de los dos parece que el juego te miente.

  2. Mira lo que estás comprobando. Pon SHOW_BOXES a true y observa los contornos verdes mientras una roca pasa junto a la nave. Ahora pon SHIP_PAD_X a 16, juega, y fíjate en que ya nada puede darte. Averigua por qué con la aritmética de shipBox.

  3. Haz el disparo demasiado rápido. Pon SHOT_SPEED a 40. Cuenta a cuántas rocas de cada diez les das. Averigua con los números por qué pasa eso antes de volver a cambiarlo.

  4. Usa el disparo entero. Reescribe shotHitsRock para que use collideRects con el rectángulo completo del disparo en lugar de collidePointRect con su punta. Juega con las dos y decide cuál prefieres; no hay respuesta correcta, y vale la pena saberlo.

  5. Haz la roca redonda. Dale a la roca un círculo en lugar de una caja: su centro está a rock.x + rockWidth / 2 en horizontal y a rock.y + rockHeight / 2 en vertical, y un radio de 10 es más o menos lo justo. Usa collideRectCircle para la nave y collidePointCircle para el disparo, y dibuja el círculo en drawBoxes con overlayCircle, que recibe un centro y un radio.

Rómpelo a propósito

Las dos cajas ya son cuatro valores cada una, así que dan ganas de pasarlas directamente y ahorrarse los ocho nombres locales:

function shipHitsRock(rock)
    return collideRects(shipBox(), rockBox(rock))
end

Parece correcto y está mal. Ejecútalo y el juego se para antes de dibujar nada:

186:collideRects:  Expected 8 argument(s), got 5.

La línea es la que acabas de escribir, así que puede que la tuya no sea la 186. El cinco, en cambio, sí. rockBox(rock) es lo último dentro de los paréntesis, así que entraron sus cuatro valores. shipBox() no lo es, así que se recortó a uno. Uno más cuatro son cinco, y collideRects no va a adivinar los otros tres.

Este error viene del motor y no de Lua, así que tiene la misma forma que los de las lecciones nueve y diez: el número del principio es la línea, luego viene el nombre de la función que se ha negado, y luego la queja. Vuelve a poner los ocho nombres locales.

Lo que has aprendido

  • Las colisiones son aritmética con rectángulos, y puedes escribirla tú mismo.

  • Dos rectángulos pueden no tocarse exactamente de cuatro formas; si no se cumple ninguna, chocan.

  • collideRects recibe una esquina y un tamaño para cada uno de dos rectángulos y responde true o false. Cuenta como que se tocan los bordes que solo se rozan.

  • Las comprobaciones de colisión son parte del kit de juego, funciones sencillas sin nada que preparar. Partida guardada, Temporizador, Interpolación y Estadísticas son el resto.

  • collidePointRect pregunta si un punto está dentro de un rectángulo, que es la pregunta adecuada para cualquier cosa pequeña.

  • La caja que compruebas es más pequeña que la imagen que dibujas, o el juego parecerá injusto.

  • Una función puede devolver varios valores, y solo la última llamada de una lista de argumentos los pasa todos.

  • Las comprobaciones de colisión solo responden. Lo que pasa después es cosa de tu código, y mantener las dos partes separadas te deja cambiar cualquiera de ellas por su cuenta.

  • Dibujar tus zonas de impacto en pantalla convierte un fallo invisible en uno visible.

  • onCollision es para cuerpos de física 3D, no para sprites en el overlay.

La próxima vez

El juego cuenta tu puntuación y te quita vidas, y en cuanto sales, la mejor puntuación que nadie haya conseguido desaparece. Empieza en plena acción en el instante en que se carga. Y lleva la cuenta de lo que está haciendo con dos variables de verdadero o falso, over y dying, que es exactamente la trampa de la que te avisó la lección siete. La lección doce le da una pantalla de título, una sola variable en lugar de esas dos y un récord que mañana seguirá ahí.

Lección 12: Puntuación, vidas y fin de partida

La lección terminada

Tu juego lleva la puntuación, quita vidas y dice GAME OVER. Es casi un juego. Todavía le faltan tres cosas. No tiene puerta de entrada: está en plena acción en el instante en que se carga. Se olvida de todo: sal, y la mejor puntuación que nadie haya conseguido se va con él. Y lleva la cuenta de lo que está haciendo con dos variables de verdadero o falso, over y dying, que es la trampa de la que te avisó la lección siete.

Esta lección arregla las tres. Una variable para lo que está haciendo el juego, una pantalla de título desde la que empezar, un récord que mañana seguirá ahí y una segunda partida que empieza exactamente igual que la primera.

Un juego siempre está exactamente en un estado

Observa cualquier máquina recreativa durante dos minutos. Muestra un título y espera a alguien. Alguien pulsa start y se pone a jugar. El jugador se queda sin vidas y la máquina lo dice, y luego vuelve a esperar. La máquina siempre está haciendo exactamente una de esas cosas.

Dodge, en la lección siete, guardaba eso en una variable que contenía una palabra: "waiting", "playing" o "over". El juego de la lección nueve volvió a un over de verdadero o falso, y la lección diez le añadió dying al lado. Cuenta lo que pueden decir dos variables así. Cada una es true o false, así que juntas dan cuatro combinaciones. Tres significan algo: jugando, muriendo y fin de partida. La cuarta, las dos a la vez, es un disparate, y tu código tiene que tener cuidado de no producirla nunca. Lo tiene: mira endGame, que vuelve a poner dying a false antes de poner over a true. Ahora añade una pantalla de título. Eso es un tercer indicador, ocho combinaciones, y cuatro de ellas disparates. Esa es exactamente la trampa de la lección siete, y es donde los juegos pequeños van a morir.

Así que haz lo que hizo Dodge. Cuatro estados, una variable. Pon los nombres de los estados debajo de tus otras constantes:

local TITLE   = "title"
local PLAYING = "playing"
local DYING   = "dying"
local OVER    = "over"

Luego quita over y dying de tus variables, y pon una sola línea en su lugar:

local state        = TITLE

Dodge usaba las propias palabras. Los nombres en mayúsculas no son más listos, y no atrapan una falta de ortografía: Lua trata un nombre mal escrito como nil y una palabra mal escrita como una palabra que no coincide con nada, y cualquiera de las dos te da un juego que deja de responder sin decir nada. Lo que te compran los nombres es una lista. Cada estado en el que puede estar el juego está escrito una vez, arriba del todo del archivo, donde puedes ver los cuatro de un vistazo.

Allí donde el juego ponía un indicador, ahora pone el estado. En updateRocks, donde se va la última vida:

            if lives <= 0 then
                state        = DYING
                deathChannel = channel

En endGame, dos líneas se convierten en una, y la combinación disparatada desaparece porque ya no queda nada que combinar:

function endGame()
    deathChannel = -1
    state        = OVER
    musicStop(theme, 1500)
end

Y en startGame, las dos líneas que borraban los dos indicadores se convierten en state = PLAYING.

Un solo sitio que decide

En cada fotograma, onOverlayUpdate toma las dos decisiones que importan: qué se mueve y qué palabras van encima. Qué se mueve es una sola comprobación:

    if state == PLAYING then
        updateShip()
        updateShots()
        updateRocks()
    end

Eso sustituye a if not over and not dying then, y dice lo que quiere decir. En el título, mientras suena la última explosión y cuando la partida ya ha terminado, nada se mueve. Lo consigues no llamando a las funciones que mueven cosas. Parar un juego no es una característica especial; es dejar cosas fuera.

El mundo se sigue dibujando en cada fotograma, sea cual sea el estado, exactamente como lo dibujaba Dodge. Solo cambian las palabras. Sustituye la línea drawHud() por esto:

    if state == TITLE then
        drawTitle()
    else
        drawHud()
    end

drawTitle es nueva, y va después de drawStars:

function drawTitle()
    overlayPrint(25, 6, "R O C K S")
    overlayPrint(25, 9, "BEST " .. best)
    overlayPrint(22, 12, "PRESS 1 TO PLAY")
end

best es la mejor puntuación hasta ahora, y llega en la sección siguiente; el juego no funcionará hasta que llegue. Antes de la primera partida la lista de rocas está vacía, así que lo que muestra el título son las estrellas pasando y la nave esperando abajo, que es todo lo que necesita una pantalla de título.

Hay una línea que tiene que irse, o no verás nunca el título. Borra el startGame() del final del todo del archivo. Ahora el juego empieza en su título, y Volver a empezar explica por qué importa esa línea.

drawHud hace una pregunta propia. Cambia su if over then por:

    if state == OVER then

El callback de entrada necesita el mismo tipo de razonamiento. Aquí lo tienes entero:

function onInputPressed(what)
    if what == SWITCH_LEFT then
        goLeft = true
    elseif what == SWITCH_RIGHT then
        goRight = true
    elseif what == SWITCH_BUTTON1 and state == PLAYING then
        shots[#shots + 1] = { x = shipX + shipWidth / 2 - shotWidth / 2, y = shipY }
        soundPlay(shootClip, 0, 35)
    elseif what == SWITCH_START1 and (state == TITLE or state == OVER) then
        soundPlay(clickClip)
        startGame()
    end
end

Léelo desde arriba. Las flechas se apuntan sea cual sea el estado, porque solo dicen qué teclas están pulsadas, y nada mueve la nave a menos que el estado sea PLAYING. Disparar solo significa algo mientras se juega. Y 1 empieza una partida desde el título o desde la pantalla de fin de partida, y no mientras la última explosión sigue sonando: la partida no ha terminado hasta que lo dice. Los paréntesis funcionan igual que en aritmética. El or de dentro se resuelve primero, y luego el and lo une a la tecla.

Puntuación y vidas

Tienes las dos desde la lección nueve, y apenas cambian. Lo nuevo es la mejor puntuación, que empieza su vida como una variable normal. Ponla con las demás, debajo de lives:

local best         = 0

Muéstrala en la línea de arriba, entre las otras dos. En drawHud:

    overlayPrint(1, 1, "SCORE " .. score)
    overlayPrint(25, 1, "BEST " .. best)
    overlayPrint(50, 1, "LIVES " .. lives)

Y dale a endGame el trabajo de darse cuenta de un récord:

    if score > best then
        best = score
    end

Ejecútalo. El título dice BEST 0. Pulsa 1, dispara a algo, pierde, y la pantalla de fin de partida muestra tu puntuación como la mejor. Vuelve a pulsar 1 y la mejor se queda mientras la puntuación vuelve a empezar. Ahora sal, vuelve a ejecutarlo y mira el título: BEST 0. El récord ha vivido exactamente lo mismo que el programa. Esa es la segunda mitad de esta lección.

Ya que estás mirando las vidas, fíjate en que la lección nueve escribió la comprobación como lives ⇐ 0, no lives == 0, y déjala así. Hoy nada puede quitar dos vidas a la vez, así que las dos solo pueden coincidir. El día que añadas una roca que cueste dos, == 0 se salta el cero y el jugador sigue jugando con menos una vida, mientras que ⇐ 0 sigue funcionando. Pide lo que quieres decir.

Volver a empezar

Ya has borrado el startGame() del final del archivo. En la lección diez la primera partida la empezaba esa línea y todas las siguientes se empezaban pulsando 1, que son dos formas de entrar. Ahora hay una. Cada partida, la primera incluida, empieza cuando alguien pulsa 1 y se ejecuta startGame, así que la primera partida y la quinta empiezan exactamente de la misma forma.

startGame tiene que volver a poner en su sitio todo lo que cambia una partida:

function startGame()
    shipX        = (screenWidth - shipWidth) / 2
    score        = 0
    lives        = START_LIVES
    state        = PLAYING
    deathChannel = -1
    shots        = {}
    for i = 1, ROCK_COUNT do
        rocks[i] = {}
        newRock(rocks[i])
    end
    musicSetVolume(50)
    musicPlay(theme, -1)
end

Igual de importante es saber qué deja en paz, y por qué. best sobrevive a todas las partidas; ese es todo su trabajo. Las estrellas son decorado. Y goLeft y goRight no son del juego en absoluto. Son del teclado, y solo el teclado debería cambiarlas.

Esa última es un fallo que acabas de arreglar sin darte cuenta. El callback de entrada de la lección diez empezaba con if over then, y mientras la partida estaba terminada tiraba todas las teclas salvo 1. Pulsa la flecha derecha mientras se ve GAME OVER, mantenla pulsada y pulsa 1. La nave nueva se queda quieta: la pulsación de la flecha derecha se tiró, todavía no la has soltado, y por eso goRight es false mientras la tecla está claramente pulsada. La nave no se mueve hasta que sueltas y vuelves a pulsar. El callback nuevo apunta las flechas en todos los estados, así que la tecla mantenida sigue mantenida cuando empieza la partida.

Los fallos al volver a empezar son los más comunes de cualquier juego, y al jugar todos se notan igual: la segunda partida está sutilmente mal y la primera estaba bien. Cuando pase eso, lee startGame y hazte dos preguntas. ¿Qué cambió la partida anterior que esta no vuelve a poner en su sitio? ¿Y qué está poniendo esta en su sitio que nunca le correspondió tocar al juego?

Un número que sobrevive al programa

Todo lo que ha guardado tu juego hasta ahora — score, lives, la lista de rocas — vive en memoria, y la memoria desaparece en el instante en que el programa se para.

Singe le da a cada juego una partida guardada propia: un conjunto de nombres con valores debajo, que se escribe en el disco por ti. Es otra parte del kit de juego de la lección once, así que es el mismo tipo de cosa que collideRects: llamadas sencillas, nada que cargar ni liberar.

saveSet("highScore", 4200)

saveSet recibe un nombre — la clave — y un valor. La clave la eliges tú y no cambia nunca; el valor es lo que quieras recordar. Caben números, cadenas, true y false, y tablas enteras de esas cosas. Lo que solo tiene sentido mientras el programa se ejecuta, no. Un handle de sprite no es más que un número, así que se guarda, y mañana es un número que no significa nada. Una función no se puede escribir en ningún sitio, y si intentas guardar una el juego se para con un error en lugar de dejar que lo descubras la semana que viene.

Leerlo de vuelta es la otra mitad. Cambia la línea que añadiste para best:

local best         = saveGet("highScore", 0)

Se ejecuta una vez, cuando arranca el juego. El segundo argumento es el valor por defecto: qué responder cuando nunca se ha guardado nada bajo esa clave. Enseguida hablamos más de eso, porque es todo el error de esta lección.

Y haz que endGame apunte el récord cuando se bata:

function endGame()
    deathChannel = -1
    state        = OVER
    musicStop(theme, 1500)
    if score > best then
        best = score
        saveSet("highScore", best)
        saveFlush()
    end
end

No tienes que pedirle a Singe que escriba el archivo. Lo escribe una vez al final de cualquier fotograma en el que haya cambiado algo, da igual cuántas claves hayas fijado, y otra vez cuando el juego se cierra. saveFlush, en cambio, lo escribe en el acto: un récord nuevo merece una escritura del archivo para él solo, porque a una recreativa la apagan desde el enchufe y un fotograma es mucho tiempo.

Ejecútalo, marca una puntuación, sal y vuelve a ejecutarlo. El título se acuerda.

La sección Partida guardada de la referencia enumera el resto de la familia. saveDelete olvida una clave, saveClear lo olvida todo — eso es el «borrar récords» de un menú de servicio — y saveGetAll te da una copia de todo, que es útil cuando quieres imprimir la partida guardada entera mientras persigues algo.

Adónde va de verdad el archivo

No va junto a tu script, y no es casualidad.

Un juego terminado puede vivir en un disco, en una carpeta compartida de la red o dentro de un único archivo empaquetado (lección treinta), y en ninguno de esos sitios se puede escribir. Un juego que guarda junto a su propio script funciona perfectamente en el ordenador en el que lo escribiste y falla en la mitad de los ordenadores en los que se instala. Singe 2 lo hacía así, y estaba mal.

Así que todo lo que Singe escribe para un juego — la partida guardada, las capturas de pantalla, su registro — va a un solo sitio, y singeGetDataPath te dice dónde:

debugPrint(singeGetDataPath())

Ponlo un momento justo debajo de la línea dofile y ejecútalo. Dice data/rocks/: la carpeta data que apareció en tu carpeta de trabajo la primera vez que ejecutaste algo, en la lección uno, y dentro una carpeta que se llama como la carpeta de tu juego. Ahí dentro encontrarás save.json. Ábrelo en tu editor de texto: es texto plano, y tu récord está ahí bajo el nombre que le diste.

Esa es también la respuesta siempre que necesites un archivo propio. Construye el nombre a partir de singeGetDataPath() y acabará en un sitio donde se puede escribir; escribe en un nombre inventado por ti y tarde o temprano no será así.

La primera vez no hay nada

La primerísima vez que alguien ejecuta tu juego, nunca se ha guardado ningún récord. saveGet no tiene nada que devolver, así que devuelve el valor por defecto que le diste:

local best         = saveGet("highScore", 0)

No hay nada guardado, así que best vale 0, la pantalla de título dice BEST 0, y la primera partida que juegue alguien marca un récord. Eso es exactamente lo que quieres, y cuesta un argumento más.

Quita el 0 y saveGet no tiene ningún valor por defecto al que recurrir, así que responde nil — el valor que usa Lua para «aquí no hay nada», que conociste en la lección tres. nil no es cero. No puedes sumarle nada, no puedes compararlo con un número y no puedes pegarlo a una cadena. Falla en el primer fotograma, siempre, en cada ordenador donde no se haya jugado al juego — lo que incluye todos los ordenadores en los que tus jugadores están a punto de instalarlo, y no el que usas para probar.

Dale a cada saveGet un valor por defecto. Es la costumbre más barata de este libro.

Qué acaba de pasar

local TITLE   = "title"

Una constante: un nombre al que das valor una vez y no cambias nunca, en mayúsculas para que veas de un vistazo que lo es, como en la lección siete. Lua no lo impone — nada te impide asignar algo a TITLE — así que las mayúsculas son un mensaje para la siguiente persona que lo lea, que eres tú dentro de dos semanas.

    if state == PLAYING then

La pregunta que decide si el mundo se mueve. Cuando más adelante añadas un quinto estado — una pausa, o una ronda de bonificación — lo primero que hay que preguntarse es si el mundo se mueve en él, y aquí es donde va la respuesta.

    elseif what == SWITCH_START1 and (state == TITLE or state == OVER) then

Sin los paréntesis, Lua uniría primero el and y lo leería como «la tecla es 1 y el estado es el título, o el estado es el de fin de partida». Entonces cualquier tecla que no hubieran atrapado las ramas de arriba empezaría una partida desde la pantalla de fin de partida, disparo incluido, y un jugador que siguiera aporreando el botón de disparo cuando le da la última roca se vería metido en una partida nueva en el momento en que apareciera GAME OVER. Los paréntesis hacen que el or vaya primero. Cuando mezcles and y or, pon los paréntesis aunque creas que sabes el orden. Así la siguiente persona que lo lea no tendrá que saberlo.

        saveSet("highScore", best)
        saveFlush()

saveSet mete el número en la partida guardada; saveFlush pone la partida guardada en el disco ahora en lugar de al final del fotograma. Los dos están dentro del if, así que el archivo solo se escribe cuando de verdad se bate el récord, que es unas pocas veces por sesión y no sesenta veces por segundo.

local best         = saveGet("highScore", 0)

Se lee una vez, al arrancar, en una variable normal. El resto del juego lee best en lugar de volver a llamar a saveGet, porque la partida guardada es un archivo y una variable es una variable. Escribe en las dos cuando se bata el récord.

Pruébalo

  1. Vuelve al título. Una máquina recreativa no se queda en GAME OVER para siempre. Busca timerAfter en la sección Temporizador de la referencia, otra parte del kit de juego, y úsalo en endGame para devolver el estado a TITLE cinco segundos después de que termine la partida. Luego pulsa 1 enseguida al terminar una partida y asegúrate de que el temporizador no devuelve tu partida nueva al título a los tres segundos.

  2. Muestra las vidas como naves. Dibuja shipSprite una vez por vida en la esquina superior derecha con spriteDraw en lugar de imprimir el número. Un bucle for de la lección cuatro, y shipWidth te dice a qué distancia ponerlas.

  3. Guarda más que un número. Añade saveSet("gamesPlayed", saveGet("gamesPlayed", 0) + 1) a startGame, e imprímelo en la pantalla de título. Sal, vuelve a ejecutarlo y mira cómo lo recuerda.

  4. Encuentra el archivo y rómpelo. Abre data/rocks/save.json en tu editor, cambia el récord por algo absurdo y ejecuta el juego. Luego borra el archivo entero y vuelve a ejecutarlo. Las dos cosas les van a pasar a tus jugadores.

  5. Bórralo desde dentro del juego. Haz que una tecla que nunca pulsarías sin querer llame a saveClear(), y mira después la pantalla de título. Cuidado: best sigue en memoria, y saveClear no lo toca. Averigua qué más tiene que pasar.

Rómpelo a propósito

Quita el valor por defecto, para que la línea quede así:

local best         = saveGet("highScore")

Si ya has marcado un récord, no pasa nada en absoluto, y esa es la trampa: la partida guardada tiene la clave, así que saveGet la devuelve. Borra primero data/rocks/save.json y luego ejecútalo. La pantalla de título no aparece nunca, y te sale esto:

Error executing function 'onOverlayUpdate':  rocks/rocks.singe:101: attempt to concatenate a nil value (upvalue 'best')
stack traceback:
	rocks/rocks.singe:101: in function 'drawTitle'
	rocks/rocks.singe:165: in function 'onOverlayUpdate'

Léelo como te enseñó la lección ocho. El archivo y la línea te llevan a overlayPrint(25, 9, "BEST " .. best) en drawTitle, y la queja dice que algo que era nil se ha pegado a una cadena. .. une dos cadenas, y nil no es una. Si tus líneas están colocadas de otra forma, tus números también serán otros.

La línea que nombra no es donde está el error. La línea 101 es donde el juego por fin ha tropezado con él; el error se cometió cerca del principio del archivo, donde se pidió best y no había nada. Esa distancia entre dónde se crea un valor malo y dónde se nota es lo más difícil de nil, y la razón de que un valor por defecto cueste un argumento y te ahorre una tarde.

Vuelve a poner el 0.

Lo que has aprendido

  • Un juego está exactamente en un estado cada vez, y los indicadores de verdadero o falso que intentan decir cuál crían combinaciones que no significan nada.

  • Guarda el estado en una variable, con sus valores posibles nombrados una vez arriba del todo del archivo.

  • onOverlayUpdate decide qué se mueve y qué se dice, preguntando al estado.

  • Parar un juego es cuestión de no llamar a lo que lo mueve.

  • Empieza cada partida, la primera incluida, a través de una sola función, y haz que esa función vuelva a poner en su sitio todo lo que cambia una partida — y nada más.

  • Las teclas son del teclado. Apúntalas en todos los estados.

  • saveSet guarda un valor bajo una clave, y saveGet lo vuelve a leer en una ejecución posterior.

  • saveFlush escribe el archivo ya, para las cosas que te daría rabia perder.

  • La partida guardada va en la carpeta de datos del propio juego, que nombra singeGetDataPath. Nunca escribas junto a tu script.

  • saveGet sin valor por defecto responde nil cuando no se ha guardado nada, y nil rompe el primer fotograma en un ordenador que nunca ha ejecutado tu juego.

  • Cuando mezcles and y or, usa paréntesis.

La próxima vez

Tu juego ya es un juego, y es una carpeta que solo tú sabes arrancar. La lección trece le da un games.dat, para que el propio menú del motor lo ponga en su lista con un título y una imagen, y un jugador que nunca ha oído hablar de ti pueda arrancarlo sin escribir nada.

Lección 13: Una carpeta de juego

La lección terminada

Tu juego es un script en una carpeta cuyo nombre recuerdas, que se arranca escribiendo su nombre en una terminal. Eso te vale a ti y no le sirve a nadie más. Un jugador debería poder copiar una carpeta junto a Singe, arrancar el menú, ver tu juego en la lista con su título y su arte, y pulsar un botón. La imagen de arriba es ese menú, con tu juego dentro.

Para eso hace falta un archivo nuevo, de unas seis líneas, y dos imágenes que puedes sacar con una tecla. Tu script no cambia en absoluto.

Ponle nombre al juego

Un juego tiene dos nombres, uno para el ordenador y otro para las personas.

El del ordenador es la carpeta, y lo elegiste en la lección nueve: rocks, con rocks.singe dentro. La carpeta y el script comparten nombre, como en todas las lecciones desde la lección uno, y por eso Singe rocks encuentra el script solo con la carpeta. Mantén ese nombre sencillo. Sin espacios, que una terminal lee como el hueco entre dos nombres. Y con las mismas mayúsculas en todos los sitios donde lo escribas: en la mayoría de los ordenadores que no son Windows, rocks y Rocks son dos carpetas distintas, y un juego que solo funciona en tu ordenador no es un juego que pueda tener nadie más.

El nombre para las personas puede ser el que quieras, con mayúsculas, espacios y todo, y no vive en el nombre de la carpeta. Vive en el archivo del que trata esta lección, para que cambiarle el nombre al juego en el menú nunca signifique cambiarle el nombre a una carpeta.

Qué va en la carpeta

Todo lo que necesita tu juego, y nada más. Al final de esta lección tiene este aspecto:

rocks/
    games.dat       Lo que lee el menú
    rocks.singe     El juego
    art/            El kit de arte de la lección nueve
        spaceship.png
        asteroid.png
        bullet.png
        star.png
        shoot.wav
        boom.wav
        ...
    cabinet.png     Una imagen que el menú muestra junto a la lista
    marquee.png     Una imagen que el menú muestra encima de ella

Cualquier otra cosa que haya acabado ahí mientras aprendías — walk.singe de la lección nueve, la pequeña prueba de sonido de la lección diez — no es parte del juego. Muévelas a una carpeta propia junto a rocks. El kit de arte también tiene unos cuantos archivos que este juego nunca carga, y de momento no hacen ningún daño. La lección treinta es donde repasas una carpeta de juego y quitas todo lo que no es el juego.

La regla que hay detrás de esa organización es que un juego nunca sale de su propia carpeta. Ni para el arte, ni para un sonido, ni para una biblioteca que también usas en otro juego — si compartes código entre dos juegos, cada uno guarda su propia copia. Hay exactamente un sitio fuera de la carpeta desde el que un juego puede cargar, y ya estás cargando desde él: la propia carpeta Singe del motor, donde vive Singe/Framework.singe, y desde la lección diez también el clic y la música.

La carpeta del juego está en tu carpeta de trabajo, junto al motor:

singe/                 Tu carpeta de trabajo
    Singe-v3.00-...    El propio motor, se llame como se llame el tuyo
    Menu.sh            Arranca el menú.  Menu.bat en Windows
    Singe/             Archivos de soporte.  No son tuyos; déjalos en paz
    data/              Todo lo que escribe cualquier cosa, tu partida guardada incluida
    rocks/             Tu juego

El ordenador de un jugador tiene esa misma forma. El motor escribió Singe, data y Menu.sh (Menu.bat en Windows) la primera vez que ejecutaste algo, allá en la lección uno. La lección uno mencionó los dos primeros. El tercero es nuevo para ti, y esta lección lo pone a trabajar.

Las rutas cuentan desde donde arrancó Singe

Llevas haciendo esto desde la lección nueve, así que esto es un recordatorio, no un cambio.

Cada nombre que carga tu juego — art/spaceship.png, art/boom.wav — se busca empezando por la carpeta en la que se arrancó Singe, no por la carpeta en la que está tu script. Arrancas Singe en tu carpeta de trabajo, así que un art/spaceship.png a secas se buscaría en singe/art, que no existe. DIR es la propia carpeta de tu script con la barra ya puesta al final, así que un nombre pegado a ella apunta a tu archivo desde dondequiera que se haya arrancado Singe:

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")

El menú arranca Singe en la carpeta en la que está Menu.sh, que vuelve a ser tu carpeta de trabajo, así que DIR hace ahí exactamente lo mismo que hace para ti. Lo sigue haciendo cuando el juego se empaqueta en un solo archivo en la lección treinta, cuando la carpeta de trabajo de otra persona se llama de una forma completamente distinta, y en un ordenador que no verás nunca. Un nombre que empieza por Singe/ es la carpeta del motor y nunca necesita DIR; todos los nombres que son tuyos lo necesitan.

games.dat

games.dat es como se presenta un juego. El menú lee el games.dat de cada carpeta de juego que tiene al lado y enumera lo que encuentra. Sin games.dat no hay entrada en la lista: tu carpeta es invisible, por bueno que sea el juego que hay dentro.

Crea un archivo nuevo llamado games.dat en tu carpeta rocks. Este es el más pequeño que funciona:

GAMES = {
    {
        TITLE  = "Rocks",
        SCRIPT = "rocks/rocks.singe"
    }
}

Eso es Lua, y es una tabla del tipo que conociste en la lección seis: GAMES es una lista, y cada cosa de la lista es un registro que describe un juego. Una carpeta puede contener varios juegos — por eso es una lista — pero la tuya contiene uno.

SCRIPT es el campo que el motor necesita para ejecutar el juego, y TITLE el que necesita el menú para mostrarlo en la lista. La ruta del script se cuenta desde la carpeta de encima del games.dat, no desde la carpeta en la que está el games.dat. Así que un games.dat dentro de rocks nombra su propio script como rocks/rocks.singe. Parece que dice rocks dos veces, y está bien. Todas las demás rutas del archivo funcionan igual. Si te equivocas, nada se queja cuando escribes el nombre: la entrada simplemente nunca coincide con el script que has ejecutado.

TITLE es el nombre para las personas del principio de esta lección. Es lo que muestra el menú, y los juegos se listan por orden de título, así que el título también decide en qué lugar de la lista queda tu juego.

Contarle más al menú

El menú tiene todo un panel que llenar junto a la lista, y lo llena con el resto de la entrada:

GAMES = {
    {
        TITLE       = "Rocks",
        SCRIPT      = "rocks/rocks.singe",
        CANVAS_X    = 720,
        CANVAS_Y    = 480,
        YEAR        = 2026,
        GENRE       = "Shooter",
        DEVELOPER   = "Your Name Here",
        PUBLISHER   = "Your Name Here",
        DESCRIPTION = "Shoot the rocks before they reach your ship.",
        CABINET     = "rocks/cabinet.png",
        MARQUEE     = "rocks/marquee.png"
    }
}

CABINET y MARQUEE son archivos de imagen normales en la carpeta de tu juego, en cualquier formato que Singe sepa leer. El arte de la recreativa es la imagen grande junto a la lista y la marquesina es la tira de encima. Hazlas del tamaño que quieras; el menú las encaja en sus paneles.

No necesitas un programa de dibujo para hacerlas, porque tu juego puede sacarse su propia foto. Ejecútalo y, cuando la pantalla tenga el aspecto con el que quieres que la vea el mundo, pulsa F12 (o F11, porque algunos escritorios se quedan F12 para ellos). Singe guarda una imagen de la ventana en la carpeta de datos de tu juego, data/rocks, con el nombre singe000.png, luego singe001.png, y así sucesivamente. Saca una de la pantalla de título y otra en mitad de una pelea. Cópialas a tu carpeta rocks y cámbiales el nombre: la de la pelea es cabinet.png y la del título es marquee.png.

Una marquesina de verdad es una tira ancha con el nombre del juego en letras grandes, y una pantalla entera apretujada ahí dentro parece un sello de correos. Servirá hasta que tengas algo mejor. Si dejas fuera MARQUEE, el menú pone ahí la imagen que usa el propio motor cuando falta una, un tablero de ajedrez rosa que dice MISSING, y eso es peor.

YEAR, GENRE, DEVELOPER, PUBLISHER y DESCRIPTION son el texto de debajo, y el motor nunca los mira. Son para la persona que lee el menú, que es de lo que se trata.

CANVAS_X y CANVAS_Y son el tamaño del mundo de tu juego, y 720 por 480 es el valor por defecto — el mismo mundo en el que llevas dibujando desde la lección uno. Ponlos solo si tu juego quiere otra forma. Un juego sin campo VIDEO es un juego sin vídeo, que es lo que es el tuyo; la lección catorce es donde ese campo empieza a importar.

La sección games.dat de la referencia enumera todos los campos que existen, incluidos varios para hardware que todavía no tienes. Vale la pena conocer ya el nombre de unos cuantos más.

REQUIRES dice lo que un juego necesita de la máquina más allá del 2D sencillo: "GUI" para los menús y páginas de la lección veinte, "SCENE" para el 3D que empieza en la lección veintidós, y unos cuantos más. El menú lo lee para poder decirle a un jugador «esta máquina no puede ejecutar eso» en lugar de dejar que el juego falle a medias. Rocks es 2D sencillo, y dejar fuera REQUIRES significa exactamente eso, así que déjalo fuera. Rara vez tendrás que averiguar la lista tú mismo, porque Singe se da cuenta de lo que usa un juego mientras se ejecuta y lo dice cuando la entrada no lo incluye. A partir de la lección veinte verás líneas como esta, tenga o no tenga el juego un games.dat:

Warning:  this game uses GUI, which its games.dat does not list in REQUIRES.

Es un consejo, no un error; el juego funciona de las dos maneras. El arreglo es una línea en la entrada, REQUIRES = { "GUI" },, y al empaquetar un juego en la lección treinta se escribe la lista por ti si la entrada no tiene ninguna. Su compañero TIER, un número del 0 al 3, dice cuánta máquina quiere un juego, y puede esperar hasta que escribas un juego lo bastante pesado como para que importe.

GAME_ID es una identidad única para tu juego, que necesitan las tablas de récords en línea de la lección veintiocho y nada más. Y RESOLUTION_X y RESOLUTION_Y piden un tamaño de ventana concreto. Olvídate del resto hasta que algo te mande a buscarlo.

Ejecutarlo desde el menú

Ejecuta Menu.sh — Menu.bat en Windows — desde tu carpeta de trabajo. Encuentra el Singe más nuevo que tiene al lado y arranca el menú.

Tu juego está en la lista, con su arte al lado y su descripción debajo. Es lo único que hay en la lista, porque rocks es la única carpeta a la que le has dado un games.dat; hello, dodge y las demás no son juegos, por lo que el menú puede saber. Arriba y abajo mueven un juego, izquierda y derecha mueven una página, y start o un botón de disparo juega el que esté seleccionado. Sal del juego con Esc y vuelves al menú, en el mismo juego, listo para otra vez. El menú también recuerda en qué juego estabas de una ejecución a otra.

Eso es todo lo que hace falta para publicar un juego, en lo que al motor respecta. Un jugador copia tu carpeta junto a Singe y aparece.

Escribir el nombre sigue funcionando, y funciona igual:

Singe rocks

Cuando lanzas un script a mano así, Singe busca un games.dat a su lado — y hasta en tres carpetas por encima — y si una entrada nombra el script que has lanzado, los ajustes de esa entrada se le aplican. Así que un juego funciona igual desde una terminal que desde el menú, lo que significa que puedes seguir trabajando como hasta ahora, con -R y un editor de texto, y aun así fiarte de lo que le llegará a un jugador. También escribe en el mismo sitio: lo arranques como lo arranques, la partida guardada de tu juego es la de data/rocks.

Más adelante: un solo archivo

Una carpeta es cómoda para trabajar y algo incómoda para regalar: una docena de archivos, una carpeta dentro de otra y un jugador que la descomprime en el sitio equivocado. Un juego de Singe terminado se puede empaquetar en un único archivo .game que el motor ejecuta directamente, con arte, sonidos y todo, y que un jugador copia junto a Singe y listo.

Para eso no tiene que cambiar nada de tu juego. Es la lección treinta, y vale la pena esperar: empaqueta un juego que no está terminado y mañana lo volverás a empaquetar.

Qué acaba de pasar

GAMES = {
    {

Dos llaves, porque es una lista de registros. La de fuera es la lista. La de dentro es lo primero de la lista, que es el registro de un juego. Equivocarse con una de ellas es el error habitual, y Lua te dirá la línea.

        SCRIPT      = "rocks/rocks.singe",

Se cuenta desde la carpeta de encima del games.dat, que es tu carpeta de trabajo. Es el mismo nombre que escribirías después de Singe para ejecutar el script a mano, y esa es la forma más fácil de recordarlo.

La coma al final de la línea separa un campo del siguiente, exactamente como en la lección seis. El último campo de un registro no lleva coma detrás — a Lua no le importa si la lleva, pero si no la pones tu archivo se parecerá al de todos los demás. Una coma que falta en medio es otra cosa, y es el error de esta lección.

        CABINET     = "rocks/cabinet.png",

Es una imagen que carga el menú, no tu juego, así que se nombra como SCRIPT, desde la carpeta de encima, y no con DIR. DIR es de tu script mientras se ejecuta, y el menú y el motor leen games.dat antes de que tu script haya empezado.

Pruébalo

  1. Haz un arte mejor. Si tienes un programa de dibujo, haz un marquee.png como es debido: una tira ancha con ROCKS en letras grandes. Ponlo en lugar de la captura de pantalla y vuelve a mirar el menú.

  2. Dale un games.dat a Dodge. Escribe un games.dat en tu carpeta dodge de la lección siete y arranca el menú. Ahora hay dos juegos, por orden de título. Luego cambia el TITLE de Rocks a Asteroid Field y mira cómo sube por encima de Dodge: la lista se ordena por título, no por carpeta.

  3. Rompe games.dat para el menú. Borra una de las llaves de cierre del games.dat de rocks y arranca el menú. Tu juego ha desaparecido de la lista, y la terminal dice por qué. Vuelve a ponerla.

  4. Equivócate con SCRIPT. Pon CANVAS_X a 1280 y CANVAS_Y a 720, y ejecuta Singe rocks. La zona de juego es más ancha. Ahora cambia SCRIPT a rocks.singe y vuelve a ejecutarlo. El juego ha vuelto a su tamaño de antes, y nada te lo ha dicho: la entrada ya no nombra el script que has ejecutado, así que no se aplica. Deja los dos como estaban.

  5. Encuentra tu partida guardada. Arranca el juego desde el menú, marca un récord, sal al menú y sal del menú. Ejecuta Singe rocks y mira el título. Luego busca en data/rocks el archivo que lo ha recordado.

Rómpelo a propósito

Quita la coma del final de la línea de TITLE, para que el principio del archivo quede así:

GAMES = {
    {
        TITLE       = "Rocks"
        SCRIPT      = "rocks/rocks.singe",

Ejecuta Singe rocks. El juego arranca, y la terminal dice esto:

Note:  rocks/games.dat ignored:  [string "rocks/games.dat"]:4: '}' expected (to close '{' at line 2) near 'SCRIPT'

Tu juego sigue funcionando, porque un juego arrancado por su nombre no necesita su entrada. Simplemente funciona sin ella. Pero arranca el menú y tu juego ha desaparecido. Si era el único, la lista dice No games yet, y la terminal dice lo mismo de otra forma:

rocks/games.dat:  rocks/games.dat:4: '}' expected (to close '{' at line 2) near 'SCRIPT'  Skipped.

Léelo como cualquier otro error de Lua. El archivo es rocks/games.dat y la línea es la 4. Pero la línea 4 es la de SCRIPT, y no tiene nada de malo. El error está al final de la línea 3. Después de TITLE = "Rocks", Lua esperaba o una coma y otro campo, o la } que cierra el registro que empezó en la línea 2. En su lugar encontró SCRIPT, así que la línea 4 es donde se dio cuenta. Lo que propone para arreglarlo — una } — está mal; la línea que da va una por detrás. Cuando un error señala el principio de una línea, mira el final de la línea anterior.

Vuelve a poner la coma y arranca otra vez el menú.

Lo que has aprendido

  • Un juego es una carpeta: el script, su arte y un games.dat, y nada de fuera de ella salvo la propia carpeta Singe del motor.

  • El nombre de la carpeta es para el ordenador, así que mantenlo sencillo. El nombre para las personas es TITLE.

  • Los nombres que carga tu script se cuentan desde donde se arrancó Singe, y por eso cada uno de ellos se construye a partir de DIR.

  • games.dat es un archivo de Lua que contiene una lista GAMES, y cada entrada es un juego.

  • Una entrada necesita TITLE y SCRIPT y nada más; sus rutas cuentan desde la carpeta de encima del games.dat.

  • CABINET, MARQUEE, YEAR, GENRE, DEVELOPER, PUBLISHER y DESCRIPTION son lo que el menú le muestra al jugador, y F12 saca una imagen que puedes usar para las dos primeras.

  • REQUIRES le dice al menú lo que un juego necesita más allá del 2D, y Singe te avisa cuando un juego usa algo que su entrada no incluye.

  • Menu.sh o Menu.bat arranca el menú incluido, que enumera cada carpeta de juego que tiene al lado, ordenadas por título.

  • Un juego lanzado por su nombre también recibe su entrada de games.dat, así que se comporta igual de las dos formas, y un games.dat que no se puede cargar se avisa y se ignora.

  • Un juego terminado se puede empaquetar más adelante en un solo archivo, en la lección treinta.

La próxima vez

Con esto termina la segunda parte: tienes un juego, con arte, sonido, colisiones, puntuación y una forma de que otra persona lo ejecute. La tercera parte trata de lo que casi ningún otro motor hace — reproducir imágenes filmadas como el mundo en el que ocurre el juego — y la lección catorce empieza con el disco, el fotograma y la espera.

Lección 14: Reproducir vídeo

La lección terminada

Singe puede reproducir una película y ejecutar tu juego dentro de ella. La imagen se convierte en el mundo, y el overlay en el que llevas dibujando desde la lección uno se coloca encima. En esta lección pondrás en marcha un vídeo, averiguarás qué fotograma se está mostrando, lo pararás y saltarás a cualquier momento que quieras.

Antes de nada de eso, hay algo que conviene decir claramente, porque decide si deberías leer siquiera esta parte del libro.

Un juego solo reproduce vídeo si lo pide

Singe es un motor de juegos. Todo lo que has construido en las partes primera y segunda — los sprites, el sonido, las colisiones, la puntuación, la carpeta del juego — es Singe entero, y nada de ello tiene que ver con el vídeo. Lo que añade la tercera parte es un extra: un juego puede pedir que haya una película reproduciéndose detrás, y entonces la película es el mundo en lugar de un lienzo negro.

Nada más cambia. A onOverlayUpdate se le sigue llamando sesenta veces por segundo. overlayPrint sigue contando en celdas de carácter. Tus sprites se dibujan donde se dibujaban antes. Un juego con vídeo y un juego sin él se escriben igual, con las mismas funciones, y comparten el mismo libro.

Así que, si el juego que quieres hacer no tiene vídeo, puedes cerrar esta parte ahora e ir a la cuarta. Nada de la cuarta parte depende de nada de la tercera, y las únicas lecciones que necesitan esta son las cuatro que vienen detrás.

¿Sigues aquí? Bien.

Ya tienes un vídeo

No necesitas buscar uno, ni comprarlo, ni hacerlo. La primera vez que ejecutaste Singe en la lección uno, apareció una carpeta llamada Singe en tu carpeta de trabajo. Ábrela y mira: entre los archivos que desempaquetó el motor está menuBackground.mkv. Es el fondo que usa el propio menú del motor, mide 720 por 480 píxeles y dura 420 fotogramas — unos catorce segundos.

Ese es el vídeo de esta lección y de las dos siguientes.

Crea una carpeta llamada movie en tu carpeta de trabajo, junto a las carpetas de las otras lecciones, y dentro un archivo llamado movie.singe. No hay que preparar nada más. Ejecutas Singe desde la carpeta de trabajo, como llevas haciendo desde la lección uno, así que la carpeta Singe, vídeo incluido, está justo ahí al lado de tu juego, y Singe/menuBackground.mkv es el nombre que le darás al motor dentro de un momento. No hace falta copiar nada.

Escribe esto

dofile("Singe/Framework.singe")


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Frame " .. discGetFrame())
    return OVERLAY_UPDATED
end


discPlay()

Guárdalo.

Ejecútalo

El vídeo no forma parte de tu script, así que no lo cargas en tu script. Se lo das al motor en la línea de comandos, con -v:

Singe -R -v Singe/menuBackground.mkv movie

-v es la forma corta de --framefile, y nombra el vídeo que tiene que reproducir el juego. El nombre de tu script va al final, como siempre. -R es el mismo -R que llevas usando desde la lección uno, y sigue reiniciando el juego cuando guardas.

Pedirlo es todo el sentido de -v. Si dejas un archivo de vídeo junto a tu script y no dices nada, el motor lo ve, lo dice en la consola y ejecuta tu juego sin él. Un juego solo es un juego de vídeo cuando alguien dice que lo es.

Se abre una ventana. La llena una bola de fuego naranja, un dragón se forma a partir del fuego, la palabra SINGE aparece debajo, y luego una cuadrícula magenta se aleja rodando bajo un sol naranja. En la esquina superior izquierda, por encima de todo, hay un número que va subiendo.

Míralo hasta el final. Luego mira qué pasa al final.

Qué acaba de pasar

discPlay()

Singe llama al vídeo el disco, y todas las funciones que lo manejan empiezan por disc. El nombre es histórico: el motor nació reproduciendo juegos que guardaban su película en un laserdisc, y el nombre se quedó pegado a la idea. Es un archivo de vídeo en tu disco duro y nada más.

Un juego tiene como mucho un disco, así que ninguna de las funciones disc recibe un argumento que diga cuál. Solo hay uno.

Esta línea no está dentro de ninguna función. Está al final del archivo, sola, y se ejecuta una vez cuando Singe carga tu script — antes del primer onOverlayUpdate, antes que cualquier otra cosa. Singe no tiene un callback onStartup porque no lo necesita: un script de Lua es una lista de instrucciones, y todo lo que escribas fuera de una función ocurre mientras se lee el archivo. Por convención, el código de arranque va al final, debajo de las funciones.

Necesitas discPlay() porque el disco no arranca solo. Cuando empieza el juego, el motor aparca el disco en el fotograma uno y lo pausa ahí. Nada se mueve hasta que lo pides.

    overlayPrint(2, 2, "Frame " .. discGetFrame())

discGetFrame responde a una pregunta: ¿qué fotograma se está mostrando ahora mismo? No recibe argumentos y devuelve un número.

Fíjate en dónde se dibuja ese número. Columna 2, fila 2 — exactamente donde fue Hello! en la lección uno, y cae en el mismo sitio de la pantalla. El overlay en el que dibujas mide la mitad que el vídeo en cada lado, lo que para un vídeo de 720 por 480 son 360 por 240, que es exactamente el tamaño sobre el que llevas dibujando trece lecciones. Tus coordenadas no se han movido. Si alguna vez reproduces un vídeo de otro tamaño, el overlay cambia de tamaño con él, y overlaySetResolution lo pone al tamaño que quieras; su entrada en la referencia tiene los detalles.

Esta es toda la idea del overlay. El vídeo está debajo. Tu dibujo está encima, y allí donde no has dibujado se ve la película. Por eso overlayClear importa ahora todavía más que antes: limpia el overlay y estarás viendo la película.

Un fotograma es una dirección

El número que devuelve discGetFrame es un número de fotograma. Un fotograma es una imagen fija. Este vídeo tiene 420 y muestra unos treinta cada segundo, así que dura unos catorce segundos.

Los fotogramas se cuentan desde cero, así que este vídeo tiene los fotogramas del 0 al 419. La cantidad y el último número no son lo mismo, y eso pilla a todo el mundo una vez. discGetFrameCount te dice la cantidad — 420 — y el fotograma más alto que puedes pedir es uno menos.

Lo importante de un número de fotograma es que nunca cambia y nunca se desvía. El fotograma 110 es el momento en que el dragón echa fuego, en esta copia del archivo, en este ordenador, hoy y el año que viene. Los segundos se desvían, porque un vídeo no siempre se reproduce exactamente a la velocidad que crees. Un número de fotograma es la dirección de un momento, y los juegos de vídeo se construyen con direcciones: apuntas el fotograma en el que aparece el dragón, y a partir de ahí puedes mandar la película allí cuando quieras.

Encontrar esos números es un trabajo que haces una vez por vídeo, y el script que has escrito es la herramienta para hacerlo: pon la película, mira el contador, apunta los fotogramas en los que pasan cosas. Todo lo de la lección dieciséis se construye sobre una lista de números encontrados exactamente así.

Qué pasó al final

El contador llegó a 419, y luego volvió a ser 0 y el fuego regresó.

Cuando el disco se sale del final, el motor lo vuelve a empezar desde el fotograma cero. No se para, y no te lo dice. Un juego de verdad nunca deja que llegue ahí: vigila el número de fotograma y manda el disco a otro sitio antes de que llegue el final. Olvidarse de hacerlo es la razón de que un juego de vídeo a medio hacer reproduzca de repente su propia secuencia de título en mitad de una pelea.

Parar, saltar y preguntar

Añade esta función encima de onOverlayUpdate:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        if discGetState() == DISC_PLAYING then
            discPause()
        else
            discPlay()
        end
    elseif what == SWITCH_LEFT then
        discSearch(0)
    elseif what == SWITCH_RIGHT then
        discSkipForward(30)
    elseif what == SWITCH_START1 then
        discStop()
    end
end

Guarda y prueba cada una. La barra espaciadora reproduce y pausa. La izquierda vuelve al principio. La derecha salta hacia delante más o menos un segundo. La tecla 1 para el disco del todo, y lo que obtienes es una pantalla azul — el color que mostraba un reproductor de laserdisc cuando estaba parado, que se ha conservado porque muchísimos juegos dibujaban encima su tabla de puntuaciones.

Ahí hay cinco llamadas nuevas, y se dividen en dos tipos.

Preguntar. discGetState devuelve uno de cuatro nombres que el motor ya ha definido por ti: DISC_PLAYING, DISC_PAUSED, DISC_STOPPED y DISC_EJECTED. Son como OVERLAY_UPDATED — sin comillas, porque son nombres de valores y no texto. Compáralos con == como comparabas números en la lección tres.

Ordenar. discPlay empieza o reanuda. discPause se congela en el fotograma que se está mostrando y lo deja en pantalla. discStop es la más contundente: la imagen se sustituye por la pantalla azul, discGetFrame responde 0 hasta que el disco vuelve a ponerse en marcha, y discPause y las llamadas de salto se ignoran mientras está parado. Cualquiera de discPlay, discSearch o discSkipToFrame lo saca de la parada.

Dos llamadas mandan el disco a un fotograma, y la diferencia entre ellas es lo único de esta lección que vale la pena aprenderse de memoria:

  • discSearch(frame) va allí y se pausa en él.

  • discSkipToFrame(frame) va allí y reproduce desde él.

Busca cuando quieras aparcar en una imagen y esperar. Salta cuando quieras que empiece una escena. discSkipForward(30) y discSkipBackward(30) son la misma idea medida desde donde estás en lugar de desde el principio, y dejan el disco reproduciéndose si se estaba reproduciendo y pausado si estaba pausado.

También existe discPauseAtFrame, que hace exactamente lo mismo que discSearch con un nombre más antiguo. La referencia lo marca como alias heredado. Lo verás en scripts de otras personas; en los tuyos, escribe discSearch.

Esperar es más difícil de lo que parece

Esta es la frase de la que está hecho todo juego de vídeo:

Reproduce del fotograma 0 al fotograma 120 y después hazle una pregunta al jugador.

Intenta escribirla. No puedes escribir «reproduce, después espera, después pregunta», porque no tienes dónde escribirlo. Tienes onOverlayUpdate, a la que Singe llama sesenta veces por segundo y que tiene que volver inmediatamente cada una de esas veces. Una función que se sentara a esperar pararía el motor en seco: ni dibujo, ni entrada, ni vídeo.

Así que no puedes decir «después». Tienes que convertir «después» en una variable que recuerde por dónde vas, y comprobarla en cada una de esas sesenta llamadas:

local asking = false


function onOverlayUpdate()
    overlayClear()
    if not asking and discGetFrame() >= 120 then
        discPause()
        asking = true
    end
    if asking then
        overlayPrint(2, 4, "Left or right?")
    end
    return OVERLAY_UPDATED
end

Eso funciona. Léelo y verás que funciona. Pero fíjate en lo que ha costado: una variable, cuyo único trabajo es recordar en qué parte de la frase estás, y dos if para mantenerla en orden.

Ahora añade el resto de la escena. El jugador responde, así que a continuación se reproduce una de dos cosas. Cada una de ellas termina en algún sitio y hace otra pregunta. Un juego con ramificaciones modesto tiene cuarenta de estos momentos, y cada uno quiere su propia variable y su propio if. Acabas con un script en el que la historia no está escrita en ninguna parte — está repartida entre una docena de indicadores, y para averiguar qué pasa después del dragón tienes que leerlos todos.

Quédate con esa idea. La lección quince no es más que el arreglo para eso.

Cuando no hay vídeo

Vuelve a ejecutar tu script de la forma normal, sin -v:

Singe -R movie

No se cuelga nada. Te sale una ventana negra con Frame 0 en la esquina.

Vale la pena entender esto, porque es la mitad tranquilizadora de la promesa del principio de esta lección. Un juego sin disco sigue ejecutando cada llamada disc que hagas; solo que no hacen nada útil. El motor documenta exactamente qué responden, y eso nunca cambia: discGetFrame y discGetFrameCount devuelven 0, discGetState devuelve DISC_EJECTED, discGetWidth y discGetHeight devuelven el tamaño del lienzo, y discPlay, discPause, discSearch y las demás se apuntan en el registro y por lo demás se ignoran.

No puedes romper un script llamando a una función de disco cuando no hay disco.

Cuando un script necesita saberlo, pregunta a SINGE_DISC. Es otro nombre que el motor define antes de que se ejecute tu script, y vale true cuando el juego tiene vídeo y false cuando el mundo es un lienzo sin más. Es la forma correcta de escribir un juego que pueda funcionar de las dos maneras:

    if not SINGE_DISC then
        overlayPrint(2, 2, "This game has no video.")
        overlayPrint(2, 4, "Run it again with -v Singe/menuBackground.mkv")
        return OVERLAY_UPDATED
    end

not le da la vuelta a un valor verdadero o falso, como en la lección tres.

Todo junto

Todo junto, con una pequeña función que convierte el estado en palabras y un fotograma en el que detenerse, este es el script terminado. Es un buscador de fotogramas: la herramienta que usarás cada vez que te encuentres con un vídeo nuevo.

dofile("Singe/Framework.singe")

local stopAt = 400
local held   = false


local function stateName()
    local state = discGetState()

    if state == DISC_PLAYING then
        return "playing"
    elseif state == DISC_PAUSED then
        return "paused"
    elseif state == DISC_STOPPED then
        return "stopped"
    end
    return "not there"
end


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        if discGetState() == DISC_PLAYING then
            discPause()
        else
            discPlay()
        end
    elseif what == SWITCH_LEFT then
        discSearch(0)
        held = false
    elseif what == SWITCH_RIGHT then
        discSkipForward(30)
    elseif what == SWITCH_START1 then
        discStop()
        held = false
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    overlayClear()
    if not SINGE_DISC then
        overlayPrint(2, 2, "This game has no video.")
        overlayPrint(2, 4, "Run it again with -v Singe/menuBackground.mkv")
        return OVERLAY_UPDATED
    end

    if not held and frame >= stopAt then
        discPause()
        held = true
    end

    overlayPrint(2, 2, "Frame " .. frame .. " of " .. discGetFrameCount())
    overlayPrint(2, 4, "The disc is " .. stateName() .. ".")
    overlayPrint(2, 6, "Space plays and pauses.  Left rewinds.")
    overlayPrint(2, 7, "Right jumps on a second.  1 stops the disc.")
    if held then
        overlayPrint(2, 9, "Holding at frame " .. stopAt .. ".")
    end

    return OVERLAY_UPDATED
end


discPlay()

held es el mismo tipo de variable que asking más arriba, y está aquí por una razón que puedes comprobar: quítala, deja if frame >= stopAt then discPause() end, y luego intenta pulsar la barra espaciadora para seguir más allá del fotograma 400. No puedes. El disco se reanuda durante una sexagésima de segundo y el siguiente onOverlayUpdate lo vuelve a pausar, para siempre. held es la forma de decir «esto ya lo he hecho una vez».

Pruébalo

  1. Encuentra el dragón. Ejecútalo, mira el contador y apunta el fotograma en el que aparece el dragón por primera vez, el fotograma en el que echa fuego y el fotograma en el que la cuadrícula se adueña de la pantalla. Querrás tener estos tres números en la lección dieciséis.

  2. Avanza paso a paso. Cambia discSkipForward(30) por discSkipForward(1) y mantén pulsada la flecha derecha. Ahora cambia stopAt a un fotograma en mitad del dragón y usa discSearch y la tecla de flecha para caer exactamente en él.

  3. Haz que se repita. Cambia la parada para que, en lugar de pausar en el fotograma 400, llame a discSkipToFrame(0). Has construido un modo de atracción: una escena que se reproduce sin fin hasta que alguien pulsa un botón.

  4. Pide un fotograma que no existe. Cambia la línea de SWITCH_RIGHT por discSkipToFrame(100000). No se cuelga. Lee la entrada de discSkipToFrame en la referencia y busca la frase que dice por qué.

  5. Juégalo sin el vídeo. Ejecuta Singe -R movie y luego pulsa todas las teclas. Nada de lo que pulses puede romperlo.

Rómpelo a propósito

El error que más tiempo cuesta aquí no es un error de Lua. Ejecuta esto:

Singe -R -v menuBackground.mkv movie

La ruta está mal — se cuenta desde la carpeta de trabajo, y el vídeo está ahí en la carpeta Singe, no suelto — y Singe no arranca. Lo que hace en su lugar es imprimir su lista entera de opciones de línea de comandos, lo que asusta la primera vez, y luego esto como última línea:

Error:  Unable to locate video.

Un muro de opciones así siempre significa lo mismo: el motor no llegó ni a tu juego. Ignora el muro y lee la última línea.

Ese es fácil. La versión traicionera es ejecutarlo sin -v y olvidar que lo has hecho. No hay ningún error, porque un juego sin vídeo es un juego perfectamente bueno. Te sale una pantalla negra y un contador clavado en 0, y te pasas veinte minutos buscando el fallo en tu script.

Para eso está el bloque de SINGE_DISC del script terminado. Tres líneas, y el juego te dice qué pasa en lugar de enfurruñarse. Pon una comprobación así en cada script que escribas que necesite un vídeo.

Lo que has aprendido

  • Un juego solo reproduce vídeo cuando lo pide, y todo lo demás de Singe funciona igual en los dos casos.

  • Singe llama al vídeo el disco. Un juego tiene uno, y las funciones disc no reciben ningún handle porque no hay nada entre lo que elegir.

  • El vídeo va en la línea de comandos con -v, no en el script.

  • El overlay se dibuja sobre la imagen, y la película se ve allí donde no has dibujado.

  • Un fotograma es una imagen fija, se cuentan desde cero, y un número de fotograma es la dirección de un momento.

  • discGetFrame pregunta dónde está el disco; discGetFrameCount dice cuántos fotogramas hay; discGetState dice qué está haciendo el disco.

  • discPlay, discPause y discStop lo manejan. discSearch va a un fotograma y pausa; discSkipToFrame va a un fotograma y reproduce.

  • Un disco que se sale del final vuelve a empezar en el fotograma cero sin decírtelo.

  • Sin disco, toda llamada disc es inofensiva, y SINGE_DISC es como un script sabe en qué tipo de juego está.

  • No puedes esperar dentro de onOverlayUpdate, así que el «después» hay que escribirlo como una variable.

La próxima vez

Ese último punto es el que duele. Un juego de vídeo es una lista de pasos — reproduce esto, pregunta aquello, reproduce lo otro — y acabas de ver que el modelo de callbacks no puede decir «después» sin un indicador y un if para cada paso. La lección quince te enseña la otra forma que te deja Singe de escribir un script, en la que «después» es una línea nueva.

Lección 15: La otra forma de escribirlo

La lección terminada

Hasta ahora, todas las lecciones se han escrito de la misma manera. Escribes funciones cuyos nombres empiezan por on, Singe las llama cuando le parece, y tú nunca dices en qué orden pasa nada. Ese es el modelo dirigido por eventos, y es como funcionan la mayoría de los motores de juegos.

Singe tiene un segundo modelo. En él escribes tu juego como una lista de pasos, de la primera línea a la última, y se te permite esperar. En esta lección escribirás la misma secuencia corta de vídeo de las dos formas y verás la diferencia con tus propios ojos.

La secuencia

Esto es lo que hace el juego, dicho en español:

  1. Empieza la película desde el principio y reprodúcela hasta el fotograma 120.

  2. Para ahí y pide al jugador que pulse la barra espaciadora.

  3. Cuando la pulse, sigue reproduciendo hasta el fotograma 300.

  4. Para ahí, di «The end.», espera cuatro segundos y sal.

Cuatro pasos. Vuelve a leerlos y fíjate en que todos llevan la palabra «después», dicha o no.

La forma que ya conoces

Crea un archivo llamado events.singe en la carpeta movie de la lección catorce, y escribe esto:

dofile("Singe/Framework.singe")

local step    = 1
local endedAt = 0


function onInputPressed(what)
    if what == SWITCH_BUTTON1 and step == 2 then
        step = 3
        discPlay()
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    overlayClear()
    overlayPrint(2, 2, "Frame " .. frame)

    if step == 1 then
        if frame >= 120 then
            discPause()
            step = 2
        end
    elseif step == 2 then
        overlayPrint(2, 4, "Press the space bar to go on.")
    elseif step == 3 then
        if frame >= 300 then
            discPause()
            endedAt = singeGetTicks()
            step = 4
        end
    elseif step == 4 then
        overlayPrint(2, 4, "The end.")
        if singeGetTicks() - endedAt > 4000 then
            singeQuit()
        end
    end

    return OVERLAY_UPDATED
end


discSearch(0)
discPlay()

Ejecútalo. Nombrar la carpeta ejecutaría movie.singe, así que nombra el script en su lugar, como te enseñó la lección uno:

Singe -R -v Singe/menuBackground.mkv movie/events.singe

Funciona. Hace exactamente los cuatro pasos. singeGetTicks es nueva — te devuelve el número de milisegundos que han pasado desde que arrancó el motor, que es la forma normal de medir un rato — y singeQuit termina el juego, que es lo que el motor hace por ti cuando pulsas Esc.

Ahora lee el script e intenta encontrar en él los cuatro pasos. Están, pero del revés. El orden de la historia está escrito en los valores de step, no en el orden de las líneas, y step se cambia en una función y se lee en otra. Para responder a «¿qué pasa después de que el jugador pulse la barra espaciadora?» tienes que tener todo el asunto en la cabeza a la vez.

Y esta es la versión fácil. Tiene dos decisiones.

La otra forma

Empieza un archivo nuevo, steps.singe, y escribe esto:

local message = ""
local pressed = false


local function drawFrame()
    overlayClear()
    overlayPrint(2, 2, "Frame " .. discGetFrame())
    overlayPrint(2, 4, message)
end


local function playTo(frame)
    while discGetFrame() < frame do
        drawFrame()
        singeYield()
    end
end


local function waitForButton()
    pressed = false
    while not pressed do
        drawFrame()
        singeYield()
    end
end


local function waitSeconds(seconds)
    local stopTime = singeGetTicks() + seconds * 1000

    while singeGetTicks() < stopTime do
        drawFrame()
        singeYield()
    end
end


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        pressed = true
    end
end


function singeMain()
    discSearch(0)
    discPlay()
    playTo(120)
    discPause()

    message = "Press the space bar to go on."
    waitForButton()

    message = ""
    discPlay()
    playTo(300)
    discPause()

    message = "The end."
    waitSeconds(4)
end


dofile("Singe/Framework.singe")

Ejecútalo igual que antes, terminando en movie/steps.singe. Hace las mismas cuatro cosas.

Ahora lee singeMain. Los cuatro pasos son los cuatro párrafos, en orden, de arriba abajo, y no hay ninguna variable step por ningún lado, porque la posición en la historia es la posición en la función. De eso trata toda esta lección.

Qué acaba de pasar

function singeMain()

singeMain es un nombre que Singe busca, como onOverlayUpdate. Si tu script la define, el framework ejecuta tu juego desde ella: se llama una vez, al principio, y tu juego dura lo que dure. Cuando vuelve, el juego se cierra.

        singeYield()

Esta es la llamada que lo hace posible, y significa «deja que pase un fotograma».

Singe no está haciendo dos cosas a la vez — aquí nada se ejecuta en paralelo, por mucho que lo sugiera el nombre de modelo con hilo («threaded»). Lo que pasa es que singeYield detiene tu función donde está, le devuelve el control al motor y recuerda el sitio exacto. El motor dibuja el fotograma, lee la entrada, hace avanzar el vídeo y luego vuelve a poner en marcha tu función desde la línea que sigue al singeYield, con todas las variables exactamente como las dejaste.

Así que un bucle while con un singeYield dentro es una forma de esperar. Es la única forma de esperar, y tienes que poner uno en cada bucle que esté esperando algo. Es un trato que haces con el motor: puedes sentarte a esperar, siempre que le devuelvas el fotograma sesenta veces por segundo.

local function playTo(frame)
    while discGetFrame() < frame do
        drawFrame()
        singeYield()
    end
end

Singe no tiene una función de «espera hasta que el vídeo llegue al fotograma 120». No le hace falta, porque puedes escribirla en cuatro líneas, y acabas de hacerlo. Sigue mientras al disco le falte para llegar al fotograma que quieres; devuelve un fotograma en cada vuelta.

waitForButton tiene la misma forma con otra pregunta, y waitSeconds es otra vez la misma forma con un reloj. Tres funciones pequeñas, escritas una vez, y gracias a ellas singeMain se lee como las frases en español del principio de la lección. Esto es exactamente para lo que, según la lección cinco, servían tus propias funciones.

        drawFrame()
        singeYield()

Cada bucle de espera dibuja antes de ceder el fotograma, y esta es la parte que sorprende a la gente. En el modelo con hilo no hay un onOverlayUpdate tuyo, así que no se dibuja nada a menos que lo dibujes tú. Lo que dibujes antes de un singeYield es lo que aparece en ese fotograma. Deja de dibujar y el overlay deja de cambiar.

Por eso existe message. singeMain le da valor, drawFrame lo imprime, y los tres bucles de espera llaman a drawFrame. Es un precio pequeño por recuperar el orden de la historia.

dofile("Singe/Framework.singe")

Al final. Esto importa más que cualquier otra cosa de la lección, así que vale la pena saber por qué.

dofile ejecuta otro script dentro del tuyo, y una de las cosas que hace el framework mientras se ejecuta es buscar una función llamada singeMain. Si la encuentra, envuelve tu juego alrededor de ella y escribe un onOverlayUpdate propio, cuyo único trabajo es volver a poner en marcha tu singeMain una vez por fotograma. Si no la encuentra, no hace nada de eso, y tu juego es un juego normal dirigido por eventos.

Así que el framework tiene que cargarse después de que exista singeMain. Cárgalo arriba, como en todas las lecciones desde la séptima, y en el momento en que mira todavía no hay ninguna singeMain, y te queda un juego sin juego dentro.

Las reglas

Hay cuatro, y entre todas cubren cada error que puedes cometer aquí.

El framework va al final. Por la razón de arriba.

No escribas tu propio onOverlayUpdate. El framework ya ha escrito uno, y solo puede haber uno: gana el que se escriba el último, y el otro se descarta sin decir nada. Encima del dofile, el tuyo desaparece y lo que dibujas no aparece nunca. Debajo, desaparece el del framework y tu singeMain no vuelve a ejecutarse. En lugar de eso, dibuja desde dentro de singeMain.

Cada bucle que espera necesita un singeYield. Un bucle sin él no devuelve nunca el fotograma. La ventana deja de redibujarse, deja de responder, y el juego se ha perdido; para salir tienes que cerrar la terminal. No hay mensaje de error, porque desde el punto de vista del motor tu función todavía no ha terminado.

Volver de singeMain cierra el juego. Lo cual es muy limpio cuando es lo que quieres y una sorpresa cuando no. Un juego que tiene que seguir para siempre acaba con un bucle que nunca termina:

    while true do
        drawFrame()
        singeYield()
    end

La entrada sigue llegando

Mira otra vez dónde se cambia pressed:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        pressed = true
    end
end

Eso es un callback, en un script escrito como una lista de pasos. Los dos modelos funcionan a la vez, y así tiene que ser.

Cuando existe singeMain, solo se te quita onOverlayUpdate. Todo lo demás — onInputPressed, onInputReleased, onKeyPressed, onSoundCompleted, onShutdown, todos ellos — se dispara exactamente igual que siempre, en los huecos entre tus cesiones. Así que la forma habitual de escribir un juego en este modelo es la que acabas de usar: la historia en singeMain, y un callback pequeño que atrapa un evento y deja una nota para que la historia la encuentre.

waitForButton pone pressed a false antes de empezar a esperar, y así tira todo lo que el jugador haya aporreado antes. Quita esa línea y un botón pulsado durante el vídeo cuenta como la respuesta a una pregunta que todavía no se ha hecho.

Cuál usar

Ningún modelo es mejor que el otro. Sirven para trabajos distintos, y un juego de verdad usa el que encaje.

El modelo con hilo va bien con todo lo que sea una secuencia. Reproduce esto, luego pregunta, luego reproduce aquello. Una introducción. Una cinemática. Un tutorial. Un combate contra un jefe con tres fases. Cualquier cosa que describirías de forma natural como una lista numerada es una singeMain esperando a que la escriban, y el vídeo es lo más secuencial que existe, y por eso la tercera parte llega a este modelo aquí.

El modelo dirigido por eventos va bien con todo lo que sea una situación. Diez enemigos y un jugador, todos moviéndose, todos chocando, ninguno en ningún orden. El juego que escribiste en la lección siete no tiene ninguna secuencia: cada fotograma es la misma pregunta hecha otra vez, que es exactamente la forma de onOverlayUpdate. Escríbelo como una lista de pasos y no ganas nada y pierdes la claridad.

Cuando un juego es las dos cosas — y la mayoría lo son — se escribe de las dos formas. singeMain recorre los niveles en orden, y dentro de cada nivel un bucle hace el trabajo de la lección siete sesenta veces por segundo hasta que el nivel termina.

Pruébalo

  1. Añade un paso. Después de waitForButton, haz que la película salte hacia atrás en lugar de seguir: discSkipToFrame(0), luego playTo(60), y después sigue como antes. Dos líneas nuevas en un solo sitio, y nada más del script tiene que enterarse.

  2. Añade el mismo paso al otro. Ahora hazlo en events.singe. Cuenta cuántos sitios has tenido que tocar.

  3. Escribe waitFrames. Una cuarta función auxiliar, junto a las otras tres, que espere un número dado de fotogramas de vídeo en lugar de un número dado de segundos. Usa discGetFrame y recuerda dónde empezaste.

  4. Quita una cesión. Borra el singeYield() de dentro de playTo y ejecútalo. Prepárate para cerrar la terminal, porque nada más lo detiene. Ahora vuelve a ponerlo y borra drawFrame() en su lugar, y averigua, por lo que ves, por qué el contador de fotogramas se para pero la película no.

  5. Haz un bucle. Mete todo singeMain dentro de while true do …​ end para que la secuencia vuelva a empezar en lugar de terminar. Esc te sigue sacando, porque eso nunca ha sido trabajo tuyo.

Rómpelo a propósito

Mueve la línea dofile("Singe/Framework.singe") del final de steps.singe al principio, y ejecútalo.

No hay ningún error. No se imprime nada. Se abre la ventana, el primer fotograma de la película se queda ahí, y eso es todo lo que pasa, para siempre.

Este es el peor tipo de fallo, y la razón por la que vale la pena conocerlo a propósito. Desde el punto de vista del motor no ha ido nada mal: tu script se ha cargado, el framework se ha cargado, y ninguno de los dos ha definido un onOverlayUpdate, así que el motor no tiene nada a lo que llamar. El disco está aparcado en el fotograma uno, en pausa, exactamente como lo dejó el motor, porque el discPlay que lo habría puesto en marcha está dentro de una singeMain que nadie ejecuta nunca.

Cuando un juego con hilo no hace nada de nada, mira primero la última línea del archivo. Casi siempre es eso.

Lo que has aprendido

  • Singe tiene dos formas de escribir un script, y eliges una definiendo singeMain o no.

  • En el modelo con hilo tu juego es una lista de pasos y se ejecuta de arriba abajo.

  • singeYield() le devuelve un fotograma al motor y sigue desde la línea siguiente.

  • Esperar es un bucle while con un singeYield dentro. La función de espera que necesites la escribes tú; el motor no trae ninguna.

  • No se dibuja nada a menos que lo dibujes tú, antes de ceder, en cada fotograma.

  • dofile("Singe/Framework.singe") va al final de un script con hilo.

  • No escribas tu propio onOverlayUpdate cuando existe singeMain.

  • Todos los demás callbacks se siguen disparando, así que los eventos y los pasos se mezclan sin problema.

  • Volver de singeMain termina el juego.

  • Las secuencias piden el modelo con hilo; las situaciones, el dirigido por eventos.

La próxima vez

Ya puedes escribir «reproduce esto, luego pregunta, luego reproduce aquello» en tres líneas. Un juego de vídeo con ramificaciones no es más que esa frase, unos cuantos cientos de veces, con las respuestas decidiendo qué línea viene después. La lección dieciséis construye uno, y resulta que lo interesante no es el vídeo en absoluto. Es guardar el mapa de qué lleva adónde de una forma que todavía puedas leer cuando el juego tenga cuarenta escenas.

Lección 16: Ramificaciones

La lección terminada

Un juego de vídeo con ramificaciones es una película con bifurcaciones. Se reproduce una escena, el jugador elige, y a continuación se reproduce una escena distinta. Haz eso veinte o treinta veces y tendrás un juego al que la gente volverá durante años intentando encontrar el final que no ha visto.

En esta lección vas a construir uno. Tiene cuatro escenas, dos elecciones, un temporizador en cada elección, una muerte y tres vidas. El código que lo reproduce tiene unas treinta líneas, y seguiría teniendo unas treinta líneas si el juego tuviera doscientas escenas — porque el juego en sí no va a estar escrito en código en absoluto.

Imagina que es un dragón

El vídeo que tiene todo el mundo es Singe/menuBackground.mkv, los mismos 420 fotogramas que llevas manejando desde la lección catorce. Es una bola de fuego, un dragón hecho de papel, la palabra SINGE y luego una cuadrícula magenta que se aleja rodando bajo un sol naranja, para siempre.

No es un drama. No sale nadie que pueda estar en peligro, y al atardecer le da igual lo que decidas.

Sígueme el juego de todos modos. El dragón es lo bastante real durante dos minutos, y todo lo que vas a escribir funciona exactamente igual cuando las imágenes son de un especialista cayendo por un acantilado. Aquí tienes el mapa, y los números de fotograma son los que encontraste tú mismo en la lección catorce:

Escena Fotogramas Qué pasa

arrive

0 a 119

Fuego, y el dragón aterriza. ¿Izquierda o derecha?

sunset

120 a 259

Echa fuego. ¿Te agachas a la izquierda o corres a la derecha?

pit

260 a 339

Te come. Pierdes una vida.

escape

340 a 410

La cuadrícula se aleja y has escapado.

Lo diestro, por así decirlo, es ir siempre a la izquierda: la izquierda desde arrive lleva a sunset, y la izquierda desde sunset te lleva a escape. La derecha lleva a pit las dos veces, y tardar demasiado también.

El mapa son datos, no código

Aquí tienes el juego entero, y es una tabla.

local scenes = {
    arrive = {
        first  = 0,
        last   = 119,
        ask    = 30,
        prompt = "The dragon lands.  Left or Right?",
        left   = "sunset",
        right  = "pit",
        goesTo = "pit"
    },
    sunset = {
        first  = 120,
        last   = 259,
        ask    = 170,
        prompt = "It breathes fire.  Duck Left or run Right?",
        left   = "escape",
        right  = "pit",
        goesTo = "pit"
    },
    pit = {
        first  = 260,
        last   = 339,
        death  = true,
        goesTo = "arrive"
    },
    escape = {
        first  = 340,
        last   = 410
    }
}

Una tabla con nombres a la izquierda en lugar de números, exactamente como en la lección seis, y cada valor de dentro es otra tabla. Cada una de esas tablas interiores es un registro: una escena, descrita campo a campo.

scenes.arrive es la primera escena. scenes.arrive.first es 0. scenes.arrive.left es la cadena "sunset", que es el nombre de otra escena de la misma tabla — y así es como se apuntan las bifurcaciones. Una escena no contiene la escena que va después de ella. Contiene el nombre de la escena que va después, y el nombre se busca cuando llega el momento.

Los campos significan esto:

first y last

Los fotogramas entre los que va la escena.

ask

El fotograma en el que aparece la pregunta. El jugador tiene de ask a last para responder, y ese es el temporizador.

prompt

Lo que dice la pregunta.

left y right

La escena a la que lleva cada respuesta.

goesTo

Adónde va la escena cuando nadie ha elegido — porque al jugador se le acabó el tiempo, o porque para empezar no había ninguna pregunta. En pit, que es una muerte, es adonde vuelve el reintento.

death

Está presente, y vale true, solo en una escena que cuesta una vida.

Hay tres cosas en las que vale la pena fijarse en esa tabla.

La primera es que es el documento de diseño. Puedes dársela a alguien que no ha escrito nunca una línea de Lua y sacará el juego de ella con solo leerla. Cuando quieras que el dragón se bifurque en tres caminos, añades un campo. Cuando quieras otra escena, añades otro registro. No vas a buscar el código que reproduce las escenas, porque no lo cambias.

La segunda es que los registros no tienen todos la misma forma. pit no tiene ask, ni prompt, ni left — en él no hay nada que elegir. escape no tiene goesTo, porque es el final y no va a ninguna parte. Un campo que no está en una tabla se lee como nil, que es la palabra que conociste en la lección tres para «ahí no hay nada», y pedir scenes.escape.goesTo no es un error. Es nil, y nil es una respuesta. El código que lee estos registros tiene que estar preparado para eso, y dentro de un momento verás la única línea que lo está.

La tercera es lo que la tabla no contiene: nada de ella dibuja, reproduce ni espera. Es una descripción. Esa separación es todo el truco de esta lección.

Una función que reproduce cualquier escena

Esta es la mitad hecha de código, y solo hay una función de cierto tamaño. Escrita en el modelo con hilo de la lección quince, porque un juego con ramificaciones es lo más secuencial que existe.

local function playScene(name)
    local scene = scenes[name]

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do
        local frame  = discGetFrame()
        local asking = scene.ask ~= nil and frame >= scene.ask

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end
        drawScene(scene, frame, asking)
        singeYield()
    end
    discPause()

    if scene.death then
        lives = lives - 1
        if lives == 0 then
            ending = "The dragon wins.  Game over."
            return nil
        end
        waitForGo("Press the space bar to try again.")
    end

    return scene.goesTo
end

Recibe el nombre de una escena, la reproduce y devuelve el nombre de la escena que va a continuación. Ese es todo su contrato, y entonces el juego son tres líneas:

function singeMain()
    local scene = "arrive"

    while scene ~= nil do
        scene = playScene(scene)
    end
    waitForGo(ending .. "  Space to quit.")
end

Empieza en arrive. Reproduce la escena que tengas en la mano, y quédate con lo que te devuelva. Cuando te devuelva nil no hay escena siguiente, el bucle termina y la partida se acaba.

Todo junto

Crea dragon.singe en tu carpeta movie y escribe esto. Es el script más largo del libro hasta ahora, y cada parte de él ya está explicada salvo las dos pequeñas funciones auxiliares, que vienen después.

local FPS = 30

local scenes = {
    arrive = {
        first  = 0,
        last   = 119,
        ask    = 30,
        prompt = "The dragon lands.  Left or Right?",
        left   = "sunset",
        right  = "pit",
        goesTo = "pit"
    },
    sunset = {
        first  = 120,
        last   = 259,
        ask    = 170,
        prompt = "It breathes fire.  Duck Left or run Right?",
        left   = "escape",
        right  = "pit",
        goesTo = "pit"
    },
    pit = {
        first  = 260,
        last   = 339,
        death  = true,
        goesTo = "arrive"
    },
    escape = {
        first  = 340,
        last   = 410
    }
}

local answer = nil
local ending = "You got out alive."
local lives  = 3


local function drawScene(scene, frame, asking)
    overlayClear()
    overlayPrint(2, 2, "Lives: " .. lives)
    if scene.death then
        overlayPrint(2, 4, "That did not go well.")
    elseif asking then
        overlayPrint(2, 4, scene.prompt)
        overlayPrint(2, 6, math.ceil((scene.last - frame) / FPS) .. " seconds left.")
    end
end


local function waitForGo(text)
    answer = nil
    while answer ~= "go" do
        overlayClear()
        overlayPrint(2, 2, "Lives: " .. lives)
        overlayPrint(2, 4, text)
        singeYield()
    end
end


local function playScene(name)
    local scene = scenes[name]

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do
        local frame  = discGetFrame()
        local asking = scene.ask ~= nil and frame >= scene.ask

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end
        drawScene(scene, frame, asking)
        singeYield()
    end
    discPause()

    if scene.death then
        lives = lives - 1
        if lives == 0 then
            ending = "The dragon wins.  Game over."
            return nil
        end
        waitForGo("Press the space bar to try again.")
    end

    return scene.goesTo
end


function onInputPressed(what)
    if what == SWITCH_LEFT then
        answer = "left"
    elseif what == SWITCH_RIGHT then
        answer = "right"
    elseif what == SWITCH_BUTTON1 then
        answer = "go"
    end
end


function singeMain()
    local scene = "arrive"

    while scene ~= nil do
        scene = playScene(scene)
    end
    waitForGo(ending .. "  Space to quit.")
end


dofile("Singe/Framework.singe")

Ejecútalo:

Singe -R -v Singe/menuBackground.mkv movie/dragon.singe

Juega cuatro o cinco veces. Ve a la izquierda dos veces y escapa. Ve a la derecha y deja que te coma. Quédate de brazos cruzados y que te coma igualmente. Pierde las tres vidas.

Qué acaba de pasar

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do

Una escena es un salto seguido de una espera, que es el patrón de la lección quince con los números saliendo del registro en lugar de estar escritos a mano. discSkipToFrame va a un fotograma y reproduce desde ahí, que es justo lo que es un cambio de escena.

El número de fotograma es correcto en el instante en que vuelve la llamada, así que el while nunca cree que sigue en la escena que acabas de dejar.

        local asking = scene.ask ~= nil and frame >= scene.ask

La única línea que está preparada para un campo que falta, y la razón por la que la escena de muerte puede dejar fuera ask.

and significa que las dos mitades tienen que ser verdaderas, como en la lección tres, y Lua comprueba primero la mitad izquierda. Si scene.ask es nil, la mitad izquierda es falsa, Lua se para ahí y la comparación de la derecha no llega a hacerse. Y menos mal, porque comparar nil con un número es un error, y te lo encontrarás al final de esta lección.

asking es la respuesta a «¿está la pregunta en pantalla ahora mismo?», calculada una vez por fotograma y usada tres veces.

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end

Mientras la pregunta no está puesta, todo lo que pulse el jugador se tira. Tiene que ser así, o un jugador que se apoye en la flecha izquierda durante la película responderá a una pregunta que no ha leído.

Una vez que la pregunta está puesta, una respuesta termina la escena en el acto. return scene[answer] merece una segunda mirada: answer guarda la cadena "left" o "right", y scene["left"] es lo mismo que scene.left. Poner el nombre entre corchetes en lugar de después de un punto te deja buscar un campo cuyo nombre tienes guardado en una variable. Dos líneas de código para las dos respuestas, y con cinco respuestas seguirían siendo dos líneas.

El elseif también explica por qué solo se dejan pasar "left" y "right". La barra espaciadora pone answer a "go", y scene["go"] es nil, así que pulsar la barra espaciadora sin querer durante una pregunta terminaría el juego en silencio. Di qué aceptas.

    discPause()

Justo después del bucle, y es fácil olvidarlo. La escena ha llegado a su último fotograma, pero el disco no tiene ni idea de que la escena ha terminado — sigue reproduciendo de corrido lo que haya a continuación en el archivo, que en un juego de verdad es la mitad de una escena de otro sitio completamente distinto. Páralo en cuanto dejes de quererlo.

    if scene.death then
        lives = lives - 1

scene.death es nil en todas las escenas salvo pit, y nil cuenta como falso en un if, así que esto se lee como «si esta escena ha sido una muerte». No tienes que escribir death = false en los otros tres registros, y no deberías: que falte el campo lo dice igual de bien, y así hay un único sitio que decide qué escenas son mortales.

El reintento son las dos líneas de debajo. Quita una vida y, si queda alguna, quédate en el fotograma y espera a la barra espaciadora. Luego return scene.goesTo manda al jugador de vuelta a arrive, y quien lo sabe es el registro. Cambia goesTo a "sunset" y el reintento se convierte en un punto de control en lugar de volver a empezar — una palabra, y cambia la dificultad del juego.

        overlayPrint(2, 6, math.ceil((scene.last - frame) / FPS) .. " seconds left.")

El temporizador. scene.last - frame es cuántos fotogramas quedan, y dividirlo por los fotogramas de un segundo lo convierte en segundos. math.ceil redondea un número hacia arriba hasta el siguiente entero, así que la cuenta atrás pone 3, 2, 1 y nunca 0.4 ni 2.966666.

FPS es 30 porque este vídeo va a algo más de treinta fotogramas por segundo. Es el único número del script que es una suposición, y es una suposición con nombre al principio del archivo en lugar de un 30 enterrado en mitad de una línea, para que cuando cambies de vídeo haya exactamente una cosa que cambiar.

Fíjate en contra qué se mide el temporizador: la película. El jugador compite contra el vídeo, no contra un reloj, así que la pregunta nunca puede durar más que el plano al que pertenece. Esa es la razón por la que los juegos con ramificaciones cuentan en fotogramas.

Por qué no escribirlo a mano

Podrías escribir este juego como una sola función larga. Reproduce los fotogramas 0 a 119; si izquierda, reproduce 120 a 259; si izquierda otra vez, reproduce 340 a 410; si no, reproduce 260 a 339, quita una vida y vuelve arriba. Con cuatro escenas sería más corto que lo que tienes.

Con cuarenta escenas sería un desastre, y vale la pena ser preciso sobre por qué.

Los números de fotograma estarían repartidos por todo el código, cada uno escrito una vez y sin nombre, así que cambiar dónde empieza una escena significaría encontrar cada sitio donde se menciona. La forma de la historia estaría enterrada en la forma de las instrucciones if, así que nadie podría ver el juego sin leerlo entero. Y añadir una escena significaría editar el código que reproduce, que es el código que ya funciona — cada escena nueva, otra ocasión de romper una vieja.

La versión que has escrito tiene un trozo de código que reproduce escenas y un trozo de datos que dice cuáles son las escenas. Añadir una escena solo toca los datos. Eso vale la media hora de más que te ha costado, y es la misma idea que hay debajo del archivo games.dat de la lección trece: describe la cosa, y luego escribe un trozo de código que lea la descripción.

Pruébalo

  1. Añade un final. Dale a escape una pregunta y una segunda escena final que reutilice fotogramas de algún punto de la película. Solo cambia la tabla.

  2. Hazlo justo. Baja ask en las dos escenas para que el jugador tenga cinco segundos en lugar de tres, y luego súbelo para que tenga uno. Encuentra el número que publicarías de verdad.

  3. Mueve el punto de control. Cambia el goesTo de pit a "sunset" y juega. Luego piensa en qué pasa si un jugador muere en arrive — y en si la escena de muerte debería saber de dónde viene en lugar de que se lo digan.

  4. Cuenta lo que ha visto el jugador. Añade una tabla junto a scenes que apunte qué nombres de escena se han reproducido, y muestra la cuenta en la esquina. Ahora tienes un juego que puede decir «has encontrado tres de los cinco finales».

  5. Rompe el mapa. Cambia el left de arrive a "cave", una escena que no existe. Ejecútalo, ve a la izquierda y lee lo que dice Lua. Ese error es el más común que tiene un juego dirigido por datos, y conocer su forma te ahorra una hora.

Rómpelo a propósito

Quita la guarda de la línea de asking, para que quede así:

        local asking = frame >= scene.ask

Ejecútalo y ve a la derecha. La escena arrive se reproduce bien, porque arrive tiene un ask. Luego empieza la escena pit, que no lo tiene, y el juego se para con esto:

Error executing function 'onOverlayUpdate':  movie/dragon.singe:68: attempt to compare nil with number
stack traceback:
	[C]: in function 'error'
	Singe/Framework.singe:603: in function 'onOverlayUpdate'

Léelo como te enseñó la lección uno. El archivo y la línea van primero, y son exactamente correctos: la línea 68 es la que acabas de cambiar. La queja es el resto: le has preguntado a Lua si un número era mayor que nil, y Lua no tiene ni idea. scene.ask es nil porque el registro pit no tiene campo ask, y un campo que no está es nil.

Hay una parte de ese mensaje que merece una explicación, porque es una mentira por omisión. La función que nombra es onOverlayUpdate, que tú no has escrito. Es la del propio framework, la que según la lección quince se instala para mover tu singeMain. El error ha salido a través de ella, así que ese es el nombre que el motor tenía a mano, y la traza de la pila que hay debajo — la lista de las funciones que se estaban ejecutando, empezando por la más interna — solo puede mostrar al framework pasando tu error. No hagas caso a ninguno de los dos. El archivo y la línea de arriba son tuyos, y son los que dicen la verdad.

Lo que has aprendido

  • Un juego con ramificaciones es un conjunto de escenas, cada una de las cuales nombra las escenas que van después de ella.

  • Guarda las escenas como datos — una tabla de registros — y el código que las reproduce seguirá siendo una sola función por mucho que crezca el juego.

  • Un registro guarda el nombre de la escena siguiente, no la escena, y el nombre se busca cuando hace falta.

  • Un campo que no está en un registro es nil, lo cual no es un error, y el código que lee registros tiene que contar con ello.

  • scene[answer] busca el campo cuyo nombre está en una variable; scene.left y scene["left"] son el mismo campo.

  • Pon el temporizador sobre el vídeo: una elección dura de un fotograma a otro, así que nunca puede durar más que su propio plano.

  • Tira todo lo que el jugador haya pulsado antes de que apareciera la pregunta.

  • Pausa el disco en cuanto termine una escena, o seguirá reproduciendo las imágenes de la escena siguiente.

  • Un campo ausente que hace las veces de falso — death en tres de los cuatro registros — mantiene la descripción corta y honesta.

  • Comparar nil con un número es un error, y and es la forma de evitarlo.

La próxima vez

Tu juego pregunta izquierda o derecha. Las máquinas recreativas en las que creció este tipo de juego preguntaban algo más difícil: apunta a la cosa de la pantalla y dispárale. La lección diecisiete trata de las pistolas de luz — adónde apunta el jugador, qué hace el juego con eso y la calibración sin la que no puede vivir una recreativa de verdad.

Lección 17: Pistolas de luz

La lección terminada

Vas a hacer una galería de tiro. Aparecen dianas sobre el vídeo en los fotogramas que tú eliges, apuntas a la pantalla y aprietas un gatillo, y las que aciertas puntúan.

No necesitas una pistola de luz para escribir esto. Necesitas un ratón, porque para Singe una pistola de luz es un ratón: informa de una posición en las mismas coordenadas, con las mismas llamadas, y su gatillo llega como el mismo interruptor que un botón del ratón. Escribe el juego para el ratón de tu mesa y funcionará en una recreativa con una pistola atornillada, que es la única forma sensata de hacerlo. Una pistola no es otro tipo de entrada. Es un ratón que alguien apunta.

A qué apuntas

Empieza igual que en la lección catorce, con el vídeo que el motor ha desempaquetado para ti:

Singe -R -v Singe/menuBackground.mkv gallery

Esas imágenes son una cuadrícula morada y una puesta de sol. No son un atraco a un banco. Todos los números de fotograma de esta lección se refieren a ellas para que el código funcione el mismo día que lo escribes, y el clip entero mide 720 por 480 y dura unos 420 fotogramas, que a unos treinta fotogramas por segundo son catorce segundos. Imagínate algo mejor. Al código le da igual lo que haya en la imagen.

Ajusta el overlay al vídeo

Pon esto al principio de gallery.singe, debajo de la línea del dofile:

overlaySetResolution(discGetWidth(), discGetHeight())

Sin esa llamada, el overlay mide la mitad que el vídeo en cada dirección — aquí, 360 por 240 — y cada coordenada con la que dibujas, y cada posición del ratón que te llega, está en ese espacio más pequeño. El overlay pequeño no tiene nada de malo, pero es una conversión más que tener en la cabeza mientras averiguas dónde ha caído un disparo. Ajustarlo al vídeo significa que una diana en x = 80 está a ochenta píxeles del borde de la imagen, y un disparo en x = 80 también. La entrada de la referencia de overlaySetResolution explica lo que cuesta.

Adónde apunta la pistola

Eso lo responde una sola llamada:

local x, y = mouseGetPosition(0)

mouseGetPosition te devuelve dos números, algo que todavía no habías visto hacer a una función y con lo que Lua está encantado: una función puede devolver tantos valores como quiera, y tú los recoges poniendo a la izquierda del = otros tantos nombres. El 0 dice por qué dispositivo apuntador preguntas, contando desde cero. Con un ratón, o con una pistola, la respuesta es siempre el dispositivo 0.

Los números están en coordenadas del overlay, no en píxeles del escritorio, y por eso valía la pena hacer la llamada de antes. La posición es la última de la que informó el dispositivo, así que puedes pedirla cuando quieras y tantas veces como quieras. Pídela en onOverlayUpdate y dibuja con la respuesta.

Hay otra forma de obtener los mismos números. onMouseMoved es un callback, como onOverlayUpdate, y el motor lo llama cada vez que se mueve un puntero, y le pasa la posición nueva. Es la elección correcta cuando quieres reaccionar al movimiento. Para dibujar un punto de mira no quieres eso: quieres saber dónde está la cosa ahora mismo, y mouseGetPosition te lo dice sin que tengas que guardar una copia.

Dibujar un punto de mira

El motor no te lo va a dibujar. Un punto de mira son cuatro líneas y un círculo:

local function drawCrosshair(x, y)
    colorForeground(255, 255, 255, 255)
    overlayCircle(x, y, 10)
    overlayLine(x - 18, y, x - 4, y)
    overlayLine(x + 4, y, x + 18, y)
    overlayLine(x, y - 18, x, y - 4)
    overlayLine(x, y + 4, x, y + 18)
end

Los huecos importan más que las líneas. Dejar los cuatro radios sin llegar al círculo te da un agujero en el centro por el que ver la diana, que es todo el sentido de un punto de mira y lo primero que los principiantes tapan al dibujar.

Una cosa que deberías preguntar antes de dibujarlo:

local drawAim = singeWantsCrosshairs()

Eso devuelve false cuando el jugador arrancó Singe con --nocrosshair. Algunas pistolas de luz ponen un punto propio en la pantalla, y dos puntos de mira a unos pocos píxeles de distancia son peor que ninguno. La respuesta no puede cambiar mientras el juego está en marcha, así que léela una vez al principio y guárdala en una variable.

No tienes que ocultar el puntero del sistema, porque Singe ya lo ha hecho. Captura el ratón al arrancar, lo que lo encierra en la ventana y oculta la flecha del escritorio. Si alguna vez lo quieres de vuelta — para un editor de niveles, por ejemplo — mouseSetCaptured(false) lo suelta, y la tecla asignada a INPUT_GRAB, que es la G en los controles que vienen con Singe, activa y desactiva lo mismo mientras juegas.

El gatillo

Un gatillo es un botón, y los botones llegan a onInputPressed, que viste por primera vez en la lección tres:

function onInputPressed(what, device)
    if what ~= SWITCH_BUTTON3 then
        return
    end

    local x, y = mouseGetPosition(device or 0)
    -- ...
end

SWITCH_BUTTON3 es el botón izquierdo del ratón, y en una pistola es el gatillo. El controls.cfg que viene con Singe asigna el botón izquierdo a SWITCH_BUTTON3, el derecho a SWITCH_BUTTON1 y el central a SWITCH_BUTTON2. Esos números parecen barajados porque lo están: los interruptores son los botones del panel de la recreativa, y qué control físico va cableado a cuál es asunto de la recreativa, no del juego. La Mayús izquierda también está asignada a SWITCH_BUTTON3, así que puedes disparar sin ratón mientras haces pruebas.

El segundo argumento es lo nuevo. Cuando el interruptor viene de un ratón o de una pistola de luz, device es el índice de ese dispositivo — 0 para el primero, 1 para el segundo, y así sucesivamente. Cuando viene de una tecla o de un mando es nil, porque no ha intervenido ningún dispositivo apuntador. Por eso la llamada de arriba dice device or 0: si device es nil, usa 0 en su lugar. Usarás or así constantemente, y se lee exactamente como suena — «device, o nada, y en ese caso cero».

Ese argumento de más es lo que hace posible una recreativa de dos pistolas. La pistola del jugador uno es el dispositivo 0 y la del jugador dos es el dispositivo 1, y el mismo onInputPressed las distingue sin que tengas que adivinar.

¿Ha dado en algo?

Ya sabes responder a esto. Es la lección once:

if collidePointRect(x, y, target.x, target.y, TARGET_SIZE, TARGET_SIZE) then

Un disparo es un punto. Una diana es un rectángulo. collidePointRect pregunta si el punto está dentro del rectángulo, y el borde cuenta como dentro. Disparar no tiene nada de especial. La comprobación de impacto de un juego de pistolas es la misma que usa un juego de plataformas para saber si has caído sobre un bloque, y la familia collide de la referencia tiene el resto de las formas.

Dianas que vienen y van

Lo único que cambia el vídeo es cuándo existe una diana. En la lección once, una roca estaba ahí hasta que le disparabas. Aquí una diana está en pantalla mientras la película muestra la parte de la escena a la que pertenece, y después desaparece tanto si le has disparado como si no.

Eso son dos campos más en el registro, y la lección seis te dio la herramienta:

local targets = {
    { first =  40, last = 110, x =  80, y = 110 },
    { first = 120, last = 190, x = 470, y = 140 },
    { first = 200, last = 270, x = 290, y = 250 },
    { first = 280, last = 360, x = 150, y = 300 },
}

Cuatro registros, cada uno con el fotograma en el que aparece la diana, el fotograma en el que se va y dónde está. Añadir una quinta diana es añadir una línea. Esa es la forma a la que tienes que recurrir cada vez que te veas a punto de escribir las mismas cuatro líneas de código con números distintos.

Si una diana cuenta o no es entonces una pequeña función propia:

local function targetIsUp(target, frame)
    return not target.hit and frame >= target.first and frame <= target.last
end

El dibujo se lo pregunta, y el disparo también, y para eso está en un solo sitio: una diana que puedes ver y una diana a la que puedes acertar nunca pueden estar en desacuerdo.

Todo junto

-- Aprende a programar con Singe -- Lección 17: Pistolas de luz

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local FIRST_FRAME = 20
local LAST_FRAME  = 400
local TARGET_SIZE = 96
local HIT_SCORE   = 100
local FLASH_TIME  = 12

local targets = {
    { first =  40, last = 110, x =  80, y = 110 },
    { first = 120, last = 190, x = 470, y = 140 },
    { first = 200, last = 270, x = 290, y = 250 },
    { first = 280, last = 360, x = 150, y = 300 },
}

local aimX    = overlayGetWidth() / 2
local aimY    = overlayGetHeight() / 2
local score   = 0
local shots   = 0
local hits    = 0
local flash   = 0
local flashX  = 0
local flashY  = 0
local drawAim = singeWantsCrosshairs()


local function drawCrosshair(x, y)
    colorForeground(255, 255, 255, 255)
    overlayCircle(x, y, 10)
    overlayLine(x - 18, y, x - 4, y)
    overlayLine(x + 4, y, x + 18, y)
    overlayLine(x, y - 18, x, y - 4)
    overlayLine(x, y + 4, x, y + 18)
end


local function targetIsUp(target, frame)
    return not target.hit and frame >= target.first and frame <= target.last
end


local function startRound()
    score = 0
    shots = 0
    hits  = 0
    flash = 0
    for _, target in ipairs(targets) do
        target.hit = false
    end
    discSkipToFrame(FIRST_FRAME)
end


function onInputPressed(what, device)
    if what == SWITCH_START1 then
        startRound()
        return
    end

    if what ~= SWITCH_BUTTON3 then
        return
    end

    local x, y = mouseGetPosition(device or 0)
    local frame = discGetFrame()

    shots = shots + 1

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) and collidePointRect(x, y, target.x, target.y, TARGET_SIZE, TARGET_SIZE) then
            target.hit = true
            hits       = hits + 1
            score      = score + HIT_SCORE
            flash      = FLASH_TIME
            flashX     = x
            flashY     = y
            return
        end
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    if frame >= LAST_FRAME then
        startRound()
        frame = FIRST_FRAME
    end

    aimX, aimY = mouseGetPosition(0)

    overlayClear()

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) then
            colorForeground(255, 200, 0, 255)
            overlayBox(target.x, target.y, target.x + TARGET_SIZE - 1, target.y + TARGET_SIZE - 1)
            overlayCircle(target.x + TARGET_SIZE / 2, target.y + TARGET_SIZE / 2, TARGET_SIZE / 3)
        end
    end

    if flash > 0 then
        colorForeground(255, 255, 255, 255)
        overlayCircle(flashX, flashY, 30 - flash * 2)
        flash = flash - 1
    end

    overlayPrint(2, 1, "SCORE " .. score .. "   HITS " .. hits .. "/" .. shots .. "   FRAME " .. frame)

    if drawAim then
        drawCrosshair(aimX, aimY)
    end

    return OVERLAY_UPDATED
end


startRound()

Apunta a una caja amarilla y haz clic. El contador de la esquina sube, se abre un anillo blanco donde has acertado y la caja desaparece. Si fallas, solo sube la cuenta de disparos, que es el marcador más barato que existe y le dice al jugador más sobre cómo lo está haciendo que la puntuación. La ronda vuelve a empezar sola cuando se acaba la película, y 1 la reinicia cuando quieras.

Qué acaba de pasar

local frame = discGetFrame()

if frame >= LAST_FRAME then
    startRound()
    frame = FIRST_FRAME
end

El vídeo es el reloj, como en la lección catorce, y discGetFrame es la forma de leerlo. Todo lo demás del fotograma se decide a partir de ese único número. Cuando la película pasa del final de la última diana, la ronda vuelve a empezar: startRound pone a cero la puntuación, marca todas las dianas como no disparadas y manda el disco de vuelta al principio con discSkipToFrame. La línea de debajo cambia también la copia local de frame, porque se leyó antes del salto y todavía guarda el número viejo. Sin ella, el dibujo de más abajo pasaría un fotograma trabajando con un número que ya no es verdad.

    shots = shots + 1

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) and collidePointRect(...) then

Cuenta el disparo antes de buscar un impacto, para que un fallo también cuente. Luego recorre la lista. El return de dentro del bucle se para en la primera diana acertada, lo que significa que una bala no puede llevarse dos dianas que se solapan — una regla que tienes que decidir en un sentido o en otro, y esta es la línea que la decide.

overlayBox(target.x, target.y, target.x + TARGET_SIZE - 1, target.y + TARGET_SIZE - 1)

overlayBox quiere dos esquinas opuestas, no una esquina y un tamaño, así que la esquina lejana es la cercana más el tamaño. El - 1 está porque las dos esquinas se incluyen: una caja de 80 a 175 mide noventa y seis píxeles de ancho. collidePointRect, en cambio, quiere una esquina y un tamaño, y por eso TARGET_SIZE entra solo allí y sumado a la esquina aquí. Confundir esas dos cosas es un fallo muy común de verdad, y se nota en dianas a las que puedes acertar un poco fuera de donde están dibujadas.

if flash > 0 then
    colorForeground(255, 255, 255, 255)
    overlayCircle(flashX, flashY, 30 - flash * 2)
    flash = flash - 1
end

flash es una cuenta atrás en fotogramas, que se pone a doce cuando un disparo acierta y baja en uno cada vez que se dibuja la pantalla. Como el radio se calcula a partir de la cuenta atrás, el anillo crece a medida que el número encoge. Doce fotogramas son menos de medio segundo. Una respuesta que dura más que eso deja de sentirse como consecuencia del gatillo y empieza a parecer el tiempo que hace.

Dos pistolas

Estás a dos cambios de una recreativa para dos jugadores, y ninguno de ellos está en el bucle del juego.

El primero es mouseSetMode(MOUSE_MANY), que le dice a Singe que lea cada dispositivo por separado en lugar de juntarlos todos en un solo cursor. mouseHowMany() dice cuántos encontró al arrancar, así que lo normal es que un juego pregunte antes de comprometerse:

if mouseHowMany() >= 2 then
    mouseSetMode(MOUSE_MANY)
end

A partir de ahí, mouseGetPosition(1) es la segunda pistola, y el argumento device de onInputPressed dice qué pistola ha disparado. Ten dos puntos de mira, dos puntuaciones y una sola lista de dianas, y tendrás un juego cooperativo.

El segundo cambio no está en tu script en absoluto. El controls.cfg que viene con Singe solo asigna los botones del primer ratón, así que el gatillo de la segunda pistola no llega a ninguna parte. Una recreativa con dos pistolas necesita su propia línea en ese archivo que nombre las dos:

INPUT_ACTION_3 = { SCANCODE.LSHIFT, GAMEPAD_0.BUTTON_X, MOUSE_0.BUTTON_LEFT, MOUSE_1.BUTTON_LEFT }

Dilo en tus instrucciones. Un jugador cuya segunda pistola no hace nada le echará la culpa a tu juego, y tendrá media razón.

La otra forma de comprobar un impacto

Hay una segunda forma de responder a «¿ha dado ese disparo en algo?», y vale la pena conocerla aunque hoy no la vayas a usar. vldpGetPixel(x, y) lee el color de un píxel del fotograma de vídeo que está en pantalla. Los juegos lo usan desde la primerísima versión de Singe: pinta cada diana de las imágenes de un color que no aparezca en ningún otro sitio, y cuando se apriete el gatillo pregunta qué color hay debajo del punto de mira.

Te da formas de impacto que siguen la acción con exactitud, gratis, sin rectángulos que preparar. Te cuesta unas imágenes que tienes que preparar así, y una comprobación de impacto que no puedes ver ni depurar. La entrada de la referencia de vldpGetPixel tiene los detalles. Los rectángulos son lo correcto por defecto; guárdate esto en el bolsillo.

Lo que solo le importa a una recreativa

Todo lo anterior funciona en tu mesa. Varias cosas no existen en absoluto en tu mesa, y este es un buen momento para nombrarlas y que no te pillen por sorpresa más adelante.

Calibración. A una pistola de luz de verdad hay que decirle dónde está la pantalla, porque es una cámara que mira un monitor desde donde esté el jugador. Las herramientas de servicio de Singe tienen una pantalla Light Gun que pone dianas en el centro y en cada esquina y marca adónde apuntó de verdad la pistola, para que veas hacia qué lado se desvía. Tu juego no hace la calibración y no debería intentarlo.

El borde Sinden. Una familia de pistolas muy popular encuentra la pantalla buscando un marco brillante dibujado alrededor de la imagen. --sindengun dibuja ese marco, y el motor traslada las posiciones a la imagen más pequeña que queda dentro, así que tu juego sigue recibiendo coordenadas que significan lo mismo que antes.

Pantallas que no tienen la forma de la película. ratioGetX() y ratioGetY() te dan los números que un jugador ha puesto en la línea de comandos para una pantalla cuyas proporciones no coinciden con las imágenes. Singe no los aplica; un juego que los quiera hace la cuenta por su cuenta.

Pistolas que se van. SWITCH_MOUSE_DISCONNECT llega a onInputPressed cuando se desenchufa una pistola. No lo produce ningún botón; lo lanza el motor. Un juego que esté pendiente de él puede poner «JUGADOR 2: PISTOLA DESCONECTADA» en pantalla en lugar de parecer que se ha muerto.

Ningún ratón. Una recreativa con un joystick y sin dispositivo apuntador puede mover el cursor con el stick, cosa que activa joyMouseEnable.

Nada de eso cambia el juego que has escrito. Todo ello es la lección treinta y uno.

Pruébalo

  1. Mueve una diana. Cambia la x de la tercera diana a 680 y ejecútalo. La mayor parte de ella cuelga ahora por fuera del borde derecho, porque el overlay mide 720 de ancho y la diana 96. Todavía puedes disparar a la tira que queda. Decide qué quieres que pase en los bordes.

  2. Haz las dianas más fáciles. Cambia TARGET_SIZE a 140. Fíjate en que cambian tanto el dibujo como la comprobación de impacto, y en que solo has tocado un número. Para eso sirve una constante con nombre.

  3. Lleva la cuenta de la puntería. Añade una línea que imprima hits como porcentaje de shots. Protégete contra la división por cero antes del primer disparo, y averigua qué imprime Lua si no lo haces.

  4. Haz que una diana te castigue. Añade un campo penalty = true a un registro y resta puntos cuando le aciertes. Fíjate en que añades un campo a un registro, no a los cuatro, y en que los que no lo tienen tienen nil ahí.

  5. Quita el return del bucle de onInputPressed, y luego solapa dos dianas dándoles los mismos fotogramas y casi la misma posición. Ahora un disparo se lleva las dos. Decide qué comportamiento quiere tu juego.

Rómpelo a propósito

Cambia la comprobación del disparo para que use SWITCH_BUTTON1 en lugar de SWITCH_BUTTON3 y ejecútalo. No se rompe nada. No aparece ningún error. El botón izquierdo deja de hacer nada, y ahora dispara el derecho.

Este es el peor tipo de fallo y el más común en el código de entrada: el programa no está mal, solo está conectado a lo que no es. No hay ningún mensaje de error que leer, porque has hecho una pregunta sensata sobre un interruptor que existe y te ha respondido con sinceridad.

Hay dos cosas que lo encuentran. La primera es debugPrint, de la lección ocho:

function onInputPressed(what, device)
    debugPrint("switch " .. what .. " from device " .. tostring(device))

Ahora cada pulsación imprime una línea, y puedes ver lo que manda de verdad el gatillo. Fíjate en tostring(device): device es nil cuando se pulsa una tecla, y pegar nil a una cadena con .. es un error. tostring lo convierte en la palabra nil y la línea se imprime.

La segunda es la propia herramienta Input Test del motor, en las herramientas de servicio, que muestra todos los dispositivos que ve y el último interruptor que habría recibido el juego. Cuando un botón no hace nada, esa pantalla te dice qué mitad del problema tienes: o el interruptor está llegando y tu juego no le hace caso, o no está llegando en absoluto.

Lo que has aprendido

  • Una pistola de luz se presenta como un ratón, así que un juego escrito para el ratón funciona con una pistola.

  • mouseGetPosition(device) devuelve dos valores, la posición del puntero en coordenadas del overlay.

  • Una función de Lua puede devolver más de un valor, y los recoges poniendo otros tantos nombres.

  • singeWantsCrosshairs() dice si tienes que dibujar tu propio punto de mira. Léelo una vez.

  • Singe captura y oculta el puntero del sistema al arrancar; no tienes que hacerlo tú.

  • onInputPressed recibe un segundo argumento que dice qué ratón o qué pistola ha disparado, y nil cuando ha sido una tecla o un mando.

  • Una comprobación de impacto contra un rectángulo es collidePointRect, la misma colisión que aprendiste en la lección once.

  • La ventana de fotogramas de una diana no es más que dos campos más en su registro.

  • a or b te da b cuando a es nil.

  • La calibración, el borde Sinden y el cableado de dos pistolas viven fuera de tu script.

La próxima vez

Tu galería pide una sola cosa: dale a eso, ahí. La otra convención de las recreativas sobre la que se construyen los juegos de vídeo pide algo más difícil — pulsa esto, ya, y tienes medio segundo. La lección dieciocho construye un quick-time event, con una indicación, una ventana medida en fotogramas y tres finales distintos según hayas acertado, fallado o sido demasiado lento.

Lección 18: Quick-time events

La lección terminada

Aparece una indicación. Tienes medio segundo. Pulsa lo correcto y la historia sigue; pulsa lo que no es, o no pulses nada, y se va a otra parte.

Esa es toda la idea, y un número sorprendente de juegos de vídeo no están hechos de casi nada más. Ya tienes todas las piezas: la lección catorce te dio los fotogramas, la lección seis una lista de registros, la lección tres la entrada, y la lección dieciséis las ramificaciones. Esta lección las junta y añade una cosa que es nueva de verdad — una ventana de tiempo, y lo que pasa cuando se cierra.

El reloj es la película

Aquí todo se mide en fotogramas, no en segundos, y vale la pena detenerse en ello, porque es la única decisión que hace que esto funcione.

La lección catorce decía que un fotograma es la dirección de un momento de la película. La indicación tiene que aparecer cuando el actor empieza a lanzar el golpe, y la ventana tiene que cerrarse cuando llega el puño. Eso no son tiempos, son lugares de las imágenes, y los encontraste avanzando por ellas paso a paso. Si escribes la ventana en segundos, tienes que poner en marcha un cronómetro cuando aparece la indicación, y entonces los dos relojes — el tuyo y el de la película — pueden desfasarse. Si el vídeo da tirones en un ordenador lento, tu cronómetro sigue corriendo y el jugador sale castigado por culpa de su hardware.

Los fotogramas no pueden desfasarse, porque solo hay un reloj. discGetFrame() es la hora, siempre. Una ventana son dos números de fotograma, y «cuánto queda» es una resta.

Ejecútalo con el mismo vídeo que antes:

Singe -R -v Singe/menuBackground.mkv moves

Sigue siendo la cuadrícula morada y la puesta de sol. Imagínate una pelea.

Un movimiento es un registro

Esta es la tabla de la que cuelga toda la lección:

local moves = {
    { first =  60, last = 105, switch = SWITCH_LEFT,  name = "LEFT"  },
    { first = 140, last = 185, switch = SWITCH_UP,    name = "UP"    },
    { first = 220, last = 265, switch = SWITCH_RIGHT, name = "RIGHT" },
    { first = 300, last = 345, switch = SWITCH_DOWN,  name = "DOWN"  },
}

Cuatro movimientos. Cada uno dice cuándo se abre la ventana, cuándo se cierra, qué interruptor la responde y qué poner en pantalla. Cuarenta y cinco fotogramas son más o menos un segundo y medio a la velocidad de este vídeo, lo cual es generoso; los juegos de verdad suelen darte menos de la mitad.

Todo lo que hace que un movimiento sea un movimiento está en esa tabla. No hay ningún código más abajo que sepa que hay cuatro movimientos, ni que el segundo es hacia arriba, ni que la primera ventana se abre en el fotograma sesenta. Añadir un quinto movimiento es añadir una línea. Cambiar el ritmo de todos los movimientos es editar números. Nadie tiene que leer una función para cambiar la pelea.

Eso no es un truco para esta lección. Es la diferencia entre un juego que puedes ajustar y uno que no, y no cuesta nada hacerlo desde el principio. Cuando te veas a punto de escribir if frame == 60 then por cuarta vez, para y haz una tabla.

Qué pasa y cuándo

A un movimiento le pueden pasar tres cosas, y son tres resultados distintos, no dos:

  • El jugador pulsa el interruptor correcto dentro de la ventana. Se puntúa y se sigue.

  • El jugador pulsa un interruptor equivocado dentro de la ventana. Lo ha intentado y ha fallado.

  • La ventana se cierra sin ninguna respuesta. Se ha quedado helado.

El código perezoso trata igual los dos últimos. Los juegos casi nunca lo hacen, porque al jugar se sienten completamente distintos: equivocarse es un error, y quedarse helado es otro error distinto, y normalmente la película va a un sitio distinto con cada uno. Aquí la respuesta equivocada manda el disco al fotograma 362 y la falta de respuesta lo manda al fotograma 388, lo que en estas imágenes significa dos cantidades ligeramente distintas de puesta de sol. En imágenes de verdad serían dos planos distintos de ti perdiendo.

Así que cada registro gana un quinto campo mientras dura la partida — se llama answer y es nil hasta que al movimiento le pasa algo, y luego una de tres cadenas:

move.answer = "right"
move.answer = "wrong"
move.answer = "late"

nil es el valor que te da Lua para un campo al que nadie ha dado valor. Lo conociste en la lección tres. Aquí se gana el sueldo: «todavía sin respuesta» es de verdad un estado distinto de cualquiera de las tres respuestas, y nil lo dice sin que tengas que inventarte una palabra para ello.

Encontrar el movimiento que se está pidiendo

Todo lo demás necesita saber una cosa: ¿qué movimiento está abierto ahora mismo, si es que hay alguno?

local function moveAt(frame)
    for _, move in ipairs(moves) do
        if move.answer == nil and frame >= move.first and frame <= move.last then
            return move
        end
    end
    return nil
end

Recorre la lista y responde con el primer movimiento cuya ventana cubra este fotograma y que no se haya respondido. Si no coincide ninguno, responde nil.

Vale la pena fijarse en que se devuelve nil a propósito. Una función que a veces no tiene respuesta debería decirlo, y «no hay ningún movimiento abierto» es una respuesta perfectamente buena. Quien la llama escribe entonces if move ~= nil then, y el código que dibuja la indicación nunca se ejecuta cuando no hay nada que indicar.

La comprobación move.answer == nil es lo que impide que un movimiento se pida dos veces. En cuanto el jugador acierta, la indicación desaparece aunque la ventana siga abierta — que es justo lo que debe hacer, porque ya ha respondido.

Leer la respuesta

function onInputPressed(what)
    if not isDirection(what) then
        return
    end

    local move = moveAt(discGetFrame())
    if move == nil then
        return
    end

    if what == move.switch then
        move.answer = "right"
        score       = score + RIGHT_SCORE
    else
        move.answer = "wrong"
        endRun("WRONG WAY", WRONG_FRAME)
    end
end

Léelo de arriba abajo. Si el interruptor no es una de las cuatro direcciones, no es asunto nuestro: vete. Si no hay ningún movimiento abierto, pulsar una dirección no significa nada: vete. Si no, hay exactamente un movimiento con el que comparar, y una comparación que hacer.

Esas dos líneas return del principio son guardas: echan fuera los casos que no te interesan para que el código de debajo solo se ejecute en la única situación para la que se escribió. Escribirlo al revés, con el trabajo de verdad metido tres niveles más adentro, dentro de tres bloques if, dice lo mismo y es mucho más difícil de leer.

isDirection es una función diminuta que no hace nada más que mantener corta esa primera línea:

local function isDirection(what)
    return what == SWITCH_UP or what == SWITCH_DOWN or what == SWITCH_LEFT or what == SWITCH_RIGHT
end

Fíjate en que devuelve la propia comparación en lugar de decir if …​ then return true else return false end. Una comparación ya es true o false. Comprobar si algo es verdad para poder decir que es verdad es una costumbre que conviene perder pronto.

La ventana se cierra

Nadie pulsa nada, y los fotogramas siguen pasando. Algo tiene que darse cuenta. Ese algo es onOverlayUpdate, porque se ejecuta en cada fotograma, haga algo el jugador o no:

if not runOver then
    for _, move in ipairs(moves) do
        if move.answer == nil and frame > move.last then
            move.answer = "late"
            endRun("TOO SLOW", LATE_FRAME)
            break
        end
    end
end

Un movimiento sin responder cuyo último fotograma ya ha pasado se ha perdido. break sale del bucle inmediatamente, porque una vez terminada la partida no tiene sentido mirar el resto.

endRun es la ramificación, y es la misma ramificación que escribiste en la lección dieciséis:

local function endRun(reason, frame)
    verdict = reason
    runOver = true
    discSkipToFrame(frame)
end

Tres líneas. Recuerda qué decir, recuerda que la partida ha terminado y manda la película a otra parte. Un quick-time event perdido no es un mecanismo especial. Es una elección que el jugador ha hecho al no hacer ninguna, y la película se ramifica con ella exactamente igual que con una puerta que hubiera escogido.

Un indicador que se vacía

El jugador no ve los números de fotograma. Necesita ver que se acaba el tiempo, y necesita verlo sin apartar la vista de la acción, lo que significa una forma que cambia en lugar de un número que cuenta.

Dos números te lo dan todo:

local left = move.last - frame
local span = move.last - move.first

span es lo que dura la ventana. left es lo que queda de ella. La barra ocupa left partido por span del ancho completo:

fillBar(GAUGE_X, GAUGE_Y, GAUGE_W * left // span, GAUGE_H)

// es una división que tira los decimales, que es lo que quieres aquí, porque una barra de ciento treinta y tres píxeles y un tercio de ancho no existe. Multiplica antes de dividir — GAUGE_W * left // span y no GAUGE_W * (left // span) — o los decimales se tiran mientras todavía son la única información que tienes, y la barra salta de llena a vacía sin nada en medio.

El overlay no tiene rectángulos rellenos. overlayBox dibuja un contorno, que es lo que quieres para el marco del indicador, y el relleno lo pones tú:

local function fillBar(x, y, width, height)
    if width < 1 then
        return
    end
    for row = 0, height - 1 do
        overlayLine(x, y + row, x + width - 1, y + row)
    end
end

Dieciocho líneas horizontales apiladas una encima de otra. La guarda del principio importa: en el último fotograma de la ventana left es cero, el ancho es cero, y sin ella x + width - 1 queda un píxel a la izquierda de x y dibujas una línea corta hacia atrás en lugar de nada.

El último toque es un cambio de color cuando la cosa se pone desesperada:

if left * 3 < span then
    colorForeground(255, 60, 60, 255)
else
    colorForeground(255, 200, 0, 255)
end

La barra se pone roja en su último tercio. Escrito así — multiplicando el tiempo que queda en lugar de dividir lo que dura la ventana — todo sigue siendo números enteros y funciona con una ventana de cualquier longitud.

Todo junto

-- Aprende a programar con Singe -- Lección 18: Quick-time events

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local FIRST_FRAME = 20
local WRONG_FRAME = 362
local LATE_FRAME  = 388
local LAST_FRAME  = 415

local PROMPT_COL  = 54
local PROMPT_ROW  = 22
local GAUGE_X     = 210
local GAUGE_Y     = 330
local GAUGE_W     = 300
local GAUGE_H     = 18

local RIGHT_SCORE = 100

local moves = {
    { first =  60, last = 105, switch = SWITCH_LEFT,  name = "LEFT"  },
    { first = 140, last = 185, switch = SWITCH_UP,    name = "UP"    },
    { first = 220, last = 265, switch = SWITCH_RIGHT, name = "RIGHT" },
    { first = 300, last = 345, switch = SWITCH_DOWN,  name = "DOWN"  },
}

local score   = 0
local runOver = false
local verdict = ""


local function fillBar(x, y, width, height)
    if width < 1 then
        return
    end
    for row = 0, height - 1 do
        overlayLine(x, y + row, x + width - 1, y + row)
    end
end


local function isDirection(what)
    return what == SWITCH_UP or what == SWITCH_DOWN or what == SWITCH_LEFT or what == SWITCH_RIGHT
end


local function moveAt(frame)
    for _, move in ipairs(moves) do
        if move.answer == nil and frame >= move.first and frame <= move.last then
            return move
        end
    end
    return nil
end


local function startRun()
    score   = 0
    runOver = false
    verdict = ""
    for _, move in ipairs(moves) do
        move.answer = nil
    end
    discSkipToFrame(FIRST_FRAME)
end


local function endRun(reason, frame)
    verdict = reason
    runOver = true
    discSkipToFrame(frame)
end


function onInputPressed(what)
    if runOver then
        if what == SWITCH_START1 then
            startRun()
        end
        return
    end

    if not isDirection(what) then
        return
    end

    local move = moveAt(discGetFrame())
    if move == nil then
        return
    end

    if what == move.switch then
        move.answer = "right"
        score       = score + RIGHT_SCORE
    else
        move.answer = "wrong"
        endRun("WRONG WAY", WRONG_FRAME)
    end
end


function onOverlayUpdate()
    local frame = discGetFrame()

    if not runOver then
        for _, move in ipairs(moves) do
            if move.answer == nil and frame > move.last then
                move.answer = "late"
                endRun("TOO SLOW", LATE_FRAME)
                break
            end
        end
    end

    if frame >= LAST_FRAME and discGetState() == DISC_PLAYING then
        if not runOver then
            verdict = "CLEAR"
            runOver = true
        end
        discSearch(LAST_FRAME)
    end

    overlayClear()

    local move = nil
    if not runOver then
        move = moveAt(frame)
    end

    if move ~= nil then
        local left = move.last - frame
        local span = move.last - move.first

        overlayPrint(PROMPT_COL, PROMPT_ROW, "PRESS " .. move.name)

        colorForeground(255, 255, 255, 255)
        overlayBox(GAUGE_X - 2, GAUGE_Y - 2, GAUGE_X + GAUGE_W + 1, GAUGE_Y + GAUGE_H + 1)

        if left * 3 < span then
            colorForeground(255, 60, 60, 255)
        else
            colorForeground(255, 200, 0, 255)
        end
        fillBar(GAUGE_X, GAUGE_Y, GAUGE_W * left // span, GAUGE_H)
    end

    overlayPrint(2, 1, "SCORE " .. score .. "   FRAME " .. frame)

    if runOver then
        overlayPrint(2, 3, verdict)
        overlayPrint(2, 4, "PRESS 1 TO RUN IT AGAIN")
    end

    return OVERLAY_UPDATED
end


startRun()

Las teclas de flecha responden a las indicaciones. Acierta las cuatro y la película llega hasta el final y se queda ahí con CLEAR. Falla una, o quédate de brazos cruzados, y corta a otro fotograma con otra palabra en pantalla. 1 la vuelve a poner en marcha.

Qué acaba de pasar

Casi todo ya lo has leído. Hay cuatro trozos que merecen una segunda mirada.

if frame >= LAST_FRAME and discGetState() == DISC_PLAYING then

Hay que atrapar el final de la película, o se sale del final y no queda nada que ver. discSearch va a un fotograma y se pausa ahí, que es exactamente lo que quiere un plano final. La mitad de discGetState() impide que eso vuelva a pasar en cada uno de los fotogramas siguientes: una vez en pausa, el disco ya no está en DISC_PLAYING, así que la condición es falsa y el salto no se repite sesenta veces por segundo. discGetState y las constantes DISC_* están en la referencia, en discGetState.

local move = nil
if not runOver then
    move = moveAt(frame)
end

onOverlayUpdate vuelve a preguntar cuál es el movimiento abierto, en lugar de que se lo diga onInputPressed. Es a propósito. Hay exactamente una función que sabe qué movimiento está abierto, y todo el mundo se lo pregunta a ella. Si la indicación saliera de una variable que el código de entrada mantuviera al día, habría dos trozos de código recordando el mismo dato, y tarde o temprano uno de ellos se equivocaría. Cuando tengas que elegir entre preguntar y recordar, pregunta.

overlayPrint(PROMPT_COL, PROMPT_ROW, "PRESS " .. move.name)

overlayPrint cuenta en celdas de carácter, como desde la lección uno, así que la indicación se coloca a ojo: la columna cincuenta y cuatro está lo bastante cerca del centro para palabras de esta longitud. Está lo bastante cerca, no bien, y «PRESS RIGHT» termina tres caracteres más a la derecha que «PRESS UP». La lección diecinueve carga una fuente de verdad, y con ella llega la posibilidad de medir una cadena en píxeles y centrarla como es debido.

function onInputPressed(what)
    if runOver then
        if what == SWITCH_START1 then
            startRun()
        end
        return
    end

Un callback, dos trabajos completamente distintos, y runOver elige cuál. Mientras dura la partida, las direcciones son movimientos; una vez terminada, la única tecla que significa algo es la de empezar. Una variable que decide qué reglas se aplican es un estado, que es como lo llamó la lección doce, y un juego es sobre todo un puñado de ellos.

Pruébalo

  1. Hazlo más difícil. Cambia el last del primer movimiento de 105 a 75. Quince fotogramas son medio segundo. Juégalo y averigua si puedes.

  2. Añade un movimiento. Pon una quinta línea en la tabla con una ventana entre los fotogramas 370 y 400, y sube LAST_FRAME a 418. No deberías tener que tocar ninguna otra línea. Si tienes que hacerlo, algo del código sabe demasiado de la tabla.

  3. Puntúa la rapidez. Da más puntos por responder pronto. En onInputPressed, donde se puntúa la respuesta correcta, calcula left y span a partir de move y discGetFrame() igual que hace el indicador, y suma RIGHT_SCORE * left // span en lugar de RIGHT_SCORE. Decide si eso hace el juego mejor o solo más ajetreado.

  4. Dale a una respuesta equivocada su propia consecuencia. En lugar de terminar la partida, haz que pulsar mal cueste cincuenta puntos y deje la ventana abierta para volver a intentarlo. Tendrás que dejar de poner move.answer, y te encontrarás con la razón por la que se ponía.

  5. Dos indicaciones a la vez. Solapa las ventanas de dos movimientos y mira qué pasa. moveAt devuelve la primera coincidencia, así que solo se pide uno. Decide qué querrías, y qué haría falta.

Rómpelo a propósito

Borra el break del bucle que encuentra los movimientos perdidos, y pierde el primero a propósito. La partida termina, el disco salta y todo parece correcto.

Ahora pon debugPrint(move.name .. " missed") junto a move.answer = "late" y vuelve a hacerlo. La consola muestra una línea, como era de esperar.

Luego quita también el if not runOver then que rodea el bucle, y vuelve a perder el primer movimiento:

LEFT missed
UP missed
RIGHT missed
DOWN missed

La primera línea llega cuando se cierra la ventana, como antes. Las otras tres llegan juntas en el fotograma siguiente, en el instante en que el disco aterriza en el 388: todas las ventanas que quedaban están ahora en el pasado, así que todos los movimientos sin responder se pierden a la vez, y cada uno llama a endRun y vuelve a saltar. El juego sigue funcionando más o menos, y eso es lo que lo hace peligroso. Tres saltos de más en un solo fotograma, tres veces sobrescrito el veredicto, y nada en pantalla lo dice.

Aquí tampoco hay mensaje de error. La lección es que ese break y esa guarda no son por limpieza. Son las dos líneas que dicen «esto ya está decidido», y el código que sigue decidiendo algo que ya ha decidido es una de las fuentes de fallos más fiables que vas a escribir nunca.

Lo que has aprendido

  • Un quick-time event es una indicación, una ventana y una consecuencia.

  • Mide la ventana en fotogramas, porque la película es el reloj y solo debe haber un reloj.

  • Guarda los movimientos en una tabla de registros, para que añadir un movimiento sea añadir una línea.

  • Acertar, fallar y no responder son tres resultados, y normalmente llevan a tres sitios distintos.

  • nil en un campo de un registro es un estado de verdad: nadie ha respondido todavía.

  • Una sola función responde a «qué movimiento está abierto», y todo el mundo se lo pregunta en lugar de guardar una copia.

  • Las cláusulas de guarda — un return temprano para los casos que no te interesan — evitan que el trabajo de verdad quede anidado.

  • // divide y tira los decimales; multiplica antes de dividir.

  • overlayBox dibuja un contorno, así que una barra rellena es una pila de llamadas a overlayLine.

  • Un movimiento perdido es una ramificación, y discSkipToFrame la toma, exactamente como en la lección dieciséis.

La próxima vez

La tercera parte está terminada. Puedes reproducir película, esperarla, ramificarla, apuntarle y medir el tiempo del jugador contra ella. Lo que has estado escribiendo encima de todo eso es la fuente de consola del motor, que tiene seis píxeles de ancho y está pensada para diagnósticos. La lección diecinueve carga un tipo de letra de verdad, lo mide y hace que las palabras de la pantalla parezcan parte del juego.

Lección 19: Texto con buen aspecto

La lección terminada

Cada palabra que has puesto en pantalla desde la lección uno ha salido de overlayPrint, y overlayPrint tiene exactamente una fuente: un bloque de píxeles de ancho fijo integrado en el motor, siempre del mismo tamaño, del color que le toque. Es perfecta para un contador de fotogramas. No sirve para un título, una puntuación, un menú ni nada que el jugador tenga que mirar en lugar de leer de pasada.

Esta lección carga una fuente de verdad desde el disco, imprime con ella, le da color, la mide para que puedas centrar las cosas y te enseña lo que cuesta de verdad imprimir texto. Al final tendrás una pantalla de título que parece hecha a propósito y no por casualidad.

Pon el overlay a un tamaño con el que puedas pensar

Empieza un archivo nuevo llamado text.singe con dos líneas:

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

La primera línea la has escrito muchas veces; carga el framework, que define DIR, los nombres SWITCH_* y los nombres FONT_QUALITY_* que estás a punto de usar.

La segunda importa más de lo que parece. El overlay — la superficie sobre la que cae todo lo que dibujas — empieza con la mitad del tamaño del mundo. Un juego sin vídeo tiene un lienzo de 720 por 480, así que el overlay empieza en 360 por 240, y una fuente de 36 puntos en un overlay de 360 píxeles de ancho es enorme. overlaySetResolution cambia el overlay por uno del tamaño que pidas, y a partir de ahí cada coordenada que das, y todo lo que te dicen overlayGetWidth y overlayGetHeight, está en ese espacio.

discGetWidth() y discGetHeight() responden con el tamaño del vídeo cuando lo hay y con el tamaño del lienzo cuando no, así que esa única línea te da un overlay que encaja con el mundo sea cual sea el tipo de juego. Llámala una vez, al principio, antes de dibujar nada.

Carga una fuente

Debajo de eso, añade:

fontQuality(FONT_QUALITY_BLENDED)

local titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)

fontLoad abre un archivo de fuente TrueType y te devuelve un número — un handle — que usas cada vez que quieres esa fuente. El segundo argumento es el tamaño en puntos, y queda fijo mientras viva el handle. No hay forma de cambiar después el tamaño de una fuente cargada. Si quieres el mismo tipo de letra en tres tamaños, llamas a fontLoad tres veces y guardas tres handles.

Singe/FreeSansBold.ttf es la fuente que el motor desempaquetó en la carpeta Singe de tu carpeta de trabajo la primera vez que ejecutaste algo. Todas las copias de Singe la tienen, así que puedes contar con ella. Cualquier otro archivo .ttf funciona igual; ponlo junto a tu script y cárgalo como DIR .. "myfont.ttf".

Ahora imprime con ella:

function onOverlayUpdate()
    overlayClear()
    fontPrint(24, 60, "ASTEROID PATROL")
    return OVERLAY_UPDATED
end

Ejecútalo. Letras blancas grandes cerca de la esquina superior izquierda.

Fíjate en lo que no has hecho: no le has dicho a fontPrint qué fuente usar. fontLoad deja seleccionada la fuente que acaba de cargar, y fontPrint dibuja siempre con la que esté seleccionada. Con más de una fuente cargada, eliges entre ellas con fontSelect, que es lo que harás dentro de un momento.

Fíjate también en que 24 y 60 son píxeles, no celdas de carácter. Esta es la diferencia entre fontPrint y overlayPrint que hace tropezar a la gente: overlayPrint(2, 2, …​) significa dos letras hacia dentro y dos líneas hacia abajo, mientras que fontPrint(2, 2, …​) significa dos píxeles hacia dentro y dos píxeles hacia abajo, que es estar metido en la esquina. La y que das es la parte de arriba del texto, no la línea base sobre la que se apoya.

Color

fontPrint recibe tres argumentos y ninguno de ellos es un color. El color sale de otro sitio:

    colorForeground(255, 211, 90)
    fontPrint(24, 60, "ASTEROID PATROL")

colorForeground pone el rojo, el verde y el azul de 0 a 255, y un cuarto número opcional para la opacidad. No es un argumento de nada; es un ajuste que el motor recuerda. Todo lo que se dibuja después sale de ese color hasta que lo vuelvas a cambiar, exactamente igual que ya funcionan overlayBox y overlayLine. Así que el patrón es siempre el mismo: pon el color y luego dibuja.

Esto es lo primero que la gente hace mal con las fuentes, y lo segundo llega dentro de unas páginas.

Calidad

fontQuality decide cómo se rasterizan las letras — cómo se convierten en píxeles las curvas de una letra — y hay tres opciones. Prueba cada una poniéndola encima de la línea de fontLoad y mirando el resultado de cerca.

FONT_QUALITY_SOLID es la más rápida. Cada píxel o es de la letra o no lo es, así que las diagonales y las curvas salen con escalones visibles. A 48 puntos queda barato. A 12 puntos en un overlay pequeño puede verse más nítida que las otras, y a veces es justo lo que quieres.

FONT_QUALITY_SHADED suaviza los bordes, pero lo hace mezclándolos con el color de fondo actual, y dibuja ese fondo como un rectángulo sólido detrás de toda la cadena. Te sale una etiqueta con una caja alrededor, la quisieras o no. Es la respuesta correcta para una lectura de depuración sobre una imagen recargada, y la equivocada para casi todo lo demás.

FONT_QUALITY_BLENDED suaviza los bordes y los deja transparentes, así que las letras se asientan sobre lo que haya detrás. Es la que más cuesta y es la que quieres casi siempre. Úsala a menos que tengas un motivo para no hacerlo.

El ajuste es global, no de cada fuente, y se aplica desde el momento en que lo llamas en adelante. Los sprites que ya has creado conservan la calidad con la que se crearon. La entrada de la referencia de fontQuality enumera los tres nombres y sus valores.

Medir, para poder centrar las cosas

Tarde o temprano — normalmente a los diez minutos — querrás el título en el centro de la pantalla. Sabes que la pantalla mide overlayGetWidth() de ancho. No sabes cuánto mide de ancho el texto, y no hay ninguna llamada fontMeasure a la que preguntar.

Lo que hay en su lugar es fontToSprite. Dibuja una cadena con la fuente seleccionada, la calidad actual y el color actual, y en lugar de ponerla en pantalla te devuelve un sprite: el mismo tipo de handle que te da spriteLoad, lo que significa que todas las llamadas sprite* que aprendiste en la lección nueve funcionan con él. Incluidas las dos que lo miden.

fontSelect(titleFont)
colorForeground(255, 211, 90)
local titleImage = fontToSprite("ASTEROID PATROL")

Y luego, en onOverlayUpdate:

    local x = (overlayGetWidth() - spriteGetWidth(titleImage)) / 2
    spriteDraw(titleImage, x, 60)

Eso es centrar, y ese es todo el truco. Toma el ancho del espacio, réstale el ancho de la cosa, y la mitad de lo que queda es el hueco de cada lado.

Alinear a la derecha es la misma idea con menos cuentas. Para poner texto contra el margen derecho:

    spriteDraw(scoreImage, overlayGetWidth() - MARGIN - spriteGetWidth(scoreImage), y)

spriteGetHeight mide la otra dirección, para apilar líneas o centrar en vertical.

Hay una trampa en ese primer bloque de código, y es lo segundo que todo el mundo hace mal. El color se queda grabado cuando se crea el sprite, no cuando se dibuja. Un colorForeground encima de fontToSprite cambia el texto. Ponerlo en cambio encima de spriteDraw no hace nada de nada, porque colorForeground es un ajuste para dibujar texto y líneas, y un sprite se dibuja con sus propios píxeles. Si tu título, coloreado con tanto cuidado, sale blanco, es por esto.

Un sprite se puede volver a colorear después de crearlo, pero con una llamada de sprite, no con colorForeground. spriteSetTint(image, red, green, blue) multiplica cada píxel del sprite por ese color cada vez que se dibuja, así que un texto dibujado en blanco se puede pintar amarillo hoy y rojo mañana sin volver a crearlo. El blanco es el color con el que hay que dibujarlo cuando piensas teñirlo: cualquier cosa multiplicada por blanco se queda como estaba, así que el tinte es exactamente el color que pides.

Lo que cuesta imprimir

La primera vez que fontPrint ve una cadena, trabaja de verdad: rasteriza cada letra a partir de los contornos de la fuente y construye una imagen de toda la cadena. Luego se guarda esa imagen. La siguiente vez que imprimes la misma cadena, con la misma fuente, calidad y colores, se salta todo eso y copia la imagen que ya tiene, que cuesta más o menos lo mismo que dibujar un sprite. Una cadena que dejas de imprimir se suelta un segundo después, así que no se acumula nada.

Eso significa que la forma obvia de escribir una pantalla de título es también la rápida. Imprimir "ASTEROID PATROL" sesenta veces por segundo la dibuja una vez. Una puntuación que cambia dos veces por segundo se dibuja dos veces por segundo, ella sola, sin que tengas que llevar ninguna cuenta.

El único caso que cuesta es el texto que es distinto en cada fotograma — un temporizador en milisegundos, un contador de fotogramas — porque cada fotograma es una cadena que fontPrint no ha visto nunca. En un ordenador de escritorio da igual. En una Raspberry Pi o en una consola portátil, una pantalla llena de eso se notará. El remedio es cambiar el texto menos a menudo: un temporizador en segundos enteros es una cadena nueva una vez por segundo, no sesenta.

Entonces, ¿por qué ha usado esta lección fontToSprite? Porque un sprite puede hacer cosas que el texto impreso no puede:

  • Se puede medir, que es la única forma de centrar texto o alinearlo contra el lado derecho.

  • Se puede escalar y girar con las llamadas sprite* de la lección nueve.

  • Puede sobrevivir a su fuente, lo que importará dentro de un momento.

Usa fontPrint para el texto, y fontToSprite cuando necesites una de esas cosas.

La puntuación de esta lección necesita una de ellas: va contra el margen derecho, así que hay que medirla, así que tiene que ser un sprite. Y un sprite de una puntuación solo es correcto hasta que la puntuación cambia. Cuando cambie, crea un sprite nuevo y descarga el viejo — si se te olvida, pierdes un sprite en cada cambio:

local function renderScore()
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontSelect(scoreFont)
    colorForeground(255, 255, 255)
    scoreImage = fontToSprite(string.format("%06d", score))
    scoreShown = score
end

scoreShown recuerda qué puntuación dice ese sprite, para que el código de dibujo pueda saber si sigue siendo correcto:

    if score ~= scoreShown then
        renderScore()
    end

string.format("%06d", score) es Lua normal, no Singe. Convierte un número en una cadena, y %06d significa «como número entero, con al menos seis cifras, rellenando con ceros», que es por lo que las puntuaciones de las recreativas llevan ceros delante. Cámbialo por %d y los ceros desaparecen.

Recoger las fuentes

fontUnload cierra una fuente y deja su handle inválido. Los sprites que creaste con fontToSprite no se ven afectados — una vez dibujado, un sprite ya no tiene nada que ver con la fuente — así que puedes descargar una fuente y seguir dibujando el texto que hiciste con ella.

Un borde afilado: si descargas la fuente que estaba seleccionada, después no queda ninguna fuente seleccionada, y el siguiente fontPrint termina tu juego con un error. Selecciona otra antes si vas a seguir imprimiendo.

El sitio ordenado para todo esto es onShutdown, un callback que el motor llama una vez cuando el juego se está cerrando:

function onShutdown()
    spriteUnload(titleImage)
    fontUnload(titleFont)
end

Singe recoge lo tuyo cuando el juego termina, así que no se quema nada si te saltas esto. Escríbelo de todos modos. Un juego que suelta lo que ha cargado es un juego que puedes cargar dos veces.

El script completo

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local MARGIN  = 24
local TITLE_Y = 60
local SCORE_Y = 170
local LABEL_Y = 186
local HINT_Y  = 300
local CLOCK_Y = 430

local score      = 0
local titleFont  = nil
local scoreFont  = nil
local smallFont  = nil
local titleImage = nil
local hintImage  = nil
local scoreImage = nil
local scoreShown = nil


local function centered(image)
    return (overlayGetWidth() - spriteGetWidth(image)) / 2
end


local function renderScore()
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontSelect(scoreFont)
    colorForeground(255, 255, 255)
    scoreImage = fontToSprite(string.format("%06d", score))
    scoreShown = score
end


fontQuality(FONT_QUALITY_BLENDED)

titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)
scoreFont = fontLoad("Singe/FreeSansBold.ttf", 36)
smallFont = fontLoad("Singe/FreeSansBold.ttf", 18)

fontSelect(titleFont)
colorForeground(255, 211, 90)
titleImage = fontToSprite("ASTEROID PATROL")

fontSelect(smallFont)
colorForeground(140, 200, 255)
hintImage = fontToSprite("Press the fire button to score")

renderScore()


function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        score = score + 125
    end
end


function onOverlayUpdate()
    overlayClear()

    spriteDraw(titleImage, centered(titleImage), TITLE_Y)

    if score ~= scoreShown then
        renderScore()
    end
    spriteDraw(scoreImage, overlayGetWidth() - MARGIN - spriteGetWidth(scoreImage), SCORE_Y)

    fontSelect(smallFont)
    colorForeground(160, 160, 160)
    fontPrint(MARGIN, LABEL_Y, "SCORE")
    fontPrint(MARGIN, CLOCK_Y, "Running for " .. (singeGetTicks() // 1000) .. " seconds")

    if (singeGetTicks() // 500) % 2 == 0 then
        spriteDraw(hintImage, centered(hintImage), HINT_Y)
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    spriteUnload(titleImage)
    spriteUnload(hintImage)
    if scoreImage ~= nil then
        spriteUnload(scoreImage)
    end
    fontUnload(titleFont)
    fontUnload(scoreFont)
    fontUnload(smallFont)
end

Ejecútalo y mantén pulsado el botón de disparo. El título y la pista se quedan centrados, la puntuación sube contra el margen derecho y solo se vuelve a dibujar cuando cambia, la pista parpadea, y la etiqueta y el reloj se imprimen con fontPrint en cada fotograma — el reloj en segundos enteros, así que solo es una cadena nueva una vez por segundo.

Qué acaba de pasar

titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)
scoreFont = fontLoad("Singe/FreeSansBold.ttf", 36)
smallFont = fontLoad("Singe/FreeSansBold.ttf", 18)

Un archivo, tres tamaños, tres handles. Cada uno cuesta memoria para su propio juego de glifos dibujados, así que carga los tamaños que uses y ni uno más. Tres es normal. Una docena huele mal.

Después de estas tres líneas la fuente seleccionada es smallFont, porque cargar selecciona. Por eso el código llama a fontSelect(titleFont) antes de dibujar el título: lo último que se ha cargado no es lo que quieres primero.

local function centered(image)
    return (overlayGetWidth() - spriteGetWidth(image)) / 2
end

Escrita una vez como función porque se usa dos veces, y porque la próxima vez que quieras centrar algo la vas a volver a querer. Ponle nombre a la cuenta y no tendrás que volver a leerla nunca.

    if (singeGetTicks() // 500) % 2 == 0 then
        spriteDraw(hintImage, centered(hintImage), HINT_Y)
    end

singeGetTicks() es el número de milisegundos desde que arrancó el motor. // es una división que tira el resto, así que singeGetTicks() // 500 cuenta medios segundos, y % 2 es el resto de dividir entre dos, que es 0, 1, 0, 1…​ Así que la pista se dibuja durante medio segundo y se salta durante medio segundo. No dibujar nada es como se hace que algo parpadee.

    fontSelect(smallFont)
    colorForeground(160, 160, 160)
    fontPrint(MARGIN, LABEL_Y, "SCORE")

Aquí hacen falta los dos ajustes, y vale la pena tener claro por qué. Dibujar un sprite no cambia la fuente seleccionada ni el color, así que las dos llamadas spriteDraw de arriba los dejan exactamente como los encontraron. Pero el código de preparación seleccionó tres fuentes distintas una tras otra, y renderScore selecciona otra cada vez que se mueve la puntuación, así que la selección cuando se ejecuta esta línea es la que haya tocado elegir la última. No intentes seguirle la pista. Selecciona la fuente y pon el color justo antes de imprimir, siempre. Son dos líneas, y te quitan de encima toda una categoría de tardes de desconcierto.

Pruébalo

  1. Cambia la calidad. Pon FONT_QUALITY_SOLID en la línea de fontQuality y mira la curva de la S de ASTEROID. Luego prueba FONT_QUALITY_SHADED y fíjate en lo que pasa detrás de cada cadena.

  2. Pon la pista en amarillo. Mueve la línea colorForeground(140, 200, 255) de encima de fontToSprite a justo encima del spriteDraw que dibuja hintImage, y cambia los números. Averigua por qué no pasa nada. Luego devuélvela a su sitio, haz la pista blanca y vuélvela amarilla con spriteSetTint justo antes de dibujarla.

  3. Alinea el reloj a la derecha. El reloj se dibuja con fontPrint, que no se puede medir. Ponlo contra el margen derecho de todos modos. Solo hay una forma, y encontrarla es lo importante.

  4. Quita la comprobación de scoreShown, para que renderScore() se ejecute en cada fotograma. Se verá igual, pero ahora dibuja la puntuación sesenta veces por segundo en lugar de cuando cambia — justo el trabajo que fontPrint te ahorra cuando le dejas. Luego quita también el spriteUnload de renderScore, déjalo en marcha un minuto y vigila la memoria que usa tu juego.

  5. Imprime un reloj en milisegundos. Cambia la línea del reloj para que imprima singeGetTicks() sin el // 1000. Sigue funcionando; ahora es una cadena que fontPrint no ha visto nunca, en cada fotograma. En un ordenador lento, ese es el tipo de texto que cuesta.

  6. Usa tu propia fuente. Busca un .ttf en tu ordenador, cópialo junto a tu script y cárgalo con DIR .. "thatfont.ttf". Algunas fuentes quedan fatal a 18 puntos y bien a 48. Eso es culpa de la fuente, no tuya.

Rómpelo a propósito

Añade una línea que diga fontPrint(24, 60, "SCORE") justo debajo de overlaySetResolution(discGetWidth(), discGetHeight()), para que se ejecute antes de que haya habido ningún fontLoad. Singe arranca y se muere al instante:

4:fontPrint:  No font selected.

Léelo igual que cualquier otro error. 4 es la línea. fontPrint es la llamada del motor que se ha quejado — este tipo de mensaje sale de dentro del motor y no de Lua, así que nombra la función en lugar del archivo. El resto es la queja, y aquí es exacta: le has pedido que imprima y no había ninguna fuente con la que imprimir.

Te encontrarás con este de verdad de una forma menos evidente. Descarga la fuente seleccionada mientras el juego está en marcha y el siguiente fontPrint dirá exactamente lo mismo, a varios cientos de líneas del fontUnload que lo provocó.

Lo que has aprendido

  • fontLoad abre un archivo TrueType a un tamaño en puntos fijo y devuelve un handle. Un tamaño, un handle.

  • Cargar una fuente la selecciona; fontSelect elige entre las fuentes cargadas.

  • fontPrint cuenta en píxeles y overlayPrint cuenta en celdas de carácter.

  • El color no es un argumento. colorForeground es un ajuste; ponlo y luego dibuja.

  • fontQuality elige cómo se rasterizan las letras, y FONT_QUALITY_BLENDED es la respuesta habitual.

  • fontPrint guarda lo que dibuja, así que imprimir el mismo texto en cada fotograma es barato; lo que cuesta es el texto que cambia en cada fotograma.

  • fontToSprite dibuja en un sprite, que spriteGetWidth mide y que las llamadas sprite* pueden escalar y girar. Úsalo para eso, no por velocidad.

  • Medir es la forma de centrar o alinear texto a la derecha, porque nada más te puede decir cuánto va a medir de ancho una cadena.

  • colorForeground llega al texto cuando se crea, nunca a un sprite cuando se dibuja; spriteSetTint es la forma de volver a colorear un sprite después.

  • fontUnload libera una fuente; los sprites que creó sobreviven.

La próxima vez

Un texto con buen aspecto está muy lejos de un menú que funcione. Una página con un título, una lista por la que mueves un cursor, un deslizador y un botón son cien líneas de dibujo y de cuentas con el cursor si la construyes con las llamadas de esta lección. La lección veinte no la construye con esas llamadas en absoluto.

Lección 20: Menús y pantallas

La lección terminada

Puedes construir un menú con lo que ya sabes. Una caja, algo de texto, un cursor que se mueve cuando se mueve el stick, un if para cada opción, y aritmética para que todo siga alineado cuando añadas una cuarta opción. Funciona. También son unas cien líneas para una página con tres botones, y cada una de esas líneas te toca mantenerla a ti.

Singe lleva dentro todo un motor de documentos — RmlUi — y un menú escrito para él es una página, como una página web, con una hoja de estilo. Reparte él solo su texto en líneas. Se vuelve a maquetar solo cuando añades una opción. Sabe qué es un botón, qué es un deslizador y a qué control está apuntando el jugador. Esta lección construye con él un menú de pausa, sobre un juego que sigue funcionando por detrás.

Dos archivos

Una página de GUI son dos cosas: un documento que dice qué hay en la página, y Lua que dice qué hace la página. Viven en archivos separados, y esa es toda la gracia del ejercicio — la maquetación deja de ser código.

Empieza con un script llamado menu.singe y un juego tan pequeño que cabe en un párrafo: una nave que cruza la pantalla y una puntuación que sube cada vez que llega al otro lado. Llevas escribiendo este tipo de cosas desde la lección siete.

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local ship  = spriteLoad(DIR .. "art/spaceship.png")
local shipX = 0
local speed = 2
local score = 0


function onOverlayUpdate()
    overlayClear()
    shipX = shipX + speed
    if shipX > overlayGetWidth() then
        shipX = -spriteGetWidth(ship)
        score = score + 10
    end
    spriteDraw(ship, shipX, 300)
    return OVERLAY_UPDATED
end

Eso funciona. Ahora el documento. Junto a tu script, crea un archivo llamado pause.rml:

<rml>
<head>
	<title>Pause</title>
	<link type="text/rcss" href="Singe/gui.rcss"/>
	<style>
		body { width: 100%; height: 100%; }
		#frame { width: 380dp; margin: 80dp auto; }
		.row { display: block; margin: 8dp 0; }
		label { display: inline-block; width: 100dp; }
		button { nav: auto; }
		input.range { nav: auto; width: 200dp; }
		#status { min-height: 28dp; }
	</style>
</head>
<body id="pause">
	<div id="frame" class="panel">
		<h1>Paused</h1>
		<p class="row">Score <span id="score">000000</span></p>
		<div class="row"><label>Speed</label><input type="range" id="speed" min="1" max="8" step="1" value="2"/></div>
		<div class="row">
			<button id="resume" autofocus>Resume</button>
			<button id="restart">Restart</button>
			<button id="quit">Quit</button>
		</div>
		<p id="status" class="muted">Arrow keys move, Return chooses.</p>
	</div>
</body>
</rml>

Si alguna vez has visto el código fuente de una página web, esto te sonará. Si no, aquí tienes todo lo que necesitas para leerlo.

Un documento está hecho de elementos. Un elemento empieza con un nombre entre corchetes angulares, <h1>, termina con el mismo nombre y una barra, </h1>, y lo que haya entre los dos está dentro de él. Algunos elementos no tienen nada dentro y se cierran solos con una barra al final, como el <input …​/> de arriba. Los elementos se anidan, y la sangría muestra el anidamiento igual que lo muestra en Lua.

Las palabras que hay dentro de la etiqueta de apertura son atributos, y se escriben name="value". Dos de ellos te importan más que el resto. id le da a un elemento un nombre por el que tu script puede encontrarlo, que es como se hablan Lua y el documento. class mete el elemento en un grupo al que puede apuntar la hoja de estilo; panel, muted y list son grupos que la hoja de estilo del propio motor ya conoce.

El lenguaje de marcado se llama RML y el lenguaje de estilos se llama RCSS. Son de RmlUi, no de Singe. El capítulo sobre la GUI de la referencia te remite a la documentación de RmlUi para la lista completa de lo que puedes escribir, y tarde o temprano la querrás. Todo lo de esta lección funciona sin ella.

Muéstrala

De vuelta al script. Encima de onOverlayUpdate, añade:

local gui  = guiNew(overlayGetWidth(), overlayGetHeight())
local page = guiLoad(gui, DIR .. "pause.rml")

guiNew crea una GUI: un rectángulo de tamaño fijo en el que se maquetan y se dibujan los documentos. Devuelve un handle, igual que fontLoad y spriteLoad. Hacerla del tamaño del overlay significa que un píxel del documento es un píxel de tu overlay, y así las cuentas que haces de cabeza siguen siendo sencillas.

guiLoad lee un documento en esa GUI y devuelve un segundo handle, para el propio documento. Casi todas las demás llamadas reciben los dos: la GUI y el documento que hay en ella. Una GUI puede contener hasta treinta y dos documentos — una página de título, una de opciones y una de fin de partida pueden compartir una — y pueden existir hasta dieciséis GUI a la vez.

Todavía no hay nada en pantalla, porque cargar un documento no lo dibuja. Añade una línea a onOverlayUpdate, justo antes del return:

    guiDraw(gui)

Ejecútalo. Ahí está el panel, encima de la nave, con su título, sus tres botones y su deslizador, y no has escrito nada de código de dibujo.

guiDraw compone la GUI sobre el overlay solo para este fotograma, como todas las demás llamadas de dibujo, así que va en onOverlayUpdate y hay que volver a llamarla en el fotograma siguiente. Dónde la pongas decide qué queda encima: todo lo que dibujaste antes queda debajo, y todo lo que dibujes después va por encima. Un punto de mira dibujado después de guiDraw nunca queda tapado por el menú.

Deja que el jugador la use

Haz clic en un botón. No pasa nada, y el botón ni siquiera se ilumina.

Una GUI nueva es un dibujo, no un panel de control. Es a propósito: un HUD o un cartel no deberían tragarse el botón de disparo. Para que una página reciba entrada:

guiSetInput(gui, true)

Ahora el ratón funciona, los botones se iluminan bajo el puntero y las teclas de flecha saltan de un control a otro, porque el documento lo pidió con nav: auto. En un mando o en un stick, las cuatro direcciones llegan como las teclas de flecha, el primer botón de acción llega como Intro y el segundo llega como Esc. Una recreativa con un joystick y dos botones maneja esta página sin saber que es un documento.

Del control sobre el que actúan las teclas se dice que tiene el foco, y un botón con el foco lleva un borde dorado. El foco empieza en Resume porque ese botón dice autofocus: cada vez que se muestra la página, el foco va al control marcado así. Si lo quitas, las teclas de flecha no tienen desde dónde moverse hasta que el jugador hace clic en algo, lo que en una recreativa sin ratón no pasa nunca.

Pero hacer clic sigue sin hacer nada, porque no hay nada escuchando.

Háblale

Tres llamadas unen el documento a tu script, y entre las tres lo hacen casi todo.

guiSetHandler(gui, page, "resume", "click", function()
    closeMenu()
end)

guiSetHandler dice: cuando el elemento con este id haga esto, llama a esta función. El id es el del documento. El nombre del evento es de RmlUi: "click" para los botones, "change" para cualquier cosa que el jugador ajuste, y una larga lista de otros que puedes consultar cuando los necesites. Se guarda una función por elemento y por evento, así que poner otra sustituye a la anterior, y pasar nil en lugar de una función la quita.

Tu función se llama con cinco argumentos — la GUI, el documento, el id, el evento y el valor actual del elemento como cadena. Recoge los que quieras e ignora el resto, igual que ya ignoras argumentos en Lua.

guiSetHandler(gui, page, "speed", "change", function(g, d, id, event, value)
    speed = math.floor(tonumber(value))
end)

El deslizador entrega su valor como cadena, y RmlUi escribe los números a su manera, así que 4 llega como "4.000000". tonumber convierte la cadena en un número y math.floor tira los decimales. Saltarte ese paso y usar la cadena como si fuera un número es un error que cometerás una vez.

guiSetValue(gui, page, "score", string.format("%06d", score))

guiSetValue escribe en un elemento. En un control de formulario pone el valor del control; en cualquier otra cosa — un párrafo, un div, el <span id="score"> de tu documento — sustituye lo que hay dentro del elemento, y la página se vuelve a maquetar en el fotograma siguiente. guiGetValue es la misma llamada al revés, y responde nil para un id que no tiene ningún elemento, así que puedes preguntar por un elemento que quizá no exista sin morir en el intento.

Esa es toda la API del día a día: guiSetHandler, guiSetValue, guiGetValue. Hay muchísimo más a tu alcance a través de los propios objetos Lua de RmlUi, a los que se llega desde la variable global rmlui, y el capítulo sobre la GUI de la referencia explica cómo. Llegarás muy lejos antes de necesitarlo.

Vuelve a esconderla

Un menú de pausa no está a la vista todo el tiempo. guiHide quita un documento de la pantalla y guiShow lo vuelve a poner, conservando todo lo que el jugador haya escrito o elegido.

La pausa en sí es singeSetPauseFlag(true), que detiene el disco, los vídeos y los sonidos pero sigue llamando a tus callbacks, así que todavía puedes dibujar. El motor tiene su propia tecla de pausa, que congela el script por completo, y las dos se pelearían; singeSetPauseKeyEnabled(false) le quita esa tecla al motor para que SWITCH_PAUSE llegue a onInputPressed como cualquier otro interruptor. En un teclado, esa tecla es la P.

local function closeMenu()
    paused = false
    singeSetPauseFlag(false)
    guiHide(gui, page)
    guiSetInput(gui, false)
end


local function openMenu()
    paused = true
    singeSetPauseFlag(true)
    guiSetValue(gui, page, "score", string.format("%06d", score))
    guiShow(gui, page)
    guiSetInput(gui, true)
end

Apagar la entrada junto con la página no es decoración. Una página escondida que sigue recibiendo entrada se come las teclas de flecha del jugador durante el resto de la partida.

Lo que la página no usa te sigue llegando

Esta es la regla que hace que sea seguro dejar una GUI a la vista durante la partida, y vale la pena decirla claramente: un evento que ha usado un elemento nunca llega a tus callbacks. Un Intro que ha pulsado el botón que tiene el foco no llega como onInputPressed. Una flecha que ha movido el foco no llega como SWITCH_LEFT. Un clic en un botón no es un interruptor del ratón.

Todo lo que la página no ha usado la atraviesa y te llega como siempre. Por eso P cierra este menú: ningún elemento del documento usa P, así que la tecla llega a onInputPressed exactamente igual que cuando el menú no está. También es por eso que un HUD que recibe entrada sigue dejando pasar el botón de disparo.

Hay una tecla que no sigue la regla. RmlUi usa la tecla Tab para mover el foco y nunca la devuelve, así que Singe solo le pasa Tab a una GUI mientras alguien está escribiendo de verdad en un campo de texto. Un juego que asigna Tab a algo la conserva.

Dale estilo

Vuelve a mirar el <head> del documento. Una sola línea hace casi todo el trabajo:

	<link type="text/rcss" href="Singe/gui.rcss"/>

Ese es el tema que trae el motor, y es la razón de que tu panel tenga un borde, un degradado y un título dorado sin que tú hayas elegido nada de eso. Sin una hoja de estilo, RmlUi casi no dibuja nada, porque todos los elementos empiezan en línea y del tamaño de su contenido, así que enlazar esta primero y sobrescribir lo que no te guste es el camino más rápido hacia una página que parezca algo.

El tema te da .panel (una caja con borde y esquinas redondeadas), .list (una caja con desplazamiento cuyas filas div hijas se resaltan y reciben el foco), .muted (texto más tenue para las pistas), títulos, y todos los controles de formulario con sus estados al pasar el ratón, con el foco y pulsados. El capítulo sobre la GUI de la referencia los enumera.

Todo lo que va después del enlace es tuyo. El bloque <style> de pause.rml sobrescribe el tema para esta página: las reglas posteriores ganan a las anteriores, y una regla que apunta a un id gana a una que apunta a una class. En un juego de verdad, pon tus propias reglas en un archivo .rcss junto al documento y enlázalo en segundo lugar, para que tu aspecto sea un solo archivo para todas las páginas.

La unidad dp es un píxel del tamaño propio de la GUI — tu GUI es del tamaño del overlay, así que 380dp son 380 píxeles del overlay. margin: 80dp auto es el truco que centra un bloque de anchura conocida: auto reparte lo que sobra a partes iguales entre los dos lados. No hay que medir nada ni hacer cuentas, cosa que, después de la lección diecinueve, quizá te resulte un poco molesta.

Para usar tu propia fuente en un documento, cárgala con guiLoadFont antes de los documentos que la usan, y nómbrala en RCSS por el nombre de familia que hay dentro del archivo de la fuente, no por el nombre del archivo.

Cuándo no usar nada de esto

Una GUI es una página. Es la respuesta correcta para un menú, una pantalla de opciones, una tabla de récords, una pantalla de fin de partida o un HUD con una maquetación de verdad.

Es la respuesta equivocada para una puntuación en una esquina. Eso son dos líneas de fontPrint de la lección diecinueve, y meterlo en un documento no te da nada y te cuesta una textura. Lo mismo vale para un punto de mira, una barra de vida que has dibujado con overlayBox y una línea de texto de depuración.

Tres hechos lo deciden por ti.

Una GUI necesita una GPU. En una máquina sin ella — un ordenador viejo, una Pi pequeña, una máquina sin ningún controlador de Vulkan, Direct3D 12 o Metal — no hay GUI, y guiNew no responde educadamente false: termina tu juego. La escena 3D de la lección veintidós va por el mismo camino, así que no será la última vez que lo preguntes. Pregunta antes a singeHasGpu() si tu juego tiene que funcionar en los dos sitios, y ten una versión con el overlay de siempre a la que recurrir. El menú del propio motor hace exactamente eso.

Una GUI cuesta una textura y una pasada de maquetación en cada fotograma, la dibujes o no. Una GUI con la que has terminado debería borrarse con guiDelete, no solo esconderse. Esconder es para una página que vas a volver a mostrar dentro de un minuto.

Y una recarga se lleva por delante las GUI. F5, -R y cualquier cosa que reinicie el script se llevan todas las GUI consigo, y el script las vuelve a crear cuando se ejecuta. Eso está bien, siempre que las construyas en el cuerpo de tu script y no en algún rincón que solo se ejecuta una vez.

El script completo

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())
singeSetPauseKeyEnabled(false)

local SHIP_Y = 300

local ship    = spriteLoad(DIR .. "art/spaceship.png")
local hudFont = fontLoad("Singe/FreeSansBold.ttf", 20)
local shipX   = 0
local speed   = 2
local score   = 0
local paused  = false
local gui     = nil
local page    = nil


local function say(text)
    if gui ~= nil then
        guiSetValue(gui, page, "status", text)
    end
end


local function closeMenu()
    paused = false
    singeSetPauseFlag(false)
    if gui ~= nil then
        guiHide(gui, page)
        guiSetInput(gui, false)
    end
end


local function openMenu()
    paused = true
    singeSetPauseFlag(true)
    if gui ~= nil then
        guiSetValue(gui, page, "score", string.format("%06d", score))
        guiShow(gui, page)
        guiSetInput(gui, true)
    end
end


if singeHasGpu() then
    gui  = guiNew(overlayGetWidth(), overlayGetHeight())
    page = guiLoad(gui, DIR .. "pause.rml")
    guiHide(gui, page)
    guiSetInput(gui, false)

    guiSetHandler(gui, page, "resume", "click", function()
        closeMenu()
    end)

    guiSetHandler(gui, page, "restart", "click", function()
        score = 0
        shipX = 0
        closeMenu()
    end)

    guiSetHandler(gui, page, "quit", "click", function()
        singeQuit()
    end)

    guiSetHandler(gui, page, "speed", "change", function(g, d, id, event, value)
        speed = math.floor(tonumber(value))
        say("Speed " .. speed)
    end)
end


function onInputPressed(what)
    if what == SWITCH_PAUSE then
        if paused then
            closeMenu()
        else
            openMenu()
        end
    end
end


function onOverlayUpdate()
    overlayClear()

    if not paused then
        shipX = shipX + speed
        if shipX > overlayGetWidth() then
            shipX = -spriteGetWidth(ship)
            score = score + 10
        end
    end
    spriteDraw(ship, shipX, SHIP_Y)

    fontSelect(hudFont)
    colorForeground(255, 255, 255)
    fontPrint(16, 16, string.format("SCORE %06d", score))
    fontPrint(16, 40, "P pauses")

    if paused then
        if gui ~= nil then
            guiDraw(gui)
        else
            colorForeground(255, 211, 90)
            fontPrint(16, 70, "PAUSED -- no GPU, so no menu")
        end
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    if gui ~= nil then
        guiDelete(gui)
    end
    spriteUnload(ship)
    fontUnload(hudFont)
end

Qué acaba de pasar

if singeHasGpu() then
    gui  = guiNew(overlayGetWidth(), overlayGetHeight())
    page = guiLoad(gui, DIR .. "pause.rml")

Toda la GUI se construye dentro de ese if, y gui se queda en nil en una máquina sin GPU. Cada llamada que toca la GUI está protegida con if gui ~= nil, y la pausa sigue funcionando sin menú. Son cuatro líneas de más, y son la diferencia entre «no tiene menú en esa máquina» y «no arranca en esa máquina».

    guiHide(gui, page)
    guiSetInput(gui, false)

guiLoad muestra el documento que ha cargado, así que una página que tiene que empezar escondida hay que esconderla enseguida. En una GUI nueva la entrada ya está apagada, pero apagarla aquí hace que openMenu y closeMenu sean exactamente la una el reflejo de la otra, y las parejas que se reflejan así son mucho más difíciles de estropear.

    guiSetHandler(gui, page, "restart", "click", function()
        score = 0
        shipX = 0
        closeMenu()
    end)

El manejador es una función sin nombre, escrita donde se usa. Lua te deja escribir function(…​) …​ end en cualquier sitio donde se espera un valor, y como guiSetHandler espera una función, puedes darle una en el momento en lugar de ponerle nombre primero y pasar el nombre. Llega a score, shipX y closeMenu porque están declarados encima de ella en el mismo archivo, y esa es justamente la razón de que los manejadores se preparen debajo de las cosas que tocan.

    if not paused then
        shipX = shipX + speed

El indicador de pausa detiene el disco y los sonidos, no tus cuentas. onOverlayUpdate se sigue llamando — de eso se trata, porque si no el menú no se podría dibujar — así que lo tuyo que tenga que pararse durante la pausa lo tienes que parar tú.

Pruébalo

  1. Añade un cuarto botón. Copia la línea <button id="quit">, dale un id nuevo y un texto nuevo, y añádele un manejador. Fíjate en que no ha hecho falta volver a medir ni desplazar nada.

  2. Cámbiale el estilo. En el bloque <style>, cambia #frame por width: 260dp; margin: 20dp; y mira cómo el panel se mueve y el texto se vuelve a repartir en líneas él solo.

  3. Quita el guiSetInput(gui, true) de openMenu. La página sigue apareciendo. Averigua, solo con lo que ves en la pantalla, qué has perdido.

  4. Deja la página a la vista todo el tiempo. Borra las llamadas a guiHide, cambia las dos llamadas guiSetInput(gui, false) a true y dibuja la GUI en cada fotograma en lugar de solo durante la pausa. Luego pulsa las teclas de flecha e Intro mientras vuela la nave. La página se las queda: el foco se mueve, el deslizador cambia la velocidad e Intro pulsa el botón que tenga el foco. Un juego que se manejara con esas teclas no las oiría nunca. Por eso un HUD lleva guiSetInput(gui, false).

  5. Pon la puntuación en la página en lugar de en el HUD. Llama a guiSetValue para score en cada fotograma en lugar de solo en openMenu, y borra la línea de fontPrint. Luego decide cuál de las dos prefieres de verdad, y por qué.

Rómpelo a propósito

Cambia un id en pause.rml, de id="resume" a id="continue", y deja el script como está. Singe arranca y muere:

52:guiSetHandler:  No element "resume" in document 0 of GUI 0.

Léelo como lees cualquier error del motor. La línea, la llamada que se ha quejado y luego la queja — y esta queja es precisa. No dice que el documento esté roto; el documento se ha cargado perfectamente. Dice que has pedido un elemento por un nombre que no tiene nada de lo que hay en él.

guiSetHandler y guiSetValue mueren las dos con un id que no existe, porque un manejador que querías poner y no pusiste es un fallo del que quieres enterarte en el acto. guiGetValue es la excepción: responde nil, así que puedes preguntar si algo está ahí.

El otro error que vale la pena conocer es el que te sale cuando el propio documento no se carga. Cambia el nombre de pause.rml y ejecútalo. Esta vez Singe nombra el archivo y cita el motivo que da RmlUi, y las quejas de RmlUi sobre tu marcado y tus estilos van a la consola tanto si la carga sale bien como si no. Lee esa consola la primera vez que una página salga en blanco; normalmente ya habrá dicho por qué.

Lo que has aprendido

  • Una GUI es un rectángulo de tamaño fijo en el que se maquetan y se dibujan documentos; guiNew crea una y guiDelete la libera.

  • guiLoad pone un documento RML en una GUI y lo muestra; guiHide, guiShow y guiClose lo gestionan después.

  • guiDraw compone la GUI sobre el overlay durante un fotograma, así que va en onOverlayUpdate como todas las demás llamadas de dibujo.

  • Una GUI nueva solo muestra; guiSetInput es lo que la hace usable.

  • guiSetHandler ejecuta tu función cuando se hace clic en un elemento o se cambia, guiSetValue escribe en un elemento y guiGetValue lee uno.

  • Un evento que ha usado un elemento nunca llega a tus propios callbacks; todo lo demás pasa como siempre.

  • Singe/gui.rcss es el tema incluido; enlázalo primero y sobrescríbelo en un bloque <style> o en una hoja tuya.

  • Una GUI necesita una GPU, así que pregunta a singeHasGpu() si tu juego tiene que funcionar sin ella.

  • Cada GUI se renderiza en cada fotograma la dibujes o no, así que borra las que ya no necesites.

  • Una puntuación en la esquina son dos líneas de fontPrint, no un documento.

La próxima vez

Hay un tipo más de texto en pantalla, y tiene su propio sistema por un motivo que no tiene nada que ver con su aspecto. La lección veintiuno trata de los subtítulos, y de los jugadores que no pueden jugar a tu juego sin ellos.

Lección 21: Subtítulos

La lección terminada

Alguien que no puede oír va a jugar a tu juego.

Si tu juego tiene voces y no tiene subtítulos, no podrá. No es que «le cueste más» — llegará a la primera escena en la que un personaje dice lo que le explica al jugador qué tiene que hacer, y ahí se quedará. Eso es todo, y es la razón de que esta lección exista en lugar de ser un párrafo de la lección diecinueve.

La otra razón es práctica. Meterle subtítulos a un juego ya terminado es un suplicio. Tienes que encontrar cada frase hablada, averiguar en qué fotograma está y descubrir que la mitad de los tiempos están mal porque tu vídeo se volvió a codificar a mitad del proyecto. Si lo haces mientras escribes el juego, es cosa de una tarde. Singe te da un sistema que hace la parte difícil, y esta lección explica cómo usarlo.

No es dibujar texto sin más

Podrías hacer los subtítulos tú mismo. Guardas una lista de frases con sus tiempos de inicio y de fin, miras el reloj en onOverlayUpdate y dibujas la actual con fontToSprite. Hay quien lo ha hecho. Esta es la razón por la que tú no deberías.

Los subtítulos se sincronizan con el disco, no con un reloj. Cuando srtLoad lee tu archivo, convierte cada marca de tiempo en un número de fotograma del disco, en ese mismo momento, usando la tasa de fotogramas del disco que esté cargado. A partir de entonces el motor no mira ningún reloj; en cada fotograma dibujado pregunta qué entrada cubre el fotograma en el que está el disco.

Esa única decisión te da lo que un sistema hecho a mano nunca consigue hacer bien: un subtítulo sobrevive a un salto. Manda el disco a cualquier sitio — discSearch, discSkipForward, un paso, una ramificación a otro segmento — y la frase correcta está en pantalla en el siguiente fotograma dibujado, hacia delante o hacia atrás, sin recargar nada y sin poner a cero ningún reloj. En un juego con ramificaciones como el de la lección dieciséis, donde las decisiones del jugador hacen saltar el disco de un lado a otro sin parar, esa es la diferencia entre funcionar y casi funcionar.

Además se dibuja en el sitio correcto. El documento de los subtítulos está sobre la imagen, por encima de tu overlay y por debajo de cualquier GUI en espacio de pantalla, y sigue a la imagen allí donde la pongan los ajustes del jugador — una imagen encogida, una desplazada, una recreativa girada, un hueco en un bezel. No acepta entrada del ratón, así que un disparo de pistola de luz lo atraviesa sin más. Hacer todo eso bien por tu cuenta es una semana que no tenías prevista.

Escribe el archivo

Los subtítulos van en un archivo SubRip, que termina en .srt y es texto plano que puedes escribir en cualquier editor. Es uno de los formatos más sencillos que existen. Crea un archivo llamado subtitles.srt junto a tu script:

1
00:00:01,000 --> 00:00:04,000
They told us the cave was empty.

2
00:00:04,200 --> 00:00:08,000
They were wrong about
a great many things.

3
00:00:08,500 --> 00:00:13,000
Keep your light on the floor.

Una entrada son cuatro cosas. Un número en una línea propia. Una línea con dos marcas de tiempo y, entre ellas, una flecha hecha de dos guiones y un signo de mayor que. Una o más líneas de texto. Una línea en blanco para terminar.

Una marca de tiempo es HH:MM:SS,mmm — horas, minutos y segundos separados por dos puntos, luego una coma y luego los milisegundos. La coma no es una errata, y un punto no sirve. 00:00:04,200 son cuatro segundos y un quinto desde el principio.

Los números de las entradas se leen y se tiran, así que no tienen por qué estar en orden, ni siquiera ser correctos. Numéralas de todos modos; en algún momento estarás buscando la entrada cuarenta y uno.

La entrada dos muestra cómo es una entrada de dos líneas. Las líneas se muestran tal como las escribiste, así que eres tú quien decide dónde se parte una línea larga, lo cual importa más de lo que parece y se explica más abajo.

El analizador es tolerante a propósito con las cosas que salen mal en un archivo editado a mano. Los finales de línea de Windows se cargan sin cambios, y los espacios del principio y del final se quitan de cada línea. Una entrada cuyas marcas de tiempo no se pueden analizar se salta, y el resto del archivo se sigue cargando, lo cual es muy amable justo hasta que te preguntas dónde ha ido a parar la línea doce. Algunas cosas no están soportadas: las etiquetas <i> y <b> que escriben algunas herramientas se muestran como texto en lugar de obedecerse, y las coordenadas de posición que algunas herramientas añaden a la línea de tiempo se ignoran. La sección de subtítulos de la referencia tiene la lista completa.

Cárgalo y actívalo

Tres llamadas, y el orden importa.

if srtLoad(DIR .. "subtitles.srt") then
    srtPosition(80)
    srtEnable(true)
end

srtLoad lee el archivo y responde true o false. Responde false, sin haber cargado nada, en tres casos: el archivo no se puede leer, no hay nada en él que se pueda analizar o no hay disco. En los tres imprime en la consola un aviso que nombra el archivo. Es un buen diseño y deberías aprovecharlo: un archivo de subtítulos que falta no merece que el juego muera por él, pero publicar un juego sin subtítulos sin enterarte sí merece que lo notes.

El caso de «no hay disco» es el que te va a pillar. Las marcas de tiempo tienen que convertirse en números de fotograma a la tasa de fotogramas del disco, y mientras no hay un disco abierto no hay tasa de fotogramas que usar. Así que carga los subtítulos después del disco, lo que en un script normal significa desde el cuerpo del script, donde se ejecuta todo lo demás que has escrito fuera de las funciones. De ahí se sigue que un .srt preparado para un vídeo a una tasa de fotogramas cae en el sitio equivocado en un vídeo a otra. Sincroniza tu archivo con el vídeo que de verdad vas a publicar.

srtEnable(true) activa las entradas cargadas. Un script empieza con los subtítulos desactivados, siempre, así que un juego que los carga tiene que activarlos. Desactivarlos otra vez quita lo que se esté mostrando, y volver a activarlos pone lo que cubra el fotograma en el que está el disco ahora mismo — sin buscar nada, sin estado que guardar.

Tener los subtítulos activados es un ajuste, no una decisión que tomas tú por el jugador. Ponlo en tu página de opciones de la lección veinte, guárdalo con saveSet de la lección doce y pásale a srtEnable lo último que haya elegido el jugador.

Dónde se colocan

srtPosition(70)

srtPosition es un porcentaje hacia abajo de la imagen, de 1 a 95, y por defecto es 80. Se aplica a la entrada que está en pantalla ahora mismo y a todas las que vienen después. Un número fuera del rango se ignora en lugar de recortarse al límite, lo que significa que una errata deja la posición exactamente donde estaba y no dice nada, así que revisa tus números.

El ochenta por ciento queda bajo, y queda bajo a propósito: la parte de abajo de la imagen suele ser la menos interesante del plano. Súbelos cuando la parte de abajo no sea aburrida — cuando tu juego dibuja un marcador a lo largo del borde inferior, o cuando el punto de mira de la pistola de luz del jugador vive ahí abajo.

Quitar uno

srtClear()

srtClear quita de golpe lo que haya en pantalla, y deja en paz las entradas cargadas y el estado de activación. La línea que se estaba mostrando sigue quitada hasta que el disco llega a la siguiente entrada. Úsalo cuando una escena termina antes de tiempo y no quieres que la última frase del diálogo se quede colgando sobre el plano siguiente.

Hay una llamada más que comparte la maquinaria de los subtítulos, y puede que ya la hayas usado:

overlayBanner("Extra life!", 20)

overlayBanner muestra un mensaje corto sobre la imagen durante unos treinta fotogramas dibujados y luego lo quita. Lo dibuja el mismo documento que los subtítulos, así que un rótulo parece un subtítulo, y mientras está en pantalla ocupa el lugar de cualquier subtítulo, que vuelve cuando se le acaba el tiempo al rótulo. Su propio argumento de altura es independiente de srtPosition y por defecto vale 47, el centro de la imagen. Los mensajes de más de sesenta caracteres se ignoran por completo, así que uno largo parece no funcionar en absoluto.

Subtítulos que ya están dentro del vídeo

Algunos archivos de vídeo llevan sus propias pistas de subtítulos. Si el tuyo las lleva, no necesitas ningún .srt:

if discGetSubtitleTracks() > 0 then
    srtLoadTrack(0)
else
    srtLoad(DIR .. "subtitles.srt")
end
srtEnable(true)

srtLoadTrack recibe un número de pista de 0 a discGetSubtitleTracks() - 1 y todo lo que viene después de cargar es idéntico. discGetSubtitleLanguage(track) te dice con qué idioma está etiquetada una pista, como un código de tres letras del tipo eng o fra, así que un juego puede ofrecerle al jugador lo que su vídeo resulte llevar.

Dos advertencias. Leer una pista recorre una vez todo el archivo de vídeo, sin decodificar ninguna imagen, así que un disco tan largo como una película tarda un momento: hazlo mientras hay otra cosa en pantalla, no entre dos fotogramas de juego. Y las pistas de subtítulos que guardan imágenes de las palabras en lugar de las palabras — las que usan los DVD y los Blu-ray — no se pueden leer. Se cuentan, para que la numeración coincida con la que muestran otros reproductores, pero srtLoadTrack responde false para ellas.

El script completo

Este necesita un vídeo. Ya tienes uno: Singe/menuBackground.mkv, que el motor desempaquetó en tu carpeta de trabajo la primera vez que ejecutaste algo. Dile a Singe que lo use como disco con --framefile, que además enciende el disco:

Singe --framefile=Singe/menuBackground.mkv subtitles
dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

local HUD_X     = 16
local STEP      = 5
local TOP_LIMIT = 10
local LOW_LIMIT = 95

local hudFont = fontLoad("Singe/FreeSansBold.ttf", 18)
local loaded  = false
local showing = false
local height  = 80


if discGetSubtitleTracks() > 0 then
    loaded = srtLoadTrack(0)
end
if not loaded then
    loaded = srtLoad(DIR .. "subtitles.srt")
end

if loaded then
    srtPosition(height)
    showing = true
    srtEnable(true)
end

discPlay()


function onInputPressed(what)
    if not loaded then
        return
    end
    if what == SWITCH_BUTTON1 then
        showing = not showing
        srtEnable(showing)
        if showing then
            overlayBanner("Subtitles on", 20)
        else
            overlayBanner("Subtitles off", 20)
        end
    elseif what == SWITCH_UP then
        height = math.max(TOP_LIMIT, height - STEP)
        srtPosition(height)
    elseif what == SWITCH_DOWN then
        height = math.min(LOW_LIMIT, height + STEP)
        srtPosition(height)
    elseif what == SWITCH_LEFT then
        srtClear()
        discSearch(0)
        discPlay()
    end
end


function onOverlayUpdate()
    overlayClear()
    fontSelect(hudFont)
    colorForeground(255, 255, 255)
    if loaded then
        if showing then
            fontPrint(HUD_X, 16, "Frame " .. discGetFrame() .. "   subtitles ON at " .. height .. "%")
        else
            fontPrint(HUD_X, 16, "Frame " .. discGetFrame() .. "   subtitles OFF")
        end
        fontPrint(HUD_X, 40, "Fire toggles them, up and down move them, left rewinds")
    else
        fontPrint(HUD_X, 16, "No subtitles loaded.")
        fontPrint(HUD_X, 40, "Run with --framefile and check subtitles.srt is beside the script.")
    end
    return OVERLAY_UPDATED
end


function onShutdown()
    fontUnload(hudFont)
end

Pulsa el disparo para activarlos y desactivarlos, arriba y abajo para mover las líneas, e izquierda para rebobinar hasta el principio. El rebobinado es el que hay que mirar: el disco salta atrás al fotograma cero y la entrada correcta está en pantalla justo en el fotograma siguiente, sin que tú hagas nada al respecto.

Qué acaba de pasar

if discGetSubtitleTracks() > 0 then
    loaded = srtLoadTrack(0)
end
if not loaded then
    loaded = srtLoad(DIR .. "subtitles.srt")
end

Usa los subtítulos del propio vídeo cuando los tiene, recurre al archivo que hay junto al script cuando no, y termina sabiendo cuál ha funcionado — si es que ha funcionado alguno. Las dos llamadas responden con un booleano, así que el plan de reserva son dos sentencias if y ningún caso especial. menuBackground.mkv no lleva ninguna pista de subtítulos, así que lo que vas a obtener de verdad es el archivo que escribiste.

function onInputPressed(what)
    if not loaded then
        return
    end

return sin nada detrás sale de la función inmediatamente. Sin subtítulos cargados, ninguna de estas teclas tiene nada que hacer, y salir pronto es más claro que envolver todo el cuerpo en un if. Llamar a srtEnable sin nada cargado no hace daño, pero escribir código que solo tiene sentido cuando no hace nada es una costumbre que más vale no coger.

    elseif what == SWITCH_LEFT then
        srtClear()
        discSearch(0)
        discPlay()

El srtClear no es necesario. El motor pondrá la entrada correcta para el fotograma cero en el siguiente fotograma dibujado de todos modos. Está ahí para que puedas borrarlo y mirar qué pasa: la línea vieja se queda en pantalla una fracción de segundo mientras el disco llega a donde va. En un salto lento ese destello de la línea equivocada se ve, y limpiar primero es como lo evitas.

Texto legible sobre una imagen en movimiento

El sistema pone las palabras en pantalla. Que alguien pueda leerlas es problema tuyo, y vale para cada línea de texto que dibujes sobre vídeo — una indicación de la lección dieciocho, una puntuación, una elección de rama — no solo para los subtítulos.

No te acerques a los bordes. Los televisores llevan setenta años recortando los bordes de la imagen, y los monitores de las recreativas son peores, no mejores. Trabaja suponiendo que el cinco por ciento exterior de la imagen, en cada lado, puede no estar en absoluto en la pantalla de alguien. Mantén dentro de ese margen todo lo que el jugador tenga que leer. Por eso srtPosition se detiene en 95 y no en 100.

El contraste no es una elección de color, es una garantía. Un texto blanco sobre una imagen es un texto blanco sobre lo que la imagen esté haciendo en ese momento, y dentro de dos segundos eso puede ser un campo nevado. El estilo de subtítulos incluido lo resuelve como lo hacen los subtítulos de cine: un panel oscuro que se ciñe al texto, más una sombra de un píxel. Si dibujas tu propio texto sobre vídeo, haz una cosa o la otra — un overlayBox detrás o una copia oscura del texto desplazada un píxel. No te fíes de la imagen.

Parte tú las líneas. Dos líneas cortas se leen más rápido que una larga, y una línea que se parte donde tú no has elegido suele partirse por el sitio equivocado. Apunta a unos cuarenta caracteres por línea y no más de dos líneas a la vez. Parte en una pausa natural: They were wrong about / a great many things se lee bien; They were wrong / about a great many things tropieza.

Déjalas el tiempo suficiente. Una velocidad de lectura cómoda anda por los quince caracteres por segundo, así que una línea de cuarenta caracteres pide unos tres segundos. Mira la entrada uno del archivo de arriba: treinta y dos caracteres, tres segundos. Si una frase del diálogo es corta y rápida, dejar la entrada un momento más allá del final de lo que se dice es más amable que quitarla de golpe.

Ponlos donde no está la acción. Si lo importante del plano está en la parte de abajo del encuadre, sube los subtítulos para esa escena con srtPosition. Puedes llamarla tantas veces como quieras, y el jugador nunca notará que lo has hecho.

Darles estilo

Las líneas las dibuja un documento, del mismo tipo que conociste en la lección veinte, y dos archivos de tu carpeta Singe deciden qué aspecto tienen:

  • Singe/subtitle.rml — el documento. Tiene un solo elemento, #slot, en el que el motor escribe la entrada o el rótulo actual.

  • Singe/subtitle.rcss — el estilo. .cue es el bloque que lleva la altura que pidió srtPosition, y .cue .text es la barra de texto que hay dentro: blanca, en negrita, sobre un panel oscuro redondeado que se ciñe al texto, con una sombra.

Abre subtitle.rcss y léelo — son unas cuarenta líneas. Luego déjalo en paz, porque lo que edites ahí no dura. Cada vez que Singe arranca, vuelve a poner su propia copia de todo lo que haya cambiado en la carpeta Singe, y lo dice:

>>> Updated File:  Singe/subtitle.rcss

Esa carpeta es del motor. Tu juego trae su propia copia en su lugar. Copia los dos archivos de Singe a tu carpeta subtitles, junto al script. Luego abre tu copia de subtitle.rml y cambia la única línea de su <head> que enlaza el estilo, para que quede así:

	<link type="text/rcss" href="subtitle.rcss"/>

Un nombre dentro de un documento se cuenta desde la propia carpeta del documento, salvo un nombre que empieza por Singe/, que siempre quiere decir la carpeta del motor. El enlace tal como lo copiaste, Singe/subtitle.rcss, sigue trayendo el estilo del motor. El nuevo trae el tuyo.

Cuando Singe encuentra un subtitle.rml junto a tu script, dibuja los subtítulos con ese en lugar de con el suyo. Añade -p al comando y Singe describe lo que va haciendo, línea a línea:

Singe -p --framefile=Singe/menuBackground.mkv subtitles

Cuando aparece la primera entrada, una de esas líneas es esta:

Using the game's own subtitles/subtitle.rml

Ahora cambia el font-size, el color, el background-color, el border-radius o el font-effect en tu subtitle.rcss, guarda y vuelve a ejecutarlo. El motor solo toca el contenido de #slot y la altura de .cue, así que todo lo demás de tus dos archivos es tuyo, y nada de lo que haga Singe al arrancar los tocará. Si -p dice que está usando los tuyos y el aspecto no ha cambiado, vuelve a leer el enlace: una copia que todavía dice Singe/ está usando sin avisar el estilo del motor.

Como overlayBanner usa el mismo documento, cambiar el estilo de los subtítulos cambia también el de tus rótulos, lo cual suele ser lo que quieres, y conviene saberlo antes de que te preguntes por qué.

Un límite: el documento de los subtítulos es un documento, y los documentos necesitan una GPU. En una máquina sin ella, srtLoad sigue leyendo tu archivo y sigue respondiendo con la verdad, y no se dibuja nada. Un aviso lo dice una vez.

Pruébalo

  1. Añade una cuarta entrada a subtitles.srt, entre los segundos once y trece. Guarda y ejecuta. Luego ponla fuera de orden, como entrada 99, la primera del archivo, y comprueba que sigue funcionando.

  2. Dale a una entrada una marca de tiempo mala — escribe 00:00:05.500 con un punto en lugar de una coma — y ejecuta. Mira qué línea desaparece, y fíjate en que no se dice absolutamente nada al respecto. Un archivo que se carga no es un archivo que esté bien.

  3. Cámbiales el estilo. En tu propio subtitle.rcss — la copia que está junto a tu script, no la de Singe — cambia .cue .text a texto amarillo sobre un fondo totalmente transparente, y luego añade una sombra más gruesa. Después reprodúcelo sobre el vídeo y decide con sinceridad si todavía se lee.

  4. Rompe la sincronización a propósito. Cambia todas las marcas de tiempo del archivo para que lleguen dos segundos tarde, y mira cómo un sistema que funciona correctamente entrega unos subtítulos inútiles. Esto es lo que te hace un vídeo recodificado.

  5. Lleva la opción a un menú. Coge la página de pausa de la lección veinte, añádele una casilla y conéctala a srtEnable. Luego guarda la elección con saveSet para que siga activada la próxima vez. Esta es la versión que de verdad quieren tus jugadores.

Rómpelo a propósito

Ejecuta el script sin la opción --framefile:

Singe subtitles

Se abre la ventana, negra, con tu mensaje de reserva, y la consola dice:

Warning:  No subtitles were loaded from subtitles/subtitles.srt.

Ni un cierre inesperado ni una ventana de error, porque srtLoad ha respondido false y tu script lo ha gestionado.

Ese es el fallo más valioso de esta lección, porque es el que ocurre sin que nadie se dé cuenta. No hay disco, así que no hay tasa de fotogramas, así que no hay nada en lo que convertir las marcas de tiempo, así que no se carga nada. Si hubieras escrito srtLoad(…​) sin más y hubieras tirado la respuesta, tu juego habría funcionado perfectamente sin mostrar subtítulos, y te habrías enterado cuando alguien te lo dijera.

Usa la respuesta. Siempre.

Lo que has aprendido

  • Un juego con voces y sin subtítulos es un juego al que algunas personas no pueden jugar en absoluto.

  • Meter los subtítulos sobre la marcha es cosa de una tarde; añadirlos al final no.

  • Los subtítulos son un archivo .srt: un número, dos marcas de tiempo con -→ entre ellas, el texto y una línea en blanco.

  • srtLoad convierte las marcas de tiempo en números de fotograma del disco al cargar, y por eso una entrada sobrevive a cualquier salto.

  • Hay que cargarlo después del disco, y responde false cuando no puede cargar, también cuando no hay disco. Comprueba la respuesta.

  • srtEnable los activa, y un script siempre empieza con ellos desactivados.

  • srtPosition los coloca como un porcentaje hacia abajo de la imagen, de 1 a 95.

  • srtClear quita lo que se esté mostrando, y overlayBanner comparte el mismo documento.

  • srtLoadTrack lee los subtítulos del propio archivo de vídeo cuando los lleva.

  • Singe reescribe su carpeta Singe en cada arranque, así que para cambiar el estilo de los subtítulos copias subtitle.rml y subtitle.rcss junto a tu script, haces que el enlace de la copia apunte a tu propia hoja y cambias esa.

  • El texto sobre una imagen en movimiento necesita un margen de seguridad, su propio contraste, líneas que hayas partido tú y tiempo para leerse.

La próxima vez

Hasta aquí el texto. La cuarta parte sigue sin que tengas que leerla en orden, y la próxima lección abre una puerta que ha estado cerrada durante veinte lecciones: overlayGetWidth y overlayGetHeight son dos números, y una escena tiene tres. La lección veintidós es el tercero.

Lección 22: Hacia el 3D

La lección terminada

Todo lo que has dibujado hasta ahora ha sido plano. Los sprites, el texto, las cajas y las líneas viven en el overlay, que es una lámina de cristal en la parte delantera de la ventana con las mismas coordenadas que tenía en la lección uno. Esta lección pone un mundo detrás de ese cristal: un sitio con profundidad, donde una cosa puede estar más cerca o más lejos, y donde una cámara decide qué ves de él.

Al final tendrás una caja flotando en el espacio que puedes girar con las teclas de flecha, y los números de sus ángulos impresos en la esquina con el mismo overlayPrint que usaste el primer día. Esa última parte importa más de lo que parece, y tiene su propia sección.

Una escena, una caja y una luz

Crea una carpeta, pon dentro un archivo llamado spin.singe y escribe esto.

sceneEnable(true)
sceneSetBackground(18, 20, 34)
sceneSetAmbient(35, 35, 45)

local paint = materialNew()
materialSetColor(paint, 215, 95, 60)
materialSetRoughness(paint, 0.6)

local box = nodeNew()
nodeSetMesh(box, meshBox(2, 2, 2), paint)

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 4, 6, 5)
nodeLookAt(sun, 0, 0, 0)


function onOverlayUpdate()
    nodeRotate(box, 0, 0.5, 0)
    return OVERLAY_UPDATED
end

Ejecútalo con Singe -R spin. Una caja naranja gira despacio sobre un fondo azul oscuro, iluminada desde arriba y desde la derecha, con una cara brillante y las demás perdiéndose en la sombra.

En ese script no hay ninguna cámara. Singe te ha puesto en (0, 0, 5) mirando al centro del mundo, porque una escena sin cámara tiene que verse desde algún sitio. Dentro de un momento lo sustituirás por tu propia cámara.

Si la ventana se queda negra, lee la consola. En una máquina cuyos gráficos no pueden dibujar una escena 3D, sceneEnable detiene el juego con un mensaje que lo dice, y no hay nada que hacer salvo seguir la lección en otro sitio. Los juegos 2D siguen funcionando en una máquina así; el 3D no.

Qué acaba de pasar

Las tres llamadas de arriba preparan el mundo en su conjunto.

sceneEnable(true)
sceneSetBackground(18, 20, 34)
sceneSetAmbient(35, 35, 45)

sceneEnable(true) enciende la capa 3D. Es la única llamada que hacen todos los juegos 3D, y hasta que la hagas no se dibuja nada de lo que construyas en la escena.

sceneSetBackground es el color con el que se borra la escena en cada fotograma, rojo, verde y azul de 0 a 255, igual que han funcionado los colores desde la lección nueve. Hay un cuarto número que puedes darle para la transparencia, que es como un juego que reproduce vídeo pone un objeto 3D delante de la película. Si no lo pones, el fondo es opaco.

sceneSetAmbient es un poco de luz que llega de todas las direcciones a la vez. Su trabajo es evitar que los lados a los que no llega ninguna lámpara queden completamente negros. Más adelante bájala a 0, 0, 0 y mira lo dura que se vuelve la imagen.

local paint = materialNew()
materialSetColor(paint, 215, 95, 60)
materialSetRoughness(paint, 0.6)

Un material es el aspecto de una superficie: su color, lo brillante que es, si lleva una imagen encima. materialNew crea uno y te devuelve un número que lo representa, el mismo tipo de handle que te dio spriteLoad en la lección nueve. Guárdalo en una variable, porque todas las llamadas posteriores lo necesitan.

materialSetRoughness va de 0, un espejo con un reflejo diminuto y duro, a 1, una superficie mate como de tiza sin ningún reflejo. 0.6 es pintura sobre madera. Hay una docena más de llamadas materialSet, y la próxima lección usa algunas; la sección Material de la referencia las enumera todas.

local box = nodeNew()
nodeSetMesh(box, meshBox(2, 2, 2), paint)

Esta es la importante. Un nodo es un sitio en el mundo. Tiene una posición, una rotación y una escala, y por sí solo no dibuja absolutamente nada: es un punto al que se le pueden enganchar cosas. Todo en una escena 3D es un nodo, incluidas las luces y la cámara.

nodeNew crea uno vacío en el centro del mundo. nodeSetMesh le cuelga dos cosas: una malla, que es la forma, y el material, que es el aspecto de esa forma. meshBox(2, 2, 2) construye una caja de dos unidades de ancho, dos de alto y dos de fondo, y te devuelve un handle a ella igual que hizo materialNew.

Vale la pena compartir las mallas y los materiales. Un mismo handle de meshBox lo pueden usar cien nodos, y así es como se dibujan cien cajas sin que cueste caro. Hacer cien cajas separadas que resultan tener el mismo tamaño es la forma de principiante de volver lenta una escena.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 4, 6, 5)
nodeLookAt(sun, 0, 0, 0)

lightNew también crea un nodo — uno que lleva una luz — y te devuelve su handle de nodo, así que lo colocas y lo apuntas con las mismas llamadas que usas para todo lo demás. LIGHT_DIRECTIONAL es un sol: está tan lejos que solo cuenta la dirección en la que brilla, y por eso aquí la posición solo importa porque nodeLookAt la usa para calcular la dirección.

Quita esas tres líneas y vuelve a ejecutarlo. La caja se queda casi negra, porque la única luz que queda es la tenue luz ambiente. La lección veintitrés trata entera de la luz, y este es tu primer contacto con la decepción más común del 3D: el modelo se ha cargado bien, y la escena está negra porque no le da ninguna luz.

    nodeRotate(box, 0, 0.5, 0)

nodeRotate gira un nodo tantos grados alrededor de cada uno de sus propios tres ejes, además de la rotación que ya tuviera. Medio grado por fotograma, a unos sesenta fotogramas por segundo, es una vuelta cada doce segundos. Es el mismo truco de la lección dos: un cambio pequeño, aplicado en cada fotograma, se ve como movimiento.

Hacia dónde va cada eje

Tres números describen un sitio en la escena, y tienes que saber qué significa cada uno antes de poder poner nada en ningún sitio.

  • X va hacia la derecha. Una X mayor está más a la derecha.

  • Y va hacia arriba. Una Y mayor está más alta. El suelo de una escena suele ser y = 0.

  • Z va hacia ti, saliendo de la pantalla. Una Z mayor está más cerca de la cámara por defecto, y la Z negativa es la dirección hacia la que mira la cámara.

Esa última pilla a todo el mundo. Las cosas que quieres delante de la cámara van en Z negativa. No es una manía de Singe: glTF y Blender usan la misma disposición, así que un modelo exportado desde Blender llega mirando hacia donde Singe espera.

No te fíes de mi palabra en nada de esto. Añade esta línea después de la línea nodeSetMesh, guarda y mira:

nodeSetPosition(box, 3, 1, 0)

La caja salta hacia la derecha y hacia arriba. nodeSetPosition pone un nodo en un sitio exacto, y sustituye la posición que tuviera el nodo. Hay un nodeMove(node, dx, dy, dz) a juego que, en cambio, desplaza un nodo una cantidad, a lo largo de sus propios ejes, así que nodeMove(ship, 0, 0, -0.1) lleva una nave hacia delante apunte hacia donde apunte.

Prueba después nodeSetPosition(box, 0, 0, -20). La caja se encoge en la distancia, que es la Z negativa haciendo su trabajo. Luego prueba (0, 0, 20): la caja desaparece, porque la has puesto detrás de la cámara.

Dos llamadas más completan el conjunto.

nodeSetRotation(box, 0, 45, 0)
nodeSetScale(box, 0.5)

nodeSetRotation fija la rotación directamente en grados, mientras que nodeRotate le suma. Los tres números son alrededor de X, alrededor de Y y alrededor de Z: girar alrededor de Y es lo que hace una persona de pie en el suelo cuando se gira para mirar hacia otro lado, y es el que más vas a usar. nodeSetScale hace el nodo más grande o más pequeño, con un número para los tres ejes o con tres, uno para cada uno.

Quita esos dos experimentos antes de seguir. El resto de la lección parte del script tal como lo escribiste al principio.

Tu propia cámara

La vista por defecto es una cortesía, no una característica. Pon una cámara.

local camera = nodeNew()
nodeSetPosition(camera, 0, 2, 7)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)
cameraSetPerspective(60, 0.1, 100)

Ponlo debajo de la luz, antes de tu onOverlayUpdate, y ejecútalo. Ahora miras la caja un poco desde arriba, desde dos unidades más arriba y siete más atrás.

Una cámara es un nodo como cualquier otro. cameraSet le dice al motor desde qué nodo mirar, y la escena se dibuja desde la posición de ese nodo mirando a lo largo de la Z negativa del propio nodo. Apuntar una cámara a mano con nodeSetRotation sería un suplicio, así que nodeLookAt lo hace por ti: dale un punto del mundo y gira el nodo para que lo mire.

cameraSetPerspective es el objetivo. El primer número es el campo de visión en grados, de arriba abajo: cuánto mundo se mete en la altura de la ventana. Un número pequeño como 35 es un teleobjetivo que lo aplana todo; uno grande como 90 es un gran angular que hace que la habitación parezca enorme y que las esquinas se abomben. 60 es un valor por defecto cómodo. Los otros dos números son las distancias más cercana y más lejana que se dibujan, y lo que queda fuera de ese rango no se dibuja en absoluto.

Como la cámara es un nodo normal, todo lo que has aprendido sobre los nodos funciona con ella. Más adelante colgarás una cámara debajo de un coche en movimiento y tendrás una cámara de persecución gratis.

Girarla con las teclas de flecha

Leer el sistema de coordenadas en una página es una mala forma de aprenderlo. Mover algo dentro de él es una buena. Sustituye tu onOverlayUpdate por esto, y añade encima los dos callbacks nuevos y las cuatro variables.

local turnLeft  = false
local turnRight = false
local tiltUp    = false
local tiltDown  = false

Esas van al principio del todo del archivo, encima de todo lo demás.

function onInputPressed(what)
    if what == SWITCH_LEFT then
        turnLeft = true
    elseif what == SWITCH_RIGHT then
        turnRight = true
    elseif what == SWITCH_UP then
        tiltUp = true
    elseif what == SWITCH_DOWN then
        tiltDown = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        turnLeft = false
    elseif what == SWITCH_RIGHT then
        turnRight = false
    elseif what == SWITCH_UP then
        tiltUp = false
    elseif what == SWITCH_DOWN then
        tiltDown = false
    end
end


function onOverlayUpdate()
    if turnLeft then
        nodeRotate(box, 0, -1.5, 0)
    end
    if turnRight then
        nodeRotate(box, 0, 1.5, 0)
    end
    if tiltUp then
        nodeRotate(box, -1.5, 0, 0)
    end
    if tiltDown then
        nodeRotate(box, 1.5, 0, 0)
    end

    return OVERLAY_UPDATED
end

onInputPressed y onInputReleased son callbacks, como onOverlayUpdate: los escribes tú, y Singe los llama cuando un control se pulsa o se vuelve a soltar. Una pulsación llega una sola vez, no una y otra vez mientras se mantiene la tecla, y por eso cada uno pone una variable y el callback de dibujo hace el trabajo. Ese patrón — la pulsación pone un indicador, el fotograma lee el indicador — es como sacas «mientras se mantiene la tecla» de un motor que solo te cuenta los cambios.

Los nombres SWITCH_ vienen del propio motor, así que no hay que cargar nada para usarlos. Tampoco son teclas. Son lo que significa un control, y controls.cfg decide qué tecla, botón o dirección del stick produce cada uno. Hoy tus teclas de flecha envían SWITCH_LEFT y compañía; el stick de un mando envía lo mismo, y tu script nunca nota la diferencia.

Los signos están elegidos para que cada flecha mueva la cara que estás mirando en la dirección que has pulsado. Girar alrededor de Y un ángulo positivo lleva esa cara cercana hacia la derecha, así que la flecha izquierda pide uno negativo. Si te parece al revés, cambia los signos; son tus controles, no los del motor.

El overlay sigue encima

Añade estas líneas a onOverlayUpdate, encima del return.

    local pitch, yaw = nodeGetRotation(box)

    overlayClear()
    overlayPrint(2, 2, "Arrow keys turn the box.")
    overlayPrint(2, 4, "yaw " .. math.floor(yaw) .. "  pitch " .. math.floor(pitch))

Ahí no hay nada nuevo salvo aquello sobre lo que se imprime. overlayPrint es la llamada de la lección uno, que cuenta en celdas de carácter y no necesita ninguna fuente cargada, y está dibujando encima de una escena 3D sin que nadie le haya dicho nada.

Así es como está montado, y vale la pena decirlo claramente: Singe dibuja primero el vídeo, luego la escena 3D encima, y luego el overlay encima de eso. Tu puntuación, tus vidas, tu cronómetro, tu punto de mira y tus subtítulos son todo trabajo del overlay, exactamente igual que en la segunda parte. Un juego 3D pone su puntuación en la esquina con las mismas cinco líneas que usa un juego 2D.

nodeGetRotation devuelve tres números, los ángulos alrededor de X, de Y y de Z, y esta línea guarda los dos primeros en pitch y yaw. Son sus nombres habituales (en español, cabeceo y guiñada): pitch es el morro que sube y baja, y yaw es girar a izquierda y derecha. math.floor tira los decimales para que los números dejen de parpadear.

Mira el yaw mientras mantienes pulsada la flecha izquierda. Baja más allá de -180 y vuelve a aparecer por 180, porque los ángulos se dan como el giro más corto que te lleva ahí y no como un total acumulado. Si tu juego necesita saber cuántas vueltas ha dado el jugador, cuéntalas tú.

Pruébalo

  1. Mueve la cámara. Cambia nodeSetPosition(camera, 0, 2, 7) por (0, 8, 7), luego por (7, 2, 7) y luego por (0, 0.2, 7). Cada vez, el nodeLookAt mantiene la caja centrada, así que consigues otro ángulo de la misma escena cambiando un número.

  2. Cambia el objetivo. Prueba cameraSetPerspective(30, 0.1, 100), luego (90, 0.1, 100), sin mover la cámara. Un juego parece rápido con un campo de visión amplio y majestuoso con uno estrecho, y este es el regulador de ambiente más barato que existe.

  3. Pon una segunda caja. Copia las dos líneas que crearon la caja, cambia el nombre de la variable a mark y dale nodeSetPosition(mark, 3, 0, 0) y nodeSetScale(mark, 0.3). Ahora tienes una referencia con la que juzgar la primera caja. Muévela a (0, 3, 0) y luego a (0, 0, -3) y di en voz alta qué eje es cuál.

  4. Comparte la malla. En lugar de llamar dos veces a meshBox, guarda la primera en una variable y dale el mismo handle a los dos nodos. No se ve nada distinto. De eso se trata: una forma, dos sitios.

  5. Cuelga la cámara de la caja. Conserva la segunda caja del paso anterior, o no quedará nada con lo que comparar el movimiento. Luego busca nodeSetParent en la referencia y cuelga la cámara debajo de la primera caja. Mantén pulsada una tecla de flecha: la cámara acompaña la rotación de la caja, así que la caja se queda quieta y el resto de la escena pasa girando. Eso está a una línea de una vista en primera persona, y también es como descubres que una cámara de persecución quiere un padre y no aritmética.

Rómpelo a propósito

Escribe mal el nombre del material. Cambia la línea nodeSetMesh para que use pain en lugar de paint:

nodeSetMesh(box, meshBox(2, 2, 2), pain)

Singe se detiene antes de que arranque el juego e imprime algo así:

15:nodeSetMesh:  Argument 3 must be a number.

Este error tiene una forma distinta del de la lección uno, y viene del motor y no de Lua. El número del principio es la línea. El nombre que va detrás es la llamada que se ha quejado. La queja en sí es que la tercera cosa que le has dado no era un número.

Vale la pena seguir el motivo, porque explica toda una familia de errores. pain es una variable a la que nunca se le ha dado un valor, y en Lua una variable vacía es nil — el valor que significa «aquí no hay nada». Pasarle nil a una llamada que quiere un handle de material da exactamente esto. Cuando veas «must be a number» en una llamada del motor, busca en esa línea un nombre de variable mal escrito, o un handle que te olvidaste de guardar.

Lo que has aprendido

  • sceneEnable(true) enciende la capa 3D, y no se dibuja nada en 3D hasta que la llamas.

  • Un nodo es un sitio en el mundo con una posición, una rotación y una escala. Las mallas, las luces y las cámaras cuelgan todas de nodos.

  • Una malla es la forma y un material es el aspecto, y cualquier número de nodos puede compartir una de cada.

  • X es la derecha, Y es arriba, y la Z negativa es hacia donde mira la cámara.

  • nodeSetPosition y nodeSetRotation fijan un valor directamente; nodeMove y nodeRotate lo cambian en una cantidad.

  • Cualquier nodo puede ser la cámara. nodeLookAt la apunta y cameraSet la elige.

  • El campo de visión de cameraSetPerspective cambia cómo se siente la escena sin mover nada.

  • Una escena sin luz está negra, y es lo primero que hay que comprobar cuando no aparece nada.

  • El overlay sigue ahí, sigue encima y sigue siendo donde va tu puntuación.

La próxima vez

Como dragón, una caja deja bastante que desear. La próxima lección carga un modelo de verdad — uno que el motor ya desempaquetó en tu carpeta de trabajo, así que no hay nada que descargar ni nada que dibujar — lo coloca en el suelo y lo ilumina como es debido. Esa es la lección veintitrés.

Lección 23: Modelos y luz

La lección terminada

Las cajas y las esferas te llevarán lejos, pero tarde o temprano el juego quiere un dragón. Un modelo es una forma que ha construido otra persona en un programa de modelado: cientos de triángulos, sus propios colores y superficies, a veces un esqueleto y unos movimientos que lo acompañan, todo en un archivo. Cargarlo son dos líneas. Conseguir que parezca algo es cuestión de luz, y la luz es la mayor parte de esta lección.

No necesitas arte ni descargas. La primera vez que ejecutaste Singe, desempaquetó una carpeta llamada Singe en tu carpeta de trabajo, y dentro hay dos modelos: DragonModel.glb, el dragón de la pantalla de título del propio motor, y SingeText.glb, las letras que hay debajo. Esta lección usa el dragón.

La escena a su alrededor

Un modelo necesita un sitio donde apoyarse. Crea una carpeta, crea dentro dragon.singe y empieza con un suelo y una cámara. Si has hecho la lección veintidós, nada de esto es nuevo; si no, es una escena encendida, una losa plana sobre la que apoyarse y un punto desde el que mirar.

sceneEnable(true)
sceneSetBackground(10, 12, 20)
sceneSetAmbient(28, 30, 38)

local stone = materialNew()
materialSetColor(stone, 105, 105, 115)
materialSetRoughness(stone, 0.9)

local floor = nodeNew()
nodeSetMesh(floor, meshBox(24, 0.4, 24), stone)
nodeSetPosition(floor, 0, -0.2, 0)

local camera = nodeNew()
nodeSetPosition(camera, 0, 2.6, 9)
nodeLookAt(camera, 0, 1.7, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 200)


function onOverlayUpdate()
    return OVERLAY_UPDATED
end

Ejecútalo con Singe -R dragon. Una losa gris, vista un poco desde arriba, sobre un fondo azul oscuro. La losa mide veinticuatro unidades de lado y algo menos de media unidad de grosor, y colocarla en y = -0.2 pone su cara de arriba exactamente en y = 0, lo que hace que sea fácil pensar en todo lo que coloques después: el suelo es cero.

Cargar el dragón

Dos líneas.

local dragonModel = modelLoad("Singe/DragonModel.glb")
local dragon      = modelInstance(dragonModel)

Ponlas después del suelo y guarda. Aparece un dragón, y es muchísimo más grande de lo que cabe en la imagen — estás mirando la mitad de su cuerpo.

Qué acaba de pasar

Las dos líneas hacen trabajos distintos, y la diferencia importa.

modelLoad lee el archivo, le pasa las formas y sus superficies a la tarjeta gráfica y lo deja todo listo. Es la llamada lenta. Hazla una vez, cuando empieza el juego, y nunca en mitad de la partida.

modelInstance coloca una copia en la escena y te devuelve un nodo — un nodo normal, del mismo tipo que te da nodeNew, que colocas, giras, escalas y borras con las llamadas que ya conoces. Instanciar es la llamada barata. Carga un árbol, instáncialo cuarenta veces y tendrás un bosque, con una sola copia de las formas en la tarjeta gráfica y cuarenta sitios donde se dibujan.

Lo que viene con el modelo es todo lo que había en el archivo: las formas, las superficies y sus colores, cómo están colocadas las partes, el esqueleto si lo hay y los movimientos si los hay. No construyes materiales para un modelo cargado; ya ha traído los suyos.

La escala, y lo primero que sale mal

El dragón mide unas siete unidades y media de alto. Tu cámara está nueve unidades más atrás. Por eso llena la ventana.

nodeSetScale(dragon, 0.5)

Añade eso debajo de la línea modelInstance. Ahora mide menos de cuatro unidades de alto, se apoya en el suelo y cabe en el plano.

Esto no es un detalle; es el primer problema más común con un modelo, y tiene dos caras. Un modelo construido en centímetros llega cien veces más grande de la cuenta y ves una superficie enorme llenando la pantalla, lo que suele parecer «mi escena está rota» más que «estoy dentro del cuello del dragón». Un modelo construido en alguna otra unidad llega tan pequeño que es un punto, o invisible contra el fondo, y das por hecho que el archivo no se ha cargado.

El arreglo es siempre el mismo: una escala en el nodo de la instancia. No en las partes, ni en el programa de modelado si puedes evitarlo, sino un único nodeSetScale en el nodo que te ha dado modelInstance, elegido probando un número y mirando. 0.01 y 100 son respuestas perfectamente normales las dos.

Cuando no sepas lo grande que es algo, búscate una regla. Pon una caja de una unidad a su lado:

local ruler = nodeNew()
nodeSetMesh(ruler, meshBox(1, 1, 1), stone)
nodeSetPosition(ruler, 3, 0.5, 0)

Un objeto del tamaño de un cajón al lado del modelo te dice de un vistazo si el modelo es un dragón o una montaña. Quita la regla cuando termines.

Mientras lo colocas, gíralo para que te mire:

nodeSetRotation(dragon, 0, -60, 0)

El dragón se modeló mirando a lo largo de la X positiva, que es hacia la derecha, así que empieza de perfil. Girarlo alrededor de Y lo vuelve hacia la cámara. El «frente» de un modelo es la dirección que haya elegido quien lo construyó, y para averiguarlo hay que girarlo y mirar.

Luz

Ejecuta lo que tienes ahora. El dragón está ahí, y es deprimente: una forma plana y apagada, sin reflejos y sin sombra. Eso es porque la única luz de tu escena es la ambiente, el débil resplandor que llega de todas partes y que fija sceneSetAmbient.

Esta es la decepción más común del 3D, y le pasa a todo el mundo: el modelo se ha cargado perfectamente y la escena está negra, o casi, porque no le da ninguna luz. Antes de sospechar del archivo, pon una luz.

Hay tres tipos, y cada una es un nodo, así que las colocas y las apuntas con nodeSetPosition y nodeLookAt como cualquier otra cosa.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, -6, 9, 7)
nodeLookAt(sun, 0, 1.5, 0)
lightSetColor(sun, 255, 244, 224)
lightSetIntensity(sun, 1.8)
lightSetShadow(sun, true)

LIGHT_DIRECTIONAL es un sol. Se trata como si estuviera infinitamente lejos, así que solo cuenta la dirección en la que brilla y todo lo que hay en la escena recibe la misma cantidad. Su posición está ahí para que nodeLookAt la apunte. Esta es la luz que le da a una escena su forma principal, y la mayoría de las escenas quieren exactamente una.

lightSetIntensity es el brillo. En una luz direccional, 1 lleva hasta el blanco una superficie blanca que la tiene de frente, así que 1.8 es un día luminoso. lightSetColor la tiñe: un blanco un poco cálido para el sol, un azul frío para la luz de luna, y la sección Luz de la referencia para el resto.

lightSetShadow(sun, true) es lo que hace que el dragón se apoye en el suelo en lugar de flotar encima. Las sombras están desactivadas por defecto porque cada luz que proyecta sombras cuesta otra pasada por toda la escena en cada fotograma. Actívala en la única luz que importa y déjala desactivada en las demás; una máquina pequeña te lo agradecerá.

local torch = lightNew(LIGHT_POINT)
nodeSetPosition(torch, 3.5, 1.2, 3.0)
lightSetColor(torch, 255, 150, 70)
lightSetIntensity(torch, 14)
lightSetRange(torch, 12)

LIGHT_POINT es una bombilla. Está en un sitio, brilla en todas las direcciones y se debilita con la distancia. Ese debilitamiento es la razón de que el número sea 14 y no 1: la intensidad de una luz puntual es su brillo en la propia luz, y para cuando ha recorrido unas cuantas unidades no queda mucho. Una bombilla que ilumina una habitación suele querer algo de unas decenas. Si una luz puntual parece no hacer nada, casi siempre es por eso.

lightSetRange dice hasta dónde llega antes de apagarse del todo, lo que evita que una lámpara de una habitación ilumine débilmente la siguiente, y no cuesta nada ponerlo.

El tercer tipo es LIGHT_SPOT, un cono que apunta a lo largo de la Z negativa del propio nodo, con lightSetCone para el ángulo del centro brillante y del borde suave: una linterna, un faro, un reflector. Pueden brillar hasta ocho luces a la vez, que es más de lo que necesitan la mayoría de las escenas. Si quieres más, lo que quieres es menos.

Ejecútalo ahora. Un sol casi blanco desde la izquierda, un resplandor naranja cálido desde la derecha, una sombra en la losa y un dragón con una parte de delante y otra de detrás.

Materiales, al nivel que necesitas hoy

El dragón ha traído sus propios materiales, y son tres: un metal oscuro, un metal champán más claro y un cristal pálido en el que se ve un poco hacia dentro. La mayoría de sus partes están hechas de más de uno. No tienes que tocar nada de eso, y casi siempre no deberías.

Cuando sí quieras cambiar el aspecto de una parte de un modelo, creas un material como en la lección veintidós y se lo pones a la parte:

local red = materialNew()
materialSetColor(red, 220, 50, 40)
materialSetRoughness(red, 0.4)
nodeSetMaterial(nodeFind("crest", dragon), red)

nodeFind(name, root) busca en una instancia de modelo una parte por el nombre que tenía en el archivo y te devuelve su nodo, o nil cuando no hay ningún nombre así. Así es como llegas al interior de un modelo: una torreta, una rueda, una mano de la que colgar una antorcha, o la cresta del dragón.

La cresta es una sola pieza de un solo material, así que su nodo lleva la forma en sí y la línea de arriba la vuelve a pintar. Una parte construida con varios materiales se guarda como un nodo con un hijo por pieza, y ponerle un material al padre no cambia nada que se pueda ver. Cuando un nodeSetMaterial parece no hacer nada, es por eso, y nodeGetChildren te enseñará lo que hay debajo.

Cuatro números describen la mayoría de las superficies. El color, con materialSetColor. materialSetRoughness, de 0 para un espejo a 1 para la tiza. materialSetMetallic, que es 0 para casi todo — pintura, madera, plástico, piel — y 1 para el metal de verdad, y los valores intermedios sirven de poco. Y materialSetEmissive, que hace que una superficie brille con su propio color, para pantallas, lámparas y hierro al rojo, sin iluminar nada a su alrededor.

Una cosa que debes saber del metal: una superficie metálica te muestra sus reflejos en lugar de un color propio, así que en una escena sin nada que reflejar se ve oscura y apagada. Por eso el metal oscuro del dragón necesita el sol para cobrar vida. El arreglo de verdad es un cielo (sceneSetSky), que envuelve la escena en un panorama que a la vez se ve detrás de todo y lo ilumina; la sección «El aspecto del fotograma» de la referencia lo explica.

El movimiento que trae el modelo

Muchos modelos llevan animaciones: un paseo, una carrera, una pose de reposo, una puerta que se abre. Se guardan en el archivo, y reproducir una es una sola llamada sobre el nodo raíz de la instancia.

animationPlay(dragon, "Walk", true)

El segundo argumento es el nombre del clip tal como lo guarda el archivo, o su número. true significa repetirlo para siempre. Dos números opcionales más fijan la velocidad y el fundido cruzado: animationPlay(hero, "Run", true, 1.2, 0.4) reproduce la carrera una quinta parte más rápido y pasa a ella fundiéndose durante cuatro décimas de segundo, así que el paseo se convierte en carrera sin un salto brusco. animationStop, animationPause y animationIsPlaying hacen lo que dicen sus nombres.

No puedes ejecutar esa línea todavía, y esta es la razón sincera: el dragón de tu carpeta Singe no tiene ninguna animación. Es un modelo, no una actuación. Pedir un clip que no existe detiene el juego con un error, así que nunca des nada por hecho — pregunta:

local clips = modelGetAnimations(dragonModel)

if #clips > 0 then
    animationPlay(dragon, 1, true)
else
    debugPrint("DragonModel.glb carries no animation clips.  The wings are turned by hand.")
end

modelGetAnimations te devuelve una tabla con los nombres de los clips del archivo, en orden, así que clips[1] es el primero y #clips es cuántos hay — las llamadas de tablas de la lección seis, sobre una tabla que ha llenado el motor. Ejecútalo y mira la consola: aparece el mensaje, porque esa cuenta es cero.

Coge la costumbre de hacer esa comprobación con cualquier modelo que no hayas hecho tú. Cuesta tres líneas y convierte «el juego murió al arrancar» en una frase en el registro.

Mover las partes tú mismo

Un modelo sin animaciones no es una estatua. Sus partes son nodos, y los nodos giran.

local wingLeft  = nodeFind("wingL", dragon)
local wingRight = nodeFind("wingR", dragon)
function onOverlayUpdate()
    local flap = math.sin(singeGetTicks() / 260) * 22

    nodeSetRotation(wingLeft, flap, 0, 0)
    nodeSetRotation(wingRight, -flap, 0, 0)
    nodeRotate(dragon, 0, 0.25, 0)

    overlayClear()
    overlayPrint(2, 2, "Singe/DragonModel.glb")
    overlayPrint(2, 4, "animation clips in the file: " .. #clips)
    return OVERLAY_UPDATED
end

Guárdalo. Las alas baten, el dragón gira despacio sobre sí mismo, y la sombra del suelo bate con ellas.

singeGetTicks es el número de milisegundos desde que arrancó el motor, así que sube sin parar para siempre. math.sin toma ese número que sube y devuelve un valor que se desliza suavemente de -1 a 1 y vuelta, un aleteo completo más o menos cada segundo y medio con este divisor. Multiplicar por 22 lo convierte en un ángulo de veintidós grados hacia cada lado. Dividir por un número mayor hace el aleteo más lento; multiplicar por un número mayor lo hace más amplio. Esa línea es la animación más barata que existe, y vale la pena llevarla siempre en el bolsillo.

Las alas giran alrededor de su propio eje X, y giran alrededor del hombro y no del centro del animal, porque quien construyó el archivo puso el nodo de cada parte donde va la articulación. Un modelo que no se construyó así hará girar sus partes alrededor del centro del modelo, y el arreglo es mover el nodo de la parte, cosa que explica la sección Nodo de la referencia.

Fíjate en que el giro de todo el dragón no interfiere con el giro de las alas. Las partes cuelgan de la raíz de la instancia, así que girar la raíz se lo lleva todo consigo, y la rotación propia de cada ala va encima de eso. Ese montaje — una cosa dentro de una cosa dentro de una cosa, cada una moviéndose en el mundo de su padre — es para lo que sirve un árbol de escena.

Tus propios modelos

Cuando hagas los tuyos, expórtalos desde Blender — o Maya, o 3ds Max, o cualquier otro programa moderno — como glTF 2.0 binario, que es un archivo .glb. Es la opción por defecto de Blender y es el único formato de modelo que lee Singe.

La única regla es que el archivo tiene que ser autosuficiente: las formas, las imágenes que llevan encima y los movimientos, todo dentro del único .glb. Un archivo que hace referencia a un .bin o a un .png que está a su lado se rechaza, con un mensaje que nombra lo que quería. El exportador de Blender hace lo correcto con sus ajustes por defecto.

No todo lo que puedes construir sobrevive al viaje. La sección «Modelos y animación» de la referencia, en el capítulo «Escenas 3D», es la lista: lo que se lee, lo que se ignora sin avisar y los límites (un esqueleto puede tener hasta ciento veintiocho articulaciones, por ejemplo). Léela una vez antes de pasarte un fin de semana con un modelo, no después.

Pruébalo

  1. Apaga las luces. Comenta todo el bloque del sun poniendo -- al principio de cada línea, y ejecútalo. Luego haz lo mismo con sceneSetAmbient. Recuerda cómo se ve, porque un día te pasará sin querer.

  2. Mueve el sol. Cambia nodeLookAt(sun, 0, 1.5, 0) por nodeLookAt(sun, 0, 20, 0) para que el sol apunte por encima de la cabeza del dragón. Mira cómo se van la sombra y los reflejos. Apuntar una luz no es decoración.

  3. Calienta la antorcha. Sube la intensidad de la luz puntual de 14 a 60 y baja su alcance a 4. Luego muévela a (0, 6, 0), encima del dragón. Una luz puntual es una bombilla, y tú eliges dónde cuelga la bombilla.

  4. Instáncialo dos veces. Llama a modelInstance(dragonModel) una segunda vez, guárdalo en otra variable, escálalo y ponlo en (-4, 0, -3). Una carga, dos dragones. Luego prueba en cambio a cargar el modelo dos veces y entiende por qué no deberías.

  5. Busca otra parte. Las partes del dragón se llaman head, jaw, neck, tail, body, crest, hornL, hornR, wingL, wingR, foreLegL, foreLegR, hindLegL y hindLegR. Haz que la cola se balancee con su propio math.sin a una velocidad distinta de la de las alas. Luego prueba nodeFind("wings", dragon) y mira lo que hace un nombre equivocado cuando le pasas el nil directamente a nodeSetRotation.

Rómpelo a propósito

Cambia el nombre del archivo a Singe/Dragonmodel.glb — una sola mayúscula de diferencia — y ejecútalo. Singe se detiene antes de que arranque el juego:

13:modelLoad:  Unable to read Singe/Dragonmodel.glb.

La línea, la llamada y la queja, en ese orden. «Unable to read» significa que el motor ha buscado y no ha encontrado nada, y eso casi siempre es una de tres cosas: el nombre está mal escrito, las mayúsculas están mal o el archivo no está donde dijiste. En Windows se te habrían perdonado las mayúsculas, y entonces tu juego fallaría a todo el que use Linux, que es un fallo peor que este. Escribe los nombres exactamente.

El mismo mensaje con un nombre de archivo correcto significa que el archivo no está donde lo buscó el motor. La carpeta Singe se crea en la carpeta desde la que ejecutas el motor, así que si arrancaste Singe desde otro sitio, Singe/DragonModel.glb también apunta a otro sitio.

Lo que has aprendido

  • modelLoad lee un .glb una vez; modelInstance coloca copias de él tantas veces como quieras.

  • La raíz de una instancia es un nodo normal: colócala, gírala, escálala y bórrala como cualquier otro.

  • Un modelo trae consigo sus propias formas y materiales.

  • Un modelo llega al tamaño que usó su autor, y por eso un nodeSetScale en la instancia forma parte de colocarlo.

  • Una escena sin luz está negra o casi, y es lo primero que hay que comprobar cuando un modelo se ve mal.

  • Una luz direccional es un sol, una luz puntual es una bombilla que se debilita con la distancia y necesita una intensidad mucho mayor, y un foco es un cono.

  • Las sombras están desactivadas hasta que lightSetShadow las activa, y cada una tiene su coste.

  • nodeFind llega a una parte de un modelo por su nombre en el archivo.

  • modelGetAnimations dice qué puede reproducir un modelo, y pedir un clip que no existe es un error.

  • Un modelo sin animaciones se puede mover igualmente, parte a parte.

La próxima vez

Todo lo que hay en esta escena se mueve porque tú se lo has dicho, fotograma a fotograma. La próxima lección le pasa ese trabajo a un motor de física: cajas que caen, ruedan, se apilan y se tiran unas a otras sin que escribas ni una línea de aritmética — y la pregunta más difícil de cuándo deberías dejarle. Esa es la lección veinticuatro.

Lección 24: Física

La lección terminada

Hasta ahora, todo lo que se movía en tus juegos se movía porque tú hacías las cuentas. Un número subía de dos en dos en cada fotograma; si se pasaba de un borde, le dabas la vuelta. Es la forma honrada de hacer que un juego se mueva, y la mayoría de los juegos están hechos de eso.

Esta lección le pasa las cuentas a otro. Un motor de física simula el mundo — la gravedad, las caídas, los deslizamientos, las pilas, los rebotes, el rodar y las cosas que chocan entre sí — y mueve tus nodos por ti. Al final tendrás una bandeja de cajas y un cañón que las tira. La última sección trata de cuándo no hacer nada de esto, y es la parte que hay que leer dos veces.

Lo que hace y lo que no

Dale un cuerpo a un nodo y la simulación se hace cargo de él. A partir de entonces cae por la gravedad, aterriza sobre lo que tenga debajo, se vuelca cuando le dan descentrado, descansa en una pila, se desliza hasta pararse, y el nodo va allí donde lo ponga la simulación. Tú dejas de fijar su posición. Ese es el trato: entregas la posición y la rotación de ese nodo, y a cambio obtienes un comportamiento que no has tenido que escribir.

Lo que no hace es nada que tenga que ver con tu juego. No sabe qué es una puntuación, ni que la caja roja es la que da puntos, ni que caerse por el borde cuesta una vida. No anima a un personaje que camina, no sabe cómo debería sentirse un salto y no hará que un objeto se mueva de una forma que puedas predecir con exactitud. La física es una máquina de producir líos verosímiles.

Las unidades son metros, kilogramos y segundos. La gravedad es 0, -9.81, 0 salvo que digas otra cosa, que es la de la Tierra, hacia abajo, en metros por segundo al cuadrado. Una caja de una unidad de ancho mide un metro de ancho, y cae como tal. Si tu escena está construida a otra escala, todo parecerá caer a través de almíbar o dentro de unos dibujos animados, y el arreglo es construir en metros.

Un suelo y una caja

Crea una carpeta, crea dentro crates.singe y escribe esto. Es una escena, una losa, una caja encima de la losa y tres líneas de física.

sceneEnable(true)
sceneSetBackground(16, 18, 26)
sceneSetAmbient(40, 42, 50)

local stone = materialNew()
materialSetColor(stone, 110, 110, 120)
materialSetRoughness(stone, 0.9)

local wood = materialNew()
materialSetColor(wood, 190, 140, 80)
materialSetRoughness(wood, 0.8)

local floor = nodeNew()
nodeSetMesh(floor, meshBox(16, 0.4, 16), stone)
nodeSetPosition(floor, 0, -0.2, 0)
bodyNew(floor, BODY_STATIC, SHAPE_BOX, 16, 0.4, 16)

local crate = nodeNew()
nodeSetMesh(crate, meshBox(0.8, 0.8, 0.8), wood)
nodeSetPosition(crate, 0.3, 4, 0)
nodeSetRotation(crate, 20, 0, 15)
bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.8, 0.8, 0.8)
bodySetMass(crate, 4)

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, -5, 9, 6)
nodeLookAt(sun, 0, 0, 0)
lightSetIntensity(sun, 1.7)
lightSetShadow(sun, true)

local camera = nodeNew()
nodeSetPosition(camera, 0, 4, 11)
nodeLookAt(camera, 0, 1, 0)
cameraSet(camera)


function onOverlayUpdate()
    return OVERLAY_UPDATED
end

Ejecútalo con Singe -R crates. La caja cae desde cuatro metros de altura, aterriza sobre una esquina porque la inclinaste, se balancea hasta quedar sobre una cara y se para. Pulsa F5 para ejecutarlo otra vez y volver a mirarlo.

Nada de lo que hay en onOverlayUpdate mueve nada. Las dos llamadas a bodyNew lo han hecho todo.

Qué acaba de pasar

bodyNew(floor, BODY_STATIC, SHAPE_BOX, 16, 0.4, 16)

bodyNew le da un cuerpo a un nodo. Recibe el nodo, qué tipo de cuerpo es, qué forma debe usar la simulación para él y las medidas de esa forma.

Hay tres tipos, y elegir el correcto es la mayor parte de la habilidad.

  • BODY_STATIC no se mueve nunca. Se coloca donde está el nodo cuando creas el cuerpo, y ahí se queda para siempre. Suelos, paredes, el terreno, el armario, el nivel. Mover su nodo después no mueve el cuerpo, lo cual es una trampa que vale la pena recordar: estático significa estático.

  • BODY_DYNAMIC lo mueve la simulación. Cae, rebota, se desliza, recibe empujones y arrastra a su nodo consigo. Esto es una caja, un barril, una pelota, un trozo de escombro.

  • BODY_KINEMATIC va donde tú pones su nodo, y aparta de su camino a los cuerpos dinámicos sin que nada lo empuje nunca a él. Una plataforma móvil, una pala, una puerta sobre un raíl, el puño de un personaje que lanza un golpe. Es el puente entre tus cuentas y la simulación: tú lo manejas a él, y él los maneja a ellos.

La forma no es la malla. Es un sustituto aproximado que usa la simulación porque puede responder preguntas sobre una caja muchísimo más rápido que sobre novecientos triángulos. SHAPE_BOX recibe un ancho, un alto y un fondo; SHAPE_SPHERE recibe un radio; SHAPE_CAPSULE y SHAPE_CYLINDER reciben un radio y una altura. Está SHAPE_HULL, que envuelve como un film retráctil la malla que haya bajo el nodo — la respuesta habitual para un modelo — y SHAPE_MESH, los triángulos exactos, que puede usar el decorado estático y no puede usar un objeto que cae.

Las medidas te toca acertarlas a ti. Nada comprueba que el cuerpo que has descrito coincida con la malla que has dibujado, y una caja dibujada a 0.8 con un cuerpo creado a 2 flotará por encima del suelo y tirará cosas a distancia. Cuando algo se comporta como si tuviera otro tamaño, es que lo tiene.

bodySetMass(crate, 4)

La masa de un cuerpo dinámico sale de su forma con la densidad del agua, lo que hace que las cosas pesen mucho más de lo que esperas: una caja del tamaño de una puerta pesa unos ciento cuarenta kilos, y nada que le puedas lanzar la moverá. Fija la masa de todo lo que deba parecer ligero. Cuatro kilos es una caja que podrías levantar.

La masa importa porque las fuerzas se reparten según ella. El mismo empujón mueve más lejos una cosa ligera, y un impulso de masa por velocidad es lo que hace falta para poner algo en movimiento a esa velocidad. Ajusta primero la masa y después las fuerzas, o acabarás persiguiéndote la cola.

Hacer que las cosas se muevan

Tres llamadas empujan un cuerpo dinámico, y no son intercambiables.

bodySetVelocity(node, x, y, z) dice «ahora vas a esta velocidad», y sustituye lo que estuviera haciendo. Esto es un saque, un lanzamiento, algo que aparece ya con algo de velocidad.

bodyApplyImpulse(node, ix, iy, iz) es un golpe: una patada, una explosión, un bate que se encuentra con una pelota. Se suma a lo que el cuerpo ya estaba haciendo. Dale un punto del mundo como tres números más y golpea ahí en lugar de en el centro, así que una caja golpeada cerca de arriba se vuelca en lugar de deslizarse.

bodyApplyForce(node, fx, fy, fz) es un empujón que dura: un cohete, un ventilador, una cinta transportadora. Una fuerza aplicada durante un fotograma casi no hace nada, lo que sorprende a quien esperaba un impulso.

La gravedad en sí es physicsSetGravity(x, y, z) y vale para todo el mundo. La luna es physicsSetGravity(0, -1.62, 0), el espacio es todo ceros, y un juego con la gravedad de lado está a una línea de distancia.

Dos ajustes más completan cómo se siente un objeto. bodySetBounce(node, amount) va de 0, que se para en seco, a 1, que vuelve con todo lo que traía; por defecto es un 0.1 que casi ni se nota. bodySetFriction(node, amount) es 0 para el hielo y 0.5 por defecto. Los dos se combinan entre las dos cosas que se tocan, así que un suelo helado necesita el número bajo en el suelo, no en todo lo que camina por encima.

Saber cuándo se tocan las cosas

function onCollision(nodeA, nodeB, x, y, z, speed)
    if speed > 4 then
        knocks = knocks + 1
    end
end

Ahí, knocks es una variable tuya, que espera al principio del archivo con local knocks = 0, y el juguete de más abajo la imprime.

onCollision es un callback, como onOverlayUpdate: lo escribes tú y el motor lo llama. Llega una vez por cada contacto nuevo — dos cuerpos que siguen tocándose no vuelven a avisar — con los dos nodos, el punto del mundo donde se encontraron y lo rápido que se encontraron. La velocidad es lo que permite que un golpecito y un choque suenen distinto, y es la razón de que la comprobación de arriba ignore cómo se asienta suavemente una pila.

La otra mitad de la pareja es onTrigger. Convierte un cuerpo en activador con bodySetTrigger(node, true) y deja de empujar cosas: se convierte en una zona que informa de lo que entra y sale de ella a través de onTrigger(trigger, other, entered). Una línea de meta, una puerta, un foso, un objeto que recoger. Es el descendiente en 3D de las comprobaciones de colisión de la lección once, y para cualquier cosa del tipo «¿ha llegado aquí el jugador?» es la llamada que quieres en lugar de un cuerpo sólido.

El juguete

Ahora todo junto. Parte del script de arriba y conviértelo en esto: una bandeja con cuatro paredes, seis cajas en pirámide y una bola de acero que puedes apuntar y disparar. Todas las piezas son cosas que ya conoces.

Todo lo que recuerda el código nuevo va al principio del archivo, encima de la escena:

local crates     = {}
local balls      = {}
local aimX       = 0
local aimLeft    = false
local aimRight   = false
local knocks     = 0
local showShapes = false

Con los materiales van dos handles compartidos más: un metal pulido para la bola y para el marcador de puntería, y una malla de caja para las seis cajas.

local steel = materialNew()
materialSetColor(steel, 200, 205, 215)
materialSetMetallic(steel, 1)
materialSetRoughness(steel, 0.25)

local crateMesh = meshBox(0.8, 0.8, 0.8)

Las paredes de la bandeja son cuatro cajas estáticas, creadas en un bucle a partir de una tabla de posiciones, que es la lección seis haciendo un trabajo honrado:

local wallMesh = meshBox(16, 1, 0.4)

for _, side in ipairs({ { 0, -8, 0 }, { 0, 8, 0 }, { -8, 0, 90 }, { 8, 0, 90 } }) do
    local wall = nodeNew()
    nodeSetMesh(wall, wallMesh, stone)
    nodeSetPosition(wall, side[1], 0.5, side[2])
    nodeSetRotation(wall, 0, side[3], 0)
    bodyNew(wall, BODY_STATIC, SHAPE_BOX, 16, 1, 0.4)
end

Cada elemento es una X, una Z y un giro alrededor de Y. Dos paredes van de lado a lado, al fondo y delante; dos están giradas noventa grados para formar los laterales. Una malla sirve para las cuatro, y el cuerpo se crea después de colocar y girar el nodo, porque un cuerpo estático toma la posición y la rotación del nodo en el momento en que se crea.

Las cajas salen de una función, para que seis cajas sean seis líneas:

local function crateAt(x, y)
    local crate = nodeNew()

    nodeSetMesh(crate, crateMesh, wood)
    nodeSetPosition(crate, x, y, -2)
    bodyNew(crate, BODY_DYNAMIC, SHAPE_BOX, 0.8, 0.8, 0.8)
    bodySetMass(crate, 4)
    crates[#crates + 1] = crate
end

Guarda cada caja que crea en la tabla crates, que es como el callback de dibujo puede hacerles una pregunta a todas más tarde. Seis llamadas construyen la pirámide, tres en el suelo, dos encima de esas y una arriba del todo:

crateAt(-0.9, 0.4)
crateAt(0, 0.4)
crateAt(0.9, 0.4)
crateAt(-0.45, 1.25)
crateAt(0.45, 1.25)
crateAt(0, 2.1)

Las filas de arriba quedan a un dedo de las de abajo y caen a su sitio en cuanto empieza el juego. Dejar un hueco pequeño es más fácil que apilar con exactitud, y es más amable con la simulación que darle un montón que ya está apretado.

Disparar crea una bola nueva cada vez:

local function fire()
    local ball = nodeNew()

    nodeSetMesh(ball, meshSphere(0.35, 24), steel)
    nodeSetPosition(ball, aimX, 1.2, 6)
    bodyNew(ball, BODY_DYNAMIC, SHAPE_SPHERE, 0.35)
    bodySetMass(ball, 3)
    bodySetBounce(ball, 0.3)
    bodySetVelocity(ball, 0, 2, -14)
    balls[#balls + 1] = ball
    if #balls > 5 then
        nodeDelete(balls[1])
        table.remove(balls, 1)
    end
end

Fíjate en el orden. El nodo se crea, recibe una forma que dibujar y se coloca, y solo entonces recibe un cuerpo. Un cuerpo dinámico empieza donde está su nodo, y a partir de ahí el tráfico va en el otro sentido: el cuerpo mueve el nodo. Fijar tú después la posición de un nodo dinámico es pelearte con la simulación, y la simulación gana. Cuando haya que mover algo, dale una velocidad, golpéalo con un impulso o haz lo que hace esto — crea uno nuevo y deja ir el viejo.

Dejar ir el viejo es nodeDelete, que libera el nodo, todo lo que cuelga de él y el cuerpo que iba montado en él. Sin esas tres líneas, cada disparo se quedaría en el mundo para siempre, y unos cientos de bolas después la simulación estaría trabajando muchísimo en cosas que nadie puede ver. Limpiar forma parte de usar la física.

Los controles y lo que se muestra en pantalla son el resto:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        fire()
    elseif what == SWITCH_BUTTON3 then
        showShapes = not showShapes
        if showShapes then
            physicsSetDebug(DEBUG_SHAPES + DEBUG_CONTACTS)
        else
            physicsSetDebug(DEBUG_NONE)
        end
    elseif what == SWITCH_LEFT then
        aimLeft = true
    elseif what == SWITCH_RIGHT then
        aimRight = true
    end
end

La barra espaciadora dispara, Mayús activa y desactiva la vista de la física, y las flechas, mantenidas pulsadas, desplazan el punto de lanzamiento. Una placa plana de metal sin ningún cuerpo, que se mueve en cada fotograma a aimX, muestra de dónde saldrá la siguiente bola. El script completo, con el callback de soltar y el resto de la preparación, es 24-physics.singe en la carpeta learn.

physicsSetDebug es la llamada más útil de esta lección. Dibuja lo que la simulación tiene de verdad — las formas reales en alámbrico, y una cruz roja allí donde dos cuerpos se han tocado en este paso — por encima de tu escena. La primera vez que una caja flote a un palmo del suelo, o lo atraviese, o tire algo desde dos metros de distancia, activa esto y la respuesta estará en la pantalla. Añade DEBUG_STATIC para ver también el suelo y las paredes. No cuesta nada mientras está desactivado.

Por último, la cuenta:

function onOverlayUpdate()
    local over    = 0
    local settled = true

    if aimLeft then
        aimX = math.max(aimX - 0.08, -5)
    end
    if aimRight then
        aimX = math.min(aimX + 0.08, 5)
    end
    nodeSetPosition(marker, aimX, 0.05, 6)

    for _, crate in ipairs(crates) do
        local pitch, _, roll = nodeGetRotation(crate)

        if math.abs(pitch) > 30 or math.abs(roll) > 30 then
            over = over + 1
        end
        if not bodyIsResting(crate) then
            settled = false
        end
    end

    overlayClear()
    overlayPrint(2, 2, "Arrows aim.  Space fires.  Shift shows the shapes.")
    overlayPrint(2, 4, "knocked over " .. over .. " of " .. #crates .. "   hard hits " .. knocks)
    if settled then
        overlayPrint(2, 6, "everything has settled")
    end
    return OVERLAY_UPDATED
end

Una caja cuenta como derribada cuando se inclina más de treinta grados, que es una regla del juego escrita en una línea de aritmética por encima de lo que haya hecho la simulación. nodeGetRotation da tres ángulos y aquí se quieren el primero y el tercero, así que el del medio se recoge en una variable llamada _. Ese guion bajo es un nombre normal y corriente sin nada de especial, que se usa por convención para decir «este lo ignoro».

bodyIsResting dice si la simulación ha dormido un cuerpo porque ha dejado de moverse. Así es como sabes que un tiro ha terminado: ni un temporizador ni una suposición, sino todas las cajas dormidas. Un juego de bolos puntúa su tirada justo ahí.

Cuándo no usarla

La física es la herramienta más tentadora de cualquier motor y la que más fines de semana hace perder. Hay tres cosas ciertas sobre ella, y ninguna es culpa del motor.

Es cara. Cada cuerpo dinámico es trabajo en cada paso, sesenta veces por segundo, lo esté mirando alguien o no. Cuarenta cajas está bien. Cuatro mil no, y en una máquina pequeña cuatrocientas tampoco.

Es impredecible. Ejecuta tu juguete dos veces y las cajas caen de forma distinta. Eso es lo que hace que parezca vivo, y también es la razón de que un juego no pueda confiar en ella para nada que tenga que salir igual cada vez. Una puerta que tiene que abrirse, una plataforma que tiene que llegar, un salto que el jugador tiene que poder hacer: eso es aritmética, o una interpolación, o un cuerpo cinemático sobre un recorrido que has escrito tú. Nunca dejes algo que el jugador tiene que hacer en manos de una simulación que puede dejarlo caer detrás de una caja.

Es difícil de ajustar. La masa, la fricción, el rebote, la forma y el tamaño tiran unos de otros, y «se siente raro» rara vez tiene una sola causa. Cada hora que pasas consiguiendo que una caja con física se sienta bien es una hora que no has pasado con el juego.

Así que recurre a ella cuando el lío es lo que buscas: cosas que se derrumban, escombros que vuelan, un montón que se asienta, una pelota que rebota por una habitación, un vehículo que rueda por un terreno irregular, un ragdoll que cae a trompicones por una escalera. Nadie puede escribir eso a mano y nadie puede decirte exactamente qué aspecto debería tener.

No recurras a ella cuando sabes lo que debe pasar. Una bala que vuela recta son dos líneas de la lección dos. Una plataforma que sube y baja es math.sin. Un jugador que camina y salta como los jugadores esperan quiere un controlador de personaje (playerNew, en la referencia), porque una persona no es una caja y nunca se comporta como tal. Un enemigo que patrulla quiere un recorrido. Un menú que entra deslizándose quiere una interpolación.

La regla que mejor funciona: física para las cosas que el jugador mira, y aritmética para las cosas que el jugador hace.

Pruébalo

  1. Cambia el mundo. Añade physicsSetGravity(0, -1.62, 0) cerca del principio y vuelve a disparar. Luego prueba 0, -30, 0. Las mismas cajas, otro planeta, una línea.

  2. Cambia la bola. Haz la bola diez veces más pesada con bodySetMass(ball, 30), y luego diez veces más ligera con 0.3, manteniendo la misma velocidad. Después devuelve la masa a su valor y cambia en su lugar el -14. Dos formas de golpear más fuerte, y no se sienten igual.

  3. Haz que las cajas sean de hielo. Añade bodySetFriction(crate, 0.02) en crateAt, y añade una línea que le dé también al suelo una fricción baja. Mira cómo la pila se niega a mantenerse en pie desde el principio.

  4. Equivoca la forma a propósito. En crateAt, cambia las medidas del cuerpo a 2, 2, 2 mientras la malla se queda en 0.8. Ejecútalo, mira cómo las cajas flotan y se empujan unas a otras desde la nada, y luego pulsa Mayús y mira cómo la vista de depuración lo explica en una sola imagen.

  5. Puntúalo como es debido. Usa bodyIsResting en cada caja para darte cuenta de cuándo ha terminado el tiro, y solo entonces cuenta cuántas han caído y súmalo a una puntuación. Esa es la mitad de un juego de bolos que lleva la puntuación.

Rómpelo a propósito

Añade una línea debajo del bodyNew del suelo para que el suelo sea pesado, que es algo razonable de creer que quieres:

bodySetMass(floor, 200)

Singe detiene el juego con algo así:

32:bodySetMass:  Node 1 is not a dynamic body, or the mass is not positive.

El primer número es la línea de tu propio archivo, así que el tuyo será distinto.

El número que va después de Node es el handle del nodo, el número que te devolvió nodeNew. La queja es exacta: la masa es cosa de lo que mueve la simulación, y a un cuerpo estático no lo mueve nada, así que no tiene masa que fijar. Pedirlo es señal de que el cuerpo es del tipo equivocado para lo que tenías en mente — y si de verdad quieres un suelo pesado que se pueda mover, lo que quieres es un cuerpo dinámico con mucha masa, o uno cinemático que muevas tú.

El mismo mensaje aparece con una masa de 0, que la gente escribe queriendo decir «sin peso». Sin peso no es una masa. Es un mundo sin gravedad, o playerSetGravityScale en un controlador de personaje.

Lo que has aprendido

  • Un cuerpo se une a un nodo, y desde ese momento el nodo y el cuerpo son una sola cosa.

  • El estático no se mueve nunca, al dinámico lo mueve la simulación, y al cinemático lo mueves tú y aparta todo lo demás.

  • La forma de colisión es un sustituto de la malla, y eres tú quien responde de que sus medidas coincidan con lo que has dibujado.

  • La masa por defecto es el volumen de la forma con la densidad del agua, así que fíjala en todo lo que deba parecer ligero.

  • bodySetVelocity sustituye el movimiento de un cuerpo, bodyApplyImpulse es un golpe y bodyApplyForce es un empujón que dura.

  • No fijes la posición de un nodo dinámico; bórralo y crea uno nuevo cuando tengas que hacerlo empezar de nuevo.

  • onCollision informa de cada contacto nuevo con su punto y su velocidad, y un cuerpo activador informa de las llegadas y las salidas a través de onTrigger.

  • bodyIsResting te dice cuándo se ha parado todo, que suele ser cuando ha terminado un turno.

  • physicsSetDebug dibuja lo que ve la propia simulación, y responde a la mayoría de las preguntas sobre la física más rápido que leer código.

  • La física es cara, irrepetible y delicada de ajustar. Úsala para el lío, no para las cosas de las que depende el juego.

La próxima vez

Las cajas que caen son un tipo de espectáculo. El otro tipo está hecho de mil cosas diminutas que viven medio segundo: chispas, humo, fuego, lluvia y polvo. La próxima lección trata de los emisores, y termina con una explosión. Esa es la lección veinticinco.

Lección 25: Partículas

La lección terminada

Al final de esta lección, una nave cruzará la parte de abajo de la pantalla dejando un rastro de fuego detrás de su motor, y un botón la hará estallar en ciento cuarenta chispas que giran y rebotan en el suelo. No escribirás ni una sola línea que dibuje una chispa.

Esa es toda la idea de esta lección. Tú describes el fuego; el motor lo hace.

Por qué no dibujas tú las chispas

Podrías hacerlo al revés. Sabes lo suficiente: una tabla de chispas de la lección seis, cada una con una x, una y, y una velocidad; un bucle en onOverlayUpdate que las mueve todas, las desvanece, quita cada una cuando muere y la dibuja. Funciona. También son doscientas líneas de contabilidad que cada juego vuelve a escribir, y se ejecuta en Lua, una chispa cada vez, sesenta veces por segundo.

En lugar de eso, Singe lo hace por ti. Le das una receta — cuántas chispas por segundo, cuánto vive cada una, a qué velocidad y hacia dónde salen, qué tira de ellas, qué aspecto tienen y a qué color se desvanecen — y él se encarga de las chispas. Lo que guarda la receta y la ejecuta se llama emisor.

Un emisor no es una imagen ni un objeto de tu juego. Es la descripción de un tipo de fuego, guardada en algún sitio que puedes señalar, y puede hacer ese fuego en cualquier sitio que le pidas.

Empieza con algo que se mueve

Las partículas resultan más convincentes cuando salen de algo, así que empieza con una nave. Crea una carpeta, copia dentro la carpeta art del libro y pon esto en particles.singe:

dofile("Singe/Framework.singe")

local SHIP_WIDTH  = 32
local SHIP_HEIGHT = 24
local SHIP_SPEED  = 120

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")

local shipX = (overlayGetWidth() - SHIP_WIDTH) / 2
local shipY = overlayGetHeight() - 56

local movingLeft  = false
local movingRight = false
local lastTicks   = singeGetTicks()


function onInputPressed(what)
    if what == SWITCH_LEFT then
        movingLeft = true
    elseif what == SWITCH_RIGHT then
        movingRight = true
    end
end


function onInputReleased(what)
    if what == SWITCH_LEFT then
        movingLeft = false
    elseif what == SWITCH_RIGHT then
        movingRight = false
    end
end


function onOverlayUpdate()
    local now     = singeGetTicks()
    local seconds = (now - lastTicks) / 1000
    lastTicks     = now

    if movingLeft then
        shipX = shipX - SHIP_SPEED * seconds
    end
    if movingRight then
        shipX = shipX + SHIP_SPEED * seconds
    end

    overlayClear()
    spriteDraw(shipSprite, shipX, shipY)
    return OVERLAY_UPDATED
end

Ejecútalo con Singe -R particles y maneja la nave con las teclas de flecha izquierda y derecha. Aquí no hay nada nuevo: un sprite de la lección nueve, los interruptores de la lección tres y singeGetTicks para que la nave se mueva a la misma velocidad sea cual sea la tasa de fotogramas.

La única línea que merece la pena señalar es dofile("Singe/Framework.singe"). Es la que define DIR, la carpeta donde está tu script, así que DIR .. "art/spaceship.png" encuentra la imagen sea cual sea la carpeta desde la que arrancaste Singe.

Ponle un escape

Ahora el fuego. Añade esto encima de los callbacks, después de las variables de la nave:

local exhaust = emitterNew()
emitterSetBlend(exhaust, PARTICLE_ADD)
emitterSetRate(exhaust, 90)
emitterSetLife(exhaust, 0.15, 0.40)
emitterSetDirection(exhaust, 0, 1)
emitterSetSpread(exhaust, 12)
emitterSetSpeed(exhaust, 40, 90)
emitterSetSize(exhaust, 7, 1)
emitterSetColor(exhaust, 255, 240, 180, 255, 255, 60, 0, 0)
emitterSetMax(exhaust, 120)
emitterStart(exhaust)

Y dos líneas dentro de onOverlayUpdate. La primera va justo antes de overlayClear y la segunda justo después de spriteDraw:

    emitterSetPosition(exhaust, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT - 2)
    emitterDraw(exhaust)

Guarda. Ahora la nave va montada sobre una lengua corta de llama amarilla, y la llama la acompaña cuando la manejas.

Hazla estallar

Un escape funciona para siempre. Una explosión ocurre una sola vez, y para el motor eso es otro tipo de petición al mismo emisor.

Antes, dos archivos más y un número más. Estos van junto al sprite de la nave, arriba del todo:

local sparkSprite = spriteLoad(DIR .. "art/star.png")
local boomSound   = soundLoad(DIR .. "art/boom.wav")

y esto va junto a shipX y shipY, veinte unidades por encima de la parte de abajo de la pantalla:

local ground = overlayGetHeight() - 20

Ahora la segunda receta, debajo de la primera:

local boom = emitterNew()
emitterSetTexture(boom, sparkSprite)
emitterSetBlend(boom, PARTICLE_ADD)
emitterSetLife(boom, 0.4, 1.1)
emitterSetSpeed(boom, 40, 220)
emitterSetSpread(boom, 180)
emitterSetGravity(boom, 0, 160)
emitterSetDrag(boom, 0.9)
emitterSetSize(boom, 10, 2, 0.4)
emitterSetSpin(boom, -240, 240)
emitterSetColor(boom, 255, 255, 220, 255, 255, 70, 20, 0)
emitterSetCollide(boom, COLLIDE_FLOOR, 0.35, 0.3, ground)
emitterSetTrail(boom, 4, 2)
emitterSetMax(boom, 400)

Fíjate en que falta emitterStart. Este no va a soltar nunca un chorro.

Añade una función que lo dispare, encima de onInputPressed:

function explode()
    if not flying then
        return
    end
    flying = false
    emitterStop(exhaust)
    emitterSetPosition(boom, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT / 2)
    emitterBurst(boom, 140)
    soundPlay(boomSound)
    timerAfter(RESPAWN_MS, function()
        flying = true
        emitterStart(exhaust)
    end)
end

Para eso hacen falta tres cosas más: local RESPAWN_MS = 1400 con las demás constantes, local flying = true con las demás variables y una rama en onInputPressed:

    elseif what == SWITCH_BUTTON1 then
        explode()

Por último, la nave no debería estar ahí mientras está hecha pedazos. Envuelve el manejo y el dibujo de onOverlayUpdate en if flying then …​ end, y añade emitterDraw(boom) junto a la otra llamada de dibujo. El script terminado es learn/25-particles.singe.

Pulsa la barra espaciadora — el botón uno por defecto — y la nave se deshace en una nube de estrellas que dan vueltas, caen en arco, chocan contra el suelo y rebotan.

Qué acaba de pasar

En esta lección hay muchísimas llamadas nuevas, y todas tienen la misma forma: primero el emisor y luego lo que estás ajustando. Míralas por grupos.

local exhaust = emitterNew()

Crea un emisor y te devuelve un handle: un número que el motor usa para volver a encontrarlo, exactamente igual que el número que te da spriteLoad. Sin argumento obtienes un emisor bidimensional, que vive en coordenadas del overlay y se dibuja desde onOverlayUpdate. Dale un nodo a emitterNew y obtienes uno tridimensional, que vive en la escena y se dibuja solo; todo lo demás de esta lección es igual para los dos.

Un emisor nuevo ya tiene una receta completa — cincuenta partículas por segundo, blancas, un segundo o dos de vida, subiendo despacio por la pantalla — así que con cada llamada posterior le llevas la contraria a un valor por defecto. La entrada de la referencia para emitterNew los enumera todos.

emitterSetRate(exhaust, 90)
emitterSetLife(exhaust, 0.15, 0.40)

Noventa partículas por segundo, cada una viviendo entre quince centésimas y cuatro décimas de segundo. Esos dos números juntos deciden cuánto fuego hay: noventa por segundo que viven un tercio de segundo son unas treinta en pantalla en cada momento.

Siempre que una llamada de emisor recibe un mínimo y un máximo, cada partícula recibe su propio valor, elegido al azar entre los dos. De ahí viene la irregularidad. Un fuego en el que cada llama viviera exactamente lo mismo que todas las demás parecería una máquina.

emitterSetDirection(exhaust, 0, 1)
emitterSetSpread(exhaust, 12)
emitterSetSpeed(exhaust, 40, 90)

Hacia dónde salen, lo ancho que es el abanico y a qué velocidad. La Y del overlay crece hacia abajo, como desde la lección uno, así que (0, 1) es hacia abajo en la pantalla — por la parte de atrás de una nave que apunta hacia arriba. emitterSetSpread es la mitad del ángulo del abanico: doce grados es un haz estrecho, noventa lo abre a medio círculo y ciento ochenta es todas las direcciones a la vez.

emitterSetSize(exhaust, 7, 1)
emitterSetColor(exhaust, 255, 240, 180, 255, 255, 60, 0, 0)

Estas dos son la razón de que la llama parezca una llama. Una partícula no tiene un tamaño y un color; tiene un tamaño y un color al nacer y otros al morir, y pasa de manera uniforme de unos a otros a lo largo de la vida que le haya tocado. Así que cada chispa empieza con siete unidades del overlay de ancho y de color amarillo pálido, y acaba con una unidad de ancho y de color rojo anaranjado con un alfa de cero, que es invisible. Encoge y se desvanece porque tú dijiste dónde acaba, no porque algo la desvaneciera.

emitterSetColor recibe ocho números, que es mucho que leer: rojo, verde, azul y alfa al principio, y luego rojo, verde, azul y alfa al final.

emitterSetBlend(exhaust, PARTICLE_ADD)

Cómo se combina una partícula con lo que tiene detrás. PARTICLE_ALPHA es pintar normal y es el valor por defecto: úsalo para humo, polvo, lluvia y escombros. PARTICLE_ADD, en cambio, suma su luz a la imagen, así que dos chispas una encima de otra brillan más que una y nada se oscurece nunca. El fuego, las chispas, los láseres y la magia son aditivos. El humo no, y el humo dibujado de forma aditiva parece vapor iluminado desde dentro.

emitterSetMax(exhaust, 120)
emitterStart(exhaust)

emitterSetMax es el tamaño de la reserva: cuántas partículas de este emisor pueden existir a la vez. Cuando la reserva está llena no nace ninguna nueva hasta que muere alguna. Noventa por segundo que viven hasta cuatro décimas de segundo necesitan unas treinta y seis, así que ciento veinte va holgado. Ajústalo antes de arrancar, porque cambiarlo después tira todas las partículas vivas.

emitterStart abre el grifo. A partir de ahí el emisor crea partículas en cada fotograma, lo dibujes o no, hasta que emitterStop lo vuelve a cerrar. Fíjate en lo que emitterStop no hace: detiene las partículas nuevas, y las que ya están vivas terminan su vida y se desvanecen con normalidad. Por eso el escape se va apagando en lugar de desaparecer de golpe cuando la nave explota. Si las quieres fuera en este mismo instante, emitterClear las mata.

    emitterSetPosition(exhaust, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT - 2)

Así es como un emisor sigue a algo. Un emisor bidimensional crea sus partículas en un punto, y ese punto es donde lo pusiste la última vez, así que lo ajustas en cada fotograma a partir de lo que se esté moviendo: la posición de un sprite, el nodo de un cuerpo físico, el ratón. Las partículas nuevas aparecen en el sitio nuevo; las que ya están en el aire se quedan donde nacieron, que es justo lo correcto para un escape, porque el escape se queda atrás.

Un emisor tridimensional se crea sobre un nodo y sigue a ese nodo por su cuenta, sin ninguna llamada en tu actualización. Y cuando sí quieres que toda la nube viaje con la cosa — un escudo, un aura, la llama de un propulsor vista desde fuera — emitterSetLocal lo activa.

    emitterDraw(exhaust)

Los emisores bidimensionales se dibujan cuando lo pides, una vez por fotograma, desde onOverlayUpdate. El orden de tus llamadas a emitterDraw es el orden en que se apilan. Olvidar esta llamada es el error que todo el mundo comete una vez: el emisor sigue funcionando, sigue gastando su reserva y no muestra nada.

Ahora las llamadas propias de la explosión.

emitterSetTexture(boom, sparkSprite)

Sin textura, cada partícula es una mancha redonda y suave que dibuja el propio motor, que es lo que usa el escape y lo adecuado para una llama. Con una, cada partícula lleva puesta esa imagen — aquí star.png, de ocho por ocho píxeles. El emisor se queda con su propia copia de los píxeles, así que puedes descargar el sprite después y las partículas siguen funcionando.

emitterSetGravity(boom, 0, 160)
emitterSetDrag(boom, 0.9)

La gravedad es un tirón constante, en unidades del overlay por segundo por segundo, y es positiva hacia abajo por el mismo motivo por el que el escape sale con una Y positiva. El rozamiento es lo contrario: quita velocidad, un poco en cada fotograma, así que las chispas salen disparadas con fuerza y luego se quedan suspendidas. Las chispas con gravedad y sin rozamiento caen en línea recta como un fuego artificial; el rozamiento es lo que hace que parezca que se mueven a través del aire.

emitterSetSpin(boom, -240, 240)
emitterSetSize(boom, 10, 2, 0.4)

El giro va en grados por segundo, y un rango que cruza el cero te da algunas que giran hacia cada lado. Se nota en una textura y no le hace nada en absoluto a la mancha incorporada, que es redonda.

El tercer número de emitterSetSize es la variación. Escala los dos tamaños de cada partícula por un mismo factor aleatorio — aquí cualquier valor entre seis décimas y uno con cuatro décimas — para que las chispas no sean todas la misma estrella del mismo tamaño.

emitterSetCollide(boom, COLLIDE_FLOOR, 0.35, 0.3, ground)
emitterSetTrail(boom, 4, 2)

COLLIDE_FLOOR pone un suelo plano e invisible de lado a lado del mundo a la altura que indiques, y las partículas rebotan en él. Los dos números que van antes son cuánta velocidad sobrevive a un rebote y cuánta velocidad lateral se pierde. No cuesta nada, porque es una comparación por partícula, y hace que los restos parezcan haber caído en algún sitio en lugar de atravesar el mundo. En un juego tridimensional, COLLIDE_SCENE hace rebotar las partículas en la geometría real, lo que cuesta muchísimo más.

Una estela guarda los últimos sitios por los que ha pasado una partícula y dibuja a través de ellos una cinta que se desvanece. Cuatro posiciones y dos unidades de ancho convierten cada estrella en un trazo corto.

    emitterBurst(boom, 140)

Y esta es la otra forma de crear partículas. emitterStart es un grifo; emitterBurst es un puñado lanzado de golpe. El emisor no tiene que estar soltando un chorro, y este nunca lo está. Todo lo demás — la receta, la reserva, la posición — funciona igual.

Merece la pena quedarse con esta distinción. Todo lo continuo es un chorro que abres y cierras: escape, humo, lluvia, una antorcha, una cascada. Todo lo que pasa en un momento es una ráfaga: una explosión, una salpicadura, una pisada en el polvo, el impacto de una bala, el fogonazo de un disparo. Muchos efectos son las dos cosas, con un emisor o con dos: un proyectil estalla y luego echa humo.

Cuántas son demasiadas

La respuesta sincera es que las partículas son baratas de mover y caras de mirar.

Mover diez mil partículas es aritmética, y un ordenador capaz de ejecutar un juego puede hacerlo sin enterarse. Lo que cuesta es dibujarlas, y lo que cuesta dibujarlas es más o menos el número de píxeles de pantalla que cubren las partículas, contando los solapamientos. Doscientas chispas de ocho píxeles de ancho cubren menos pantalla que una bocanada de humo que la llena entera. Esa es la regla: pequeñas y muchas es casi gratis, y grandes y solapadas no.

La mezcla aditiva es la cara, porque nada de lo que dibuja se puede saltar — cada capa se suma a lo que hay debajo, así que la máquina las pinta todas. Una docena de destellos aditivos a pantalla completa uno encima de otro dejarán una Raspberry Pi 4 a paso de tortuga, mientras que diez mil chispitas que rebotan no la inmutan.

Así que unos pocos miles de partículas pequeñas no son motivo de preocupación. Antes de pasar de ahí, pon el recuento en pantalla y vigílalo.

    overlayPrint(2, 4, "Particles alive: " .. (emitterGetCount(exhaust) + emitterGetCount(boom)))

emitterGetCount es cómo dimensionas una reserva con honradez en lugar de a ojo. Si el número se queda exactamente en tu emitterSetMax, la reserva está llena y el motor se está negando en silencio a crear partículas que le has pedido. Si nunca se acerca, estás reservando memoria para nada.

Pruébalo

  1. Convierte el escape en humo. Cambia emitterSetBlend(exhaust, PARTICLE_ADD) por PARTICLE_ALPHA, pon el color en gris que se desvanece a gris transparente y haz que crezca en lugar de encoger con emitterSetSize(exhaust, 3, 14). Tres líneas han hecho una máquina distinta.

  2. Quítale el rozamiento a la explosión. Borra la línea emitterSetDrag y compara. Luego vuelve a poner el rozamiento y quita la gravedad. Una de las dos parece fuegos artificiales y la otra parece un accidente.

  3. Ensancha el escape. Pon emitterSetSpread(exhaust, 180). La nave deja de parecer que tiene un motor. La apertura del abanico hace más de lo que crees.

  4. Lanza mil. Cambia emitterBurst(boom, 140) por emitterBurst(boom, 1000) y mira el recuento en pantalla. No llegará a mil. Averigua por qué a partir de emitterSetMax, luego agranda la reserva, haz las chispas cuatro veces más grandes y mira qué le pasa a la tasa de fotogramas.

  5. Lanza la explosión donde no está la nave. Pon emitterSetPosition(boom, 40, 60) en explode en lugar de la posición de la nave. Un emisor es la descripción de un fuego, no una cosa que viva en algún sitio, y puedes lanzar una ráfaga del mismo emisor en diez sitios en el mismo fotograma.

Rómpelo a propósito

Las constantes — PARTICLE_ADD, COLLIDE_FLOOR, OVERLAY_UPDATED — son nombres que Singe les ha dado a números. Escribe una un poco mal y Lua no se queja, porque en Lua un nombre al que nunca se le dio un valor no es un error: es nil, el valor que significa «aquí no hay nada».

Cambia la línea de mezcla del escape por un nombre que parece igual de probable:

emitterSetBlend(exhaust, PARTICLE_ADDITIVE)

Singe se para antes de que arranque el juego, nombrando la línea de tu archivo en la que está esa llamada:

22:emitterSetBlend:  Argument 2 must be a number.

Este error tiene una forma distinta de los errores de Lua de la lección ocho, porque viene del motor y no de Lua. Es el número de línea, luego la llamada que protestó y luego la queja. El argumento dos de emitterSetBlend es el modo de mezcla, y lo que llegó fue nil, porque PARTICLE_ADDITIVE no es un nombre que nadie haya definido nunca.

«Must be a number» casi siempre significa esto: una constante mal escrita, o una variable que creías haber asignado. El arreglo es comparar el nombre con la referencia, que lo escribe PARTICLE_ADD.

Lo que has aprendido

  • Un emisor guarda la receta de un tipo de partícula y se encarga él mismo de las partículas, así que tu script nunca dibuja ninguna.

  • emitterNew sin argumento crea un emisor bidimensional en coordenadas del overlay; con un nodo crea uno tridimensional en la escena.

  • Todos los emisores empiezan con una receta completa, y cada llamada emitterSet…​ cambia una parte de ella.

  • Siempre que una llamada recibe un mínimo y un máximo, cada partícula saca su propio valor al azar entre los dos, y de ahí viene la irregularidad.

  • El tamaño y el color se fijan al nacer y al morir, y la partícula pasa de uno a otro a lo largo de su vida.

  • emitterStart suelta un chorro hasta emitterStop; emitterBurst lanza un puñado de golpe. Los efectos continuos son chorros, los momentáneos son ráfagas.

  • emitterStop deja que las partículas vivas terminen; emitterClear las mata ya.

  • Un emisor bidimensional se mueve con emitterSetPosition en cada fotograma y se dibuja con emitterDraw en cada fotograma. Uno tridimensional sigue a su nodo y se dibuja solo.

  • Las partículas cuestan lo que cubren en pantalla, no lo que cuesta moverlas, y la mezcla aditiva es la cara.

  • emitterSetMax pone un tope a la reserva, y emitterGetCount te dice si acertaste con el tamaño.

La próxima vez

La explosión movió ciento cuarenta cosas sin que nadie le dijera adónde tenía que ir ninguna, pero eran chispas, y a las chispas les da igual con qué choquen. La lección veintiséis trata de algo a lo que no le da igual: un personaje que tiene que llegar de aquí a allí, con una pared en medio.

Lección 26: Personajes que se mueven solos

La lección terminada

En esta lección construyes una habitación con una pared que la cruza por el medio y pones dos personajes en ella. A uno lo mandas a una esquina pulsando un botón. El otro elige un sitio al azar, camina hasta allí y, cuando llega, elige otro sitio, para siempre.

Ninguno de los dos se mete en la pared, y nunca escribes una línea que diga cómo rodearla. Eso es nuevo. Todas las lecciones hasta esta han movido las cosas adonde tú les decías. Esta es la primera lección en la que el juego averigua algo por sí mismo.

El problema de caminar hacia algo

Esta es la forma obvia de hacer que un personaje camine hasta un punto, y es la que todo el mundo escribe primero. Toma el destino, réstale dónde estás y da un pasito a lo largo de la línea que los une, en cada fotograma, hasta llegar.

Funciona de maravilla en una habitación vacía.

Pon una pared en la habitación y deja de funcionar, y deja de funcionar de una forma que parece estúpida más que rota: el personaje marcha contra la pared y se queda ahí restregándose contra ella, a un metro de una puerta que no puede ver, porque nada en «da un paso hacia el destino» tiene la menor idea de que el mundo tiene formas.

No puedes salir de esto a base de parches. Apartarte cuando tocas una pared hace que tu personaje se atasque en la primera esquina que encuentre. Tampoco basta con saber dónde están las paredes, porque el camino que rodea una pared puede ser largo, puede alejarse del destino antes de volver y puede no existir en absoluto.

Lo que hace falta es una forma de hacer una pregunta de verdad: ¿cómo camino de aquí a allí? Para responderla hace falta algo que conozca la forma del suelo.

Qué es una malla de navegación

Ponte en una habitación y mira el suelo. Por una parte podrías caminar. Por otra no: está debajo de una mesa, dentro de una pared, más allá del borde de un balcón o encima de un escalón demasiado alto para subirlo. Ahora imagina que pintas la parte por la que podrías caminar y tiras todo lo demás — las paredes, los muebles, el techo, el decorado. Lo que te queda es una forma plana, o varias, con agujeros donde están las columnas y huecos donde están los desniveles.

Esa forma pintada es una malla de navegación, y es todo lo que necesita un personaje para planear un paseo. No es el nivel. Es un mapa simplificado de las partes del nivel donde una persona puede estar de pie, y como es sencillo, las preguntas sobre él se pueden responder deprisa.

Singe la hace por ti a partir del nivel que ya tienes. Le dices el tamaño de los personajes, le pasas la geometría y averigua qué es transitable: suelos y rampas dentro de la pendiente que permitas, escalones no más altos de lo que permitas, con un margen recortado alrededor de cada pared y de cada desnivel para que un personaje con anchura no atraviese una esquina. Eso se llama precalcular, ocurre una vez, y el resultado se puede guardar en un archivo y cargar la próxima vez.

Una habitación con una pared

Crea una carpeta llamada navigation y empieza dentro un archivo llamado navigation.singe. Esta parte es una escena tridimensional, que es el tema de la lección veintidós: una escena es un mundo dibujado en tres dimensiones, y todo lo que hay en ella cuelga de un nodo, que es una posición, una rotación y una escala a las que puedes sujetar una forma.

Si te saltaste esa lección, puedes seguir esta igualmente. Toma los dos bloques siguientes como «un suelo gris de veinte unidades de lado, tres paredes de color tostado sobre él y una cámara que lo mira todo desde arriba».

local ROOM         = 20
local WALL_HEIGHT  = 2
local AGENT_RADIUS = 0.4
local AGENT_HEIGHT = 1.8
local WALK_SPEED   = 2.2

sceneEnable(true)
sceneSetBackground(28, 32, 42, 255)
sceneSetAmbient(80, 86, 100)

local floorLook = materialNew()
materialSetColor(floorLook, 96, 102, 110)
materialSetRoughness(floorLook, 0.9)

local wallLook = materialNew()
materialSetColor(wallLook, 150, 128, 104)
materialSetRoughness(wallLook, 0.8)

local ground = nodeNew()
nodeSetMesh(ground, meshPlane(ROOM, ROOM), floorLook)

local wallMesh = meshBox(1, WALL_HEIGHT, 1)
local walls    = {}


function addWall(x, z, width, depth)
    local wall = nodeNew()
    nodeSetMesh(wall, wallMesh, wallLook)
    nodeSetScale(wall, width, 1, depth)
    nodeSetPosition(wall, x, WALL_HEIGHT / 2, z)
    walls[#walls + 1] = wall
end


addWall(-4, 0, 12, 0.6)
addWall(7.5, 0, 5, 0.6)
addWall(-3, -6, 0.6, 8)

Las unidades aquí son metros, porque eso es lo que da por hecho el mundo tridimensional de Singe. Las dos primeras paredes cruzan la mitad de la habitación con un hueco de tres metros entre ellas: una puerta. La tercera es un tabique corto que se mete en la mitad del fondo, para que los personajes tengan algo que rodear una vez que la hayan cruzado.

Añade una luz y una cámara para que haya algo que ver:

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 8, 14, 6)
nodeLookAt(sun, 0, 0, 0)
lightSetIntensity(sun, 3.5)
lightSetShadow(sun, true)

local camera = nodeNew()
nodeSetPosition(camera, 0, 17, 19)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)
cameraSetPerspective(55, 0.1, 120)


function onOverlayUpdate()
    overlayClear()
    return OVERLAY_UPDATED
end

Ejecútalo con Singe -R navigation. Un suelo gris, una pared con un hueco y un tabique, vistos desde arriba y desde atrás.

Precalcula el suelo

Seis líneas convierten esa habitación en un mapa:

local nav = navNew(AGENT_RADIUS, AGENT_HEIGHT, 45, 0.3)
navAddNode(nav, ground)
for _, wall in ipairs(walls) do
    navAddNode(nav, wall)
end
navBuild(nav)

Ponlas después de las paredes y antes de la luz. Luego añade una línea a onOverlayUpdate, debajo de overlayClear, para ver lo que has obtenido:

    navDraw(nav, 0, 170, 190)

Ejecútalo otra vez. Una red de triángulos verdeazulados se extiende sobre el suelo, y se detiene antes de llegar a las paredes. El hueco que deja no es decoración: son los 0,4 metros de holgura que necesita un personaje con un radio de 0,4 metros para que sus hombros no atraviesen la piedra. La puerta sigue siendo una puerta en la malla, porque tres metros es lo bastante ancho para pasar; haz el hueco de medio metro y el azul se cerraría sobre él, y para todos los personajes de tu juego allí no habría ninguna puerta.

Míralo un momento, porque navDraw es la herramienta que buscarás cada vez que un personaje haga algo inexplicable. Nueve de cada diez veces la respuesta está en el suelo, delante de ti.

Alguien que lo recorra

Un personaje es un nodo. Su aspecto no es asunto de la navegación, así que construye lo más barato que muestre hacia dónde mira: una caja con nariz.

function makeWalker(x, z, look)
    local walker = nodeNew()
    nodeSetPosition(walker, x, 0, z)
    local body = nodeNew()
    nodeSetParent(body, walker)
    nodeSetMesh(body, meshBox(0.7, AGENT_HEIGHT, 0.7), look)
    nodeSetPosition(body, 0, AGENT_HEIGHT / 2, 0)
    local nose = nodeNew()
    nodeSetParent(nose, body)
    nodeSetMesh(nose, meshSphere(0.22, 16), look)
    nodeSetPosition(nose, 0, 0.4, -0.45)
    return walker
end

Eso va con addWall. Necesita un color, así que añade uno junto a los demás materiales:

local walkerLook = materialNew()
materialSetColor(walkerLook, 225, 85, 60)
materialSetEmissive(walkerLook, 70, 18, 10)

Y ahora la línea por la que existe esta lección. Después de navBuild:

local walker      = makeWalker(-7, 7, walkerLook)
local walkerAgent = navAgentNew(nav, walker, AGENT_RADIUS, AGENT_HEIGHT, WALK_SPEED)

navAgentNew pone el nodo sobre la malla y te devuelve un agente: la palabra del motor para algo que está dispuesto a hacer caminar por ti. Desde este momento, el motor es el dueño de la posición de ese nodo. En cada fotograma lo mueve y lo gira para que mire hacia donde va, y seguirá haciéndolo hasta que le digas adónde ir o retires el agente.

Ejecútalo. Una caja roja con nariz aparece en la esquina más cercana y no hace absolutamente nada, porque todavía no le has pedido nada.

Mandarla a algún sitio

Dale una lista de sitios y un botón.

local posts = {
    {  7, 0,  7 },
    {  7, 0, -7 },
    { -7, 0, -7 },
    { -7, 0,  7 },
    { 30, 0, 30 }
}
local post    = 0
local message = "Button 1 sends the red one somewhere."


function onInputPressed(what)
    if what ~= SWITCH_BUTTON1 then
        return
    end
    post = post % #posts + 1
    local target = posts[post]
    if navAgentMoveTo(walkerAgent, target[1], target[2], target[3]) then
        message = string.format("Walking to post %d.", post)
    else
        message = string.format("No path to post %d.  Staying put.", post)
    end
end

Imprime el mensaje para ver qué está pasando. En onOverlayUpdate, después de navDraw:

    overlayPrint(2, 2, message)

Ejecútalo y pulsa el botón uno — la barra espaciadora por defecto. La caja gira, camina hasta la esquina más lejana de su propia mitad de la habitación y se para. Pulsa otra vez. Camina a lo largo de la pared, encuentra la puerta, la cruza, sale por el otro lado y se para en la esquina más lejana. Pulsa una tercera vez y rodea el tabique hasta la cuarta esquina. No le has hablado de la puerta. Nada en tu script menciona la puerta. La ha encontrado, porque la puerta es un agujero en una forma y rodear agujeros es justo para lo que sirve la malla.

Cada entrada de posts son tres números, una x, una y, y una z, porque un punto en un mundo tridimensional necesita tres. La Y es hacia arriba, y las tuyas son todas cero porque aquí todo está en el suelo. La tabla posts es una tabla de tablas, de la lección seis, y posts[post] es una de las de dentro.

Saber cuándo llega

La caja se para cuando llega, pero tu script no sabe que ha llegado. Pide que te avisen:

function onNavArrived(agent)
    message = string.format("Arrived at post %d.", post)
end

Esto es un callback, la misma idea que onOverlayUpdate en la lección uno: tú lo escribes y el motor lo llama. Este se ejecuta una vez, en el momento en que un agente alcanza el destino que se le dio. No cuando está cerca, y no en cada fotograma después — una vez, al llegar.

Recibe el agente, porque un juego tiene más de uno. Ese argumento es el número que te devolvió navAgentNew, y compararlo es la forma de saber cuál de tus personajes acaba de llegar adonde iba.

Cuando no hay camino

Pulsa el botón una quinta vez y el mensaje dice No path to post 5. Staying put., y la caja no se mueve.

El puesto cinco está en { 30, 0, 30 }, que está veinte metros fuera de una habitación de veinte metros de ancho. Allí no hay suelo transitable, no hay ninguna ruta hasta él y un personaje no puede hacer nada sensato al respecto. navAgentMoveTo lo dice devolviendo false, y deja el agente exactamente como estaba.

Esta es la parte que los principiantes se saltan, y es la que muerde. Los juegos de verdad piden caminatas imposibles constantemente, porque el destino suele ser el jugador y el jugador se mete en todas partes: subido a un cajón, en mitad de un salto, en el agua, detrás de una puerta que se cerró o al otro lado de un hueco que la malla de navegación recortó por demasiado estrecho. Cada uno de esos casos hace que un navAgentMoveTo perfectamente razonable devuelva false.

Tu script decide qué significa eso. Un guardia que no puede alcanzarte debería volver a patrullar, o caminar hasta el punto más cercano al que sí pueda llegar y esperar allí, o gritar. Lo que no debe hacer es nada, mientras tu código ignora en silencio un false devuelto y tú te preguntas durante una hora por qué uno de cada veinte enemigos está congelado.

Hay otras dos llamadas que ayudan aquí, y merece la pena conocerlas antes de necesitarlas. navNearest recibe cualquier punto y devuelve el sitio más cercano de la malla, o nil si no hay nada cerca, que es como conviertes «donde está el jugador» en «un sitio donde un personaje puede estar de pie de verdad». Y navPath hace la misma pregunta que navAgentMoveTo sin mover a nadie: devuelve las esquinas de la ruta como una tabla de puntos, o nil cuando no hay ruta. Puedes medirla, dibujarla o decidir que el paseo es demasiado largo para molestarse.

Dibujarla es el truco útil. Añade esto a onOverlayUpdate:

    local target = posts[post]
    if target ~= nil then
        local x, y, z = nodeGetWorldPosition(walker)
        local route   = navPath(nav, x, y, z, target[1], target[2], target[3])
        if route ~= nil then
            for i = 2, #route do
                local a = route[i - 1]
                local b = route[i]
                lineDraw(a[1], a[2] + 0.1, a[3], b[1], b[2] + 0.1, b[3], 255, 215, 60)
            end
        end
    end

Ahora una línea amarilla va desde la caja hasta donde sea que esté yendo, doblándose por la puerta y acortándose a medida que camina. Mándala al puesto cinco y la línea no se dibuja, porque navPath devolvió nil y el if lo detectó. Estás viendo la decisión que está tomando el agente, dibujada en el suelo.

Un segundo caminante

Un personaje que esquiva paredes es navegación. Dos personajes que esquivan las paredes y se esquivan entre sí es lo que el motor te da de verdad, y cuesta cuatro líneas más.

Añade un material azul junto al rojo, y luego esto debajo del primer agente:

local wanderer      = makeWalker(6, -6, wandererLook)
local wandererAgent = navAgentNew(nav, wanderer, AGENT_RADIUS, AGENT_HEIGHT, 1.4)

Mándalo a algún sitio para ponerlo en marcha, después de la cámara:

navAgentMoveTo(wandererAgent, navRandomPoint(nav))

Y enseña a onNavArrived a distinguirlos:

function onNavArrived(agent)
    if agent == wandererAgent then
        navAgentMoveTo(agent, navRandomPoint(nav))
    else
        message = string.format("Arrived at post %d.", post)
    end
end

navRandomPoint elige un sitio de la malla transitable — cualquiera, nunca dentro de una pared — y devuelve tres números, que es exactamente lo que quiere navAgentMoveTo a continuación. Como el callback salta al llegar y su respuesta es otro viaje, la caja azul ahora vaga por la habitación mientras dure el juego, con cuatro líneas y sin ningún estado.

Mira cómo se encuentran los dos en la puerta. Ninguno se para en seco y ninguno atraviesa al otro: los dos se apartan un poco, con tiempo, y se cruzan. Eso son los agentes esquivándose entre sí, y es la diferencia entre personajes y muebles.

El script terminado es learn/26-navigation.singe.

Qué acaba de pasar

local nav = navNew(AGENT_RADIUS, AGENT_HEIGHT, 45, 0.3)

Empieza una malla de navegación, y los cuatro números son la descripción de la persona para la que es: 0,8 metros de ancho, 1,8 metros de alto, capaz de caminar por una pendiente de hasta cuarenta y cinco grados y capaz de subir un escalón de hasta 0,3 metros.

Cada uno de ellos cambia la forma que sale. Un personaje más ancho pierde más suelo por el margen alrededor de las paredes y puede encontrarse una puerta cerrada. Uno más alto no puede pasar por debajo de una viga baja. Permite una pendiente más empinada y una rampa se convierte en un camino; permite menos y se convierte en un acantilado.

El radio también decide con qué detalle se mide el suelo, así que un radio muy pequeño en un nivel muy grande tarda mucho en precalcularse. Merece la pena leer la entrada de la referencia para navNew antes de elegir tus números.

navAddNode(nav, ground)
navBuild(nav)

navAddNode le pasa geometría — un nodo y todo lo que cuelga de él, tal como está en el mundo en ese momento, así que coloca las cosas antes de añadirlas. Una sola llamada se lleva un modelo cargado entero. Solo cuentan las formas de verdad: una luz, un sonido o un cuerpo físico por sí solos no añaden nada.

navBuild hace el precálculo, y es la llamada lenta de esta lección: nada que notes para una habitación como esta, una décima de segundo para una catedral en un ordenador de sobremesa, varios segundos en una Raspberry Pi. Hazlo mientras se ve una pantalla de título, no mientras el jugador espera.

Después, la geometría se tira y la malla queda cerrada. No puedes añadir más. Si tu nivel cambia de forma — se abre una puerta, se cae un puente — precalculas otra malla, y navDelete libera la anterior.

En una máquina lenta preferirías no precalcular nada, así que navSave escribe la malla terminada en un archivo y navLoad la vuelve a leer, construida y lista. Precalcula una vez en tu propia máquina, distribuye el archivo con el juego y el jugador no espera nunca.

local walkerAgent = navAgentNew(nav, walker, AGENT_RADIUS, AGENT_HEIGHT, WALK_SPEED)

Un agente es un nodo que el motor ha aceptado hacer caminar por ti. El radio y la altura de aquí son lo que usa para mantenerse apartado de otros agentes, y el último número es su velocidad máxima en metros por segundo — 2,2 es un paso ligero, 1,4 es un paseo tranquilo y 6 es un esprint.

A partir de aquí, no ajustes tú la posición de ese nodo. Dos cosas que mueven un mismo nodo se pelean, y la pelea se ve como tirones. Si tu personaje necesita que la física lo empuje además de caminar, hay una llamada para eso — navAgentSetPlayer cede el manejo a un controlador de física — y la entrada de la referencia sobre ella explica cuándo te conviene.

local ok = navAgentMoveTo(walkerAgent, x, y, z)

Fija el destino. No camina hasta allí; dice dónde está «allí», y el motor se pone a ello en los fotogramas siguientes. Puedes volver a llamarla en cualquier momento y el nuevo destino sustituye al anterior, que es como un guardia sigue a un jugador que corre: vuelve a apuntarlo una o dos veces por segundo, no sesenta.

Y devuelve true o false, y tienes que mirarlo.

navAgentStop(walkerAgent)

No se usa arriba, pero es la otra mitad de la pareja: olvida el destino y el agente frena hasta quedarse quieto donde está. onNavArrived no salta, porque no ha llegado. Úsala cuando la razón del viaje haya desaparecido.

Lo rápido no es lo importante

Una llamada más, porque es la que convierte esto de una demostración en algo que parece un juego.

    local vx, vy, vz = navAgentGetVelocity(walkerAgent)
    local speed      = math.sqrt(vx * vx + vz * vz)
    overlayPrint(2, 4, string.format("Speed %.2f", speed))

navAgentGetVelocity te dice cómo se está moviendo el agente ahora mismo: no adónde va, sino a qué velocidad y en qué dirección está viajando de verdad en este fotograma. Mira el número cuando la caja arranca y cuando se detiene. Acelera suavemente y frena suavemente.

De ese número es del que cuelgas una animación. Un personaje cuyas piernas se mueven a la velocidad a la que viaja de verdad parece vivo; uno cuyo ciclo de paso va a un ritmo fijo mientras acelera parece que patina. Con un modelo de verdad en lugar de la caja, compararías esa velocidad con un par de umbrales y reproducirías una animación de reposo, de andar o de correr — que es el tema de la lección veintitrés, y el ejemplo de la referencia en navAgentGetVelocity está escrito justo para eso.

Y eso es lo importante de verdad de esta lección. Un personaje que toma la línea recta rápida y se restriega a lo largo de una pared es peor que uno que arranca un segundo más tarde, gira como es debido, da la vuelta por la puerta y frena al llegar. Nadie que mire un juego mide lo deprisa que un enemigo llegó hasta él. Lo que nota, al instante y sin saber decir por qué, es cuando algo se mueve de una forma en que no se movería un ser vivo.

Pruébalo

  1. Cierra la puerta. Cambia las dos primeras paredes para que el hueco entre ellas sea de medio metro en lugar de tres: addWall(-4, 0, 13, 0.6) y addWall(6.5, 0, 7, 0.6). Ejecútalo y mira lo que muestra navDraw antes de pulsar nada. Luego manda la caja al otro lado y mira qué hace.

  2. Engorda a todo el mundo. Pon AGENT_RADIUS a 2.0 y ejecútalo. La puerta sigue teniendo tres metros de ancho y los triángulos azules han desaparecido de ella. No hay nada roto; la malla ahora está respondiendo a otra pregunta.

  3. Mándala al ratón. Toma el punto que hay bajo el puntero del ratón con sceneUnproject, ajústalo a la malla con navNearest y manda la caja allí cuando se pulse el botón. Que navNearest devuelva nil es el caso que tienes que tratar, y ocurre siempre que el puntero está fuera del suelo.

  4. Añade cuatro caminantes más. Pon las cuatro líneas del caminante azul en un bucle for de la lección cuatro, guarda los agentes en una tabla y deja que vaguen todos. Mira la puerta cuando tres de ellos la quieran a la vez.

  5. Precalcúlala una vez. Llama a navSave(nav, "room.nav") después de navBuild, y luego sustituye navNew, las llamadas a navAddNode y navBuild por un único navLoad("room.nav", AGENT_RADIUS, AGENT_HEIGHT). Ahora cambia la posición de una pared y vuelve a ejecutarlo. Lo que ves es la trampa que viene con las mallas precalculadas, y merece la pena encontrársela una vez a propósito.

Rómpelo a propósito

Precalcular cierra la malla. Intenta añadir una cosa más a toro pasado — un cajón que colocaste tarde, o una pared que se te olvidó — poniendo esta línea justo después de navBuild(nav):

navAddNode(nav, ground)

Singe se para antes de que arranque el juego, nombrando la línea de tu archivo en la que está esa llamada:

68:navAddNode:  The mesh is already built.

La forma de un error del motor es la línea, la llamada que protestó y la queja, y esta queja significa lo que dice: navBuild consumió la geometría que se le dio y ya no queda nada a lo que añadir.

El arreglo nunca es mover la llamada a navAddNode. Es darte cuenta de que tienes geometría para dos niveles y quieres dos mallas, o de que precalculaste demasiado pronto. Añádelo todo, luego construye, y construye lo último.

Lo que has aprendido

  • Dar pasos hacia un destino funciona en una habitación vacía y falla en cuanto hay una pared, y ningún parche lo arregla.

  • Una malla de navegación es un mapa simplificado del suelo donde un personaje puede estar de pie, sin las paredes, los desniveles ni la holgura a su alrededor.

  • navNew describe el personaje para el que es la malla, navAddNode le pasa la geometría del nivel y navBuild la precalcula. Después del precálculo no se puede añadir nada más.

  • navSave y navLoad guardan una malla precalculada en un archivo para que el jugador nunca tenga que esperarla.

  • navDraw te muestra la malla, y es lo primero que hay que mirar cuando un personaje se porta de forma rara.

  • navAgentNew le da un nodo al motor para que lo haga caminar; a partir de ahí, no muevas tú ese nodo.

  • navAgentMoveTo fija un destino y devuelve false cuando no hay forma de llegar. Tratar eso es cosa tuya, y pasa a menudo.

  • onNavArrived se llama una vez cuando un agente alcanza su destino, y se le dice qué agente es.

  • navPath responde a la misma pregunta sin mover a nadie, y nil significa que no hay ruta.

  • Los agentes se esquivan entre sí además de esquivar el nivel.

  • navAgentGetVelocity es como un ciclo de paso se ajusta al suelo que se recorre.

La próxima vez

Tus dos cajas ahora se pasean por una habitación en silencio. La lección veintisiete trata de lo que pones detrás de ellas: música que se repite como es debido y que va a compás del vídeo, y MIDI, que permite a un juego tocar un instrumento — o a un instrumento de verdad tocar el juego.

Lección 27: Música y MIDI

La lección terminada

Esta lección son dos lecciones que da la casualidad de que viven juntas.

La primera mitad es música: cómo reproduce un juego una pieza de música como es debido, por qué eso no es lo mismo que reproducir un efecto de sonido y qué hacer cuando la música tiene que ir a compás del vídeo.

La segunda mitad es MIDI, que la mayoría de la gente no ha visto nunca y que le da a un juego algo que no le da nada más. Al final, un teclado enchufado a tu ordenador estará tocando tu juego.

Un efecto de sonido y una pieza de música son cosas distintas

Ya sabes reproducir un sonido. La lección diez cargó un .wav con soundLoad y lo lanzó con soundPlay, y si apuntas esas dos llamadas a una canción de cuatro minutos, la reproducirán.

No lo hagas. Singe mantiene separados los efectos de sonido y la música, y la separación merece la pena por cuatro razones.

  • Tienen sus propios volúmenes. soundSetVolume nunca toca la música y musicSetVolume nunca toca los disparos. Todos los juegos que se han publicado lo han necesitado, porque los jugadores bajan la música y suben los efectos.

  • La música no tiene límite de canales. Los efectos de sonido comparten dieciséis canales, y cuando los dieciséis están ocupados el decimoséptimo no suena. Una pista de música no va en un canal, así que nada puede quitarle el sitio.

  • Un handle es una pista, y se pausa, se reanuda, se para y se desvanece por su cuenta sin molestar a nada más.

  • La música se pausa con el juego. Pulsa la tecla de pausa y se queda donde está. Vuelve y sigue. No escribes nada para que eso pase.

Hay una cosa que no es distinta y que merece la pena saber, porque la gente da por hecho lo contrario: Singe decodifica un archivo de música en memoria de entrada, exactamente igual que un efecto de sonido. Una pista larga cuesta memoria. No se va leyendo del disco a trozos. Cinco minutos de música son unas cuantas decenas de megabytes de memoria mientras está cargada, así que carga la pista del nivel en el que estás y descárgala con musicUnload cuando salgas.

Reproducir una pista

Todos los lectores de este libro tienen ya una pieza de música, porque el motor desempaquetó una en tu carpeta de trabajo la primera vez que ejecutaste algo. Empieza un archivo con estas tres líneas:

local theme = musicLoad("Singe/menuIntro.flac")
musicSetVolume(64)
musicPlay(theme, -1)


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Music: " .. (musicIsPlaying(theme) and "playing" or "stopped"))
    return OVERLAY_UPDATED
end

Ejecútalo con Singe -R music. Diez segundos de música, y luego vuelve a empezar, y sigue volviendo a empezar.

Eso es lo que hace el -1. musicPlay recibe un número de repeticiones: omítelo o pasa 0 y la pista suena una vez, pasa 3 y suena cuatro veces en total, y pasa -1 y se repite hasta que algo la pare. Un menú, una pantalla de título o el fondo de un nivel casi siempre llevan -1.

Dos detalles de ese pequeño script merecen la tinta. musicLoad recibe una ruta y no una ruta DIR .., porque Singe/menuIntro.flac es uno de los archivos propios del motor y está en la carpeta que el motor desempaquetó en tu carpeta de trabajo. musicIsPlaying responde true o false, y el and …​ or …​ en medio de ese overlayPrint es la abreviatura de Lua de la lección tres para elegir uno de dos valores.

La escala de volumen no es la que conoces

musicSetVolume(64) lo pone más o menos a la mitad. Los efectos de sonido van de 0 a 63; la música va de 0 a 128, que es el doble.

Eso no es un error y no es una broma. Singe puede ejecutar juegos escritos para Hypseus, un motor cuyo volumen de música siempre ha sido una escala de 0 a 128, y cambiar los números haría, sin avisar, que la música de esos juegos sonara el doble de fuerte de lo que pretendían sus autores. Así que Singe mantiene las dos escalas, cada una unida a la familia de llamadas a la que pertenece. Efectos: de 0 a 63. Música: de 0 a 128. Dale a musicSetVolume un número fuera de su rango y el script se para, como verás por ti mismo al final de esta lección.

Qué reproduce Singe

Casi cualquier cosa. WAV, Ogg Vorbis, Opus, MP3, FLAC, WavPack, AAC y una larga lista más, todo con el mismo musicLoad.

Hay dos familias más interesantes que las corrientes, y las dos existen porque son diminutas.

Los módulos de tracker — .mod, .s3m, .xm, .it y otros cincuenta y tantos parientes — guardan un puñado de instrumentos grabados cortos y una lista de qué notas tocar con ellos. Una melodía de cuatro minutos puede ocupar menos de cien kilobytes.

Los chiptunes — .nsf, .spc, .vgm, .gbs y su familia — van más allá: guardan las escrituras en registros del chip de sonido real de una Nintendo, una Mega Drive o un Spectrum, y Singe emula el chip para reproducirlos. Si quieres que un juego suene a 1989 en lugar de sonar a una grabación de 1989, así es como se hace.

Cualquiera de los dos se carga con musicLoad como todo lo demás. La sección Formatos de vídeo, audio y contenedor de la referencia tiene la lista completa, incluido qué contenedor va con qué códec.

Parar, pausar y desvanecer

musicPause(theme)
musicResume(theme)
musicStop(theme)
musicStop(theme, 2000)

musicPause deja la pista donde está y musicResume sigue desde ese punto. musicStop la termina, y la pista vuelve a su principio la próxima vez que la reproduzcas. Con un segundo número, musicStop desvanece la pista durante esos milisegundos en lugar de cortarla en seco — aquí, dos segundos. Ese desvanecimiento es lo más fácil que puedes hacer para que un juego parezca terminado. La música que se para a mitad de compás cuando el jugador cruza una puerta suena a fallo, incluso para alguien que no sabría decir por qué.

Llama a cualquiera de las cuatro sin ningún handle y actúan sobre todas las piezas de música a la vez, que es lo que quiere una pantalla de pausa.

Ahora el límite sincero, porque lo vas a buscar y no está: Singe no puede hacer un fundido cruzado entre dos pistas. musicSetVolume es una sola ganancia para toda la música, no un volumen por pista, así que no hay forma de subir una pista mientras otra baja. Lo que sí puedes hacer es desvanecer la vieja y empezar la nueva mientras se va, que basta para un cambio de nivel y se nota que no es lo mismo para un tema de batalla que entra por debajo de un tema de exploración. Si hoy necesitas un fundido cruzado de verdad, la forma de conseguirlo es hacer de las dos piezas un solo archivo y saltar dentro de él, o aceptar el solapamiento.

Música, vídeo e ir a compás

Si tu juego reproduce vídeo — el tema de la tercera parte — hay una cosa que saber sobre el sonido, y no es una llamada de música en absoluto.

Singe muestra un fotograma de vídeo cuando se oye el sonido que le corresponde, no según un temporizador. El audio es el reloj y la imagen lo sigue. Ese es el orden correcto, porque un oído nota una quinta parte de segundo de desfase en una voz y un ojo no nota el mismo desfase en una boca.

El motor mide su propio camino de audio al arrancar. Lo que no puede medir es todo lo que viene después de que el sistema operativo entregue el sonido: un amplificador, un televisor, un receptor HDMI, unos auriculares Bluetooth. Cada uno de ellos añade un retraso propio, es distinto en cada máquina, y se nota como un sonido que llega un poco después de lo que lo produjo.

El arreglo es un número:

singeSetAudioDelay(45)

Cuarenta y cinco milisegundos de «el audio va tarde; retrasa la imagen para que coincida». También puedes pasarlo como --audiodelay=45 en la línea de comandos o ponerlo en la entrada del juego en games.dat. singeGetAudioDelay lee el valor que esté en vigor, que es lo que muestra un menú de servicio junto a su deslizador.

No tienes que adivinar el número. El propio menú de Singe tiene una pantalla de calibración: reproduce un clic una vez por segundo y pone la pantalla en blanco un instante, tú ajustas hasta que el destello y el clic ocurren a la vez, y guarda el resultado para todos los juegos de esa máquina. La sección Sincronización del audio de la referencia la describe y explica por qué funciona. Si construyes una recreativa, pásala una vez después de cablear los altavoces y no vuelvas a pensar en ello.

La otra cosa llamada MIDI

MIDI son dos cosas sin relación con un mismo nombre, y separarlas es casi todo lo que hace falta para entenderlo.

Aquí va la primera, en un párrafo. Una grabación — un .wav, un .mp3 — es una medida de un sonido, tomada cuarenta y cuatro mil veces por segundo. MIDI no es eso. Un archivo MIDI guarda lo que se tocó: en este momento, en este canal, pulsa la tecla sesenta con esta fuerza; un poco después, suéltala. Se parece más a una partitura, o al rollo perforado de una pianola, que a una grabación. Por eso un archivo MIDI ocupa unos pocos kilobytes cuando la misma música en audio ocupa unos pocos megabytes, y también por eso un archivo MIDI no contiene ningún sonido en absoluto. Algo tiene que tocar las notas.

Un archivo MIDI es música, así que se reproduce como la música:

local tune = musicLoad("music/overworld.mid")
musicPlay(tune, -1)

Pero lo que toca las notas tiene que salir de algún sitio, y eso es un soundfont: un archivo lleno de instrumentos grabados — un piano, una trompeta, una caja de batería — con las notas y los puntos de bucle marcados, para que el motor pueda construir cualquier nota de cualquier instrumento a partir de ellos.

Singe no trae ninguno. Un buen soundfont ocupa decenas de megabytes, y serían decenas de megabytes que cargaría cada copia del motor para un formato que la mayoría de los juegos no tocan nunca. Así que indicas uno con --soundfont, o pones uno en Singe/soundfont.sf2 para que un juego empaquetado lleve el suyo, o dejas que Singe encuentre el que instaló tu distribución de Linux. Sin ningún soundfont por ninguna parte, cargar un .mid falla y lo dice.

Por eso el mismo archivo MIDI suena distinto en dos máquinas y por eso sonaba tan mal en los ordenadores de los años noventa. El archivo es una lista de notas. Lo que oyes es el soundfont que haya tocado esas notas: uno bueno es una sala llena de instrumentos, uno barato es una sala llena de juguetes, y las notas son idénticas en los dos. Si un archivo MIDI va en tu juego, distribuye el soundfont con él. Si no, no has elegido cómo suena tu música; lo has dejado en manos de lo que tenga instalado la máquina del jugador.

MIDI como cable

Ahora la segunda cosa, que es la interesante.

MIDI también es un cable, y los mensajes que viajan por él. Enchufa un teclado musical a tu ordenador y cada tecla que pulses envía un mensaje: note on, canal 1, tecla 60, velocidad 90. Gira un potenciómetro de una superficie de control y envía el controlador 7 del canal 1 vale ahora 40. Estos mensajes existen tanto si algo está reproduciendo música como si no. Son otro dispositivo de entrada, como un joystick con ochenta y ocho botones que saben con qué fuerza los golpeas.

Y funciona en el otro sentido. Tu juego puede enviar esos mensajes hacia fuera, a un sintetizador, un módulo de sonido, un controlador de luces de escenario o cualquier otra cosa que haya en el cable.

Los puertos se numeran desde cero, y Singe no abre nada hasta que se lo pides — un juego que nunca menciona MIDI nunca paga por MIDI. Puede haber un puerto de entrada y un puerto de salida abiertos a la vez. Haz inventario de la máquina así:

local inPort  = "none"
local outPort = "none"

if midiInputCount() > 0 and midiOpenInput(0) then
    inPort = midiInputName(0)
end
if midiOutputCount() > 0 and midiOpenOutput(0) then
    outPort = midiOutputName(0)
end

En una máquina sin nada de MIDI los recuentos son cero, las llamadas que abren responden false y nada falla. Eso importa: significa que puedes escribir este código en un juego de verdad y publicarlo, y los noventa y nueve de cada cien jugadores que no tienen teclado MIDI nunca sabrán que está ahí. Los nombres son para una pantalla de ajustes que deje al jugador elegir qué puerto, porque el puerto cero rara vez es el que quiere. midiRescan vuelve a buscar algo enchufado mientras el juego está en marcha.

Escuchar

Cada mensaje que llega va a un callback, igual que cada pulsación de tecla va a onInputPressed:

local MIDI_NOTE_ON = 0x90


function onMidiMessage(status, data1, data2, bytes)
    if (status & 0xF0) ~= MIDI_NOTE_ON or data2 == 0 then
        return
    end
    heard = noteName(data1)
end

La mayoría de los mensajes MIDI tienen tres bytes, y los tres números que recibes son esos bytes tal y como los envió el dispositivo. Un mensaje con menos bytes te da un 0 en lugar de cada uno que no tiene.

status dice qué tipo de mensaje es y de qué canal viene, mezclado: el tipo son los cuatro bits de arriba y el canal los cuatro de abajo. 0x90 es note on, y una nota en el canal 1 llega como 0x90 mientras que la misma nota en el canal 5 llega como 0x94. status & 0xF0 se queda con la mitad de arriba y tira el canal, que es lo que quieres a menos que te importe de qué canal venía. (& es el «y» bit a bit de Lua, y 0x90 es un número escrito en hexadecimal — base dieciséis — porque así los escriben todos los documentos MIDI del mundo.)

data1 y data2 son los otros dos bytes, y lo que significan depende del tipo. Para un note on son la tecla y la velocidad: la tecla 60 es el do central, y la velocidad es con qué fuerza se tocó, de 1 a 127.

La comprobación de data2 == 0 no es por manía. Un note on con velocidad cero significa note off: así dice casi cualquier teclado que se haya fabricado «he soltado», y si no lo filtras tu juego saltará dos veces por cada tecla.

bytes es el mensaje entero como cadena, que es como lees un mensaje de más de tres bytes.

Tocar

Enviar es más fácil que recibir.

midiNoteOn(1, 60, 100)
midiNoteOff(1, 60)

Do central en el canal 1, tocado a cien y luego soltado. Aquí los canales van de 1 a 16 como los cuenta una persona, no de 0 a 15 como el cable, que es Singe siendo amable contigo.

Cada midiNoteOn necesita un midiNoteOff. Una nota que nunca se suelta suena hasta que algo la para, y el primer fallo MIDI clásico es un juego que se cuelga o se cierra con tres notas pulsadas y deja un acorde flotando en la habitación. Así que emparéjalas, y emparéjalas con un temporizador en lugar de a mano:

function playTarget()
    if not midiIsOutputOpen() then
        return
    end
    local key = target
    midiNoteOn(1, key, 100)
    timerAfter(HOLD_MS, function()
        midiNoteOff(1, key)
    end)
end

local key = target hace un trabajo de verdad. timerAfter ejecuta su función cuatro décimas de segundo después, y para entonces target puede haber cambiado a otra nota; copiarlo en una variable local significa que el temporizador suelta la nota que se pulsó de verdad. Copia todo lo que un temporizador vaya a necesitar más tarde.

Las demás llamadas de envío hacen el resto de lo que es MIDI: midiProgramChange elige qué instrumento toca un canal, midiControlChange mueve un controlador (el volumen es el 7, el panorama el 10, el pedal de sostenido el 64), midiPitchBend dobla la afinación de un canal y midiSend envía cualquier mensaje como bytes en bruto para lo que no cubren las llamadas con nombre.

Un motivo para que te importe

Todo eso es maquinaria. Esto es para lo que sirve.

Junta las dos mitades y el juego pide una nota, el jugador la toca en un instrumento de verdad y el juego sabe si ha acertado:

function onMidiMessage(status, data1, data2, bytes)
    if (status & 0xF0) ~= MIDI_NOTE_ON or data2 == 0 then
        return
    end
    heard = noteName(data1)
    if data1 == target then
        score = score + 1
        pickTarget()
        playTarget()
    end
end

Once líneas, y tienes el esqueleto de un juego para enseñar música. Añade un reloj y tienes un juego de ritmo que puntúa a alguien tocando de verdad en lugar de cuatro botones de plástico. Añade data2 a la comprobación y le importará con qué fuerza tocas la nota. Compara la hora a la que llegó la nota con la hora a la que tocaba y estarás evaluando la sincronización al milisegundo.

Y como MIDI sale además de entrar, una recreativa puede hacer cosas que nada más puede. Un instrumento de verdad conectado a la máquina. Un módulo de sonido externo tocando la partitura para que la melodía tenga una profundidad que ningún banco de muestras le da. Luces de escenario en la recreativa que destellan al ritmo porque el juego les ha enviado el ritmo. Si eres de los que construyen máquinas recreativas, esta es la llamada que permite que la recreativa sea algo en vez de una caja alrededor de un ordenador.

El script terminado es learn/27-midi.singe: los controles de la música, la lista de puertos y el juego de adivinar, en unas cien líneas. La barra espaciadora envía la nota, la tecla Alt izquierda pausa la música, la tecla Mayús izquierda la desvanece y las teclas de flecha arriba y abajo mueven el volumen. Ejecútalo sin hardware MIDI y la mitad musical funciona y la mitad MIDI dice none dos veces, que es como debe comportarse en la máquina de un jugador.

Recoger

function onShutdown()
    midiCloseInput()
    midiCloseOutput()
    musicUnload(theme)
end

onShutdown se llama una vez cuando el juego termina, y es donde un script devuelve las cosas. Cerrar un puerto que no está abierto no hace nada, así que no hay nada que comprobar antes.

Pruébalo

  1. Que dé cuatro vueltas en lugar de infinitas. Cambia musicPlay(theme, -1) por musicPlay(theme, 3) y cuenta. El número es cuántas veces se repite, no cuántas veces suena.

  2. Desvanece durante más tiempo. Cambia el desvanecimiento del botón que para la música a musicStop(theme, 4000) y escucha la diferencia que marcan cuatro segundos. Luego prueba musicStop(theme, 100).

  3. Muestra el canal. En onMidiMessage, calcula el canal con (status & 0x0F) + 1 e imprímelo. Toca tu teclado y mira en qué canal está — y luego busca sus ajustes y cambia ese canal, para demostrarte que el número es real.

  4. Puntúa la velocidad. Da un punto por la nota correcta, y tres puntos si data2 pasa de cien, para que el juego premie tocarla con ganas.

  5. Toca la respuesta. Cuando el jugador acierte una nota, haz que el juego le devuelva un pequeño acorde con tres llamadas a midiNoteOn separadas un par de notas y tres temporizadores para soltarlas. Para esto necesitarás un puerto de salida de verdad o un sintetizador por software, y en Linux eso es cualquier programa que se registre en ALSA.

Rómpelo a propósito

Las dos escalas de volumen son fáciles de confundir, y Singe prefiere pararse antes que reproducir tu música a un nivel que no querías. Añade una línea debajo de musicPlay(theme, -1), usando el número que sería el volumen máximo de un efecto de sonido si lo duplicaras de cabeza y te equivocaras:

musicSetVolume(200)

Singe se para antes de que arranque el juego, nombrando la línea de tu archivo en la que está esa llamada:

107:musicSetVolume:  Invalid music volume value:  200

La línea, la llamada que protestó y la queja, que aquí te repite el número para que no haya discusión sobre lo que llegó. La música va de 0 a 128. Los efectos de sonido van de 0 a 63. Cuando una llamada de volumen para tu juego, la pregunta que tienes que hacerte es con cuál de las dos familias estás hablando.

Lo que has aprendido

  • La música y los efectos de sonido van por separado en Singe: sus propios volúmenes, sin límite de canales para la música y una pausa que sigue a la pausa del juego.

  • Un archivo de música se decodifica en memoria de entrada, así que una pista larga cuesta memoria y conviene descargarla cuando sales del nivel.

  • musicPlay(track, -1) se repite para siempre; un número positivo es cuántas veces se repite.

  • El volumen de la música va de 0 a 128 y el de los efectos de 0 a 63, y la diferencia es por compatibilidad con Hypseus, no un error.

  • musicStop(track, milliseconds) desvanece la música, y un desvanecimiento es el pulido más barato que hay. No hay fundido cruzado, porque una sola ganancia cubre toda la música.

  • Singe presenta el vídeo según el reloj del audio, y singeSetAudioDelay corrige el retraso de lo que sea por donde sale el sonido.

  • Un archivo MIDI guarda notas, no sonido, y necesita un soundfont para que se oiga algo. Singe no trae ninguno, así que distribuye el tuyo o tu música será lo que la máquina del jugador tenga a mano.

  • Los puertos MIDI son otra cosa por completo: mensajes en directo que entran y salen, por un cable, sin nada que ver con los archivos MIDI.

  • onMidiMessage te da los bytes en bruto. Los cuatro bits de arriba de status son el tipo, los cuatro de abajo son el canal, y un note on con velocidad cero significa note off.

  • Cada midiNoteOn necesita un midiNoteOff, y un temporizador es la forma de emparejarlos.

  • En una máquina sin MIDI, todas las llamadas responden false o cero y nada falla, así que el soporte de MIDI es seguro de publicar.

La próxima vez

Tu juego tiene música, y una puntuación que un teclado MIDI puede hacer subir. La lección veintiocho saca esa puntuación de la máquina: cuentas, tablas de récords que otras personas pueden ver y el catálogo que presenta tu juego al mundo.

Lección 28: En línea

La lección terminada

En la lección doce guardaste un récord. Sigue ahí a la mañana siguiente, que es casi todo para lo que sirve un récord, pero es un récord de una sola máquina. Esta lección pone una puntuación en una tabla de récords que otras personas pueden ver.

También es la lección sobre los fallos. Todo lo demás que has escrito falla por motivos que puedes encontrar: falta un archivo, un número está mal, una función está mal escrita. La red falla por motivos que nadie en la habitación puede ver. Alguien desenchufó un cable en un edificio en el que nunca has estado, y tu juego tiene que seguir funcionando. Casi todo lo que viene ahora trata de eso.

Qué es el servicio

Singe puede hablar con un servicio maestro, un servidor que guarda tres cosas:

  • una cuenta, que pertenece a la máquina y no a ningún juego en concreto;

  • un catálogo de juegos para descargar y actualizar;

  • tablas de récords, una o más por juego.

El servicio por defecto es master.singeengine.com, y un operador que tenga el suyo propio apunta la máquina a otro sitio. La sección del manual sobre el servicio en línea describe las dos partes.

Ahora la parte que la gente se salta. El servicio no es multijugador: no hay forma de que dos jugadores estén en la misma partida. No es una nube de partidas guardadas; la partida guardada de la lección doce se queda en la máquina. No es una protección anticopia, y nada en él impide que nadie juegue a tu juego. No es obligatorio: un juego que nunca inicia sesión funciona exactamente igual que siempre, que es el único valor por defecto sensato para algo que necesita una conexión que funcione.

Así que la tabla de récords es un extra. Conserva el récord local de la lección doce, sigue mostrándolo y deja que la tabla en línea sea eso que a veces está.

La sesión se inicia una vez, y no en tu juego

La cuenta pertenece a la máquina. Se crea, y se inicia sesión con ella, desde el menú incluido, detrás de la tecla asignada a INPUT_SERVICE, en la herramienta llamada Online Account. El token que obtiene se escribe en master.dat en la raíz de datos, un nivel por encima de la carpeta de datos de cada juego, así que todos los juegos de la máquina publican sus puntuaciones con la misma sesión.

Tu juego nunca pide una dirección de correo electrónico y nunca pide una contraseña. No hay ninguna función para hacerlo, y es a propósito: un jugador que escribe una contraseña en un juego que ha descargado no tiene forma de saber adónde va.

Lo que aparece de un jugador en una tabla de récords es un alias: de tres a veinte caracteres entre letras, dígitos, guiones y guiones bajos, empezando y terminando con una letra o un dígito. Sin espacios, sin puntos y sin @, así que un alias ni siquiera puede parecer una dirección de correo electrónico. Se guarda aparte de la cuenta, es lo único de un jugador que ven los demás jugadores, y se elige una vez — un operador puede cambiarlo, un jugador no, porque una tabla de récords cuyos nombres no paran de cambiar no es realmente la historia de nadie. Hasta que se ha elegido un alias, las puntuaciones se rechazan, ya que una puntuación sin el nombre de nadie no está en una tabla de récords en ningún sentido útil.

La herramienta Online Account muestra el nombre con el que publica esta máquina, y tu juego lo lee con scorePlayerName(), que responde nil cuando no hay ninguno. Conviene saberlo antes de que te desconcierte: una puntuación enviada sin alias detrás la rechaza el servicio, no scoreSubmit, así que a tu juego no se le dice nada. Si scorePlayerName() es nil, dilo en pantalla mientras todavía haya alguien delante para leerlo.

Tu juego necesita un identificador

Una tabla de récords tiene que guardarse bajo algo. Ese algo es GAME_ID en la entrada de tu juego en games.dat, el archivo que hiciste en la lección trece:

GAME_ID = "6f1e7b62-0a4e-4d9c-9b2f-1c7a5e3d8a10"

Es un UUID, exactamente con esa forma: ocho dígitos hexadecimales, tres grupos de cuatro y luego doce, separados por guiones. Genera uno como quieras y pégalo; no importa cuál te salga, solo que no cambie nunca más. La entrada de la referencia para singeGetGameId explica por qué no se acepta nada más.

singeGetGameId() lo devuelve, o nil cuando la entrada no tiene ninguno. Un juego sin identificador se puede jugar pero no puede entrar en ninguna clasificación, y preguntar primero es la forma de no ofrecer una tabla de récords que no puede funcionar nunca:

if singeGetGameId() then
    -- showLeaderboardButton es una función tuya, no una de las de Singe.
    showLeaderboardButton()
end

Las seis llamadas

Todo lo que hace un juego con el servicio son seis funciones, y vienen de Singe/Framework.singe, así que aquí el dofile del principio de tu script no es opcional:

dofile("Singe/Framework.singe")

scoreBegin() dice que empieza una partida. scoreSubmit(value) pone una puntuación en la cola. scoreBoard(onDone) trae la tabla de récords. scorePlayerName() es el alias. scoreWaiting() es cuántas puntuaciones no han salido todavía. Y scoreUpdate() tiene que ejecutarse una vez por fotograma, desde onOverlayUpdate, o ninguna de las demás termina nunca.

Esa última es todo el truco de esta lección, así que se dice dos veces. Nada de esto habla con la red cuando lo llamas. scoreSubmit escribe en una cola y vuelve enseguida. scoreBoard recuerda lo que quieres y vuelve enseguida. El trabajo de verdad se hace a trocitos dentro de scoreUpdate, entre tus fotogramas, y por eso tu juego nunca da tirones mientras la conexión va lenta. Quita scoreUpdate y nada se rompe, nada da error, y nunca pasa nada.

function onOverlayUpdate()
    scoreUpdate()
    overlayClear()
    return OVERLAY_UPDATED
end

Publicar una puntuación

Al final de una partida:

if scoreSubmit(score) then
    fetchBoard()
else
    saying = "Kept here only:  " .. whyNotPosted()
end

scoreSubmit responde false cuando no hay cuenta o el juego no tiene GAME_ID, y true cuando la puntuación ha entrado en la cola. Fíjate en lo que no hace el else: no tira la puntuación, no se deshace en disculpas y no impide que el jugador empiece otra partida. Dice una línea corta, porque el jugador no ha hecho nada mal y no puede arreglarlo desde aquí.

La cola es la razón de que esto sea seguro. Una puntuación en la cola se escribe en disco, así que sobrevive a que se apague la máquina, y se entrega al servicio la próxima vez que haya conexión — una hora después, o el martes que viene. Por eso una recreativa en un local con un wifi malo acaba igualmente en la tabla de récords.

Sé sincero contigo mismo sobre el límite de esa promesa: la cola guarda puntuaciones de una máquina que tiene cuenta. Si nadie inició sesión nunca, scoreSubmit responde false y la puntuación no se guarda para más tarde, porque no hay nadie para quien guardarla. scoreWaiting() te dice cuántas quedan en la cola, y mostrar ese número en algún sitio es un detalle: es la diferencia entre «el servicio está roto» y «tres de tus puntuaciones están esperando a que vuelva internet».

scoreBegin() merece un párrafo propio. Llámala cuando empiece una partida, y el servicio apunta el momento según su propio reloj. La puntuación que venga después lleva cuánto duró la partida, medido en el servidor, que es el único número de un envío que no ha pasado por la máquina del jugador. No se rechaza nada por él: se le muestra a quien gestiona el servicio, junto a la puntuación, y decide una persona. Una máquina que estaba sin conexión cuando empezó la partida no registra ningún tiempo, lo cual es sincero, no un fallo.

Y ya que estamos siendo sinceros: una puntuación enviada es una afirmación. El juego se ejecuta en el ordenador del jugador, así que nada que pueda hacer el cliente la convierte en algo más, y una clave secreta incluida en tu juego solo aparentaría seguridad. El servicio registra quién afirmó qué, limita lo deprisa que pueden llegar las puntuaciones y marca las disparatadas para que las mire una persona. Diseña tu tabla de récords sabiéndolo.

Leer la tabla de récords

scoreBoard es la primera función de este libro que recibe una función como argumento.

scoreBoard(function(ok, result)
    ...
end)

Escribiste funciones en la lección cinco y les diste nombre. Esta no tiene nombre: se escribe donde se usa, se le pasa directamente a scoreBoard y se llama más tarde — quizá segundos más tarde — cuando llega la respuesta. Eso es otra vez un callback, la misma idea que onOverlayUpdate, salvo que esta vez eliges tú quién lo llama.

ok es true o false. Cuando es false, result es una cadena corta que dice por qué. Cuando es true, result es una tabla con dos partes:

  • result.top, una lista de filas, cada una con un name y un value;

  • result.standing, el value y el rank propios de este jugador y el número de players de la tabla de récords — que puede faltar, si este jugador no tiene nada en ella.

Entre la llamada y el callback tu juego sigue funcionando y dibujando. Ese hueco es real y el jugador lo ve, así que pon algo en él. El script de abajo pone una línea de texto en "Asking the service…​" antes de llamar, y el callback sustituye esa línea por la tabla de récords o por el motivo de que no la haya. Una pantalla que no dice nada durante cuatro segundos parece rota; una pantalla que dice lo que está haciendo solo es lenta.

El catálogo

Lo tercero que hace el servicio es listar juegos. La herramienta Get Games del menú muestra todo lo que ofrece el servicio, marca lo que ya está instalado en esta máquina y lo descarga, lo actualiza o lo quita. Una descarga se comprueba con el hash que publicó el catálogo antes de sustituir nada, así que una transferencia que llega dañada falla en lugar de instalar un juego que no funcionará. Un juego que el servicio ha retirado sigue funcionando y aparece como instalado pero ya no ofrecido: lo único que deja de pasar es que reciba actualizaciones, porque quien tiene un juego lo tiene.

Tu juego no llama a nada de esto, y no debería. El catálogo te importa como autor de un juego más que como escritor de un script: es adonde va tu archivo .game cuando lo publicas, que es la lección treinta, y es otra razón por la que tu games.dat necesita un GAME_ID que no cambie nunca. Si alguna vez quieres la lista desde dentro de un script, Singe/Master.singe es el módulo que hay debajo de todo esto y merece la pena leerlo una vez.

Lo que el servicio sabe de un jugador

Si publicas un juego que envía puntuaciones, le estás pasando datos de otra persona a un servidor, y eso es responsabilidad tuya aunque no hayas escrito el servidor. Así que dilo claramente, en la pantalla de información o en el léeme de tu propio juego:

  • El servicio guarda una dirección de correo electrónico y una contraseña para la cuenta. La dirección sirve para recuperar una contraseña perdida y para nada más. Nunca se muestra a otros jugadores y no se puede cambiar después.

  • El alias es lo que aparece en las tablas de récords. Se mantiene aparte de la cuenta a propósito para que una dirección no sea nunca lo que ven los demás jugadores, y se comprueba contra una lista de nombres que nadie debería reclamar y de palabras que no pintan nada en una pantalla en un local público.

  • Una puntuación lleva su valor, la tabla de récords en la que está, la hora que registró el servicio y el alias. Nada más.

  • El catálogo sabe qué juegos están instalados en la máquina, y qué versión, porque así es como te ofrece una actualización.

Lo que no hace nada de esto es seguir a un jugador de un juego a otro, vender nada ni meterse en la máquina a buscar algo que tú no hayas enviado. Tu juego no debería añadir nada a la lista. Si adjuntas información extra a una puntuación — scoreSubmit acepta un tercer argumento opcional para eso — que trate del juego.

El script

Una prueba de reflejos: espera a la palabra, pulsa el botón y puntúa lo que quede de mil. Es un juego pequeño, y el resto es la parte en línea.

Crea una carpeta llamada reaction y pon esto en reaction.singe, dentro de ella. Dale a la carpeta un games.dat como el de la lección trece, que nombre reaction/reaction.singe, con la línea GAME_ID de antes en su entrada.

dofile("Singe/Framework.singe")

local WAIT_MIN = 1000
local WAIT_MAX = 3000
local PERFECT  = 1000

local state    = "attract"
local goAt     = 0
local score    = 0
local best     = saveGet("best", 0)
local saying   = "Button 1 to play."
local top      = nil
local standing = nil


local function whyNotPosted()
    if not singeGetGameId() then
        return "this game has no GAME_ID."
    end
    return "this machine is not signed in."
end


local function fetchBoard()
    top      = nil
    standing = nil
    saying   = "Asking the service..."
    scoreBoard(function(ok, result)
        if not ok then
            saying = "No board:  " .. tostring(result)
            return
        end
        top      = result.top
        standing = result.standing
        if #top == 0 then
            saying = "The board is empty.  You could be first."
        else
            saying = ""
        end
    end)
end


local function finish(reaction)
    score = PERFECT - reaction
    if score < 0 then
        score = 0
    end
    if score > best then
        best = score
        saveSet("best", best)
    end
    state = "result"
    if scoreSubmit(score) then
        fetchBoard()
    else
        saying = "Kept here only:  " .. whyNotPosted()
    end
end


local function play()
    state    = "waiting"
    goAt     = singeGetTicks() + math.random(WAIT_MIN, WAIT_MAX)
    score    = 0
    top      = nil
    standing = nil
    saying   = ""
    scoreBegin()
end


function onInputPressed(what)
    if what ~= SWITCH_BUTTON1 then
        return
    end
    if state == "waiting" then
        state  = "result"
        score  = 0
        saying = "Too soon.  Nothing posted."
    elseif state == "go" then
        finish(singeGetTicks() - goAt)
    else
        play()
    end
end


function onOverlayUpdate()
    scoreUpdate()

    if state == "waiting" and singeGetTicks() >= goAt then
        state = "go"
    end

    overlayClear()
    overlayPrint(2, 0, "REACTION TEST")

    if state == "attract" then
        overlayPrint(2, 2, "Button 1 to play.")
    elseif state == "waiting" then
        overlayPrint(2, 2, "Wait for it...")
    elseif state == "go" then
        overlayPrint(2, 2, "NOW!")
    else
        overlayPrint(2, 2, "You scored " .. score .. ".  Button 1 plays again.")
    end

    overlayPrint(2, 4, "Best on this machine:  " .. best)
    overlayPrint(2, 5, "Posting as:  " .. (scorePlayerName() or "nobody yet"))
    overlayPrint(2, 6, "Waiting to send:  " .. scoreWaiting())
    overlayPrint(2, 8, saying)

    if top then
        for place, row in ipairs(top) do
            if place > 5 then
                break
            end
            overlayPrint(2, 9 + place, place .. ".  " .. row.name .. "  " .. row.value)
        end
    end
    if standing then
        overlayPrint(2, 16, "You are " .. standing.rank .. " of " .. standing.players .. ".")
    end

    return OVERLAY_UPDATED
end

Ejecútalo con Singe -R reaction. En una máquina que nunca ha iniciado sesión, se juega, guarda tu mejor puntuación y dice Kept here only: this machine is not signed in. Esa es la ejecución importante, y es la que tendrán la mayoría de tus jugadores.

Qué acaba de pasar

local top      = nil
local standing = nil

Dos variables que son nil casi todo el tiempo. nil significa «aquí no hay nada», y es lo que contiene una variable antes de que se meta nada en ella. Estas guardan la tabla de récords cuando la hay, y nil cuando no: mientras la petición está en camino, después de un fallo y antes de la primera partida. El código de dibujo pregunta if top then y no dibuja nada cuando no hay nada, que es la forma de casi cualquier trozo de código de red que escribas.

    saying   = "Asking the service..."
    scoreBoard(function(ok, result)

El orden importa. La línea de texto se pone antes de la llamada, porque la llamada vuelve enseguida y el callback puede tardar segundos en ejecutarse. Si pones el texto solo dentro del callback, la pantalla muestra el mensaje de la partida anterior hasta que llega la respuesta, que es exactamente el mensaje equivocado en exactamente el momento equivocado.

        if not ok then
            saying = "No board:  " .. tostring(result)
            return
        end

El fallo va primero, y es corto. tostring convierte lo que haya vuelto en texto para que unirlo con .. no pueda fallar; result es una cadena cuando ok es false, pero una línea de código de dibujo que se fía del tipo de algo que le ha llegado de un servidor es una línea esperando a romperse. El jugador ve una frase y el juego sigue.

    if scoreSubmit(score) then
        fetchBoard()
    else
        saying = "Kept here only:  " .. whyNotPosted()
    end

Que scoreSubmit responda false no es un error. Es un hecho sobre esta máquina, y merece la pena distinguir los dos hechos que puede significar, que es lo que hace whyNotPosted: que falte GAME_ID es error tuyo, y una máquina sin sesión iniciada no es error de nadie. La mejor puntuación local ya se guardó, dos líneas más arriba, antes de intentar nada de esto. Primero guarda, luego publica, siempre.

    overlayPrint(2, 6, "Waiting to send:  " .. scoreWaiting())

La cola, en pantalla. En una máquina con conexión esto marca 0 para siempre y nadie se fija. En una máquina sin ella sube, y el jugador sabe que el juego le está guardando las puntuaciones en lugar de comérselas.

function onOverlayUpdate()
    scoreUpdate()

La primera línea del fotograma, antes que nada. Ponla en algún sitio donde un if no pueda saltársela, porque un scoreUpdate que solo se ejecuta en la pantalla de fin de partida es una cola que solo se vacía en la pantalla de fin de partida.

Pruébalo

  1. Desenchúfalo. Desconecta la máquina de la red, juega unas cuantas partidas y mira el número Waiting to send. Vuelve a conectarla y mira cómo baja sin que hagas nada.

  2. Borra el identificador. Quita GAME_ID de tu games.dat y vuelve a ejecutarlo. El mensaje cambia. Vuelve a ponerlo.

  3. Muestra más de la tabla de récords. El bucle se para en cinco filas. El overlay mide dieciocho filas de caracteres de alto por defecto, así que calcula cuántas te caben de verdad, y mueve la línea de standing si hace falta.

  4. Ponle nombre a la tabla. scoreSubmit(score, "reaction") y scoreBoard(onDone, "reaction") usan una tabla de récords con ese nombre en lugar de la que lleva el nombre de tu script. Publica en dos tablas desde el mismo juego — por ejemplo, una para la puntuación y otra para la reacción más rápida — y deja que el botón 2 cambie cuál se muestra.

  5. Haz visible la espera. Entre la llamada a scoreBoard y la ejecución del callback, dibuja un punto que se mueva. Luego averigua cuánto dura eso de verdad con tu conexión, y si merecía la pena dibujarlo.

Rómpelo a propósito

Quita la primera línea de onOverlayUpdate, para que desaparezca la llamada a scoreUpdate(), y juega una partida.

No pasa nada. Ni error, ni mensaje, ni tabla de récords, y el número Waiting to send sube y se queda arriba para siempre. El juego funciona perfectamente.

Este es el peor tipo de fallo y merece la pena encontrárselo una vez a propósito: un paso que falta y que produce silencio en lugar de una queja. No hay número de línea que mirar, porque no ha ido nada mal — pediste trabajo y luego nunca le diste ocasión de hacerse. Cuando algo de Singe que recibe un callback no te devuelve nunca la llamada, la primera pregunta es siempre si lo que lo mueve se está ejecutando en cada fotograma.

El otro que te encontrarás hace más ruido. Vuelve a poner scoreUpdate(), borra la línea dofile del principio y ejecútalo:

Error executing function 'onOverlayUpdate':  reaction/reaction.singe:89: attempt to call a nil value (global 'scoreUpdate')
stack traceback:
	reaction/reaction.singe:89: in function 'onOverlayUpdate'

La línea 89 es el scoreUpdate() que volviste a poner, una línea más arriba ahora que el dofile ya no está. Lee la primera línea como siempre: la función a la que estaba llamando el motor, el archivo, la línea y la queja. nil otra vez — el nombre scoreUpdate no tiene nada dentro, porque el archivo que lo define nunca se cargó. Las seis llamadas viven en Singe/Framework.singe.

Lo que has aprendido

  • El servicio guarda una cuenta, un catálogo y tablas de récords. No es multijugador, no es una nube de partidas guardadas y nunca es obligatorio.

  • La cuenta pertenece a la máquina y se inicia sesión con ella desde las herramientas de servicio del menú. Un juego nunca pide una contraseña.

  • Una tabla de récords se guarda bajo el GAME_ID de games.dat, un UUID que no debe cambiar nunca. singeGetGameId() lo lee.

  • scoreSubmit pone una puntuación en la cola en disco y vuelve enseguida; la cola sobrevive a que se apague la máquina.

  • scoreUpdate() tiene que ejecutarse en cada fotograma o nada de lo que hace el servicio termina nunca.

  • scoreBoard le da su respuesta a una función que escribes tú, que se ejecuta más tarde. Dibuja algo mientras tanto.

  • Cualquier llamada de red puede fallar, y fallar no es un error. Di una línea corta y sigue jugando.

  • Una puntuación publicada es una afirmación, y el servicio la trata como tal.

  • Conserva el récord local. Es el que siempre funciona.

La próxima vez

Un récord es un número, y la partida guardada de la lección doce es el sitio adecuado para él. La lección veintinueve es para todo lo demás que un juego quiere guardar: cada ronda que juega cualquiera, las fases que incluyes en el juego y las preguntas que quieres hacerles a las dos cosas. Coge esta prueba de reflejos y le da una base de datos.

Lección 29: Guardar datos

La lección terminada

La lección doce guardaba un récord: un número, bajo un nombre, ahí a la mañana siguiente. Eso es justo lo adecuado para un récord, y lo inadecuado para casi todo lo demás que un juego quiere conservar. Una lista de todas las partidas que haya jugado cualquiera. El mejor tiempo en cada una de veinte pistas. Cuarenta niveles que alguien diseñó en una hoja de cálculo. La pregunta «¿cuál es mi mejor marca en la fase difícil?», que un montón de números guardados no puede responder sin que escribas tú la respuesta a mano.

Para eso está una base de datos, y Singe trae una incorporada. Esta lección toma la prueba de reflejos de la lección veintiocho, le da fases que vienen con el juego y hace que guarde cada partida que juegue cualquiera y responda preguntas sobre ellas.

Qué es una base de datos

Una base de datos es un archivo de tablas. Una tabla son filas y columnas, como una hoja de cálculo con los nombres de las columnas decididos de antemano: una tabla de partidas podría tener una fase, una puntuación y una hora en cada fila. Metes filas y haces preguntas para sacar filas, y las preguntas se escriben en SQL, un lenguaje pequeño que lleva haciendo este trabajo desde antes que la mayoría de los lenguajes de programación de los que has oído hablar.

La base de datos que lleva Singe es SQLite. No es un servidor que haya que instalar ni un servicio en el que darse de alta. Es una biblioteca, la base de datos es un archivo normal y corriente, y el mismo SQLite está en tu móvil, en tu navegador y seguramente en tu coche. No hace falta saber SQL para seguir esta lección; cada sentencia se explica según va pasando, y las tres que más usarás — CREATE TABLE, INSERT y SELECT — están todas aquí.

Abrir una

local sqlite3 = require("sqlite3")

local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

require("sqlite3") carga una biblioteca que viene con Singe y te la devuelve como una tabla, así que todo lo que sabe hacer SQLite es sqlite3. algo. sqlite3.open abre un archivo de base de datos y lo crea si todavía no existe, así que la primera vez que se ejecuta tu juego crea uno vacío y todas las veces siguientes lo vuelve a encontrar.

El archivo va en singeGetDataPath(), por la misma razón que la partida guardada de la lección doce: la carpeta del propio juego puede estar en un disco, en una carpeta compartida o empaquetada en un solo archivo, y en ninguno de esos sitios se puede escribir. Todo lo que escribe un juego va en su carpeta de datos.

Crear una tabla

Una base de datos vacía no tiene tablas. Creas una describiéndola:

runs:exec([[
    CREATE TABLE IF NOT EXISTS runs (
        id    INTEGER PRIMARY KEY,
        stage TEXT    NOT NULL,
        score INTEGER NOT NULL,
        at    INTEGER NOT NULL
    )
]])

exec ejecuta SQL que no devuelve nada. Los dobles corchetes son la cadena larga de Lua: todo lo que hay entre ellos, saltos de línea incluidos, es una sola cadena, y así es como mantienes el SQL legible.

CREATE TABLE nombra la tabla y sus columnas, cada una con un tipo: TEXT para palabras e INTEGER para números enteros. NOT NULL significa que todas las filas tienen que tener un valor ahí. INTEGER PRIMARY KEY es especial: SQLite la rellena solo, contando hacia arriba, así que cada fila recibe su propio número sin que tengas que pensar en ello.

IF NOT EXISTS es lo que hace que sea seguro ejecutar esto cada vez que arranca el juego. La primera vez, crea la tabla. Todas las veces siguientes, la tabla ya está ahí y la línea no hace nada. Sin esas tres palabras, la segunda vez que ejecutaras tu juego se pararía con un error diciendo que la tabla ya existe.

Meter una fila

Podrías construir el SQL de una fila nueva pegando cadenas:

runs:exec("INSERT INTO runs (stage, score, at) VALUES ('" .. stage .. "', " .. score .. ", " .. os.time() .. ")")

No lo hagas. Funciona hasta que un nombre lleva un apóstrofo, y en ese momento la comilla termina la cadena antes de tiempo y la sentencia no tiene ni pies ni cabeza. En un juego que deja escribir a los jugadores es peor: lo que escriban pasa a formar parte de tu SQL.

La forma correcta es escribir la sentencia una vez, con signos de interrogación donde van los valores, y pasar los valores aparte:

local addRun = runs:prepare("INSERT INTO runs (stage, score, at) VALUES (?, ?, ?)")

local function record(stage, points)
    addRun:bind_values(stage, points, os.time())
    addRun:step()
    addRun:reset()
end

prepare convierte el SQL en una sentencia que se puede usar una y otra vez. bind_values pone un valor en cada signo de interrogación, en orden. Contenga lo que contenga un valor, apóstrofos incluidos, es un valor y nunca parte del SQL. step ejecuta la sentencia, y reset la deja lista para ejecutarse otra vez. os.time() es Lua normal: la hora actual como un número de segundos, que es la forma más fácil de guardar «cuándo».

Preparar una vez y reutilizar la sentencia también es más rápido, porque SQLite solo calcula una vez cómo ejecutarla. Para un juego que escribe una fila por minuto da igual. Para un editor de niveles que escribe mil, no.

Hacer preguntas

Las filas vuelven a salir con nrows, que ejecuta un SELECT y te da cada fila como una tabla con los nombres de las columnas como claves:

for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC LIMIT 5") do
    debugPrint(row.stage .. "  " .. row.score)
end

Lee el SQL de izquierda a derecha. SELECT stage, score dice qué columnas quieres. FROM runs dice de qué tabla. ORDER BY score DESC ordena las filas por puntuación, de mayor a menor, y LIMIT 5 se para después de cinco. Eso es una tabla de récords, y no ha necesitado ni una línea tuya de código para ordenar.

Las preguntas pueden ser más listas que las que querrías escribir a mano:

for row in runs:nrows("SELECT stage, MAX(score) AS top, COUNT(*) AS tries FROM runs GROUP BY stage ORDER BY stage") do
    debugPrint(row.stage .. ":  best " .. row.top .. " of " .. row.tries)
end

GROUP BY stage reúne las filas en un grupo por fase, y MAX(score) y COUNT(*) se calculan para cada grupo: la mejor puntuación de esa fase y cuántas veces se ha jugado. AS top le pone nombre a la respuesta, que es la clave con la que la vuelves a leer.

Cuando una pregunta tiene una sola respuesta, urows te devuelve las columnas mismas en lugar de una tabla, que queda más limpio para un recuento:

for count in runs:urows("SELECT COUNT(*) FROM runs") do
    played = count
end

Pregunta cuando cambie

Ninguna de esas preguntas va en onOverlayUpdate. Una consulta es rápida, pero sesenta por segundo, para obtener respuestas que cambian una vez por minuto, es el juego haciendo la misma pregunta y recibiendo la misma respuesta cincuenta y nueve veces de cada sesenta.

Así que el juego pregunta cuando la respuesta puede haber cambiado — una vez al principio, y otra cada vez que se registra una partida — y guarda lo que le llega en tablas normales:

local function refresh()
    best = {}
    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do
        best[#best + 1] = row
    end
    -- y lo mismo para las otras dos preguntas
end

onOverlayUpdate dibuja a partir de best, que no cuesta nada. record llama a refresh después de cada fila nueva, así que la tabla de la pantalla nunca está desfasada.

Datos que vienen con el juego

La otra mitad de los datos de un juego es la parte que escribes antes de que juegue nadie: las fases, los niveles, los objetos, las líneas de diálogo. Eso también puede ser una base de datos, hecha con cualquier herramienta de SQLite — el programa sqlite3 en la línea de comandos, o un programa con ventanas como DB Browser for SQLite — y puesta en la carpeta de tu juego junto a su arte. El kit de arte trae una, stages.db, con un nombre y la espera más corta y la más larga de cada fase.

Esa la abre un juego de otra manera:

local stages  = {}
local shipped = sqlite3.open(DIR .. "art/stages.db", sqlite3.OPEN_READONLY)

for row in shipped:nrows("SELECT name, waitMin, waitMax FROM stages ORDER BY id") do
    stages[#stages + 1] = row
end
shipped:close()

DIR es la carpeta de tu juego, donde está el arte. sqlite3.OPEN_READONLY dice que solo piensas leerla, y eso importa el día que publiques. Cuando empaquetes tu juego en un solo archivo en la próxima lección, una base de datos abierta de solo lectura se lee directamente de ese archivo, sin desempaquetar nada. Una abierta para escritura se copia, una vez, a la carpeta de datos del juego, y a partir de entonces lo que cambias es la copia; en el archivo que publicaste no se escribe nunca.

Así que mantén separados los dos tipos. Lo que has hecho tú va en tu carpeta y se abre de solo lectura. Lo que hace el juego va en la carpeta de datos. Aquí las fases se leen una vez al principio en una tabla normal y la base de datos se cierra, porque una lista de cuatro fases no merece tener un archivo abierto.

Cerrar al terminar

Las sentencias y las bases de datos retienen memoria y mantienen un archivo abierto hasta que dices que has terminado, y el sitio ordenado para decirlo es onShutdown:

function onShutdown()
    addRun:finalize()
    runs:close()
end

finalize es el close de una sentencia. Una base de datos no se cierra mientras siga por ahí una sentencia hecha a partir de ella, así que las sentencias van primero.

El script completo

Crea una carpeta llamada runs, copia dentro la carpeta art del libro para tener stages.db, y pon esto en runs.singe:

dofile("Singe/Framework.singe")

local sqlite3 = require("sqlite3")

local PERFECT = 1000

-- Lo que viene con el juego:  las fases, leídas una vez y cerradas.
local stages  = {}
local shipped = sqlite3.open(DIR .. "art/stages.db", sqlite3.OPEN_READONLY)

for row in shipped:nrows("SELECT name, waitMin, waitMax FROM stages ORDER BY id") do
    stages[#stages + 1] = row
end
shipped:close()

-- Lo que escribe el juego:  cada partida que juegue cualquiera, guardada en la carpeta de datos.
local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

runs:exec([[
    CREATE TABLE IF NOT EXISTS runs (
        id    INTEGER PRIMARY KEY,
        stage TEXT    NOT NULL,
        score INTEGER NOT NULL,
        at    INTEGER NOT NULL
    )
]])

local addRun   = runs:prepare("INSERT INTO runs (stage, score, at) VALUES (?, ?, ?)")
local stageAt  = 1
local state    = "attract"
local goAt     = 0
local score    = 0
local best     = {}
local perStage = {}
local played   = 0


-- Las preguntas, hechas cuando se añade una partida y no en cada fotograma.
local function refresh()
    best = {}
    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do
        best[#best + 1] = row
    end
    perStage = {}
    for row in runs:nrows("SELECT stage, MAX(score) AS top, COUNT(*) AS tries FROM runs GROUP BY stage ORDER BY stage") do
        perStage[#perStage + 1] = row
    end
    for count in runs:urows("SELECT COUNT(*) FROM runs") do
        played = count
    end
end


local function record(stage, points)
    addRun:bind_values(stage, points, os.time())
    addRun:step()
    addRun:reset()
    refresh()
end


local function play()
    local stage = stages[stageAt]

    state = "waiting"
    goAt  = singeGetTicks() + math.random(stage.waitMin, stage.waitMax)
    score = 0
end


function onInputPressed(what)
    if what == SWITCH_BUTTON2 and state ~= "waiting" and state ~= "go" then
        stageAt = stageAt % #stages + 1
        return
    end
    if what ~= SWITCH_BUTTON1 then
        return
    end
    if state == "waiting" then
        state = "result"
        score = 0
        record(stages[stageAt].name, score)
    elseif state == "go" then
        score = math.max(0, PERFECT - (singeGetTicks() - goAt))
        state = "result"
        record(stages[stageAt].name, score)
    else
        play()
    end
end


function onOverlayUpdate()
    if state == "waiting" and singeGetTicks() >= goAt then
        state = "go"
    end

    overlayClear()
    overlayPrint(2, 0, "REACTION TEST:  " .. stages[stageAt].name)

    if state == "attract" then
        overlayPrint(2, 2, "Button 1 to play, button 2 for another stage.")
    elseif state == "waiting" then
        overlayPrint(2, 2, "Wait for it...")
    elseif state == "go" then
        overlayPrint(2, 2, "NOW!")
    else
        overlayPrint(2, 2, "You scored " .. score .. ".  Button 1 plays again.")
    end

    overlayPrint(2, 4, "Runs kept:  " .. played)
    overlayPrint(2, 6, "BEST RUNS")
    for place, row in ipairs(best) do
        overlayPrint(2, 6 + place, string.format("%d.  %-8s %4d", place, row.stage, row.score))
    end
    overlayPrint(24, 6, "BY STAGE")
    for line, row in ipairs(perStage) do
        overlayPrint(24, 6 + line, string.format("%-8s best %4d of %d", row.stage, row.top, row.tries))
    end

    return OVERLAY_UPDATED
end


function onShutdown()
    addRun:finalize()
    runs:close()
end


refresh()

Ejecútalo con Singe -R runs. El botón 1 empieza una ronda y la detiene, como en la lección veintiocho, y el botón 2 entre rondas pasa a la fase siguiente. Juega unas cuantas en cada una. Luego sal y vuelve a ejecutarlo: todas las partidas siguen ahí, las cinco mejores a la izquierda y la mejor de cada fase a la derecha.

Qué acaba de pasar

local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

Hay dos archivos en juego, y no se parecen. art/stages.db es tuyo: lo escribiste tú, viene con el juego y el juego solo lo lee. runs.db es del juego: no existía hasta que la primera ejecución lo creó, vive en la carpeta de datos y nadie lo publica.

    if state == "waiting" then
        state = "result"
        score = 0
        record(stages[stageAt].name, score)

Un botón pulsado demasiado pronto también registra una partida, con una puntuación de nada. La base de datos es un registro de lo que pasó, y una salida en falso pasó. Si mostrar esas filas o no es cosa del SELECT, no algo que esconder no escribiéndolas nunca.

    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do

ORDER BY score DESC, id ordena por puntuación y, cuando dos puntuaciones son iguales, por id — el orden en que se jugaron. Sin el segundo criterio, dos puntuaciones iguales salen en el orden que a SQLite le venga bien, que puede cambiar de una ejecución a otra. Una tabla que se reordena sola sin motivo visible parece rota aunque no lo esté.

Pruébalo

  1. Muestra la fecha. os.date("%Y-%m-%d", row.at) vuelve a convertir una hora guardada en algo que una persona puede leer. Añade la fecha a cada una de las mejores partidas.

  2. Ignora las salidas en falso. Añade WHERE score > 0 a la pregunta de las mejores partidas, entre FROM runs y ORDER BY. Luego cuenta las salidas en falso de cada fase con una pregunta tuya.

  3. Añade una fase. Abre stages.db en una herramienta de SQLite, añade una fila y ejecuta el juego. No cambia nada del script. Esa es la gracia de tener los datos fuera del script.

  4. Borra el historial. runs:exec("DELETE FROM runs") vacía la tabla. Ponlo en un botón, llama a refresh después y mira cómo todo se queda en nada. Este es el «borrar récords» de un menú de servicio.

  5. Escribe mil filas. Llama a record mil veces en un bucle y cronométralo con singeGetTicks. Luego pon runs:exec("BEGIN") antes del bucle y runs:exec("COMMIT") después, y vuelve a cronometrarlo. Una transacción convierte muchas escrituras en una, y la diferencia es lo bastante grande como para que valga la pena recordarla.

Rómpelo a propósito

Quita addRun:reset() de record y juega tres rondas en tres fases distintas.

Ningún error. El juego funciona perfectamente. Pero la tabla de la derecha dice que has jugado la primera fase tres veces, y las mejores partidas son tres copias de tu primera puntuación. bind_values no podía poner valores nuevos en una sentencia que ya se había ejecutado y no se había reiniciado, así que se rindió — en silencio, devolviendo un número que no estabas comprobando — y step volvió a ejecutar la sentencia con los valores que ya tenía.

Este es el fallo que importa en esta lección, porque no lo parece. Una consulta que falla hace ruido. Una escritura que escribe lo que no es no hace ninguno, y la encuentras una semana después en los datos. Cuando las filas de una base de datos no son lo que esperas, mira el código que las puso ahí antes que el código que las lee.

Vuelve a poner reset y rómpelo de la forma ruidosa: cambia score por scroe en el primer SELECT de refresh.

Error running script:  no such column: scroe
stack traceback:
	[C]: in method 'nrows'
	runs/runs.singe:42: in local 'refresh'
	runs/runs.singe:132: in main chunk

SQLite lee los nombres de las columnas cuando prepara la pregunta, así que uno mal escrito para el juego en el acto, y el mensaje lo nombra exactamente. La traza se lee de dentro hacia fuera: nrows se quejó, refresh la llamó en la línea 42, y el propio script llamó a refresh en la línea 132, la última, al arrancar el juego. Por eso dice running script en lugar de nombrar una función que llamó el motor: nunca llegó al primer fotograma.

Lo que has aprendido

  • Una base de datos es un archivo de tablas; una tabla son filas con columnas que tienen nombre.

  • require("sqlite3") te da SQLite. sqlite3.open abre un archivo y lo crea si no existe.

  • Lo que escribe el juego va en singeGetDataPath(). Lo que publicas va en tu carpeta, y se abre con sqlite3.OPEN_READONLY.

  • CREATE TABLE IF NOT EXISTS se puede ejecutar sin peligro cada vez que arranca el juego.

  • Los valores entran con prepare, bind_values, step y reset, nunca pegando cadenas en el SQL.

  • nrows devuelve las filas como tablas; urows devuelve las columnas mismas.

  • ORDER BY, LIMIT, GROUP BY, MAX y COUNT responden a las preguntas para las que, si no, escribirías bucles.

  • Pregunta cuando la respuesta puede cambiar, no en cada fotograma.

  • En onShutdown se finalizan las sentencias y después se cierra la base de datos.

La próxima vez

Tu juego tiene ya una carpeta llena de cosas: un script, arte, sonidos y una base de datos o dos. La lección treinta convierte esa carpeta en un solo archivo que un desconocido puede copiar en su propio ordenador y jugar — y tu base de datos de solo lectura va con él, abriéndose exactamente igual que ahora.

Lección 30: Publicarlo

La lección terminada

Tienes una carpeta. Dentro hay un script, unas cuantas imágenes, algunos sonidos y el games.dat que escribiste en la lección trece. Funciona, porque todo lo que necesita está donde lo dejaste y tú sabes dónde es.

Esta lección convierte esa carpeta en un solo archivo que alguien que no te conoce de nada puede copiar en su ordenador y jugar. Casi todo son dos líneas de comandos. El resto es la parte que no enseña nadie: qué va en el archivo, qué trabajo de otros hay ahí además del tuyo y cómo averiguar si funciona en algún sitio aparte de aquí.

Un solo archivo

Un juego de Singe terminado se publica como un único archivo .game. Empaquetar uno es:

Singe --pack MyGame MyGame.game

El primer nombre es la carpeta de tu juego, el segundo es el archivo que hay que escribir. Singe mete todos los archivos de la carpeta en una base de datos y dice lo que ha hecho:

>>> Packed 42 files (3819204 bytes) from MyGame into MyGame.game

Se ejecuta igual que cualquier otra cosa:

Singe MyGame.game

Eso ejecuta la primera entrada del games.dat que lleva dentro; --entry=2 ejecuta la segunda, para un archivo que contiene más de un juego. Para instalarlo, el jugador copia MyGame.game junto al programa Singe. El menú incluido lo encuentra y lo pone en la lista. No hay nada más: ni instalador, ni archivo comprimido que descomprimir, ni carpeta que poner en el sitio correcto.

Lo que el empaquetado le hace a cada nombre de archivo

No hay que cambiar nada de tu juego para empaquetarlo, y vale la pena saber por qué, porque es lo que más probablemente te sorprenda.

Todos los nombres que usa tu juego — dofile, require, io.open, spriteLoad, soundLoad, fontLoad, videoLoad, un framefile, un controls.cfg — pasan por una única búsqueda. Para una carpeta suelta, esa búsqueda es el sistema de archivos normal. Para un juego empaquetado, el nombre se prueba en tres sitios y gana el primero que lo encuentra:

  1. una carpeta suelta con el nombre del archivo sin su extensión — MyGame/ junto a MyGame.game;

  2. la carpeta de datos del juego, dentro de files/, que es donde ha ido a parar todo lo que el juego escribe;

  3. la propia base de datos.

Dentro de la base de datos, los nombres se comparan sin tener en cuenta las mayúsculas, con cualquiera de los dos tipos de barra y a partir de la raíz del juego. Un nombre de carpeta inicial igual al del propio juego se ignora, así que MyGame/art/spaceship.png, art/spaceship.png y DIR .. "art/spaceship.png" encuentran todos el mismo archivo.

De ahí salen dos reglas, y si has ido siguiendo el libro ya cumples las dos. Usa DIR para todo lo que cargues, para que un nombre nunca dependa de dónde se arrancó Singe. Y escribe solo dentro de singeGetDataPath(), que es donde saveSet ya pone las cosas — un juego empaquetado se abre de solo lectura y nunca se escribe en él, así que un juego que guarda junto a sí mismo funciona suelto y falla empaquetado.

Dos nombres van a otro sitio a propósito. Todo lo que empieza por Singe/ se queda en el sistema de archivos de verdad, así que dofile("Singe/Framework.singe") sigue funcionando, y lo mismo pasa con la carpeta de datos. Y un nombre con .. que intenta salirse del juego no lleva a ninguna parte: io.open devuelve nil y un mensaje que dice que el nombre apunta fuera del juego, y spriteLoad y sus parientes informan de que el archivo no existe.

La carpeta suelta sigue ganando

El primer sitio de la lista es el que usarás todos los días. Una carpeta con el nombre del archivo empaquetado, puesta a su lado, gana a las copias empaquetadas archivo por archivo.

MyGame.game        el juego empaquetado
MyGame/            una carpeta con un archivo cambiado dentro

Mete ahí un solo art/spaceship.png corregido y el juego empaquetado se ejecuta con tu imagen nueva y todo lo demás sacado de la base de datos. No hay que volver a empaquetar nada para probar un cambio, y puedes tener ahí toda tu carpeta de trabajo mientras terminas el juego. También es como un jugador modifica uno, cosa que puede que te parezca una ventaja o puede que no.

De ahí salen dos cosas. Prueba tu juego una vez con esa carpeta renombrada para que no estorbe, o publicarás un archivo que solo funciona en el ordenador que tiene la carpeta. Y que sepas que empaquetar no esconde nada: --unpack es una opción documentada y cualquiera puede usarla. Empaqueta tu juego porque es un solo archivo, no porque sea un archivo cerrado con llave.

Parchear un juego publicado

Alguien tiene tu juego, hay un fallo en un script y no quieres volver a mandarle cuarenta megabytes.

Singe --patch MyGame.game fixes

fixes es una carpeta organizada como el juego — los mismos nombres en los mismos sitios — que contiene solo los archivos que han cambiado. Los archivos que el parche no nombra se dejan como están. Todo el cambio es una sola transacción, así que un parche interrumpido deja el juego exactamente como estaba en lugar de a medio sustituir.

Un parche puede viajar como un archivo propio, hecho con el empaquetador:

Singe --pack fixes MyGame-1.0.2.patch
Singe --patch MyGame.game MyGame-1.0.2.patch

Un .patch no necesita games.dat, no se puede ejecutar y el menú lo ignora. También puede llevar una tabla removed(path) que nombra archivos que borrar, para el arte que hayas sustituido por otro con un nombre distinto. En cualquier caso, Singe comprueba después el juego parcheado igual que comprueba uno nuevo, así que un parche no puede dejar tu games.dat apuntando a un archivo que ya no está.

Y para volver a sacarlo todo:

Singe --unpack MyGame.game MyGameUnpacked

Lo que el empaquetador rechaza

El empaquetador no construye un juego con cualquier cosa, y cada rechazo tiene que ver con algo que se rompería más tarde. Rechaza una carpeta sin games.dat en su raíz. Rechaza un Framework.singe, un controls.dat, cualquier cosa que termine en exe, sh, bat o cmd, y un archivo sin extensión cuyo nombre empiece por singe — es decir, una copia del motor o de sus archivos de soporte que se ha colado en la carpeta de tu juego. Rechaza dos archivos cuyos nombres solo se diferencian en las mayúsculas, porque la búsqueda no puede distinguirlos. Rechaza una entrada de primer nivel con el mismo nombre que la propia carpeta. Y comprueba tu games.dat antes de confirmar nada: cada entrada necesita un SCRIPT, y cada SCRIPT, VIDEO, CABINET, MARQUEE y ATTRACT que nombre tiene que ser un archivo que esté de verdad ahí dentro. Una ruta mala se informa con el título de la entrada y no se escribe nada.

Cada queja nombra el archivo, y sale la lista entera en lugar de solo la primera, así que una sola pasada te dice todo lo que hay que arreglar.

Qué incluir y qué dejar fuera

Mira en la carpeta de tu juego. Parte de lo que hay es el juego, y parte es cómo se hizo el juego.

Publica: el script y todo lo que carga, el games.dat, el arte que muestra el menú (CABINET, MARQUEE y el clip de ATTRACT), tus archivos de créditos y de licencias, y un léame si tienes uno.

Deja fuera: los dibujos de los que exportaste el arte, las tomas de sonido que no usaste, tus notas, los scripts de prueba, las capturas de pantalla, cualquier cosa que se llame old o backup, la carpeta data con tus propias partidas guardadas y tus propios récords, y cualquier cosa que no quieras que lea un desconocido. Todo eso se empaqueta perfectamente, y ese es el problema: sale con el juego y está a un --unpack de cualquiera.

La forma fiable de saber lo que has publicado de verdad es desempaquetarlo en una carpeta vacía y mirar. Hazlo una vez con cada versión. Lleva un minuto y es la única comprobación que ve lo que olvidaste en lugar de lo que recuerdas.

Créditos y licencias

Si algo del arte, el sonido, la música o las fuentes de tu juego lo ha hecho otra persona, estás publicando su trabajo, y las condiciones con las que lo cedió son una obligación, no una cortesía. No es una formalidad ni es cosa de abogados: una persona hizo eso y pidió una cosa concreta a cambio, normalmente su nombre.

Lleva un registro mientras trabajas, no al final. Un archivo de texto plano en la carpeta del juego con una línea por cosa: qué archivo es, de dónde salió, quién lo hizo, qué licencia tiene y qué exige esa licencia. Escribirlo sobre la marcha lleva segundos. Reconstruirlo la noche antes de publicar, a partir del historial del navegador, es como se quedan créditos fuera.

Unas cuantas cosas que conviene saber antes de necesitarlas. «Descarga gratuita» no es una licencia; busca las condiciones de verdad. Creative Commons BY significa que tienes que dar el crédito que se indica, y no tiene ninguna excepción para juegos. CC0 y el dominio público no piden nada, y dar el crédito de todos modos te cuesta una línea. Las fuentes llevan sus propias licencias, y unas permiten incrustarlas y otras no. La música de un vídeo casi nunca es tuya para usarla. Cualquier cosa generada por una herramienta solo está tan limpia como las condiciones de la herramienta.

Luego pon los créditos en algún sitio al que pueda llegar un jugador, dentro del juego. No solo en un archivo de texto al lado — un juego empaquetado es un solo archivo y el archivo de texto está dentro, donde nadie va a mirar. El script del final de esta lección es esa pantalla.

El propio Singe/LICENSES de Singe es el modelo que copiar: una línea por biblioteca, con su versión, su licencia y de dónde salió. La lista de tu juego será más corta y el trabajo es el mismo.

Un número de versión que signifique algo

Tu juego tendrá una segunda versión. La primera seguirá por ahí mientras dure internet, y alguien te mandará un informe de fallo sobre ella sin tener ni idea de qué versión tiene.

Así que elige un número, ponlo donde un jugador pueda leerlo y no repitas nunca uno. Tres partes es la forma habitual — 1.0.2 — y lo que signifique cada parte importa menos que el hecho de que solo suban. Sube la última por un arreglo, la del medio por algo nuevo y la primera cuando hayas hecho un juego distinto. Elijas lo que elijas, apúntalo en tu léame para que tu yo del futuro también lo cumpla.

games.dat no tiene clave de versión, así que el número lo llevas tú. Ponlo en el script como constante, muéstralo en la pantalla de créditos y ponlo en el nombre de lo que mandes (MyGame-1.0.2.game, MyGame-1.0.2.patch). Así el informe de fallo dice la versión de la pantalla y sabes de qué archivos se trata.

Probar en un ordenador que no es el tuyo

Tu ordenador es el peor sitio posible para probar una versión. Tiene las fuentes que instalaste, la carpeta que estabas editando, el archivo de partida guardada con tus ajustes dentro y el motor en el estado en que lo haya dejado un mes de trabajo.

La prueba mínima, en orden:

  1. Desempaqueta la versión en una carpeta vacía y lee la lista de archivos.

  2. Copia solo el archivo .game en otra carpeta, con una copia recién sacada de Singe y nada más, y ejecútalo desde el menú como lo hará un jugador.

  3. Borra la carpeta data de esa carpeta y vuelve a ejecutarlo. Eso es una primera ejecución en un ordenador nuevo: sin ajustes guardados, sin récords, sin una cuenta con la sesión iniciada. Un juego que solo funciona la segunda vez que se ejecuta es un fallo habitual, y así es como lo encuentras.

  4. Dáselo a una persona que no lo haya visto nunca y mira sin ayudar.

Luego prueba el ordenador además del juego. Tendrá una pantalla de otra forma, así que mira tu juego en ventana y a pantalla completa. Puede que no tenga ningún dispositivo 3D, que es por lo que el menú tiene un segundo renderizador. La página System Information de las herramientas de servicio muestra en una sola pantalla la versión del motor, el sistema operativo, el procesador, el renderizador, los decodificadores y la carpeta de datos; una foto de esa página responde a casi todo un informe de fallo, y decírselo a tus jugadores en tu léame te ahorrará una semana de adivinanzas.

El script

Una pantalla de créditos y versión. Es poca cosa de escribir y es la parte de publicar que la mayoría de los juegos hace mal.

dofile("Singe/Framework.singe")

local GAME_NAME    = "Rock Dodger"
local GAME_VERSION = "1.0.2"

local CREDITS = {
    "Written and drawn by   <your name here>",
    "",
    "Music                  \"Night Drive\" by A. Composer",
    "                       Creative Commons BY 4.0",
    "                       example.org/night-drive",
    "",
    "Explosion              freesound.org user \"thud\"",
    "                       Creative Commons CC0",
    "",
    "Font                   FreeSansBold",
    "                       GPL with the font exception",
    "",
    "Engine                 Singe " .. SINGE_VERSION_STRING,
    "                       GPL version 3",
    "                       See Singe/LICENSES for the",
    "                       libraries Singe is built on.",
    "",
    "Thank you for playing.",
}

local FIRST_ROW = 4
local ROWS      = 10

local scroll = 0


local function scrollBy(lines)
    local most = #CREDITS - ROWS

    if most < 0 then
        most = 0
    end
    scroll = scroll + lines
    if scroll < 0 then
        scroll = 0
    end
    if scroll > most then
        scroll = most
    end
end


function onInputPressed(what)
    if what == SWITCH_UP then
        scrollBy(-1)
    elseif what == SWITCH_DOWN then
        scrollBy(1)
    elseif what == SWITCH_BUTTON1 then
        scroll = 0
    end
end


function onOverlayUpdate()
    local line = nil

    overlayClear()
    overlayPrint(2, 0, GAME_NAME .. "  version " .. GAME_VERSION)
    overlayPrint(2, 1, "Singe " .. SINGE_VERSION_STRING .. "   id " .. (singeGetGameId() or "none"))

    for row = 0, ROWS - 1 do
        line = CREDITS[scroll + row + 1]
        if line then
            overlayPrint(2, FIRST_ROW + row, line)
        end
    end

    overlayPrint(2, FIRST_ROW + ROWS + 1, "Saves go to:")
    overlayPrint(2, FIRST_ROW + ROWS + 2, singeGetDataPath())
    overlayPrint(2, 17, "Up and down scroll.  Button 1 goes back to the top.")

    return OVERLAY_UPDATED
end

Sustituye cada línea de CREDITS por la verdad sobre tu propio juego. Los textos de relleno están ahí para mostrar la forma: qué es, quién lo hizo, qué licencia tiene y de dónde salió.

Qué acaba de pasar

local GAME_VERSION = "1.0.2"

Un solo sitio, arriba, en mayúsculas porque nunca cambia mientras el juego se ejecuta. Todo lo que muestra la versión lee esto, así que subirla es un cambio y no una búsqueda.

    "Music                  \"Night Drive\" by A. Composer",

Esas barras invertidas son la secuencia de escape que conociste en la lección uno: unas comillas dobles que forman parte del texto en lugar de terminar la cadena. Los títulos llevan comillas, y por eso una lista de créditos se topa con esto en su primera línea.

    for row = 0, ROWS - 1 do
        line = CREDITS[scroll + row + 1]
        if line then

Diez filas de pantalla que muestran diez líneas de una lista de más de diez. scroll es cuánto ha bajado la ventana por la lista. El + 1 está porque Lua cuenta una lista desde uno y las filas de la pantalla cuentan desde cero, y el if line then está porque el final de la lista es nil — leer más allá del final de una tabla no es un error en Lua, simplemente no te da nada, e imprimir nada sí lo sería.

    overlayPrint(2, 1, "Singe " .. SINGE_VERSION_STRING .. "   id " .. (singeGetGameId() or "none"))

Tres datos que necesita un informe de fallo y que un jugador no puede encontrar de otra manera: tu versión, en la línea de arriba, la versión del motor y el id del juego. SINGE_VERSION_STRING es una variable global que el motor fija antes de que se ejecute tu script. or "none" cubre el caso en que el juego no tiene entrada en games.dat, para que la línea se imprima en lugar de fallar con un nil.

    overlayPrint(2, FIRST_ROW + ROWS + 2, singeGetDataPath())

Dónde escribe este juego. En un juego empaquetado es el único sitio donde se escribe algo, y es la carpeta que borra un jugador para empezar de cero. Mostrarla convierte «¿dónde están mis partidas guardadas?» en una pregunta que nunca tendrás que responder.

Si esa ruta se sale por la derecha de la pantalla, no es que esté rota: overlayPrint descarta los caracteres que pasarían del borde. El overlay por defecto tiene sesenta celdas de carácter de ancho.

Pruébalo

  1. Empaquétalo. Pon este script en la carpeta de tu juego, ejecuta --pack y ejecuta el archivo .game. Luego desempaquétalo en una carpeta vacía y lee la lista de lo que ha salido.

  2. Sustituye un archivo. Junto al archivo empaquetado, crea una carpeta con su nombre sin la extensión y pon dentro un archivo cambiado. Ejecuta el juego empaquetado y mira cómo gana tu archivo suelto.

  3. Haz un parche. Cambia la versión a 1.0.3, pon solo el script en una carpeta fixes, empaqueta eso como un .patch y aplícalo al juego que ya hiciste. Comprueba la versión en pantalla.

  4. Rompe el empaquetador. Cambia el nombre de tu games.dat un momento e intenta empaquetar. Luego déjalo como estaba, haz que uno de sus SCRIPT apunte a un archivo que no existe y vuelve a intentarlo. Dos rechazos distintos, los dos antes de que se escriba nada.

  5. Escribe los créditos de verdad. Repasa la carpeta de tu juego archivo por archivo y escribe una línea por cada uno que no hayas hecho tú. Si no recuerdas de dónde salió algo, esa es la respuesta a si deberías publicarlo.

Rómpelo a propósito

Ejecuta Singe una vez desde dentro de la carpeta de tu juego, para que el motor desempaquete ahí sus archivos de soporte, y luego empaquétala:

Singe --pack MyGame MyGame.game
!!! MyGame has Framework.singe:  Singe/Framework.singe
!!! MyGame has sh file:  Menu.sh

No se escribe nada. Cada línea es un archivo que no acepta y el porqué, y puede que te salgan en otro orden o que salgan otras además. Hay una copia de la propia carpeta de soporte del motor dentro de tu juego, y el script lanzador que el motor escribió a su lado, porque en algún momento ejecutaste Singe desde ahí dentro. Un juego no debe llevar nunca ninguno de los dos: los archivos de soporte pertenecen al Singe que esté usando el jugador, no a tu juego, y un Framework.singe empaquetado se cargaría en lugar del suyo. En Windows, la segunda línea nombra Menu.bat en su lugar.

Borra la carpeta Singe y Menu.sh (o Menu.bat) de dentro de tu juego, deja la carpeta de tu juego como una carpeta junto al programa Singe y no alrededor de él, y vuelve a empaquetar. Es la misma organización que describía la lección trece, y este error es lo que pasa cuando se descuida.

Lo que has aprendido

  • Singe --pack folder name.game convierte la carpeta de un juego en un solo archivo, y copiar ese archivo junto al programa Singe lo instala.

  • Todo nombre de archivo dentro de un juego empaquetado se busca primero en una carpeta suelta, luego en la carpeta de datos y luego en la base de datos.

  • Una carpeta suelta con el nombre del archivo empaquetado lo sustituye archivo por archivo, que es como sigues trabajando — y como publicas una versión rota si te olvidas de que está ahí.

  • Carga con DIR y escribe solo dentro de singeGetDataPath(), o tu juego funcionará suelto y fallará empaquetado.

  • --patch sustituye archivos de un juego publicado en una sola transacción; --unpack vuelve a sacarlo todo.

  • El empaquetador rechaza los archivos del motor, los nombres que chocan y un games.dat que apunta a archivos que no tiene.

  • Desempaqueta tu propia versión y lee lo que lleva antes de mandarla a ningún sitio.

  • El arte y el sonido de otros vienen con condiciones, y cumplirlas significa una pantalla de créditos dentro del juego.

  • Un número de versión solo sube, y su sitio es la pantalla.

  • Prueba en un ordenador que no sea el tuyo, empezando sin ninguna carpeta data.

La próxima vez

Un solo archivo, instalado, con sus créditos y su número. La última lección lo mete en una caja de madera con una ranura para monedas y sin teclado, lo que cambia más cosas de tu juego de lo que crees.

Lección 31: En una recreativa

La lección terminada

Hay una diferencia entre un juego y una máquina recreativa, y no es la madera. Una máquina se enciende sola por la mañana, juega para una sala vacía, coge la moneda de alguien que no ha leído ni una palabra sobre ella y sigue funcionando a medianoche sin que nadie haya tocado un teclado, porque no hay teclado. Todo lo de esta lección sale de ahí.

No necesitas una recreativa para hacer nada de esto. Un stick y dos botones encima de una mesa, o un mando, bastan para encontrar todos los errores de esta lección, y casi todo lo que aprendas aquí también mejora un juego en un ordenador de sobremesa.

No hay teclado

Empieza por lo que falta, porque es lo que rompe los juegos.

Una recreativa tiene un stick, unos cuantos botones, una puerta del monedero, un botón de inicio y, en algún sitio dentro, un pequeño interruptor al que llega el operador. Eso es todo. Ni Esc, ni letras, ni ratón, ni forma de escribir. Así que:

  • Todos los menús de tu juego tienen que poder usarse con arriba, abajo y un botón. Si alguna pantalla de tu juego dice «pulsa Y para continuar», en una recreativa no funciona.

  • Meter las iniciales es cosa de tres botones y una letra que va cambiando, no de un campo de texto. Por eso los juegos de recreativa tienen nombres de tres letras.

  • Un aviso que nombra una tecla por su letra está mal. Di «botón 1», o dibuja el botón.

  • No hay salida. Un jugador no puede salir, y no debería poder.

Repasa tu juego una vez, pantalla por pantalla, y pregúntate en cada una: ¿podría alguien pasar esto con un stick y un botón? Ese repaso de tu propio juego vale más que todo el resto de esta lección.

controls.cfg

Desde la lección tres has estado leyendo la entrada como SWITCH_UP, SWITCH_BUTTON1, SWITCH_COIN1 y demás, y ni una sola vez has dicho qué tecla son. Esa es precisamente su gracia. En algún punto entre el microinterruptor de la recreativa y tu onInputPressed hay un archivo que lo decide, y tu juego no forma parte de esa conversación.

El archivo es controls.cfg. Es Lua, como tu script, y es una lista de tablas — una por interruptor — que nombran todo lo que puede producirlo:

INPUT_1P_START = { SCANCODE.MAIN_1, GAMEPAD_0.BUTTON_START }
INPUT_1P_COIN  = { SCANCODE.MAIN_5, GAMEPAD_0.BUTTON_LEFT_BUMPER }
INPUT_ACTION_1 = { SCANCODE.LCTRL, GAMEPAD_0.BUTTON_A }
INPUT_UP       = { SCANCODE.UP, GAMEPAD_0.DPAD_UP, GAMEPAD_0.AXIS_LEFT_Y_U }

Cada nombre INPUT_ del archivo se convierte en el valor SWITCH_ correspondiente de tu juego: INPUT_ACTION_1 es el SWITCH_BUTTON1 que has estado comprobando, e INPUT_1P_COIN es SWITCH_COIN1. Todas las entradas de una tabla producen el mismo interruptor, así que a un juego le da igual si el jugador pulsó la tecla, el botón del mando o movió el stick.

No tienes que escribir el archivo entero. Singe empieza con sus propios valores por defecto y lee controls.cfg de cuatro sitios por turno — la carpeta del script del juego, la carpeta desde la que se arrancó Singe, la carpeta que está por encima de la carpeta de datos del juego y la carpeta de datos del juego — y cada uno que encuentra sustituye a lo anterior, clave por clave. Así que una recreativa tiene un archivo arriba del todo para toda la máquina, y un juego que necesita un botón más tiene un archivo propio de cuatro líneas. En la carpeta Singe hay un controls.cfg.example del que copiar.

DEAD_ZONE también está ahí: cuánto tiene que moverse un stick antes de contar como pulsado, en las unidades en bruto que da el hardware, donde el recorrido completo es 32767. El valor por defecto es 15000. Un stick gastado que se desliza solo necesita un número más grande, y DEAD_ZONES fija un eje cada vez para ese stick que está cansado. La sección del manual sobre cómo personalizar los controles lo cubre todo.

Todo dispositivo es un mando

Los botones de una recreativa van cableados a una placa encoder, que el ordenador ve como algún tipo de joystick, y que no se parece en nada a un mando de Xbox. Singe escribe él mismo una asignación para un dispositivo así y luego lo abre como GAMEPAD_0, así que llega a controls.cfg y a tu juego exactamente igual que un mando reconocido. Hay una sola familia de dispositivos y ningún segundo vocabulario que aprender.

La asignación que se inventa es directa: los botones de la placa, en orden, pasan a ser BUTTON_A, BUTTON_B, BUTTON_X, BUTTON_Y y así sucesivamente. Si los botones de tu recreativa no están cableados en ese orden, saldrán en los sitios equivocados, y el arreglo no está en tu juego: --program escribe en la traza la asignación que escribió Singe, de una forma que puedes editar y poner en un gamecontrollerdb.txt junto al juego.

Cuando un botón «no hace nada», la herramienta Input Test del menú responde a la pregunta en cinco segundos. Muestra todos los dispositivos que ve el motor y el último interruptor que habría recibido un juego. O el interruptor llega y tu juego lo está ignorando, o no llega nunca y el problema es la asignación o el cable.

Cuatro interruptores no son tuyos

La mayoría de los interruptores van directos a tu juego. Cuatro no: de la pausa, la salida, la captura de pantalla y atrapar o soltar el ratón se encarga el propio motor.

La pausa es útil de verdad y gratis. Mientras la tiene el motor, la tecla asignada a INPUT_PAUSE lo congela todo — el disco, todos los vídeos, todos los sonidos y tu script — dibuja su propio indicador y lo descongela todo con la siguiente pulsación. Todo lo que tu juego creía que estaba pulsado se suelta como es debido y se vuelve a pulsar después, así que un stick que se mantiene durante una pausa nunca se queda atascado.

La salida es la que hay que quitar, y eso lo hace una sección posterior.

Monedas, créditos e inicio

Una máquina recreativa tiene una forma más antigua que cualquiera de nosotros, y los jugadores la conocen sin que nadie se la cuente:

  1. Atracción. No hay nadie. La máquina muestra lo que es, hace parpadear INSERT COIN y no pide nada.

  2. Crédito. Una moneda llega como SWITCH_COIN1. Las monedas se convierten en créditos al cambio que haya fijado el operador — no siempre una por uno.

  3. Juego. SWITCH_START1 gasta un crédito y empieza.

  4. Fin de partida. La puntuación, un momento, y vuelta al modo de atracción por sí sola. Nadie pulsa nada para salir; el jugador ya se ha ido.

Dos detalles en los que la gente se equivoca. Las monedas se cuentan, no se gastan: a dos monedas por crédito, una moneda tiene que quedarse ahí esperando a su pareja, y un jugador que echó una y se fue se la ha dejado al siguiente. Y la máquina tiene que encontrar sola el camino de vuelta al modo de atracción, porque lo último que hace un jugador es dejar de jugar.

Tras el interruptor de servicio

Dentro de la puerta del monedero hay un botón que el jugador no ve nunca y que el operador usa constantemente. Es SWITCH_SERVICE, y el motor te lo pasa directamente.

Un operador que abre tu menú de servicio espera encontrar, más o menos en este orden:

  • el precio — monedas por crédito, y un ajuste de juego gratis para una máquina en casa o en una feria;

  • la dificultad, porque una máquina en un bar y una máquina en un salón recreativo piden respuestas distintas;

  • una forma de borrar la tabla de récords, que es lo más pedido de toda esta lista;

  • qué máquina es — la versión del motor, la pantalla, dónde viven los datos — para que un informe de avería tenga hechos dentro;

  • una forma de salir, sin apagar nada.

Todo lo que cambia un operador tiene que sobrevivir a un corte de corriente, que en un salón recreativo significa un corte en mitad de una partida, sin aviso, porque alguien tira de un enchufe. saveSet escribe al final del fotograma, que es bastante pronto para una puntuación y no lo bastante para un ajuste que alguien acaba de cambiar. saveFlush() escribe en el acto, y un menú de servicio es justo para lo que está.

Vale la pena conocer las herramientas de servicio del propio menú incluido, tras el mismo interruptor, ya que están en todas las máquinas en las que se ejecutará tu juego: la prueba de entrada, las pruebas de sonido y de pistola de luz, la geometría de la pantalla, el retardo del audio, la cuenta en línea y una página que borra los datos guardados de cualquier juego. El tuyo no tiene que duplicarlas.

Una máquina que arranca sola y nunca sale

La recreativa se enciende desde el enchufe. Nadie inicia sesión. Tiene que haber un juego en la pantalla en un minuto más o menos, y seguir ahí.

Hacer que Singe se ejecute al encender es trabajo de tu sistema operativo, no de Singe — la máquina arranca el Menu.sh o el Menu.bat que el motor escribe junto a tus juegos, o tu juego directamente. Lo que sí es trabajo tuyo es lo que pasa durante el resto del día.

Quita la tecla de salida:

singeSetQuitKeyEnabled(false)

Entonces el motor deja de hacer caso al interruptor asignado a INPUT_QUIT y te lo entrega como SWITCH_QUIT, como cualquier otro, para que puedas preguntar antes, guardar antes o no hacer nada en absoluto. El botón de cerrar de la ventana siempre sale, pongas lo que pongas, y eso importará dentro de un momento.

Además, unas cuantas opciones son de la máquina y no de tu script, y van en un settings.cfg junto a los juegos — los mismos nombres que las opciones de línea de comandos, sin los guiones:

fullscreen  = true
screen      = 2
idleexit    = 900
startsilent = true

idleexit sale tras esa cantidad de segundos sin ninguna entrada de ningún tipo, para una recreativa que debe devolverle la pantalla a un menú o a un front-end. startsilent arranca en silencio hasta que alguien toca algo, que es lo que hace soportable una sala llena de máquinas. Hay más; las secciones de ajustes y de línea de comandos del manual los enumeran todos.

Arte alrededor de la imagen

Una recreativa de verdad tiene alrededor de la pantalla un bezel impreso (un marco decorativo): arte con un hueco por el que se ve el juego. Singe te dibuja uno.

Singe --bezel cabinet.png MyGame.game

El archivo se busca en una carpeta bezels dentro del juego — un juego empaquetado puede llevar el suyo — y luego en una carpeta bezels de la carpeta de datos, para que un jugador pueda ponerle su propio arte a un juego sin tocarlo. Junto a la imagen, con su mismo nombre, un pequeño archivo de Lua dice dónde va la imagen del juego, en los propios píxeles del arte:

-- bezels/cabinet.cfg
CUTOUT = { x = 200, y = 120, width = 800, height = 500 }

Como esos números son los del propio arte, siguen siendo correctos con cualquier tamaño de ventana: la imagen y el hueco se escalan juntos. Sin ese archivo, la imagen del juego ocupa toda la ventana, como siempre.

Por defecto el arte queda detrás de todo y tu juego tapa el hueco. --bezelflip lo pone delante, así que solo su transparencia deja ver el juego, que es lo que quieres para bordes suaves o con forma — y entonces tu overlay también queda debajo, salvo que digas lo contrario:

if mainBezelLoaded() then
    setOverlayOnTop(true)
end

mainBezelLoaded() también te dice si hay arte o no, y así es como un juego decide dibujar su propio marco cuando no lo hay.

Un monitor de lado

Muchos monitores de recreativa están montados en vertical. Gira toda la presentación:

Singe --rotate=90 MyGame.game

La imagen, el overlay, cualquier GUI, una escena 3D y las partículas giran todos juntos, y las posiciones del ratón y de la pistola de luz se giran de vuelta, así que un clic sigue cayendo donde lo ve el jugador. Un cuarto de vuelta también intercambia la forma del área, así que una ventana alta se llena en lugar de dejar la imagen metida en una franja.

Solo se aceptan 0, 90, 180 y 270. Un script puede cambiarlo mientras se ejecuta con vldpSetRotate, que responde false a cualquier otra cosa en lugar de terminar tu juego, y vldpGetRotate() lo vuelve a leer — algo que vale la pena poner en una pantalla de servicio, porque «la imagen está de lado» y «el monitor está de lado» son averías distintas.

Lo que no hace la rotación es reescribir tu juego. Un juego dibujado para una pantalla ancha, girado noventa grados, es un juego ancho tumbado. Diseñar para una pantalla alta significa diseñar para una pantalla alta.

El script

La forma completa: atracción, moneda, crédito, juego, fin de partida, servicio y una salida que pregunta. El juego del medio es un botón y un temporizador de quince segundos, porque esta vez lo importante no es el juego — es la máquina que lo rodea.

dofile("Singe/Framework.singe")

local ROUND_MS  = 15000
local MENU      = { "Coins per credit", "Difficulty", "Free play", "Clear high score", "Exit service" }
local HARDNESS  = { "Easy", "Normal", "Hard" }

local coinsPerCredit = saveGet("coinsPerCredit", 1)
local difficulty     = saveGet("difficulty", 2)
local freePlay       = saveGet("freePlay", false)
local best           = saveGet("best", 0)

local state    = "attract"
local goBackTo = "attract"
local coins    = 0
local credits  = 0
local score    = 0
local endsAt   = 0
local item     = 1
local saying   = ""
local hasBezel = false


local function wrap(value, low, high)
    if value < low then
        return high
    end
    if value > high then
        return low
    end
    return value
end


local function canStart()
    return freePlay or credits > 0
end


local function insertCoin()
    coins = coins + 1
    while coins >= coinsPerCredit do
        coins   = coins - coinsPerCredit
        credits = credits + 1
    end
end


local function startGame()
    if not freePlay then
        credits = credits - 1
    end
    score  = 0
    endsAt = singeGetTicks() + ROUND_MS
    state  = "play"
end


local function endGame()
    if score > best then
        best = score
        saveSet("best", best)
    end
    saveFlush()
    endsAt = singeGetTicks() + 5000
    state  = "over"
end


local function settingOf(which)
    if which == 1 then
        return tostring(coinsPerCredit)
    elseif which == 2 then
        return HARDNESS[difficulty]
    elseif which == 3 then
        if freePlay then
            return "on"
        end
        return "off"
    elseif which == 4 then
        return tostring(best)
    end
    return ""
end


local function adjust(step)
    if item == 1 then
        coinsPerCredit = wrap(coinsPerCredit + step, 1, 4)
        saveSet("coinsPerCredit", coinsPerCredit)
    elseif item == 2 then
        difficulty = wrap(difficulty + step, 1, #HARDNESS)
        saveSet("difficulty", difficulty)
    elseif item == 3 then
        freePlay = not freePlay
        saveSet("freePlay", freePlay)
    end
    saveFlush()
end


local function serviceInput(what)
    if what == SWITCH_UP then
        item = wrap(item - 1, 1, #MENU)
    elseif what == SWITCH_DOWN then
        item = wrap(item + 1, 1, #MENU)
    elseif what == SWITCH_LEFT then
        adjust(-1)
    elseif what == SWITCH_RIGHT then
        adjust(1)
    elseif what == SWITCH_BUTTON1 then
        if item == 4 then
            best = 0
            saveSet("best", 0)
            saveFlush()
            saying = "High score cleared."
        elseif item == 5 then
            state = goBackTo
        end
    elseif what == SWITCH_BUTTON2 or what == SWITCH_SERVICE then
        state = goBackTo
    end
end


function onInputPressed(what)
    if what == SWITCH_QUIT then
        if state == "confirm" then
            singeQuit()
        else
            goBackTo = state
            state    = "confirm"
        end
        return
    end

    if state == "confirm" then
        if what == SWITCH_BUTTON2 then
            state = goBackTo
        end
        return
    end

    if state == "service" then
        serviceInput(what)
        return
    end

    if what == SWITCH_SERVICE then
        goBackTo = state
        saying   = ""
        state    = "service"
        return
    end

    if what == SWITCH_COIN1 then
        insertCoin()
        return
    end

    if state == "play" then
        if what == SWITCH_BUTTON1 then
            score = score + 10 * difficulty
        end
        return
    end

    if what == SWITCH_START1 and canStart() then
        startGame()
    end
end


local function drawAttract()
    overlayPrint(2, 2, "ROCK DODGER")
    if canStart() then
        overlayPrint(2, 4, "PRESS START")
    elseif (singeGetTicks() // 400) % 2 == 0 then
        overlayPrint(2, 4, "INSERT COIN")
    end
    overlayPrint(2, 6, "High score  " .. best)
end


local function drawService()
    overlayPrint(2, 0, "SERVICE MENU")
    for row, name in ipairs(MENU) do
        if row == item then
            overlayPrint(1, row + 1, ">")
        end
        overlayPrint(3, row + 1, name)
        overlayPrint(24, row + 1, settingOf(row))
    end
    overlayPrint(2, 8, saying)
    overlayPrint(2, 10, "Singe " .. SINGE_VERSION_STRING .. "   rotation " .. vldpGetRotate())
    if hasBezel then
        overlayPrint(2, 11, "Bezel artwork loaded.")
    else
        overlayPrint(2, 11, "No bezel artwork.")
    end
    overlayPrint(2, 12, singeGetDataPath())
    overlayPrint(2, 16, "Up/Down choose.  Left/Right change.  Button 1 does it.")
    overlayPrint(2, 17, "Button 2 or the service switch leaves.")
end


function onOverlayUpdate()
    overlayClear()

    if state == "play" and singeGetTicks() >= endsAt then
        endGame()
    elseif state == "over" and singeGetTicks() >= endsAt then
        state = "attract"
    end

    if state == "service" then
        drawService()
    elseif state == "confirm" then
        overlayPrint(2, 2, "QUIT THIS GAME?")
        overlayPrint(2, 4, "Quit again to quit.  Button 2 stays.")
    elseif state == "play" then
        overlayPrint(2, 2, "SCORE  " .. score)
        overlayPrint(2, 3, "TIME   " .. ((endsAt - singeGetTicks()) // 1000))
        overlayPrint(2, 5, "Button 1 scores.  " .. HARDNESS[difficulty] .. ".")
    elseif state == "over" then
        overlayPrint(2, 2, "GAME OVER")
        overlayPrint(2, 4, "You scored " .. score .. ".")
        overlayPrint(2, 6, "High score  " .. best)
    else
        drawAttract()
    end

    if state ~= "service" then
        overlayPrint(2, 17, "CREDITS " .. credits .. "   COINS " .. coins .. "/" .. coinsPerCredit)
    end

    return OVERLAY_UPDATED
end


singeSetQuitKeyEnabled(false)
hasBezel = mainBezelLoaded()
if hasBezel then
    setOverlayOnTop(true)
end

Ejecútalo y pulsa 5 para echar una moneda, 1 para empezar y 9 para el interruptor de servicio — son los valores por defecto del controls.cfg de serie. Luego pulsa Esc y lee lo que dice antes de volver a pulsarla.

Qué acaba de pasar

local coinsPerCredit = saveGet("coinsPerCredit", 1)
local difficulty     = saveGet("difficulty", 2)
local freePlay       = saveGet("freePlay", false)

Los ajustes del operador se leen una vez, arriba, con un valor razonable para una máquina que nunca se ha configurado. saveGet con un segundo argumento devuelve ese valor cuando no se ha guardado nada, y así se distingue la primera ejecución de las siguientes.

local function insertCoin()
    coins = coins + 1
    while coins >= coinsPerCredit do
        coins   = coins - coinsPerCredit
        credits = credits + 1
    end
end

Entran monedas, salen créditos, al cambio que haya fijado el operador. Que sea un while y no un if no es prudencia ante una entrada imposible — es el operador bajando el precio de cuatro monedas a una mientras hay tres monedas esperando ahí dentro.

    if what == SWITCH_QUIT then
        if state == "confirm" then
            singeQuit()
        else
            goBackTo = state
            state    = "confirm"
        end
        return
    end

El interruptor de salida solo llega a tu juego por el singeSetQuitKeyEnabled(false) que hay al final del todo del script. Pulsarlo una vez pregunta; pulsarlo otra vez, desde la pantalla de la pregunta, hace que llames tú mismo a singeQuit(). goBackTo recuerda dónde estaba el jugador, así que decir que no lo devuelve a su partida en lugar de a la pantalla de atracción.

Este bloque va el primero de la función y hace return, así que nada más puede tragarse el interruptor. Todos los demás estados del juego se tratan debajo.

    if state == "service" then
        serviceInput(what)
        return
    end

La misma forma otra vez. Mientras el menú de servicio está abierto, todos los interruptores son suyos — el stick no mueve el juego de debajo y una moneda no cae en mitad de un ajuste. Un if, pronto, con un return. Cualquier pantalla que se pone encima de otra necesita esto, y un juego al que le salen tres y no lo tiene produce fallos casi imposibles de describir.

        saveSet("coinsPerCredit", coinsPerCredit)
    ...
    saveFlush()

Fijar y luego volcar. Sin el volcado, la escritura ocurre al final del fotograma, que es rápido pero no inmediato. Un operador cambia un ajuste y desenchufa la máquina diez segundos después, y este es el único sitio de un juego donde eso pasa de verdad.

    elseif (singeGetTicks() // 400) % 2 == 0 then
        overlayPrint(2, 4, "INSERT COIN")
    end

El parpadeo. singeGetTicks() son los milisegundos desde que arrancó el motor, // divide y tira el resto, así que el número cambia cada cuatrocientos milisegundos, y % 2 hace que vaya alternando entre cero y uno. Ni variable, ni temporizador, ni nada que reiniciar: el reloj ya estaba contando.

    overlayPrint(2, 10, "Singe " .. SINGE_VERSION_STRING .. "   rotation " .. vldpGetRotate())

La mitad del operador de la página de servicio. Una versión, una rotación, si hay arte o no, y dónde viven los datos. Nada de eso es para el jugador, y todo es lo que te gustaría tener cuando alguien te llame por teléfono por una máquina que está a quinientos kilómetros.

singeSetQuitKeyEnabled(false)
hasBezel = mainBezelLoaded()

Al final, fuera de todas las funciones, así que se ejecuta una vez cuando se carga el script. Ninguna de las dos cosas es para hacerla en cada fotograma, y mainBezelLoaded no puede cambiar mientras el juego se ejecuta.

Pruébalo

  1. Cambia el precio. Abre el menú de servicio, pon dos monedas por crédito y echa una moneda. Mira cómo no aparece el crédito, y mira el contador de monedas de la última línea. Luego sal, vuelve a arrancarlo y comprueba que el precio se ha quedado.

  2. Juega gratis. Activa el juego gratis y comprueba que el inicio funciona sin monedas y que los créditos no se vuelven negativos.

  3. Añade una página. Pon una segunda página de información de servicio tras el botón 3 — los campos de singeGetSystemInfo() son un buen comienzo, y su entrada en la referencia los enumera todos.

  4. Gira la pantalla. Ejecútalo con --rotate=90 y mira cómo queda tu diseño. Luego haz que la página de servicio se pueda leer con esa rotación, que es más difícil de lo que parece y es justo el trabajo que pide una recreativa vertical.

  5. Quita el teclado. Desenchúfalo, o prométete no tocarlo, y recorre todas las pantallas con un mando. Cualquier cosa a la que no llegues es un fallo.

Rómpelo a propósito

Borra el bloque de SWITCH_QUIT de onInputPressed, dejando singeSetQuitKeyEnabled(false) donde está, y ejecútalo.

Ahora no hay nada que salga. Esc no hace nada, Q no hace nada y tu juego no tiene salida, que es exactamente lo que pediste. No es un fallo y no hay ningún mensaje; el motor ha hecho exactamente lo que le dijeron.

Cierra la ventana con su botón de cerrar. Eso funciona siempre, diga lo que diga un script, y es la puerta que te dejaste abierta. A pantalla completa, Alt-Enter te devuelve primero a una ventana.

Vale la pena sufrir este en tus propias carnes. Desactivar la tecla de salida es lo único de este libro que puede dejarte con un programa del que no puedes salir, y la costumbre que lo evita es sencilla: escribe la salida en la misma sesión en que desactivas la tecla de salida, nunca más tarde.

Lo que has aprendido

  • Una recreativa no tiene teclado, así que todas las pantallas del juego tienen que funcionar con un stick y un botón.

  • controls.cfg asigna teclas, botones de mando y direcciones del stick a los nombres SWITCH_ que tu juego ya usa, y tu juego nunca sabe cuál se pulsó.

  • Se leen por turno cuatro archivos de asignaciones, cada uno sustituyendo al anterior, así que pueden existir a la vez un archivo para toda la máquina y uno para cada juego.

  • Todo dispositivo que abre Singe es un mando, incluida una placa encoder de recreativa, y la herramienta Input Test dice lo que está llegando.

  • El motor se queda la pausa, la salida, la captura de pantalla y atrapar el ratón; el resto son tuyos.

  • Las monedas se cuentan y se convierten en créditos al cambio del operador, y una máquina vuelve sola al modo de atracción.

  • SWITCH_SERVICE es el interruptor del operador, y lo que hay tras él es el precio, la dificultad, una forma de borrar las puntuaciones y qué máquina es.

  • saveFlush() escribe un ajuste ya, porque una recreativa se queda sin corriente sin avisar.

  • singeSetQuitKeyEnabled(false) le pasa el interruptor de salida a tu juego. Escribe la salida en ese mismo momento.

  • Un bezel es arte con un hueco, y --rotate gira toda la presentación para un monitor vertical.

Fin

Eso son treinta y una lecciones, y sabes escribir un juego.

No uno perfecto, y todavía no uno grande, pero lo que hay entre aquí y cualquiera de las dos cosas es tiempo y práctica, no otro libro. Empezaste con cinco líneas que ponían una palabra en una pantalla negra. Ahora sabes qué es una variable, para qué sirve una función, cómo dibujar, cómo hacer ruido, cómo saber cuándo se han tocado dos cosas, cómo guardar una puntuación en algún sitio donde sobreviva, cómo hacer de una película un mundo, cómo poner un modelo en una habitación con una luz encima y cómo darle todo a un desconocido.

Lo que necesitas ahora es la Referencia de Singe, no este libro. Es la referencia de cada función, cada argumento y cada valor devuelto, y es lo que de verdad tendrás abierto mientras trabajas. Viene con este libro, como Reference.pdf y Reference.html. Lee la entrada antes de usar la llamada; en la mayoría hay una nota sobre el error que comete la gente con ella.

Lee también los scripts que vienen con Singe. Singe/Menu.singe, Singe/Tools.singe y Singe/Framework.singe no son demostraciones escritas para leerse — son el menú y las herramientas de servicio que llevas usando todo este tiempo, haciendo trabajo de verdad con las mismas funciones que tienes tú. Averiguar cómo hace algo el programa de otra persona es una habilidad en sí misma, y esos son un sitio amable para practicarla.

Y está Forge, una herramienta aparte con su propio libro, para describir un juego en lugar de escribirlo. Es otro camino. No lo necesitas, pero ahí está.

El próximo juego es tuyo. Haz primero el pequeño, termínalo y pónselo delante a alguien. Terminar es la parte que nadie te dice que es la difícil, y es la única que convierte una carpeta llena de scripts en un juego al que alguien ha jugado.

Ve y constrúyelo.