singe/docs/es/Learn.adoc

= Aprende a programar con Singe
Scott Duensing <scott@kangaroopunch.com>
:revnumber: 3.00
:revdate: 2026
:doctype: book
:toc: left
:toclevels: 3
:title-logo-image: image:singeLogo.png[Singe, pdfwidth=2.6in, align=center]
:source-highlighter: rouge
:icons: font
:experimental:
:imagesdir: ../images
:lang: es
include::locale.adoc[]

[preface]
[#_before_you_begin]
== 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.

[#_what_you_need]
=== 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.

[#_how_to_read_this_book]
=== 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.

[#_how_your_folders_are_laid_out]
=== 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.

[literal]
----
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.

[#_what_comes_with_this_book]
=== 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.

[#_this_is_not_the_forge_book]
=== 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.

[#_the_series]
== 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* -- `for` y `while`, 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, `debugPrint` y recargar con F5.

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

[start=9]
. *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.

[start=14]
. *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.

[start=19]
. *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.

include::lessons/01-hello.adoc[]

include::lessons/02-numbers.adoc[]

include::lessons/03-decisions.adoc[]

include::lessons/04-repeating.adoc[]

include::lessons/05-functions.adoc[]

include::lessons/06-tables.adoc[]

include::lessons/07-a-game.adoc[]

include::lessons/08-when-it-goes-wrong.adoc[]

include::lessons/09-pictures.adoc[]

include::lessons/10-sound.adoc[]

include::lessons/11-hitting-things.adoc[]

include::lessons/12-score.adoc[]

include::lessons/13-game-folder.adoc[]

include::lessons/14-video.adoc[]

include::lessons/15-threaded.adoc[]

include::lessons/16-branching.adoc[]

include::lessons/17-light-guns.adoc[]

include::lessons/18-qte.adoc[]

include::lessons/19-text.adoc[]

include::lessons/20-gui.adoc[]

include::lessons/21-subtitles.adoc[]

include::lessons/22-3d.adoc[]

include::lessons/23-models.adoc[]

include::lessons/24-physics.adoc[]

include::lessons/25-particles.adoc[]

include::lessons/26-navigation.adoc[]

include::lessons/27-midi.adoc[]

include::lessons/28-online.adoc[]

include::lessons/29-databases.adoc[]

include::lessons/30-shipping.adoc[]

include::lessons/31-cabinet.adoc[]