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.
-
Hola — un script, una función, una cadena y algo en pantalla.
-
Números que cambian — variables, aritmética y hacer que algo se mueva.
-
Tomar decisiones —
if, comparaciones y leer los controles. -
Otra vez —
forywhile, y dibujar cien de algo. -
Tus propias funciones — argumentos, valores de retorno y por qué molestarse.
-
Listas de cosas — tablas,
ipairs, añadir y quitar. -
Un juego — todo lo visto hasta ahora, jugable, en unas ciento veinte líneas.
-
Cuando algo sale mal — leer errores,
debugPrinty recargar con F5.
Segunda parte: un juego de verdad. Arte, sonido y la forma que toma un juego terminado.
-
Imágenes — sprites, cargar, dibujar y fotogramas.
-
Sonido — efectos, música y cuándo cargar cada cosa.
-
Chocar con cosas — colisiones, el kit de juego y las zonas de impacto.
-
Puntuación, vidas y fin de partida — estado, guardar y volver a empezar.
-
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.
-
Reproducir vídeo — el disco, los fotogramas, saltar y esperar.
-
La otra forma de escribirlo — el modelo con hilo («threaded»), y por qué le va bien al vídeo.
-
Ramificaciones — elecciones, caminos y la forma de un juego de vídeo con ramificaciones.
-
Pistolas de luz — apuntar, disparar y la calibración que necesita una recreativa.
-
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.
-
Texto con buen aspecto — fuentes, calidad y medir.
-
Menús y pantallas — la GUI, los documentos y el estilo.
-
Subtítulos — y por qué son un sistema aparte.
-
Hacia el 3D — escenas, cámaras y coordenadas.
-
Modelos y luz — glTF, materiales y animación.
-
Física — cuerpos, fuerzas, articulaciones y cuándo no usarlos.
-
Partículas — emisores, y cómo hacer una explosión.
-
Personajes que se mueven solos — navegación y búsqueda de caminos.
-
Música y MIDI — pistas, soundfonts e instrumentos.
-
En línea — cuentas, tablas de récords y el catálogo.
-
Guardar datos — bases de datos, tablas y las preguntas que les haces.
-
Publicarlo — empaquetar, parchear, licencias y la publicación.
-
En una recreativa — controles, menús de servicio, bezels y las cosas que solo importan en hardware de verdad.
Lección 1: Hola
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.
-
Mueve el texto. Cambia
overlayPrint(2, 2, "Hello!")poroverlayPrint(10, 5, "Hello!"). Luego prueba(0, 0). Luego prueba(200, 2), y averigua por qué ha desaparecido. -
Di otra cosa. Pon tu nombre entre las comillas.
-
Di dos cosas. Añade una segunda línea
overlayPrintdebajo de la primera, con otro número de fila y otro texto. Nada te impide tener tantas como quieras. -
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
functionagrupa instrucciones bajo un nombre y se detiene en suend. -
onOverlayUpdatees 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.
onOverlayUpdatees 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
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
-
Cambia las velocidades. Prueba
speedX = 1yspeedY = 1. Luego prueba0.05para las dos. Luego haz una mucho mayor que la otra. -
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.lenhaciendo su trabajo. -
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. -
Que no vaya de lado. Pon
speedX = 0y ejecútalo. Averigua por qué ahora la palabra no sale nunca de la columna cero, y por qué elifdel borde izquierdo no salta nunca. -
Rompe el contador de fotogramas a propósito. Vuelve a meter la línea
frames = 0dentro de la función, encima deframes = 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 + 1calcula 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
onOverlayUpdatese 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.
-
overlayGetWidthyoverlayGetHeightte dicen el tamaño de la superficie de dibujo, así que nunca tienes que adivinarlo. -
overlayClearimporta 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
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 es menor que b |
|
a es mayor que b |
|
a es menor o igual que b |
|
a es mayor o igual que b |
|
a es lo mismo que 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 salvofalseynil.
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
-
Cambia la velocidad.
BOX_SPEED = 1yBOX_SPEED = 8. Con ocho, fíjate en lo que hace el límite cuando empujas la caja contra una esquina. -
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 eltostringy lee el error que te da Lua. -
Que vaya más rápido con un botón pulsado. Añade un indicador
runningcontrolado porSWITCH_BUTTON1en los dos callbacks de entrada, y usa unifenonOverlayUpdatepara moverte el doble deBOX_SPEEDmientras sea verdadero. -
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
andpara 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. -
Quita lo de soltar. Borra toda la función
onInputReleasedy 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 … endejecuta un cuerpo solo cuando la respuesta es verdadera. -
elseda el otro caso, yelseifencadena 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. -
trueyfalseson valores, y puedes guardarlos en variables. -
and,orynotunen y dan la vuelta a esas respuestas. -
niles lo que obtienes de un nombre al que nunca has dado valor, y no es cero. -
Todo es verdadero salvo
falseynil. -
onInputPressedyonInputReleasedson callbacks que Singe llama con un valorSWITCH_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.
-
overlayBoxdibuja un contorno en píxeles, ycolorForegroundes 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
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
forcuando 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
whilecuando 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
-
Más y menos. Prueba
STARS_PER_LAYER = 200, luego4. LuegoLAYERS = 8y fíjate en lo que hacelayer * LAYER_BRIGHTconshadecuando el número de capa se hace grande. Los números que admitecolorForegroundllegan hasta 255. -
Cambia el espaciado. Pon
ACROSS_STEPa 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. -
Quita el titileo. Cambia la línea de
math.randompor un simpleshade = layer * 70y compara. Decide cuál te gusta más; no hay respuesta correcta, y darte cuenta de que tienes una preferencia es parte del trabajo. -
Haz que caigan hacia arriba. Un carácter.
-
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 … endejecuta 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.
-
fornecesita undo, y todo bucle necesita unend. -
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 … endrepite mientras la pregunta sea verdadera, y tienes que cambiar algo en el cuerpo tú mismo. -
Usa
forcuando sabes cuántas veces, ywhilecuando 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.floortira 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 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
-
Cambia el nombre de un parámetro. En
drawStar, cambiaxeyporacrossydown, 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. -
Dibújalos al revés. Intercambia
drawStars()ydrawPlayer()enonOverlayUpdatey 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. -
Usa
clampcon un tono. CambiashadeForporreturn clamp(math.random(60, 90) + layer * 90, 0, 200)y mira las tres capas. Luego quita elclampy vuelve a mirar:colorForegroundte estaba conteniendo los números sin decir nada todo este tiempo, y ahora puedes ver dónde. -
Llama a
drawStarcon dos argumentos. EscribedrawStar(100, 100)en algún sitio dedrawLayery ejecútalo. El error nombra exactamente lo que falta. Léelo antes de volver a poner el tercer argumento. -
Mueve una variable local. Coge la línea
local drift = 0y 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ó.
-
returndevuelve un valor y detiene la función ahí mismo, y una función que termina sin él devuelvenil. -
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.
-
localcrea 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
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.
-
ies1. La estrella uno está bien. -
ies2. 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. -
ies3. 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. -
ies4. Ya no hay elemento cuatro.stars[4]esnil.
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
-
Hazlo más profundo. Cambia
math.random(1, 3)pormath.random(1, 6)ySTAR_SHADEpor25. Más velocidades, más tonos, un cielo más profundo. -
Menos estrellas, ráfaga más grande. Pon
STAR_COUNTa10yBURST_COUNTa100, 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. -
Dale a una estrella otro campo. Añade
age = 0anewStar, suma uno astar.ageenmoveStarsy ponstars[1].ageen pantalla junto a la cuenta. No hace falta cambiar nada más del programa para que cada estrella lleve un dato nuevo. -
Deja de quitarlas. Borra las tres líneas del bloque
if star.y >= heightdemoveStarsy 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. -
Hazlo hacia delante. Cambia
for i = #stars, 1, -1porfor i = 1, #starsy 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.
-
#listes cuántos elementos tiene, ylist[#list]es el último. -
table.insertañade un elemento, al final o en la posición que digas;table.removesaca 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. -
ipairsrecorre 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
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í. -
SCANCODEyMODIFIER, nombres para cada tecla de un teclado, para un juego que lee lo que se escribe en lugar de un joystick. -
De
GAMEPAD_0aGAMEPAD_3y deMOUSE_0aMOUSE_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
-
Hazlo más fácil, y luego injusto. Cambia
PLAYER_WIDTHa80y juega una partida. Luego cámbialo a12, 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. -
Que acelere más deprisa. Cambia
BLOCK_FASTERde0.05a0.5y mira cuántos puntos consigues. Luego prueba0, y pregúntate si el juego sigue mereciendo la pena. -
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. -
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_COLUMNStambién lo preguntó. -
Ponlo en pausa. Añade un cuarto estado,
"paused".SWITCH_BUTTON2debería cambiar entre"playing"y"paused", y nada debería moverse en pausa. Bien hecho, son tres líneas y no tienes que tocarupdatePlayingen 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.
-
collideRectsresponde 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
stateque 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
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 tienelocaldelante en ningún sitio. -
local— un nombre que declaraste conlocalen la función en la que estás. -
field— un nombre detrás de un punto, como laydeblock.y. -
upvalue— unlocalde más afuera que esta función puede ver, que es lo que son todas las variables dedodge.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:
-
Has escrito mal una de tus propias funciones.
-
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.
-
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.
-
La hiciste
localy la llamaste desde algún sitio por encima de donde se declara. Esa es justo la razón de que las funciones dedodge.singesean 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
-
Conócelos a todos. Comete a propósito en
dodge.singecada 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. -
Vigila dónde nacen. Pon dentro de
spawnBlockundebugPrintque imprima laxdel bloque nuevo. Juega treinta segundos y luego mira los números. ¿Están repartidos por toda la pantalla, o prefieren un extremo? -
Apágalo. Cambia
DEBUGafalseen el script de la lección, y comprueba por ti mismo que no se imprime nada y que el juego no ha cambiado. -
Un fallo sin error. En
updatePlaying, cambiaif spawnTimer ⇐ 0 thenporif 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 undebugLogdentro despawnBlock, añadespawnTimera la primera línea que imprimedebugReporty vuelve a jugar. Averigua por lo que dicen, y por lo que uno de ellos no dice nunca, por qué==era la pregunta equivocada. -
Rompe el nombre de un callback. Cambia el nombre de
onInputPressedporonInputPressy 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 scriptsignifica que no se ha ejecutado nada; la forma con traza significa que estaba funcionando y se paró. -
niles 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
endque 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.
-
debugPrintte enseña lo que guarda de verdad una variable.tostringhace que cualquier cosa se pueda imprimir, y un interruptor comoDEBUGquita 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
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.glbySinge/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
-
Centra la nave en su posición. Añade
truecomo cuarto argumento alspriteDrawde 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. -
Más rocas. Cambia
ROCK_COUNTa 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. -
Agranda la nave. Añade
spriteScale(shipSprite, 2)al final del todo del archivo, en la línea de encima destartGame(). 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 aspriteGetWidthy mira cómo se arregla. La entrada despriteScaleen la referencia explica lo que hace el escalado con las medidas. -
Mete al caminante. Carga
walk.pngen 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 deonOverlayUpdateva el dibujo — delante de las estrellas, detrás de las rocas. -
Descarga algo que todavía estás usando. Añade
spriteUnload(starSprite)al final del archivo, después destartGame(), 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. -
spriteLoadte devuelve un handle: un número que para el motor significa «esa imagen», y que guardas en una variable. -
DIRes 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 deonOverlayUpdate. Un cuarto argumentotruehace que la posición sea el centro. -
Carga una vez, al principio del archivo. Cargar dentro de
onOverlayUpdatese come la memoria hasta que el juego se muere. -
spriteUnloaddevuelve una imagen, normalmente desdeonShutdown, y después el handle está muerto. -
El PNG lleva transparencia, y por eso las esquinas de la nave no son cajas negras.
-
spriteGetWidthyspriteGetHeightmiden 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, yspriteDrawFrame(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
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.
-
musicStoppuede 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
-
Baja todavía más el disparo. Cambia el
35delsoundPlaydel disparo por10, y luego por63. Encuentra el número con el que queda por debajo de las explosiones en lugar de por encima. -
Baja la música sin tocar los efectos. Cambia
musicSetVolume(50)pormusicSetVolume(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. -
Corta el final. En
endGame, cambiamusicStop(theme, 1500)pormusicStop(theme). Escucha los dos finales dos veces. La diferencia es un número en un argumento, y no es una diferencia pequeña. -
Ponle un motor a la nave. Arranca
soundPlay(clickClip, -1, 12)enstartGame, guarda el canal que te da en una variable propia y páralo enendGame. 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 elsoundStop, juega tres partidas seguidas y escucha lo que has construido. -
Cuenta los canales. Imprime el número de canal cada vez que explota una roca. Luego sube
ROCK_COUNThasta 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
-
soundLoadlee un clip y devuelve un handle. Carga una vez, arriba del todo del archivo. -
soundPlayempieza 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,
soundPlaydevuelve-1y 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;
soundStopes para sonidos que ya no deberían sonar. -
soundUnloadno 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
0a63. El de la música, de0a128. 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
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:
-
collideCirclesycollidePointCircle, 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úmerosx,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
-
Quita los márgenes. Pon
ROCK_PADa0y juega un minuto. Luego ponlo a8y vuelve a jugar. Con uno de los dos parece que el juego te miente. -
Mira lo que estás comprobando. Pon
SHOW_BOXESatruey observa los contornos verdes mientras una roca pasa junto a la nave. Ahora ponSHIP_PAD_Xa16, juega, y fíjate en que ya nada puede darte. Averigua por qué con la aritmética deshipBox. -
Haz el disparo demasiado rápido. Pon
SHOT_SPEEDa40. Cuenta a cuántas rocas de cada diez les das. Averigua con los números por qué pasa eso antes de volver a cambiarlo. -
Usa el disparo entero. Reescribe
shotHitsRockpara que usecollideRectscon el rectángulo completo del disparo en lugar decollidePointRectcon su punta. Juega con las dos y decide cuál prefieres; no hay respuesta correcta, y vale la pena saberlo. -
Haz la roca redonda. Dale a la roca un círculo en lugar de una caja: su centro está a
rock.x + rockWidth / 2en horizontal y arock.y + rockHeight / 2en vertical, y un radio de10es más o menos lo justo. UsacollideRectCirclepara la nave ycollidePointCirclepara el disparo, y dibuja el círculo endrawBoxesconoverlayCircle, 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.
-
collideRectsrecibe una esquina y un tamaño para cada uno de dos rectángulos y respondetrueofalse. 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.
-
collidePointRectpregunta 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.
-
onCollisiones 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
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
-
Vuelve al título. Una máquina recreativa no se queda en GAME OVER para siempre. Busca
timerAfteren la sección Temporizador de la referencia, otra parte del kit de juego, y úsalo enendGamepara devolver el estado aTITLEcinco segundos después de que termine la partida. Luego pulsa1enseguida al terminar una partida y asegúrate de que el temporizador no devuelve tu partida nueva al título a los tres segundos. -
Muestra las vidas como naves. Dibuja
shipSpriteuna vez por vida en la esquina superior derecha conspriteDrawen lugar de imprimir el número. Un bucleforde la lección cuatro, yshipWidthte dice a qué distancia ponerlas. -
Guarda más que un número. Añade
saveSet("gamesPlayed", saveGet("gamesPlayed", 0) + 1)astartGame, e imprímelo en la pantalla de título. Sal, vuelve a ejecutarlo y mira cómo lo recuerda. -
Encuentra el archivo y rómpelo. Abre
data/rocks/save.jsonen 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. -
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:bestsigue en memoria, ysaveClearno 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.
-
onOverlayUpdatedecide 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.
-
saveSetguarda un valor bajo una clave, ysaveGetlo vuelve a leer en una ejecución posterior. -
saveFlushescribe 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. -
saveGetsin valor por defecto respondenilcuando no se ha guardado nada, ynilrompe el primer fotograma en un ordenador que nunca ha ejecutado tu juego. -
Cuando mezcles
andyor, 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
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
-
Haz un arte mejor. Si tienes un programa de dibujo, haz un
marquee.pngcomo es debido: una tira ancha con ROCKS en letras grandes. Ponlo en lugar de la captura de pantalla y vuelve a mirar el menú. -
Dale un games.dat a Dodge. Escribe un
games.daten tu carpetadodgede la lección siete y arranca el menú. Ahora hay dos juegos, por orden de título. Luego cambia elTITLEde Rocks aAsteroid Fieldy mira cómo sube por encima de Dodge: la lista se ordena por título, no por carpeta. -
Rompe games.dat para el menú. Borra una de las llaves de cierre del
games.datderocksy arranca el menú. Tu juego ha desaparecido de la lista, y la terminal dice por qué. Vuelve a ponerla. -
Equivócate con SCRIPT. Pon
CANVAS_Xa1280yCANVAS_Ya720, y ejecutaSinge rocks. La zona de juego es más ancha. Ahora cambiaSCRIPTarocks.singey 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. -
Encuentra tu partida guardada. Arranca el juego desde el menú, marca un récord, sal al menú y sal del menú. Ejecuta
Singe rocksy mira el título. Luego busca endata/rocksel 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 carpetaSingedel 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.dates un archivo de Lua que contiene una listaGAMES, y cada entrada es un juego. -
Una entrada necesita
TITLEySCRIPTy nada más; sus rutas cuentan desde la carpeta de encima delgames.dat. -
CABINET,MARQUEE,YEAR,GENRE,DEVELOPER,PUBLISHERyDESCRIPTIONson lo que el menú le muestra al jugador, y F12 saca una imagen que puedes usar para las dos primeras. -
REQUIRESle 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.shoMenu.batarranca 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 ungames.datque 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
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
-
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.
-
Avanza paso a paso. Cambia
discSkipForward(30)pordiscSkipForward(1)y mantén pulsada la flecha derecha. Ahora cambiastopAta un fotograma en mitad del dragón y usadiscSearchy la tecla de flecha para caer exactamente en él. -
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. -
Pide un fotograma que no existe. Cambia la línea de
SWITCH_RIGHTpordiscSkipToFrame(100000). No se cuelga. Lee la entrada dediscSkipToFrameen la referencia y busca la frase que dice por qué. -
Juégalo sin el vídeo. Ejecuta
Singe -R moviey 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
discno 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.
-
discGetFramepregunta dónde está el disco;discGetFrameCountdice cuántos fotogramas hay;discGetStatedice qué está haciendo el disco. -
discPlay,discPauseydiscStoplo manejan.discSearchva a un fotograma y pausa;discSkipToFrameva 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
disces inofensiva, ySINGE_DISCes 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
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:
-
Empieza la película desde el principio y reprodúcela hasta el fotograma 120.
-
Para ahí y pide al jugador que pulse la barra espaciadora.
-
Cuando la pulse, sigue reproduciendo hasta el fotograma 300.
-
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
-
Añade un paso. Después de
waitForButton, haz que la película salte hacia atrás en lugar de seguir:discSkipToFrame(0), luegoplayTo(60), y después sigue como antes. Dos líneas nuevas en un solo sitio, y nada más del script tiene que enterarse. -
Añade el mismo paso al otro. Ahora hazlo en
events.singe. Cuenta cuántos sitios has tenido que tocar. -
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. UsadiscGetFramey recuerda dónde empezaste. -
Quita una cesión. Borra el
singeYield()de dentro deplayToy ejecútalo. Prepárate para cerrar la terminal, porque nada más lo detiene. Ahora vuelve a ponerlo y borradrawFrame()en su lugar, y averigua, por lo que ves, por qué el contador de fotogramas se para pero la película no. -
Haz un bucle. Mete todo
singeMaindentro dewhile true do … endpara 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
singeMaino 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
whilecon unsingeYielddentro. 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
onOverlayUpdatecuando existesingeMain. -
Todos los demás callbacks se siguen disparando, así que los eventos y los pasos se mezclan sin problema.
-
Volver de
singeMaintermina 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
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 |
|---|---|---|
|
0 a 119 |
Fuego, y el dragón aterriza. ¿Izquierda o derecha? |
|
120 a 259 |
Echa fuego. ¿Te agachas a la izquierda o corres a la derecha? |
|
260 a 339 |
Te come. Pierdes una vida. |
|
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:
firstylast-
Los fotogramas entre los que va la escena.
ask-
El fotograma en el que aparece la pregunta. El jugador tiene de
askalastpara responder, y ese es el temporizador. prompt-
Lo que dice la pregunta.
leftyright-
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
-
Añade un final. Dale a
escapeuna pregunta y una segunda escena final que reutilice fotogramas de algún punto de la película. Solo cambia la tabla. -
Hazlo justo. Baja
asken 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. -
Mueve el punto de control. Cambia el
goesTodepita"sunset"y juega. Luego piensa en qué pasa si un jugador muere enarrive— y en si la escena de muerte debería saber de dónde viene en lugar de que se lo digan. -
Cuenta lo que ha visto el jugador. Añade una tabla junto a
scenesque 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». -
Rompe el mapa. Cambia el
leftdearrivea"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.leftyscene["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 —
deathen tres de los cuatro registros — mantiene la descripción corta y honesta. -
Comparar
nilcon un número es un error, yandes 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
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
-
Mueve una diana. Cambia la
xde la tercera diana a680y 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. -
Haz las dianas más fáciles. Cambia
TARGET_SIZEa140. 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. -
Lleva la cuenta de la puntería. Añade una línea que imprima
hitscomo porcentaje deshots. Protégete contra la división por cero antes del primer disparo, y averigua qué imprime Lua si no lo haces. -
Haz que una diana te castigue. Añade un campo
penalty = truea 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 tienennilahí. -
Quita el
returndel bucle deonInputPressed, 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ú.
-
onInputPressedrecibe un segundo argumento que dice qué ratón o qué pistola ha disparado, ynilcuando 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 bte dabcuandoaesnil. -
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
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
-
Hazlo más difícil. Cambia el
lastdel primer movimiento de105a75. Quince fotogramas son medio segundo. Juégalo y averigua si puedes. -
Añade un movimiento. Pon una quinta línea en la tabla con una ventana entre los fotogramas
370y400, y subeLAST_FRAMEa418. No deberías tener que tocar ninguna otra línea. Si tienes que hacerlo, algo del código sabe demasiado de la tabla. -
Puntúa la rapidez. Da más puntos por responder pronto. En
onInputPressed, donde se puntúa la respuesta correcta, calculaleftyspana partir demoveydiscGetFrame()igual que hace el indicador, y sumaRIGHT_SCORE * left // spanen lugar deRIGHT_SCORE. Decide si eso hace el juego mejor o solo más ajetreado. -
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. -
Dos indicaciones a la vez. Solapa las ventanas de dos movimientos y mira qué pasa.
moveAtdevuelve 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.
-
nilen 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
returntemprano para los casos que no te interesan — evitan que el trabajo de verdad quede anidado. -
//divide y tira los decimales; multiplica antes de dividir. -
overlayBoxdibuja un contorno, así que una barra rellena es una pila de llamadas aoverlayLine. -
Un movimiento perdido es una ramificación, y
discSkipToFramela 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
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
-
Cambia la calidad. Pon
FONT_QUALITY_SOLIDen la línea defontQualityy mira la curva de laSdeASTEROID. Luego pruebaFONT_QUALITY_SHADEDy fíjate en lo que pasa detrás de cada cadena. -
Pon la pista en amarillo. Mueve la línea
colorForeground(140, 200, 255)de encima defontToSpritea justo encima delspriteDrawque dibujahintImage, 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 conspriteSetTintjusto antes de dibujarla. -
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. -
Quita la comprobación de
scoreShown, para querenderScore()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 quefontPrintte ahorra cuando le dejas. Luego quita también elspriteUnloadderenderScore, déjalo en marcha un minuto y vigila la memoria que usa tu juego. -
Imprime un reloj en milisegundos. Cambia la línea del reloj para que imprima
singeGetTicks()sin el// 1000. Sigue funcionando; ahora es una cadena quefontPrintno ha visto nunca, en cada fotograma. En un ordenador lento, ese es el tipo de texto que cuesta. -
Usa tu propia fuente. Busca un
.ttfen tu ordenador, cópialo junto a tu script y cárgalo conDIR .. "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
-
fontLoadabre un archivo TrueType a un tamaño en puntos fijo y devuelve un handle. Un tamaño, un handle. -
Cargar una fuente la selecciona;
fontSelectelige entre las fuentes cargadas. -
fontPrintcuenta en píxeles yoverlayPrintcuenta en celdas de carácter. -
El color no es un argumento.
colorForegroundes un ajuste; ponlo y luego dibuja. -
fontQualityelige cómo se rasterizan las letras, yFONT_QUALITY_BLENDEDes la respuesta habitual. -
fontPrintguarda 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. -
fontToSpritedibuja en un sprite, quespriteGetWidthmide y que las llamadassprite*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.
-
colorForegroundllega al texto cuando se crea, nunca a un sprite cuando se dibuja;spriteSetTintes la forma de volver a colorear un sprite después. -
fontUnloadlibera 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
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
-
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. -
Cámbiale el estilo. En el bloque
<style>, cambia#frameporwidth: 260dp; margin: 20dp;y mira cómo el panel se mueve y el texto se vuelve a repartir en líneas él solo. -
Quita el
guiSetInput(gui, true)deopenMenu. La página sigue apareciendo. Averigua, solo con lo que ves en la pantalla, qué has perdido. -
Deja la página a la vista todo el tiempo. Borra las llamadas a
guiHide, cambia las dos llamadasguiSetInput(gui, false)atruey 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 llevaguiSetInput(gui, false). -
Pon la puntuación en la página en lugar de en el HUD. Llama a
guiSetValueparascoreen cada fotograma en lugar de solo enopenMenu, y borra la línea defontPrint. 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;
guiNewcrea una yguiDeletela libera. -
guiLoadpone un documento RML en una GUI y lo muestra;guiHide,guiShowyguiCloselo gestionan después. -
guiDrawcompone la GUI sobre el overlay durante un fotograma, así que va enonOverlayUpdatecomo todas las demás llamadas de dibujo. -
Una GUI nueva solo muestra;
guiSetInputes lo que la hace usable. -
guiSetHandlerejecuta tu función cuando se hace clic en un elemento o se cambia,guiSetValueescribe en un elemento yguiGetValuelee uno. -
Un evento que ha usado un elemento nunca llega a tus propios callbacks; todo lo demás pasa como siempre.
-
Singe/gui.rcsses 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
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..cuees el bloque que lleva la altura que pidiósrtPosition, y.cue .textes 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
-
Añade una cuarta entrada a
subtitles.srt, entre los segundos once y trece. Guarda y ejecuta. Luego ponla fuera de orden, como entrada99, la primera del archivo, y comprueba que sigue funcionando. -
Dale a una entrada una marca de tiempo mala — escribe
00:00:05.500con 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. -
Cámbiales el estilo. En tu propio
subtitle.rcss— la copia que está junto a tu script, no la deSinge— cambia.cue .texta 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. -
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.
-
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 consaveSetpara 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. -
srtLoadconvierte 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
falsecuando no puede cargar, también cuando no hay disco. Comprueba la respuesta. -
srtEnablelos activa, y un script siempre empieza con ellos desactivados. -
srtPositionlos coloca como un porcentaje hacia abajo de la imagen, de1a95. -
srtClearquita lo que se esté mostrando, yoverlayBannercomparte el mismo documento. -
srtLoadTracklee los subtítulos del propio archivo de vídeo cuando los lleva. -
Singe reescribe su carpeta
Singeen cada arranque, así que para cambiar el estilo de los subtítulos copiassubtitle.rmlysubtitle.rcssjunto 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
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
-
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, elnodeLookAtmantiene la caja centrada, así que consigues otro ángulo de la misma escena cambiando un número. -
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. -
Pon una segunda caja. Copia las dos líneas que crearon la caja, cambia el nombre de la variable a
marky dalenodeSetPosition(mark, 3, 0, 0)ynodeSetScale(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. -
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. -
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
nodeSetParenten 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.
-
nodeSetPositionynodeSetRotationfijan un valor directamente;nodeMoveynodeRotatelo cambian en una cantidad. -
Cualquier nodo puede ser la cámara.
nodeLookAtla apunta ycameraSetla elige. -
El campo de visión de
cameraSetPerspectivecambia 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
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
-
Apaga las luces. Comenta todo el bloque del
sunponiendo--al principio de cada línea, y ejecútalo. Luego haz lo mismo consceneSetAmbient. Recuerda cómo se ve, porque un día te pasará sin querer. -
Mueve el sol. Cambia
nodeLookAt(sun, 0, 1.5, 0)pornodeLookAt(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. -
Calienta la antorcha. Sube la intensidad de la luz puntual de
14a60y baja su alcance a4. 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. -
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. -
Busca otra parte. Las partes del dragón se llaman
head,jaw,neck,tail,body,crest,hornL,hornR,wingL,wingR,foreLegL,foreLegR,hindLegLyhindLegR. Haz que la cola se balancee con su propiomath.sina una velocidad distinta de la de las alas. Luego pruebanodeFind("wings", dragon)y mira lo que hace un nombre equivocado cuando le pasas elnildirectamente anodeSetRotation.
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
-
modelLoadlee un.glbuna vez;modelInstancecoloca 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
nodeSetScaleen 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
lightSetShadowlas activa, y cada una tiene su coste. -
nodeFindllega a una parte de un modelo por su nombre en el archivo. -
modelGetAnimationsdice 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
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_STATICno 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_DYNAMIClo 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_KINEMATICva 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
-
Cambia el mundo. Añade
physicsSetGravity(0, -1.62, 0)cerca del principio y vuelve a disparar. Luego prueba0, -30, 0. Las mismas cajas, otro planeta, una línea. -
Cambia la bola. Haz la bola diez veces más pesada con
bodySetMass(ball, 30), y luego diez veces más ligera con0.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. -
Haz que las cajas sean de hielo. Añade
bodySetFriction(crate, 0.02)encrateAt, 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. -
Equivoca la forma a propósito. En
crateAt, cambia las medidas del cuerpo a2, 2, 2mientras la malla se queda en0.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. -
Puntúalo como es debido. Usa
bodyIsRestingen 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.
-
bodySetVelocitysustituye el movimiento de un cuerpo,bodyApplyImpulsees un golpe ybodyApplyForcees 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.
-
onCollisioninforma de cada contacto nuevo con su punto y su velocidad, y un cuerpo activador informa de las llegadas y las salidas a través deonTrigger. -
bodyIsRestingte dice cuándo se ha parado todo, que suele ser cuando ha terminado un turno. -
physicsSetDebugdibuja 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
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
-
Convierte el escape en humo. Cambia
emitterSetBlend(exhaust, PARTICLE_ADD)porPARTICLE_ALPHA, pon el color en gris que se desvanece a gris transparente y haz que crezca en lugar de encoger conemitterSetSize(exhaust, 3, 14). Tres líneas han hecho una máquina distinta. -
Quítale el rozamiento a la explosión. Borra la línea
emitterSetDragy compara. Luego vuelve a poner el rozamiento y quita la gravedad. Una de las dos parece fuegos artificiales y la otra parece un accidente. -
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. -
Lanza mil. Cambia
emitterBurst(boom, 140)poremitterBurst(boom, 1000)y mira el recuento en pantalla. No llegará a mil. Averigua por qué a partir deemitterSetMax, luego agranda la reserva, haz las chispas cuatro veces más grandes y mira qué le pasa a la tasa de fotogramas. -
Lanza la explosión donde no está la nave. Pon
emitterSetPosition(boom, 40, 60)enexplodeen 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.
-
emitterNewsin 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.
-
emitterStartsuelta un chorro hastaemitterStop;emitterBurstlanza un puñado de golpe. Los efectos continuos son chorros, los momentáneos son ráfagas. -
emitterStopdeja que las partículas vivas terminen;emitterClearlas mata ya. -
Un emisor bidimensional se mueve con
emitterSetPositionen cada fotograma y se dibuja conemitterDrawen 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.
-
emitterSetMaxpone un tope a la reserva, yemitterGetCountte 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
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
-
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)yaddWall(6.5, 0, 7, 0.6). Ejecútalo y mira lo que muestranavDrawantes de pulsar nada. Luego manda la caja al otro lado y mira qué hace. -
Engorda a todo el mundo. Pon
AGENT_RADIUSa2.0y 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. -
Mándala al ratón. Toma el punto que hay bajo el puntero del ratón con
sceneUnproject, ajústalo a la malla connavNearesty manda la caja allí cuando se pulse el botón. QuenavNearestdevuelvaniles el caso que tienes que tratar, y ocurre siempre que el puntero está fuera del suelo. -
Añade cuatro caminantes más. Pon las cuatro líneas del caminante azul en un bucle
forde 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. -
Precalcúlala una vez. Llama a
navSave(nav, "room.nav")después denavBuild, y luego sustituyenavNew, las llamadas anavAddNodeynavBuildpor un úniconavLoad("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.
-
navNewdescribe el personaje para el que es la malla,navAddNodele pasa la geometría del nivel ynavBuildla precalcula. Después del precálculo no se puede añadir nada más. -
navSaveynavLoadguardan una malla precalculada en un archivo para que el jugador nunca tenga que esperarla. -
navDrawte muestra la malla, y es lo primero que hay que mirar cuando un personaje se porta de forma rara. -
navAgentNewle da un nodo al motor para que lo haga caminar; a partir de ahí, no muevas tú ese nodo. -
navAgentMoveTofija un destino y devuelvefalsecuando no hay forma de llegar. Tratar eso es cosa tuya, y pasa a menudo. -
onNavArrivedse llama una vez cuando un agente alcanza su destino, y se le dice qué agente es. -
navPathresponde a la misma pregunta sin mover a nadie, ynilsignifica que no hay ruta. -
Los agentes se esquivan entre sí además de esquivar el nivel.
-
navAgentGetVelocityes 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
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.
soundSetVolumenunca toca la música ymusicSetVolumenunca 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
-
Que dé cuatro vueltas en lugar de infinitas. Cambia
musicPlay(theme, -1)pormusicPlay(theme, 3)y cuenta. El número es cuántas veces se repite, no cuántas veces suena. -
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 pruebamusicStop(theme, 100). -
Muestra el canal. En
onMidiMessage, calcula el canal con(status & 0x0F) + 1e 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. -
Puntúa la velocidad. Da un punto por la nota correcta, y tres puntos si
data2pasa de cien, para que el juego premie tocarla con ganas. -
Toca la respuesta. Cuando el jugador acierte una nota, haz que el juego le devuelva un pequeño acorde con tres llamadas a
midiNoteOnseparadas 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
0a128y el de los efectos de0a63, 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
singeSetAudioDelaycorrige 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.
-
onMidiMessagete da los bytes en bruto. Los cuatro bits de arriba destatusson el tipo, los cuatro de abajo son el canal, y un note on con velocidad cero significa note off. -
Cada
midiNoteOnnecesita unmidiNoteOff, y un temporizador es la forma de emparejarlos. -
En una máquina sin MIDI, todas las llamadas responden
falseo 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
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 unnamey unvalue; -
result.standing, elvaluey elrankpropios de este jugador y el número deplayersde 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
-
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. -
Borra el identificador. Quita
GAME_IDde tugames.daty vuelve a ejecutarlo. El mensaje cambia. Vuelve a ponerlo. -
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
standingsi hace falta. -
Ponle nombre a la tabla.
scoreSubmit(score, "reaction")yscoreBoard(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. -
Haz visible la espera. Entre la llamada a
scoreBoardy 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_IDdegames.dat, un UUID que no debe cambiar nunca.singeGetGameId()lo lee. -
scoreSubmitpone 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. -
scoreBoardle 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 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
-
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. -
Ignora las salidas en falso. Añade
WHERE score > 0a la pregunta de las mejores partidas, entreFROM runsyORDER BY. Luego cuenta las salidas en falso de cada fase con una pregunta tuya. -
Añade una fase. Abre
stages.dben 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. -
Borra el historial.
runs:exec("DELETE FROM runs")vacía la tabla. Ponlo en un botón, llama arefreshdespués y mira cómo todo se queda en nada. Este es el «borrar récords» de un menú de servicio. -
Escribe mil filas. Llama a
recordmil veces en un bucle y cronométralo consingeGetTicks. Luego ponruns:exec("BEGIN")antes del bucle yruns: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.openabre 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 consqlite3.OPEN_READONLY. -
CREATE TABLE IF NOT EXISTSse puede ejecutar sin peligro cada vez que arranca el juego. -
Los valores entran con
prepare,bind_values,stepyreset, nunca pegando cadenas en el SQL. -
nrowsdevuelve las filas como tablas;urowsdevuelve las columnas mismas. -
ORDER BY,LIMIT,GROUP BY,MAXyCOUNTresponden a las preguntas para las que, si no, escribirías bucles. -
Pregunta cuando la respuesta puede cambiar, no en cada fotograma.
-
En
onShutdownse 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
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:
-
una carpeta suelta con el nombre del archivo sin su extensión —
MyGame/junto aMyGame.game; -
la carpeta de datos del juego, dentro de
files/, que es donde ha ido a parar todo lo que el juego escribe; -
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:
-
Desempaqueta la versión en una carpeta vacía y lee la lista de archivos.
-
Copia solo el archivo
.gameen 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. -
Borra la carpeta
datade 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. -
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
-
Empaquétalo. Pon este script en la carpeta de tu juego, ejecuta
--packy ejecuta el archivo.game. Luego desempaquétalo en una carpeta vacía y lee la lista de lo que ha salido. -
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.
-
Haz un parche. Cambia la versión a
1.0.3, pon solo el script en una carpetafixes, empaqueta eso como un.patchy aplícalo al juego que ya hiciste. Comprueba la versión en pantalla. -
Rompe el empaquetador. Cambia el nombre de tu
games.datun momento e intenta empaquetar. Luego déjalo como estaba, haz que uno de susSCRIPTapunte a un archivo que no existe y vuelve a intentarlo. Dos rechazos distintos, los dos antes de que se escriba nada. -
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.gameconvierte 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
DIRy escribe solo dentro desingeGetDataPath(), o tu juego funcionará suelto y fallará empaquetado. -
--patchsustituye archivos de un juego publicado en una sola transacción;--unpackvuelve a sacarlo todo. -
El empaquetador rechaza los archivos del motor, los nombres que chocan y un
games.datque 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
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:
-
Atracción. No hay nadie. La máquina muestra lo que es, hace parpadear
INSERT COINy no pide nada. -
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. -
Juego.
SWITCH_START1gasta un crédito y empieza. -
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
-
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.
-
Juega gratis. Activa el juego gratis y comprueba que el inicio funciona sin monedas y que los créditos no se vuelven negativos.
-
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. -
Gira la pantalla. Ejecútalo con
--rotate=90y 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. -
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.cfgasigna teclas, botones de mando y direcciones del stick a los nombresSWITCH_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_SERVICEes 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
--rotategira 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.