singe/docs/it/Learn.adoc

= Impara a programmare 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: it
include::locale.adoc[]

[preface]
[#_before_you_begin]
== Prima di cominciare

Questo libro ti insegna a programmare. Dà per scontato che tu non abbia mai
scritto una riga di codice in vita tua, e non dà per scontato che tu voglia
diventare un programmatore -- solo che tu voglia fare un gioco.

Ogni lezione finisce con qualcosa che puoi eseguire e con cui puoi giocare.
Niente viene tenuto da parte per dopo: non ci sono capitoli di teoria prima che
la prima immagine compaia sullo schermo. Scriverai il tuo primo programma
funzionante in una decina di minuti, e sarà lungo cinque righe.

Singe è un motore di gioco. Ci puoi fare tutto quello che puoi fare con
qualsiasi altro motore, in due dimensioni o in tre, e la maggior parte di
questo libro parla proprio di questo. Ciò che lo distingue è che può anche
riprodurre video FMV («full motion video») come il mondo in cui si svolge il
gioco, che è il modo in cui funzionavano i giochi laserdisc delle sale giochi e
che quasi nient'altro sa fare bene. È una possibilità, non un obbligo: un gioco
riproduce video solo se lo chiede, e niente di quello che scriverai nelle prime
tredici lezioni ci si avvicinerà.

Il linguaggio è Lua, che Singe usa per tutto. Lua è stato scelto da persone che
dovevano insegnarlo ad artisti e designer, e si vede. Non ci sono punti e
virgola da dimenticare, né tipi da dichiarare, né compilatori con cui
combattere. Quando sbagli, Singe ti dice il file, la riga e che cosa non ha
capito.

[#_what_you_need]
=== Che cosa ti serve

* *Singe.* Un solo file. Mettilo in una cartella, da qualche parte dove saprai
  ritrovarlo.
* *Un editor di testo.* Blocco note, TextEdit in modalità testo semplice,
  Notepad++, VS Code o qualsiasi altro programma che salvi testo semplice. Un
  programma di videoscrittura non va bene: salva una formattazione che non vedi,
  e Singe non riesce a leggerla.
* *Nient'altro.* Non ti servono un laserdisc, un file video, un programma di
  disegno o della grafica. Tutta la prima parte disegna tutto da sé, e dalla
  seconda parte in poi le immagini, i suoni, il video e i modelli che ti servono
  vengono tutti con il libro o con il motore. Ciò che ti serve è elencato qui
  sotto.

[#_how_to_read_this_book]
=== Come leggere questo libro

Digita il codice. Non copiarlo e incollarlo. Digitarlo è più lento, ed è
proprio questo il punto: farai piccoli errori, e correggerli è il modo in cui
impari a leggere quello che il computer ti dice. Ogni lezione ha una sezione
*Prova tu* con delle modifiche da fare, e contano quanto la lezione.

Se una lezione va storta e non riesci a capire perché, lo script finito di ogni
lezione si trova nella cartella `learn` che viene con questo libro, con il nome
della sua lezione: `01-hello.singe` e così via. Leggilo solo dopo averci
provato.

[#_how_your_folders_are_laid_out]
=== Come sono organizzate le tue cartelle

La prima lezione prepara tutto questo e ogni lezione successiva lo dà per
scontato, quindi vale la pena vederlo una volta adesso.

Tieni una *cartella di lavoro* con dentro la tua copia di Singe. Ogni lezione
crea una nuova cartella al suo interno, con il nome dello script che contiene.

[literal]
----
singe/                 <- la tua cartella di lavoro, con dentro Singe
    Singe/             <- qui il motore mette i propri file
    data/              <- e tutto ciò che i tuoi giochi salvano
    hello/
        hello.singe
    rocks/
        rocks.singe
        art/
----

Esegui una lezione dalla cartella di lavoro indicando la sua cartella, quindi
`Singe rocks` esegue `rocks/rocks.singe`. Questa forma breve funziona perché la
cartella e lo script hanno lo stesso nome. È la stessa struttura che ha un vero
gioco installato, ed è per questo che il libro la usa fin dalla prima lezione
invece di mettere in ordine più avanti.

[#_what_comes_with_this_book]
=== Che cosa viene con questo libro

Dalla seconda parte in poi le lezioni usano immagini e suoni. Si trovano nella
cartella `art` che viene con il libro, e tu copi quella cartella in qualunque
cartella di lezione su cui stai lavorando, mantenendone il nome. Ci sono
un'astronave, una roccia, un colpo, una stella, quattro fotogrammi di qualcuno
che cammina e due rumori. `art/README.txt` li elenca con le loro dimensioni.

Il resto lo fornisce Singe stesso. La prima volta che esegui qualcosa, il motore
estrae una cartella chiamata `Singe` nella tua cartella di lavoro, e dentro ci
sono un video, un font, due modelli 3D e un clic. Le lezioni che ne hanno
bisogno usano quelli già presenti sul tuo disco, quindi non c'è niente da
cercare e niente da comprare. Niente di tutto ciò è bello. È tutto vero, e per
metterci al suo posto qualcosa di meglio di solito basta cambiare il nome di un
file.

[#_this_is_not_the_forge_book]
=== Questo non è il libro di Forge

Forge, uno strumento separato con un libro tutto suo, crea un gioco
descrivendolo invece di programmarlo. È una strada diversa verso un posto
diverso, per chi non vuole proprio scrivere codice. Se sei qui per imparare a
programmare, sei nel posto giusto. Non ti servono né Forge né il suo libro, e
questo non si basa su di esso.

Il _Riferimento di Singe_ è il riferimento: ogni funzione, ogni argomento, ogni
valore restituito e il modello di programmazione che c'è dietro. Non è un
tutorial e non cerca di esserlo. Comincerai a prenderlo in mano intorno alla
sesta lezione, e alla fine di questo libro lo userai più di questo libro. Si
trova nello stesso download di questo.

[#_the_series]
== La serie

Trentuno lezioni in quattro parti. Ognuna ha bisogno di quella precedente e di
nient'altro.

*Prima parte: le idee.* Niente grafica, niente video, niente da installare.
Disegni con le forme e il testo che il motore ha già, e impari di che cosa è
fatto un programma.

. *Ciao* -- uno script, una funzione, una stringa e qualcosa sullo schermo.
. *Numeri che cambiano* -- variabili, aritmetica e far muovere le cose.
. *Prendere decisioni* -- `if`, i confronti e la lettura dei comandi.
. *Ancora una volta* -- `for` e `while`, e disegnare cento copie di qualcosa.
. *Funzioni tutte tue* -- argomenti, valori restituiti e perché prendersi il
  disturbo.
. *Elenchi di cose* -- tabelle, `ipairs`, aggiungere e togliere.
. *Un gioco* -- tutto quello visto finora, giocabile, in circa centoventi righe.
. *Quando qualcosa va storto* -- leggere gli errori, `debugPrint` e ricaricare
  con F5.

*Seconda parte: un vero gioco.* Grafica, suono e la forma che prende un gioco
finito.

[start=9]
. *Immagini* -- sprite, caricamento, disegno e fotogrammi.
. *Suono* -- effetti, musica e quando caricare che cosa.
. *Colpire le cose* -- collisioni, il kit di gioco e le hitbox.
. *Punteggio, vite e game over* -- stato, salvataggio e ricominciare da capo.
. *La cartella del gioco* -- `games.dat`, la grafica per il menu e l'avvio da
  lì.

*Terza parte: video.* Riprodurre filmati come mondo del gioco, e le convenzioni
da sala giochi che sono nate attorno a questo. Salta questa parte se il tuo
gioco non vuole video; niente di ciò che viene dopo dipende da questa parte.

[start=14]
. *Riprodurre video* -- il disco, i fotogrammi, la ricerca e l'attesa.
. *L'altro modo di scriverlo* -- il modello a thread («threaded»), e perché si
  adatta al video.
. *Diramazioni* -- scelte, percorsi e la forma di un gioco video a diramazioni.
. *Pistole ottiche* -- mirare, sparare e la calibrazione di cui ha bisogno un
  cabinato.
. *Quick-time event* -- richieste a schermo, finestre di tempo e il punteggio
  sul tempismo del giocatore.

*Quarta parte: tutto il resto.* Ogni lezione sta in piedi da sola; affrontale
nell'ordine che preferisci.

[start=19]
. *Testo che fa bella figura* -- font, qualità e misure.
. *Menu e schermate* -- la GUI, i documenti e gli stili.
. *Sottotitoli* -- e perché sono un sistema a parte.
. *Nel 3D* -- scene, telecamere e coordinate.
. *Modelli e luce* -- glTF, materiali e animazione.
. *Fisica* -- corpi, forze, giunti e quando non usarli.
. *Particelle* -- emettitori, e come fare un'esplosione.
. *Personaggi che si muovono da soli* -- navigazione e ricerca del percorso.
. *Musica e MIDI* -- tracce, soundfont e strumenti.
. *Online* -- account, classifiche dei punteggi record e il catalogo.
. *Conservare i dati* -- database, tabelle e le domande che poni loro.
. *Distribuirlo* -- impacchettare, applicare patch, licenze e l'uscita.
. *In un cabinato* -- comandi, menu di servizio, bezel (cornici decorative) e
  le cose che contano solo sull'hardware vero.

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