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.

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.

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.

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.

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.

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.

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.

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.

  1. Ciao — uno script, una funzione, una stringa e qualcosa sullo schermo.

  2. Numeri che cambiano — variabili, aritmetica e far muovere le cose.

  3. Prendere decisioni — if, i confronti e la lettura dei comandi.

  4. Ancora una volta — for e while, e disegnare cento copie di qualcosa.

  5. Funzioni tutte tue — argomenti, valori restituiti e perché prendersi il disturbo.

  6. Elenchi di cose — tabelle, ipairs, aggiungere e togliere.

  7. Un gioco — tutto quello visto finora, giocabile, in circa centoventi righe.

  8. 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.

  1. Immagini — sprite, caricamento, disegno e fotogrammi.

  2. Suono — effetti, musica e quando caricare che cosa.

  3. Colpire le cose — collisioni, il kit di gioco e le hitbox.

  4. Punteggio, vite e game over — stato, salvataggio e ricominciare da capo.

  5. 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.

  1. Riprodurre video — il disco, i fotogrammi, la ricerca e l’attesa.

  2. L’altro modo di scriverlo — il modello a thread («threaded»), e perché si adatta al video.

  3. Diramazioni — scelte, percorsi e la forma di un gioco video a diramazioni.

  4. Pistole ottiche — mirare, sparare e la calibrazione di cui ha bisogno un cabinato.

  5. 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.

  1. Testo che fa bella figura — font, qualità e misure.

  2. Menu e schermate — la GUI, i documenti e gli stili.

  3. Sottotitoli — e perché sono un sistema a parte.

  4. Nel 3D — scene, telecamere e coordinate.

  5. Modelli e luce — glTF, materiali e animazione.

  6. Fisica — corpi, forze, giunti e quando non usarli.

  7. Particelle — emettitori, e come fare un’esplosione.

  8. Personaggi che si muovono da soli — navigazione e ricerca del percorso.

  9. Musica e MIDI — tracce, soundfont e strumenti.

  10. Online — account, classifiche dei punteggi record e il catalogo.

  11. Conservare i dati — database, tabelle e le domande che poni loro.

  12. Distribuirlo — impacchettare, applicare patch, licenze e l’uscita.

  13. In un cabinato — comandi, menu di servizio, bezel (cornici decorative) e le cose che contano solo sull’hardware vero.

Lezione 1: Ciao

La lezione finita

Ecco che cosa avrai alla fine di questa lezione. Non è granché da vedere. È anche un programma scritto da te, che gira su un vero motore di gioco, e tutto il resto di questo libro è costruito sulle cinque righe che l’hanno creato.

Prepara la cartella di lavoro

Crea una cartella in cui tenere tutto, chiamata singe o come preferisci, e mettici dentro la tua copia di Singe. Questa è la tua cartella di lavoro, e ogni lezione di questo libro ci mette dentro una nuova cartella. La crei una volta e non ci pensi più.

Dentro la cartella di lavoro crea una cartella chiamata hello, e dentro quella un file chiamato hello.singe.

singe/                 <- la tua cartella di lavoro, con dentro Singe
    hello/
        hello.singe

Questo annidamento non è pignoleria. Singe considera la cartella da cui lo esegui come il posto in cui vivono i giochi, una cartella per gioco, e ci tiene anche i propri file. Il tuo gioco va nella sua cartella, un livello più giù. Dalla seconda lezione in poi ogni lezione è un’altra cartella accanto a hello.

Due cose sui nomi. La parte dopo il punto, .singe, è il modo in cui Singe sa che questo è uno script. E sulla maggior parte dei computer che non usano Windows le maiuscole contano: Hello.singe e hello.singe sono due file diversi. Prendi fin da ora l’abitudine di scrivere i nomi esattamente.

Conta anche dare alla cartella e allo script lo stesso nome, e tra un momento vedrai perché.

Apri hello.singe nel tuo editor di testo. È vuoto. È giusto così.

Scrivi questo

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

Salvalo.

Non preoccuparti ancora di che cosa voglia dire. Prima di eseguirlo vale la pena notare due cose, perché varranno per ogni programma che scriverai.

La prima è che gli spazi all’inizio delle tre righe centrali sono lì apposta. Al programma non fanno proprio niente — Singe lo eseguirebbe esattamente allo stesso modo anche senza — ma ti mostrano a colpo d’occhio che quelle tre righe stanno dentro la cosa che comincia con function e finisce con end. Lo fanno tutti i programmatori. Fallo dal primo giorno e non dovrai mai impararlo dopo.

La seconda è l’ordine delle righe. Avvengono dall’alto in basso, una dopo l’altra, come i passi di una ricetta. È la cosa più importante in assoluto di un programma, e quasi tutto ciò che confonde un principiante nasce dal dimenticarlo.

Avvialo

Apri un terminale, vai nella tua cartella di lavoro — non nella cartella hello che c’è dentro — e indica la cartella che vuoi eseguire:

Singe hello

Su Windows è Singe.exe hello. Se la tua copia di Singe sta da un’altra parte, scrivi il percorso per arrivarci, come ../Singe hello.

Ecco perché la cartella e lo script hanno lo stesso nome. Quando gli dai una cartella, Singe ci cerca dentro uno script che si chiama allo stesso modo. Dagli nomi diversi e ottieni Error: Unable to locate the game., che è il motore che ti dice di aver cercato senza trovare niente che riconoscesse. In alternativa puoi sempre essere esplicito e scrivere Singe hello/hello.singe, che fa lo stesso lavoro.

Si apre una finestra nera con la parola Hello! vicino all’angolo in alto a sinistra. Premi Esc o Q per uscire.

Saranno successe due cose che non hai chiesto, ed entrambe sono normali. Nella tua cartella di lavoro, accanto a hello, sono comparse le cartelle Singe e data: la prima è il motore che estrae i file che gli servono, la seconda è dove finirà tutto ciò che i tuoi giochi salvano. Lasciale stare tutte e due. E la finestra è quasi tutta nera, perché non hai disegnato niente a parte sei caratteri.

Cos’è appena successo

Ora le cinque righe, una alla volta.

function onOverlayUpdate()

function comincia un gruppo di istruzioni e gli dà un nome. Tutto ciò che c’è da qui fino al suo end gli appartiene. Questa si chiama onOverlayUpdate, e le parentesi vuote dopo il nome avranno senso nella quinta lezione.

Quel nome non lo scegli tu. Singe cerca una funzione con esattamente quel nome e la chiama circa sessanta volte al secondo, per sempre, così hai l’occasione di disegnare. Se la scrivi onoverlayupdate o onOverlayUpdated, Singe non la trova, la finestra resta nera e niente ti dirà che hai sbagliato. Ecco la prima vera lezione: il computer fa quello che hai scritto, non quello che intendevi.

Una funzione che scrivi tu e che chiama il motore è una callback. Non la chiami tu, e non puoi decidere quando viene eseguita: tu la scrivi, e Singe ti richiama quando c’è qualcosa da fare. Ogni nome di questo libro che comincia con on è una callback, e ce n’è una per quasi tutto ciò che può succedere: un pulsante premuto, un tasto digitato, un suono che finisce, il disco che raggiunge un fotogramma. onOverlayUpdate è quella per disegnare, ed è l’unico posto in cui è permesso disegnare.

    overlayClear()

Anche questa è una funzione, ma non una che devi scrivere tu: la fornisce Singe, insieme a diverse centinaia di altre, e tu la stai chiamando. Chiamare una funzione vuol dire dire il suo nome seguito dalle parentesi. Questa pulisce lo schermo.

Viene per prima perché disegnare non sostituisce quello che c’era prima: ci disegna sopra. Pulisci, poi disegna, ogni volta.

    overlayPrint(2, 2, "Hello!")

Un’altra chiamata, e a questa bisogna dire tre cose, che vanno dentro le parentesi separate da virgole. Le cose che passi così a una funzione si chiamano argomenti.

I primi due sono numeri: quanto più a destra e quanto più in basso. Il terzo è il testo da stampare, ed è tra virgolette doppie perché è così che dici al computer che Hello! è un pezzo di testo e non il nome di qualcosa. Il testo tra virgolette si chiama stringa, e userai le stringhe di continuo.

Prima o poi vorrai delle virgolette doppie dentro una stringa, e il modo ovvio non funziona: la seconda virgoletta chiude la stringa troppo presto, e ottieni lo stesso errore unfinished string che incontrerai alla fine di questa lezione. Ci sono due modi per aggirarlo, e conviene conoscerli entrambi.

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

Il primo mette una barra rovesciata davanti a ogni virgoletta che fa parte del testo. La barra rovesciata dice «il carattere successivo fa parte della stringa, non ne è la fine», e la coppia si chiama sequenza di escape. Il secondo usa le virgolette singole per segnare i due capi della stringa, e così le virgolette doppie restano libere di essere testo normale. Lua accetta tutti e due i tipi di virgolette, purché la stringa finisca con lo stesso tipo con cui è cominciata.

Quelle due righe stampano esattamente la stessa cosa. Usa quella più facile da leggere, che di solito è quella con le virgolette singole quando il testo è pieno di virgolette doppie.

I due numeri non sono pixel. overlayPrint è il testo semplice del motore, e conta in celle di carattere: (0, 0) è proprio l’angolo in alto a sinistra, (1, 0) è una lettera più a destra e (0, 1) è una riga più in basso. Quindi (2, 2) è due lettere verso destra e due righe verso il basso. Altri modi di disegnare il testo contano invece in pixel, e li incontrerai nella diciannovesima lezione.

    return OVERLAY_UPDATED

return restituisce una risposta a chi ha chiamato la funzione. Ogni volta che chiama la tua onOverlayUpdate, Singe le fa una domanda: hai cambiato qualcosa? OVERLAY_UPDATED vuol dire sì, quindi mettilo sullo schermo.

OVERLAY_UPDATED non ha virgolette intorno perché non è testo. È un nome che Singe ha già dato a un valore, così puoi scrivere qualcosa che sai leggere invece di un numero che dovresti ricordare.

end

La fine corrispondente della function. Ogni function ne ha esattamente una, e dimenticarla è in assoluto l’errore più comune che ci sia.

Prova tu

Cambia una cosa alla volta, salva ed eseguilo di nuovo. Quel ciclo — cambia, esegui, guarda — è tutto il lavoro.

  1. Sposta il testo. Cambia overlayPrint(2, 2, "Hello!") in overlayPrint(10, 5, "Hello!"). Poi prova (0, 0). Poi prova (200, 2), e scopri perché è sparito.

  2. Di' qualcos’altro. Metti il tuo nome tra le virgolette.

  3. Di' due cose. Aggiungi una seconda riga overlayPrint sotto la prima, con un numero di riga diverso e un testo diverso. Niente ti impedisce di averne quante ne vuoi.

  4. Togli la pulizia. Cancella la riga overlayClear() ed eseguilo. Non cambia niente, perché sullo schermo ancora non si muove niente. Rimettila comunque. Nella seconda lezione conterà moltissimo, ed è un buon momento per vedere che certi errori aspettano prima di mordere.

Rompilo apposta

I principianti passano più tempo a leggere messaggi di errore che libri di programmazione, quindi togliamoci subito il pensiero del primo.

Cancella la virgoletta di chiusura dopo Hello!, così la riga diventa overlayPrint(2, 2, "Hello!), ed eseguilo. Singe si rifiuta di partire e dice:

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

Leggilo da sinistra. hello/hello.singe è il file: la cartella, poi lo script che contiene. 3 è la riga. Il resto è che cosa è andato storto, in questo caso un pezzo di testo aperto e mai chiuso. Vai alla riga tre, rimetti la virgoletta, e parte.

Quasi ogni errore che vedrai ha questa forma: un file, una riga e una lamentela. La lamentela a volte è scritta per qualcuno che conosce già Lua, ma il file e la riga sono sempre giusti, e nove volte su dieci basta la riga.

Smetti di riavviarlo

Ormai hai avviato Singe a mano cinque o sei volte. Smetti di farlo. Avvialo invece così:

Singe -R hello

-R dice a Singe di tenere d’occhio il tuo script. Salva una modifica nel tuo editor, e un attimo dopo il gioco riparte da solo con la modifica dentro, senza chiudere la finestra. Se salvi un errore, l’errore viene stampato e la finestra resta vuota finché non salvi una correzione.

Usa -R per il resto di questo libro.

Cosa hai imparato

  • Un programma è un file di istruzioni che avvengono in ordine, dall’alto in basso.

  • Una function raggruppa delle istruzioni sotto un nome e si ferma al suo end.

  • onOverlayUpdate è un nome che Singe cerca e chiama molte volte al secondo, ed è lì che va tutto ciò che disegni.

  • Chiamare una funzione vuol dire scriverne il nome e le parentesi. Tutto ciò che sta dentro le parentesi è un argomento.

  • Una funzione che il motore chiama per te, invece di una che chiami tu, è una callback. onOverlayUpdate è una di queste.

  • Il testo tra virgolette doppie è una stringa.

  • Pulisci lo schermo prima di disegnarci sopra.

  • Un errore ti dice il file e la riga. Comincia da lì.

La prossima volta

Il tuo Hello! sta dove l’hai messo e non si muove mai. Per farlo muovere ti serve un posto dove tenere un numero che cambia — una variabile — ed è di questo che parla tutta la seconda lezione.

Lezione 2: Numeri che cambiano

La lezione finita

Nella prima lezione hai messo una parola sullo schermo e lei è rimasta lì. Alla fine di questa lezione la stessa parola scivolerà per la finestra, tornando indietro quando arriva a un bordo, e lo farà grazie a quattro numeri che il programma cambia sessanta volte al secondo.

Lungo la strada incontrerai l’idea che fa inciampare più principianti di qualsiasi altra: dove metti una cosa decide quanto a lungo vive.

Crea una nuova cartella

Crea una cartella chiamata numbers accanto alla cartella hello, e dentro un file chiamato numbers.singe. Scrivici dentro il programma della prima lezione, oppure copia hello.singe e rinominalo — vanno bene tutti e due, e riscriverlo non è tempo perso.

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

Avvialo con Singe -R numbers e lascialo andare. Grazie al -R della fine della prima lezione non dovrai più riavviarlo per il resto di questa lezione: salva il file e la finestra si mette in pari da sola.

Conta i fotogrammi

La prima lezione diceva che Singe chiama onOverlayUpdate circa sessanta volte al secondo. È facile dirlo e difficile crederci, quindi contale.

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

Salvalo. Nell’angolo in alto a sinistra compare frame 1, e resta frame 1 per sempre.

È deludente, ed è anche la cosa più utile di questa lezione, quindi non correggerlo ancora. Guarda quello che hai scritto e pensa all’ordine delle righe, che secondo la prima lezione è la cosa più importante di un programma.

Singe chiama onOverlayUpdate. La prima riga mette frames a zero. La seconda ci aggiunge uno, e fa uno. Lo stampi, fai il return, e la funzione è finita. Poi Singe la chiama di nuovo, e la prima cosa che succede è che frames torna a zero.

Non stai contando i fotogrammi. Stai contando fino a uno, sessanta volte al secondo.

Porta fuori la riga

Togli la riga frames = 0 dalla funzione e mettila sopra, da sola, prima della parola function.

frames = 0


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

Salvalo. Il numero sale, veloce, e non si ferma.

Nient’altro è cambiato. L’unica differenza è dove sta la riga, e l’idea è tutta qui. Le righe dentro una funzione avvengono ogni singola volta che la funzione viene chiamata. Le righe fuori da tutte le funzioni avvengono una volta sola, quando Singe legge il tuo file, prima che il gioco cominci.

frames = 0 doveva avvenire una volta sola. Avveniva sessanta volte al secondo, e cancellava il lavoro della riga sotto.

Ogni cosa in movimento che scriverai avrà questa forma. Prepara il numero fuori, cambialo dentro.

Cos’è appena successo

Lì dentro ci sono tre nuovi pezzi di codice. Eccoli da soli.

frames = 0

Questo inventa un nome, frames, e ci mette dietro il numero zero. Un nome con dietro un valore è una variabile, e si chiama così perché il valore può variare — cambiare mentre il programma gira.

Il = non è il segno di uguale che hai imparato a scuola. Non dice che frames è uguale a zero: dice metti zero in frames, e funziona sempre in quella direzione, da destra verso sinistra. I programmatori la chiamano assegnazione, e vale la pena dire la riga ad alta voce in quel modo mentre la scrivi: «frames riceve zero».

Il nome lo scegli tu. Può essere quasi qualsiasi cosa che cominci con una lettera e non contenga spazi, e dovrebbe dire che cos’è la cosa. frames è un buon nome. f è un nome pessimo, e fra una settimana non ti ringrazierai.

    frames = frames + 1

Questa è la riga che fa fermare la gente a fissarla, perché come affermazione di aritmetica non ha senso: niente è uguale a se stesso più uno.

Non è un’affermazione di aritmetica. Ricorda che = mette il lato destro nel nome a sinistra, e leggila in quell’ordine, prima la destra. Calcola frames + 1 usando quello che c’è in frames in questo momento. Poi rimetti il risultato in frames. Se frames conteneva sei, il lato destro fa sette, e sette va in frames.

Aggiungere uno a una variabile in questo modo è una cosa che scriverai migliaia di volte.

Il + fa quello che ti aspetti, e così gli altri tre: - sottrae, * moltiplica e / divide. Non c’è un tasto x per moltiplicare, ed è per questo che quel lavoro lo fa l’asterisco.

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

overlayPrint vuole del testo, e frames è un numero, non testo. I due puntini uniscono le due cose e consegnano il risultato come un’unica stringa: i cinque caratteri frame, uno spazio, e poi tutte le cifre che servono al numero.

Quei due puntini sono l’operatore di unione, e conviene conoscerne il vero nome perché lo usano i messaggi di errore: unire stringhe si chiama concatenazione.

Nota lo spazio dentro le virgolette, prima di quella di chiusura. Senza, ottieni frame6. Lua unisce esattamente quello che gli dai e non aggiunge niente di suo.

Quando unisci un numero a una stringa in questo modo, Lua lo trasforma in testo per te, ed è per questo che non hai dovuto fare niente di speciale. Non lo fa con tutto. Se provi a unire qualcosa che non è né testo né un numero, Lua si ferma con un errore, e il modo per aggirarlo è tostring, che trasforma in testo qualsiasi cosa:

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

Quella riga fa esattamente la stessa cosa di quella prima. Per i numeri tostring non ti serve. Ti servirà nella terza lezione.

Fallo muovere

Ora hai tutto quello che ti serve per muovere la parola. La parola viene disegnata dove dici tu, hai un modo per conservare un numero da un fotogramma all’altro, e hai un modo per cambiarlo.

Dai alla colonna una variabile tutta sua fuori dalla funzione, e aumentala 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

Salvalo. La parola schizza fuori dal lato destro e non torna più.

Si è spostata di una colonna a ogni fotogramma, sessanta volte al secondo, quindi ha attraversato tutta la finestra in circa un secondo. Rallentala aggiungendo meno di una colonna intera:

    wordX = wordX + 0.25

Adesso le servono quattro fotogrammi per spostarsi di una colonna, e la parola striscia. Quasi sempre wordX è un numero come 12.75, che non è affatto una colonna, e Singe se la cava buttando via tutto quello che c’è dopo il punto quando disegna: 12.75 viene disegnato nella colonna dodici. Tenere la parte frazionaria nella variabile è proprio ciò che ti permette di muoverti più lentamente di una colonna a fotogramma. Il numero è più fine dello schermo.

Dov’è il bordo?

La parola se ne va ancora. Per farla tornare indietro devi sapere dov’è il bordo destro, e potresti scoprirlo contando: un gioco senza video ha per impostazione predefinita un mondo di 720 per 480, l’overlay su cui disegni è la metà, 360 per 240, e le lettere del font da console incorporato sono larghe sei pixel, quindi ci sono sessanta colonne.

Non farlo. Chiedilo al motore.

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

overlayGetWidth e overlayGetHeight sono altre due funzioni fornite da Singe, come overlayPrint. Non prendono niente e restituiscono un numero: quanto è larga e quanto è alta la superficie su cui disegni. Nella prima lezione hai visto return restituire un valore, e questo è l’altro capo del filo — una funzione che chiami può darti qualcosa, e qui fai dei calcoli con quello che ti ha dato.

I numeri che ti danno sono in pixel, e overlayPrint conta in celle di carattere, quindi devi dividere. overlayGetFontWidth ti dice quanti pixel è larga una cella, e overlayGetFontHeight quanti è alta, così non devi mai sapere tu la risposta. Le due barre vogliono dire dividi e butta via la parte frazionaria, perché un terzo di cella non è un posto in cui si possa stampare. La normale barra singola ti darebbe una frazione, e nemmeno una frazione di cella è un posto.

string.len conta i caratteri di una stringa, ed è lì perché la parola torni indietro quando è la sua ultima lettera a raggiungere il bordo, non la prima. Prova senza e vedrai sei caratteri scivolare nel nulla.

Le maiuscole di CELL_WIDTH, che contiene quello che ti dà overlayGetFontWidth, sono un’abitudine, non una regola. A Lua non importa, ma un nome in maiuscolo è il modo in cui i programmatori dicono «questo è un numero che imposto una volta in cima e non tocco mai più», ed è meglio di un 6 buttato lì a metà file che fra un mese nessuno sa spiegare.

Fallo tornare indietro

Muoversi nell’altro senso non costa nessuna fatica: invece di aggiungere 0.25 a ogni fotogramma, aggiungi -0.25. Quindi tieni la quantità in una variabile tutta sua e cambiale segno quando la parola arriva a un bordo.

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

Questa è una decisione, e le decisioni sono tutta la terza lezione, quindi per una lezione fidati. Leggila ad alta voce: se wordX ha superato lastColumn, allora fai le due righe rientrate; altrimenti saltale. A chiuderla è end, nello stesso modo in cui end chiude una funzione.

La prima riga inchioda la parola esattamente sul bordo, così una parola veloce non può oltrepassarlo. La seconda è il cambio di segno. -speedX è meno quello che contiene speedX, quindi se conteneva 0.25 ora contiene -0.25, e aggiungere -0.25 a ogni fotogramma riporta la parola indietro da dove è venuta. Quando raggiunge il bordo sinistro, il blocco if corrispondente cambia di nuovo il segno, e torna a 0.25.

Altri due blocchi così per il bordo in alto e quello in basso, e la parola rimbalza per tutta la finestra.

Tutto insieme

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 tiene la parola fuori dalle prime due righe in alto, così non scarabocchia mai sopra il contatore dei fotogrammi. lastRow contiene un - 1 invece di uno string.len, perché una parola è larga molti caratteri ma è sempre alta una riga sola.

Nota che tutta la metà superiore del file viene eseguita una volta e tutta la metà inferiore sessanta volte al secondo, e che capisci quale è quale guardando il rientro. Ecco a che cosa servivano gli spazi.

Prova tu

  1. Cambia le velocità. Prova speedX = 1 e speedY = 1. Poi prova 0.05 per entrambe. Poi rendine una molto più grande dell’altra.

  2. Cambia la parola. Metti tra le virgolette una parola molto più lunga — abbastanza da riempire un terzo della finestra — e guarda il rimbalzo a destra avvenire ancora nel posto giusto. È string.len che fa il suo lavoro.

  3. Togli la pulizia. Cancella la riga overlayClear(). La prima lezione aveva promesso che un giorno sarebbe contato, e quel giorno è oggi: la parola spalma una scia per tutta la finestra e non ne cancella mai niente, perché disegnare ha sempre disegnato sopra quello che c’era. Rimettila.

  4. Impediscile di andare di lato. Metti speedX = 0 ed eseguilo. Scopri perché ora la parola non lascia mai la colonna zero, e perché il blocco if del bordo sinistro non scatta mai.

  5. Rompi apposta il contatore dei fotogrammi. Riporta la riga frames = 0 dentro la funzione, sopra frames = frames + 1. Guarda il contatore bloccarsi a uno mentre la parola continua a muoversi perfettamente. Poi scopri perché la parola non ne risente.

Rompilo apposta

Sostituisci i due puntini nella riga del contatore dei fotogrammi con un segno più, così che diventi:

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

Salvalo. La finestra si chiude, Singe si ferma e il terminale dice:

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

seguito da diverse righe che cominciano con stack traceback:, che per ora puoi ignorare.

Leggilo come ti ha insegnato la prima lezione: il file, la riga, poi la lamentela. La riga 42 è quella che hai cambiato. La lamentela dice che a Lua è stato chiesto di sommare una stringa a un numero, e sommare è roba da numeri. + e .. sulla pagina si somigliano e fanno lavori completamente diversi: il più è aritmetica, .. è colla.

Vale la pena incontrare questo errore per il punto in cui è comparso. L’errore della prima lezione ha fermato Singe prima ancora che il tuo gioco partisse, perché Lua non riusciva proprio a leggere il file. Questo invece è una riga perfettamente leggibile che va storta solo quando viene eseguita, quindi la finestra si è aperta, il gioco è partito ed è morto al primo fotogramma. Tutti e due i tipi ti dicono il file e la riga. In ogni caso, comincia da lì.

Cosa hai imparato

  • Una variabile è un nome con dietro un valore, e il valore può cambiare.

  • = vuol dire «metti il lato destro nel nome a sinistra», non «è uguale a».

  • frames = frames + 1 calcola prima il lato destro, poi lo memorizza.

  • +, -, * e / fanno i calcoli che ti aspetti; // divide e butta via la parte frazionaria.

  • .. unisce il testo, e strada facendo trasforma un numero in testo.

  • Una riga dentro onOverlayUpdate viene eseguita a ogni fotogramma. Una riga fuori da tutte le funzioni viene eseguita una volta sola, prima che il gioco cominci.

  • Tutto ciò che deve ricordare qualcosa da un fotogramma all’altro deve vivere fuori.

  • overlayGetWidth e overlayGetHeight ti dicono le dimensioni della superficie su cui disegni, così non devi mai tirare a indovinare.

  • overlayClear conta dal momento in cui qualcosa si muove.

La prossima volta

La parola si muove, ma si muove da sola e niente di quello che fai cambia qualcosa. Nella terza lezione prendi i quattro blocchi if che hai usato sulla fiducia, impari che cosa dicono davvero e li rivolgi ai tasti freccia invece che ai bordi dello schermo. Il riquadro che alla fine guiderai per la finestra è il giocatore del gioco che costruirai nella settima lezione.

Lezione 3: Prendere decisioni

La lezione finita

Tutto quello che hai scritto finora fa la stessa cosa a ogni fotogramma. La parola della seconda lezione si muoveva che tu lo volessi o no, e l’unico motivo per cui tornava indietro erano quattro blocchi di codice che ti era stato detto di prendere sulla fiducia.

Questa lezione è quei quattro blocchi, spiegati per bene. Alla fine il tuo programma farà domande, agirà in base alle risposte e — visto che la domanda più interessante che un gioco possa fare è «che cosa sta facendo il giocatore?» — guiderai un riquadro per la finestra con i tasti freccia. Tieniti quel riquadro. È il giocatore del gioco che costruirai nella settima lezione.

Crea una nuova cartella

Una cartella chiamata decisions, dentro un file chiamato decisions.singe, e Singe -R decisions in esecuzione in un terminale. Come l’ultima volta.

Che cosa dice davvero un if

Ecco il blocco della seconda lezione, da solo.

if wordX > lastColumn then
    wordX = lastColumn
end

Quattro parti. La parola if. Una domanda. La parola then. E un corpo di righe che vengono eseguite solo quando la risposta alla domanda è sì, chiuso da end.

La domanda è wordX > lastColumn, e il vero lavoro lo fa il >. Confronta i due numeri ai suoi lati e produce una risposta che è o vero o falso. Quelle due parole non sono testo e non sono numeri: sono valori a tutti gli effetti, chiamati booleani, e un booleano è l’unica cosa che interessa a un if.

Il rientro è la stessa idea della prima lezione: le righe interne sono rientrate così vedi a colpo d’occhio che cosa appartiene al blocco if, e la riga end è allineata con la riga if che ha aperto il blocco. Lua lo eseguirebbe anche senza spazi. Tu non riusciresti a leggerlo.

Questi confronti sono sei, e li userai tutti.

a < b

a è minore di b

a > b

a è maggiore di b

a ⇐ b

a è minore o uguale a b

a >= b

a è maggiore o uguale a b

a == b

a è uguale a b

a ~= b

a non è uguale a b

Gli ultimi due sono quelli a cui fare attenzione, per motivi diversi.

~= vuol dire «non è uguale a». La maggior parte dei linguaggi lo scrive !=, e se hai già visto un programma, le tue dita scriveranno != e Lua lo rifiuterà. La tilde sulla tua tastiera sta accanto al tasto 1 o sotto il #, a seconda di dove vivi.

== sono due segni di uguale, e non è un errore di battitura per uno solo. È uno degli errori più comuni nella programmazione, e vale la pena fermarcisi un momento.

Nella seconda lezione hai imparato che un segno di uguale vuol dire metti il lato destro nel nome a sinistra. È una cosa che fai. Cambia qualcosa.

Due segni di uguale vogliono dire queste due cose sono uguali? È una domanda che fai. Non cambia niente, e restituisce vero o falso.

lives = 3
if lives == 3 then

La prima riga mette lives a tre. La seconda chiede se vale tre. Lavori diversi, simboli diversi, a un carattere di distanza. Se li scambi Lua ti coglie in fallo, e alla fine di questa lezione incontrerai l’errore che usa.

Quando la risposta è no

Da solo, un if non fa proprio niente quando la risposta è falsa. Molto spesso vuoi che succeda invece l’altra cosa, e quello è else.

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

Viene eseguito esattamente uno dei due corpi, mai tutti e due, mai nessuno, quindi alla fine message contiene sempre una delle due stringhe e mai niente.

Quando le possibilità sono più di due, elseif le mette in catena.

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

Lua prova le domande dall’alto e si ferma alla prima che è vera. Un punteggio di 6000 non è maggiore di 10000, quindi prova la successiva, che è vera, quindi rank diventa pilot e le altre due domande non vengono mai fatte. Quest’ultimo punto conta: anche il ramo elseif per 1000 è vero per un punteggio di 6000, e non viene mai raggiunto, ed è per questo che l’ordine va dal più grande al più piccolo.

Tutta la catena ha bisogno di un solo end, per quante parti elseif contenga. È una sola decisione, non quattro.

Vero, falso e niente del tutto

Non devi per forza confrontare due cose per ottenere un booleano. Puoi tenerne uno.

paused = false

È una variabile come tutte le altre, e il valore che contiene è il booleano false in persona, scritto senza virgolette perché non è la parola «false», è l’idea. Lo stesso vale per true. Una variabile che ne contiene uno può andare dritta in un if senza nessun confronto:

if paused then

Leggilo come «se in pausa». Si legge meglio di if paused == true, che fa la stessa cosa facendo il giro lungo, e i programmatori esperti ti guarderanno strano se lo scrivi.

Tre parole uniscono e capovolgono queste risposte.

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

and è vero quando lo sono entrambi i lati. or è vero quando lo è uno dei due lati, o tutti e due. not trasforma vero in falso e falso in vero. Si leggono come l’inglese e, cosa insolita in programmazione, vogliono dire proprio quello che dicono in inglese.

C’è un altro valore da conoscere, ed è quello che produce gli errori più confusi del tuo primo anno.

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

Se in lives non hai mai messo niente, quella riga stampa lives nil. Lua non si lamenta di un nome che non ha mai visto: ti dà nil, che è la sua parola per qui non c’è niente. Non è zero e non è una stringa vuota. Zero è un numero che volevi memorizzare. nil è l’assenza di un valore.

Hai già incontrato nil due volte senza saperlo. frames = frames + 1 senza la riga frames = 0 sopra fallisce perché hai chiesto a Lua di aggiungere uno a niente. E anche una callback scritta male è nil, ed è per questo che una onOverlayUpdate scritta male ti dà una finestra nera e nessun errore: Singe cerca il nome, non ci trova niente e se ne va tranquillo per la sua strada.

tostring è in quella riga perché .. non unisce a niente un booleano o un nil. I numeri li converte per te; questi no. Era la promessa della fine della seconda lezione, e ora sai a che cosa serve.

Infine, la regola che tiene insieme tutta la sezione, perché if accetta qualsiasi cosa gli dai, non solo vero e falso:

In Lua tutto è vero tranne false e nil.

Zero è vero. Una stringa vuota è vera. Solo quei due non lo sono, e una volta che lo sai, if movingLeft then si legge benissimo sia che movingLeft contenga true, sia che contenga false, sia che non sia mai stata impostata.

Leggere i comandi

È ora di chiedere qualcosa al giocatore. Per questo serve una nuova callback.

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

onInputPressed è la seconda callback che scrivi, e funziona esattamente come descritto nella prima lezione: tu la scrivi, Singe la chiama. onOverlayUpdate viene chiamata a tempo. Questa viene chiamata quando succede qualcosa — quando il giocatore preme qualsiasi cosa il motore riconosca.

La differenza rispetto a onOverlayUpdate è la parola dentro le parentesi. Singe deve dirti quale comando è stato premuto, quindi passa un valore alla funzione, e what è il nome con cui hai scelto di riceverlo. La prima lezione chiamava argomenti le cose che passi a una funzione; visto da dentro, il nome che ne riceve uno è un parametro. Il nome è tuo: chiamalo what, chiamalo button, chiamalo k. Singe lo riempie in ogni caso.

SWITCH_RIGHT è un nome che il motore ha già dato a un valore, come OVERLAY_UPDATED nella prima lezione. Per usarlo non devi caricare niente: Singe li definisce tutti prima che il tuo script parta. Ce n’è uno per ogni cosa che ha un cabinato: SWITCH_LEFT, SWITCH_RIGHT, SWITCH_UP, SWITCH_DOWN, da SWITCH_BUTTON1 a SWITCH_BUTTON4, SWITCH_START1, SWITCH_COIN1 e altri ancora. La tabella Costanti del motore del riferimento copre tutta la famiglia, che va da SWITCH_UP a SWITCH_RECORD. Di proposito non si chiamano «il tasto freccia destra», perché lo stesso SWITCH_RIGHT arriva sia che il giocatore abbia premuto un tasto freccia, sia che abbia spinto un joystick o la levetta di un controller. Scrivi il gioco una volta e funziona con tutti e tre.

Aggiungi quella callback, dai a boxX un valore iniziale fuori dalle funzioni e disegna qualcosa in boxX. Premi la freccia destra. Il riquadro salta di dieci pixel ogni volta che la premi.

È successo, e sta succedendo

Tieni premuto il tasto freccia. Non succede nient’altro.

onInputPressed viene chiamata una volta, mentre il tasto scende, e non di nuovo finché non lo lasci e lo premi ancora. Non c’è ripetizione automatica. Per certe cose è esattamente giusto — sparare un colpo, inserire un gettone, scegliere una voce di menu — e per camminare è esattamente sbagliato, perché camminare deve continuare a succedere finché il tasto resta premuto.

Sono davvero due domande diverse. È successo è un evento, e lo vieni a sapere una volta. Sta succedendo è uno stato, e dura. Singe ti informa degli eventi, e il modo per trasformare gli eventi in uno stato è ricordarli da te.

Due callback, con una variabile in mezzo.

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 è la terza callback, ed è lo specchio della seconda: Singe la chiama quando il tasto risale, con lo stesso valore SWITCH_. Insieme fanno in modo che movingRight dica sempre la verità su quello che sta facendo in questo momento il dito del giocatore.

Non si è ancora mosso niente, ed è proprio questo il punto. Premere e muoversi ora sono due lavori separati. Il movimento va dove va tutto il lavoro da fare a ogni fotogramma.

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

Ora il riquadro scivola fluido finché il tasto resta premuto, a una velocità che decidi tu, e i calcoli sono tornati dove devono stare, nell’unica funzione che gira sessanta volte al secondo. Questa forma — gli eventi impostano dei flag, il fotogramma agisce sui flag — è il modo in cui quasi ogni gioco gestisce i comandi, e la userai di nuovo in ogni lezione in cui c’è un giocatore.

Disegnare un riquadro

overlayBox prende due angoli: il lato sinistro e quello in alto del rettangolo, poi il destro e quello in basso.

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

Disegna un contorno, quattro linee spesse un pixel, e non un rettangolo pieno. Tra le chiamate per disegnare sull’overlay un rettangolo pieno proprio non c’è. Quando più avanti vorrai un blocco pieno ci sono modi per ottenerlo, e la nona lezione ti mostra quello solito.

I suoi numeri sono pixel, non celle di carattere. Questo trae in inganno, perché overlayPrint nella seconda lezione contava in celle da sei pixel per tredici e tutto il resto di Singe conta in pixel. overlayPrint è l’eccezione; le altre chiamate per disegnare — overlayBox, overlayLine, overlayCircle, overlayEllipse e overlayPlot — lavorano tutte negli stessi pixel che riporta overlayGetWidth.

colorForeground imposta il colore, con tre numeri da 0 a 255: quanto rosso, quanto verde, quanto blu. Tutti e tre a 255 è bianco, tutti a 0 è nero, e (255, 220, 0) è un giallo caldo. Nota che non è un argomento di overlayBox. È un’impostazione: la cambi, e tutto quello che disegni dopo esce nel nuovo colore finché non la cambi di nuovo. overlayPrint è ancora una volta l’eccezione — il font da console arriva con i suoi colori già incorporati e ti ignora.

Tutto insieme

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

Lì dentro ci sono quattro cose che meritano una seconda occhiata.

movingLeft and not movingRight c’è perché un giocatore può tenere premute tutte e due le frecce insieme. Senza il not, le due litigherebbero e il riquadro tremolerebbe o andrebbe alla deriva; se invece c’è, tenerle premute tutte e due vuol dire che non vince nessuna e il riquadro sta fermo, che è quello che un giocatore si aspetta.

maxX viene calcolato una volta sola in cima, usando overlayGetWidth come nella seconda lezione, e il - 1 c’è perché l’ultimo pixel della superficie è uno in meno della sua larghezza. Togli il - 1 e il lato destro del riquadro cade fuori dalla superficie e sparisce, perché Singe butta via senza lamentarsi tutto quello che disegni fuori dall’overlay.

I blocchi di contenimento usano elseif invece di due blocchi if separati. Il riquadro non può essere oltre il bordo sinistro e oltre il bordo destro nello stesso momento, quindi fare la seconda domanda quando la prima era vera è lavoro sprecato.

E la decisione sul colore è un if che ha il solo compito di scegliere un valore. Giallo mentre il giocatore fa qualcosa, blu quando non fa niente: un modo gratuito per vedere che la tua gestione dei comandi funziona davvero.

Prova tu

  1. Cambia la velocità. BOX_SPEED = 1 e BOX_SPEED = 8. A otto, guarda che cosa fa il contenimento quando spingi il riquadro in un angolo.

  2. Mostra i tuoi flag. Aggiungi una riga a onOverlayUpdate: overlayPrint(0, 1, "left " .. tostring(movingLeft)). Premi e rilascia la freccia sinistra e guardalo cambiare. Poi togli il tostring e leggi l’errore che ti dà Lua.

  3. Fallo andare più veloce quando un pulsante è premuto. Aggiungi un flag running comandato da SWITCH_BUTTON1 nelle due callback dei comandi, e usa un if in onOverlayUpdate per muoverti del doppio di BOX_SPEED finché è vero.

  4. Segna il centro. Disegna un secondo riquadro, piccolo, al centro della finestra, che cambi colore quando il riquadro del giocatore ci si sovrappone. Ti servirà and per unire quattro confronti, ed è più difficile di quanto sembri. Sbagliarlo un po' è normale; l’undicesima lezione lo fa per bene.

  5. Togli i rilasci. Cancella tutta la funzione onInputReleased ed eseguilo. Il riquadro fa un passo e poi non si ferma più. Scopri quale riga ora non viene mai raggiunta.

Rompilo apposta

Trova il blocco di contenimento e cambia il < del suo primo confronto in un segno di uguale singolo, così che diventi:

    if boxX = 0 then

Salvalo. La finestra resta lì vuota e il terminale dice:

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

È l’errore da cui metteva in guardia tutta la parte su ==, e il messaggio è un buon esempio di errore del tutto esatto e del tutto inutile se lo prendi alla lettera. Lua non ti sta chiedendo di aggiungere la parola then. Lua è arrivato fino a if boxX, subito dopo si aspettava un confronto o un then, e ha trovato =, che non può essere né l’uno né l’altro.

Ogni volta che vedi 'then' expected dopo un if, cerca un = singolo che dovrebbe essere doppio. È quasi sempre quello.

Nota dove è comparso questo: il gioco non è mai partito, come per la stringa non chiusa della prima lezione, perché Lua non riusciva a leggere il file. L’errore del contatore dei fotogrammi nella seconda lezione è successo durante l’esecuzione. Gli errori nella forma del tuo codice ti fermano prima che il gioco cominci. Gli errori in quello che il tuo codice fa aspettano che venga eseguito.

Cosa hai imparato

  • if question then …​ end esegue un corpo solo quando la risposta è vera.

  • else dà l’altro caso, e elseif ne mette in catena altri; vince la prima domanda vera e le altre non vengono mai fatte.

  • I confronti sono <, >, ⇐, >=, == e ~=.

  • = mette un valore in un nome. == chiede se due cose sono uguali.

  • true e false sono valori, e puoi tenerli in delle variabili.

  • and, or e not uniscono e capovolgono quelle risposte.

  • nil è quello che ottieni da un nome che non hai mai impostato, e non è zero.

  • Tutto è vero tranne false e nil.

  • onInputPressed e onInputReleased sono callback che Singe chiama con un valore SWITCH_ quando il giocatore preme o lascia andare un comando.

  • Una pressione è un evento e succede una volta; tieni lo stato in una variabile e agisci in base a quello a ogni fotogramma.

  • overlayBox disegna un contorno in pixel, e colorForeground è un’impostazione, non un argomento.

La prossima volta

Un riquadro è facile. Cento stelle no, almeno non nel modo in cui hai scritto le cose finora, perché scrivere cento righe overlayPlot non è l’idea di bella serata di nessuno. La quarta lezione è il ciclo: dire al computer di fare la stessa cosa molte volte, con qualcosa di diverso a ogni giro, ed è questo che rende possibile uno schermo pieno di qualsiasi cosa.

Lezione 4: Ancora una volta

La lezione finita

Hai disegnato una parola e un riquadro. A un gioco le cose servono a centinaia: stelle, mattoni, proiettili, le righe di un menu. Scrivere cento righe non è la risposta, e se lo fosse, dovresti scriverne altre cento nel momento in cui ne volessi centouno.

Questa lezione è la risposta. Alla fine un campo di stelle scenderà lentamente lungo la tua finestra, e ognuna sarà disegnata dalle stesse cinque righe di codice.

Crea una nuova cartella

Una cartella chiamata repeating, dentro un file chiamato repeating.singe, e Singe -R repeating in esecuzione in un terminale.

Quaranta punti

Scrivi questo ed eseguilo.

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

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

    return OVERLAY_UPDATED
end

Una fila di quaranta punti bianchi attraverso il centro della finestra.

overlayPlot è la chiamata per disegnare più semplice che ci sia: colora un pixel con il colore di primo piano attuale, ed è esattamente quello che serve a una stella. Tutto ciò che c’è di interessante qui sono le tre righe intorno.

    for star = 1, 40 do

Questo dice: fai quello che segue quaranta volte, e a ogni giro star contiene un numero diverso — uno la prima volta, due la seconda, quaranta l’ultima. Entrambi gli estremi sono compresi, quindi 1, 40 sono davvero quaranta giri e non trentanove. Questa forma è un ciclo, e questo in particolare è un ciclo for numerico.

star è un nome che inventi tu, come hai inventato frames nella seconda lezione, e il ciclo lo riempie per te. Non sei tu a impostarlo, e non dovresti cambiarlo dentro il ciclo. Esiste solo tra il for e il suo end; se lo chiedi dopo, ottieni nil.

Il do è obbligatorio ed è facile dimenticarlo. Se lo togli Lua dice 'do' expected near, seguito da quello che ha trovato al suo posto, che sarà la prima cosa della riga successiva.

        overlayPlot(star * 8, 100)

Il corpo. È questo che viene eseguito quaranta volte, ed è sempre la stessa riga — quello che cambia è star, quindi il primo punto cade a x 8, il secondo a 16 e l’ultimo a 320. Un ciclo serve solo se il corpo fa qualcosa con il numero del ciclo, e la prima cosa a cui ricorrerai ogni volta è farci dei calcoli.

Il corpo è rientrato di un passo in più rispetto al for, per lo stesso motivo per cui finora è stato rientrato tutto il resto.

    end

Chiude il ciclo. Ora hai incontrato tre cose che hanno bisogno di un end: function, if e for. Funzionano tutte allo stesso modo, si annidano una dentro l’altra, e il rientro è il modo in cui tieni traccia di quale end appartiene a che cosa.

Contare a passi più grandi di uno

Il ciclo conta in avanti di uno alla volta, a meno che tu non gli dica altrimenti. Aggiungi un terzo numero e conterà invece a passi di quel numero.

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

Leggilo come da, fino a, a passi di. Questo va 0, 10, 20 e così via, fermandosi sull’ultimo pixel della superficie o prima, e disegna una linea punteggiata da un lato all’altro, qualunque sia la dimensione della finestra. È la stessa fila di punti di prima, descritta in termini di dove vanno invece che di quanti sono.

Il passo può essere negativo, e allora conta all’indietro.

    for countdown = 10, 1, -1 do

Dieci, nove, otto, giù fino a uno. Con un passo negativo il secondo numero è il pavimento invece del soffitto, come ti aspetteresti, e sbagliare il segno dà un ciclo che non viene mai eseguito: for i = 10, 1 do senza passo conta in avanti da dieci verso uno, è già oltre la fine prima di cominciare e non fa niente. Nessun errore, nessun risultato. Se un tuo ciclo sembra non partire mai, controlla prima la direzione.

Il passo può anche essere una frazione, anche se ti servirà meno spesso di quanto pensi.

Un ciclo dentro un altro

Il corpo di un ciclo è codice normale, e il codice normale può contenere un ciclo.

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

Questo disegna una griglia di punti su tutta la finestra. Mettilo nella tua onOverlayUpdate al posto della fila e guardalo, perché conviene chiarirti in testa adesso come viene eseguito, invece che nell’undicesima lezione, quando qualcosa dipenderà da questo.

Il ciclo esterno viene eseguito una volta con row a 0. Lì dentro, tutto il ciclo interno viene eseguito dall’inizio alla fine — diciotto colonne, diciotto punti, una riga della griglia. Solo quando il ciclo interno ha finito il ciclo esterno passa a row a 20 ed esegue di nuovo tutto il ciclo interno.

Il corpo del ciclo interno viene quindi eseguito diciotto per dodici volte, cioè duecentosedici volte, per dodici giri del ciclo esterno. Quella moltiplicazione è il motivo per cui i cicli annidati sono il modo di riempire un rettangolo con qualsiasi cosa, e anche il motivo per cui dovresti dare un’occhiata ai numeri prima di annidarne tre.

Nota che la posizione di ogni punto ha bisogno di entrambe le variabili dei cicli: column per l’orizzontale e row per il verticale. Lo schema è questo. Se il corpo interno usa solo la variabile interna, il ciclo interno disegna la stessa cosa più e più volte nello stesso posto, e hai scritto un modo lento per farla una volta sola.

Quando non sai quante volte

Un ciclo for ha bisogno di sapere quante volte prima di cominciare. A volte non lo sai, e allora ti serve l’altro tipo.

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

Un ciclo while controlla una domanda prima di ogni giro, esattamente la domanda che farebbe un if, e continua finché la risposta è vera. Quando la risposta è falsa si ferma e prosegue con la riga che segue end. Se la risposta è falsa già la prima volta, il corpo non viene mai eseguito.

Quell’esempio disegna la stessa linea punteggiata del for con passo dieci, e ci mette tre righe per fare quello che for faceva in una, quindi per quello usa for. Ecco la differenza che decide:

  • Usa for quando il numero di giri è noto prima di cominciare. Quaranta stelle. Un pixel ogni dieci da un lato all’altro. Ogni riga di una griglia.

  • Usa while quando aspetti che qualcosa diventi vero e non puoi dire in anticipo quanto ci vorrà. Distribuisci carte finché il mazzo non finisce. Continua a chiedere finché il giocatore non scrive qualcosa di valido. Scorri un elenco finché non trovi quello che cercavi.

Un while ha tre parti e devi scriverle tutte e tre tu: preparare la variabile prima del ciclo, controllarla nel while e cambiarla dentro il corpo. Il ciclo for le fa tutte e tre per te, ed è per questo che è quello da scegliere quando va bene. Dimentica la terza parte in un while e la domanda non smette mai di essere vera, cosa che farai apposta alla fine di questa lezione.

Una stella fatta del suo numero

Ora il campo di stelle, e un problema che dà forma al resto della prima parte.

Ogni stella ha bisogno di una x e di una y tutte sue, e non hai modo di tenere cento variabili separate — scrivere star1X, star2X e così via fino a cento è peggio che scrivere le cento righe che stavi evitando. Quindi non memorizzarle. Calcolale una per una a partire dall’unica cosa che rende una stella diversa dalle sue vicine: il suo numero.

        starX = (star * 37) % width

Il % è l’ultimo degli operatori aritmetici ed è il resto: quello che avanza dopo una divisione. Quindici diviso quattro fa tre con il resto di tre, quindi 15 % 4 fa 3. La sua proprietà utile è che il risultato non può mai essere grande quanto il numero a destra, quindi il resto della divisione per width è sempre una posizione da qualche parte sullo schermo, per quanto grande diventi il lato sinistro.

La stella 1 va a 37, la stella 5 a 185, la stella 10 a 10 — 370 ha fatto il giro oltre 360 ed è ricomparso a sinistra. Trentasette è scelto perché non ha fattori in comune con 360, ed è questo che impedisce alle stelle di disporsi in strisce ordinate; prova invece 36 e vedrai subito il problema.

La discesa lenta è lo stesso trucco con un numero che cresce col tempo.

drift = 0


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

drift vive fuori dalla funzione e sale a ogni fotogramma, esattamente come frames nella seconda lezione. Aggiungerlo alla y di ogni stella sposta in basso tutto il campo insieme, e il % riporta in cima una stella che cade fuori dal fondo, per sempre, gratis.

math.floor butta via la parte frazionaria di un numero e restituisce la parte intera sotto: math.floor(7.9) fa 7. La seconda lezione faceva notare che Singe lo fa per te quando disegna, ed è vero, ma farlo tu vuol dire che il numero con cui lavori è il numero che compare sullo schermo. Questo conterà nella settima lezione, quando due cose dovranno essere d’accordo sul fatto di toccarsi o no.

Nota che lì dentro layer è una seconda variabile di ciclo. Le stelle sono disegnate da un ciclo dentro un ciclo, e quello esterno non è una riga di una griglia ma una distanza: tre strati di stelle, ognuno che scende alla sua velocità e con la sua luminosità, ed è questo che fa sembrare profondo un campo piatto di punti.

Il caso

Le stelle scintillano. Scintillare vuol dire una luminosità un po' diversa a ogni fotogramma, e «un po' diversa» è math.random.

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

math.random(60, 90) restituisce un numero intero da 60 a 90, entrambi compresi, scelto di nuovo ogni volta che la chiami. Chiamala senza nessun argomento e ottieni invece una frazione tra 0 e 1, che è la forma da usare quando vuoi che qualcosa succeda una volta su cinque. Non devi preparare il generatore: lo fa Lua quando Singe parte.

Aggiungere layer * 55 solleva gli strati vicini fuori dalla fascia scura, così le stelle lontane restano fioche e quelle vicine sono quasi bianche. Rosso, verde e blu uguali, come spiegava la terza lezione, danno una sfumatura di grigio.

Siccome shade viene scelto di nuovo a ogni fotogramma per ogni stella, ogni stella tremola per conto suo, e a sessanta fotogrammi al secondo sembra uno scintillio e non un difetto.

Tutto insieme

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

Centoventi stelle, disegnate da cinque righe, e il file è più corto di quello della terza lezione.

È anche il limite di questo approccio, e vale la pena essere onesti sul perché mentre lo hai sotto gli occhi. Ogni stella lì dentro è una formula. Di una stella non viene ricordato niente: non puoi renderne una più luminosa della vicina e farla restare così, non puoi abbatterne una dal cielo e non puoi far sì che il giocatore ne raccolga una, perché non c’è nessun posto dove scrivere che le è successo qualcosa. La stella diciassette non è una cosa. È un numero che passa per un attimo in una variabile chiamata star.

Nel momento in cui vuoi cento cose che si ricordino ognuna qualcosa di suo, ti serve un posto dove mettere cento gruppi di informazioni. Quella è la sesta lezione, e il campo di stelle è il motivo per cui esiste.

Prova tu

  1. Di più e di meno. Prova STARS_PER_LAYER = 200, poi 4. Poi LAYERS = 8 e guarda che cosa fa layer * LAYER_BRIGHT a shade quando il numero dello strato diventa grande. I numeri che accetta colorForeground si fermano a 255.

  2. Cambia la spaziatura. Metti ACROSS_STEP a 36 ed eseguilo. Le stelle si mettono in strisce, perché 36 sta in 360 esattamente dieci volte. Rimettilo a 37 e prova 71 e 90.

  3. Ferma lo scintillio. Sostituisci la riga con math.random con un semplice shade = layer * 70 e confronta. Decidi quale preferisci; non c’è una risposta giusta, e accorgerti di avere una preferenza fa parte del lavoro.

  4. Falle cadere verso l’alto. Un carattere.

  5. Disegna anche la griglia. Rimetti il ciclo annidato della griglia di prima, dopo le stelle, in un colore scuro. Due cicli annidati in una sola funzione, che disegnano due cose diverse, e il secondo non disturba il primo.

Rompilo apposta

Finora ogni errore è stato un messaggio. Questo no, ed è proprio per questo che dovresti incontrarlo mentre te lo aspetti.

Metti questo nella tua onOverlayUpdate, subito sotto overlayClear(), eseguilo e leggi il paragrafo successivo prima di fare qualsiasi altra cosa.

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

Manca la riga che fa avanzare x, quindi x resta a zero, quindi x < width non smette mai di essere vero. Il ciclo gira per sempre, disegnando lo stesso pixel, ed è dentro onOverlayUpdate, quindi onOverlayUpdate non ritorna mai. Singe sta aspettando la tua funzione. Non può disegnare, non può leggere la tastiera e non può uscire.

Quello che vedi è una finestra che smette di muoversi. Esc non fa niente. Q non fa niente. E non viene stampato niente.

Vai nel terminale da cui hai avviato Singe e premi Ctrl e C insieme. Singe ferma il tuo ciclo e ti dice dov’era:

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

Può dirlo due volte, a qualche secondo di distanza, prima di uscire. Una volta basta e avanza. La riga 20 è l’end del tuo while, che è dove il ciclo stava girando quando l’hai fermato. Togli il ciclo, salva e avvia di nuovo Singe.

Questo è un resoconto, non un errore. Niente si è lamentato finché non l’hai chiesto, perché, per quanto riguarda il computer, non è andato storto niente. Hai chiesto un ciclo che gira finché x è minore della larghezza, ed è esattamente quello che hai ottenuto. Questo è l’unico tipo di errore con cui i messaggi di errore non possono aiutarti, e la cura è un’abitudine: ogni volta che scrivi un while, scrivi la riga che cambia la variabile prima di scrivere qualsiasi altra cosa nel corpo.

Cosa hai imparato

  • for name = first, last do …​ end esegue il suo corpo una volta per ogni numero dal primo all’ultimo, entrambi compresi.

  • Un terzo numero è il passo, e può essere negativo per contare all’indietro.

  • La variabile del ciclo esiste solo dentro il ciclo, e il corpo dovrebbe usarla.

  • for ha bisogno di un do, e ogni ciclo ha bisogno di un end.

  • Un ciclo dentro un ciclo esegue tutto il ciclo interno per ogni giro di quello esterno, ed è così che riempi un rettangolo.

  • while question do …​ end ripete finché la domanda è vera, e qualcosa nel corpo devi cambiarlo tu.

  • Usa for quando sai quante volte, e while quando aspetti che qualcosa diventi vero.

  • % è il resto, e tiene dentro un intervallo un numero che cresce.

  • math.random(a, b) dà un numero intero da a a b; math.floor butta via la parte frazionaria.

  • Un ciclo che non finisce mai blocca tutto il gioco senza nessun messaggio di errore, e Ctrl e C nel terminale sono il modo per uscirne.

La prossima volta

Guarda di nuovo quella onOverlayUpdate. Disegna stelle, calcola posizioni, sceglie colori, e sta cominciando a diventare una funzione che fa quattro lavori invece di uno. Nella quinta lezione scrivi funzioni tutte tue, passi loro argomenti come li ricevono le funzioni di Singe e ne ottieni delle risposte — e il campo di stelle diventa una riga che dice drawStars().

Lezione 5: Funzioni tutte tue

La lezione finita

La quarta lezione è finita con un avvertimento sul tuo stesso programma: onOverlayUpdate calcola dove vanno centoventi stelle, decide quanto è luminosa ognuna, le disegna e conta la discesa, ed è una sola funzione che fa quattro lavori. Le stanno per chiedere di farne un quinto, perché un campo di stelle senza niente davanti non è un gioco.

In questa lezione la smonti. Scriverai funzioni tutte tue — funzioni di cui Singe non ha mai sentito parlare e che non chiamerà mai — e passerai a loro il lavoro. Alla fine tutto il campo di stelle è una riga che dice drawStars(), in fondo allo schermo è tornata un’astronave, e il programma è più facile da leggere di quando faceva meno.

Crea una nuova cartella

Una cartella chiamata functions, dentro un file chiamato functions.singe, e Singe -R functions in esecuzione in un terminale.

Copiaci dentro il programma finito della quarta lezione. Eccolo, invariato, e vale la pena eseguirlo una volta prima di toccare qualsiasi cosa:

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

Tre strati di stelle che scendono lungo la finestra a tre velocità. Niente nella prima metà di questa lezione cambia quello che vedi. Tutto quello che c’è cambia il modo in cui si legge il programma.

Un lavoro, un nome

Comincia dalle due righe che mettono una stella sullo schermo. Sopra onOverlayUpdate, aggiungi questo:

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

Poi, nel ciclo interno, cancella quelle due righe e al loro posto chiama la funzione:

        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

Salva. L’immagine è la stessa.

Hai già scritto delle funzioni — onOverlayUpdate è una di queste, e lo sono anche onInputPressed e onInputReleased della terza lezione — ma quelle sono callback. Tu le scrivi e Singe le chiama. drawStar è diversa. Singe non ne ha mai sentito parlare. Viene eseguita perché tu hai scritto il suo nome e le parentesi, nello stesso modo in cui chiami overlayPlot, e niente al mondo la eseguirà se non lo fai tu.

Il trucco è tutto qui. D’ora in poi, quando ti trovi a pensare «e adesso disegna una stella», puoi scrivere «disegna una stella» e intenderlo davvero.

Un parametro è un nome, non una cosa

Guarda di nuovo la prima riga di drawStar.

function drawStar(x, y, shade)

I tre nomi tra le parentesi sono parametri. Un parametro è un nome che la funzione usa per qualunque cosa le abbia passato chi la chiama. Quando scrivi drawStar(starX, starY, shade), Lua mette in x quello che c’è in starX, in y quello che c’è in starY, in shade quello che c’è in shade, e poi esegue la funzione.

I nomi non hanno niente a che fare tra loro. Il numero di chi chiama là fuori si chiama starX e qui dentro x, e funzionerebbe esattamente allo stesso modo se lo chiamassi across o banana. Dentro la funzione esistono solo i nomi tra le parentesi, e contengono copie di quello che è entrato.

È qui che le parentesi vuote della prima lezione finalmente hanno senso.

function onOverlayUpdate()

Niente tra le parentesi vuol dire nessun parametro: il motore non ha niente da dire a questa funzione, quindi non c’è niente a cui dare un nome. Confrontala con la callback che hai scritto nella terza lezione.

function onInputPressed(what)

Un parametro, chiamato what. A questa il motore ha qualcosa da dire — quale comando è stato premuto — quindi c’è un nome in cui riceverlo. Usi un parametro dalla terza lezione.

Un parametro è davvero la copia personale della funzione, e vale la pena dimostrartelo una volta. Scrivi questa, chiamala da onOverlayUpdate e poi toglila di nuovo:

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

Chiamala come half(drift). La funzione dimezza il suo number e restituisce la risposta, e drift, là fuori in onOverlayUpdate, continua a contare come se niente fosse. Una funzione non può allungare la mano e cambiare le variabili di chi la chiama attraverso un parametro. Riceve una copia, e quello che fa alla copia sono affari suoi.

Restituire una risposta

half ha fatto una cosa che le funzioni scritte da te finora non facevano: ha dato una risposta. È l’ultima riga.

    return number

return restituisce un valore a chi ha chiamato la funzione, e la chiamata si trasforma in quel valore. Scrivi smaller = half(drift) e Lua esegue half, prende quello che half ha restituito e lo mette in smaller. Hai incontrato return nella prima lezione, dove onOverlayUpdate restituisce OVERLAY_UPDATED per rispondere alla domanda di Singe se fosse cambiato qualcosa. Qui è la stessa parola che fa lo stesso lavoro, solo che adesso la domanda la fai tu.

La riga della luminosità implora di diventare una funzione con una risposta. Aggiungi questa:

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

Tutto il corpo è un return, cosa normale per una funzione piccola. Ora il ciclo interno può passare la risposta direttamente a drawStar, senza un nome in mezzo:

            drawStar(starX, starY, shadeFor(layer))

Una chiamata dentro una chiamata. Lua calcola prima quella interna, riceve un numero da shadeFor e passa quel numero a drawStar come terzo argomento. Hai già scritto qualcosa di simile senza accorgertene: il math.floor(drift * layer * LAYER_SPEED) della quarta lezione è una chiamata la cui risposta viene usata sul momento, in mezzo a un calcolo più grande.

Due risposte insieme

Le due righe della posizione sono più difficili, perché sono due numeri calcolati insieme e dovresti sceglierne uno da restituire. Nella maggior parte dei linguaggi una funzione può restituire un solo valore, e tirarne fuori due è una seccatura. Lua ti lascia restituirne quanti ne vuoi.

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

Raccogli le risposte mettendo due nomi a sinistra, separati da una virgola:

            local x, y = starAt(star, layer)

Il primo valore nel primo nome, il secondo nel secondo. Se chiedi meno nomi di quanti valori restituisce la funzione, i valori in più vengono buttati via: local x = starAt(star, layer) ti dà il numero orizzontale e perde quello verticale, senza lamentarsi. Se chiedi più nomi di quanti sono i valori, quelli in più sono nil.

Ignora la parola local in quei due blocchi ancora per un minuto. Sta arrivando una sezione tutta sua, ed è quella importante.

Il campo di stelle in una riga

Il ciclo interno ora è tre righe brevi, tutte su uno strato di stelle. Questo è un lavoro con un nome.

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

E anche il ciclo esterno è un lavoro con un nome:

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

Funzioni che chiamano funzioni che chiamano funzioni, tre livelli di profondità, e ognuna è tre o quattro righe che riesci a tenere in testa tutte insieme. Ora onOverlayUpdate può dire che cosa è un fotogramma:

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

Ecco la promessa fatta alla fine della quarta lezione, mantenuta.

Rimetti l’astronave

Ora il quinto lavoro, quello che avrebbe fatto un disastro della vecchia onOverlayUpdate. Riporta il riquadro che guidavi nella terza lezione, stavolta come un’astronave ferma vicino al fondo dello schermo che si muove solo a destra e a sinistra.

Le servono alcuni valori suoi, su in cima insieme agli altri, e le due callback dei comandi della terza lezione senza i rami per su e giù:

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

Disegnarla sono due righe, quindi è una funzione:

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

Muoverla è il punto in cui la lezione dà i suoi frutti. Nella terza lezione, tenere il riquadro sullo schermo richiedeva quattro righe di if ed elseif per ogni direzione. Quell’idea — tenere un numero tra un minimo e un massimo — ha un nome, e il nome è clamp:

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

Tre return, e al massimo uno di loro avviene, perché return non si limita a restituire una risposta: ferma la funzione di colpo. Niente di quello che viene dopo viene eseguito. Se il valore è sotto il minimo, restituisci il minimo e fermati. Se è sopra il massimo, restituisci il massimo e fermati. Altrimenti restituisci quello che è entrato.

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 funzione che finisce senza un return restituisce niente, cioè nil. Va bene per drawPlayer e movePlayer, che vengono chiamate per fare qualcosa e non per rispondere a qualcosa. È un bug in una funzione come clamp: togli quell’ultimo return value e ogni posizione in mezzo all’intervallo torna indietro come nil.

Dove vivono i nomi

Ogni nome che hai creato dalla seconda lezione in poi è stato una variabile globale. Una globale appartiene a tutto il programma: drift, playerX e LAYERS possono essere letti e scritti da qualsiasi funzione del file, in qualsiasi momento, e restano lì finché il gioco gira.

Sembra comodo, e con sei nomi lo è. I guai cominciano a sessanta. Ogni globale è un nome che tutto il programma ha accettato di riservare, quindi quando un’altra funzione vuole un posto dove tenere una posizione orizzontale e lo chiama anche lei starX, i due sono la stessa scatola, e ognuno scrive sopra il numero dell’altro. Quando una globale contiene qualcosa di sbagliato, qualsiasi cosa nel file potrebbe avercelo messo, e scoprire che cosa vuol dire leggerlo tutto.

La cura è una locale. Metti la parola local davanti a un nome la prima volta che lo usi, e il nome esiste solo dentro la function, il ciclo o il blocco if in cui è stato scritto.

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

Qui x e y non sono affari di nessun altro. Un’altra funzione può avere la sua x e le due non si incontrano mai. Quando la x di starAt è sbagliata, le tre righe qui sopra sono le uniche tre che possono averlo fatto. Senza la parola local, quelle due righe creerebbero in silenzio altre due globali, che è esattamente ciò che starX e starY sono sempre stati.

Ora la parte che sorprende tutti. Scrivi questa funzione, e metti in onOverlayUpdate una riga che ti mostri che cosa restituisce:

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

Count: 1, e resta Count: 1 finché il gioco gira, anche se quella funzione viene chiamata sessanta volte al secondo e aggiunge uno ogni volta. Una locale viene creata nuova quando la funzione comincia e sparisce quando la funzione finisce, quindi counted nasce come 0, diventa 1 e muore, sessanta volte al secondo, per sempre. Una locale non ricorda. Quando l’hai visto, togli di nuovo le due cose.

Non è un difetto, è proprio lo scopo: una locale non può essere avvelenata dalla chiamata precedente, perché della chiamata precedente non resta niente. Quando invece devi ricordare qualcosa tra una chiamata e l’altra — drift e playerX devono ricordare — il nome deve vivere fuori da tutte le funzioni. Mettilo in cima al file con local davanti:

local drift   = 0
local playerX = width // 2

Un local scritto in cima al file, fuori da tutte le funzioni, vive quanto lo script e può essere visto da ogni funzione che sta sotto. Quell’ultima parola conta: sotto. Una locale esiste dalla sua riga in giù, quindi una funzione scritta sopra la riga che la crea non può vederla. Lo stesso vale per le funzioni stesse una volta che le segni come local, ed è per questo che lo script finito è nell’ordine in cui è: prima i valori, poi le tue funzioni, poi, per ultime, le callback.

Adesso passa tutto il file e metti local davanti a ogni nome che hai creato — le costanti in maiuscolo, width e height, drift, i quattro valori del giocatore e ognuna delle tue funzioni. Tre nomi non lo ricevono: onInputPressed, onInputReleased e onOverlayUpdate devono restare globali, perché Singe le trova per nome e un nome locale è invisibile da fuori del file.

Sii onesto su quello che le locali non risolvono. Se sbagli a scrivere un nome a cui stai assegnando un valore — movinLeft = true invece di movingLeft = true — Lua non si lamenta. Crea una globale nuova di zecca con il tuo errore di battitura come nome, la imposta e lascia stare quella vera. Non si muove niente, non c’è nessun errore, e tu lo fissi per dieci minuti. Da quello le locali non ti salvano. Leggere il nome due volte sì.

Tutto insieme

Ecco il programma finito, con dentro ogni pezzo della lezione.

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

Prima di andare avanti vale la pena indicare due cose.

local function drawStar(x, y, shade) segna come locale la funzione stessa. Le tue funzioni sono nomi come tutti gli altri, e appartengono solo a questo file. Le tre callback restano globali così Singe può trovarle.

E ora onOverlayUpdate è sei righe che dicono che cos’è un fotogramma: conta la discesa, pulisci lo schermo, muovi il giocatore, disegna il cielo, disegna il giocatore, fatto. Fa cinque lavori nominando cinque cose che fanno un lavoro ciascuna, che è la forma di ogni ciclo di gioco che scriverai.

Una funzione è un nome per un’idea

clamp viene chiamata una volta sola. Tirarla fuori non ha risparmiato nessuna battitura — quattro righe sono uscite, una è entrata, e da un’altra parte è comparsa una funzione di nove righe. Valeva comunque la pena farlo.

Una funzione non è solo un modo per non ripeterti. È un modo per dare un nome a un’idea, così il codice che usa l’idea può dire il nome e andare avanti. «Tieni il giocatore tra il bordo sinistro e il bordo destro» è un pensiero che hai avuto una volta. clamp(playerX, 0, width - PLAYER_WIDTH - 1) è quel pensiero, messo per iscritto. Quattro istruzioni if sono lo stesso pensiero smontato in pezzi che devi rimettere insieme in testa ogni volta che li leggi.

Quando stai decidendo se una cosa merita di essere una funzione, non chiederti quante volte la chiamerai. Chiediti se ha un nome.

Prova tu

  1. Rinomina un parametro. In drawStar, cambia x e y in across e down, ovunque dentro la funzione. Non toccare niente fuori. Eseguilo. Scopri perché non si è rotto niente.

  2. Disegnali al contrario. Scambia drawStars() e drawPlayer() in onOverlayUpdate e guarda l’astronave. Poi rimettili a posto. Ognuna di quelle cinque righe è un lavoro, e il loro ordine sullo schermo è il loro ordine nella funzione.

  3. Usa clamp su una sfumatura. Cambia shadeFor in return clamp(math.random(60, 90) + layer * 90, 0, 200) e guarda i tre strati. Poi togli il clamp e guarda di nuovo: colorForeground ti teneva in silenzio i numeri sotto il limite da sempre, e ora puoi vedere dove.

  4. Chiama drawStar con due argomenti. Scrivi drawStar(100, 100) da qualche parte in drawLayer ed eseguilo. L’errore nomina esattamente la cosa che è mancata. Leggilo prima di rimettere il terzo argomento.

  5. Sposta una locale. Prendi la riga local drift = 0 e spostala in fondo al file, sotto tutto il resto. Eseguilo, leggi l’errore e pensa alla parola «sotto» nella sezione precedente.

Rompilo apposta

L’ordine di un file con dentro delle locali conta, e l’errore che ottieni quando rompi quell’ordine non è quello che ti aspetti.

Prendi tutta la funzione drawStar e spostala in fondo allo script, sotto onOverlayUpdate. C’è ancora tutto, scritto allo stesso modo. Eseguilo:

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'

Ha un aspetto diverso dall’errore della prima lezione perché è un tipo di errore diverso. L’errore della prima lezione è stato colto prima che lo script partisse. Questo è stato colto mentre era in esecuzione, ed è per questo che Singe nomina la funzione in cui si trovava, e per questo sotto c’è un traceback: l’elenco di chi ha chiamato chi, dal più recente. La riga 50 è dentro drawLayer, che è stata chiamata dalla riga 57 dentro drawStars, che è stata chiamata dalla riga 101 dentro onOverlayUpdate. I tuoi numeri di riga saranno diversi se il tuo file non corrisponde esattamente a quello qui sopra, e il motore potrebbe aggiungere sotto queste una o due righe sue. La parola upvalue è il nome che Lua dà a una locale che una funzione ha preso in prestito dal file che la circonda; per ora passaci sopra.

La lamentela in sé vale la pena di impararla a memoria. «Attempt to call a nil value» vuol dire che hai messo delle parentesi dopo un nome che non conteneva niente. La parola global davanti a drawStar è la parte che svela tutto: hai segnato drawStar come locale, quindi quando Lua ha letto drawLayer e non ha trovato da nessuna parte sopra una locale con quel nome, l’unica cosa che restava da provare era una globale — e non c’è nemmeno una globale chiamata drawStar. Rimetti la funzione sopra il codice che la chiama e l’errore se ne va con lei.

Cosa hai imparato

  • Puoi scrivere funzioni tutte tue, e niente le esegue tranne le tue chiamate.

  • I nomi tra le parentesi di una funzione sono parametri, e sono le copie personali della funzione di quello che ha passato chi la chiama.

  • return restituisce un valore e ferma la funzione lì dov’è, e una funzione che finisce senza di esso restituisce nil.

  • Una chiamata può essere un argomento di un’altra chiamata, e quella interna avviene per prima.

  • Lua può restituire più di un valore, e li raccogli con più nomi separati da virgole.

  • local crea un nome che esiste solo dove è stato scritto.

  • Una locale dentro una funzione viene creata nuova a ogni chiamata e non ricorda niente di quella precedente.

  • Una locale si vede solo sotto la riga che la crea, quindi i valori e le tue funzioni vanno sopra le callback che li usano.

  • Le callback restano globali, perché Singe le trova per nome.

  • Vale la pena scrivere una funzione quando la cosa che fa ha un nome, anche se la chiami una volta sola.

La prossima volta

Le tue centoventi stelle sono ancora centoventi copie di tre idee. Niente nel programma è una stella: c’è un numero, e un po' di aritmetica che trasforma il numero in una posizione. Non puoi dire «questa è più vicina, quindi cade più in fretta e brilla di più», perché non c’è nessun «questa» di cui dirlo, e non puoi lasciare che una stella cada fuori dal fondo e venga sostituita da una nuova, perché lì non c’è niente da togliere.

La sesta lezione ti dà la cosa che contiene una stella, e poi un modo per contenerne centoventi e aggiungerne una centoventunesima mentre il gioco gira. È la lezione più utile di questa parte del libro.

Lezione 6: Elenchi di cose

La lezione finita

Hai centoventi stelle e nessuna di loro esiste. Nel tuo programma non c’è una stella da nessuna parte: c’è un ciclo che gira centoventi volte, e a ogni giro ricava due numeri dal numero della stella e dal suo livello, disegna un pixel e dimentica tutto. I tre livelli servono a simulare l’unica cosa che quella sistemazione non sa fare, cioè lasciare che una stella sia diversa dalla sua vicina.

Questa lezione ti dà il pezzo mancante. Imparerai a tenere un elenco di elementi, a creare un elemento che contiene diversi valori con un nome tutti insieme, e poi a mettere insieme le due cose in un elenco di elementi che ricordano ciascuno la propria posizione, velocità e luminosità. È la lezione più lunga di questa parte del libro, e quella su cui si appoggia tutto ciò che viene dopo. Prenditela con calma.

Crea una nuova cartella

Una cartella chiamata tables, dentro un file chiamato tables.singe, e Singe -R tables in esecuzione in un terminale. Copiaci dentro il programma finito della quinta lezione: il campo stellare, l’astronave e tutto il resto.

Un elenco

Aggiungi questa riga in cima a tables.singe, sotto gli altri valori, e le tre chiamate overlayPrint a onOverlayUpdate, sopra il return.

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

Avvialo. Ada su una riga, Alan sulla successiva e There are 3 names. sotto.

Le parentesi graffe della prima riga creano una tabella. Una tabella è l’unico contenitore che Lua abbia, e tutto ciò di cui conserverai più di uno ci finisce dentro. Qui contiene tre stringhe in fila, che è la forma che tutti chiamano elenco.

Le parentesi quadre delle righe successive tirano fuori un elemento. names[1] è il primo elemento, names[3] è il terzo, e il numero tra le parentesi quadre si chiama indice.

Quel numero è il punto in cui Lua si separa da quasi tutti gli altri linguaggi che incontrerai. Lua conta da uno. C, Java, Python, JavaScript e quasi tutti gli altri contano da zero, quindi il loro primo elemento è l’elemento zero e il loro terzo elemento ha indice due. Il primo elemento di Lua è l’elemento uno, ed è questa l’unica cosa che fa inciampare i programmatori che arrivano da altrove. Tu non arrivi da nessuna parte, quindi hai il compito più facile: il primo è il numero uno.

names[0], tra l’altro, non è un errore. È nil — il valore «niente» della terza lezione — perché lì non c’è niente. Leggere un indice che non è mai stato riempito dà sempre nil, il che è una gentilezza fino al momento in cui provi a usarlo.

Il # davanti al nome di una tabella è l’ultimo segno di punteggiatura nuovo per un bel po'. Ti dà quanti elementi ci sono nell’elenco, quindi #names vale 3. Siccome il conteggio e l’ultimo indice sono lo stesso numero, names[#names] è sempre l’ultimo elemento, per quanto l’elenco si allunghi.

Aggiungere e togliere

Un elenco che devi scrivere per intero non serve a molto in un gioco. Queste due chiamate sono il modo in cui un elenco cambia mentre il programma gira.

    table.insert(names, "Katherine")

Questa mette Katherine in fondo, e ora #names vale 4. table.insert è una funzione come tutte le altre, e il punto in mezzo al suo nome vuol dire che vive dentro una tabella chiamata table fornita da Lua — una tabella di funzioni per lavorare sulle tabelle. Non devi crearla né caricarla. C’è già.

Dai a table.insert tre argomenti e quello in mezzo dice dove mettere il nuovo elemento.

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

Edsger entra in testa, e tutto ciò che c’era già scivola avanti per fargli posto: Ada era l’elemento uno e ora è l’elemento due. Niente viene sovrascritto e niente va perso.

Togliere un elemento è l’immagine speculare.

    table.remove(names, 2)

L’elemento due se ne va, e tutto ciò che viene dopo scivola indietro per chiudere il vuoto, così l’elenco non ha mai un buco in mezzo. table.remove restituisce anche l’elemento che ha tolto, quindi local gone = table.remove(names, 2) se ne libera e ti dice che cos’era in una riga sola. Togli del tutto il numero — table.remove(names) — e toglie l’ultimo elemento, che è il modo più rapido di usare un elenco come una pila.

Metti queste tre chiamate nel tuo script, una alla volta, avvialo dopo ognuna e guarda cambiare il conteggio sulla terza riga.

Percorrere un elenco

Conosci già un modo per visitare ogni elemento, perché lo usi dalla quarta lezione:

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

Funziona. Comincia da uno, fermati al conteggio, usa il contatore come indice. C’è un modo migliore, ed è quello che scriverai d’ora in poi:

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

ipairs percorre un elenco dall’elemento uno finché non finisce, e a ogni giro passa al tuo ciclo due cose: l’indice e l’elemento stesso. Il punto è la seconda. Con il for numerico ottieni un numero e devi tornare alla tabella con names[i] per scoprire che cos’è; con ipairs l’elemento ce l’hai già in mano, con qualunque nome tu abbia messo per secondo.

È anche più difficile sbagliarlo. for i = 1, #names è un posto perfetto per sbagliare di uno — comincia da zero e stampi un nil, fermati a #names - 1 e perdi l’ultimo — e in ipairs non c’è proprio nessun numero da sbagliare.

Il più delle volte non vuoi l’indice, solo l’elemento. Scrivi l’indice come un singolo trattino basso e non pensarci più:

    for _, name in ipairs(names) do

_ è un nome perfettamente normale, e niente in Lua lo tratta in modo speciale. È un’abitudine che i programmatori condividono per dire «qui arriva qualcosa e non ho intenzione di usarlo». Chiunque legga il tuo ciclo capisce a colpo d’occhio che lì l’indice non conta.

Ora cancella gli esperimenti con names, e con loro le righe overlayPrint. Sai che cos’è un elenco. È ora di metterci dentro qualcosa di meglio di una stringa.

Una tabella può anche essere un record

Una stella deve ricordare quattro cose: dove si trova in orizzontale, dove si trova in verticale, quanto velocemente cade e quanto è luminosa. Quattro elenchi separati, tenuti allineati a mano, sarebbero un tormento. Invece crea una tabella e mettici dentro dei nomi.

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

Le graffe vuote creano una tabella vuota. Le quattro righe dopo ci mettono dentro dei valori sotto dei nomi invece che sotto dei numeri, e il punto è il modo in cui dici quale nome intendi. star.x si legge la x di star, e si comporta esattamente come qualsiasi altra variabile: leggila, assegnale un valore, aggiungici qualcosa.

    star.y = star.y + star.speed

Una tabella usata così — un insieme fisso di valori con un nome che descrivono una cosa sola — è un record, e i nomi al suo interno sono i suoi campi. È lo stesso tipo di tabella dell’elenco qui sopra. L’unica differenza è che gli elementi di un elenco si trovano per numero e i campi di un record si trovano per nome, e una tabella può fare entrambe le cose insieme, se mai ti servisse.

Il punto è un’abbreviazione. star.x e star["x"] vogliono dire esattamente la stessa cosa, e vale la pena vederlo una volta: le parentesi quadre accettano un nome volentieri quanto un numero, quindi un elenco e un record sono davvero un’idea sola con due cappelli diversi. Usa il punto. Si legge meglio.

Un campo che non hai mai impostato è nil, come un indice che non hai mai riempito. Non c’è da nessuna parte un elenco dei nomi di campo permessi, e niente controlla come scrivi, quindi star.sped non è un errore — è nil, e quello che succede dopo lo vedrai alla fine di questa lezione.

Scrivere quattro righe per riempire quattro campi stanca presto. Puoi mettere i campi dentro le graffe quando crei la tabella:

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

Stessa tabella, un’istruzione sola. Le virgole separano i campi, l’ultimo non vuole una virgola dopo, e le righe sono distribuite così solo perché si leggano facilmente.

Un elenco di record

Ecco l’idea intera di questa lezione in due righe:

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

Un elenco può contenere qualsiasi cosa, comprese le tabelle. Quindi un elenco di record è un elenco di cose che ricordano ciascuna tutto di sé. stars[1] è una stella intera, e stars[1].y è la distanza di quella stella dall’alto dello schermo. Quasi ogni gioco che scriverai è una manciata di elenchi come questo: i nemici, i proiettili, gli oggetti da raccogliere e i blocchi che cadono.

C’è una cosa sulle tabelle che devi sapere prima di scrivere il codice, e prima o poi frega tutti, una volta. Passare una tabella a una funzione non la copia. Un numero viene copiato — è per questo che nella quinta lezione half poteva fare a pezzi il suo number senza disturbare drift — ma una tabella è condivisa. Entrambi i nomi si riferiscono alla stessa tabella, e una modifica fatta attraverso uno si vede attraverso l’altro.

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

Questo sposta la terza stella dell’elenco. Non una sua copia: proprio lei. È esattamente ciò che vuoi qui, ed è ciò che fa funzionare la prossima sezione, ma ricordatelo quando una funzione che hai scritto cambia qualcosa che non ti aspettavi.

Ricostruisci il campo stellare

Fuori l’aritmetica. Una stella sta per diventare una cosa.

Cancella starAt, shadeFor, drawLayer e il vecchio drawStar, e con loro le costanti che usavano: LAYERS, STARS_PER_LAYER, ACROSS_STEP, DOWN_STEP, LAYER_SHIFT e LAYER_SPEED. Se ne va anche la variabile drift, e con lei la riga di drift in cima a onOverlayUpdate. LAYER_BRIGHT resta, con un nome che non parla più di livelli, e lo raggiungono due valori:

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

Centoventi è quello che avevi: tre livelli da quaranta. L’elenco parte vuoto, e questo è ciò che lo riempie:

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 stella e te la restituisce. Guarda l’ultimo campo e confrontalo con shadeFor nella quinta lezione: la stessa somma, con la velocità della stella al posto del numero del livello. I livelli non sono spariti, si sono piuttosto dissolti. Ogni stella ora si sceglie la propria velocità, uno, due o tre pixel a fotogramma, e una stella che cade più veloce è più luminosa, il che è tutta l’illusione della profondità e costa una riga.

La y di partenza è un parametro perché i due chiamanti vogliono cose diverse. Le stelle create quando il gioco parte devono essere sparse su tutto lo schermo; quelle create dopo entrano dall’alto.

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

Per ora niente chiama makeStars. Aggiungi una riga proprio in fondo al file, dopo tutto il resto e fuori da qualsiasi funzione:

makeStars()

C’è altro da dire su quella riga, e aspetta la fine della lezione. Ora il disegno, che si accorcia ogni volta che lo tocchi:

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

Nella quinta lezione drawStar prendeva tre numeri, e ora prende una stella. Tutto ciò che deve sapere è dentro la stella, ed è proprio questa la ragione per cui esistono i record: una cosa sola da passare in giro invece di quattro, e nessuna possibilità di consegnarle nell’ordine sbagliato. E drawStars ha perso il suo ciclo sui livelli, insieme a qualsiasi interesse per quante stelle ci sono o da dove sono venute.

Stelle che vanno e vengono

Ora la parte che il vecchio campo stellare non sapeva proprio fare. Le stelle cadono ognuna alla propria velocità, escono dal fondo e vengono sostituite in cima.

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

Chiamala da onOverlayUpdate, sulla riga dove prima c’era drift = drift + 1.

Ogni stella scende della sua speed, ed è la riga che la quinta lezione non poteva scrivere. Il while in fondo è il rabbocco: finché ci sono meno di centoventi stelle, creane un’altra in cima allo schermo. Gira tutte le volte che serve e poi si ferma, ed è lo strumento giusto quando non sai quante ne mancano.

La riga del for in cima conta all’indietro, usando il passo che hai incontrato nella quarta lezione. for i = #stars, 1, -1 visita prima l’ultimo elemento e torna indietro fino all’elemento uno. Non è un vezzo. È l’unico modo sicuro di fare ciò che fa questo ciclo, e la prossima sezione spiega perché.

Mai togliere andando avanti

Scrivi lo stesso ciclo in avanti ed è rotto:

    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

Seguilo a mano con quattro stelle, e supponi che le stelle due e tre abbiano raggiunto entrambe il fondo.

  • i vale 1. La stella uno va bene.

  • i vale 2. La stella due è uscita dal fondo, quindi viene tolta. Tutto scivola giù: la stella che era la tre ora è la due, e quella che era la quattro ora è la tre.

  • i vale 3. È la stella che prima era la quattro. La stella tre non è mai stata guardata. Togliere l’elemento due l’ha fatta scendere nella posizione due, e il ciclo dalla posizione due era già passato.

  • i vale 4. Non c’è più nessun elemento quattro. stars[4] è nil.

Due guasti distinti da un piccolo errore. Alcuni elementi vengono saltati, quindi una stella che aveva raggiunto il fondo questa volta non viene nemmeno guardata. Una stella che sopravvive un fotogramma in più non fa danni, ma lo stesso ciclo su un elenco di nemici, dove essere guardati è ciò che li uccide, è un bug che inseguiresti per un’ora. Il secondo guasto fa più rumore. L’elenco ora è più corto del conteggio con cui il ciclo è partito, perché #stars è stato calcolato una volta sola, prima di qualsiasi rimozione, quindi gli ultimi giri del ciclo vanno oltre la fine dell’elenco:

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» vuol dire che hai messo un punto dopo qualcosa che non conteneva niente. Il (local 'star') alla fine dice di chi si tratta: star era nil, quindi star.y non aveva dove guardare.

Andare all’indietro risolve entrambi i guasti in un colpo solo, e vale la pena vedere perché invece di crederci sulla parola. Quando togli l’elemento i, tutto ciò che viene dopo i scende di una posizione — e andando all’indietro, tutto ciò che viene dopo i è tutto ciò che hai già visitato. Ciò che deve ancora venire, gli elementi da i - 1 giù fino a 1, non si è mosso affatto. Nemmeno l’elenco che si accorcia alle tue spalle può farti male, perché stai camminando verso l’elemento uno e l’elemento uno c’è sempre.

La regola, che userai per tutta la vita: quando un ciclo potrebbe togliere elementi dall’elenco che sta percorrendo, percorrilo all’indietro.

ipairs non fa eccezione. Togliere elementi in mezzo a un ciclo ipairs va storto nello stesso modo. ipairs serve a guardare, e il for all’indietro serve a cambiare.

Aggiungine qualcuna tu

Un ramo in più in onInputPressed e puoi guardare l’elenco crescere mentre il gioco gira. Va insieme agli altri due:

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

addBurst va sopra le callback, con le tue altre funzioni. E perché tu possa vedere cambiare la lunghezza dell’elenco, metti il conteggio sullo schermo in onOverlayUpdate:

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

Premi il pulsante — la barra spaziatrice, a meno che tu non abbia cambiato da dove arriva SWITCH_BUTTON1 — una dozzina di volte. Il conteggio sale di dieci a ogni pressione e il cielo si infittisce, e se lo tieni premuto non si ripete: onInputPressed viene avvisata una volta sola, quando il pulsante va giù. Poi guarda il conteggio tornare da solo a centoventi man mano che le stelle in più raggiungono il fondo e vengono tolte, perché il rabbocco riempie l’elenco solo fino a STAR_COUNT e non lo accorcia mai.

Niente nel disegno, nel movimento o nella rimozione ha dovuto sapere che il numero delle stelle era cambiato. Lavorano tutti a partire dall’elenco.

Tutto insieme

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()

Cos’è appena successo

Il programma è più corto di quello della quinta lezione e fa qualcosa che la quinta lezione non poteva nemmeno cominciare a fare. Tre pezzi meritano una seconda occhiata.

makeStars()

Quella singola riga in fondo al file non sta dentro nessuna funzione, ed è facile non notarla. Lua legge il tuo file dall’alto in basso quando Singe lo carica, e una riga al livello esterno del file viene eseguita lì per lì, una volta, prima che il motore abbia chiamato qualsiasi cosa. Tutto ciò che sta sopra sono definizioni — ecco un valore, ecco una funzione — e questa è l’unica istruzione che avviene al caricamento. Deve stare in fondo, perché makeStars non esiste finché non è stata letta la riga che la crea.

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

star è una variabile locale creata da capo a ogni giro del ciclo, e contiene la stessa tabella che sta nell’elenco — non una sua copia. Cambiare star.y sposta la stella che sta nell’elenco. Se le tabelle venissero copiate, questo ciclo sposterebbe centoventi copie a fotogramma e sullo schermo non cambierebbe mai niente.

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

Confrontalo con la quarta lezione: due cicli annidati, due calcoli per stella, un resto per tenere ciascuna sullo schermo e tre livelli per simulare la varietà che ora ottieni gratis. Il disegno non sa più, e non gli interessa, come le stelle siano arrivate dove sono, quante siano o che cosa succederà loro dopo. Ogni parte del programma fa un solo lavoro, e l’elenco è ciò su cui sono tutte d’accordo.

Prova tu

  1. Rendilo più profondo. Cambia math.random(1, 3) in math.random(1, 6) e STAR_SHADE in 25. Più velocità, più sfumature, un cielo più profondo.

  2. Meno stelle, raffica più grande. Imposta STAR_COUNT a 10 e BURST_COUNT a 100, poi premi il pulsante tre o quattro volte. Guarda salire il conteggio sullo schermo, e cronometra quanto ci mette a svuotarsi.

  3. Dai a una stella un altro campo. Aggiungi age = 0 a newStar, aggiungi uno a star.age in moveStars e metti stars[1].age sullo schermo accanto al conteggio. Per portarsi dietro un fatto nuovo su ogni stella, nel resto del programma non serve cambiare niente.

  4. Smetti di toglierle. Cancella le tre righe del blocco if star.y >= height da moveStars ed eseguilo. Aspetta dieci secondi, poi leggi il conteggio sullo schermo e guarda il cielo. Scopri come possono essere vere entrambe le cose insieme.

  5. Fallo in avanti. Cambia for i = #stars, 1, -1 in for i = 1, #stars ed eseguilo finché non cade. Poi rileggi la sezione qui sopra con l’errore vero davanti agli occhi.

Rompilo apposta

Scrivi male il nome di un campo. In moveStars, cambia star.speed in star.sped:

        star.y = star.y + star.sped

Eseguilo:

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'

I tuoi numeri di riga non saranno esattamente questi, a meno che il tuo file non corrisponda riga per riga a quello qui sopra. Quello che leggi sono il nome del file, il numero che lo segue e la lamentela.

Leggi prima la fine della prima riga. field 'sped' è Lua che ti dice quale nome è risultato vuoto, e ti dice che era un campo — qualcosa dopo un punto — e non una tua variabile. «Attempt to perform arithmetic on a nil value» è ciò che stava facendo quando se n’è accorto: sommare nil a un numero, cosa che non si può fare.

Non ci sono state lamentele quando la tabella è stata creata senza un campo sped, e nessuna nel momento in cui l’hai chiesto. Una tabella restituisce nil per qualsiasi nome che non ha, senza commenti. L’errore arriva dopo, alla prima riga che prova a usare il niente che ti è stato dato, e che può essere molto lontana dall’errore di battitura. Quando vedi nil value (field 'something'), cerca il punto in cui quel nome è stato scritto in modo diverso.

Cosa hai imparato

  • Le graffe creano una tabella, l’unico contenitore che Lua abbia. Una tabella usata come elenco contiene elementi in fila, e le parentesi quadre con un indice ne tirano fuori uno.

  • Lua conta da uno. Quasi tutti gli altri linguaggi contano da zero.

  • #list è quanti elementi contiene, e list[#list] è l’ultimo.

  • table.insert aggiunge un elemento, in fondo o nella posizione che indichi; table.remove ne toglie uno e chiude il vuoto.

  • Un indice o un campo mai riempito è nil, e niente ti avvisa finché non lo usi.

  • ipairs percorre un elenco e ti passa l’indice e l’elemento; _ è l’abitudine per un indice che non ti serve.

  • Una tabella usata come record contiene campi con un nome, che raggiungi con un punto.

  • Un elenco di record è il modo in cui un gioco tiene i suoi nemici, i suoi proiettili e tutto ciò di cui ha più di uno.

  • Le tabelle, quando le passi in giro, sono condivise, non copiate.

  • Quando un ciclo può togliere elementi dall’elenco che sta percorrendo, percorrilo all’indietro.

La prossima volta

Ora hai tutti i pezzi di un gioco: cose che si muovono, un’astronave che risponde ai comandi, decisioni, cicli, funzioni e un elenco in cui le cose possono entrare e da cui possono uscire mentre il gioco gira.

La settima lezione li mette insieme in un gioco in cui puoi perdere. Ti sposti lungo il fondo dello schermo, dei blocchi cadono dall’alto e tu stai alla larga — e i blocchi che cadono sono un elenco di record, creati, spostati e tolti esattamente come le tue stelle.

Lezione 7: Un gioco

La lezione finita

Sei lezioni fa hai messo una parola su uno schermo nero. Da allora hai imparato tutte le idee di cui è fatto un piccolo gioco: variabili, decisioni, cicli, funzioni tutte tue ed elenchi di cose. Questa lezione non insegna un’idea nuova. Spende quelle che hai.

Costruirai un gioco chiamato Dodge. Dei blocchi cadono dal cielo, tu fai scorrere una barra lungo il fondo per scansarli, e ogni blocco che ti manca è un punto. Fatti colpire da tre ed è finita. Lo costruirai in sei fasi, e ognuna di esse funziona: non dovrai mai scrivere cento righe e sperare.

Crea la cartella

Crea una cartella chiamata dodge, e dentro un file chiamato dodge.singe. Avvialo come avvii tutto dalla prima lezione:

Singe -R dodge

Lascialo in esecuzione in un terminale per tutta la lezione. Ogni volta che salvi, il gioco riparte con dentro la tua modifica.

Prima fase: qualcosa da guidare

Scrivi questo, salva e guidalo con i tasti freccia sinistra e destra.

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

Cinquanta righe, e quasi niente è nuovo. Due cose lo sono, quindi parti dalla prima riga.

dofile("Singe/Framework.singe")

dofile appartiene a Lua più che a Singe, e vuol dire «vai a eseguire quel file, poi continua qui». Il file che esegue è Singe/Framework.singe, uno dei file che il motore ha estratto nella tua cartella di lavoro la prima volta che hai eseguito qualcosa, nella prima lezione. Aprilo nel tuo editor di testo e guarda: è Lua normale, non diverso per natura da quello che scrivi dalla seconda lezione, e non c’è niente di magico.

Eseguirlo consegna al tuo script una serie di nomi che poi può usare. Quelli a cui ricorre questo libro sono questi:

  • DIR, che contiene la cartella in cui si trova il tuo script. La nona lezione ne ha bisogno appena un gioco carica un’immagine, ed è il vero motivo per cui questa riga è qui.

  • SCANCODE e MODIFIER, nomi per ogni tasto di una tastiera, per un gioco che legge quello che si digita invece di un joystick.

  • Da GAMEPAD_0 a GAMEPAD_3 e da MOUSE_0 a MOUSE_3, per un cabinato con più di un esemplare di qualcosa collegato.

  • Alcune funzioni di aiuto il cui nome comincia con util, e le sei chiamate che inviano un punteggio a una classifica, che sono la ventottesima lezione.

  • Il secondo modo di scrivere un gioco, del tutto diverso, che è la quindicesima lezione.

Una cosa che non ti dà, perché è la cosa naturale da supporre. SWITCH_LEFT, e ogni altro nome che comincia con SWITCH_, viene dal motore stesso, prima ancora che venga eseguito qualsiasi script. È per questo che dalla terza alla sesta lezione hai potuto leggere i tasti freccia senza caricare niente. Il framework aggiunge a ciò che c’è già; non lo fornisce.

Questo gioco in particolare non usa niente del framework. La riga è qui perché ogni gioco dalla nona lezione alla fine del libro ne ha bisogno, e perché è così che cominciano quasi tutti i veri giochi Singe. Viene letta una volta, all’avvio, e poi dimenticata.

La seconda cosa nuova è il modo in cui vengono gestiti i tasti freccia, perché è la prima cosa che i principianti sbagliano.

onInputPressed non muove il giocatore. Imposta goingLeft a true, e onInputReleased lo rimette a false. Il movimento avviene in onOverlayUpdate, che sessanta volte al secondo chiede «il giocatore sta tenendo premuto sinistra?». Se invece muovessi il giocatore dentro onInputPressed, otterresti un passo per pressione: Singe invia una pressione esattamente una volta, quando il tasto va giù, e non la ripete mai, come dice chiaramente la voce di onInputPressed nel Riferimento. Tenere premuto il tasto non farebbe proprio niente.

Quindi il gestore della pressione registra ciò che è vero nel mondo, e l’aggiornamento decide che cosa farne. Mantieni questa divisione e il tuo codice per i comandi resterà lungo cinque righe per sempre.

I quattro nomi in maiuscolo sono variabili normali. Scrivere PLAYER_SPEED in maiuscolo è un messaggio a te stesso e a chiunque legga: questo viene impostato una volta in cima e non cambia mai. Niente in Lua lo impone. Conta perché fra un minuto ce ne saranno dieci, e quando il gioco è troppo difficile vuoi un posto ovvio dove andare ad abbassare un numero.

screenWidth e screenHeight vengono dal motore invece di essere scritti a mano, così il gioco si dispone da sé secondo la dimensione che l’overlay si trova ad avere. playerY viene calcolato una volta sola dall’altezza: la barra sta a PLAYER_MARGIN pixel dal fondo e non si muove mai né su né giù, quindi non c’è motivo di ricalcolarlo a ogni fotogramma.

Il - 1 nella riga di overlayBox non è un errore di battitura. overlayBox disegna fino a entrambi gli angoli che gli dai, compresi, quindi un riquadro da playerX a playerX + 40 è largo quarantuno pixel. Togliere uno rende la barra che vedi larga esattamente quaranta, e conterà nella quarta fase, quando qualcosa dovrà decidere se ti ha toccato.

Seconda fase: qualcosa da schivare

Un blocco che cade. Aggiungi due costanti all’elenco in cima:

local BLOCK_SIZE    = 12
local BLOCK_SPEED   = 1.5

Altre due variabili sotto goingRight:

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

In onOverlayUpdate, subito sopra la riga overlayClear(), fallo cadere:

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

E sotto la riga che disegna il giocatore, disegnalo:

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

Salva. Un quadrato rosso cade, raggiunge il fondo e ricompare in cima in un punto nuovo.

Parte da -BLOCK_SIZE, che è sopra il bordo superiore dello schermo. Non c’è niente di sbagliato in una posizione negativa: il motore disegna la parte del riquadro che sta sull’overlay e butta via in silenzio quella che non c’è. Il blocco scivola nella visuale invece di spuntare dal nulla.

BLOCK_SPEED vale 1.5, non un numero intero, quindi blockY passa gran parte della sua vita a valere qualcosa come 83.5. Va bene anche questo. Il disegno taglia via la parte decimale, e tenerla nella variabile è ciò che permette al blocco di muoversi più lentamente di un pixel a fotogramma.

Terza fase: un cielo pieno di blocchi

Un blocco non è un gioco. Nella sesta lezione hai imparato a tenere tanti esemplari di qualcosa in un elenco, e questo è ciò a cui serviva.

Cancella blockX e blockY, e al loro posto metti questi:

local blocks     = {}
local spawnTimer = 0

Aggiungi un’altra costante in cima:

local SPAWN_FRAMES  = 40

Ora una funzione che crea un blocco e lo mette nell’elenco. Mettila sopra onInputPressed:

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

Sostituisci il codice della caduta della seconda fase con questo:

    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

E sostituisci l’unica riga che disegnava il blocco con un ciclo su tutti quanti:

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

Salva. Piovono blocchi.

Un blocco è un record: una piccola tabella con dentro una x e una y, che è il modo di evitare che due numeri che stanno insieme vadano ognuno per conto suo. blocks è un elenco di questi record, che è la forma che ha il mondo di quasi ogni gioco.

spawnTimer conta all’indietro di uno a ogni fotogramma, e quando arriva a zero nasce un blocco e il timer viene ricaricato. Quaranta fotogrammi sono circa due terzi di secondo. In questo gioco non c’è un orologio e non ce n’è bisogno: onOverlayUpdate è il battito del cuore, e contare i battiti è un modo perfettamente valido di misurare il tempo.

Il ciclo della caduta va all’indietro — da #blocks giù fino a 1, un passo alla volta — perché toglie cose mentre procede. È la regola della sesta lezione, ed è la prima volta che hai un vero motivo per rispettarla. Togli l’elemento tre mentre vai avanti e tutto scivola giù di uno, così il blocco che era l’elemento quattro ora è l’elemento tre e il ciclo non lo guarda mai. Andando all’indietro, tutto ciò che si sposta è già stato sistemato.

Il ciclo del disegno invece usa ipairs, perché non toglie niente e vuole solo ogni blocco a turno.

Quarta fase: farsi colpire

I blocchi ti passano attraverso. È ora di accorgersene.

Il motore ha una funzione proprio per questa domanda. Cambia il controllo dentro il ciclo della caduta da così:

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

a così:

        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

Salva, e porta la barra contro un blocco che cade. Sparisce.

collideRects prende due rettangoli e risponde true se si sovrappongono. Ogni rettangolo è fatto di quattro numeri: un angolo, poi una larghezza e un’altezza — non due angoli, che è l’altro modo ragionevole di descrivere un rettangolo e quello usato da overlayBox. La voce di collideRects nel Riferimento dà l’ordine, e vale la pena guardarla adesso, perché mettere gli otto argomenti nell’ordine sbagliato è il tipo di errore che non produce nessun messaggio, solo un gioco in cui niente colpisce mai niente.

Potresti scriverla da te. Sono quattro confronti, e non è davvero difficile. Usa comunque quella del motore, per tre motivi. È corretta, anche nei casi scomodi: un rettangolo senza larghezza, due rettangoli che si toccano solo lungo un bordo. Dice quello che intende, così la riga si legge «questi due si sono sovrapposti?» invece di quattro confronti uniti da and da decifrare ogni volta che ci torni. E quando arriverai all’undicesima lezione, dove le cose si colpiscono di continuo, conoscerai già la famiglia: collidePointRect per un clic del mouse, collideCircles per due cose rotonde e collideSegments per un colpo contro un muro. Il Riferimento le elenca insieme.

L’unica cosa che il motore non può fare per te è decidere che cosa significa un rettangolo. Qui il rettangolo del blocco è il blocco intero. In un vero gioco spesso vuoi che il rettangolo di collisione sia un po' più piccolo dell’immagine, così un colpo mancato di poco sembra proprio un colpo mancato di poco. È una decisione di design, e l’undicesima lezione è dove la prendi.

Quinta fase: punteggio e vite

Essere colpiti dovrebbe costare qualcosa, e sopravvivere dovrebbe valere qualcosa.

Due costanti in più in cima:

local BLOCK_FASTER  = 0.05
local START_LIVES   = 3

Tre variabili in più, accanto a spawnTimer:

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

BLOCK_SPEED ora è la velocità a cui il gioco comincia, e blockSpeed è la velocità a cui sta andando in questo momento. Cambia la riga della caduta perché usi la variabile:

        block.y = block.y + blockSpeed

Poi separa i due casi, perché ora fanno cose diverse:

        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

E mostra i numeri. Metti questo subito prima del return:

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

Salva, e giocaci per un minuto. Diventa più difficile, ed è tutto lì il trucco: ogni blocco che schivi fa cadere i successivi più veloci di un ventesimo di pixel a fotogramma. Dopo venti punti sono visibilmente più rapidi. Non hai dovuto scrivere una sola parola sui livelli di difficoltà.

Vedrai anche LIVES arrivare a -4, perché ancora niente ferma il gioco. È la prossima fase, ed è quella che conta di più.

Sesta fase: game over e una nuova partita

Ecco la trappola. Il modo ovvio per aggiungere una schermata di game over è una variabile chiamata gameOver, impostata a true quando finiscono le vite. Poi vuoi una schermata del titolo prima della prima partita, quindi aggiungi started. Poi vuoi un tasto di pausa, quindi aggiungi paused. Ora hai tre variabili vero-o-falso, otto combinazioni tra loro, e cinque di quelle combinazioni sono assurdità che il tuo codice deve stare attento a non produrre mai. Ogni principiante scrive questo gioco almeno una volta, ed è il posto dove i piccoli giochi vanno a morire.

Fai invece così. Una variabile contiene che cosa sta facendo il gioco, sotto forma di parola:

local state      = "waiting"

Vale "waiting" prima della prima partita, "playing" durante una partita e "over" quando le vite sono finite. Tre stati, una variabile, e nessuna combinazione impossibile. Le stringhe non hanno niente di magico; sono parole che hai scelto tu, e devi scriverle sempre allo stesso modo.

Ora la funzione che comincia una partita. Ogni variabile che appartiene a una partita torna qui al suo valore iniziale, in un posto solo:

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

Perdere l’ultima vita la fa finire. Dentro il ramo della collisione, sotto lives = lives - 1:

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

La barra spaziatrice comincia una partita, ma solo quando non ce n’è già una in corso. Aggiungi un ramo a onInputPressed:

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

~= vuol dire «è diverso da». state ~= "playing" è vero durante l’attesa e vero a partita finita, che sono esattamente i due momenti in cui la barra spaziatrice deve cominciare una partita. SWITCH_BUTTON1 è la barra spaziatrice per impostazione predefinita, e anche il pulsante A di un controller.

Due piccole funzioni mettono le parole sullo schermo. printCentered fa il calcolo una volta sola, così che la schermata del titolo e quella di game over non debbano farlo male ciascuna per conto suo:

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 un’altra costante in cima:

local TEXT_COLUMNS  = overlayGetWidth() // overlayGetFontWidth()

Infine, la parte importante. Sposta tutto ciò che disegna fuori da onOverlayUpdate, in una funzione chiamata drawGame, sposta tutto ciò che muove in una funzione chiamata updatePlaying — sono tutte e due nel listato completo qui sotto — e lascia onOverlayUpdate così:

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

Salva. Hai un gioco: una schermata del titolo, una partita, un game over e un modo per ricominciare.

Rileggi quelle tredici righe, perché sono la forma di ogni gioco che scriverai. Il mondo si muove solo mentre lo stato è "playing", quindi la schermata di game over si congela con gli ultimi blocchi sospesi esattamente dov’erano. Il mondo viene disegnato a ogni fotogramma qualunque sia lo stato, perché l’immagine è la stessa in tutti e tre; lo stato decide solo quali parole ci vanno sopra. E c’è esattamente un posto che prende questa decisione.

Ecco che cosa ti sei comprato con la variabile state. Quando aggiungerai una pausa, aggiungerai un ramo a quell’istruzione if e una riga a onInputPressed, e nient’altro nel gioco avrà bisogno di saperne qualcosa.

Tutto insieme

Eccolo, finito. Se il tuo non corrisponde, vale la pena trovare la differenza.

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

Circa centoventi righe di codice, e le hai scritte tutte poche alla volta.

Cos’è appena successo

Alcuni pezzi meritano una seconda occhiata.

local blocks     = {}
local score      = 0


function startGame()
    score = 0
end

I dati sono local e le funzioni no. Sono due scelte volute, e opposte.

I dati sono local perché appartengano a questo file e niente da fuori possa entrare a cambiarli. Le funzioni sono globali perché possano chiamarsi a vicenda in qualsiasi ordine: drawOverText è definita prima di printCentered e la chiama lo stesso, perché un nome globale viene cercato nel momento della chiamata, e a quel punto l’intero file è già stato letto. Rendi local quelle funzioni e il file dovrà essere ordinato in modo che niente venga usato prima di comparire, una regola su cui inciamperesti per tutto il resto del libro. Tre di questi nomi non hanno proprio scelta: onOverlayUpdate e le due callback dei comandi devono essere globali, perché è così che Singe le trova.

Dentro il file l’ordine è alfabetico, con le tre callback per ultime. Non è una regola di Lua. Serve a farti trovare spawnBlock fra sei mesi senza leggere niente.

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

#text è la lunghezza di una stringa, in caratteri. Hai incontrato # nella sesta lezione, mentre contava gli elementi di un elenco, e qui fa lo stesso lavoro. "GAME OVER" è lungo nove caratteri, quindi su uno schermo di sessanta colonne comincia alla colonna venticinque, il che lascia venticinque celle di spazio alla sua sinistra e ventisei alla sua destra. math.floor butta via la parte decimale, perché non esiste una colonna venticinque e mezzo.

TEXT_COLUMNS calcola quante celle di carattere stanno in larghezza sullo schermo. overlayPrint conta in celle mentre tutto il resto conta in pixel, quindi la larghezza dell’overlay viene divisa per la larghezza di una cella, ed è overlayGetFontWidth a dirtela. Due barre invece di una, perché una frazione di colonna non è un posto dove stampare. Calcolalo così e la centratura resta giusta con qualsiasi dimensione dell’overlay, che è la quarta cosa di Prova tu.

    colorForeground(255, 90, 90)

colorForeground imposta un colore che resta impostato. Non è un argomento di overlayBox; è un interruttore che fai scattare, e tutto ciò che disegni dopo esce in quel colore finché non lo fai scattare di nuovo. È per questo che drawGame imposta il verde, disegna il giocatore, imposta il rosso e poi disegna tutti i blocchi senza più nominare il colore.

Non influisce su overlayPrint. Il font della console viene copiato sull’overlay esattamente com’è, nei suoi colori, come dice testualmente la voce di overlayPrint nel Riferimento. Il testo colorato ha bisogno di un font caricato, e questa è la diciannovesima lezione.

Prova tu

  1. Rendilo più facile, poi ingiusto. Cambia PLAYER_WIDTH in 80 e gioca una partita. Poi cambialo in 12, la stessa dimensione di un blocco. Nota che per fare l’una o l’altra cosa non hai dovuto toccare né il disegno né la collisione.

  2. Accelera più in fretta. Cambia BLOCK_FASTER da 0.05 a 0.5 e guarda quanti punti riesci a fare. Poi prova 0, e chiediti se vale ancora la pena di giocarci.

  3. Una vita in più. Restituisci una vita al giocatore ogni dieci punti. Tutto ciò che ti serve è già in updatePlaying, nel ramo che aumenta il punteggio.

  4. Giocalo più grande. Avvialo con Singe -R --canvas=1280x720 dodge. Il gioco si dispone correttamente, testo centrato compreso, perché ha chiesto al motore quanto è grande lo schermo. Anche TEXT_COLUMNS l’ha chiesto.

  5. Mettilo in pausa. Aggiungi un quarto stato, "paused". SWITCH_BUTTON2 dovrebbe passare da "playing" a "paused" e viceversa, e durante la pausa non dovrebbe muoversi niente. Fatto bene, sono tre righe e non devi toccare updatePlaying per niente.

Rompilo apposta

Vai in spawnBlock e cancella la riga che imposta block.y, così che diventi:

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

Salva, premi la barra spaziatrice, e Singe si ferma con questo:

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 riga 97 è block.y = block.y + blockSpeed. La lamentela è che qualcosa in quella somma non è un numero, e la parte tra parentesi ti dice che cosa: field 'y', cioè la y dentro una tabella. Non ha un valore, perché non gliel’hai mai dato, e una cosa senza valore in Lua è nil.

Nota dov’è l’errore e dov’è lo sbaglio. L’errore è in updatePlaying, a quaranta righe da spawnBlock, dove non c’è proprio niente che non va. updatePlaying è solo il primo pezzo di codice abbastanza sfortunato da toccare il danno. Questo è il caso normale, non l’eccezione, e seguire quella pista a ritroso è un’abilità.

Rimetti la riga. Poi gira pagina, perché la prossima lezione parla solo di questo.

Cosa hai imparato

  • Un gioco è un mondo che cambia, un mondo che viene disegnato e una decisione su quale delle due cose fare — e sono tre pezzi di codice separati.

  • I gestori dei comandi dovrebbero registrare che cosa è tenuto premuto; l’aggiornamento dovrebbe decidere che cosa significa.

  • Un elenco di record è la forma di quasi ogni mondo di gioco.

  • Togli le cose da un elenco percorrendolo all’indietro.

  • collideRects risponde se due rettangoli si sovrappongono, e la versione del motore è migliore della tua perché è corretta, si legge bene e ha una famiglia che incontrerai di nuovo.

  • Una variabile state che contiene una parola batte tre indicatori vero-o-falso, e continua a batterli man mano che il gioco cresce.

  • Comincia una partita da una funzione che azzera tutto, così la seconda partita è esattamente come la prima.

  • I numeri che potresti voler regolare vanno in costanti con un nome, in cima al file.

  • Costruisci un gioco per fasi che funzionano ciascuna. Un programma che non ha mai funzionato è molto più difficile da correggere di uno che funzionava cinque minuti fa.

La prossima volta

Ora hai scritto abbastanza codice da fare errori interessanti. La prossima lezione è quella di cui nessun libro per principianti si preoccupa: che cosa dicono davvero i messaggi di errore di Singe, come scoprire che cosa contiene davvero una variabile invece di tirare a indovinare, e come tagliare un problema a metà finché non gli resta nessun posto dove nascondersi.

Lezione 8: Quando qualcosa va storto

La lezione finita

Hai scritto un gioco. Da qui in poi passerai più tempo ad aggiustare programmi che a scriverli, e non è segno che ci sia qualcosa che non va in te. È il mestiere. La differenza tra chi si diverte a programmare e chi ci rinuncia non è quasi mai il talento; è se ha imparato a leggere quello che il computer gli sta dicendo.

Quindi in questa lezione non c’è niente di nuovo da costruire. Ci sono i cinque messaggi che vedrai più spesso per il resto della tua vita, che cosa vuol dire davvero ciascuno, e quattro modi per stanare l’errore che c’è dietro. Tieni aperto dodge.singe della settima lezione, perché lo romperai apposta parecchie volte.

Due tipi di arresto

Singe si ferma per due motivi diversi, e lo dice in due modi diversi.

Quando lo script non parte nemmeno, ottieni questa forma:

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

Lua legge tutto il tuo file prima di eseguirne una sola parola, e questo vuol dire che non è riuscito a dare un senso a ciò che ha letto. Non è stato eseguito niente.

Quando lo script è partito bene ma qualcosa è andato storto dopo, ottieni invece questa 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'

Il gioco stava girando. Singe ha chiamato la tua onOverlayUpdate, come fa sessanta volte al secondo, e questa volta la chiamata non è tornata.

Entrambe le forme contengono le stesse tre cose, e sono proprio le tre cose che vuoi: un file, una riga e una lamentela. Leggile in quest’ordine, ogni volta.

I numeri di riga di questa lezione vengono dal listato finito della settima lezione. Se i tuoi sono spostati di una riga o due, lo è anche il tuo file, e niente nel leggere un errore dipende dal fatto che il numero corrisponda.

Quelli che lo fermano prima che parta

Questi sono quelli facili, e sono anche quelli che fanno sentire peggio, perché lo schermo resta nero e non c’è niente da guardare.

Vai in updatePlaying e cancella la parola then dalla riga if spawnTimer ⇐ 0 then. Salva:

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

Lua è arrivato alla fine della riga con if, voleva la parola then e invece ha trovato l’inizio della riga successiva — che è spawnBlock(), ed è quella la parte near 'spawnBlock'. «Near» vuol dire «è qui che me ne sono accorto», e di solito è la prima cosa dopo quello che hai dimenticato.

Ora una più cattiva. Rimetti then, e cancella invece la parola end sull’ultima riga di spawnBlock. Salva:

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

La riga 148 è la fine del file, appena dopo la sua ultima riga. Non c’è niente di sbagliato nella riga 148. Lua ha letto fino in fondo — <eof> è il modo in cui chiama la fine di un file — sempre aspettando un end che non è mai arrivato, e a quel punto aveva inghiottito ogni funzione dopo spawnBlock come se ne facesse parte.

La metà utile di quel messaggio è (to close 'function' at line 58), che è dove comincia spawnBlock. Quando un messaggio punta alla fine del file, credi a quello che dice tra parentesi, non al numero di riga. È anche per questo che il rientro conta così tanto: un end mancante è quasi invisibile in un elenco di righe, ed evidente nel momento in cui tutto ciò che sta sotto è rientrato di un passo di troppo.

Altri due che vale la pena saper riconoscere, perché li incontrerai entrambi questa settimana:

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

Una virgoletta che hai aperto e mai chiuso, che hai incontrato nella prima lezione.

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

Questo è if state = "playing" then. Un = imposta una variabile, due == fanno una domanda, e Lua non ti lascia impostare una variabile dentro un if. Sembra una lamentela strana, e vuol dire sempre la stessa cosa.

Attempt to index a nil value

Questo è quello che vedrai più spesso, e di gran lunga.

Vai in spawnBlock e scrivi male block nella prima riga che lo usa, così che diventi blocl.x = math.random(0, screenWidth - BLOCK_SIZE). Salva, premi la barra spaziatrice:

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'

Indicizzare è ciò che fa il punto. blocl.x vuol dire «entra nella cosa chiamata blocl e trovaci la x». Puoi farlo solo con una tabella.

Nil è il nome che Lua dà a un nome senza niente dietro. Non l’hai visto molto, perché sei stato attento a dare un valore a tutto, ma ogni nome che non hai mai usato è già nil, e scrivere male un nome ne inventa uno nuovo di zecca.

Quindi il messaggio intero dice: hai usato un punto su qualcosa che non esiste.

La parte tra parentesi è il regalo. global 'blocl' è il nome esatto della cosa che era vuota. Cercalo nel tuo file. Se compare una volta sola, è un errore di battitura, e l’hai trovato in dieci secondi.

La parola prima del nome ti dice dove l’ha cercato Lua:

  • global — un nome senza un local davanti, da nessuna parte.

  • local — un nome che hai dichiarato con local nella funzione in cui ti trovi.

  • field — un nome dopo un punto, come la y in block.y.

  • upvalue — una variabile local di un livello più esterno che questa funzione riesce a vedere, ed è ciò che sono tutte le variabili di dodge.singe, visto che sono dichiarate in cima al file e usate dentro le funzioni.

field è l’altra causa comune, e non è affatto un errore di battitura. Se hai scritto block.hit.when e non hai mai impostato block.hit, ottieni attempt to index a nil value (field 'hit'). Il punto che fallisce è il secondo. Lua ti dice quale, nominandolo.

Attempt to call a nil value

Rimetti a posto blocl. Ora scrivi male una funzione del motore: in drawGame, cambia overlayPrint in overlayPirnt. Salva:

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'

Stesso nil, crimine diverso. Chiamare è ciò che fanno le parentesi, e puoi farlo solo con una funzione. Non esiste nessuna funzione chiamata overlayPirnt, quindi overlayPirnt è nil, quindi le parentesi non hanno niente da chiamare.

Succede per quattro motivi, in ordine di frequenza:

  1. Hai scritto male una delle tue funzioni.

  2. Hai scritto male una di quelle di Singe. Niente nel motore controlla come scrivi quando il file viene caricato, quindi un nome del motore scritto male è solo un altro nome che si trova a essere vuoto, e non ti costa niente finché la riga non viene eseguita.

  3. La funzione non esiste proprio in Singe — era un’ipotesi ragionevole, e le ipotesi ragionevoli sono sbagliate più o meno una volta su due. L’elenco delle funzioni del Riferimento è l’unico modo per esserne sicuro.

  4. L’hai resa local e l’hai chiamata da un punto che sta sopra quello in cui è dichiarata. È esattamente per questo che le funzioni di dodge.singe sono globali.

C’è una versione molto peggiore di questo errore, e l’hai incontrata nella prima lezione senza saperlo: scrivi male il nome di una callback e non ottieni nessun messaggio. onOverlayUpdated non è un errore. È una funzione perfettamente valida di cui Singe non ha mai sentito parlare e che non chiamerà mai, quindi lo schermo resta nero e niente si lamenta. Quando un’intera funzionalità non fa assolutamente niente, sospetta del nome.

Attempt to perform arithmetic on a nil value

Rimetti a posto overlayPrint. In updatePlaying, scrivi male blockSpeed nella riga della caduta, così che diventi 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'

L’aritmetica è +, -, * e /. Non puoi sommare il niente a un numero. Di nuovo le parentesi nominano la cosa vuota, e di nuovo la causa più comune è un errore di battitura — ma questo ha una seconda causa che vale la pena conoscere, perché è più difficile da vedere.

Una variabile a cui non hai mai dato un numero è nil, non zero. Se aggiungi al gioco un punteggio record e scrivi local hiScore in cima senza = 0, contiene nil finché qualcosa non la imposta, e il primo hiScore + score ferma il gioco. Lua non fa partire i numeri da zero per te. Sei tu a farli partire da zero.

Due parenti stretti, con la stessa causa e la stessa cura:

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

.. che attacca una stringa a qualcosa che non c’è. Questo lo vedrai ogni volta che stampi un punteggio che hai dimenticato di impostare — qui, hiScore aggiunto alla riga del punteggio in drawGame, che ora è la riga 37 visto che sopra c’è local hiScore.

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

È if score > hiScore then, messo sotto state = "over" per tenere il punteggio migliore quando una partita finisce, senza niente in hiScore. Nota che questo messaggio non nomina niente tra parentesi. Quando Lua non sa dirti quale lato era vuoto, la sezione dopo la prossima ti spiega come scoprirlo.

Un argomento del tipo sbagliato

Finora tutti i messaggi venivano da Lua. Questo viene da Singe, e ha un aspetto completamente diverso, quindi vale la pena incontrarlo apposta.

Supponi di voler vedere che cosa c’è in blocks, e di provare a stamparlo. Aggiungi questa riga a drawGame, sotto il punteggio:

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

Niente nome del file, niente traceback, nessun attempt to qualcosa. Una lamentela del motore comincia con il numero di riga, poi il nome della funzione che si è rifiutata, poi che cosa voleva. Qui a overlayPrint è stata passata una tabella dove serve del testo, e si è fermata invece di disegnare qualcosa senza senso.

Il messaggio fratello conta invece di controllare:

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

È un overlayBox a cui manca un angolo. Lo strano argument(s) è del motore, non un tuo errore di battitura.

Quando ottieni uno di questi, la risposta è la voce di quella funzione nel Riferimento, e ti ci vorrà un minuto. Ogni voce elenca gli argomenti in ordine, con che cosa deve essere ciascuno. Singe li controlla perché l’alternativa è un gioco che gira per dieci minuti e poi disegna spazzatura.

Scoprire che cosa c’è davvero lì dentro

Metà del debug non è affatto leggere errori. È il caso in cui niente va in crash e niente funziona: blocchi che non compaiono mai, un giocatore che non si muove, un punteggio fermo a zero. Per questo devi vedere dentro il gioco mentre gira, e ci sono due modi.

Il primo è debugPrint, che scrive una riga nel terminale da cui hai avviato Singe. Prendi la riga che non riesci a capire e mettine una sopra:

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

Ora stai guardando quello che c’è davvero invece di quello che sei sicuro che ci sia, ed è in quella distanza che vivono i bug. Stampa playerX allo stesso modo e vedrai la verità anche su di lui: viene stampato come 160.0, non 160, perché in Lua dividere con / dà sempre un numero con una parte decimale, anche quando la parte decimale è zero.

Due cose ti morderanno. La prima è che debugPrint vuole per forza del testo o un numero; dagli qualsiasi altra cosa e ferma il gioco come ha fatto overlayPrint. debugPrint(blocks) non ti mostrerà un elenco, e debugPrint("left " .. goingLeft) in cima a updatePlaying non ti mostrerà nemmeno un true o un false:

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

La soluzione è tostring. Prende qualsiasi cosa e te ne dà una versione in testo, quindi tostring(goingLeft) è "true" o "false" e la riga funziona.

La seconda è che onOverlayUpdate gira sessanta volte al secondo, quindi un debugPrint lì dentro stampa sessanta righe al secondo e non riesci a leggerne nessuna. Lo dice anche il Riferimento, nella sua voce: la chiamata costa poco, ma niente ne limita la frequenza.

Prima di tutto, metti un interruttore davanti a ogni riga di debug che aggiungi, così puoi spegnere il rumore senza doverle andare a cercare di nuovo:

local DEBUG = true


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

Ogni debugLog del gioco obbedisce a quell’unico true. Cambialo in false e il gioco tace; rimettilo com’era e torna tutto.

Poi stampa quando qualcosa succede, invece che a ogni fotogramma:

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

Oppure stampa a tempo, con un conto alla rovescia fatto esattamente come quello che fa comparire i blocchi:

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

La cartella learn ha tutto quanto in 08-when-it-goes-wrong.singe: è il gioco della settima lezione con un resoconto circa ogni due secondi, una riga quando vieni colpito e una riga quando la partita finisce.

Il secondo modo di vedere dentro è mettere le cose sullo schermo, che è meglio per tutto ciò che cambia a ogni fotogramma, perché sessanta righe al secondo in un terminale non servono a niente, ma un numero che scatta nell’angolo è facile da tenere d’occhio:

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

Tagliare il problema a metà

Quando non riesci a vedere quale di venti righe è sbagliata, smetti di guardare e comincia a togliere.

Metti due trattini all’inizio di una riga e Lua ignora tutto il resto. Quello è un commento, e di solito serve a lasciare appunti per te stesso, ma l’uso migliore è questo:

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

Commenta metà di drawGame ed eseguilo. Se il problema c’è ancora, sta nella metà che hai tenuto. Se è sparito, sta nella metà che hai tolto. Rimetti quella metà e taglia a metà lei. Venti righe richiedono cinque giri, e ogni giro è un salvataggio e un’occhiata.

Funziona anche su cose più grandi delle righe. Commenta il corpo di updatePlaying e i blocchi smettono di muoversi, il che ti dice se la cosa che stai inseguendo sta nel movimento o nel disegno. Commenta il ramo di collideRects e guarda se il gioco smette di andare in crash. Mentre fai questo non stai cercando di aggiustare niente. Stai cercando di scoprire dove non è.

Fare il giro più in fretta

Tutto questo dipende dal poter provare qualcosa in un paio di secondi, ed è a questo che serve -R. Lo usi dalla prima lezione; ecco che cosa fa davvero, e vale la pena saperlo ora che stai per appoggiarti a lui.

Singe tiene d’occhio ogni file di script che il tuo gioco ha caricato. Quando ne salvi uno, il gioco riparte dall’inizio: tutto ciò che lo script aveva creato viene buttato via e il tuo file viene eseguito da capo, nel tempo che serve a leggere il file invece che in quello che serve ad avviare il motore. F5 fa la stessa cosa a comando, senza salvare niente.

Un tasto che tieni premuto durante un ricaricamento viene ignorato finché non lo lasci, così il giocatore non scappa via da solo dopo un ricaricamento.

I due tipi di arresto qui si comportano in modo diverso, ed è utile sapere quale stai guardando senza leggere il messaggio. Uno script che non si compila viene stampato, e Singe sopravvive: la finestra resta aperta e vuota, il file resta sotto osservazione, e salvare la correzione riporta indietro il gioco. Un crash dentro una callback — tutti i messaggi attempt to e le lamentele del motore sugli argomenti — butta giù Singe, e lo riavvii a mano.

Leggere un traceback

Le righe sotto stack traceback: sono l’elenco delle funzioni che erano in corso quando tutto si è fermato, a partire dalla più interna. Ecco di nuovo quello di blocl:

	dodge/dodge.singe:60: in function 'spawnBlock'
	dodge/dodge.singe:92: in function 'updatePlaying'
	dodge/dodge.singe:136: in function 'onOverlayUpdate'

Leggilo dal basso verso l’alto ed è una frase. Singe ha chiamato onOverlayUpdate. Alla riga 136, onOverlayUpdate ha chiamato updatePlaying. Alla riga 92, updatePlaying ha chiamato spawnBlock. Alla riga 60, spawnBlock si è arresa.

La riga in cima è dove si è rotto. Le righe sotto sono come ci è arrivato, e sono ciò che ti serve quando la riga in cima sembra innocente. Una funzione che somma un numero a block.y non è sbagliata; una funzione che ha messo un blocco nell’elenco senza una y lo è. Solo la pista collega le due cose, e la pista ti viene stampata ogni singola volta.

L’abitudine

Tutto ciò che c’è qui sopra è tecnica. Questa è l’abitudine, e conta di più:

Cambia una cosa. Eseguilo. Guarda che cosa è successo.

Quando qualcosa non funziona, la tentazione è cambiare quattro cose insieme, perché una di loro sarà per forza quella giusta. Fallo e smette di funzionare in un modo nuovo, e ora non sai quale delle quattro è stata, o se due di loro si stanno annullando a vicenda. Hai reso il problema più grande e l’hai nascosto meglio.

Una modifica. Esegui. Guarda. Sembra più lento. È la cosa più veloce che ci sia, e ogni programmatore esperto che incontrerai lo fa, esattamente per il motivo che stai per scoprire.

Prova tu

  1. Conoscili tutti. Fai apposta in dodge.singe ciascuno dei cinque errori di questa lezione, uno alla volta, e leggi il messaggio prima di correggerlo. Non ne avrai mai più paura.

  2. Osserva chi crea i blocchi. Metti dentro spawnBlock un debugPrint che stampi la x del nuovo blocco. Gioca per trenta secondi, poi guarda i numeri. Sono sparsi su tutto lo schermo, o preferiscono un lato?

  3. Spegnilo. Cambia DEBUG in false nello script della lezione, e assicurati che non venga stampato niente e che il gioco non cambi.

  4. Un bug senza errore. In updatePlaying, cambia if spawnTimer ⇐ 0 then in if spawnTimer == 0 then, che sembra voler dire la stessa cosa. Eseguilo e comincia una partita. Non c’è nessun errore, niente va in crash, e non cade mai nemmeno un blocco, quindi non puoi neanche perdere. Metti un debugLog dentro spawnBlock, aggiungi spawnTimer alla prima riga che stampa debugReport e gioca di nuovo. Scopri da quello che dicono, e da quello che uno dei due non dice mai, perché == era la domanda sbagliata da fare.

  5. Rompi il nome di una callback. Rinomina onInputPressed in onInputPress ed eseguilo. Non viene stampato nessun errore, niente va in crash, il giocatore non si muove e la barra spaziatrice non fa partire una partita. Poi spiega a te stesso perché questo è l’errore più pericoloso di questa lezione.

Cosa hai imparato

  • Gli errori hanno un file, una riga e una lamentela. Leggili in quest’ordine.

  • Error running script vuol dire che non è stato eseguito niente; la forma con un traceback vuol dire che stava girando e si è fermato.

  • nil è un nome senza niente dietro, e sta dietro alla maggior parte dei messaggi di errore che vedrai.

  • La parola tra parentesi nomina la cosa vuota, e dice se era una globale, una locale, un campo o un upvalue.

  • Un end mancante viene segnalato alla fine del file, e le parentesi ti dicono dov’è davvero lo sbaglio.

  • Le lamentele del motore hanno un aspetto diverso: un numero di riga, il nome di una funzione e che cosa voleva invece.

  • debugPrint ti mostra che cosa contiene davvero una variabile. tostring rende stampabile qualsiasi cosa, e un interruttore come DEBUG spegne il rumore.

  • Commenta una metà con -- per scoprire in quale metà sta il problema.

  • Una callback scritta male non produce nessun errore, il che la rende peggiore di una che lo produce.

  • Cambia una cosa, eseguilo, guarda.

La prossima volta

Questa è la fine della prima parte. Sai scrivere un gioco, e ora sai anche aggiustarne uno, il che vuol dire che tutto ciò che viene da qui in poi è aggiunta, non fondamenta. La seconda parte comincia sostituendo quei riquadri colorati con delle vere immagini, e da lì il gioco che stai costruendo comincia ad assomigliare a un gioco a cui qualcun altro vorrebbe giocare.

Lezione 9: Immagini

La lezione finita

Tutto quello che hai disegnato finora l’hai disegnato con riquadri, linee e il testo semplice del motore. Era voluto: otto lezioni senza grafica volevano dire otto lezioni in cui niente poteva andare storto tranne il tuo programma. Ora i riquadri diventano un’astronave e qualche roccia.

Un’immagine che il motore disegna sull’overlay si chiama sprite. Questa lezione li carica, li disegna, li misura, li mette nell’ordine giusto e scorre un’immagine che contiene diversi fotogrammi di un’animazione. Alla fine, il gioco della settima lezione sembrerà un gioco.

Il kit di grafica

Non devi disegnare niente. Questo libro viene con una piccola cartella di grafica, e tutto ciò che c’è in questa lezione e nella prossima la usa.

Trova la cartella art che è arrivata con il libro e copia l’intera cartella nella cartella di questa lezione, accanto al tuo script. Dovresti ottenere questo:

singe/                 <- la tua cartella di lavoro
    Singe/
    data/
    rocks/
        rocks.singe
        art/
            spaceship.png
            asteroid.png
            bullet.png
            star.png
            walk.png
            shoot.wav
            boom.wav

La tua grafica va dentro la cartella del tuo gioco, e la cartella Singe del motore resta dov’è, fuori nella cartella di lavoro. Questo conta tra un momento, perché decide come indichi un file quando lo carichi.

La cartella Singe è quella che il motore ha estratto per te al tuo primissimo avvio, nella prima lezione. Vale la pena sapere che cosa contiene, perché anche quei file li puoi usare, e ogni lettore di questo libro li ha:

  • Singe/click.wav — un breve clic, che il menu del motore usa per la sua prova del suono.

  • Singe/FreeSansBold.ttf — un font TrueType, per la diciannovesima lezione.

  • Singe/menuIntro.flac — la musica che suona il menu del motore. La userai nella decima lezione.

  • Singe/menuBackground.mkv — un video, per la quattordicesima lezione.

  • Singe/DragonModel.glb e Singe/SingeText.glb — due modelli 3D, per la ventitreesima lezione.

  • Singe/missing.png — l’immagine che il motore disegna quando un gioco ne chiede una che non riesce a trovare.

Le immagini del kit sono piccole apposta. L’astronave è larga 32 pixel e alta 24, una roccia è 24 per 24, un colpo è 4 per 10 e una stella è 8 per 8. Sembra minuscolo finché non ti ricordi quanto è grande davvero lo schermo, che è la prossima cosa da chiarire.

Quanto è grande lo schermo

Senza un video da riprodurre, Singe dà al tuo gioco un canvas largo 720 pixel e alto 480, e la superficie su cui disegni — l'overlay — è la metà in ciascuna direzione: 360 per 240. Singe lo stira per riempire la finestra al posto tuo, quindi un’astronave di 32 pixel occupa circa un decimo della larghezza dello schermo, che è più o meno l’aspetto di un’astronave in un gioco da sala giochi.

Non scrivere mai 360 e 240 nel tuo programma. Chiedi:

local screenWidth  = overlayGetWidth()
local screenHeight = overlayGetHeight()

Quelle due riportano la dimensione dell’overlay, e un gioco che chiede è un gioco che funziona ancora quando qualcuno lo avvia a una dimensione diversa.

C’è una cosa che non conta in quei pixel: overlayPrint, della prima lezione, conta in celle di carattere. Ogni cella è larga 6 pixel e alta 13, quindi un overlay di 360 per 240 fa 60 colonne per 18 righe di testo. Gli sprite sono in pixel, overlayPrint è in celle, e confondere le due cose vale un pomeriggio di confusione, se glielo permetti.

Un’immagine sullo schermo

Comincia un nuovo file accanto alla tua cartella art e scrivici questo.

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

Avvialo. Una piccola astronave blu sta vicino al centro di uno schermo nero, con la punta verso l’alto.

Cos’è appena successo

Quattro cose nuove, una alla volta.

local ship = spriteLoad(DIR .. "art/spaceship.png")

spriteLoad legge un file di immagine dal disco, lo decodifica e tiene l’immagine in memoria. Quello che ti restituisce non è l’immagine. È un handle: un semplice numero, un biglietto d’ingresso, il modo del motore per dire «quella lì». Ridai quel numero al motore ogni volta che vuoi fare qualcosa con l’immagine, e non ti serve mai sapere che numero sia, né preoccupartene.

Stampalo, se vuoi — debugPrint(ship) dell’ottava lezione ti mostrerà un numero piccolo — ma il numero in sé non è affar tuo, e niente nel tuo programma dovrebbe mai dipendere da quale numero risulti. L’unica regola è che lo tieni da qualche parte dove puoi riprenderlo, che è esattamente ciò a cui serve una variabile.

DIR è nuovo anche lui, e risolve un problema creato dalla struttura che usi dalla prima lezione. Singe cerca i file a partire dalla cartella in cui ti trovavi quando l’hai avviato, non a partire dal tuo script. Tu lo avvii dalla cartella di lavoro, quindi un semplice art/spaceship.png manda il motore a cercare singe/art/spaceship.png, là fuori accanto alla cartella Singe. La tua grafica non è lì. Sta un livello più giù, in rocks/art/spaceship.png, con il tuo script.

DIR colma quel divario. È un pezzo di testo che contiene la cartella in cui si trova il tuo script, con la barra già in fondo, quindi DIR .. "art/spaceship.png" — che unisce due pezzi di testo con .., come fai dalla prima parte — indica l’immagine correttamente comunque sia stato avviato il gioco, e continua a indicarla correttamente quando sposti l’intera cartella da un’altra parte.

DIR è uno dei nomi che definisce Singe/Framework.singe, ed è a questo che serve la riga dofile in cima al tuo script. Hai incontrato quella riga, e ciò che contiene, nella settima lezione, e questo è il momento in cui si guadagna il posto: senza di lei non c’è DIR, e senza DIR il motore non trova la tua astronave.

Usa DIR per ogni file che il tuo gioco carica, da qui alla fine del libro.

    spriteDraw(ship, 160, 100)

Disegna lo sprite con quell’handle, in quella posizione. Come ogni chiamata di disegno, funziona solo dentro onOverlayUpdate.

La posizione è l'angolo in alto a sinistra dell’immagine, non il suo centro. Chiedi (160, 100) e il pixel più in alto e più a sinistra dell’astronave atterra lì, e il resto pende verso il basso e verso destra. Questo frega tutti una volta, di solito quando provano a centrare qualcosa e viene fuori spostato in basso a destra di metà della sua dimensione.

Se preferisci indicare il centro, dillo:

    spriteDraw(ship, 160, 100, true)

Un quarto argomento true vuol dire «tratta quel punto come il centro». Tutte e due le forme sono nella voce di spriteDraw nel Riferimento, insieme ad altre due che stirano l’immagine dentro un rettangolo.

function onShutdown()
    spriteUnload(ship)
end

onShutdown è una callback, come onOverlayUpdate e le due callback dei comandi della terza lezione. Il motore la chiama una volta, quando il tuo gioco sta finendo. È lì che restituisci quello che hai preso: spriteUnload libera l’immagine e butta via l’handle.

A rigore, potresti ometterla. Il motore libera tutto ciò che il tuo script ha caricato quando il gioco finisce, quindi uno spriteUnload dimenticato non è una perdita di memoria. Scrivila comunque. Costa una riga, dice che cosa possiede il tuo programma, e fra un minuto vedrai il caso in cui dimenticarsi di scaricare conta davvero.

Un avvertimento su quell’handle: una volta scaricato uno sprite, il numero è morto. Disegnare con quel numero non si limita a non disegnare niente: termina il tuo gioco con un errore.

La trasparenza, e perché è un PNG

L’astronave è un triangolo con due alette. Il file in cui vive è un rettangolo, 32 per 24, perché ogni file di immagine è un rettangolo. Quindi che fine hanno fatto gli angoli?

Sono trasparenti. Un PNG può dire, per ogni singolo pixel, quanto è solido, e le immagini del kit dicono «proprio non c’è» per ogni pixel fuori dalla forma. Singe lo rispetta, quindi lo sfondo nero si vede attraverso gli angoli e l’astronave ha un contorno invece di un riquadro intorno.

È per questo che il kit è in PNG e non in JPEG. Un JPEG non può proprio memorizzare la trasparenza — ti darebbe l’astronave in un riquadro grigio — e in più sbava i bordi netti, che è l’ultima cosa di cui ha bisogno la grafica piccola. Per la grafica di un gioco, PNG. Per una fotografia che riempie tutto lo schermo e non ha parti trasparenti, JPEG va bene ed è molto più piccolo. La voce di spriteLoad nel Riferimento elenca tutti i formati che Singe sa leggere, e sono parecchi.

Provalo tu stesso: cambia il nero con qualcos’altro disegnando un riquadro dietro l’astronave prima di disegnare l’astronave. Gli angoli mostreranno qualunque cosa ci sia dietro, che è proprio il punto.

Non caricare mentre disegni

Ecco l’errore che questa sezione esiste per impedire. Sembra del tutto ragionevole:

function onOverlayUpdate()
    overlayClear()
    local ship = spriteLoad(DIR .. "art/spaceship.png")
    spriteDraw(ship, 160, 100)
    return OVERLAY_UPDATED
end

Eseguilo e funziona. Disegna l’astronave. Niente si lamenta. Non avresti nessun motivo di pensare che qualcosa non vada.

onOverlayUpdate gira circa sessanta volte al secondo. Sono sessanta copie nuove dell’astronave caricate in memoria ogni secondo, tremilaseicento al minuto, e nessuna viene mai scaricata. Il gioco gira benissimo per due minuti, poi rallenta, poi la macchina resta senza memoria e il gioco muore. Peggio ancora, muore durante la demo e non mentre lo stavi provando.

La regola: carica una volta, disegna molte volte. Caricare è lento e occupa memoria. Disegnare è veloce e non ne occupa. Quindi spriteLoad va in cima al tuo file, fuori da ogni funzione, dove viene eseguito una volta sola all’avvio dello script.

Non riguarda solo gli sprite. Ogni somethingLoad del motore funziona così — i suoni nella decima lezione, i font nella diciannovesima, i modelli nella ventitreesima. Se ti ritrovi a scrivere Load dentro una funzione che gira a ogni fotogramma, fermati e spostalo fuori.

Quanto è grande?

Sai che l’astronave è 32 per 24 perché te l’ha detto questo libro. Il tuo programma non lo sa, e non dovrebbe averne bisogno. Chiedi:

local shipWidth  = spriteGetWidth(ship)
local shipHeight = spriteGetHeight(ship)

Ora puoi tenere l’astronave sullo schermo, perché la posizione più a destra in cui può stare è screenWidth - shipWidth, e metterla al centro, perché il centro è (screenWidth - shipWidth) / 2. Nessuna delle due righe contiene un numero che dovrebbe cambiare se qualcuno ridisegnasse l’astronave un po' più grande.

Entrambe riportano la dimensione con cui lo sprite verrebbe disegnato in questo momento. Se mai scali o ruoti uno sprite, con spriteScale o spriteRotate, la risposta cambia di conseguenza. Di solito è quello che vuoi, e ti sorprenderà esattamente una volta.

L’ordine di disegno

Gli sprite non si fondono. Il successivo copre il precedente, pixel per pixel, esattamente come attaccare ritagli di carta su un muro. Quindi l’ordine delle tue chiamate spriteDraw è l’ordine dal fondo verso il davanti:

    drawStars()
    drawRocks()
    drawShots()
    spriteDraw(shipSprite, shipX, shipY)
    drawHud()

Le stelle sono le più lontane, quindi vanno giù per prime. L’astronave sta davanti a tutto nell’area di gioco. Il punteggio sta sopra tutto quanto. Inverti l’ordine e la tua astronave disegnata con tanta cura passa la partita a nascondersi dietro il campo stellare, e non c’è nessun errore a dirtelo — solo un’astronave che non vedi.

overlayClear viene ancora per primo, prima di tutto questo. Disegnare non sostituisce mai, copre soltanto, quindi il fotogramma comincia vuoto ogni volta.

Fotogrammi

Apri art/walk.png con un qualsiasi visualizzatore di immagini. Non è l’immagine di una persona. È l’immagine di quattro persone, una accanto all’altra: la stessa figura in quattro momenti di una camminata, ognuna larga 24 pixel, in una striscia larga 96.

Un’immagine che contiene diversi fotogrammi di un’animazione è uno sprite sheet, ed è così che viene conservata quasi tutta l’animazione 2D. Un file, un caricamento, un handle, e il gioco sceglie quale fetta disegnare.

Crea un secondo file, walk.singe, accanto al primo:

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

Avvialo con Singe rocks/walk.singe. Una piccola figura attraversa lo schermo camminando con passo regolare, sparisce oltre il bordo destro e rientra da sinistra.

spriteLoadFrames è spriteLoad con una cosa in più da dire: quanti fotogrammi ci sono nella striscia. Il conteggio viene per primo, prima del nome del file, che è il contrario di quello che pensano quasi tutti. Divide la larghezza dell’immagine per il conteggio e si ricorda le fette. Quattro fotogrammi in una striscia di 96 pixel vuol dire quattro fotogrammi larghi 24 pixel. Sbaglia il conteggio — diciamo 3 — e ottieni tre fette da 32 pixel, ognuna con dei pezzi di due figure, che è un modo memorabilmente buffo di scoprire che hai scritto il numero sbagliato.

spriteDrawFrame disegna una fetta. Prende l’handle, dove metterla e quale fotogramma, in quest’ordine, e i fotogrammi sono numerati a partire da 1: il fotogramma 1 è la figura più a sinistra e il fotogramma 4 quella più a destra.

Attento a quell'1. Altrove nella famiglia degli sprite — spriteSetFrame e spriteGetFrame — i fotogrammi sono numerati da 0. È un incidente della storia, sono tutte e due nel Riferimento, e questo libro usa spriteDrawFrame e conta da 1.

spriteFrameWidth riporta la larghezza di un fotogramma, qui 24, invece dei 96 dell’intera striscia. spriteFrameHeight è il suo compagno. Quando vuoi sapere quanto è larga una fetta di uno sprite sheet, sono queste le due a cui chiedere, e non spriteGetWidth.

Il numero del fotogramma è un numero in una variabile come qualsiasi altro, quindi la camminata è aritmetica:

    walkTick = walkTick + 1
    if walkTick >= 8 then
        walkTick  = 0
        walkFrame = walkFrame + 1
        if walkFrame > 4 then
            walkFrame = 1
        end
    end

Conta i fotogrammi che passano. Ogni otto, passa all’immagine successiva, e dopo la quarta immagine torna alla prima. Sessanta fotogrammi al secondo diviso otto fa tra i sette e gli otto passi al secondo, che per un ciclo di quattro fotogrammi è una camminata svelta ma credibile. Cambia l'8 e cambi la velocità: più grande è, più è lenta.

Ti chiederai perché stai contando, quando il motore ha spritePlay per far girare un’animazione al posto tuo. Ce l’ha, e per una GIF animata è la risposta giusta, perché una GIF porta dentro il file la tempistica di ciascuno dei suoi fotogrammi. Una semplice striscia come walk.png non porta nessuna tempistica, quindi il motore la fa girare alla massima velocità consentita — cento fotogrammi al secondo, venticinque cicli di camminata completi ogni secondo, una macchia indistinta. Quando i fotogrammi vengono da una striscia, conta tu.

Il gioco riceve la sua grafica

Ora metti tutto insieme. Il gioco della settima lezione guidava un riquadro lungo il fondo dello schermo e gli faceva cadere addosso altri riquadri. Ogni riquadro diventa un’immagine, e già che ci sei l’astronave riceve qualcosa con cui sparare.

Le modifiche sono tutte collegate fra loro, quindi ecco lo script intero. È più lungo di qualsiasi cosa tu abbia scritto, e non c’è niente dentro che tu non abbia già incontrato.

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()

Le frecce sinistra e destra guidano. La barra spaziatrice spara. Quando le rocce ti hanno tolto l’ultima vita, 1 comincia una nuova partita.

Alcune cose lì dentro meritano di essere indicate.

Le quattro chiamate spriteLoad e le otto misure stanno in cima, fuori da ogni funzione, quindi avvengono una volta sola. Tutto ciò che viene dopo è scritto in termini di screenWidth, shipWidth e compagnia, e in tutto il codice di gioco non c’è un solo numero di pixel scritto a mano.

Le funzioni sono in ordine alfabetico, un’abitudine che vale la pena prendere adesso. A Lua non importa minimamente — è per te, fra sei mesi, quando cercherai updateShots in un file con dentro quaranta funzioni.

Le ultime due cose nel file non sono affatto funzioni. Sono semplici istruzioni in fondo allo script: costruisci il campo stellare, poi chiama startGame per preparare le rocce e azzerare il punteggio. Vengono eseguite una volta, in ordine, mentre lo script si carica, e devono venire dopo le funzioni che usano.

overlapping sono i quattro confronti che, come diceva la settima lezione, potevi scrivere da te invece di chiamare collideRects, messi per esteso in una funzione con gli stessi otto argomenti. Due rettangoli non si toccano se uno dei due sta completamente a sinistra, a destra, sopra o sotto l’altro; se nessuna di queste quattro cose è vera, si sovrappongono. L’undicesima lezione la sostituisce con qualcosa che fornisce il motore, e spiega perché il rettangolo è la forma sbagliata per un’astronave.

Un’ultima nota per quando leggerai il codice Singe di altre persone. Ogni chiamata agli sprite in questo libro prende l’handle per primo. Singe 2.10 lo metteva per ultimo, e un gioco può chiedere al motore di continuare a fare così, quindi il codice che trovi online potrebbe essere spriteDraw(x, y, ship). Non copiarlo. L’handle per primo è l’ordine attuale, e quello documentato dal Riferimento.

Prova tu

  1. Centra l’astronave sulla sua posizione. Aggiungi true come quarto argomento allo spriteDraw dell’astronave. Guarda dove salta l’astronave, e dalla distanza di cui si è spostata deduci che cosa ha fatto davvero il quarto argomento.

  2. Più rocce. Cambia ROCK_COUNT in 20. Poi in 200. Da qualche parte tra quei due valori il gioco smette di essere giocabile, e da qualche parte molto più in là il gioco comincia a rallentare. Trovali tutti e due.

  3. Fai crescere l’astronave. Aggiungi spriteScale(shipSprite, 2) proprio in fondo al file, sulla riga sopra startGame(). Avvialo e guida contro il bordo destro: l’astronave è grande il doppio ma si ferma ancora dove si fermava quella piccola, e sporge oltre il bordo destro e oltre il fondo. Scopri perché, poi sposta quell’unica riga sopra le chiamate spriteGetWidth e guarda le cose sistemarsi. La voce di spriteScale nel Riferimento spiega che cosa fa la scalatura alle misure.

  4. Metti dentro chi cammina. Carica walk.png nel gioco, e disegna la figura che cammina lungo la parte alta dello schermo come scenografia. Ti servirà il conteggio dei fotogrammi dello script della camminata, e dovrai decidere in che punto di onOverlayUpdate va il disegno — davanti alle stelle, dietro le rocce.

  5. Scarica qualcosa che stai ancora usando. Aggiungi spriteUnload(starSprite) in fondo al file, dopo startGame(), ed eseguilo. Leggi che cosa ottieni.

Rompilo apposta

Le maiuscole contano, ed è con la grafica che mordono più forte. Cambia il caricamento dell’astronave perché usi una S maiuscola:

local shipSprite = spriteLoad(DIR .. "art/Spaceship.png")

Il gioco si rifiuta di partire:

10:spriteLoad:  Couldn't open rocks/art/Spaceship.png: No such file or directory

Leggilo come l’errore della prima lezione, ma nota che la forma è un po' diversa. 10 è la riga. spriteLoad è la funzione del motore che si è arresa, invece del nome di un file — quando la lamentela viene da Singe invece che da Lua, ottieni questo. Poi il motivo, che qui è formulato dal tuo sistema operativo e cambierà un po' da macchina a macchina.

No such file or directory è il computer che è preciso, non scortese. Non esiste davvero nessun file chiamato Spaceship.png; ce n’è uno chiamato spaceship.png, e per una macchina Linux sono due nomi diversi. Su Windows, e sulla maggior parte dei Mac, avrebbe funzionato, il che è peggio, perché vuol dire che il bug viaggia fino alla macchina di qualcun altro e compare lì per la prima volta.

L’altra metà di questo errore che incontrerai è la cartella. Se hai messo il kit di grafica nel posto sbagliato, o hai avviato Singe dalla cartella sbagliata, il messaggio è esattamente lo stesso e la correzione no. Il percorso nel messaggio aiuta: è il nome completo che Singe ha provato, contato dalla cartella da cui l’hai avviato, e il rocks/ davanti è la parte che ha aggiunto DIR. Controlla tre cose, in quest’ordine: se il file si chiama esattamente come l’hai scritto, se sta nella cartella art e se quella cartella art sta accanto al tuo script.

Cosa hai imparato

  • Un’immagine disegnata sull’overlay è uno sprite, e si carica con spriteLoad.

  • spriteLoad restituisce un handle: un numero che per il motore vuol dire «quell’immagine», e che tieni in una variabile.

  • DIR è la cartella in cui si trova il tuo script, e ogni file che il tuo gioco carica andrebbe indicato a partire da lì.

  • spriteDraw(handle, x, y) lo disegna, dal suo angolo in alto a sinistra, e solo dentro onOverlayUpdate. Un quarto argomento true indica invece il centro.

  • Carica una volta, in cima al file. Caricare dentro onOverlayUpdate si mangia la memoria finché il gioco muore.

  • spriteUnload restituisce un’immagine, di solito da onShutdown, e dopo l’handle è morto.

  • Il PNG porta con sé la trasparenza, ed è per questo che gli angoli dell’astronave non sono riquadri neri.

  • spriteGetWidth e spriteGetHeight misurano uno sprite come verrebbe disegnato ora, così non devi mai scrivere la sua dimensione nel programma.

  • Gli sprite si coprono a vicenda. L’ordine in cui disegni va dal fondo verso il davanti.

  • spriteLoadFrames(count, file) taglia una striscia in fotogrammi, e spriteDrawFrame(handle, x, y, frame) ne disegna uno, contando da 1.

La prossima volta

Il gioco ha l’aspetto giusto e non ha nessun suono. Nella decima lezione i colpi ricevono un rumore, le rocce un’esplosione, e sotto a tutto suona qualcosa — e incontri la tua quinta callback, quella che il motore usa per dirti che un suono è finito.

Lezione 10: Suono

La lezione finita

Un gioco senza suono sembra rotto, in un modo su cui è difficile mettere il dito. I colpi partono e non succede niente. Le rocce si spezzano e non succede niente. Metti un rumore di mezzo secondo su ognuna di queste cose e lo stesso gioco all’improvviso sembra fatto di qualcosa.

Questa lezione dà al tuo gioco uno sparo, un’esplosione e una musica sotto. Strada facendo ti presenta la tua quinta callback: quella che il motore usa per dirti che un suono ha finito di suonare.

Un solo rumore

Il kit di grafica che hai copiato nella nona lezione contiene due suoni, shoot.wav e boom.wav, e dei due l’esplosione è quello che si sente meglio. Crea un nuovo file accanto alla tua cartella art e scrivi questo.

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

Eseguilo e premi la barra spaziatrice tre o quattro volte, in fretta. I botti si ammucchiano uno sull’altro invece di interrompersi a vicenda.

Tenere premuta la barra spaziatrice ti dà esattamente un botto, non una raffica. È lo stesso comportamento che hai incontrato nella terza lezione: un tasto tenuto premuto è una sola pressione, segnalata una volta, e il motore butta via le ripetizioni che manda la tastiera. È per questo che per sterzare servono onInputReleased e una variabile, invece di contare le pressioni.

Cos’è appena successo

La forma è la stessa della nona lezione: carica una volta in cima, usa l’handle, restituiscilo alla fine.

local boom = soundLoad(DIR .. "art/boom.wav")

soundLoad legge un file audio e lo tiene in memoria, e ti restituisce un handle — la stessa idea dell’handle di uno sprite, un numero che per il motore vuol dire «quella clip». DIR c’è per lo stesso motivo per cui c’era nella nona lezione: il suono sta nella cartella del tuo gioco, e il gioco deve riuscire a trovarlo da qualunque posto sia stato avviato Singe.

Tutto quello che la nona lezione diceva sul caricamento vale qui parola per parola. Carica in cima al file, una volta. Un soundLoad dentro onOverlayUpdate carica la clip sessanta volte al secondo e non ne restituisce mai nessuna, e qualche minuto dopo il gioco ne muore.

        soundPlay(boom)

Riproducila. Riprodurre un effetto sonoro è tutto qui, e al resto pensa il motore: la clip parte, finisce, e non intralcia mai il tuo programma.

Ma anche soundPlay restituisce qualcosa, e non è lo stesso numero che gli hai dato. Cambia la riga e guarda:

        local channel = soundPlay(boom)
        debugPrint("clip " .. boom .. " on channel " .. channel)

Premi in fretta la barra spaziatrice una mezza dozzina di volte e osserva i due numeri. Il numero della clip non cambia mai. Il numero del canale sale — 0, poi 1, poi 2 — e una volta finiti i botti precedenti torna giù e ricomincia a riusare i numeri bassi.

Questa è l’unica cosa del suono che frega tutti, quindi vale la pena dirla lentamente. In gioco ci sono due tipi diversi di numero.

L'handle della clip che viene da soundLoad è la registrazione. Ce n’è uno solo. Non cambia, non sta né suonando né non suonando: è il suono che se ne sta in memoria in attesa di essere usato.

Il canale che viene da soundPlay è un’esecuzione di quella registrazione. Singe ne ha sedici, numerati da 0 a 15, e ogni suono che si sente in questo momento ne usa uno. Ecco perché i botti si sovrappongono: la seconda pressione non ha interrotto la prima, ha avviato una seconda esecuzione sul canale libero successivo.

Tutto ciò che agisce su un suono che senti prende un canale: soundStop, soundIsPlaying, soundPause, soundResume. Tutto ciò che agisce sulla registrazione prende l’handle: soundPlay e soundUnload. Passa l’uno dove va l’altro e non sempre otterrai un errore, perché 3 è un numero di canale valido e anche un handle di clip perfettamente buono — otterrai silenzio, o il suono sbagliato che si ferma, che è molto più difficile da trovare.

Sedici sono tanti, ma non sono infiniti. Quando tutti i canali sono occupati non suona niente, e soundPlay restituisce -1 invece di un numero di canale. Un gioco che fa partire moltissimi suoni insieme dovrebbe aspettarselo, e tra un minuto ne scriverai uno.

Volume

Ci sono tre volumi, e si moltiplicano tra loro.

Il volume generale degli effetti copre tutto. soundGetVolume lo legge e soundSetVolume lo imposta, su una scala da 0 a 63.

    soundSetVolume(40)

Resisti. Quel numero è del giocatore, non tuo: parte da quello che ha chiesto quando ha avviato il gioco, e un gioco che lo sovrascrive è un gioco troppo forte nella stanza silenziosa di qualcuno. Cambia il volume generale solo quando te lo chiede il giocatore, da una schermata delle opzioni. soundGetVolume c’è perché una schermata delle opzioni possa mostrare quanto vale adesso invece di tirare a indovinare.

Quello che dovresti usare è il volume del canale, che sta sotto quello generale. Dai a soundPlay un terzo argomento e questa singola esecuzione suona più piano:

    soundPlay(shootClip, 0, 35)

Lo 0 in mezzo è quante volte ripetere, e devi darlo perché il volume viene dopo. 0 vuol dire suonala una volta. -1 vuol dire ripetila finché qualcosa non la ferma, ed è così che faresti il rombo di un motore o il vento. La voce del Riferimento per soundPlay elenca tutti e tre gli argomenti.

Il terzo volume è la distanza, per i suoni collocati in un mondo 3D. Quello è per la quarta parte, quando il gioco passa alle tre dimensioni.

La musica ha un volume tutto suo, ed è su una scala diversa. Ne riparliamo tra un momento.

Fermare, e non fermare

soundStop prende un canale e lo interrompe lì dov’è:

    soundStop(engineChannel)
    engineChannel = -1

Nota la seconda riga. Appena un canale si ferma, il motore è libero di dare quello stesso numero al soundPlay successivo, quindi un numero di canale che tieni ancora potrebbe ora appartenere a un suono completamente diverso. Buttalo via nel momento stesso in cui lo fermi. -1 è la cosa utile da metterci, perché è lo stesso valore che soundPlay ti dà quando non è riuscito a suonare affatto, quindi un solo controllo copre tutti e due i casi: if channel >= 0 then.

soundStop è per un suono che adesso è sbagliato — il rumore del motore quando il motore muore, l’allarme quando qualcuno ha risposto all’allarme. È lo strumento sbagliato per un effetto breve. Un’esplosione di mezzo secondo troncata dopo un decimo di secondo sembra un errore, perché lo è.

Quindi la maggior parte delle volte non fare proprio niente. Lascialo finire. Un effetto sonoro che avvii e a cui non pensi più finisce da solo e libera il suo canale da solo, che è esattamente quello che vuoi.

Questo vale anche alla fine. soundUnload non interrompe una clip che sta ancora suonando: il motore tiene vivo l’audio finché non si è fermato l’ultimo canale che lo usa. Puoi scaricare in onShutdown senza preoccuparti di aver zittito qualcosa.

soundIsPlaying(channel) risponde se un canale sta facendo rumore in questo momento. Il suo uso principale non è la curiosità ma la moderazione: un allarme che deve suonare una volta, e non ripartire ogni volta che il gioco si accorge che il pericolo è ancora lì.

function raiseAlarm()
    if alarmChannel < 0 or not soundIsPlaying(alarmChannel) then
        alarmChannel = soundPlay(alarmClip)
    end
end

Leggi la condizione ad alta voce: suona l’allarme se non c’è un canale dell’allarme, o se quello che hai si è fermato. Altrimenti lascialo stare.

Il suono che balbetta

Ecco l’errore. Lo scrivono tutti, di solito entro una settimana da quando scoprono il suono.

Supponi di volere che la nave continui a sparare finché il pulsante resta premuto, invece di sparare una volta per pressione. Lo faresti come sterzi: una variabile firing messa a true in onInputPressed e di nuovo a false in onInputReleased, e il colpo creato in onOverlayUpdate finché è vera. È una cosa perfettamente sensata da volere, e il rumore sembra stare proprio lì, insieme al colpo:

function onOverlayUpdate()
    if firing then
        shots[#shots + 1] = { x = shipX, y = shipY }
        soundPlay(shootClip)
    end
    ...

Quello che esce non è uno sparo. È un ronzio gracchiante, o un tono duro e piatto, o un suono come di una piccola macchina che si rompe.

onOverlayUpdate viene eseguita circa sessanta volte al secondo. Tieni premuto il pulsante per un secondo e avrai chiesto sessanta esecuzioni di una clip che dura circa un quinto di secondo, ognuna che parte sopra la precedente. In ogni momento ne stanno suonando circa undici, ognuna un fotogramma dietro quella prima, e quello che senti sono sessanta copie dello stesso attacco ammucchiate l’una sull’altra.

La soluzione non è un suono più furbo. È riprodurre il suono dove avviene l'evento invece che dove lo stato è vero:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        soundPlay(shootClip, 0, 35)
    end
end

onInputPressed avviene una volta, quando il pulsante va giù. Una pressione, un colpo, un rumore.

Se vuoi davvero il fuoco continuo, la risposta è la stessa in un’altra forma: fai diventare un evento lo sparo stesso. Conta i fotogrammi, esattamente come li contava il ciclo della camminata nella nona lezione, e crea un colpo solo ogni otto fotogrammi. Il rumore va con il colpo, quindi suona sette o otto volte al secondo invece di sessanta, e quella è una mitragliatrice e non un gracchiare.

Questa è la regola, e vale la pena portarsela via da questa lezione: i suoni vanno con gli eventi, non con le condizioni. Una pressione, un colpo a segno, una morte, un oggetto raccolto — ognuna di queste cose avviene una volta e merita un suono. «Il pulsante è premuto» e «la nave si sta muovendo» non sono eventi; sono veri per centinaia di fotogrammi di fila, e qualunque cosa riproduci a partire da loro viene riprodotta centinaia di volte.

Quando un suono appartiene davvero a uno stato che dura — un motore, il vento, una sirena — avvialo una volta con -1 come numero di ripetizioni, tieni il canale e fermalo quando lo stato finisce.

La quinta callback

A volte ti serve proprio sapere quando un suono è finito. Scrivi questa funzione e il motore la chiamerà:

function onSoundCompleted(channel)
end

È la tua quinta callback, dopo onOverlayUpdate nella prima lezione, le due callback dei comandi nella terza e onShutdown nella nona, e funziona come tutte le altre: tu la scrivi, non la chiami mai, il motore chiama te. Il channel che ti passa è il canale che si è appena zittito — il numero che soundPlay ti ha dato quando l’hai avviato.

Scatta quando una clip finisce, quando termina l’ultima ripetizione di un loop, e quando fermi tu stesso un canale con soundStop. Quest’ultimo caso sorprende chi usa la callback per concatenare un suono al successivo: fermare un canale apposta lo segnala comunque come completato, e se non stai attento il suono successivo della catena parte lo stesso.

Il gioco sta per usarla per qualcosa che vale la pena fare. Quando se ne va l’ultima vita, suona l’esplosione della nave e il gioco resta immobile — niente GAME OVER, niente musica che sfuma — finché quell’esplosione non è davvero finita. Poi si ferma tutto insieme. Bastano poche righe, ed è la differenza tra un finale e un taglio.

La musica non è un effetto sonoro

Potresti caricare un motivo di tre minuti con soundLoad e riprodurlo con soundPlay. Non farlo. La musica ha una famiglia di chiamate tutta sua, per motivi che contano:

  • La musica ha un volume suo, separato da quello degli effetti, così un giocatore può abbassare la musica e sentire ancora i colpi.

  • Non c’è il limite dei sedici canali e non c’è un numero di canale. Un handle è un brano, e lo fermi, lo metti in pausa e lo riprendi tramite quell’handle.

  • musicStop può far sfumare un brano in un secondo o due invece di troncarlo.

Le chiamate rispecchiano quelle che conosci già:

local theme = musicLoad("Singe/menuIntro.flac")

musicSetVolume(50)
musicPlay(theme, -1)

musicLoad dà un handle. musicPlay lo avvia, con lo stesso numero di ripetizioni di soundPlay: -1 per sempre. musicStop(theme) lo termina, e musicStop(theme, 1500) impiega un secondo e mezzo a farlo sfumare. musicUnload lo restituisce.

Ora la trappola. Il volume della musica va da 0 a 128, non da 0 a 63. Gli effetti sonori usano una scala e la musica un’altra, lunga il doppio, per motivi storici che non ti consolano affatto quando la tua musica esce a metà del volume che volevi. Quando lavori con la musica, raddoppia il numero che avevi in mente per un effetto.

Il brano caricato lì è la musica del menu del motore stesso, presa dalla cartella Singe che il motore ha estratto nella tua cartella di lavoro al primo avvio. Dura dieci secondi ed è stato scritto per sfumare alla fine, quindi ripeterlo in loop suona esattamente come un loop di dieci secondi che continua a sfumare. Va bene per imparare le chiamate e non va bene per niente in un gioco finito, che porta con sé un brano più lungo tutto suo. Va bene uno qualunque dei formati soliti: la sezione Musica del Riferimento li elenca, e Ogg Vorbis o MP3 sono le scelte sensate, perché qualche minuto di musica in WAV è un file enorme.

Il gioco ha una colonna sonora

Apri il gioco della nona lezione. Tutto quello che c’è qui gli si aggiunge; non si toglie niente.

Quattro cose da caricare, in cima, insieme agli sprite:

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")

I primi due hanno DIR e gli ultimi due no, ed è voluto. DIR vuol dire la cartella del tuo gioco. Un nome che comincia con Singe/ vuol dire invece la cartella del motore, dovunque si trovi — ed è per questo che dofile("Singe/Framework.singe") funziona dalla settima lezione anche lui senza DIR. I tuoi file hanno bisogno di DIR; quelli del motore mai.

Due nuove variabili, accanto alle altre:

local dying        = false
local deathChannel = -1

dying è il momento tra la perdita dell’ultima vita e la fine della partita: l’esplosione si sente ancora, e sullo schermo non si muove niente.

Il colpo prende il suo rumore in onInputPressed, proprio dove viene creato il colpo stesso, e la ripartenza prende un clic, così premere 1 dà l’impressione di aver fatto qualcosa:

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 roccia colpita fa un botto, e così una roccia che colpisce te. In updateShots, accanto al punteggio:

                newRock(rock)
                score = score + HIT_SCORE
                gone  = true
                soundPlay(boomClip, 0, 45)

E in updateRocks, dove si perde la vita, la parte interessante:

        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

Quando se ne va l’ultima vita, l’esplosione suona e il suo canale viene ricordato. Il gioco ora è dying, cosa che ferma ogni movimento ma non dice ancora GAME OVER.

Quel if channel < 0 è il limite dei sedici canali, gestito. Se proprio in quell’istante tutti i canali fossero occupati, non ci sarebbero né un’esplosione né un canale da aspettare, e senza quelle due righe il gioco resterebbe in dying per sempre, ad aspettare un suono mai partito. Aspettare qualcosa che non può arrivare è uno dei modi più facili per bloccare un programma, e il controllo costa sempre meno del bug.

Ora la nuova callback, e la piccola funzione che condivide con quel controllo:

function endGame()
    dying        = false
    deathChannel = -1
    over         = true
    musicStop(theme, 1500)
end


function onSoundCompleted(channel)
    if channel == deathChannel then
        endGame()
    end
end

Il motore chiama onSoundCompleted per ogni canale che si ferma, quindi la prima cosa che fa è controllare se questo è il canale che le interessa. Tutto il resto — ogni colpo, ogni roccia — passa oltre e viene ignorato.

onOverlayUpdate deve restare immobile mentre l’esplosione va avanti, e basta una parola:

    if not over and not dying then
        updateShip()
        updateShots()
        updateRocks()
    end

startGame azzera le due nuove variabili e fa ripartire la musica da capo:

    dying        = false
    deathChannel = -1
    musicSetVolume(50)
    musicPlay(theme, -1)

E onShutdown restituisce quello che era stato caricato:

function onShutdown()
    spriteUnload(shipSprite)
    spriteUnload(rockSprite)
    spriteUnload(shotSprite)
    spriteUnload(starSprite)
    soundUnload(shootClip)
    soundUnload(boomClip)
    soundUnload(clickClip)
    musicUnload(theme)
end

Eseguilo. Spara alle rocce, fatti colpire tre volte e ascolta la fine: l’ultimo botto suona fino in fondo, e solo quando è finito la musica comincia a sfumare e compaiono le parole.

Lo script finito si trova nella cartella learn come 10-sound.singe, se vuoi fare un confronto.

Prova tu

  1. Rendi il colpo ancora più piano. Cambia il 35 nel soundPlay del colpo in 10, poi in 63. Trova il numero in cui sta sotto le esplosioni invece che sopra.

  2. Abbassa la musica senza toccare gli effetti. Cambia musicSetVolume(50) in musicSetVolume(15). Verifica che i botti siano forti esattamente quanto prima, che è tutto il motivo per cui la musica è un sistema a parte.

  3. Taglia il finale. In endGame, cambia musicStop(theme, 1500) in musicStop(theme). Ascolta entrambi i finali due volte. La differenza è un numero in un argomento, e non è una piccola differenza.

  4. Dai un motore alla nave. Avvia soundPlay(clickClip, -1, 12) in startGame, tieni il canale che ti dà in una variabile tutta sua e fermalo in endGame. Il clic dura un cinquantesimo di secondo, quindi in loop diventa un ronzio, che è quanto di più vicino a un motore offra questo kit. Poi togli di nuovo il soundStop, gioca tre partite di fila e ascolta che cosa hai costruito.

  5. Conta i canali. Stampa il numero del canale ogni volta che una roccia esplode. Poi aumenta ROCK_COUNT finché non ne esplodono parecchie insieme, e continua ad aumentarlo finché non vedi passare un -1.

Rompilo apposta

Ormai hai in testa due scale di volume, e prima o poi dalle dita esce quella sbagliata. Aggiungi questa riga da sola, subito sotto le quattro righe soundLoad e musicLoad:

soundSetVolume(100)

Il gioco si rifiuta di partire:

20:soundSetVolume:  Invalid sound volume value:  100

Il numero di riga che ottieni è la riga in cui l’hai scritta davvero, quindi il tuo potrebbe non essere 20. Poi la funzione che ha protestato, e il valore contro cui ha protestato. Il messaggio non ti dice qual è l’intervallo — a quello serve la voce di soundSetVolume nel Riferimento — ma ti dice il numero che non ha voluto accettare, e una volta che sai che gli effetti si fermano a 63 la correzione è un numero solo.

100 è un numero sospetto da trovare in un volume, e vale la pena sapere perché l’hai scritto. Quasi di sicuro hai pensato al volume come a una percentuale, perché ogni cursore del volume che tu abbia mai usato arriva a 100. Quello di Singe no. Gli effetti vanno da 0 a 63 e la musica da 0 a 128, e nessuno dei due è una percentuale di qualcosa.

Questa è la forma generale di un errore del motore, a differenza degli errori di Lua della prima lezione: un numero di riga, il nome della funzione del motore che hai chiamato e una lamentela sui valori che le hai passato. Quando ne vedi uno, la voce di quella funzione nel Riferimento è la prossima cosa da leggere.

Cosa hai imparato

  • soundLoad legge una clip e restituisce un handle. Carica una volta, in cima al file.

  • soundPlay avvia una clip e restituisce un canale, che è un tipo di numero diverso dall’handle.

  • Singe mescola sedici canali. Quando sono tutti occupati, soundPlay restituisce -1 e non suona niente.

  • I numeri dei canali vengono riusati. Dimenticane uno appena l’hai fermato.

  • Gli effetti brevi vanno lasciati finire da soli; soundStop è per i suoni che sono diventati sbagliati.

  • soundUnload non interrompe una clip che sta ancora suonando.

  • Riproduci un suono dove avviene l’evento, non dove una condizione è vera, altrimenti suona sessanta volte al secondo.

  • onSoundCompleted(channel) è una callback che il motore chiama ogni volta che un canale si zittisce, per qualunque motivo.

  • La musica è un sistema separato, con i suoi handle, il suo volume e nessun limite di canali.

  • Il volume degli effetti va da 0 a 63. Il volume della musica va da 0 a 128. Non sono percentuali.

La prossima volta

Le tue rocce vengono colpite quando i loro rettangoli si sovrappongono, ed è per questo che un colpo che passa per un angolo di cielo conta lo stesso. Nell’undicesima lezione ottieni i controlli di collisione del motore, impari che cos’è una hitbox e scopri perché il rettangolo attorno a una roccia rotonda ha la forma sbagliata.

Lezione 11: Colpire le cose

La lezione finita

Il tuo gioco della decima lezione funziona. I colpi spezzano le rocce, le rocce costano vite e le esplosioni arrivano nei punti giusti. Guardalo bene, però, e vedrai che bara, in tutte e due le direzioni. Una roccia che scivola oltre la punta di un’ala ti toglie una vita. Un colpo che attraversa il cielo vuoto accanto a una roccia la spezza lo stesso.

In un gioco due cose si toccano quando lo dicono i numeri. Nessuno guarda le immagini. Questa lezione mette d’accordo i numeri con quello che vede il giocatore: sostituisce il controllo che hai scritto a mano con quello del motore, rimpicciolisce i riquadri controllati perché calzino sulle cose che contengono, e ti dà un interruttore che ti mostra quei riquadri. L’immagine qui sopra è il gioco con quell’interruttore acceso.

Dove sei arrivato

Il gioco chiede «queste due cose si toccano?» esattamente in due punti, e tutti e due usano overlapping, la funzione che hai scritto nella nona lezione. Uno è in updateRocks, dove una roccia incontra la nave:

        if overlapping(shipX, shipY, shipWidth, shipHeight, rock.x, rock.y, rockWidth, rockHeight) then

L’altro è in updateShots, dove un colpo incontra una roccia:

            if not gone and overlapping(shot.x, shot.y, shotWidth, shotHeight, rock.x, rock.y, rockWidth, rockHeight) then

Tutto ciò che c’è in questa lezione cambia quelle due righe e aggiunge qualche piccola funzione che le alimenti. Il resto del gioco non cambia. Lo script completo e finito è in learn/11-hitting-things.singe, se ti perdi.

Rileggila ancora una volta

Questa parte l’ha già fatta la nona lezione: overlapping è la collisione tra rettangoli scritta a mano. Rileggila ancora una volta prima di buttarla via, perché è l’idea tutta intera:

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

Alla domanda «queste due cose si toccano?» è difficile rispondere direttamente e facile rispondere al contrario. Due rettangoli non si toccano quando uno dei due sta tutto a sinistra dell’altro, o tutto a destra, o tutto sopra, o tutto sotto. Non c’è un quinto modo di mancarsi. Se nessuno di questi quattro è vero, si toccano.

Ogni if è uno dei quattro modi di mancarsi. ax + aw è il bordo destro del primo rettangolo, quindi ax + aw ⇐ bx si legge «il primo finisce prima che cominci il secondo», che è quello che «tutto a sinistra» vuol dire in numeri. La stessa forma altre tre volte, per destra, sopra e sotto, con y e le altezze al posto di x e delle larghezze, e l’unica cosa che resta è true.

Questi sono gli otto numeri che servono a qualunque controllo di collisione: un angolo e una dimensione per ciascuna delle due cose. Tieni a mente la forma, perché stai per cancellarla.

Il motore ce l’ha già

Hai incontrato collideRects nella settima lezione, dove acchiappava i blocchi che cadevano in Dodge. La nona lezione ha scritto lo stesso controllo a mano perché tu potessi vederci dentro. Ci hai guardato dentro. Cancella overlapping e cambia le due righe di Dove sei arrivato perché chiamino invece il motore:

        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

Gli stessi otto numeri, nello stesso ordine: l’angolo e la dimensione del primo rettangolo, poi quelli del secondo. Eseguilo, e il gioco si comporta esattamente come prima, ed è questo il punto. L’unica differenza sta proprio sul bordo. Il tuo ⇐ diceva che due rettangoli che si incontrano lungo un bordo non si toccano. collideRects dice che si toccano, e un rettangolo senza larghezza o altezza non tocca proprio niente. Questi casi scomodi sono il punto in cui le versioni scritte a mano sbagliano in silenzio, e sono uno dei motivi per usare quella del motore.

collideRects fa parte di una famiglia di controlli di collisione, e la famiglia è una delle parti di quello che questo libro chiama il kit di gioco: una manciata di semplici funzioni per le cose che quasi ogni gioco un tempo si scriveva da sé. Controllare se due cose si toccano è una. Salvare un numero per la volta successiva è un’altra, ed è la dodicesima lezione. Aspettare un po', far scorrere un numero dolcemente da un valore a un altro e mostrare quanto è durato ogni fotogramma sono le altre. Il Riferimento dà a ogni parte una sezione tutta sua: Collisioni, Salvataggio, Timer, Tween e Statistiche.

I controlli di collisione sono i più semplici del mucchio: domande e basta, senza handle da conservare e niente da preparare o liberare. E nessuno di loro sposta qualcosa. collideRects ti dice che la nave e la roccia sono nello stesso posto; che cosa farne lo decidi tu, e tutto ciò che c’è di interessante in un gioco succede in quella decisione.

L’immagine non è la hitbox

La decima lezione ha promesso di spiegare perché il rettangolo attorno a una roccia rotonda ha la forma sbagliata. Anche il rettangolo attorno alla nave è sbagliato, e per lo stesso motivo.

Disegna su carta il rettangolo 32 per 24 della nave e colora la nave. È un triangolo con due pinne, quindi c’è cielo vuoto in tutti e due gli angoli in alto e tra le pinne. La roccia è rotonda, quindi c’è cielo vuoto in tutti e quattro gli angoli del suo quadrato. Una roccia che sfiora l’angolo in alto del rettangolo della nave non ha colpito la nave. È passata oltre l’ala, e un giocatore che ci perde una vita dirà che il gioco ha barato — e avrà ragione.

Quindi il riquadro che controlli non è l’immagine che disegni. È più piccolo, e sta dentro l’immagine. Aggiungi tre numeri alle costanti in cima al tuo file:

local SHIP_PAD_X  = 6
local SHIP_PAD_Y  = 5
local ROCK_PAD    = 4

Il margine è quanto più all’interno di ogni bordo comincia la cosa vera. Sei pixel tolti da ogni lato della nave e cinque da sopra e da sotto lasciano un riquadro di 20 per 14 in mezzo a un’immagine di 32 per 24, che è più o meno dove sta lo scafo. Quattro tolti da ogni lato della roccia lasciano 16 per 16, ed è quasi tutto roccia.

Tutti e due i riquadri sono un po' più piccoli delle cose che rappresentano, ed è voluto. Un riquadro appena troppo piccolo regala al giocatore dei passaggi per un pelo che sembrano bravura. Un riquadro appena troppo grande gli dà dei colpi subiti che sembrano un imbroglio. I giocatori perdonano i primi e mai i secondi.

Invece di scrivere quei calcoli a ogni controllo, scrivili una volta per ogni tipo di 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

Le dimensioni vengono da rockWidth, shipWidth e compagnia, le misure che la nona lezione ha preso dalle immagini, quindi nel codice di gioco non c’è ancora una sola dimensione in pixel scritta a mano. Ridisegna la nave più grande e il riquadro cresce con lei.

Ognuna di queste funzioni restituisce quattro numeri insieme, separati da virgole. Una funzione può restituire tutti i valori che vuole, e il modo per raccoglierli è un elenco di nomi a sinistra del segno =:

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

Ora il controllo in updateRocks si legge come la domanda che sta facendo:

        if shipHitsRock(rock) then

I calcoli del margine stanno esattamente in due posti, e i numeri che usano sono in cima al file, quindi puoi regolare quanto il gioco sembra onesto cambiando un numero invece di andare a caccia tra i tuoi controlli.

Metti le nuove funzioni al loro posto in ordine alfabetico, come chiedeva la nona lezione: rockBox dopo onSoundCompleted, poi shipBox e shipHitsRock.

Rispondere al fuoco

Il lato della nave è sistemato. L’altra collisione del gioco è quella con cui rispondi al fuoco: ogni colpo contro ogni roccia, in updateShots. Ha lo stesso problema che aveva la nave, in formato ridotto. Un colpo è un rettangolo di 4 per 10 controllato contro l’intero quadrato di 24 per 24 della roccia, quindi un colpo che passa soltanto per l’angolo vuoto accanto a una roccia la spezza lo stesso.

Potresti dare anche al colpo un riquadro con il suo margine. Prima però guarda i numeri. Togli un margine a un colpo largo quattro pixel e non resta quasi niente, e controllare un intero rettangolo per scoprire se un filo di luce ha toccato qualcosa è più macchinario di quanto la domanda meriti.

Un colpo è quasi un punto

Controlla invece la punta. collidePointRect chiede se un punto cade dentro un rettangolo — due numeri per il punto, poi l’angolo e la dimensione del rettangolo:

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 è la cima del colpo e shot.x + shotWidth / 2 è a metà della sua larghezza, quindi il punto controllato è il centro della punta del colpo. È lì che un giocatore pensa che sia un colpo. Dalla parte della roccia, la domanda usa lo stesso rockBox che usa la nave, quindi una roccia ha la stessa dimensione qualunque cosa la colpisca.

Va dopo shipHitsRock, e il controllo in updateShots diventa:

            if not gone and shotHitsRock(shot, rock) then

Decidere che cosa è successo

Nessuno dei controlli di collisione fa niente. Rispondono, e decide il tuo codice. Ecco i due punti che decidono, con dentro le loro nuove domande. Prima 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

E il ciclo dentro 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

Tutto quello che sta sotto le domande è esattamente ciò che ci ha lasciato la decima lezione. Una roccia che colpisce la nave fa un botto, torna in cima e costa una vita. Una roccia centrata da un colpo fa un botto, torna in cima e dà punti. Se ne va anche il colpo, e il not gone impedisce a un colpo solo di spezzare due rocce. Cambia una qualunque di queste cose e cambi il gioco, senza toccare un solo controllo di collisione, ed è per questo che le domande e le risposte stanno separate.

Eseguilo. Passa vicinissimo a una roccia e lasciale sfiorare una pinna: la vita resta tua. Spara appena accanto a una roccia e il colpo tira dritto. Spara nel mezzo di una roccia e si spezza, come sempre.

Vedere i riquadri

Le hitbox sono invisibili, e questo rende invisibile anche un errore al loro interno. Disegnale mentre ci lavori. Un’altra costante in cima:

local SHOW_BOXES  = false

Altre due funzioni, che vanno proprio in cima all’ordine alfabetico:

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

E in onOverlayUpdate, dopo che è stata disegnata la nave e prima che ci vada sopra il punteggio:

    spriteDraw(shipSprite, shipX, shipY)
    if SHOW_BOXES then
        drawBoxes()
    end
    drawHud()

Cambia SHOW_BOXES in true e sopra la grafica compaiono dei contorni verdi, come nell’immagine all’inizio di questa lezione. Rimettilo com’era quando hai finito. Un interruttore come questo, una parola in cima a un file che accende un’immagine di quello che il programma crede, vale più di tutte le occhiate del mondo.

Cos’è appena successo

function rockBox(rock)
    return rock.x + ROCK_PAD, rock.y + ROCK_PAD, rockWidth - ROCK_PAD * 2, rockHeight - ROCK_PAD * 2
end

Quattro valori da un solo return, separati da virgole. Lua ti restituisce volentieri tutti quelli che vuoi, e chi chiama decide quanti tenerne. Quando una chiamata come questa è l'ultima cosa dentro le parentesi di un’altra chiamata, passano tutti e quattro, ed è per questo che drawBox(rockBox(rock)) funziona e dà a drawBox i suoi quattro argomenti. In qualunque altro punto di un elenco di argomenti sopravvive solo il primo valore. Quella regola morde esattamente una volta, e morde alla fine di questa lezione.

    return collideRects(sx, sy, sw, sh, rx, ry, rw, rh)

collideRects vuole otto numeri: angolo e dimensione, angolo e dimensione. Restituisce true o false e non cambia niente. Siccome la risposta esce dritta dalla funzione con return, shipHitsRock(rock) si legge come una domanda dovunque venga usata.

    return collidePointRect(shot.x + shotWidth / 2, shot.y, rx, ry, rw, rh)

collidePointRect ne vuole sei: un punto, poi un rettangolo. Il bordo conta come interno, quindi un colpo esattamente sul confine colpisce. Usala ogni volta che uno dei due lati della domanda è abbastanza piccolo da rendere irrilevante la sua dimensione.

    colorForeground(0, 255, 0)
    overlayBox(x, y, x + width - 1, y + height - 1)

Vengono tutte e due dalla settima lezione. overlayBox prende due angoli, non un angolo e una dimensione — l’unico punto di questa lezione in cui i numeri cambiano forma — e il - 1 c’è perché entrambi gli angoli sono inclusi. colorForeground è un interruttore che resta dove l’hai messo, quindi tutto ciò che disegna drawBoxes viene verde. Gli sprite e overlayPrint lo ignorano, quindi il resto del gioco ha lo stesso aspetto di prima.

Il resto della famiglia

collideRects e collidePointRect bastano per la maggior parte dei giochi 2D. Le altre ci sono per le forme che i rettangoli descrivono male, e ognuna è lo stesso tipo di domanda semplice:

  • collideCircles e collidePointCircle, per qualunque cosa rotonda. Un cerchio è un centro e un raggio.

  • collideRectCircle, per una cosa rotonda contro una quadrata.

  • collidePointPolygon, per una forma con angoli tutti suoi — un drago, un continente, un pulsante dalla forma strana. Le passi un elenco piatto di numeri x, y, x, y.

  • collideSegments, per due segmenti che si incrociano.

A essere onesti, la tua roccia è rotonda, e i controlli con i cerchi le calzano meglio di qualunque riquadro. Il margine è la risposta economica, e basta per la maggior parte dei giochi, ed è per questo che viene prima. La risposta esatta è una delle cose da provare qui sotto.

collideSegments conta più di quanto sembri. Il tuo colpo si muove di sei pixel per fotogramma e le rocce hanno sedici pixel di hitbox, quindi un colpo non può superarne una senza essere controllato mentre ci sta dentro. Rendi il colpo abbastanza veloce — quaranta pixel per fotogramma — e salta da sotto una roccia a sopra, senza mai trovarsi nello stesso posto della roccia, e non colpisce mai niente. La cura è tracciare la linea da dove era il colpo a dove si trova adesso, e chiedere a collideSegments se quella linea attraversa un bordo. Alle cose lente non serve.

In Singe c’è una sola callback di collisione, onCollision, e non è per questo. Appartiene al motore fisico 3D: corpi con una massa, che cadono e rimbalzano uno contro l’altro in tre dimensioni, e ti dicono dove si sono toccati e con quanta forza. La incontrerai nella ventiquattresima lezione. Niente sull’overlay si segnala da solo, e niente ne ha bisogno. Le tue rocce sono in un elenco, sai quante sono, e chiedere costa poco.

E quando vuoi sapere non solo se due cose si sono incontrate ma dove dovrebbe finire quella che si muove — scivolando lungo un muro invece di fermarsi di colpo dentro — le chiamate collide di proposito non rispondono. Per esattamente quel lavoro con Singe viene fornita una libreria chiamata bump, e la sezione Librerie incluse del Riferimento spiega come raggiungerla.

Prova tu

  1. Togli il margine. Metti ROCK_PAD a 0 e gioca per un minuto. Poi mettilo a 8 e gioca di nuovo. In uno dei due casi sembra che il gioco ti stia mentendo.

  2. Guarda che cosa stai controllando. Metti SHOW_BOXES a true e osserva i contorni verdi mentre una roccia passa accanto alla nave. Ora metti SHIP_PAD_X a 16, gioca, e nota che niente riesce più a colpirti. Scopri perché dai calcoli in shipBox.

  3. Rendi il colpo troppo veloce. Metti SHOT_SPEED a 40. Conta quante rocce colpisci su dieci. Prima di rimetterlo com’era, ricava dai numeri perché succede.

  4. Usa tutto il colpo. Riscrivi shotHitsRock in modo che usi collideRects con il rettangolo intero del colpo invece di collidePointRect con la sua punta. Provale tutte e due e decidi quale preferisci; non c’è una risposta giusta, ed è una cosa che vale la pena sapere.

  5. Rendi rotonda la roccia. Dai alla roccia un cerchio invece di un riquadro: il suo centro è a rock.x + rockWidth / 2 in orizzontale e a rock.y + rockHeight / 2 in verticale, e un raggio di 10 va più o meno bene. Usa collideRectCircle per la nave e collidePointCircle per il colpo, e disegna il cerchio in drawBoxes con overlayCircle, che prende un centro e un raggio.

Rompilo apposta

I due riquadri sono già quattro valori ciascuno, quindi viene la tentazione di passarli direttamente e saltare gli otto nomi locali:

function shipHitsRock(rock)
    return collideRects(shipBox(), rockBox(rock))
end

Sembra giusto ed è sbagliato. Eseguilo e il gioco si ferma prima di disegnare qualunque cosa:

186:collideRects:  Expected 8 argument(s), got 5.

La riga è quella che hai appena scritto, quindi la tua potrebbe non essere la 186. Cinque, però. rockBox(rock) è l’ultima cosa tra le parentesi, quindi sono entrati tutti e quattro i suoi valori. shipBox() no, quindi è stato ridotto a uno. Uno più quattro fa cinque, e collideRects non tira a indovinare gli altri tre.

Questo errore viene dal motore e non da Lua, quindi ha la stessa forma di quelli della nona e della decima lezione: il numero davanti è la riga, poi il nome della funzione che si è rifiutata, poi la lamentela. Rimetti gli otto nomi locali.

Cosa hai imparato

  • La collisione è aritmetica sui rettangoli, e puoi scriverla da solo.

  • Due rettangoli si mancano esattamente in quattro modi; se nessuno di questi è vero, si colpiscono.

  • collideRects prende un angolo e una dimensione per ciascuno di due rettangoli e risponde true o false. Due bordi che si toccano appena contano come contatto.

  • I controlli di collisione fanno parte del kit di gioco: semplici funzioni, senza niente da preparare. Salvataggio, Timer, Tween e Statistiche sono il resto.

  • collidePointRect chiede se un punto sta dentro un rettangolo, che è la domanda giusta per qualunque cosa piccola.

  • Il riquadro che controlli è più piccolo dell’immagine che disegni, altrimenti il gioco sembra ingiusto.

  • Una funzione può restituire più valori, e solo l’ultima chiamata in un elenco di argomenti li passa tutti.

  • I controlli di collisione rispondono e basta. Quello che succede dopo è il tuo codice, e tenere separate le due cose ti permette di cambiarne una sola.

  • Disegnare le hitbox sullo schermo trasforma un bug invisibile in uno visibile.

  • onCollision è per i corpi della fisica 3D, non per gli sprite sull’overlay.

La prossima volta

Il gioco conta il tuo punteggio e ti toglie le vite, e nel momento in cui esci il punteggio migliore che qualcuno abbia mai fatto è sparito. Comincia nel mezzo dell’azione nell’istante in cui si carica. E tiene traccia di quello che sta facendo con due variabili vero-o-falso, over e dying, che è esattamente la trappola da cui ti metteva in guardia la settima lezione. La dodicesima lezione gli dà una schermata del titolo, una variabile sola al posto di quelle due e un punteggio record che domani c’è ancora.

Lezione 12: Punteggio, vite e game over

La lezione finita

Il tuo gioco tiene il punteggio, toglie le vite e dice GAME OVER. È quasi un gioco. Mancano ancora tre cose. Non ha una porta d’ingresso: è nel mezzo dell’azione nell’istante in cui si carica. Dimentica: esci, e il punteggio migliore che qualcuno abbia mai fatto se ne va con lui. E tiene traccia di quello che sta facendo con due variabili vero-o-falso, over e dying, che è la trappola da cui ti metteva in guardia la settima lezione.

Questa lezione le sistema tutte e tre. Una variabile per quello che sta facendo il gioco, una schermata del titolo da cui partire, un punteggio record che domani c’è ancora e una seconda partita che comincia esattamente come la prima.

Un gioco è sempre in un solo stato

Guarda un cabinato qualunque per due minuti. Mostra un titolo e aspetta qualcuno. Qualcuno preme start e lui gioca. Il giocatore finisce le vite e lui lo dice, poi aspetta di nuovo. La macchina fa sempre esattamente una di queste cose.

Dodge, nella settima lezione, lo teneva in una variabile che conteneva una parola: "waiting", "playing" o "over". Il gioco della nona lezione è tornato a un over vero-o-falso, e la decima lezione gli ha messo accanto dying. Conta che cosa possono dire due variabili così. Ognuna è true o false, quindi insieme fanno quattro combinazioni. Tre vogliono dire qualcosa: si gioca, si muore e la partita è finita. La quarta, tutte e due insieme, è un’assurdità, e il tuo codice deve stare attento a non produrla mai. E ci sta attento: guarda endGame, che rimette dying a false prima di mettere over a true. Ora aggiungi una schermata del titolo. È un terzo flag, otto combinazioni, e quattro sono assurdità. È esattamente la trappola della settima lezione, ed è il posto dove i piccoli giochi vanno a morire.

Quindi fai come Dodge. Quattro stati, una variabile. Metti i nomi degli stati sotto le tue altre costanti:

local TITLE   = "title"
local PLAYING = "playing"
local DYING   = "dying"
local OVER    = "over"

Poi togli over e dying dalle tue variabili, e al loro posto metti una riga sola:

local state        = TITLE

Dodge usava direttamente le parole. I nomi in maiuscolo non sono più furbi, e non acchiappano un errore di battitura: Lua tratta un nome scritto male come nil e una parola scritta male come una parola che non corrisponde a niente, e in tutti e due i casi ottieni un gioco che smette di rispondere senza dire niente. Quello che i nomi ti comprano è un elenco. Ogni stato in cui il gioco può trovarsi è scritto una volta sola, in cima al file, dove li vedi tutti e quattro con un’occhiata.

Dovunque il gioco impostava un flag, adesso imposta lo stato. In updateRocks, dove se ne va l’ultima vita:

            if lives <= 0 then
                state        = DYING
                deathChannel = channel

In endGame due righe diventano una, e la combinazione assurda sparisce perché non resta niente da combinare:

function endGame()
    deathChannel = -1
    state        = OVER
    musicStop(theme, 1500)
end

E in startGame le due righe che azzeravano tutti e due i flag diventano state = PLAYING.

Un solo posto che decide

A ogni fotogramma onOverlayUpdate prende le due decisioni che contano: che cosa si muove, e quali parole ci vanno sopra. Che cosa si muove è un controllo solo:

    if state == PLAYING then
        updateShip()
        updateShots()
        updateRocks()
    end

Prende il posto di if not over and not dying then, e dice quello che intende. Sulla schermata del titolo, mentre suona l’ultima esplosione e dopo la fine della partita, non si muove niente. Lo ottieni non chiamando le funzioni che muovono le cose. Fermare un gioco non è una funzionalità speciale; è lasciare fuori delle cose.

Il mondo viene comunque disegnato a ogni fotogramma, qualunque sia lo stato, esattamente come lo disegnava Dodge. Cambiano solo le parole. Sostituisci la riga drawHud() con questa:

    if state == TITLE then
        drawTitle()
    else
        drawHud()
    end

drawTitle è nuova, e va dopo 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 è il punteggio migliore finora, e arriva nella prossima sezione; finché non arriva, il gioco non parte. Prima della prima partita l’elenco delle rocce è vuoto, quindi il titolo mostra le stelle che scorrono e la nave che aspetta in fondo, ed è tutto ciò che serve a una schermata del titolo.

Una riga se ne deve andare, altrimenti il titolo non lo vedrai mai. Cancella lo startGame() proprio in fondo al file. Adesso il gioco comincia dal suo titolo, e Ricominciare spiega perché quella riga conta.

drawHud fa una domanda tutta sua. Cambia il suo if over then in:

    if state == OVER then

La callback dei comandi ha bisogno dello stesso tipo di ragionamento. Eccola intera:

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

Leggila dall’alto. I tasti freccia vengono registrati qualunque sia lo stato, perché dicono soltanto quali tasti sono premuti, e niente muove la nave se lo stato non è PLAYING. Il fuoco vuol dire qualcosa solo mentre si gioca. E 1 comincia una partita dal titolo o dalla schermata di game over, e non mentre l’ultima esplosione sta ancora suonando: la partita non è finita finché non lo dice lei. Le parentesi funzionano come in aritmetica. Prima si calcola l’or che sta dentro, e poi l’and lo unisce al tasto.

Punteggio e vite

Li hai tutti e due dalla nona lezione, e cambiano poco. La novità è il punteggio migliore, che nasce come una variabile qualunque. Mettila con le altre, sotto lives:

local best         = 0

Mostralo nella riga in alto, tra gli altri due. In drawHud:

    overlayPrint(1, 1, "SCORE " .. score)
    overlayPrint(25, 1, "BEST " .. best)
    overlayPrint(50, 1, "LIVES " .. lives)

E dai a endGame il compito di accorgersi di un record:

    if score > best then
        best = score
    end

Eseguilo. Il titolo dice BEST 0. Premi 1, spara a qualcosa, perdi, e la schermata di game over mostra il tuo punteggio come il migliore. Premi di nuovo 1 e il migliore resta mentre il punteggio riparte da zero. Ora esci, eseguilo di nuovo e guarda il titolo: BEST 0. Il record è vissuto esattamente quanto il programma. È la seconda metà di questa lezione.

Già che guardi le vite, nota che la nona lezione ha scritto il controllo come lives ⇐ 0 e non lives == 0, e lascialo così. Oggi niente può toglierti due vite in una volta, quindi i due controlli vanno sempre d’accordo. Il giorno in cui aggiungi una roccia che ne costa due, == 0 scavalca lo zero e il giocatore continua a giocare con meno una vita, mentre ⇐ 0 continua a funzionare. Chiedi quello che intendi.

Ricominciare

Hai già cancellato lo startGame() in fondo al file. Nella decima lezione la prima partita cominciava con quella riga e tutte le successive premendo 1: due porte d’ingresso. Adesso ce n’è una. Ogni partita, compresa la prima, comincia quando qualcuno preme 1 e parte startGame, quindi la prima partita e la quinta cominciano esattamente allo stesso modo.

startGame deve rimettere a posto tutto ciò che una partita cambia:

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

È altrettanto importante sapere che cosa lascia stare, e perché. best sopravvive a ogni partita; è tutto il suo lavoro. Le stelle sono scenografia. E goLeft e goRight non sono affatto della partita. Sono della tastiera, e solo la tastiera dovrebbe cambiarli.

Quest’ultima cosa è un bug che hai appena corretto senza accorgertene. La callback dei comandi della decima lezione cominciava con if over then, e mentre la partita era finita buttava via ogni tasto tranne 1. Premi la freccia destra mentre si vede GAME OVER, tienila premuta e premi 1. La nuova nave resta ferma: la pressione della freccia destra è stata buttata via, il rilascio non è ancora avvenuto, e quindi goRight è false mentre il tasto è chiaramente giù. La nave resta dov’è finché non lasci il tasto e lo premi di nuovo. La nuova callback registra i tasti freccia in ogni stato, quindi il tasto tenuto premuto è ancora premuto quando la partita comincia.

I bug del ricominciare sono i bug più comuni in qualunque gioco, e quando giochi sembrano tutti uguali: la seconda partita è sbagliata in un modo sottile e la prima andava bene. Quando succede, leggi startGame e fatti due domande. Che cosa ha cambiato l’ultima partita che questa non rimette a posto? E che cosa sta rimettendo a posto questa che la partita non doveva mai toccare?

Un numero che sopravvive al programma

Tutto quello che il tuo gioco ha tenuto finora — score, lives, l’elenco delle rocce — vive in memoria, e la memoria sparisce nell’istante in cui il programma si ferma.

Singe dà a ogni gioco un salvataggio tutto suo: un insieme di nomi con dei valori sotto, scritto su disco per te. È un’altra parte del kit di gioco dell’undicesima lezione, quindi è lo stesso tipo di cosa di collideRects: chiamate semplici, niente da caricare o liberare.

saveSet("highScore", 4200)

saveSet prende un nome — la chiave — e un valore. La chiave la scegli tu e non cambia mai; il valore è qualunque cosa tu voglia ricordare. Numeri, stringhe, true e false, e intere tabelle di queste cose: ci va tutto. Non ci vanno le cose che hanno senso solo mentre il programma è in esecuzione. Un handle di sprite è solo un numero, quindi si salva, e domani è un numero che non vuol dire niente. Una funzione non si può proprio scrivere, e provare a salvarne una ferma il gioco con un errore invece di lasciartelo scoprire la settimana dopo.

Rileggerlo è l’altra metà. Cambia la riga che hai aggiunto per best:

local best         = saveGet("highScore", 0)

Viene eseguita una volta, all’avvio del gioco. Il secondo argomento è il valore predefinito: che cosa rispondere quando sotto quella chiave non è mai stato salvato niente. Ne riparliamo tra un momento, perché è tutto l’errore di questa lezione.

E fai in modo che endGame scriva il record quando viene battuto:

function endGame()
    deathChannel = -1
    state        = OVER
    musicStop(theme, 1500)
    if score > best then
        best = score
        saveSet("highScore", best)
        saveFlush()
    end
end

Non devi chiedere a Singe di scrivere il file. Lo scrive una volta alla fine di ogni fotogramma in cui è cambiato qualcosa, per quante chiavi tu abbia impostato, e di nuovo quando il gioco si chiude. saveFlush invece lo scrive subito: un nuovo punteggio record merita una scrittura del file tutta sua, perché un cabinato viene spento staccando la corrente e un fotogramma è tanto tempo.

Eseguilo, fai un punteggio, esci ed eseguilo di nuovo. Il titolo se lo ricorda.

La sezione Salvataggio del Riferimento elenca il resto della famiglia. saveDelete dimentica una chiave, saveClear dimentica tutto — è il «reset dei punteggi record» di un menu di servizio — e saveGetAll ti dà una copia di tutto quanto, che è utile quando vuoi stampare l’intero salvataggio mentre stai dando la caccia a qualcosa.

Dove va a finire davvero il file

Non va accanto al tuo script, e non è un caso.

Un gioco finito può stare su un disco, su una cartella condivisa in rete o dentro un unico file impacchettato (la trentesima lezione), e in nessuno di questi si può scrivere. Un gioco che salva accanto al proprio script funziona perfettamente sulla macchina su cui l’hai scritto e fallisce su metà delle macchine su cui viene installato. Singe 2 faceva così, ed era sbagliato.

Quindi tutto ciò che Singe scrive per un gioco — il salvataggio, gli screenshot, il suo log — va in un posto solo, e singeGetDataPath ti dice dove:

debugPrint(singeGetDataPath())

Mettilo per un momento subito sotto la riga del dofile ed eseguilo. Dice data/rocks/: la cartella data comparsa nella tua cartella di lavoro la prima volta che hai eseguito qualcosa, nella prima lezione, e dentro una cartella con il nome della cartella del tuo gioco. Lì dentro troverai save.json. Aprilo nel tuo editor di testo: è testo semplice, e il tuo punteggio record è lì dentro, sotto il nome che gli hai dato.

È questa la risposta anche ogni volta che ti serve un file tutto tuo. Costruisci il nome a partire da singeGetDataPath() e il file finisce in un posto dove si può scrivere; scrivi su un nome inventato da te e prima o poi non sarà così.

La prima volta non c’è niente

La primissima volta che qualcuno esegue il tuo gioco, non è mai stato salvato nessun punteggio record. saveGet non ha niente da restituire, quindi restituisce il valore predefinito che gli hai dato:

local best         = saveGet("highScore", 0)

Niente di salvato, quindi best è 0, la schermata del titolo dice BEST 0, e la prima partita che qualcuno gioca stabilisce un record. È esattamente quello che vuoi, e costa un argomento in più.

Lascia fuori lo 0 e saveGet non ha un valore predefinito su cui ripiegare, quindi risponde nil — il valore che Lua usa per «qui non c’è niente», che hai incontrato nella terza lezione. nil non è zero. Non ci puoi sommare niente, non lo puoi confrontare con un numero e non lo puoi attaccare a una stringa. Va storto al primo fotogramma, ogni volta, su ogni macchina dove il gioco non è ancora stato giocato — il che comprende ogni macchina su cui i tuoi giocatori stanno per installarlo, e non quella su cui stai facendo le prove.

Dai a ogni saveGet un valore predefinito. È l’abitudine più economica di questo libro.

Cos’è appena successo

local TITLE   = "title"

Una costante: un nome che imposti una volta e non cambi mai, in maiuscolo così si vede con un’occhiata che è una costante, come nella settima lezione. Lua non lo impone — niente ti impedisce di assegnare un valore a TITLE — quindi le maiuscole sono un messaggio per la prossima persona che legge, cioè tu fra due settimane.

    if state == PLAYING then

La domanda che decide se il mondo si muove. Quando più avanti aggiungerai un quinto stato — una pausa, o un round bonus — la prima cosa da chiedersi è se in quello stato il mondo si muove, ed è qui che va la risposta.

    elseif what == SWITCH_START1 and (state == TITLE or state == OVER) then

Senza le parentesi, Lua legherebbe per primo and e leggerebbe la riga come «il tasto è 1 e lo stato è il titolo, oppure lo stato è la fine della partita». Allora qualunque tasto che i rami qui sopra non hanno acchiappato farebbe cominciare una partita dalla schermata di game over, compreso il fuoco, e un giocatore che martella ancora il pulsante di fuoco quando arriva l’ultima roccia verrebbe buttato in una nuova partita nell’istante in cui compare GAME OVER. Le parentesi fanno venire prima or. Quando mescoli and e or, metti le parentesi anche se pensi di conoscere l’ordine. La prossima persona che lo legge non avrà bisogno di conoscerlo.

        saveSet("highScore", best)
        saveFlush()

saveSet mette il numero nel salvataggio; saveFlush mette il salvataggio sul disco adesso invece che alla fine del fotogramma. Stanno tutte e due dentro l’if, quindi il file viene scritto solo quando il record viene battuto davvero, cioè qualche volta per sessione invece che sessanta volte al secondo.

local best         = saveGet("highScore", 0)

Letto una volta, all’avvio, in una variabile qualunque. Il resto del gioco legge best invece di chiamare di nuovo saveGet, perché il salvataggio è un file e una variabile è una variabile. Quando il record cade, scrivi in tutti e due.

Prova tu

  1. Torna al titolo. Un cabinato non resta su GAME OVER per sempre. Cerca timerAfter nella sezione Timer del Riferimento, un’altra parte del kit di gioco, e usalo in endGame per riportare lo stato a TITLE cinque secondi dopo la fine della partita. Poi premi 1 subito dopo la fine di una partita e controlla che il timer non rispedisca al titolo la tua nuova partita dopo tre secondi.

  2. Mostra le vite come navi. Disegna shipSprite una volta per ogni vita nell’angolo in alto a destra con spriteDraw, invece di stampare il numero. Un ciclo for della quarta lezione, e shipWidth ti dice quanto distanziarle.

  3. Salva più di un numero. Aggiungi saveSet("gamesPlayed", saveGet("gamesPlayed", 0) + 1) a startGame, e stampalo sulla schermata del titolo. Esci, eseguilo di nuovo e guarda che se lo ricorda.

  4. Trova il file e rompilo. Apri data/rocks/save.json nel tuo editor, cambia il punteggio record in qualcosa di assurdo e avvia il gioco. Poi cancella del tutto il file e avvialo di nuovo. Ai tuoi giocatori succederanno tutte e due le cose.

  5. Azzeralo dall’interno del gioco. Fai in modo che un tasto che non premeresti mai per sbaglio chiami saveClear(), e poi controlla la schermata del titolo. Attento: best è ancora in memoria, e saveClear non lo tocca. Scopri che cos’altro deve succedere.

Rompilo apposta

Togli il valore predefinito, così la riga diventa:

local best         = saveGet("highScore")

Se hai già fatto un punteggio record non succede proprio niente, ed è questa la trappola: il salvataggio ha la chiave, quindi saveGet ti restituisce il valore. Prima cancella data/rocks/save.json, poi eseguilo. La schermata del titolo non compare mai, e ottieni questo:

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'

Leggilo come ti ha insegnato l’ottava lezione. Il file e la riga ti portano a overlayPrint(25, 9, "BEST " .. best) in drawTitle, e la lamentela dice che qualcosa che era nil è stato attaccato a una stringa. .. unisce due stringhe, e nil non è una stringa. Se le tue righe sono disposte diversamente, anche i tuoi numeri lo saranno.

La riga che nomina non è dove sta l’errore. La riga 101 è dove il gioco alla fine ci è inciampato; l’errore è stato fatto vicino all’inizio del file, dove è stato chiesto best e lì non c’era niente. Quella distanza tra il punto in cui nasce un valore sbagliato e il punto in cui qualcuno se ne accorge è la cosa più difficile di nil, ed è il motivo per cui un valore predefinito costa un argomento e ti risparmia una serata.

Rimetti lo 0.

Cosa hai imparato

  • Un gioco è in un solo stato alla volta, e i flag vero-o-falso che cercano di dire quale generano combinazioni che non vogliono dire niente.

  • Tieni lo stato in una variabile sola, con i suoi possibili valori nominati una volta in cima al file.

  • onOverlayUpdate decide che cosa si muove e che cosa viene detto, chiedendolo allo stato.

  • Fermare un gioco vuol dire non chiamare le cose che lo muovono.

  • Fai cominciare ogni partita, compresa la prima, da una sola funzione, e fai in modo che quella funzione rimetta a posto tutto ciò che una partita cambia — e nient’altro.

  • I tasti appartengono alla tastiera. Registrali in ogni stato.

  • saveSet conserva un valore sotto una chiave, e saveGet lo rilegge in un avvio successivo.

  • saveFlush scrive subito il file, per le cose che ti dispiacerebbe perdere.

  • Il salvataggio va nella cartella dei dati del gioco, quella che nomina singeGetDataPath. Non scrivere mai accanto al tuo script.

  • saveGet senza valore predefinito risponde nil quando non è stato salvato niente, e nil rompe il primo fotogramma su una macchina che non ha mai eseguito il tuo gioco.

  • Quando mescoli and e or, usa le parentesi.

La prossima volta

Adesso il tuo gioco è un gioco, ed è una cartella che solo tu sai come avviare. La tredicesima lezione gli dà un games.dat, così il menu del motore stesso lo elenca con un titolo e un’immagine, e un giocatore che non ha mai sentito parlare di te può avviarlo senza scrivere niente.

Lezione 13: La cartella del gioco

La lezione finita

Il tuo gioco è uno script in una cartella di cui ricordi il nome, avviato scrivendo il suo nome in un terminale. Per te va bene, e per chiunque altro non serve a niente. Un giocatore dovrebbe poter copiare una cartella accanto a Singe, avviare il menu, vedere il tuo gioco nell’elenco con il suo titolo e la sua grafica, e premere un pulsante. L’immagine qui sopra è quel menu, con dentro il tuo gioco.

Serve un file nuovo, lungo più o meno sei righe, e due immagini che puoi fare con un tasto. Il tuo script non cambia per niente.

Dai un nome al gioco

Un gioco ha due nomi, uno per il computer e uno per le persone.

Quello per il computer è la cartella, e l’hai scelto nella nona lezione: rocks, con dentro rocks.singe. La cartella e lo script hanno lo stesso nome, come in ogni lezione dalla prima in poi, ed è per questo che Singe rocks trova lo script partendo solo dalla cartella. Tieni quel nome semplice. Niente spazi, che un terminale legge come lo stacco tra due nomi. E le stesse maiuscole dovunque lo scrivi: sulla maggior parte dei computer che non sono Windows, rocks e Rocks sono due cartelle diverse, e un gioco che funziona solo sulla tua macchina non è un gioco che possa avere qualcun altro.

Il nome per le persone può essere quello che vuoi, maiuscole, spazi e tutto il resto, e non sta nel nome della cartella. Sta nel file di cui parla questa lezione, così cambiare il nome del gioco nel menu non vuol mai dire rinominare una cartella.

Che cosa va nella cartella

Tutto ciò che serve al tuo gioco, e nient’altro. Alla fine di questa lezione ha questo aspetto:

rocks/
    games.dat       Quello che legge il menu
    rocks.singe     Il gioco
    art/            Il kit di grafica della nona lezione
        spaceship.png
        asteroid.png
        bullet.png
        star.png
        shoot.wav
        boom.wav
        ...
    cabinet.png     Un'immagine che il menu mostra accanto all'elenco
    marquee.png     Un'immagine che il menu mostra sopra l'elenco

Qualunque altra cosa ci sia finita dentro mentre imparavi — walk.singe della nona lezione, la piccola prova del suono della decima — non fa parte del gioco. Spostale in una cartella tutta loro accanto a rocks. Anche il kit di grafica ha qualche file che questo gioco non carica mai, e per adesso non fanno danni. È nella trentesima lezione che passi in rassegna la cartella di un gioco e togli tutto ciò che non è il gioco.

La regola dietro questa struttura è che un gioco non va mai a prendere niente fuori dalla propria cartella. Né la grafica, né un suono, né una libreria che usi anche in un altro gioco — se condividi del codice tra due giochi, ognuno tiene la propria copia. C’è esattamente un posto fuori dalla cartella da cui un gioco può caricare, e ci stai già caricando: la cartella Singe del motore stesso, dove sta Singe/Framework.singe e, dalla decima lezione, il clic e la musica.

La cartella del gioco sta nella tua cartella di lavoro, accanto al motore:

singe/                 La tua cartella di lavoro
    Singe-v3.00-...    Il motore, comunque si chiami il tuo
    Menu.sh            Avvia il menu.  Menu.bat su Windows
    Singe/             File di supporto.  Non sono tuoi; lasciali stare
    data/              Tutto ciò che viene scritto, tra cui il tuo salvataggio
    rocks/             Il tuo gioco

È la stessa forma che ha anche la macchina di un giocatore. Il motore ha scritto Singe, data e Menu.sh (Menu.bat su Windows) la prima volta che hai eseguito qualcosa, nella prima lezione. Le prime due cose le nominava la prima lezione. La terza è nuova per te, e questa lezione la mette al lavoro.

I percorsi partono da dove è stato avviato Singe

Lo fai dalla nona lezione, quindi questo è un promemoria, non un cambiamento.

Ogni nome che il tuo gioco carica — art/spaceship.png, art/boom.wav — viene cercato a partire dalla cartella in cui Singe è stato avviato, non da quella in cui sta il tuo script. Tu avvii Singe nella tua cartella di lavoro, quindi un art/spaceship.png da solo verrebbe cercato in singe/art, che non esiste. DIR è la cartella del tuo script con la barra già in fondo, quindi un nome attaccato in coda punta al tuo file da dovunque sia stato avviato Singe:

local shipSprite = spriteLoad(DIR .. "art/spaceship.png")

Il menu avvia Singe nella cartella in cui sta Menu.sh, che è di nuovo la tua cartella di lavoro, quindi lì DIR fa esattamente quello che fa per te. E continua a farlo quando il gioco viene impacchettato in un unico file nella trentesima lezione, quando la cartella di lavoro di qualcun altro si chiama in tutt’altro modo, e su una macchina che non vedrai mai. Un nome che comincia con Singe/ è la cartella del motore e non ha mai bisogno di DIR; ogni nome che è tuo sì.

games.dat

games.dat è il modo in cui un gioco si presenta. Il menu legge il games.dat di ogni cartella di gioco che ha accanto ed elenca quello che trova. Niente games.dat, niente posto nell’elenco: la tua cartella è invisibile, per quanto sia bello il gioco che contiene.

Crea un nuovo file chiamato games.dat nella tua cartella rocks. Questo è il più piccolo che funziona:

GAMES = {
    {
        TITLE  = "Rocks",
        SCRIPT = "rocks/rocks.singe"
    }
}

È Lua, ed è una tabella del tipo che hai incontrato nella sesta lezione: GAMES è un elenco, e ogni cosa nell’elenco è un record che descrive un gioco. Una cartella può contenere più giochi — ecco perché è un elenco — ma la tua ne contiene uno.

SCRIPT è il campo che serve al motore per avviare il gioco, e TITLE quello che serve al menu per elencarlo. Il percorso dello script parte dalla cartella sopra il games.dat, non dalla cartella in cui sta il games.dat. Quindi un games.dat dentro rocks indica il proprio script come rocks/rocks.singe. Sembra che dica rocks due volte, ed è giusto così. Ogni altro percorso nel file funziona allo stesso modo. Sbaglialo e, quando scrivi il nome, nessuno si lamenta: semplicemente la voce non corrisponde mai allo script che hai avviato.

TITLE è il nome per le persone di cui parlava l’inizio di questa lezione. È quello che mostra il menu, e i giochi sono elencati in ordine di titolo, quindi il titolo decide anche dove si trova il tuo gioco nell’elenco.

Dire di più al menu

Il menu ha un intero pannello da riempire accanto all’elenco, e lo riempie con il resto della voce:

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 e MARQUEE sono normali file di immagine nella cartella del tuo gioco, in qualunque formato Singe sappia leggere. La grafica del cabinato è l’immagine grande accanto all’elenco e il marquee è la striscia sopra. Falli grandi quanto vuoi; il menu li adatta ai loro pannelli.

Per farli non ti serve un programma di disegno, perché il tuo gioco sa fotografarsi da solo. Eseguilo, e quando lo schermo ha l’aspetto con cui vuoi che lo veda il mondo, premi F12 (o F11, perché alcuni desktop tengono F12 per sé). Singe salva un’immagine della finestra nella cartella dei dati del tuo gioco, data/rocks, con il nome singe000.png, poi singe001.png, e così via. Fanne una della schermata del titolo e una nel mezzo di una battaglia. Copiale nella tua cartella rocks e rinominale: la battaglia è cabinet.png, il titolo è marquee.png.

Un vero marquee è una striscia larga con il nome del gioco a lettere grandi, e uno schermo intero schiacciato lì dentro sembra un francobollo. Andrà bene finché non avrai qualcosa di meglio. Lascia fuori MARQUEE e il menu ci mette al suo posto l’immagine mancante del motore stesso, una scacchiera rosa con scritto MISSING, che è peggio.

YEAR, GENRE, DEVELOPER, PUBLISHER e DESCRIPTION sono il testo sotto, e il motore non li guarda mai. Sono per la persona che legge il menu, ed è proprio questo lo scopo.

CANVAS_X e CANVAS_Y sono la dimensione del mondo del tuo gioco, e 720 per 480 è il valore predefinito — lo stesso mondo in cui disegni dalla prima lezione. Impostali solo se il tuo gioco vuole una forma diversa. Un gioco senza il campo VIDEO è un gioco senza video, ed è il caso del tuo; è nella quattordicesima lezione che quel campo comincia a contare.

La sezione games.dat del Riferimento elenca tutti i campi che esistono, compresi diversi per hardware che non hai ancora. Di alcuni altri vale la pena conoscere il nome già adesso.

REQUIRES dice di che cosa ha bisogno un gioco dalla macchina oltre al semplice 2D: "GUI" per i menu e le pagine della ventesima lezione, "SCENE" per il 3D che comincia nella ventiduesima, e qualche altro. Il menu lo legge per poter dire a un giocatore «questa macchina quello non lo può eseguire» invece di lasciare che il gioco si pianti a metà strada. Rocks è semplice 2D, e lasciare fuori REQUIRES vuol dire esattamente questo, quindi lascialo fuori. Raramente dovrai ricavare l’elenco da solo, perché Singe si accorge di quello che un gioco usa mentre gira e lo dice quando la voce non lo elenca. Dalla ventesima lezione in poi vedrai righe come questa, che il gioco abbia o no un games.dat:

Warning:  this game uses GUI, which its games.dat does not list in REQUIRES.

È un consiglio, non un errore; il gioco gira lo stesso. La cura è una riga nella voce, REQUIRES = { "GUI" },, e impacchettare un gioco, nella trentesima lezione, ti scrive l’elenco se la voce non ne ha uno. Il suo compagno TIER, un numero da 0 a 3, dice quanta macchina vuole un gioco, e può aspettare finché non scrivi un gioco abbastanza pesante da preoccupartene.

GAME_ID è un’identità unica per il tuo gioco, che serve alle classifiche online della ventottesima lezione e a nient’altro. E RESOLUTION_X e RESOLUTION_Y chiedono una dimensione particolare della finestra. Ignora il resto finché qualcosa non ti manda a cercarlo.

Avviarlo dal menu

Esegui Menu.sh — Menu.bat su Windows — dalla tua cartella di lavoro. Trova il Singe più recente che ha accanto e avvia il menu.

Il tuo gioco è nell’elenco, con la sua grafica accanto e la sua descrizione sotto. È l’unica cosa nell’elenco, perché rocks è l’unica cartella a cui hai dato un games.dat; per quanto ne sa il menu, hello, dodge e gli altri non sono giochi. Su e giù si spostano di un gioco, sinistra e destra di una pagina, e start o un pulsante di fuoco avviano quello selezionato. Esci dal gioco con Esc e sei di nuovo nel menu, sullo stesso gioco, pronto a ripartire. Il menu si ricorda su quale gioco eri anche da un avvio all’altro.

Ecco tutto quello che serve per distribuire un gioco, per quanto riguarda il motore. Un giocatore copia la tua cartella accanto a Singe e il gioco compare.

Scrivere il nome funziona ancora, e funziona allo stesso modo:

Singe rocks

Quando avvii a mano uno script in questo modo, Singe cerca un games.dat lì accanto — e fino a tre cartelle più su — e se una voce nomina lo script che hai avviato, le impostazioni di quella voce valgono per lui. Così un gioco si comporta da un terminale come dal menu, il che vuol dire che puoi continuare a lavorare come hai fatto finora, con -R e un editor di testo, e fidarti comunque di quello che otterrà un giocatore. E scrive anche nello stesso posto: comunque lo avvii, il salvataggio del tuo gioco è quello in data/rocks.

Più avanti: un solo file

In una cartella è facile lavorare, ed è un po' scomodo regalarla: una dozzina di file, una cartella dentro una cartella, e un giocatore che la estrae nel posto sbagliato. Un gioco Singe finito può essere impacchettato in un unico file .game che il motore esegue direttamente, grafica, suoni e tutto il resto, e che un giocatore copia accanto a Singe, e ha finito.

Per questo nel tuo gioco non deve cambiare niente. È la trentesima lezione, e vale la pena aspettarla: impacchetta un gioco non finito e domani lo impacchetterai di nuovo.

Cos’è appena successo

GAMES = {
    {

Due graffe, perché è un elenco di record. Quella esterna è l’elenco. Quella interna è la prima cosa nell’elenco, cioè il record di un gioco. Sbagliarne una è l’errore tipico, e Lua ti dirà la riga.

        SCRIPT      = "rocks/rocks.singe",

Parte dalla cartella sopra il games.dat, che è la tua cartella di lavoro. È lo stesso nome che scriveresti dopo Singe per avviare lo script a mano, ed è il modo più facile per ricordartelo.

La virgola in fondo alla riga separa un campo dal successivo, esattamente come nella sesta lezione. L’ultimo campo di un record non ha la virgola dopo — a Lua non importa se ce l’ha, ma lasciala fuori e il tuo file somiglierà a quelli di tutti gli altri. Una virgola che manca in mezzo è un’altra faccenda, ed è l’errore di questa lezione.

        CABINET     = "rocks/cabinet.png",

Un’immagine che carica il menu, non il tuo gioco, quindi si indica come SCRIPT, dalla cartella sopra, e non con DIR. DIR appartiene al tuo script mentre gira, e il menu e il motore leggono games.dat prima che il tuo script sia partito.

Prova tu

  1. Fai una grafica migliore. Se hai un programma di disegno, fai un marquee.png come si deve: una striscia larga con ROCKS scritto a lettere grandi. Mettilo al posto dello screenshot e guarda di nuovo il menu.

  2. Dai un games.dat a Dodge. Scrivi un games.dat nella tua cartella dodge della settima lezione e avvia il menu. Adesso i giochi sono due, in ordine di titolo. Poi cambia il TITLE di Rocks in Asteroid Field e guardalo salire sopra Dodge: l’elenco è ordinato per titolo, non per cartella.

  3. Rompi games.dat per il menu. Cancella una delle graffe di chiusura nel games.dat di rocks e avvia il menu. Il tuo gioco è sparito dall’elenco, e il terminale dice perché. Rimettila a posto.

  4. Sbaglia SCRIPT. Metti CANVAS_X a 1280 e CANVAS_Y a 720, ed esegui Singe rocks. Il campo di gioco è più largo. Ora cambia SCRIPT in rocks.singe ed eseguilo di nuovo. Il gioco è tornato alla sua vecchia dimensione, e niente te l’ha detto: la voce non nomina più lo script che hai avviato, quindi non vale. Rimetti tutti e due com’erano.

  5. Trova il tuo salvataggio. Avvia il gioco dal menu, fai un punteggio record, esci tornando al menu ed esci dal menu. Esegui Singe rocks e guarda il titolo. Poi cerca in data/rocks il file che se l’è ricordato.

Rompilo apposta

Togli la virgola in fondo alla riga di TITLE, così l’inizio del file diventa:

GAMES = {
    {
        TITLE       = "Rocks"
        SCRIPT      = "rocks/rocks.singe",

Esegui Singe rocks. Il gioco parte, e il terminale dice questo:

Note:  rocks/games.dat ignored:  [string "rocks/games.dat"]:4: '}' expected (to close '{' at line 2) near 'SCRIPT'

Il tuo gioco gira lo stesso, perché a un gioco avviato per nome la sua voce non serve. Semplicemente gira senza. Avvia il menu, però, e il tuo gioco è sparito. Se era l’unico, l’elenco dice No games yet, e il terminale dice la stessa cosa in un altro modo:

rocks/games.dat:  rocks/games.dat:4: '}' expected (to close '{' at line 2) near 'SCRIPT'  Skipped.

Leggilo come qualunque altro errore di Lua. Il file è rocks/games.dat e la riga è la 4. Ma la riga 4 è quella di SCRIPT, e non ha niente che non va. L’errore è alla fine della riga 3. Dopo TITLE = "Rocks", Lua si aspettava o una virgola e un altro campo, o la } che chiude il record cominciato alla riga 2. Ha trovato invece SCRIPT, quindi è alla riga 4 che se n’è accorto. Il suo suggerimento per la correzione — una } — è sbagliato; la sua riga è sbagliata di uno. Quando un errore indica l’inizio di una riga, guarda la fine della riga prima.

Rimetti la virgola e avvia di nuovo il menu.

Cosa hai imparato

  • Un gioco è una cartella: lo script, la sua grafica e un games.dat, e niente da fuori tranne la cartella Singe del motore stesso.

  • Il nome della cartella è per il computer, quindi tienilo semplice. Il nome per le persone è TITLE.

  • I nomi che il tuo script carica partono da dove è stato avviato Singe, ed è per questo che ognuno di loro è costruito a partire da DIR.

  • games.dat è un file Lua che contiene un elenco GAMES, e ogni voce è un gioco.

  • A una voce servono TITLE e SCRIPT e nient’altro; i percorsi al suo interno partono dalla cartella sopra il games.dat.

  • CABINET, MARQUEE, YEAR, GENRE, DEVELOPER, PUBLISHER e DESCRIPTION sono quello che il menu mostra al giocatore, e F12 fa un’immagine che puoi usare per i primi due.

  • REQUIRES dice al menu di che cosa ha bisogno un gioco oltre al 2D, e Singe ti avverte quando un gioco usa qualcosa che la sua voce non elenca.

  • Menu.sh o Menu.bat avvia il menu incluso, che elenca ogni cartella di gioco che ha accanto, in ordine di titolo.

  • Anche un gioco avviato per nome riceve la sua voce di games.dat, quindi si comporta allo stesso modo in tutti e due i casi, e un games.dat che non si carica viene segnalato e ignorato.

  • Un gioco finito si può impacchettare in un unico file più avanti, nella trentesima lezione.

La prossima volta

Con questo la seconda parte è finita: hai un gioco, con grafica, suono, collisioni, punteggio e un modo perché qualcun altro lo possa avviare. La terza parte parla della cosa che quasi nessun altro motore fa — riprodurre un filmato come mondo in cui si svolge il gioco — e la quattordicesima lezione comincia con il disco, il fotogramma e l’attesa.

Lezione 14: Riprodurre video

La lezione finita

Singe sa riprodurre un filmato e far girare il tuo gioco al suo interno. L’immagine diventa il mondo, e l’overlay su cui disegni dalla prima lezione viene steso sopra. In questa lezione avvierai un video, scoprirai quale fotogramma si vede, lo fermerai e salterai a qualunque momento ti piaccia.

Prima di tutto questo, c’è una cosa da dire chiaramente, perché decide se devi leggere questa parte del libro.

Un gioco riproduce video solo se lo chiede

Singe è un motore di gioco. Tutto ciò che hai costruito nella prima e nella seconda parte — gli sprite, il suono, le collisioni, il punteggio, la cartella del gioco — è Singe per intero, e niente di tutto ciò riguarda il video. Quello che la terza parte aggiunge è un extra: un gioco può chiedere che dietro di lui scorra un filmato, e allora il mondo è il filmato invece di un canvas nero.

Non cambia nient’altro. onOverlayUpdate viene ancora chiamata sessanta volte al secondo. overlayPrint conta ancora in celle di carattere. I tuoi sprite si disegnano dove si disegnavano prima. Un gioco con il video e uno senza si scrivono allo stesso modo, con le stesse funzioni, e condividono lo stesso libro.

Quindi se il gioco che vuoi fare non ha video, puoi chiudere adesso questa parte e passare alla quarta. Niente nella quarta parte dipende da qualcosa della terza, e le uniche lezioni che hanno bisogno di questa sono le quattro che la seguono.

Ancora qui? Bene.

Hai già un video

Non devi trovarne uno, comprarne uno o farne uno. La prima volta che hai eseguito Singe nella prima lezione, nella tua cartella di lavoro è comparsa una cartella chiamata Singe. Aprila e guarda: tra i file che il motore ha estratto c’è menuBackground.mkv. È lo sfondo che usa il menu del motore stesso, è di 720 per 480 pixel, ed è lungo 420 fotogrammi — circa quattordici secondi.

È il video di questa lezione e delle due successive.

Crea una cartella chiamata movie nella tua cartella di lavoro, accanto alle cartelle delle altre lezioni, e dentro un file chiamato movie.singe. Non c’è nient’altro da preparare. Avvii Singe dalla cartella di lavoro, come fai dalla prima lezione, quindi la cartella Singe, video compreso, è proprio lì accanto al tuo gioco, e Singe/menuBackground.mkv è il nome che fra un momento darai al motore. Non c’è niente da copiare.

Scrivi questo

dofile("Singe/Framework.singe")


function onOverlayUpdate()
    overlayClear()
    overlayPrint(2, 2, "Frame " .. discGetFrame())
    return OVERLAY_UPDATED
end


discPlay()

Salvalo.

Avvialo

Il video non fa parte del tuo script, quindi non lo carichi nel tuo script. Lo passi al motore sulla riga di comando, con -v:

Singe -R -v Singe/menuBackground.mkv movie

-v è l’abbreviazione di --framefile, e indica il video che il gioco deve riprodurre. Il nome del tuo script viene per ultimo, come sempre. -R è lo stesso -R che usi dalla prima lezione, e fa ancora ripartire il gioco quando salvi.

Il senso di -v sta tutto nel chiedere. Se metti un file video accanto al tuo script e non dici niente, il motore se ne accorge, lo dice sulla console ed esegue il tuo gioco senza. Un gioco è un gioco video solo quando qualcuno dice che lo è.

Si apre una finestra. Una palla di fuoco arancione la riempie, dal fuoco prende forma un drago, sotto compare la parola SINGE, e poi una griglia magenta scorre via sotto un sole arancione. Nell’angolo in alto a sinistra, sopra tutto quanto, c’è un numero che sale.

Guardalo fino alla fine. Poi guarda che cosa succede alla fine.

Cos’è appena successo

discPlay()

Singe chiama il video il disco, e ogni funzione che lo comanda comincia con disc. Il nome è storico: il motore è nato facendo girare giochi che tenevano il loro filmato su un laserdisc, e il nome è rimasto attaccato all’idea. È un file video sul tuo disco rigido e niente di più.

Un gioco ha al massimo un disco, quindi nessuna delle funzioni disc prende un argomento che dica quale. Ce n’è uno solo.

Questa riga non sta dentro nessuna funzione. Sta in fondo al file, da sola, e viene eseguita una volta quando Singe carica il tuo script — prima del primo onOverlayUpdate, prima di qualunque altra cosa. Singe non ha una callback onStartup perché non gliene serve una: uno script Lua è un elenco di istruzioni, e tutto ciò che scrivi fuori da una funzione avviene mentre il file viene letto. Per convenzione, il codice di avvio va in fondo, sotto le funzioni.

Ti serve discPlay() perché il disco non parte da solo. Quando il gioco comincia, il motore parcheggia il disco sul fotogramma uno e lo mette in pausa lì. Non si muove niente finché non lo chiedi.

    overlayPrint(2, 2, "Frame " .. discGetFrame())

discGetFrame risponde a una domanda: quale fotogramma si vede in questo momento? Non prende argomenti e restituisce un numero.

Nota dove viene disegnato quel numero. Colonna 2, riga 2 — esattamente dove andava Hello! nella prima lezione, e finisce nello stesso punto dello schermo. L’overlay su cui disegni è grande la metà del video su ogni lato, cioè 360 per 240 per un video di 720 per 480, che è esattamente la dimensione su cui disegni da tredici lezioni. Le tue coordinate non si sono spostate. Se un giorno riproduci un video di un’altra dimensione, l’overlay cambia dimensione con lui, e overlaySetResolution lo imposta a quello che vuoi; la voce nel Riferimento ha i dettagli.

È tutta qui l’idea dell’overlay. Il video sta sotto. Il tuo disegno sta sopra, e dovunque non hai disegnato si vede il filmato. Ecco perché overlayClear adesso conta ancora più di prima: pulisci l’overlay e stai guardando il filmato.

Un fotogramma è un indirizzo

Il numero che discGetFrame restituisce è un numero di fotogramma. Un fotogramma è un’immagine ferma. Questo video ne contiene 420 e ne mostra circa trenta al secondo, quindi dura circa quattordici secondi.

I fotogrammi si contano da zero, quindi questo video ha i fotogrammi da 0 a 419. Il conteggio e l’ultimo numero non sono la stessa cosa, e questo frega tutti una volta. discGetFrameCount ti dice il conteggio — 420 — e il fotogramma più alto che puoi chiedere è uno di meno.

La cosa importante di un numero di fotogramma è che non cambia mai e non slitta mai. Il fotogramma 110 è il momento in cui il drago sputa fuoco, in questa copia del file, su questa macchina, oggi e l’anno prossimo. I secondi slittano, perché un video non va sempre esattamente alla velocità che pensi. Un numero di fotogramma è l’indirizzo di un momento, e gli indirizzi sono la materia di cui è fatto un gioco video: annoti il fotogramma in cui compare il drago, e da lì in poi puoi mandarci il filmato quando vuoi.

Trovare quei numeri è un lavoro che fai una volta per ogni video, e lo script che hai scritto è lo strumento per farlo: fai andare il filmato, guarda il contatore, annota i fotogrammi in cui succedono le cose. Tutto ciò che c’è nella sedicesima lezione è costruito su un elenco di numeri trovati esattamente così.

Che cosa è successo alla fine

Il contatore è arrivato a 419, poi è tornato a 0 e il fuoco è ricomparso.

Quando il disco arriva in fondo, il motore lo fa ripartire dal fotogramma zero. Non si ferma, e non te lo dice. Un vero gioco non lo lascia mai arrivare lì: tiene d’occhio il numero del fotogramma e manda il disco da un’altra parte prima che arrivi la fine. Dimenticarsene è il motivo per cui un gioco video finito a metà all’improvviso riproduce la propria sequenza dei titoli nel bel mezzo di un combattimento.

Fermare, saltare e chiedere

Aggiungi questa funzione sopra 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

Salva, e provali uno per uno. La barra spaziatrice avvia e mette in pausa. Sinistra torna all’inizio. Destra salta avanti di circa un secondo. Il tasto 1 ferma del tutto il disco, e quello che ottieni è una schermata blu — il colore che mostrava un lettore laserdisc quando era fermo, mantenuto perché moltissimi giochi ci disegnavano sopra la tabella dei punteggi.

Lì ci sono cinque nuove chiamate, e si dividono in due tipi.

Chiedere. discGetState restituisce uno di quattro nomi che il motore ha già definito per te: DISC_PLAYING, DISC_PAUSED, DISC_STOPPED e DISC_EJECTED. Sono come OVERLAY_UPDATED — niente virgolette, perché sono nomi di valori e non testo. Confrontali con == come confrontavi i numeri nella terza lezione.

Comandare. discPlay avvia o riprende. discPause si blocca sul fotogramma che si vede e lo lascia sullo schermo. discStop è quella più pesante: l’immagine viene sostituita dalla schermata blu, discGetFrame risponde 0 finché il disco non riparte, e discPause e le chiamate di salto vengono ignorate finché è fermo. Una qualunque tra discPlay, discSearch e discSkipToFrame lo rimette in moto.

Due chiamate mandano il disco a un fotogramma, e la differenza tra le due è l’unica cosa di questa lezione che valga la pena imparare a memoria:

  • discSearch(frame) ci va e lì si mette in pausa.

  • discSkipToFrame(frame) ci va e da lì riproduce.

Cerca quando vuoi parcheggiare su un’immagine e aspettare. Salta quando vuoi che cominci una scena. discSkipForward(30) e discSkipBackward(30) sono la stessa idea misurata da dove sei invece che dall’inizio, e lasciano il disco in riproduzione se era in riproduzione e in pausa se era in pausa.

C’è anche discPauseAtFrame, che fa esattamente quello che fa discSearch con un nome più vecchio. Il Riferimento lo segna come alias storico. Lo vedrai negli script degli altri; nei tuoi scrivi discSearch.

Aspettare è più difficile di quanto sembri

Ecco la frase di cui è fatto ogni gioco video:

Riproduci dal fotogramma 0 al fotogramma 120, poi fai una domanda al giocatore.

Prova a scriverla. Non puoi scrivere «riproduci, poi aspetta, poi chiedi», perché non hai nessun posto dove scriverlo. Hai onOverlayUpdate, che Singe chiama sessanta volte al secondo e che deve tornare subito, ogni singola volta. Una funzione che se ne stesse lì ad aspettare fermerebbe il motore di colpo: niente disegno, niente comandi, niente video.

Quindi non puoi dire «poi». Devi trasformare il «poi» in una variabile che ricorda a che punto sei arrivato, e controllarla in ognuna di quelle sessanta chiamate:

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

Funziona. Leggilo e vedi che funziona. Ma nota quanto è costato: una variabile, il cui unico lavoro è ricordare in quale parte della frase ti trovi, e due istruzioni if per tenerla in riga.

Ora aggiungi il resto della scena. Il giocatore risponde, quindi dopo parte una di due cose. Ognuna di queste finisce da qualche parte e fa un’altra domanda. Un modesto gioco a diramazioni ha quaranta di questi momenti, e ognuno vuole la sua variabile e il suo if. Finisci con uno script in cui la storia non è scritta da nessuna parte — è sparpagliata su una dozzina di flag, e per scoprire che cosa succede dopo il drago devi leggerli tutti.

Tieni a mente questo pensiero. La quindicesima lezione non è nient’altro che la soluzione.

Quando non c’è il video

Esegui di nuovo il tuo script nel modo semplice, senza -v:

Singe -R movie

Non va in crash niente. Ottieni una finestra nera con Frame 0 nell’angolo.

Vale la pena capirlo, perché è la metà rassicurante della promessa all’inizio di questa lezione. Un gioco senza disco esegue comunque ogni chiamata disc che fai; semplicemente non fanno niente di utile. Il motore documenta esattamente che cosa rispondono, e non cambia mai: discGetFrame e discGetFrameCount restituiscono 0, discGetState restituisce DISC_EJECTED, discGetWidth e discGetHeight restituiscono la dimensione del canvas, e discPlay, discPause, discSearch e le altre vengono annotate nel log e per il resto ignorate.

Non puoi rompere uno script chiamando una funzione del disco quando il disco non c’è.

Quando uno script ha bisogno di saperlo, chiede a SINGE_DISC. È un altro nome che il motore definisce prima che parta il tuo script, e vale true quando il gioco ha un video e false quando il mondo è un semplice canvas. È il modo giusto di scrivere un gioco che possa funzionare in tutti e due i modi:

    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 capovolge un valore vero o falso, come nella terza lezione.

Tutto insieme

Messo insieme, con una piccola funzione che trasforma lo stato in parole e un fotogramma su cui fermarsi, questo è lo script finito. È un cercatore di fotogrammi: lo strumento che userai ogni volta che incontri un nuovo video.

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 è lo stesso tipo di variabile di asking qui sopra, ed è qui per un motivo che puoi verificare: toglila, lascia if frame >= stopAt then discPause() end, e poi prova a premere la barra spaziatrice per andare oltre il fotogramma 400. Non ci riesci. Il disco riparte per un sessantesimo di secondo e il onOverlayUpdate successivo lo rimette in pausa, per sempre. held è il modo in cui dici «questo l’ho già fatto una volta».

Prova tu

  1. Trova il drago. Eseguilo, guarda il contatore e annota il fotogramma in cui il drago compare per la prima volta, quello in cui sputa fuoco e quello in cui la griglia si prende lo schermo. Questi tre numeri ti serviranno nella sedicesima lezione.

  2. Procedi un passo alla volta. Cambia discSkipForward(30) in discSkipForward(1) e tieni premuto il tasto freccia destra. Ora cambia stopAt in un fotogramma a metà del drago e usa discSearch e il tasto freccia per atterrarci esattamente.

  3. Fallo ripetere. Cambia la fermata in modo che invece di mettere in pausa al fotogramma 400 chiami discSkipToFrame(0). Hai costruito una modalità attract: una scena che si ripete per sempre finché qualcuno non preme un pulsante.

  4. Chiedi un fotogramma che non c’è. Cambia la riga di SWITCH_RIGHT in discSkipToFrame(100000). Non va in crash. Leggi la voce di discSkipToFrame nel Riferimento e trova la frase che dice perché.

  5. Giocaci senza il video. Esegui Singe -R movie e poi premi tutti i tasti. Niente di quello che premi può romperlo.

Rompilo apposta

L’errore che costa più tempo qui non è un errore di Lua. Esegui questo:

Singe -R -v menuBackground.mkv movie

Il percorso è sbagliato — parte dalla cartella di lavoro, e lì il video sta nella cartella Singe, non in giro da solo — e Singe non parte. Quello che fa invece è stampare l’intero elenco delle sue opzioni da riga di comando, cosa che la prima volta mette in allarme, e poi questa come ultimissima riga:

Error:  Unable to locate video.

Un muro di opzioni come quello vuol dire sempre la stessa cosa: il motore non è mai arrivato fino al tuo gioco. Ignora il muro e leggi l’ultima riga.

Quello è facile. La versione meno simpatica è eseguire senza nessun -v e dimenticarsi di averlo fatto. Non c’è nessun errore, perché un gioco senza video è un gioco perfettamente valido. Ottieni uno schermo nero e un contatore fermo su 0, e passi venti minuti a cercare il bug nel tuo script.

È a questo che serve il blocco SINGE_DISC nello script finito. Tre righe, e il gioco ti dice che cosa non va invece di tenere il muso. Metti un controllo come quello in ogni script che scrivi e che ha bisogno di un video.

Cosa hai imparato

  • Un gioco riproduce video solo quando lo chiede, e tutto il resto di Singe funziona allo stesso modo in entrambi i casi.

  • Singe chiama il video il disco. Un gioco ne ha uno, e le funzioni disc non prendono un handle perché non c’è niente tra cui scegliere.

  • Il video va sulla riga di comando con -v, non nello script.

  • L’overlay viene disegnato sopra l’immagine, e il filmato si vede dovunque non hai disegnato.

  • Un fotogramma è un’immagine ferma, contata da zero, e un numero di fotogramma è l’indirizzo di un momento.

  • discGetFrame chiede dove si trova il disco; discGetFrameCount dice quanti fotogrammi ci sono; discGetState dice che cosa sta facendo il disco.

  • discPlay, discPause e discStop lo comandano. discSearch va a un fotogramma e si mette in pausa; discSkipToFrame va a un fotogramma e riproduce.

  • Un disco che arriva in fondo riparte dal fotogramma zero senza dirtelo.

  • Senza disco ogni chiamata disc è innocua, e SINGE_DISC è il modo in cui uno script capisce in che tipo di gioco si trova.

  • Non puoi aspettare dentro onOverlayUpdate, quindi il «poi» deve essere scritto per esteso, come variabile.

La prossima volta

Quell’ultimo punto è quello dolente. Un gioco video è un elenco di passi — riproduci questo, chiedi quello, riproduci l’altro — e hai appena visto che il modello a callback non sa dire «poi» senza un flag e un if per ogni passo. La quindicesima lezione ti mostra l’altro modo in cui Singe ti lascia scrivere uno script, in cui «poi» è una riga nuova.

Lezione 15: L’altro modo di scriverlo

La lezione finita

Tutte le lezioni finora sono state scritte allo stesso modo. Scrivi funzioni il cui nome comincia con on, Singe le chiama quando gli pare, e tu non dici mai in che ordine succede qualcosa. Questo è il modello guidato dagli eventi, ed è così che funziona la maggior parte dei motori di gioco.

Singe ha un secondo modello. Con questo scrivi il tuo gioco come un elenco di passi, dalla prima riga all’ultima, e hai il permesso di aspettare. In questa lezione scriverai la stessa breve sequenza video in tutti e due i modi e vedrai la differenza con i tuoi occhi.

La sequenza

Ecco che cosa fa il gioco, in italiano:

  1. Fai partire il filmato dall’inizio e riproducilo fino al fotogramma 120.

  2. Fermati lì e chiedi al giocatore di premere la barra spaziatrice.

  3. Quando la preme, continua a riprodurre fino al fotogramma 300.

  4. Fermati lì, di' «The end.», aspetta quattro secondi ed esci.

Quattro passi. Rileggili e nota che ognuno contiene la parola «poi», detta o sottintesa.

Il modo che conosci

Crea un file chiamato events.singe nella cartella movie della quattordicesima lezione, e scrivi questo:

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()

Eseguilo. Dare il nome della cartella avvierebbe movie.singe, quindi dai invece il nome dello script, come ti ha mostrato la prima lezione:

Singe -R -v Singe/menuBackground.mkv movie/events.singe

Funziona. Fa esattamente i quattro passi. singeGetTicks è nuova — restituisce il numero di millisecondi trascorsi dall’avvio del motore, che è il modo normale di misurare un intervallo di tempo — e singeQuit termina il gioco, che è quello che il motore fa per te quando premi Esc.

Ora leggi lo script e prova a trovarci i quattro passi. Ci sono, ma rivoltati come un calzino. L’ordine della storia è scritto nei valori di step, non nell’ordine delle righe, e step viene impostata in una funzione e letta in un’altra. Per rispondere a «che cosa succede dopo che il giocatore preme spazio?» devi tenerti in testa tutto quanto in una volta.

E questa è la versione facile. Dentro ci sono due decisioni.

L’altro modo

Crea un nuovo file, steps.singe, e scrivi questo:

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")

Eseguilo allo stesso modo, finendo con movie/steps.singe. Fa le stesse quattro cose.

Ora leggi singeMain. I quattro passi sono i quattro paragrafi, in ordine, dall’alto in basso, e non c’è nessuna variabile step da nessuna parte, perché il punto in cui sei nella storia è il punto in cui sei nella funzione. Questo è tutto il senso della lezione.

Cos’è appena successo

function singeMain()

singeMain è un nome che Singe cerca, come onOverlayUpdate. Se il tuo script la definisce, il framework esegue il tuo gioco a partire da lì: viene chiamata una volta, all’inizio, e il tuo gioco dura quanto dura. Quando la funzione finisce, il gioco si chiude.

        singeYield()

Questa è la chiamata che rende tutto possibile, e vuol dire «lascia che passi un fotogramma».

Singe non sta facendo due cose contemporaneamente — qui niente gira in parallelo, qualunque cosa suggerisca la parola threaded. Quello che succede è che singeYield ferma la tua funzione nel punto in cui si trova, restituisce il controllo al motore e si ricorda il punto esatto. Il motore disegna il fotogramma, legge i comandi, fa avanzare il video, e poi fa ripartire la tua funzione dalla riga dopo il singeYield, con ogni variabile esattamente come l’avevi lasciata.

Quindi un ciclo while con dentro un singeYield è un modo di aspettare. È l’unico modo di aspettare, e devi metterne uno in ogni ciclo che sta aspettando qualcosa. È un patto che fai con il motore: puoi startene seduto ad aspettare, purché gli restituisca il fotogramma sessanta volte al secondo.

local function playTo(frame)
    while discGetFrame() < frame do
        drawFrame()
        singeYield()
    end
end

Singe non ha una funzione «aspetta finché il video arriva al fotogramma 120». Non gliene serve una, perché puoi scriverla in quattro righe, e l’hai appena fatto. Continua finché il disco non è arrivato al fotogramma che vuoi; restituisci un fotogramma a ogni giro.

waitForButton ha la stessa forma con una domanda diversa, e waitSeconds ha di nuovo la stessa forma, con un orologio. Tre piccole funzioni, scritte una volta sola, e grazie a loro singeMain si legge come le frasi in italiano all’inizio della lezione. È proprio a questo che, come diceva la quinta lezione, servono le funzioni tutte tue.

        drawFrame()
        singeYield()

Ogni ciclo di attesa disegna prima di cedere il controllo, ed è questa la parte che sorprende la gente. Nel modello a thread non c’è una onOverlayUpdate tua, quindi niente viene disegnato se non lo disegni tu. Quello che disegni prima di un singeYield è ciò che compare in quel fotogramma. Smetti di disegnare e l’overlay smette di cambiare.

Ecco perché esiste message. singeMain la imposta, drawFrame la stampa, e i tre cicli di attesa chiamano tutti drawFrame. È un prezzo piccolo per riavere la storia in ordine.

dofile("Singe/Framework.singe")

In fondo. Questo conta più di qualsiasi altra cosa nella lezione, quindi vale la pena sapere perché.

dofile esegue un altro script dentro il tuo, e una delle cose che fa il framework mentre viene eseguito è cercare una funzione chiamata singeMain. Se ne trova una, costruisce il tuo gioco intorno a lei e scrive una onOverlayUpdate tutta sua, il cui unico compito è far ripartire la tua singeMain una volta per fotogramma. Se non la trova, non fa niente del genere, e il tuo gioco è un normale gioco guidato dagli eventi.

Quindi il framework va caricato dopo che singeMain esiste. Caricalo in cima, come hai fatto in ogni lezione dalla settima in poi, e nel momento in cui guarda non c’è ancora nessuna singeMain, e ottieni un gioco senza il gioco dentro.

Le regole

Sono quattro, e insieme coprono ogni errore che puoi fare qui.

Il framework va per ultimo. Per il motivo appena visto.

Non scrivere una tua onOverlayUpdate. Il framework ne ha già scritta una, e ce ne può essere una sola: vince quella scritta per ultima, e l’altra viene buttata via senza una parola. Se la tua sta sopra il dofile, sparisce la tua e i tuoi disegni non compaiono mai. Se sta sotto, sparisce quella del framework e la tua singeMain non viene più eseguita. Disegna invece dall’interno di singeMain.

Ogni ciclo che aspetta ha bisogno di un singeYield. Un ciclo senza non restituisce mai il fotogramma. La finestra smette di ridisegnarsi, smette di rispondere, e il gioco è andato; per uscirne devi chiudere il terminale. Non c’è nessun messaggio di errore, perché dal punto di vista del motore la tua funzione non ha ancora finito.

Quando singeMain finisce, il gioco si chiude. Il che è comodo quando lo vuoi e una sorpresa quando non lo vuoi. Un gioco che deve andare avanti per sempre finisce con un ciclo da cui non si esce mai:

    while true do
        drawFrame()
        singeYield()
    end

I comandi arrivano lo stesso

Guarda di nuovo dove viene impostata pressed:

function onInputPressed(what)
    if what == SWITCH_BUTTON1 then
        pressed = true
    end
end

Quella è una callback, in uno script scritto come un elenco di passi. I due modelli sono in funzione insieme, ed è voluto.

Quando esiste singeMain, ti viene tolta solo onOverlayUpdate. Tutte le altre — onInputPressed, onInputReleased, onKeyPressed, onSoundCompleted, onShutdown, tutte quante — vengono chiamate esattamente come prima, negli intervalli tra uno yield e l’altro. Quindi il modo normale di scrivere un gioco con questo modello è quello che hai appena usato: la storia in singeMain, e una piccola callback che coglie un evento e lascia un biglietto che la storia troverà.

waitForButton imposta pressed a false prima di cominciare ad aspettare, e così butta via qualunque cosa il giocatore abbia pestato prima. Togli quella riga e un pulsante premuto durante il video conta come la risposta a una domanda che non è ancora stata fatta.

Quale usare

Nessuno dei due modelli è il migliore. Servono a lavori diversi, e un vero gioco usa quello che va meglio.

Il modello a thread è adatto a tutto ciò che è una sequenza. Riproduci questo, poi chiedi, poi riproduci quello. Un’introduzione. Un filmato di intermezzo. Un tutorial. Uno scontro con un boss in tre fasi. Qualunque cosa descriveresti spontaneamente come un elenco numerato è una singeMain che aspetta di essere scritta, e il video è la cosa più sequenziale che ci sia, ed è per questo che la terza parte ci arriva qui.

Il modello guidato dagli eventi è adatto a tutto ciò che è una situazione. Dieci nemici e un giocatore, tutti in movimento, tutti che si scontrano, nessuno in un ordine preciso. Il gioco che hai scritto nella settima lezione non contiene nessuna sequenza: ogni fotogramma è la stessa domanda fatta di nuovo, che è esattamente la forma di onOverlayUpdate. Scrivilo come un elenco di passi e non guadagni niente, e perdi in chiarezza.

Quando un gioco è tutte e due le cose — e quasi tutti lo sono — si scrive in tutti e due i modi. singeMain attraversa i livelli in ordine, e dentro ogni livello un ciclo fa il lavoro della settima lezione sessanta volte al secondo, finché il livello non finisce.

Prova tu

  1. Aggiungi un passo. Dopo waitForButton, fai invece tornare indietro il filmato: discSkipToFrame(0), poi playTo(60), poi continua come prima. Due righe nuove in un posto solo, e nient’altro nello script deve saperlo.

  2. Aggiungi lo stesso passo all’altro. Ora fallo in events.singe. Conta quanti punti hai dovuto toccare.

  3. Scrivi waitFrames. Una quarta funzione di aiuto, accanto alle altre tre, che aspetta un certo numero di fotogrammi di video invece di un certo numero di secondi. Usa discGetFrame e ricordati da dove sei partito.

  4. Togli uno yield. Cancella il singeYield() dentro playTo ed eseguilo. Tieniti pronto a chiudere il terminale, perché nient’altro lo ferma. Ora rimettilo e cancella invece drawFrame(), e da quello che vedi capisci perché il contatore dei fotogrammi si ferma ma il filmato no.

  5. Fanne un ciclo. Metti tutta singeMain dentro while true do …​ end così la sequenza ricomincia invece di uscire. Esc ti fa ancora uscire, perché quello non è mai stato compito tuo.

Rompilo apposta

Sposta la riga dofile("Singe/Framework.singe") dal fondo di steps.singe alla cima, ed eseguilo.

Non c’è nessun errore. Non viene stampato niente. La finestra si apre, il primo fotogramma del filmato resta lì, e non succede mai nient’altro.

Questo è il tipo di bug peggiore, ed è il motivo per cui vale la pena incontrarlo apposta. Dal punto di vista del motore non è andato storto niente: il tuo script è stato caricato, il framework è stato caricato, e nessuno dei due ha definito una onOverlayUpdate, quindi il motore non ha niente da chiamare. Il disco è fermo al fotogramma uno, in pausa, esattamente come l’ha lasciato il motore, perché il discPlay che l’avrebbe fatto partire sta dentro una singeMain che nessuno esegue mai.

Quando un gioco a thread non fa proprio niente, guarda prima l’ultima riga del file. È quasi sempre quella.

Cosa hai imparato

  • Singe ha due modi di scrivere uno script, e scegli definendo singeMain oppure no.

  • Nel modello a thread il tuo gioco è un elenco di passi e va dall’alto in basso.

  • singeYield() restituisce un fotogramma al motore e continua dalla riga successiva.

  • Aspettare è un ciclo while con dentro un singeYield. La funzione di attesa che ti serve la scrivi tu; il motore non ne fornisce una.

  • Niente viene disegnato se non lo disegni tu, prima di uno yield, a ogni fotogramma.

  • dofile("Singe/Framework.singe") va alla fine di uno script a thread.

  • Non scrivere una tua onOverlayUpdate quando esiste singeMain.

  • Tutte le altre callback vengono ancora chiamate, quindi eventi e passi si mescolano liberamente.

  • Quando singeMain finisce, finisce il gioco.

  • Le sequenze vogliono il modello a thread; le situazioni quello guidato dagli eventi.

La prossima volta

Ora sai scrivere «riproduci questo, poi chiedi, poi riproduci quello» in tre righe. Un gioco video a diramazioni non è altro che quella frase, qualche centinaio di volte, con le risposte che decidono quale riga viene dopo. La sedicesima lezione ne costruisce uno, e la parte interessante si rivela non essere affatto il video. È tenere la mappa di che cosa porta dove in una forma che riesci ancora a leggere quando il gioco ha quaranta scene.

Lezione 16: Diramazioni

La lezione finita

Un gioco video a diramazioni è un film con dei bivi. Una scena va avanti, il giocatore sceglie, e dopo va avanti una scena diversa. Fallo venti o trenta volte e hai un gioco che la gente rigiocherà per anni cercando il finale che non ha ancora visto.

In questa lezione ne costruirai uno. Ha quattro scene, due scelte, un timer per ogni scelta, una morte e tre vite. Il codice che lo fa girare è di una trentina di righe, e resterebbe di una trentina di righe anche se il gioco avesse duecento scene — perché il gioco in sé non sarà affatto scritto nel codice.

Immagina che sia un drago

Il video che hanno tutti è Singe/menuBackground.mkv, gli stessi 420 fotogrammi che guidi dalla quattordicesima lezione. È una palla di fuoco, un drago di carta, la parola SINGE, e poi una griglia magenta che scorre via per sempre sotto un sole arancione.

Non è un dramma. Non c’è nessuno dentro che possa essere in pericolo, e al tramonto non importa che cosa decidi.

Sta' al gioco lo stesso. Per due minuti il drago è abbastanza vero, e tutto quello che stai per scrivere funziona esattamente allo stesso modo quando il filmato è uno stuntman che cade da una scogliera. Ecco la mappa, e i numeri dei fotogrammi sono quelli che hai trovato da solo nella quattordicesima lezione:

Scena Fotogrammi Che cosa succede

arrive

da 0 a 119

Fuoco, e il drago atterra. Sinistra o destra?

sunset

da 120 a 259

Sputa fuoco. Ti abbassi a sinistra o corri a destra?

pit

da 260 a 339

Vieni mangiato. Perdi una vita.

escape

da 340 a 410

La griglia scorre via e ne sei uscito.

La sinistra è sempre la scelta giusta, per così dire: a sinistra da arrive si va a sunset, a sinistra da sunset si arriva a escape. A destra si finisce nel pit tutte e due le volte, e lo stesso succede se ci metti troppo.

La mappa è fatta di dati, non di codice

Ecco tutto il gioco, ed è una tabella.

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 tabella con dei nomi sulla sinistra invece dei numeri, esattamente come nella sesta lezione, e ogni valore che contiene è un’altra tabella. Ognuna di quelle tabelle interne è un record: una scena, descritta campo per campo.

scenes.arrive è la prima scena. scenes.arrive.first vale 0. scenes.arrive.left è la stringa "sunset", che è il nome di un’altra scena nella stessa tabella — ed è così che si scrivono i bivi. Una scena non contiene la scena che viene dopo. Contiene il nome della scena che viene dopo, e il nome viene cercato quando arriva il momento.

I campi vogliono dire questo:

first e last

I fotogrammi tra cui va la scena.

ask

Il fotogramma in cui compare la domanda. Il giocatore ha da ask a last per rispondere, e questo è il timer.

prompt

Che cosa dice la domanda.

left e right

La scena a cui porta ciascuna risposta.

goesTo

Dove va la scena quando nessuno ha scelto — perché il giocatore ha finito il tempo, o perché una domanda non c’era proprio. Per pit, che è una morte, è il punto a cui torna il nuovo tentativo.

death

Presente, e true, solo in una scena che costa una vita.

Su quella tabella vale la pena notare tre cose.

La prima è che è il documento di progetto. Puoi darla a qualcuno che non ha mai scritto una riga di Lua e ci leggerà dentro il gioco. Quando vuoi che il drago si divida in tre strade, aggiungi un campo. Quando vuoi un’altra scena, aggiungi un altro record. Non vai a cercare il codice che riproduce le scene, perché non lo cambi.

La seconda è che i record non hanno tutti la stessa forma. pit non ha ask, né prompt, né left — dentro non c’è niente da scegliere. escape non ha goesTo, perché è la fine e non porta da nessuna parte. Un campo che non c’è in una tabella si legge come nil, che è la parola che hai incontrato nella terza lezione per «lì non c’è niente», e chiedere scenes.escape.goesTo non è un errore. È nil, e nil è una risposta. Il codice che legge questi record deve essere pronto a riceverla, e tra un minuto vedrai l’unica riga che lo è.

La terza è quello che la tabella non contiene: niente lì dentro disegna, riproduce o aspetta. È una descrizione. Questa separazione è tutto il trucco della lezione.

Una funzione che riproduce qualsiasi scena

Questa è la metà fatta di codice, e c’è una sola funzione di una certa lunghezza. È scritta con il modello a thread della quindicesima lezione, perché un gioco a diramazioni è la cosa più sequenziale che ci sia.

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

Prende il nome di una scena, la riproduce e restituisce il nome della scena che viene dopo. Questo è tutto il suo contratto, e il gioco a quel punto sono tre righe:

function singeMain()
    local scene = "arrive"

    while scene ~= nil do
        scene = playScene(scene)
    end
    waitForGo(ending .. "  Space to quit.")
end

Comincia da arrive. Riproduci la scena che hai in mano, e tieni in mano quella che ti restituisce. Quando ti restituisce nil non c’è una scena successiva, il ciclo finisce e la partita è finita.

Tutto insieme

Crea dragon.singe nella tua cartella movie e scrivici questo. È lo script più lungo del libro finora, e ogni suo pezzo è stato spiegato, tranne le due piccole funzioni di aiuto, che vengono dopo.

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")

Eseguilo:

Singe -R -v Singe/menuBackground.mkv movie/dragon.singe

Giocaci quattro o cinque volte. Va' a sinistra due volte ed esci. Va' a destra e fatti mangiare. Resta con le mani in mano e fatti mangiare lo stesso. Perdi tutte e tre le vite.

Cos’è appena successo

    discSkipToFrame(scene.first)
    while discGetFrame() < scene.last do

Una scena è un salto seguito da un’attesa, cioè lo schema della quindicesima lezione con i numeri che escono dal record invece di essere scritti a mano. discSkipToFrame va a un fotogramma e riproduce da lì, ed è proprio questo un cambio di scena.

Il numero del fotogramma è giusto nell’istante in cui la chiamata ritorna, quindi il while non pensa mai di essere ancora nella scena che hai appena lasciato.

        local asking = scene.ask ~= nil and frame >= scene.ask

L’unica riga pronta per un campo che manca, e il motivo per cui la scena della morte può fare a meno di ask.

and vuol dire che tutte e due le metà devono essere vere, come nella terza lezione, e Lua controlla prima la metà di sinistra. Se scene.ask è nil la metà di sinistra è falsa, Lua si ferma lì, e il confronto a destra non avviene mai. Ed è meglio così, perché confrontare nil con un numero è un errore, e lo incontrerai alla fine di questa lezione.

asking è la risposta a «la domanda è sullo schermo in questo momento?», calcolata una volta per fotogramma e usata tre volte.

        if not asking then
            answer = nil
        elseif answer == "left" or answer == "right" then
            return scene[answer]
        end

Finché la domanda non c’è, qualunque cosa prema il giocatore viene buttata via. Deve esserlo, altrimenti un giocatore che si appoggia sulla freccia sinistra durante il filmato risponde a una domanda che non ha letto.

Una volta che la domanda c’è, una risposta fa finire subito la scena. return scene[answer] merita una seconda occhiata: answer contiene la stringa "left" o "right", e scene["left"] è la stessa cosa di scene.left. Mettere il nome tra parentesi quadre invece che dopo un punto ti permette di cercare un campo il cui nome sta in una variabile. Due righe di codice per tutte e due le risposte, e con cinque risposte sarebbero ancora due righe.

Il ramo elseif spiega anche perché passano solo "left" e "right". La barra spaziatrice imposta answer a "go", e scene["go"] è nil, quindi una barra spaziatrice premuta per sbaglio durante una domanda farebbe finire il gioco in silenzio. Di' che cosa accetti.

    discPause()

Subito dopo il ciclo, ed è facile dimenticarlo. La scena è arrivata al suo ultimo fotogramma, ma il disco non ha idea che la scena sia finita — va avanti dritto in qualunque filmato si trovi dopo nel file, che in un gioco vero è il mezzo di una scena di tutt’altra parte. Fermalo nell’istante in cui smetti di volerlo.

    if scene.death then
        lives = lives - 1

scene.death è nil per ogni scena tranne pit, e in un if nil conta come falso, quindi questo si legge «se questa scena era una morte». Non devi scrivere death = false negli altri tre record, e non dovresti: l’assenza del campo lo dice altrettanto bene, e così c’è un solo posto che decide quali scene sono mortali.

Il nuovo tentativo sono le due righe sotto. Togli una vita e, se ne restano, fermati sul fotogramma e aspetta la barra spaziatrice. Poi return scene.goesTo rimanda il giocatore ad arrive, ed è il record a saperlo. Cambia goesTo in "sunset" e il nuovo tentativo diventa un checkpoint invece di una ripartenza da capo — una parola, e la difficoltà del gioco cambia.

        overlayPrint(2, 6, math.ceil((scene.last - frame) / FPS) .. " seconds left.")

Il timer. scene.last - frame è quanti fotogrammi restano, e dividerlo per i fotogrammi in un secondo lo trasforma in secondi. math.ceil arrotonda un numero per eccesso all’intero successivo, quindi il conto alla rovescia dice 3, 2, 1 e mai 0.4 o 2.966666.

FPS vale 30 perché questo video va a poco più di trenta fotogrammi al secondo. È l’unico numero dello script che è una stima, ed è una stima con un nome in cima al file invece di un 30 sepolto in mezzo a una riga, così quando cambi video c’è esattamente una cosa da cambiare.

Nota rispetto a che cosa si misura il timer: il filmato. Il giocatore fa a gara con il video, non con un orologio, quindi la domanda non può mai durare più dell’inquadratura a cui appartiene. È per questo che i giochi a diramazioni contano in fotogrammi.

Perché non scriverlo tutto a mano

Potresti scrivere questo gioco come un’unica lunga funzione. Riproduci i fotogrammi da 0 a 119; se sinistra, riproduci da 120 a 259; se di nuovo sinistra, riproduci da 340 a 410; altrimenti riproduci da 260 a 339, togli una vita, torna all’inizio. Con quattro scene sarebbe più corto di quello che hai.

Con quaranta scene sarebbe un disastro, e vale la pena essere precisi sul perché.

I numeri dei fotogrammi sarebbero sparsi per tutto il codice, ognuno scritto una volta e mai con un nome, quindi cambiare il punto in cui comincia una scena vorrebbe dire trovare ogni posto in cui è nominata. La forma della storia sarebbe sepolta nella forma delle istruzioni if, quindi nessuno potrebbe vedere il gioco senza leggerlo tutto. E aggiungere una scena vorrebbe dire modificare il codice che riproduce, cioè il codice che già funziona — ogni nuova scena un’altra occasione per romperne una vecchia.

La versione che hai scritto ha un pezzo di codice che riproduce le scene e un pezzo di dati che dice quali sono le scene. Aggiungere una scena tocca solo i dati. Vale la mezz’ora in più che ci è voluta, ed è la stessa idea che sta sotto il file games.dat della tredicesima lezione: descrivi la cosa, poi scrivi un pezzo di codice che legge la descrizione.

Prova tu

  1. Aggiungi un finale. Da' a escape una domanda e una seconda scena finale che riusa fotogrammi da qualche parte del filmato. Cambia solo la tabella.

  2. Rendilo equo. Abbassa ask in tutte e due le scene così il giocatore ha cinque secondi invece di tre, poi alzalo così ne ha uno. Trova il numero che useresti davvero nel gioco finito.

  3. Sposta il checkpoint. Cambia il goesTo di pit in "sunset" e giocaci. Poi pensa a che cosa succede se un giocatore muore in arrive — e se la scena della morte dovrebbe sapere da dove è arrivata invece di sentirselo dire.

  4. Conta quello che il giocatore ha visto. Aggiungi una tabella accanto a scenes che registra quali nomi di scena sono stati riprodotti, e mostra il conto nell’angolo. Adesso hai un gioco che può dire «hai trovato tre finali su cinque».

  5. Rompi la mappa. Cambia il left di arrive in "cave", una scena che non esiste. Eseguilo, va' a sinistra e leggi che cosa dice Lua. Quell’errore è il più comune in un gioco guidato dai dati, e conoscerne la forma ti fa risparmiare un’ora.

Rompilo apposta

Togli la guardia dalla riga di asking, così diventa:

        local asking = frame >= scene.ask

Eseguilo e va' a destra. La scena arrive va bene, perché arrive ha un ask. Poi comincia la scena pit, che non ce l’ha, e il gioco si ferma con questo:

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'

Leggilo come ti ha insegnato la prima lezione. Prima vengono il file e la riga, e sono esattamente giusti: la riga 68 è quella che hai appena cambiato. La lamentela è il resto: hai chiesto a Lua se un numero era maggiore di nil, e Lua non ne ha idea. scene.ask è nil perché il record pit non ha un campo ask, e un campo che non c’è è nil.

Una parte di quel messaggio merita una spiegazione, perché è una bugia per omissione. La funzione nominata è onOverlayUpdate, che non hai scritto tu. È quella del framework, quella che secondo la quindicesima lezione viene installata per far andare la tua singeMain. L’errore è uscito passando da lì, quindi quello è il nome che il motore aveva sotto mano, e il traceback sotto — l’elenco delle funzioni che erano in esecuzione, dalla più interna — può mostrare soltanto il framework che passa avanti il tuo errore. Ignorali tutti e due. Il file e la riga in cima sono tuoi, e sono quelli veri.

Cosa hai imparato

  • Un gioco a diramazioni è un insieme di scene, ognuna delle quali nomina le scene che vengono dopo.

  • Tieni le scene come dati — una tabella di record — e il codice che le riproduce resta una sola funzione per quanto grande diventi il gioco.

  • Un record contiene il nome della scena successiva, non la scena, e il nome viene cercato quando serve.

  • Un campo che non c’è in un record è nil, che non è un errore, e il codice che legge i record se lo deve aspettare.

  • scene[answer] cerca il campo il cui nome sta in una variabile; scene.left e scene["left"] sono lo stesso campo.

  • Metti il timer sul video: una scelta dura da un fotogramma a un altro, quindi non può mai durare più della sua inquadratura.

  • Butta via qualunque cosa il giocatore abbia premuto prima che comparisse la domanda.

  • Metti in pausa il disco nell’istante in cui una scena finisce, o va avanti nel filmato della scena successiva.

  • Un campo mancante che sta per falso — death in tre record su quattro — mantiene la descrizione breve e onesta.

  • Confrontare nil con un numero è un errore, e and è il modo per evitarlo.

La prossima volta

Il tuo gioco chiede sinistra o destra. Le macchine da sala giochi in cui è cresciuto questo genere di gioco chiedevano qualcosa di più difficile: punta la cosa sullo schermo e sparale. La diciassettesima lezione parla di pistole ottiche — dove sta mirando il giocatore, che cosa ne fa il gioco, e la calibrazione di cui un vero cabinato non può fare a meno.

Lezione 17: Pistole ottiche

La lezione finita

Stai per fare un tiro a segno. I bersagli compaiono sopra il video nei fotogrammi che scegli tu, tu miri allo schermo e premi un grilletto, e quelli che colpisci fanno punti.

Per scriverlo non ti serve una pistola ottica. Ti serve un mouse, perché per Singe una pistola ottica è un mouse: riporta una posizione nelle stesse coordinate, attraverso le stesse chiamate, e il suo grilletto arriva come lo stesso interruttore di un pulsante del mouse. Scrivi il gioco per il mouse sulla tua scrivania e funziona su un cabinato con una pistola imbullonata sopra, ed è l’unico modo sensato di farlo. Una pistola non è un tipo diverso di comando. È un mouse che qualcuno ha puntato.

A che cosa stai mirando

Comincia come nella quattordicesima lezione, con il video che il motore ha estratto per te:

Singe -R -v Singe/menuBackground.mkv gallery

Quel filmato è una griglia viola e un tramonto. Non è una rapina in banca. Ogni numero di fotogramma di questa lezione si riferisce a lui, così il codice funziona il giorno stesso in cui lo scrivi, e tutto lo spezzone è 720 per 480 e lungo circa 420 fotogrammi, che a circa trenta fotogrammi al secondo fanno quattordici secondi. Immagina un filmato migliore. Al codice non importa che cosa c’è nell’immagine.

Adatta l’overlay al video

Metti questo in cima a gallery.singe, sotto la riga del dofile:

overlaySetResolution(discGetWidth(), discGetHeight())

Senza quella chiamata l’overlay è metà del video in ciascuna direzione — qui 360 per 240 — e ogni coordinata con cui disegni, e ogni posizione del mouse che ricevi, sta in quello spazio più piccolo. Non c’è niente di sbagliato nell’overlay piccolo, ma è una conversione in più da tenere a mente mentre cerchi di capire dove è finito un colpo. Adattarlo al video vuol dire che un bersaglio a x = 80 sta a ottanta pixel dal bordo dell’immagine, e lo stesso vale per un colpo a x = 80. La voce del Riferimento su overlaySetResolution spiega quanto costa.

Dove punta la pistola

Lo dice una sola chiamata:

local x, y = mouseGetPosition(0)

mouseGetPosition restituisce due numeri, cosa che non hai ancora visto fare a una funzione e che a Lua va benissimo: una funzione può restituire tutti i valori che vuole, e tu li prendi elencando altrettanti nomi a sinistra del segno =. Lo 0 dice quale dispositivo di puntamento ti interessa, contando da zero. Con un mouse solo, o una pistola sola, la risposta è sempre il dispositivo 0.

I numeri sono in coordinate dell’overlay, non in pixel del desktop, ed è per questo che valeva la pena fare la chiamata di prima. La posizione è l’ultima che il dispositivo ha riportato, quindi puoi chiederla quando vuoi, tutte le volte che vuoi. Chiedila in onOverlayUpdate e disegna con la risposta.

C’è un altro modo di avere gli stessi numeri. onMouseMoved è una callback, come onOverlayUpdate, e il motore la chiama ogni volta che un puntatore si muove, passandole la nuova posizione. È la scelta giusta quando vuoi reagire al movimento. Per disegnare un mirino non lo vuoi: vuoi sapere dov’è la cosa in questo momento, e mouseGetPosition te lo dice senza che tu debba tenerne una copia.

Disegnare un mirino

Il motore non te lo disegna. Un mirino è quattro linee e un cerchio:

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

Gli spazi vuoti contano più delle linee. Fermare i quattro raggi prima del cerchio ti lascia un buco nel mezzo da cui vedere il bersaglio, che è tutto lo scopo di un mirino e la prima cosa che i principianti coprono disegnandoci sopra.

Una cosa che dovresti chiedere prima di disegnarlo:

local drawAim = singeWantsCrosshairs()

Restituisce false quando il giocatore ha avviato Singe con --nocrosshair. Alcune pistole ottiche mettono sullo schermo un loro puntino, e due mirini a pochi pixel l’uno dall’altro sono peggio di nessuno. La risposta non può cambiare mentre il gioco gira, quindi leggila una volta all’inizio e tienila in una variabile.

Non devi nascondere il puntatore di sistema, perché Singe l’ha già fatto. Si prende il mouse all’avvio, il che lo confina nella finestra e nasconde la freccia del desktop. Se mai lo rivuoi — per un editor di livelli, per dire — mouseSetCaptured(false) lo rilascia, e il tasto assegnato a INPUT_GRAB, che nei comandi forniti è G, fa la stessa cosa avanti e indietro mentre giochi.

Il grilletto

Un grilletto è un pulsante, e i pulsanti arrivano a onInputPressed, che hai incontrato per la prima volta nella terza lezione:

function onInputPressed(what, device)
    if what ~= SWITCH_BUTTON3 then
        return
    end

    local x, y = mouseGetPosition(device or 0)
    -- ...
end

SWITCH_BUTTON3 è il pulsante sinistro del mouse, e su una pistola è il grilletto. Il controls.cfg fornito assegna il pulsante sinistro a SWITCH_BUTTON3, il destro a SWITCH_BUTTON1 e quello centrale a SWITCH_BUTTON2. Quei numeri sembrano mescolati perché lo sono: gli interruttori sono i pulsanti del pannello da sala giochi, e quale comando fisico sia collegato a quale è affare del cabinato, non del gioco. Anche Maiusc sinistro è assegnato a SWITCH_BUTTON3, così puoi sparare senza mouse mentre fai le prove.

La parte nuova è il secondo argomento. Quando l’interruttore arriva da un mouse o da una pistola ottica, device è l’indice di quel dispositivo — 0 per il primo, 1 per il secondo e così via. Quando arriva da un tasto o da un controller è nil, perché non c’era di mezzo nessun dispositivo di puntamento. Ecco perché la chiamata sopra dice device or 0: se device è nil, usa 0 al suo posto. Userai or così di continuo, e si legge esattamente come suona — «device, oppure niente, e in quel caso zero».

Quell’unico argomento in più è ciò che rende possibile un cabinato con due pistole. La pistola del primo giocatore è il dispositivo 0 e quella del secondo è il dispositivo 1, e la stessa onInputPressed le distingue senza che tu debba indovinare.

Ha colpito qualcosa

Sai già come rispondere. È l’undicesima lezione:

if collidePointRect(x, y, target.x, target.y, TARGET_SIZE, TARGET_SIZE) then

Un colpo è un punto. Un bersaglio è un rettangolo. collidePointRect chiede se il punto sta dentro il rettangolo, e il bordo conta come dentro. Sparare non ha niente di speciale. La verifica dei colpi di un gioco di pistole è la stessa che usa un platform per scoprire se sei atterrato su un blocco, e la famiglia collide del Riferimento ha il resto delle forme.

Bersagli che vanno e vengono

L’unica cosa che il video cambia è quando esiste un bersaglio. Nell’undicesima lezione una roccia restava lì finché non le sparavi. Qui un bersaglio è sullo schermo mentre il filmato mostra la parte della scena a cui appartiene, e poi sparisce, che tu gli abbia sparato o no.

Sono due campi in più nel record, e la sesta lezione ti ha dato lo strumento:

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 },
}

Quattro record, ognuno con il fotogramma in cui compare il bersaglio, il fotogramma in cui se ne va, e il punto in cui si trova. Aggiungere un quinto bersaglio vuol dire aggiungere una riga. È la forma a cui ricorrere ogni volta che ti accorgi che stai per scrivere le stesse quattro righe di codice con numeri diversi dentro.

Se un bersaglio conta o no è allora una piccola funzione tutta sua:

local function targetIsUp(target, frame)
    return not target.hit and frame >= target.first and frame <= target.last
end

Glielo chiede il disegno, e glielo chiede lo sparo, ed è proprio questo il motivo per metterlo in un posto solo: un bersaglio che vedi e un bersaglio che puoi colpire non possono mai essere in disaccordo.

Tutto insieme

-- Impara a programmare con Singe -- Lezione 17: Pistole ottiche

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()

Mira a un riquadro giallo e fai clic. Il contatore nell’angolo sale, un anello bianco si apre dove hai colpito, e il riquadro sparisce. Se manchi, sale solo il conto dei colpi sparati, che è il tabellone più economico che ci sia e dice a un giocatore come se la sta cavando più di quanto faccia il punteggio. Il giro ricomincia da solo quando il filmato finisce, e 1 lo fa ricominciare quando vuoi.

Cos’è appena successo

local frame = discGetFrame()

if frame >= LAST_FRAME then
    startRound()
    frame = FIRST_FRAME
end

Il video è l’orologio, come nella quattordicesima lezione, e discGetFrame è il modo in cui lo leggi. Tutto il resto del fotogramma si decide a partire da quel numero. Quando il filmato supera la fine dell’ultimo bersaglio, il giro ricomincia: startRound azzera il punteggio, segna tutti i bersagli come non colpiti e rimanda il disco all’inizio con discSkipToFrame. La riga sotto imposta anche la copia locale di frame, perché è stata letta prima del salto e contiene ancora il numero vecchio. Senza quella riga, il disegno qui sotto passerebbe un fotogramma a lavorare con un numero che non è più vero.

    shots = shots + 1

    for _, target in ipairs(targets) do
        if targetIsUp(target, frame) and collidePointRect(...) then

Conta il colpo prima di cercare un bersaglio colpito, così conta anche un colpo a vuoto. Poi scorri l’elenco. Il return dentro il ciclo si ferma al primo bersaglio colpito, il che vuol dire che un proiettile non può prendere due bersagli sovrapposti — una regola che devi decidere in un senso o nell’altro, e questa è la riga che la decide.

overlayBox(target.x, target.y, target.x + TARGET_SIZE - 1, target.y + TARGET_SIZE - 1)

overlayBox vuole due angoli opposti, non un angolo e una dimensione, quindi l’angolo lontano è quello vicino più la dimensione. Il - 1 c’è perché tutti e due gli angoli sono inclusi: un riquadro da 80 a 175 è largo novantasei pixel. collidePointRect invece vuole un angolo e una dimensione, ed è per questo che lì TARGET_SIZE entra da solo e qui sommato all’angolo. Confondere le due cose è un bug davvero comune, e si vede come bersagli che puoi colpire un po' fuori da dove sono disegnati.

if flash > 0 then
    colorForeground(255, 255, 255, 255)
    overlayCircle(flashX, flashY, 30 - flash * 2)
    flash = flash - 1
end

flash è un conto alla rovescia in fotogrammi, messo a dodici quando un colpo va a segno e diminuito di uno ogni volta che lo schermo viene disegnato. Siccome il raggio è calcolato a partire dal conto alla rovescia, l’anello si allarga mentre il numero si rimpicciolisce. Dodici fotogrammi sono meno di mezzo secondo. Una reazione che dura più di così smette di sembrare una conseguenza del grilletto e comincia a sembrare il tempo che fa.

Due pistole

Sei a due modifiche da un cabinato per due giocatori, e nessuna delle due sta nel ciclo del gioco.

La prima è mouseSetMode(MOUSE_MANY), che dice a Singe di leggere ogni dispositivo per conto suo invece di riunirli tutti in un unico cursore. mouseHowMany() dice quanti ne ha trovati all’avvio, quindi di solito un gioco lo chiede prima di impegnarsi:

if mouseHowMany() >= 2 then
    mouseSetMode(MOUSE_MANY)
end

Dopo di che, mouseGetPosition(1) è la seconda pistola, e l’argomento device di onInputPressed dice quale pistola ha sparato. Tieni due mirini, due punteggi e un solo elenco di bersagli, e hai un gioco cooperativo.

La seconda modifica non sta affatto nel tuo script. Il controls.cfg fornito collega solo i pulsanti del primo mouse, quindi il grilletto della seconda pistola non arriva da nessuna parte. Un cabinato con due pistole ha bisogno in quel file di una riga sua che le nomini tutte e due:

INPUT_ACTION_3 = { SCANCODE.LSHIFT, GAMEPAD_0.BUTTON_X, MOUSE_0.BUTTON_LEFT, MOUSE_1.BUTTON_LEFT }

Scrivilo nelle tue istruzioni. Un giocatore la cui seconda pistola non fa niente darà la colpa al tuo gioco, e avrà ragione a metà.

L’altro modo di verificare un colpo

C’è un secondo modo di rispondere a «quel colpo ha preso qualcosa?», e vale la pena conoscerlo anche se oggi non lo userai. vldpGetPixel(x, y) legge il colore di un pixel del fotogramma video che è sullo schermo in quel momento. I giochi lo usano fin dalla primissima versione di Singe: dipingi ogni bersaglio nel filmato di un colore che non compare da nessun’altra parte, e quando qualcuno preme il grilletto chiedi di che colore è quello che sta sotto il mirino.

Ti fa avere gratis forme di colpo che seguono l’azione alla perfezione, senza rettangoli da preparare. Ti costa un filmato che devi preparare in quel modo, e una verifica dei colpi che non puoi vedere né mettere a punto. La voce del Riferimento su vldpGetPixel ha i dettagli. I rettangoli sono la scelta giusta di partenza; questo tienilo in tasca.

Cose che contano solo per un cabinato

Tutto quello che c’è sopra funziona sulla tua scrivania. Diverse cose sulla tua scrivania non esistono proprio, e questo è un buon momento per nominarle, così più avanti non saranno una sorpresa.

Calibrazione. A una vera pistola ottica bisogna dire dov’è lo schermo, perché è una telecamera che guarda un monitor da dovunque si trovi il giocatore. Gli strumenti di servizio di Singe hanno una schermata Light Gun che mette dei bersagli al centro e in ogni angolo e segna dove ha puntato davvero la pistola, così puoi vedere da che parte è sballata. Il tuo gioco non fa la calibrazione e non dovrebbe provarci.

Il bordo Sinden. Una famiglia di pistole molto diffusa trova lo schermo cercando una cornice luminosa disegnata intorno all’immagine. --sindengun disegna quella cornice, e il motore riporta le posizioni dentro l’immagine più piccola che sta al suo interno, così il tuo gioco continua a ricevere coordinate che vogliono dire quello che volevano dire prima.

Schermi che non hanno la forma del filmato. ratioGetX() e ratioGetY() ti danno i numeri che un giocatore ha indicato sulla riga di comando per uno schermo le cui proporzioni non corrispondono a quelle del filmato. Singe non li applica; un gioco che li vuole fa i conti da sé.

Pistole che se ne vanno. SWITCH_MOUSE_DISCONNECT arriva a onInputPressed quando una pistola viene scollegata. Nessun pulsante lo produce; lo genera il motore. Un gioco che lo tiene d’occhio può mettere sullo schermo «PLAYER 2 GUN DISCONNECTED» invece di sembrare morto.

Niente mouse. Un cabinato con un joystick e nessun dispositivo di puntamento può muovere il cursore con la levetta, cosa che si attiva con joyMouseEnable.

Niente di tutto questo cambia il gioco che hai scritto. Tutto questo è la trentunesima lezione.

Prova tu

  1. Sposta un bersaglio. Cambia la x del terzo bersaglio in 680 ed eseguilo. Adesso quasi tutto il bersaglio sporge oltre il bordo destro, perché l’overlay è largo 720 e il bersaglio 96. Puoi ancora sparare alla striscia che resta. Decidi che cosa vuoi che succeda ai bordi.

  2. Rendi i bersagli più facili. Cambia TARGET_SIZE in 140. Nota che cambiano sia il disegno sia la verifica dei colpi, e che hai modificato un numero solo. È a questo che serve una costante con un nome.

  3. Tieni il conto della precisione. Aggiungi una riga che stampa hits come percentuale di shots. Proteggiti dalla divisione per zero prima del primo colpo, e scopri che cosa stampa Lua se non lo fai.

  4. Fai in modo che un bersaglio ti punisca. Aggiungi un campo penalty = true a un record e togli punti quando viene colpito. Nota che stai aggiungendo un campo a un record solo, non a tutti e quattro, e che quelli senza hanno lì nil.

  5. Togli il return dal ciclo in onInputPressed, poi sovrapponi due bersagli dando loro gli stessi fotogrammi e quasi la stessa posizione. Adesso un colpo li prende tutti e due. Decidi quale comportamento vuole il tuo gioco.

Rompilo apposta

Cambia la verifica dello sparo perché usi SWITCH_BUTTON1 invece di SWITCH_BUTTON3, ed eseguilo. Non si rompe niente. Non compare nessun errore. Il pulsante sinistro smette di fare qualcosa, e adesso spara il pulsante destro.

Questo è il tipo di bug peggiore e il più comune nel codice che gestisce i comandi: il programma non è sbagliato, è solo collegato alla cosa sbagliata. Non c’è nessun messaggio di errore da leggere, perché hai fatto una domanda sensata su un interruttore che esiste e lui ha risposto onestamente.

Lo trovano due cose. La prima è debugPrint, dell’ottava lezione:

function onInputPressed(what, device)
    debugPrint("switch " .. what .. " from device " .. tostring(device))

Adesso ogni pressione stampa una riga, e puoi vedere che cosa manda davvero il grilletto. Nota tostring(device): device è nil per la pressione di un tasto, e attaccare nil a una stringa con .. è un errore. tostring lo trasforma nella parola nil e la riga viene stampata.

La seconda è la schermata Input Test del motore, negli strumenti di servizio, che mostra ogni dispositivo che riesce a vedere e l’ultimo interruttore che il gioco avrebbe ricevuto. Quando un pulsante non fa niente, quella schermata ti dice quale metà del problema hai: o l’interruttore arriva e il tuo gioco lo ignora, o non arriva proprio.

Cosa hai imparato

  • Una pistola ottica si presenta come un mouse, quindi un gioco scritto per il mouse funziona con una pistola.

  • mouseGetPosition(device) restituisce due valori, la posizione del puntatore in coordinate dell’overlay.

  • In Lua una funzione può restituire più di un valore, e tu li prendi elencando altrettanti nomi.

  • singeWantsCrosshairs() dice se disegnare un mirino tuo. Leggilo una volta.

  • Singe si prende il puntatore di sistema e lo nasconde all’avvio; tu non devi farlo.

  • onInputPressed riceve un secondo argomento che dice quale mouse o pistola ha sparato, ed è nil quando era un tasto o un controller.

  • La verifica di un colpo contro un rettangolo è collidePointRect, la stessa collisione che hai imparato nell’undicesima lezione.

  • La finestra di fotogrammi di un bersaglio è solo due campi in più nel suo record.

  • a or b ti dà b quando a è nil.

  • La calibrazione, il bordo Sinden e il collegamento di due pistole stanno fuori dal tuo script.

La prossima volta

Il tuo tiro a segno chiede una cosa sola: colpisci quello, lì. L’altra convenzione da sala giochi su cui sono costruiti i giochi video chiede qualcosa di più difficile — premi questo, adesso, e hai mezzo secondo. La diciottesima lezione costruisce un quick-time event, con una richiesta a schermo, una finestra misurata in fotogrammi e tre finali diversi a seconda che tu abbia fatto giusto, sbagliato o troppo tardi.

Lezione 18: Quick-time event

La lezione finita

Compare una richiesta a schermo. Hai mezzo secondo. Premi la cosa giusta e la storia va avanti; premi quella sbagliata, o niente del tutto, e va da un’altra parte.

Questa è tutta l’idea, e un numero sorprendente di giochi video è fatto quasi solo di questo. Hai già tutti i pezzi: la quattordicesima lezione ti ha dato i fotogrammi, la sesta un elenco di record, la terza i comandi e la sedicesima le diramazioni. Questa lezione li mette insieme e aggiunge una cosa davvero nuova — una finestra di tempo, e che cosa succede quando si chiude.

L’orologio è il filmato

Qui tutto si misura in fotogrammi, non in secondi, e vale la pena fermarsi su questo, perché è l’unica decisione che fa funzionare tutto.

La quattordicesima lezione diceva che un fotogramma è l’indirizzo di un momento del filmato. La richiesta deve comparire quando l’attore comincia a caricare il pugno, e la finestra deve chiudersi quando il pugno arriva. Quelli non sono tempi, sono punti del filmato, e li hai trovati scorrendolo un passo alla volta. Se scrivi la finestra in secondi devi far partire un cronometro quando compare la richiesta, e a quel punto i due orologi — il tuo e quello del filmato — possono andare fuori sincrono. Se il video scatta su una macchina lenta, il tuo cronometro continua a correre e il giocatore viene punito per il suo hardware.

I fotogrammi non possono andare fuori sincrono, perché c’è un orologio solo. discGetFrame() è l’ora, sempre. Una finestra è due numeri di fotogramma, e «quanto manca» è una sottrazione.

Eseguilo con lo stesso video di prima:

Singe -R -v Singe/menuBackground.mkv moves

Sempre la griglia viola e il tramonto. Immagina uno scontro.

Una mossa è un record

Ecco la tabella su cui si regge tutta la lezione:

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"  },
}

Quattro mosse. Ognuna dice quando si apre la finestra, quando si chiude, quale interruttore le risponde e che cosa mettere sullo schermo. Quarantacinque fotogrammi sono circa un secondo e mezzo alla velocità di questo video, il che è generoso; i giochi veri spesso ti danno meno della metà.

Tutto ciò che fa di una mossa una mossa sta in quella tabella. Nel codice più sotto non c’è niente che sappia che le mosse sono quattro, o che la seconda è su, o che la prima finestra si apre al fotogramma sessanta. Aggiungere una quinta mossa vuol dire aggiungere una riga. Cambiare i tempi di tutte le mosse vuol dire modificare dei numeri. Nessuno deve leggere una funzione per cambiare lo scontro.

Non è un trucco per questa lezione. È la differenza tra un gioco che puoi mettere a punto e uno che non puoi, e farlo fin dall’inizio non costa niente. Quando ti accorgi che stai per scrivere if frame == 60 then per la quarta volta, fermati e fai invece una tabella.

Che cosa succede quando

A una mossa possono succedere tre cose, e sono tre esiti diversi, non due:

  • Il giocatore preme l’interruttore giusto dentro la finestra. Assegna i punti e si va avanti.

  • Il giocatore preme un interruttore sbagliato dentro la finestra. Ci ha provato e ha fallito.

  • La finestra si chiude senza nessuna risposta. Si è bloccato.

Il codice pigro tratta allo stesso modo gli ultimi due. I giochi non lo fanno quasi mai, perché giocandoci danno sensazioni completamente diverse: tirare a indovinare e sbagliare è un errore, bloccarsi è un errore diverso, e di solito il filmato va in un posto diverso per ciascuno. Qui la risposta sbagliata manda il disco al fotogramma 362 e la risposta mancata lo manda al fotogramma 388, il che su questo filmato vuol dire due quantità di tramonto un po' diverse. Su un filmato vero sarebbero due inquadrature diverse di te che perdi.

Quindi ogni record mette su un quinto campo mentre la partita è in corso — answer — che è nil finché alla mossa non succede qualcosa, e poi una di tre stringhe:

move.answer = "right"
move.answer = "wrong"
move.answer = "late"

nil è il valore che Lua ti dà per un campo che nessuno ha impostato. L’hai incontrato nella terza lezione. Qui si guadagna il pane: «nessuna risposta ancora» è davvero uno stato diverso da tutte e tre le risposte, e nil lo dice senza che tu debba inventarti una parola apposta.

Trovare la mossa richiesta

Tutto il resto ha bisogno di sapere una cosa: quale mossa, se ce n’è una, è aperta in questo momento?

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

Scorri l’elenco, e rispondi con la prima mossa la cui finestra copre questo fotogramma e che non ha ancora avuto risposta. Se non corrisponde niente, rispondi nil.

Vale la pena notare che restituisce nil apposta. Una funzione che a volte non ha una risposta dovrebbe dirlo, e «nessuna mossa è aperta» è una risposta più che valida. Chi la chiama scrive allora if move ~= nil then, e il codice che disegna la richiesta non viene mai eseguito quando non c’è niente da chiedere.

La verifica move.answer == nil è ciò che impedisce a una mossa di essere chiesta due volte. Nell’istante in cui il giocatore risponde giusto, la richiesta sparisce anche se la finestra è ancora aperta — ed è proprio quello che deve fare, perché ha risposto.

Leggere la risposta

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

Leggila dall’alto in basso. Se l’interruttore non è una delle quattro direzioni, non sono affari nostri — vattene. Se nessuna mossa è aperta, premere una direzione non vuol dire niente — vattene. Altrimenti c’è esattamente una mossa con cui confrontare, e un confronto da fare.

Quelle due righe return in anticipo sono delle guardie: buttano fuori i casi che non ti interessano, così il codice sotto viene eseguito solo nell’unica situazione per cui è stato scritto. Scriverlo al contrario, con il lavoro vero annidato tre livelli più in fondo dentro tre blocchi if, dice la stessa cosa ed è molto più difficile da leggere.

isDirection è una funzione minuscola che non fa altro che tenere corta quella prima riga:

local function isDirection(what)
    return what == SWITCH_UP or what == SWITCH_DOWN or what == SWITCH_LEFT or what == SWITCH_RIGHT
end

Nota che restituisce direttamente il confronto invece di dire if …​ then return true else return false end. Un confronto è già true o false. Verificare se qualcosa è vero per poter dire che è vero è un’abitudine da perdere presto.

La finestra che si chiude

Nessuno preme niente, e i fotogrammi continuano a passare. Qualcosa deve accorgersene. Quel qualcosa è onOverlayUpdate, perché viene eseguita a ogni fotogramma, che il giocatore faccia qualcosa 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

Una mossa che non ha avuto risposta e il cui ultimo fotogramma è passato è stata mancata. break esce subito dal ciclo, perché una volta finita la partita non ha senso guardare il resto.

endRun è la diramazione, ed è la stessa diramazione che hai scritto nella sedicesima lezione:

local function endRun(reason, frame)
    verdict = reason
    runOver = true
    discSkipToFrame(frame)
end

Tre righe. Ricordati che cosa dire, ricordati che la partita è finita, e manda il filmato da un’altra parte. Un quick-time event mancato non è un meccanismo speciale. È una scelta che il giocatore ha fatto non facendone nessuna, e il filmato si dirama su di essa esattamente come si dirama su una porta che ha scelto.

Un indicatore che si svuota

Il giocatore non vede i numeri dei fotogrammi. Deve vedere il tempo che finisce, e deve vederlo senza distogliere lo sguardo dall’azione, il che vuol dire una forma che cambia invece di un numero che conta.

Due numeri ti danno tutto:

local left = move.last - frame
local span = move.last - move.first

span è quanto è lunga la finestra. left è quanta ne resta. La barra è left su span della larghezza piena:

fillBar(GAUGE_X, GAUGE_Y, GAUGE_W * left // span, GAUGE_H)

// è la divisione che butta via la parte frazionaria, ed è quello che vuoi qui, perché una barra larga centotrentatré pixel e un terzo non esiste. Moltiplica prima di dividere — GAUGE_W * left // span e non GAUGE_W * (left // span) — altrimenti la parte frazionaria viene buttata via quando è ancora l’unica informazione che hai, e la barra salta da piena a vuota senza niente in mezzo.

Nell’overlay non c’è un rettangolo pieno. overlayBox disegna un contorno, che è quello che ti serve per la cornice intorno all’indicatore, e il riempimento lo fai tu:

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

Diciotto linee orizzontali impilate una sull’altra. La guardia in cima conta: all’ultimissimo fotogramma della finestra left vale zero, la larghezza vale zero, e senza la guardia x + width - 1 sta un pixel a sinistra di x e disegni una piccola linea all’indietro invece di niente.

L’ultimo tocco è un cambio di colore quando la situazione si fa disperata:

if left * 3 < span then
    colorForeground(255, 60, 60, 255)
else
    colorForeground(255, 200, 0, 255)
end

La barra diventa rossa nel suo ultimo terzo. Scritto così — moltiplicando il tempo che resta invece di dividere la durata — resta in numeri interi e funziona per una finestra di qualsiasi lunghezza.

Tutto insieme

-- Impara a programmare con Singe -- Lezione 18: Quick-time event

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()

I tasti freccia rispondono alle richieste. Azzeccale tutte e quattro e il filmato va fino in fondo e si ferma lì su CLEAR. Sbagliane una, o resta con le mani in mano, e il filmato salta a un fotogramma diverso con una parola diversa sullo schermo. 1 lo fa ripartire.

Cos’è appena successo

La maggior parte l’hai già letta. Quattro pezzi meritano una seconda occhiata.

if frame >= LAST_FRAME and discGetState() == DISC_PLAYING then

La fine del filmato va intercettata, altrimenti il filmato va oltre la fine e non c’è più niente da vedere. discSearch va a un fotogramma e lì si mette in pausa, ed è esattamente quello che vuole un’inquadratura finale. La metà con discGetState() impedisce che questo succeda di nuovo a ognuno dei fotogrammi successivi: una volta in pausa il disco non è più DISC_PLAYING, quindi la condizione è falsa e il salto non viene ripetuto sessanta volte al secondo. discGetState e le costanti DISC_* sono nel Riferimento, sotto discGetState.

local move = nil
if not runOver then
    move = moveAt(frame)
end

onOverlayUpdate chiede di nuovo qual è la mossa aperta, invece di farselo dire da onInputPressed. È voluto. C’è esattamente una funzione che sa quale mossa è aperta, e tutti chiedono a lei. Se la richiesta venisse da una variabile tenuta aggiornata dal codice dei comandi, allora due pezzi di codice si ricorderebbero lo stesso fatto, e prima o poi uno dei due sbaglierebbe. Quando devi scegliere tra chiedere e ricordare, chiedi.

overlayPrint(PROMPT_COL, PROMPT_ROW, "PRESS " .. move.name)

overlayPrint conta in celle di carattere, come fa dalla prima lezione, quindi la richiesta è posizionata a occhio: la colonna cinquantaquattro è abbastanza vicina al centro per parole di questa lunghezza. È abbastanza vicina, non giusta, e «PRESS RIGHT» finisce tre caratteri più a destra di «PRESS UP». La diciannovesima lezione carica un vero font, e con lui la possibilità di misurare una stringa in pixel e centrarla come si deve.

function onInputPressed(what)
    if runOver then
        if what == SWITCH_START1 then
            startRun()
        end
        return
    end

Una callback, due lavori completamente diversi, scelti da runOver. Mentre la partita è in corso le direzioni sono mosse; una volta finita, l’unico tasto che vuol dire qualcosa è start. Una variabile che decide quali regole valgono è uno stato, che la dodicesima lezione chiamava proprio così, e un gioco è fatto soprattutto di un piccolo numero di stati.

Prova tu

  1. Rendilo più difficile. Cambia il last della prima mossa da 105 a 75. Quindici fotogrammi sono mezzo secondo. Giocaci e scopri se ce la fai.

  2. Aggiungi una mossa. Metti una quinta riga nella tabella con una finestra tra i fotogrammi 370 e 400, e porta LAST_FRAME a 418. Non dovresti dover toccare nessun’altra riga. Se devi farlo, qualcosa nel codice sa troppo della tabella.

  3. Dai punti alla velocità. Assegna più punti a chi risponde presto. In onInputPressed, dove viene premiata la risposta giusta, calcola left e span a partire da move e discGetFrame() come fa l’indicatore, e aggiungi RIGHT_SCORE * left // span invece di RIGHT_SCORE. Decidi se così il gioco diventa migliore o solo più movimentato.

  4. Da' alla risposta sbagliata una conseguenza sua. Invece di far finire la partita, fai costare cinquanta punti a una pressione sbagliata e lascia la finestra aperta per riprovare. Dovrai smettere di impostare move.answer, e incontrerai il motivo per cui veniva impostata.

  5. Due richieste insieme. Sovrapponi le finestre di due mosse e guarda che cosa succede. moveAt restituisce la prima corrispondenza, quindi ne viene chiesta sempre una sola. Decidi che cosa vorresti, e che cosa ci vorrebbe.

Rompilo apposta

Cancella il break dal ciclo che trova le mosse mancate, e manca la prima apposta. La partita finisce, il disco salta, e sembra tutto a posto.

Ora metti debugPrint(move.name .. " missed") accanto a move.answer = "late" e rifallo. La console mostra una riga, come ti aspetteresti.

Poi togli anche il blocco if not runOver then intorno al ciclo, e manca di nuovo la prima mossa:

LEFT missed
UP missed
RIGHT missed
DOWN missed

La prima riga arriva quando la finestra si chiude, come prima. Le altre tre arrivano insieme proprio al fotogramma successivo, nell’istante in cui il disco atterra sul 388: ogni finestra rimasta ormai è nel passato, quindi ogni mossa senza risposta viene mancata tutta in una volta, e ognuna chiama endRun e fa un altro salto. Il gioco più o meno funziona ancora, ed è questo che lo rende pericoloso. Tre salti in più in un solo fotogramma, tre sovrascritture del verdetto, e niente sullo schermo lo dice.

Anche qui non c’è nessun messaggio di errore. La lezione è che quel break e quella guardia non sono questione di ordine. Sono le due righe che dicono «questo è già stato deciso», e il codice che continua a decidere una cosa che ha già deciso è una delle fonti di bug più affidabili che scriverai mai.

Cosa hai imparato

  • Un quick-time event è una richiesta, una finestra e una conseguenza.

  • Misura la finestra in fotogrammi, perché il filmato è l’orologio e di orologio ce ne deve essere sempre uno solo.

  • Tieni le mosse in una tabella di record, così aggiungere una mossa vuol dire aggiungere una riga.

  • Giusto, sbagliato e nessuna risposta sono tre esiti, e di solito portano in tre posti diversi.

  • nil in un campo di un record è uno stato vero: nessuno ha ancora risposto.

  • Una sola funzione risponde a «quale mossa è aperta», e tutti chiedono a lei invece di tenerne una copia.

  • Le clausole di guardia — un return anticipato per i casi che non ti interessano — evitano di annidare il lavoro vero.

  • // divide e butta via la parte frazionaria; moltiplica prima di dividere.

  • overlayBox disegna un contorno, quindi una barra piena è una pila di chiamate a overlayLine.

  • Una mossa mancata è una diramazione, e la prende discSkipToFrame, esattamente come nella sedicesima lezione.

La prossima volta

La terza parte è finita. Sai riprodurre un filmato, aspettarlo, diramarlo, mirarci e misurare il tempo del giocatore contro di lui. Quello che hai scritto sopra a tutto questo è il font della console del motore, che è largo sei pixel e pensato per la diagnostica. La diciannovesima lezione carica un vero carattere tipografico, lo misura, e fa sembrare le parole sullo schermo parte del gioco.

Lezione 19: Testo che fa bella figura

La lezione finita

Ogni parola che hai messo sullo schermo dalla prima lezione è uscita da overlayPrint, e overlayPrint ha esattamente un font: un blocco di pixel a larghezza fissa incorporato nel motore, sempre della stessa dimensione, in qualunque colore capiti. È perfetto per un contatore di fotogrammi. È sbagliato per un titolo, un punteggio, un menu, o qualsiasi cosa che un giocatore deve guardare invece di scorrere con gli occhi.

Questa lezione carica un vero font dal disco, ci stampa, lo colora, lo misura così puoi centrare le cose, e ti mostra quanto costa davvero stampare del testo. Alla fine avrai una schermata del titolo che sembra voluta invece che capitata per caso.

Dai all’overlay una dimensione con cui ragionare

Crea un nuovo file chiamato text.singe con due righe:

dofile("Singe/Framework.singe")

overlaySetResolution(discGetWidth(), discGetHeight())

La prima riga l’hai scritta molte volte; carica il framework, che definisce DIR, i nomi SWITCH_* e i nomi FONT_QUALITY_* che stai per usare.

La seconda conta più di quanto sembri. L’overlay — la superficie su cui finisce tutto quello che disegni — parte a metà della dimensione del mondo. Un gioco senza video ha un canvas di 720 per 480, quindi l’overlay parte da 360 per 240, e un font da 36 punti su un overlay largo 360 pixel è enorme. overlaySetResolution sostituisce l’overlay con uno della dimensione che chiedi, e da quel momento ogni coordinata che dai, e tutto ciò che ti dicono overlayGetWidth e overlayGetHeight, sta in quello spazio.

discGetWidth() e discGetHeight() rispondono con la dimensione del video quando c’è, e con quella del canvas quando non c’è, così quell’unica riga ti dà un overlay che corrisponde al mondo, qualunque tipo di gioco sia questo. Chiamala una volta, all’inizio, prima di disegnare qualsiasi cosa.

Carica un font

Sotto, aggiungi:

fontQuality(FONT_QUALITY_BLENDED)

local titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)

fontLoad apre un file di font TrueType e ti restituisce un numero — un handle — che usi ogni volta che vuoi quel font. Il secondo argomento è la dimensione in punti, ed è fissa per tutta la vita dell’handle. Non c’è modo di cambiare la dimensione di un font già caricato. Se vuoi lo stesso carattere in tre dimensioni, chiami fontLoad tre volte e tieni tre handle.

Singe/FreeSansBold.ttf è il font che il motore ha estratto nella cartella Singe dentro la tua cartella di lavoro la prima volta che hai eseguito qualcosa. Ce l’ha ogni copia di Singe, quindi puoi contarci. Qualsiasi altro file .ttf funziona allo stesso modo; mettilo accanto al tuo script e caricalo come DIR .. "myfont.ttf".

Ora stampaci:

function onOverlayUpdate()
    overlayClear()
    fontPrint(24, 60, "ASTEROID PATROL")
    return OVERLAY_UPDATED
end

Eseguilo. Grandi lettere bianche vicino all’angolo in alto a sinistra.

Nota che cosa non hai fatto: non hai mai detto a fontPrint quale font usare. fontLoad seleziona il font che ha appena caricato, e fontPrint disegna sempre con quello selezionato. Con più di un font caricato scegli tra loro con fontSelect, ed è quello che farai tra un momento.

Nota anche che 24 e 60 sono pixel, non celle di carattere. Questa è la differenza tra fontPrint e overlayPrint che fa inciampare la gente: overlayPrint(2, 2, …​) vuol dire due lettere verso destra e due righe verso il basso, mentre fontPrint(2, 2, …​) vuol dire due pixel verso destra e due pixel verso il basso, cioè schiacciato nell’angolo. La y che dai è la cima del testo, non la linea di base su cui poggia.

Colore

fontPrint prende tre argomenti e nessuno di questi è un colore. Il colore arriva da un’altra parte:

    colorForeground(255, 211, 90)
    fontPrint(24, 60, "ASTEROID PATROL")

colorForeground imposta rosso, verde e blu da 0 a 255, più un quarto numero facoltativo per l’opacità. Non è un argomento di niente; è un’impostazione che il motore si ricorda. Tutto ciò che disegni dopo esce in quel colore finché non lo cambi di nuovo, esattamente come funzionano già overlayBox e overlayLine. Quindi lo schema è sempre lo stesso: imposta il colore, poi disegna.

Questa è la prima cosa che la gente sbaglia con i font, e la seconda arriva tra qualche pagina.

Qualità

fontQuality decide come vengono rasterizzate le lettere — come le curve di una lettera vengono trasformate in pixel — e ci sono tre scelte. Provale una per una mettendola sopra la riga di fontLoad e guardando bene il risultato.

FONT_QUALITY_SOLID è la più veloce. Ogni pixel o è la lettera o non lo è, quindi le diagonali e le curve escono con dei gradini ben visibili. A 48 punti sembra da quattro soldi. A 12 punti su un overlay piccolo può sembrare più nitida delle alternative, ed è a volte quello che vuoi.

FONT_QUALITY_SHADED ammorbidisce i bordi, ma lo fa sfumandoli nel colore di sfondo attuale, e disegna quello sfondo come un rettangolo pieno dietro tutta la stringa. Ottieni un’etichetta con un riquadro intorno, che tu lo volessi o no. È la risposta giusta per un indicatore di debug sopra un’immagine piena di roba, e quella sbagliata per quasi tutto il resto.

FONT_QUALITY_BLENDED ammorbidisce i bordi e li lascia trasparenti, così le lettere stanno sopra qualunque cosa ci sia dietro. È quella che costa di più ed è quella che vuoi quasi sempre. Usala, a meno che tu non abbia un motivo per non farlo.

L’impostazione è globale, non per font, e vale dal momento in cui la chiami in poi. Gli sprite che hai già creato mantengono la qualità con cui sono stati creati. La voce del Riferimento su fontQuality elenca i tre nomi e i loro valori.

Misurare, per poter centrare le cose

Prima o poi — di solito dopo una decina di minuti — vuoi il titolo in mezzo allo schermo. Sai che lo schermo è largo overlayGetWidth(). Non sai quanto è largo il testo, e non c’è nessuna chiamata fontMeasure a cui chiederlo.

Quello che c’è invece è fontToSprite. Disegna una stringa con il font selezionato, la qualità attuale e il colore attuale, e invece di metterla sullo schermo ti restituisce uno sprite: lo stesso tipo di handle che ti dà spriteLoad, il che vuol dire che ogni chiamata sprite* che hai imparato nella nona lezione funziona anche su questo. Comprese le due che lo misurano.

fontSelect(titleFont)
colorForeground(255, 211, 90)
local titleImage = fontToSprite("ASTEROID PATROL")

E poi, in onOverlayUpdate:

    local x = (overlayGetWidth() - spriteGetWidth(titleImage)) / 2
    spriteDraw(titleImage, x, 60)

Questo è centrare, ed è tutto il trucco. Prendi la larghezza dello spazio, togli la larghezza della cosa, e metà di quello che resta è lo spazio vuoto da ogni lato.

Allineare a destra è la stessa idea con meno aritmetica. Per mettere il testo contro il margine destro:

    spriteDraw(scoreImage, overlayGetWidth() - MARGIN - spriteGetWidth(scoreImage), y)

spriteGetHeight misura l’altra direzione, per impilare righe o centrare in verticale.

C’è un tranello in quel primo blocco di codice, ed è la seconda cosa che sbagliano tutti. Il colore viene fissato quando lo sprite viene creato, non quando viene disegnato. colorForeground sopra fontToSprite cambia il testo. Metterlo invece sopra spriteDraw non fa proprio niente, perché colorForeground è un’impostazione per disegnare testo e linee, e uno sprite viene disegnato con i suoi pixel. Se il tuo titolo colorato con tanta cura esce bianco, il motivo è questo.

Uno sprite si può ricolorare dopo averlo creato, ma con una chiamata degli sprite, non con colorForeground. spriteSetTint(image, red, green, blue) moltiplica ogni pixel dello sprite per quel colore ogni volta che viene disegnato, così un testo creato in bianco si può disegnare giallo oggi e rosso domani senza rifarlo. Il bianco è il colore in cui crearlo quando hai intenzione di tingerlo: qualsiasi cosa moltiplicata per il bianco resta com’era, quindi la tinta è esattamente il colore che chiedi.

Quanto costa stampare

La prima volta che fontPrint vede una stringa, fa un lavoro vero: rasterizza ogni lettera dai contorni del font e costruisce un’immagine di tutta la stringa. Poi quell’immagine se la tiene. La volta dopo che stampi la stessa stringa, con lo stesso font, la stessa qualità e gli stessi colori, salta tutto questo e copia l’immagine che ha già, che costa più o meno quanto disegnare uno sprite. Una stringa che smetti di stampare viene lasciata andare un secondo dopo, quindi non si accumula niente.

Questo vuol dire che il modo ovvio di scrivere una schermata del titolo è anche quello veloce. Stampare "ASTEROID PATROL" sessanta volte al secondo lo disegna una volta sola. Un punteggio che cambia due volte al secondo viene disegnato due volte al secondo, da solo, senza che tu debba tenere nessun conto.

L’unico caso che costa è il testo che è diverso a ogni fotogramma — un timer in millisecondi, un contatore di fotogrammi — perché ogni fotogramma è una stringa che fontPrint non ha mai visto. Su un computer desktop non importa. Su un Raspberry Pi o una console portatile, uno schermo pieno di testo così importa. Il rimedio è cambiare il testo meno spesso: un timer in secondi interi è una stringa nuova una volta al secondo, non sessanta.

Allora perché questa lezione ha usato fontToSprite? Perché uno sprite può fare cose che il testo stampato non può fare:

  • Si può misurare, ed è l’unico modo per centrare il testo o allinearlo contro il lato destro.

  • Si può ridimensionare e ruotare con le chiamate sprite* della nona lezione.

  • Può sopravvivere al suo font, e tra un momento questo conterà.

Usa fontPrint per il testo, e fontToSprite quando ti serve una di queste cose.

Il punteggio di questa lezione ne ha bisogno: sta contro il margine destro, quindi va misurato, quindi deve essere uno sprite. E uno sprite di un punteggio è giusto solo finché il punteggio non cambia. Quando cambia, crea un nuovo sprite e scarica quello vecchio — dimenticarsene lascia per strada uno sprite a ogni 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 si ricorda quale punteggio dice quello sprite, così il codice che disegna può capire se è ancora giusto:

    if score ~= scoreShown then
        renderScore()
    end

string.format("%06d", score) è Lua puro, non Singe. Trasforma un numero in una stringa, e %06d vuol dire «come numero intero, di almeno sei cifre, riempito di zeri», ed è per questo che i punteggi da sala giochi hanno gli zeri davanti. Cambialo in %d e gli zeri spariscono.

Mettere via i font

fontUnload chiude un font e rende il suo handle non valido. Gli sprite che hai creato con fontToSprite non ne risentono — una volta disegnato, uno sprite non ha più niente a che fare con il font — quindi puoi scaricare un font e continuare a disegnare il testo creato con lui.

Un’insidia: se scarichi il font che era selezionato, dopo non è selezionato nessun font, e il fontPrint successivo chiude il tuo gioco con un errore. Se hai intenzione di continuare a stampare, selezionane prima un altro.

Il posto ordinato per tutto questo è onShutdown, una callback che il motore chiama una volta quando il gioco si sta chiudendo:

function onShutdown()
    spriteUnload(titleImage)
    fontUnload(titleFont)
end

Singe fa pulizia al posto tuo quando il gioco finisce, quindi non prende fuoco niente se salti questa parte. Scrivila lo stesso. Un gioco che rilascia quello che ha caricato è un gioco che puoi caricare due volte.

Lo 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

Eseguilo e tieni premuto il pulsante di fuoco. Il titolo e il suggerimento stanno al centro, il punteggio sale contro il margine destro e viene ridisegnato solo quando cambia, il suggerimento lampeggia, e l’etichetta e l’orologio vengono stampati con fontPrint a ogni fotogramma — l’orologio in secondi interi, così è una stringa nuova solo una volta al secondo.

Cos’è appena successo

titleFont = fontLoad("Singe/FreeSansBold.ttf", 48)
scoreFont = fontLoad("Singe/FreeSansBold.ttf", 36)
smallFont = fontLoad("Singe/FreeSansBold.ttf", 18)

Un file, tre dimensioni, tre handle. Ognuno costa memoria per il suo insieme di glifi disegnati, quindi carica le dimensioni che usi e non di più. Tre è normale. Una dozzina comincia a puzzare.

Dopo queste tre righe il font selezionato è smallFont, perché caricare seleziona. Ecco perché il codice chiama fontSelect(titleFont) prima di disegnare il titolo: l’ultima cosa caricata non è quella che vuoi per prima.

local function centered(image)
    return (overlayGetWidth() - spriteGetWidth(image)) / 2
end

Scritta una volta come funzione perché viene usata due volte, e perché la prossima volta che vorrai centrare qualcosa la vorrai di nuovo. Dai un nome all’aritmetica e non dovrai mai più rileggerla.

    if (singeGetTicks() // 500) % 2 == 0 then
        spriteDraw(hintImage, centered(hintImage), HINT_Y)
    end

singeGetTicks() è il numero di millisecondi dall’avvio del motore. // è la divisione che butta via il resto, quindi singeGetTicks() // 500 conta i mezzi secondi, e % 2 è il resto della divisione per due, che fa 0, 1, 0, 1…​ Quindi il suggerimento viene disegnato per mezzo secondo e saltato per mezzo secondo. Non disegnare niente è il modo per far lampeggiare qualcosa.

    fontSelect(smallFont)
    colorForeground(160, 160, 160)
    fontPrint(MARGIN, LABEL_Y, "SCORE")

Qui servono tutte e due le impostazioni, e vale la pena capire bene perché. Disegnare uno sprite non cambia il font selezionato né il colore, quindi le due chiamate spriteDraw qui sopra li lasciano esattamente come li hanno trovati. Ma il codice di preparazione ha selezionato tre font diversi uno dopo l’altro, e renderScore ne seleziona un altro ogni volta che il punteggio si muove, quindi quando questa riga viene eseguita è selezionato quello che è capitato di scegliere per ultimo. Non cercare di tenerne traccia. Seleziona il font e imposta il colore subito prima di stampare, ogni volta. Sono due righe, e tolgono di mezzo un’intera categoria di serate passate a grattarsi la testa.

Prova tu

  1. Cambia la qualità. Metti FONT_QUALITY_SOLID nella riga di fontQuality e guarda la curva della S in ASTEROID. Poi prova FONT_QUALITY_SHADED e guarda che cosa succede dietro ogni stringa.

  2. Fai diventare giallo il suggerimento. Sposta la riga colorForeground(140, 200, 255) da sopra fontToSprite a subito sopra lo spriteDraw che disegna hintImage, e cambia i numeri. Capisci perché non succede niente. Poi rimettila a posto, fai invece il suggerimento bianco, e fallo diventare giallo con spriteSetTint subito prima che venga disegnato.

  3. Allinea l’orologio a destra. L’orologio è disegnato con fontPrint, che non si può misurare. Mettilo contro il margine destro lo stesso. C’è un solo modo, e trovarlo è il punto.

  4. Togli il controllo su scoreShown, così renderScore() viene eseguita a ogni fotogramma. Sembrerà identico, ma adesso disegna il punteggio sessanta volte al secondo invece di quando cambia — esattamente il lavoro che fontPrint ti risparmia quando lo lasci fare. Poi togli anche lo spriteUnload in renderScore, lascialo girare per un minuto, e guarda la memoria che usa il tuo gioco.

  5. Stampa un orologio in millisecondi. Cambia la riga dell’orologio perché stampi singeGetTicks() senza il // 1000. Funziona ancora; adesso è una stringa che fontPrint non ha mai visto, a ogni fotogramma. Su una macchina lenta, è questo il tipo di testo che costa.

  6. Usa un font tuo. Trova un .ttf sul tuo computer, copialo accanto al tuo script e caricalo con DIR .. "thatfont.ttf". Certi font sono orribili a 18 punti e vanno benissimo a 48. È colpa del font, non tua.

Rompilo apposta

Aggiungi una riga con scritto fontPrint(24, 60, "SCORE") subito sotto overlaySetResolution(discGetWidth(), discGetHeight()), così viene eseguita prima di qualsiasi fontLoad. Singe parte e muore subito:

4:fontPrint:  No font selected.

Leggilo come qualsiasi altro errore. 4 è la riga. fontPrint è la chiamata del motore che si è lamentata — un messaggio di questa forma arriva da dentro il motore invece che da Lua, quindi nomina la funzione invece del file. Il resto è la lamentela, e qui è precisa: gli hai chiesto di stampare e non c’era nessun font con cui farlo.

Questo errore lo incontrerai sul serio in un modo meno ovvio. Scarica il font selezionato mentre il gioco gira e il fontPrint successivo dice esattamente la stessa cosa, a qualche centinaio di righe di distanza dal fontUnload che l’ha causato.

Cosa hai imparato

  • fontLoad apre un file TrueType a una dimensione in punti fissa e restituisce un handle. Una dimensione, un handle.

  • Caricare un font lo seleziona; fontSelect sceglie tra i font caricati.

  • fontPrint conta in pixel e overlayPrint conta in celle di carattere.

  • Il colore non è un argomento. colorForeground è un’impostazione: impostala, poi disegna.

  • fontQuality sceglie come vengono rasterizzate le lettere, e FONT_QUALITY_BLENDED è la risposta normale.

  • fontPrint si tiene quello che disegna, quindi stampare lo stesso testo a ogni fotogramma costa poco; quello che costa è il testo diverso a ogni fotogramma.

  • fontToSprite disegna dentro uno sprite, che spriteGetWidth misura e le chiamate sprite* possono ridimensionare e ruotare. Usalo per questo, non per la velocità.

  • Misurare è il modo per centrare il testo o allinearlo a destra, perché nient’altro può dirti quanto sarà larga una stringa.

  • colorForeground arriva al testo quando viene creato, mai a uno sprite quando viene disegnato; spriteSetTint è il modo per ricolorare uno sprite dopo.

  • fontUnload libera un font; gli sprite che ha creato gli sopravvivono.

La prossima volta

Un testo che fa bella figura è ben lontano da un menu che funziona. Una pagina con un titolo, un elenco in cui sposti un cursore, uno slider e un pulsante è un centinaio di righe di disegno e di aritmetica dei cursori, se la costruisci con le chiamate di questa lezione. La ventesima lezione non la costruisce affatto con quelle chiamate.

Lezione 20: Menu e schermate

La lezione finita

Puoi costruire un menu con quello che sai già. Un riquadro, un po' di testo, un cursore che si sposta quando si sposta la levetta, un if per ogni scelta, e un po' di aritmetica per tenere tutto allineato quando aggiungi una quarta voce. Funziona. Sono anche un centinaio di righe per una pagina con sopra tre pulsanti, e ognuna di quelle righe tocca a te mantenerla.

Singe ha al suo interno un intero motore per documenti — RmlUi — e un menu scritto per RmlUi è una pagina, come una pagina web, con un foglio di stile. Manda a capo il testo da sé. Si impagina da sé quando aggiungi una voce. Sa che cos’è un pulsante, che cos’è uno slider, e a quale controllo sta puntando il giocatore. Questa lezione ci costruisce un menu di pausa, sopra un gioco che continua a girare dietro.

Due file

Una pagina della GUI è fatta di due cose: un documento che dice che cosa c’è sulla pagina, e del Lua che dice che cosa fa la pagina. Stanno in file separati, ed è proprio questo il senso dell’esercizio — l’impaginazione smette di essere codice.

Comincia con uno script chiamato menu.singe e un gioco così piccolo che sta in un paragrafo: un’astronave che attraversa lo schermo, e un punteggio che sale ogni volta che arriva dall’altra parte. Scrivi cose del genere dalla settima lezione.

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

Funziona. Adesso il documento. Accanto al tuo script, crea un file chiamato 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>

Se hai mai visto il sorgente di una pagina web, ti sembrerà familiare. Se non l’hai mai visto, ecco tutto quello che ti serve per leggerlo.

Un documento è fatto di elementi. Un elemento comincia con un nome tra parentesi angolari, <h1>, finisce con lo stesso nome e una barra, </h1>, e tutto quello che sta tra i due è al suo interno. Alcuni elementi non hanno niente dentro e si chiudono da soli con una barra alla fine, come l’elemento <input …​/> qui sopra. Gli elementi si annidano, e il rientro mostra l’annidamento nello stesso modo in cui lo mostra in Lua.

Le parole dentro il tag di apertura sono attributi, scritti name="value". Due ti interessano più degli altri. id dà a un elemento un nome con cui il tuo script può trovarlo, ed è così che Lua e il documento si parlano. class mette l’elemento in un gruppo a cui il foglio di stile può mirare; panel, muted e list sono gruppi che il foglio di stile del motore conosce già.

Il linguaggio di markup si chiama RML e il linguaggio degli stili si chiama RCSS. Sono di RmlUi, non di Singe. Il capitolo sulla GUI del Riferimento rimanda alla documentazione di RmlUi per l’elenco completo di quello che puoi scrivere, e prima o poi ti servirà. Tutto quello che c’è in questa lezione funziona anche senza.

Mostralo

Torna allo script. Sopra onOverlayUpdate, aggiungi:

local gui  = guiNew(overlayGetWidth(), overlayGetHeight())
local page = guiLoad(gui, DIR .. "pause.rml")

guiNew crea una GUI: un rettangolo di dimensione fissa in cui i documenti vengono impaginati e disegnati. Restituisce un handle, come fanno fontLoad e spriteLoad. Farla grande quanto l’overlay vuol dire che un pixel del documento è un pixel del tuo overlay, e così i conti che fai a mente restano semplici.

guiLoad legge un documento dentro quella GUI e restituisce un secondo handle, per il documento stesso. Quasi tutte le altre chiamate li vogliono entrambi: la GUI e il documento che contiene. Una GUI può contenere fino a trentadue documenti — una pagina del titolo, una pagina delle opzioni e una pagina di game over possono stare in una sola — e possono esistere fino a sedici GUI contemporaneamente.

Sullo schermo non c’è ancora niente, perché caricare un documento non lo disegna. Aggiungi una riga a onOverlayUpdate, subito prima del return:

    guiDraw(gui)

Eseguilo. Il pannello è lì, sopra l’astronave, con il suo titolo, i suoi tre pulsanti e il suo slider, e non hai scritto nemmeno una riga di codice di disegno.

guiDraw compone la GUI sopra l’overlay solo per questo fotogramma, come ogni altra chiamata di disegno, quindi va in onOverlayUpdate e va chiamata di nuovo al fotogramma successivo. Il punto in cui la metti decide che cosa sta sopra: tutto quello che hai disegnato prima sta sotto, e tutto quello che disegni dopo le va sopra. Un mirino disegnato dopo guiDraw non viene mai nascosto dal menu.

Lascia che il giocatore lo usi

Fai clic su un pulsante. Non succede niente, e il pulsante non si illumina nemmeno.

Una GUI nuova è un’immagine, non un pannello di controllo. È voluto: un HUD o un cartello non devono inghiottire il pulsante di fuoco. Per fare in modo che una pagina riceva l’input:

guiSetInput(gui, true)

Adesso il mouse funziona, i pulsanti si illuminano sotto il puntatore, e con i tasti freccia ti sposti tra i controlli, perché il documento l’ha chiesto con nav: auto. Su un controller o una levetta le quattro direzioni arrivano come tasti freccia, il primo pulsante d’azione arriva come Invio, e il secondo arriva come Esc. Un cabinato con un joystick e due pulsanti usa questa pagina senza sapere che è un documento.

Del controllo su cui stanno lavorando i tasti si dice che ha il focus, e un pulsante con il focus porta un bordo dorato. Il focus parte da Resume perché quel pulsante dice autofocus: ogni volta che la pagina viene mostrata, il focus va al controllo segnato così. Toglilo e i tasti freccia non hanno nessun punto da cui partire finché il giocatore non fa clic su qualcosa, il che, su un cabinato senza mouse, vuol dire mai.

Fare clic però continua a non fare niente, perché nessuno sta ascoltando.

Parlagli

Tre chiamate collegano il documento al tuo script, e da sole fanno quasi tutto.

guiSetHandler(gui, page, "resume", "click", function()
    closeMenu()
end)

guiSetHandler dice: quando l’elemento con questo id fa questa cosa, chiama questa funzione. Questo id è quello scritto nel documento. Il nome dell’evento è di RmlUi: "click" per i pulsanti, "change" per qualsiasi cosa il giocatore regoli, e un lungo elenco di altri che puoi cercare quando ti servono. Viene tenuta una funzione per elemento e per evento, quindi impostarne un’altra sostituisce la precedente, e passare nil al posto di una funzione la rimuove.

La tua funzione viene chiamata con cinque argomenti — la GUI, il documento, l’id, l’evento e il valore attuale dell’elemento come stringa. Prendine quanti ne vuoi e ignora il resto, come già ignori gli argomenti in Lua.

guiSetHandler(gui, page, "speed", "change", function(g, d, id, event, value)
    speed = math.floor(tonumber(value))
end)

Lo slider consegna il suo valore come stringa, e RmlUi formatta i numeri a modo suo, quindi 4 arriva come "4.000000". tonumber trasforma la stringa in un numero e math.floor butta via la parte decimale. Saltare questo passaggio e usare la stringa come numero è un errore che farai una volta.

guiSetValue(gui, page, "score", string.format("%06d", score))

guiSetValue scrive dentro un elemento. Per un controllo di un modulo imposta il valore del controllo; per qualsiasi altra cosa — un paragrafo, un div, lo <span id="score"> nel tuo documento — sostituisce quello che c’è dentro l’elemento, e la pagina si reimpagina al fotogramma successivo. guiGetValue è la stessa chiamata al contrario, e risponde nil per un id che nessun elemento ha, così puoi chiedere di un elemento che potrebbe non esserci senza morire.

Ecco tutta l’API di tutti i giorni: guiSetHandler, guiSetValue, guiGetValue. C’è molto di più a disposizione tramite gli oggetti Lua di RmlUi, raggiungibili dalla variabile globale rmlui, e il capitolo sulla GUI del riferimento mostra come. Farai molta strada prima di averne bisogno.

Nascondilo di nuovo

Un menu di pausa non sta sempre aperto. guiHide toglie un documento dallo schermo e guiShow lo rimette, conservando tutto quello che il giocatore ha scritto o scelto.

La pausa vera e propria è singeSetPauseFlag(true), che ferma il disco, i video e i suoni ma continua a chiamare le tue callback, così puoi ancora disegnare. Il motore ha un suo tasto di pausa, che congela completamente lo script, e i due si darebbero battaglia; singeSetPauseKeyEnabled(false) toglie quel tasto al motore, così SWITCH_PAUSE arriva a onInputPressed come qualsiasi altro interruttore. Sulla tastiera quel tasto è 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

Spegnere l’input insieme alla pagina non è un abbellimento. Una pagina nascosta che riceve ancora l’input si mangia i tasti freccia del giocatore per il resto della partita.

Quello che la pagina non usa arriva comunque a te

Questa è la regola che rende sicuro lasciare una GUI aperta durante il gioco, e vale la pena dirla chiaramente: un evento usato da un elemento non raggiunge mai le tue callback. Un Invio che ha premuto il pulsante con il focus non arriva come onInputPressed. Una freccia che ha spostato il focus non arriva come SWITCH_LEFT. Un clic su un pulsante non è un interruttore del mouse.

Tutto quello che la pagina non ha usato passa dritto come al solito. È per questo che P chiude questo menu: nessun elemento del documento usa P, quindi il tasto arriva a onInputPressed esattamente come quando il menu è chiuso. Ed è anche per questo che un HUD che riceve l’input lascia comunque passare il pulsante di fuoco.

Un tasto non segue la regola. RmlUi usa Tab per spostare il focus e non lo restituisce mai, quindi Singe passa Tab a una GUI solo mentre si sta davvero scrivendo in un campo di testo. Un gioco che assegna Tab a qualcosa se lo tiene.

Dagli uno stile

Riguarda il <head> del documento. Una riga fa la maggior parte del lavoro:

	<link type="text/rcss" href="Singe/gui.rcss"/>

È il tema che il motore fornisce, ed è per questo che il tuo pannello ha un bordo, una sfumatura e un titolo dorato senza che tu abbia scelto niente di tutto ciò. Senza un foglio di stile RmlUi non disegna quasi niente, perché ogni elemento parte in linea e grande quanto il suo contenuto, quindi collegare prima questo e sovrascrivere quello che non ti piace è la strada più rapida verso una pagina che sembri qualcosa.

Il tema ti dà .panel (un riquadro con bordo e angoli arrotondati), .list (un riquadro che scorre, le cui righe div figlie si evidenziano e prendono il focus), .muted (testo più tenue per i suggerimenti), i titoli, e ogni controllo dei moduli con i suoi stati di mouse sopra, focus e pressione. Il capitolo sulla GUI del Riferimento li elenca.

Tutto quello che viene dopo il collegamento è tuo. Il blocco <style> in pause.rml sovrascrive il tema per questa pagina, con le regole successive che vincono su quelle precedenti, e una regola che mira a un id batte una che mira a una class. Per un vero gioco metti le tue regole in un file .rcss accanto al documento e collegalo per secondo, così il tuo aspetto sta in un solo file per tutte le pagine.

L’unità dp è un pixel della dimensione propria della GUI — la tua GUI è grande quanto l’overlay, quindi 380dp sono 380 pixel dell’overlay. margin: 80dp auto è il trucco che centra un blocco di larghezza nota: auto divide quello che avanza in parti uguali tra i due lati. Niente misure e niente conti, cosa che dopo la diciannovesima lezione potresti trovare un po' irritante.

Per usare un tuo font in un documento, caricalo con guiLoadFont prima dei documenti che lo usano, e chiamalo in RCSS con il nome della famiglia scritto dentro il file del font, non con il nome del file.

Quando non usare niente di tutto questo

Una GUI è una pagina. È la risposta giusta per un menu, una schermata delle opzioni, una tabella dei punteggi record, una schermata di game over, o un HUD con un’impaginazione vera.

È la risposta sbagliata per un punteggio nell’angolo. Quello sono due righe di fontPrint della diciannovesima lezione, e avvolgerlo in un documento non ti dà niente e ti costa una texture. Lo stesso vale per un mirino, una barra della salute disegnata con overlayBox e una riga di testo di debug.

Tre fatti decidono per te.

Una GUI ha bisogno di una GPU. Su una macchina che non ce l’ha — un vecchio computer, un Pi piccolo, una macchina senza alcun driver Vulkan, Direct3D 12 o Metal — non ci sono GUI, e guiNew non risponde educatamente false: termina il tuo gioco. La scena 3D della ventiduesima lezione fa lo stesso, quindi non è l’ultima volta che te lo chiederai. Chiedi prima a singeHasGpu() se il tuo gioco deve funzionare in entrambi i posti, e tieni pronta una versione semplice sull’overlay su cui ripiegare. Il menu del motore fa proprio così.

Una GUI costa una texture e un passaggio di impaginazione a ogni fotogramma, che tu la disegni o no. Una GUI con cui hai finito va eliminata con guiDelete, non semplicemente nascosto. Nascondere serve per una pagina che mostrerai di nuovo tra un minuto.

E un ricaricamento smonta le GUI. F5, -R e qualsiasi cosa riavvii lo script si portano via tutte le GUI, e lo script le ricrea quando riparte. Va bene così, purché tu le costruisca nel corpo dello script e non in qualche angolo che viene eseguito una volta sola.

Lo 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

Cos’è appena successo

if singeHasGpu() then
    gui  = guiNew(overlayGetWidth(), overlayGetHeight())
    page = guiLoad(gui, DIR .. "pause.rml")

Tutta la GUI viene costruita dentro quel blocco if, e gui resta nil su una macchina che non ha una GPU. Ogni chiamata che tocca la GUI è protetta da if gui ~= nil, e la pausa funziona anche senza menu. Sono quattro righe in più, e sono la differenza tra «non ha un menu su quella macchina» e «non parte su quella macchina».

    guiHide(gui, page)
    guiSetInput(gui, false)

guiLoad mostra il documento che ha caricato, quindi una pagina che deve partire nascosta va nascosta subito. Per una GUI nuova l’input è già spento, ma spegnerlo qui vuol dire che openMenu e closeMenu sono esattamente l’una lo specchio dell’altra, e le coppie speculari sono molto più difficili da sbagliare.

    guiSetHandler(gui, page, "restart", "click", function()
        score = 0
        shipX = 0
        closeMenu()
    end)

L’handler è una funzione senza nome, scritta dove viene usata. Lua ti lascia scrivere function(…​) …​ end ovunque serva un valore, e siccome guiSetHandler vuole una funzione, puoi dargliene una sul momento invece di darle prima un nome e poi passare il nome. Raggiunge score, shipX e closeMenu perché sono dichiarati sopra di lei nello stesso file, ed è proprio per questo che gli handler vengono impostati sotto le cose che toccano.

    if not paused then
        shipX = shipX + speed

L’indicatore di pausa ferma il disco e i suoni, non i tuoi conti. onOverlayUpdate continua a essere chiamata — è proprio questo il punto, perché altrimenti il menu non potrebbe essere disegnato — quindi qualsiasi cosa tua debba fermarsi durante la pausa, la fermi tu.

Prova tu

  1. Aggiungi un quarto pulsante. Copia la riga <button id="quit">, dalle un nuovo id e un nuovo testo, e aggiungi un handler per il nuovo pulsante. Nota che non c’è stato niente da rimisurare o da spostare.

  2. Cambiagli stile. Nel blocco <style>, cambia #frame in width: 260dp; margin: 20dp; e guarda il pannello spostarsi e il testo andare a capo di nuovo da solo.

  3. Togli il guiSetInput(gui, true) in openMenu. La pagina compare ancora. Capisci, solo guardando lo schermo, che cosa hai perso.

  4. Lascia la pagina sempre visibile. Cancella le chiamate a guiHide, cambia entrambe le chiamate guiSetInput(gui, false) in true e disegna la GUI a ogni fotogramma invece che solo durante la pausa. Poi premi i tasti freccia e Invio mentre l’astronave vola. La pagina se li prende per sé: il focus si sposta, lo slider cambia la velocità, e Invio preme il pulsante che ha il focus. Un gioco che si guidasse con quei tasti non li sentirebbe mai. È per questo che un HUD è guiSetInput(gui, false).

  5. Metti il punteggio sulla pagina invece che nell’HUD. Chiama guiSetValue per score a ogni fotogramma invece che solo in openMenu, e cancella la riga fontPrint. Poi decidi quale dei due preferisci davvero, e perché.

Rompilo apposta

Cambia un id in pause.rml, da id="resume" a id="continue", e lascia stare lo script. Singe parte e muore:

52:guiSetHandler:  No element "resume" in document 0 of GUI 0.

Leggilo come leggi qualsiasi errore del motore. La riga, la chiamata che si è lamentata, poi la lamentela — e questa lamentela è precisa. Non sta dicendo che il documento è rotto; il documento si è caricato perfettamente. Sta dicendo che hai chiesto un elemento con un nome che lì dentro non ha nessuno.

guiSetHandler e guiSetValue muoiono entrambe se manca un id, perché un handler che volevi collegare e non hai collegato è un bug di cui vuoi sapere subito. guiGetValue è l’eccezione: risponde nil, così puoi chiedere se una cosa c’è.

L’altro errore che vale la pena incontrare è quello che ottieni quando non si carica il documento stesso. Rinomina pause.rml ed esegui. Stavolta Singe nomina il file e cita il motivo dato da RmlUi, e i brontolii di RmlUi sul tuo markup e sui tuoi stili finiscono nella console che il caricamento riesca o no. Leggi quella console la prima volta che una pagina esce vuota; di solito ti avrà già detto il perché.

Cosa hai imparato

  • Una GUI è un rettangolo di dimensione fissa in cui i documenti vengono impaginati e disegnati; guiNew ne crea una e guiDelete la libera.

  • guiLoad mette un documento RML in una GUI e lo mostra; guiHide, guiShow e guiClose lo gestiscono in seguito.

  • guiDraw compone la GUI sopra l’overlay per un fotogramma, quindi va in onOverlayUpdate come ogni altra chiamata di disegno.

  • Una GUI nuova si limita a mostrare; è guiSetInput a renderla utilizzabile.

  • guiSetHandler esegue la tua funzione quando un elemento viene cliccato o cambiato, guiSetValue scrive dentro un elemento e guiGetValue ne legge uno.

  • Un evento usato da un elemento non raggiunge mai le tue callback; tutto il resto passa come al solito.

  • Singe/gui.rcss è il tema fornito con il motore; collegalo per primo e sovrascrivilo in un blocco <style> o in un foglio tutto tuo.

  • Una GUI ha bisogno di una GPU, quindi chiedi a singeHasGpu() se il tuo gioco deve funzionare anche senza.

  • Ogni GUI viene elaborata a ogni fotogramma, che tu la disegni o no, quindi elimina quelle con cui hai finito.

  • Un punteggio nell’angolo sono due righe di fontPrint, non un documento.

La prossima volta

C’è ancora un tipo di testo sullo schermo, e ha un sistema tutto suo per un motivo che non ha niente a che fare con il suo aspetto. La ventunesima lezione parla di sottotitoli, e dei giocatori che senza sottotitoli non possono giocare al tuo gioco.

Lezione 21: Sottotitoli

La lezione finita

Qualcuno che non sente giocherà al tuo gioco.

Se il tuo gioco ha del parlato e niente sottotitoli, non potrà farlo. Non nel senso di «fa più fatica» — arriverà alla prima scena in cui un personaggio dice la cosa che spiega al giocatore che cosa fare, e si fermerà lì. Tutto qui, ed è il motivo per cui questa lezione esiste invece di essere un paragrafo della diciannovesima.

L’altro motivo è pratico. Aggiungere i sottotitoli a un gioco finito è una tortura. Devi trovare ogni frase parlata, capire in quale fotogramma si trova, e scoprire che metà delle tue tempistiche sono sbagliate perché il video è stato ricodificato a metà del progetto. Fatto mentre scrivi il gioco, è un pomeriggio. Singe ti dà un sistema che fa la parte difficile, e questa lezione spiega come usarlo.

Non è il solito testo disegnato

Potresti fare i sottotitoli da solo. Tieni un elenco di frasi con il tempo di inizio e di fine, controlla l’orologio in onOverlayUpdate, e disegna quella corrente con fontToSprite. C’è chi l’ha fatto. Ecco perché tu non dovresti.

I sottotitoli sono sincronizzati con il disco, non con un orologio. Quando srtLoad legge il tuo file converte ogni marca temporale in un numero di fotogramma del disco, lì per lì, usando la frequenza dei fotogrammi del disco caricato. Da quel momento il motore non guarda più nessun orologio; a ogni fotogramma disegnato chiede quale battuta copre il fotogramma su cui si trova il disco.

Quella sola decisione ti dà la cosa che un sistema fatto in casa non azzecca mai: un sottotitolo sopravvive a un salto. Manda il disco dove vuoi — discSearch, discSkipForward, un passo, una diramazione verso un altro segmento — e la frase giusta compare al fotogramma disegnato successivo, in avanti o all’indietro, senza ricaricare niente e senza azzerare nessun orologio. In un gioco a diramazioni come quello della sedicesima lezione, dove le scelte del giocatore fanno saltare il disco di continuo, è la differenza tra funzionare e quasi funzionare.

Si disegna anche nel posto giusto. Il documento dei sottotitoli sta sopra l’immagine, sopra il tuo overlay, sotto qualsiasi GUI nello spazio dello schermo, e segue l’immagine ovunque la mettano le impostazioni del giocatore — un’immagine rimpicciolita, una spostata, un cabinato ruotato, un’apertura in un bezel. Non riceve input dal mouse, quindi un colpo di pistola ottica gli passa dritto attraverso. Sistemare tutto questo da solo è una settimana che non avevi messo in conto.

Scrivi il file

I sottotitoli vanno in un file SubRip, che finisce in .srt ed è testo semplice che puoi scrivere con qualsiasi editor. È uno dei formati più semplici che esistano. Crea un file chiamato subtitles.srt accanto al tuo 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 battuta è fatta di quattro cose. Un numero su una riga tutta sua. Una riga con due marche temporali e, tra le due, una freccia fatta di due trattini e un segno di maggiore. Una o più righe di testo. Una riga vuota per finire.

Una marca temporale è HH:MM:SS,mmm — ore, minuti e secondi separati da due punti, poi una virgola, poi i millisecondi. La virgola non è un errore di battitura, e un punto non va bene. 00:00:04,200 vuol dire quattro secondi e un quinto dall’inizio.

I numeri delle battute vengono letti e buttati via, quindi non devono essere in ordine e nemmeno giusti. Numerale comunque; prima o poi ti ritroverai a cercare la battuta quarantuno.

La battuta due mostra com’è fatta una battuta su due righe. Le righe vengono mostrate come le hai scritte, quindi sei tu a decidere dove va a capo una riga lunga, il che conta più di quanto penseresti ed è spiegato più avanti.

Il caricamento è volutamente tollerante con le cose che vanno storte in un file scritto a mano. I fine riga di Windows si caricano senza problemi, e gli spazi all’inizio e alla fine di ogni riga vengono tolti. Una battuta le cui marche temporali non si riescono a leggere viene saltata e il resto del file continua a caricarsi, il che è gentile fino al momento in cui ti chiedi dov’è finita la riga dodici. Alcune cose non sono supportate: i tag <i> e <b> che certi strumenti scrivono vengono mostrati come testo invece di essere applicati, e le coordinate di posizione che certi strumenti aggiungono alla riga dei tempi vengono ignorate. La sezione sui sottotitoli del Riferimento ha l’elenco completo.

Caricalo e accendilo

Tre chiamate, e l’ordine conta.

if srtLoad(DIR .. "subtitles.srt") then
    srtPosition(80)
    srtEnable(true)
end

srtLoad legge il file e risponde true o false. Risponde false, senza aver caricato niente, in tre casi: il file non si può leggere, non c’è niente al suo interno che si riesca a leggere, oppure non c’è un disco. In tutti e tre i casi scrive nella console un avviso con il nome del file. È una buona scelta di progetto e dovresti sfruttarla: un file di sottotitoli mancante non vale la morte di un gioco, ma distribuire senza accorgertene un gioco senza sottotitoli è una cosa che vale la pena notare.

Il caso «nessun disco» è quello in cui cadrai. Le marche temporali devono diventare numeri di fotogramma alla frequenza dei fotogrammi del disco, e finché non c’è un disco aperto non c’è nessuna frequenza da usare. Quindi carica i sottotitoli dopo il disco, il che in uno script normale vuol dire dal corpo dello script, dove gira tutto il resto che hai scritto al livello più esterno. Ne segue che un .srt preparato per un video a una certa frequenza dei fotogrammi finisce nel posto sbagliato su un video a un’altra. Sincronizza il tuo file con il video che distribuirai davvero.

srtEnable(true) accende le battute caricate. Uno script parte con i sottotitoli spenti, sempre, quindi un gioco che li carica deve accenderli. Spegnerli di nuovo toglie quello che si vede, e riaccenderli mostra quello che copre il fotogramma su cui si trova il disco in quel momento — niente ricerche, nessuno stato da tenere.

Tenere i sottotitoli accesi è un’impostazione, non una decisione che prendi al posto del giocatore. Mettila nella tua pagina delle opzioni della ventesima lezione, salvala con il saveSet della dodicesima, e passa a srtEnable quello che il giocatore ha scelto l’ultima volta.

Dove stanno

srtPosition(70)

srtPosition è una percentuale dell’altezza dell’immagine, contata dall’alto, da 1 a 95, e il valore predefinito è 80. Ha effetto sulla battuta che si vede in quel momento e su tutte quelle successive. Un numero fuori dall’intervallo viene ignorato invece di essere riportato nei limiti, il che vuol dire che un errore di battitura lascia la posizione esattamente dov’era e non dice niente, quindi controlla i tuoi numeri.

L’ottanta per cento è in basso, ed è in basso apposta: la parte bassa dell’immagine di solito è la meno interessante dell’inquadratura. Spostali più su quando la parte bassa non è noiosa — quando il tuo gioco disegna un tabellone segnapunti lungo il bordo inferiore, o quando il mirino della pistola ottica del giocatore sta laggiù.

Toglierne uno

srtClear()

srtClear toglie subito dallo schermo quello che c’è, e lascia stare le battute caricate e lo stato di accensione. La frase che si vedeva resta spenta finché il disco non raggiunge la battuta successiva. Usalo quando una scena finisce prima del previsto e non vuoi che l’ultima frase del dialogo resti appesa sopra l’inquadratura successiva.

C’è un’altra chiamata che condivide il meccanismo dei sottotitoli, e forse l’hai già usata:

overlayBanner("Extra life!", 20)

overlayBanner mostra un breve messaggio sopra l’immagine per circa trenta fotogrammi disegnati e poi lo toglie. Viene disegnato dallo stesso documento dei sottotitoli, quindi un banner sembra un sottotitolo, e mentre è visibile prende il posto di qualsiasi sottotitolo, che torna quando il banner scade. Il suo argomento per l’altezza è separato da srtPosition e se non lo dai vale 47, il centro dell’immagine. I messaggi più lunghi di sessanta caratteri vengono ignorati del tutto, quindi uno lungo sembra proprio non funzionare.

Sottotitoli già dentro il video

Alcuni file video portano con sé le proprie tracce di sottotitoli. Se il tuo lo fa, non ti serve affatto un .srt:

if discGetSubtitleTracks() > 0 then
    srtLoadTrack(0)
else
    srtLoad(DIR .. "subtitles.srt")
end
srtEnable(true)

srtLoadTrack prende un numero di traccia da 0 a discGetSubtitleTracks() - 1, e dopo il caricamento tutto è identico. discGetSubtitleLanguage(track) ti dice con quale lingua è etichettata una traccia, come codice di tre lettere tipo eng o fra, così un gioco può offrire al giocatore tutto quello che il suo video si trova ad avere.

Due avvertenze. Leggere una traccia percorre tutto il file video una volta, senza decodificare immagini, quindi un disco lungo quanto un film richiede un momento: fallo mentre sullo schermo c’è qualcos’altro, non tra due fotogrammi di gioco. E le tracce di sottotitoli che contengono immagini delle parole invece delle parole — il tipo che usano i DVD e i Blu-ray — non si possono leggere. Vengono contate, così la numerazione corrisponde a quella che mostrano gli altri lettori multimediali, ma per loro srtLoadTrack risponde false.

Lo script completo

Questo script ha bisogno di un video. Ce l’hai: Singe/menuBackground.mkv, che il motore ha estratto nella tua cartella di lavoro la prima volta che hai eseguito qualcosa. Di' a Singe di usarlo come disco con --framefile, che accende anche il 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

Premi fuoco per accenderli e spegnerli, su e giù per spostare le righe, e sinistra per riavvolgere fino all’inizio. Il riavvolgimento è quello da tenere d’occhio: il disco salta indietro al fotogramma zero e la battuta giusta compare proprio al fotogramma successivo, senza che tu faccia niente.

Cos’è appena successo

if discGetSubtitleTracks() > 0 then
    loaded = srtLoadTrack(0)
end
if not loaded then
    loaded = srtLoad(DIR .. "subtitles.srt")
end

Prendi i sottotitoli del video quando ce li ha, ripiega sul file accanto allo script quando non li ha, e alla fine sai quale dei due — se uno dei due — ha funzionato. Entrambe le chiamate rispondono con un booleano, quindi il ripiego sono due istruzioni if e nessun caso speciale. menuBackground.mkv non ha nessuna traccia di sottotitoli, quindi quello che otterrai davvero è il file che hai scritto.

function onInputPressed(what)
    if not loaded then
        return
    end

return senza niente dopo esce subito dalla funzione. Senza sottotitoli caricati nessuno di questi tasti ha qualcosa da fare, e uscire subito è più chiaro che avvolgere tutto il corpo in un if. Chiamare srtEnable senza niente di caricato non fa danni, ma scrivere codice che ha senso solo quando non fa niente è un’abitudine che conviene non prendere.

    elseif what == SWITCH_LEFT then
        srtClear()
        discSearch(0)
        discPlay()

La chiamata a srtClear non è necessaria. Il motore mostrerà comunque la battuta giusta per il fotogramma zero al fotogramma disegnato successivo. È lì perché tu possa cancellarla e guardare che cosa succede: la vecchia frase resta su per una frazione di secondo mentre il disco arriva dove deve andare. Con un salto lento quel lampo della frase sbagliata si vede, e pulire prima è il modo per evitarlo.

Rendere leggibile il testo sopra un’immagine in movimento

Il sistema mette le parole sullo schermo. Se qualcuno riesce a leggerle è un problema tuo, e vale per ogni riga di testo che disegni sopra un video — una richiesta della diciottesima lezione, un punteggio, una scelta di diramazione — non solo per i sottotitoli.

Stai lontano dai bordi. I televisori tagliano i bordi delle immagini da settant’anni, e i monitor da sala giochi sono peggio, non meglio. Parti dal presupposto che il cinque per cento più esterno dell’immagine, su ogni lato, sullo schermo di qualcuno potrebbe proprio non esserci. Tieni lì dentro tutto quello che il giocatore deve leggere. È per questo che srtPosition si ferma a 95 e non a 100.

Il contrasto non è una scelta di colore, è una garanzia. Un testo bianco sopra un’immagine è un testo bianco sopra qualunque cosa l’immagine stia facendo, e fra due secondi potrebbe essere un campo di neve. Lo stile dei sottotitoli fornito con il motore lo risolve come fanno i sottotitoli dei film: un pannello scuro che avvolge il testo, più un’ombra di un pixel. Se disegni tu del testo sopra un video, fai l’una o l’altra cosa — un overlayBox dietro, o una copia scura del testo spostata di un pixel. Non contare sull’immagine.

Vai a capo tu. Due righe corte si leggono più in fretta di una lunga, e una riga che va a capo dove non l’hai deciso tu di solito si spezza nel punto sbagliato. Punta a una quarantina di caratteri per riga e non più di due righe alla volta. Vai a capo in una pausa naturale: They were wrong about / a great many things si legge; They were wrong / about a great many things inciampa.

Lasciali su abbastanza a lungo. Una velocità di lettura comoda è intorno ai quindici caratteri al secondo, quindi una riga di quaranta caratteri vuole più o meno tre secondi. Guarda la battuta uno nel file qui sopra: trentadue caratteri, tre secondi. Se una frase del dialogo è breve e rapida, tenere la battuta su un attimo dopo la fine del parlato è più gentile che farla sparire di colpo.

Mettili dove non c’è l’azione. Se la cosa importante dell’inquadratura è in basso nel fotogramma, sposta i sottotitoli più su per quella scena con srtPosition. Puoi chiamarla tutte le volte che vuoi, e il giocatore non si accorgerà mai che l’hai fatto.

Lo stile dei sottotitoli

Le righe vengono disegnate da un documento, dello stesso tipo che hai incontrato nella ventesima lezione, e due file nella tua cartella Singe decidono che aspetto hanno:

  • Singe/subtitle.rml — il documento. Contiene un solo elemento, #slot, in cui il motore scrive la battuta o il banner del momento.

  • Singe/subtitle.rcss — lo stile. .cue è il blocco che porta l’altezza chiesta da srtPosition, e .cue .text è la barra di testo al suo interno: bianca, in grassetto, su un pannello scuro con gli angoli arrotondati che avvolge il testo, con un’ombra.

Apri subtitle.rcss e leggilo — sono una quarantina di righe. Poi lascialo stare, perché una modifica lì non dura. Ogni volta che Singe parte, rimette la propria copia di qualsiasi cosa nella cartella Singe sia stata cambiata, e lo dice:

>>> Updated File:  Singe/subtitle.rcss

Quella cartella è del motore. Il tuo gioco porta invece una copia sua. Copia entrambi i file fuori da Singe e dentro la tua cartella subtitles, accanto allo script. Poi apri la tua copia di subtitle.rml e cambia l’unica riga del suo <head> che collega lo stile, in modo che diventi:

	<link type="text/rcss" href="subtitle.rcss"/>

Un nome dentro un documento parte dalla cartella del documento stesso, tranne un nome che comincia con Singe/, che vuol dire sempre la cartella del motore. Il collegamento così come l’hai copiato, Singe/subtitle.rcss, prende ancora lo stile del motore. Quello nuovo prende il tuo.

Quando Singe trova un subtitle.rml accanto al tuo script, disegna i sottotitoli con quello invece che con il proprio. Aggiungi -p al comando e Singe descrive quello che sta facendo man mano, una riga alla volta:

Singe -p --framefile=Singe/menuBackground.mkv subtitles

Quando compare la prima battuta, una di quelle righe è questa:

Using the game's own subtitles/subtitle.rml

Ora cambia font-size, color, background-color, border-radius o font-effect nel tuo subtitle.rcss, salva ed esegui di nuovo. Il motore imposta sempre e solo il contenuto di #slot e l’altezza di .cue, quindi tutto il resto dei tuoi due file è tuo, e niente di quello che Singe fa all’avvio li toccherà. Se -p dice che sta usando i tuoi e l’aspetto non è cambiato, rileggi il collegamento: una copia che dice ancora Singe/ sta usando in silenzio lo stile del motore.

Siccome overlayBanner usa lo stesso documento, cambiare lo stile dei sottotitoli cambia anche quello dei tuoi banner, il che di solito è quello che vuoi, ed è meglio saperlo prima di chiederti perché.

Un limite: il documento dei sottotitoli è un documento, e i documenti hanno bisogno di una GPU. Su una macchina che non ce l’ha, srtLoad legge comunque il tuo file e risponde comunque il vero, e non viene disegnato niente. Un avviso lo dice una volta.

Prova tu

  1. Aggiungi una quarta battuta a subtitles.srt, tra gli undici e i tredici secondi. Salva ed esegui. Poi mettila fuori ordine, come battuta 99, per prima nel file, e verifica che funzioni ancora.

  2. Dai a una battuta una marca temporale sbagliata — scrivi 00:00:05.500 con un punto al posto della virgola — ed esegui. Guarda quale riga sparisce, e nota che nessuno ti dice niente. Un file che si carica non è un file giusto.

  3. Cambia il loro stile. Nel tuo subtitle.rcss — la copia accanto al tuo script, non quella in Singe — cambia .cue .text in testo giallo su uno sfondo del tutto trasparente, poi aggiungi un’ombra più marcata. Poi guardalo sopra il video e decidi onestamente se si legge ancora.

  4. Rompi apposta la tempistica. Cambia ogni marca temporale del file in modo che sia in ritardo di due secondi, e guarda un sistema che funziona a dovere consegnare sottotitoli inutili. È questo che ti fa un video ricodificato.

  5. Metti il comando in un menu. Prendi la pagina di pausa della ventesima lezione, aggiungi una casella di controllo, e collegala a srtEnable. Poi salva la scelta con saveSet, così la volta dopo è ancora attiva. Questa è la versione che i tuoi giocatori vogliono davvero.

Rompilo apposta

Esegui lo script senza l’opzione --framefile:

Singe subtitles

La finestra si apre, nera, con sopra il tuo messaggio di ripiego, e la console dice:

Warning:  No subtitles were loaded from subtitles/subtitles.srt.

Nessun crash e nessuna finestra di errore, perché srtLoad ha risposto false e il tuo script ne ha tenuto conto.

È il fallimento più prezioso di questa lezione, perché è quello che succede senza che nessuno se ne accorga. Non c’è un disco, quindi non c’è una frequenza dei fotogrammi, quindi non c’è niente in cui trasformare le marche temporali, quindi non si carica niente. Se avessi scritto srtLoad(…​) da solo e avessi buttato via la risposta, il tuo gioco sarebbe andato alla perfezione senza mostrare nessun sottotitolo, e l’avresti scoperto quando qualcuno te l’avesse detto.

Usa la risposta. Ogni volta.

Cosa hai imparato

  • Un gioco con del parlato e senza sottotitoli è un gioco a cui alcune persone non possono proprio giocare.

  • Inserire i sottotitoli strada facendo è un pomeriggio; aggiungerli dopo no.

  • I sottotitoli sono un file .srt: un numero, due marche temporali con -→ in mezzo, il testo e una riga vuota.

  • srtLoad trasforma le marche temporali in numeri di fotogramma del disco al momento del caricamento, ed è per questo che una battuta sopravvive a qualsiasi salto.

  • I sottotitoli vanno caricati dopo il disco, e il caricamento risponde false quando non riesce, anche quando non c’è un disco. Controlla la risposta.

  • srtEnable li accende, e uno script parte sempre con i sottotitoli spenti.

  • srtPosition li colloca a una percentuale dell’altezza dell’immagine, contata dall’alto, da 1 a 95.

  • srtClear toglie quello che si vede, e overlayBanner condivide lo stesso documento.

  • srtLoadTrack legge i sottotitoli dal file video stesso, quando li contiene.

  • Singe riscrive la sua cartella Singe a ogni avvio, quindi per cambiare lo stile dei sottotitoli copi subtitle.rml e subtitle.rcss accanto al tuo script, fai puntare il collegamento della copia al tuo foglio, e cambi quello.

  • Il testo sopra un’immagine in movimento ha bisogno di un margine di sicurezza, di un contrasto suo, di righe che hai spezzato tu e del tempo per essere letto.

La prossima volta

Con questo il testo è finito. La quarta parte prosegue senza che tu debba leggerla in ordine, e la prossima lezione apre una porta rimasta chiusa per venti lezioni: overlayGetWidth e overlayGetHeight sono due numeri, e una scena ne ha tre. La ventiduesima lezione parla del terzo.

Lezione 22: Nel 3D

La lezione finita

Tutto quello che hai disegnato finora era piatto. Sprite, testo, riquadri e linee vivono tutti sull’overlay, che è una lastra di vetro sul davanti della finestra, con le stesse coordinate che aveva nella prima lezione. Questa lezione mette un mondo dietro quel vetro: un posto con la profondità, dove una cosa può essere più vicina o più lontana, e dove una telecamera decide che cosa ne vedi.

Alla fine avrai un cubo che galleggia nello spazio e che puoi girare con i tasti freccia, e i numeri dei suoi angoli scritti in un angolo dello schermo dallo stesso overlayPrint che hai usato il tuo primissimo giorno. Quest’ultima parte conta più di quanto sembri, e ha una sezione tutta sua.

Una scena, un cubo e una luce

Crea una cartella, mettici dentro un file chiamato spin.singe e scrivi questo.

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

Eseguilo con Singe -R spin. Un cubo arancione gira lentamente su uno sfondo blu scuro, illuminato dall’alto e da destra, con una faccia chiara e le altre che sfumano nell’ombra.

In quello script non c’è nessuna telecamera. Singe ti ha messo in (0, 0, 5) a guardare il centro del mondo, perché una scena senza telecamera deve pur essere vista da qualche parte. Tra un momento la sostituirai con una telecamera tua.

Se la finestra resta nera, leggi la console. Su una macchina la cui grafica non sa disegnare una scena 3D, sceneEnable ferma il gioco con un messaggio che lo dice, e non c’è altro da fare che eseguire la lezione da un’altra parte. Su una macchina del genere i giochi 2D continuano a funzionare; il 3D no.

Cos’è appena successo

Le tre chiamate in cima preparano il mondo nel suo insieme.

sceneEnable(true)
sceneSetBackground(18, 20, 34)
sceneSetAmbient(35, 35, 45)

sceneEnable(true) accende il livello 3D. È l’unica chiamata che fa ogni gioco 3D, e finché non la fai niente di quello che costruisci nella scena viene disegnato.

sceneSetBackground è il colore con cui la scena viene ripulita a ogni fotogramma, rosso, verde e blu da 0 a 255, come funzionano i colori dalla nona lezione. C’è un quarto numero che puoi darle per la trasparenza, ed è così che un gioco che riproduce video mette un oggetto 3D davanti al filmato. Se non lo dai, lo sfondo è pieno.

sceneSetAmbient è un po' di luce che arriva da tutte le direzioni insieme. Il suo compito è evitare che i lati che nessuna lampada raggiunge siano nero pieno. Più avanti abbassala a 0, 0, 0 e guarda quanto diventa dura l’immagine.

local paint = materialNew()
materialSetColor(paint, 215, 95, 60)
materialSetRoughness(paint, 0.6)

Un materiale è l’aspetto di una superficie: il suo colore, quanto è lucida, se ha sopra un’immagine. materialNew ne crea uno e restituisce un numero che lo rappresenta, lo stesso tipo di handle che ti ha dato spriteLoad nella nona lezione. Tienilo in una variabile, perché tutte le chiamate successive ne hanno bisogno.

materialSetRoughness va da 0, uno specchio con un riflesso piccolo e netto, a 1, una superficie opaca come il gesso, senza nessun riflesso. 0.6 è vernice sul legno. Ci sono un’altra dozzina di chiamate materialSet, e la prossima lezione ne usa alcune; la sezione sui materiali del riferimento le elenca tutte.

local box = nodeNew()
nodeSetMesh(box, meshBox(2, 2, 2), paint)

Questa è quella importante. Un nodo è un posto nel mondo. Ha una posizione, una rotazione e una scala, e da solo non disegna proprio niente: è un punto a cui si possono attaccare delle cose. In una scena 3D tutto è un nodo, comprese le luci e la telecamera.

nodeNew ne crea uno vuoto al centro del mondo. nodeSetMesh ci appende due cose: una mesh, che è la forma, e il materiale, che è l’aspetto di quella forma. meshBox(2, 2, 2) costruisce un cubo largo due unità, alto due e profondo due, e ne restituisce un handle come ha fatto materialNew.

Vale la pena condividere mesh e materiali. Un solo handle di meshBox può essere usato da cento nodi, ed è così che disegni cento casse spendendo poco. Creare cento cubi separati che per caso hanno la stessa dimensione è il modo da principiante di rendere lenta una scena.

local sun = lightNew(LIGHT_DIRECTIONAL)
nodeSetPosition(sun, 4, 6, 5)
nodeLookAt(sun, 0, 0, 0)

Anche lightNew crea un nodo — uno che porta una luce — e ne restituisce l’handle, così lo posizioni e lo punti con le stesse chiamate che usi per tutto il resto. LIGHT_DIRECTIONAL è un sole: è così lontano che conta solo la direzione in cui splende, ed è per questo che qui la posizione conta solo perché nodeLookAt la usa per ricavare la direzione.

Togli quelle tre righe ed eseguilo di nuovo. Il cubo diventa quasi nero, perché l’unica luce rimasta è quella ambiente, debole. Alla luce è dedicata tutta la ventitreesima lezione, e questo è il primo assaggio della delusione più comune nel 3D: il modello si è caricato benissimo, e la scena è nera perché niente lo illumina.

    nodeRotate(box, 0, 0.5, 0)

nodeRotate gira un nodo di un certo numero di gradi attorno a ciascuno dei suoi tre assi, in aggiunta alla rotazione che aveva già. Mezzo grado per fotogramma, a circa sessanta fotogrammi al secondo, fa un giro ogni dodici secondi. È lo stesso trucco della seconda lezione: un piccolo cambiamento, applicato a ogni fotogramma, si legge come movimento.

Orientarsi

Tre numeri descrivono un posto nella scena, e devi sapere che cosa vuol dire ciascuno prima di poter mettere qualcosa da qualche parte.

  • X va verso destra. Una X più grande è più a destra.

  • Y va verso l’alto. Una Y più grande è più in alto. Il pavimento di una scena di solito è y = 0.

  • Z va verso di te, fuori dallo schermo. Una Z più grande è più vicina alla telecamera predefinita, e la Z negativa è la direzione in cui guarda la telecamera.

Quest’ultima trae in inganno tutti. Le cose che vuoi davanti alla telecamera vanno a Z negativa. Non è una stranezza di Singe: glTF e Blender usano la stessa disposizione, quindi un modello esportato da Blender arriva rivolto dalla parte che Singe si aspetta.

Non credermi sulla parola. Aggiungi questa riga dopo la riga nodeSetMesh, salva e guarda:

nodeSetPosition(box, 3, 1, 0)

Il cubo salta a destra e in alto. nodeSetPosition mette un nodo in un punto preciso, e sostituisce qualunque posizione il nodo avesse. C’è una nodeMove(node, dx, dy, dz) corrispondente che invece sposta un nodo di una certa quantità, lungo i suoi assi, quindi nodeMove(ship, 0, 0, -0.1) fa avanzare un’astronave da qualunque parte stia puntando.

Prova poi nodeSetPosition(box, 0, 0, -20). Il cubo si rimpicciolisce in lontananza, ed è la Z negativa che fa il suo lavoro. Poi prova (0, 0, 20): il cubo sparisce, perché l’hai messo dietro la telecamera.

Altre due chiamate completano la serie.

nodeSetRotation(box, 0, 45, 0)
nodeSetScale(box, 0.5)

nodeSetRotation imposta la rotazione direttamente in gradi, mentre nodeRotate la aggiunge. I tre numeri sono attorno a X, attorno a Y e attorno a Z: girare attorno a Y è quello che fa una persona in piedi sul pavimento quando si gira per guardare da un’altra parte, ed è quella che userai di più. nodeSetScale rende il nodo più grande o più piccolo, con un solo numero per tutti e tre gli assi oppure con tre, uno per asse.

Togli di nuovo tutti e due gli esperimenti prima di andare avanti. Il resto della lezione parte dallo script come l’hai scritto la prima volta.

Una telecamera tua

La vista predefinita è una cortesia, non una funzionalità. Metti una telecamera.

local camera = nodeNew()
nodeSetPosition(camera, 0, 2, 7)
nodeLookAt(camera, 0, 0, 0)
cameraSet(camera)
cameraSetPerspective(60, 0.1, 100)

Metti queste righe sotto la luce, prima del tuo onOverlayUpdate, ed eseguilo. Adesso guardi il cubo leggermente dall’alto, da due unità più su e sette più indietro.

Una telecamera è un nodo come un altro. cameraSet dice al motore da quale nodo guardare, e la scena viene disegnata dalla posizione di quel nodo guardando lungo la Z negativa del nodo stesso. Puntare una telecamera a mano con nodeSetRotation sarebbe una tortura, quindi lo fa per te nodeLookAt: dagli un punto del mondo e lui gira il nodo verso quel punto.

cameraSetPerspective è l’obiettivo. Il primo numero è il campo visivo in gradi, in verticale: quanta parte del mondo viene schiacciata nell’altezza della finestra. Un numero piccolo come 35 è un teleobiettivo che appiattisce tutto; uno grande come 90 è un grandangolo che fa sembrare enorme la stanza e gonfiare gli angoli. 60 è un valore predefinito comodo. Gli altri due numeri sono la distanza più vicina e quella più lontana che vengono disegnate, e le cose fuori da quell’intervallo non vengono disegnate affatto.

Siccome la telecamera è un nodo normale, tutto quello che hai imparato sui nodi funziona anche su di lei. Più avanti appenderai una telecamera sotto un’auto in movimento e avrai gratis una telecamera d’inseguimento.

Giralo con i tasti freccia

Leggere il sistema di coordinate su una pagina è un pessimo modo per impararlo. Muoverci dentro qualcosa è un buon modo. Sostituisci il tuo onOverlayUpdate con questo, e aggiungi sopra di esso le due nuove callback e le quattro variabili.

local turnLeft  = false
local turnRight = false
local tiltUp    = false
local tiltDown  = false

Queste vanno proprio in cima al file, sopra tutto il resto.

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 e onInputReleased sono callback, come onOverlayUpdate: le scrivi tu, e Singe le chiama quando un comando viene premuto o rilasciato. Una pressione arriva una volta sola, non di continuo mentre il tasto è tenuto premuto, ed è per questo che ognuna imposta una variabile e il lavoro lo fa la callback di disegno. Quello schema — la pressione alza un indicatore, il fotogramma legge l’indicatore — è il modo in cui ottieni «mentre il tasto è tenuto premuto» da un motore che ti dice solo i cambiamenti.

I nomi SWITCH_ vengono dal motore stesso, quindi non c’è niente da caricare per usarli. E non sono nemmeno tasti. Sono quello che un comando significa, e controls.cfg decide quale tasto, pulsante o direzione della levetta produce ciascuno. Oggi i tuoi tasti freccia mandano SWITCH_LEFT e compagnia; la levetta di un controller manda la stessa cosa, e il tuo script non si accorge mai della differenza.

I segni sono scelti in modo che ogni freccia sposti la faccia che stai guardando nella direzione che hai premuto. Girare attorno a Y di un angolo positivo sposta quella faccia vicina verso destra, quindi la freccia sinistra chiede un angolo negativo. Se ti sembra al contrario, scambia i segni; sono i tuoi comandi, non quelli del motore.

L’overlay sta ancora sopra

Aggiungi queste righe a onOverlayUpdate, sopra il 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))

Qui non c’è niente di nuovo, tranne quello sopra cui viene scritto. overlayPrint è la chiamata della prima lezione, che conta in celle di carattere e non vuole nessun font caricato, e sta disegnando sopra una scena 3D senza che nessuno le abbia detto niente.

Questa è la disposizione, e vale la pena dirla chiaramente: Singe disegna prima il video, poi sopra di esso la scena 3D, poi sopra ancora l’overlay. Il tuo punteggio, le tue vite, il tuo timer, il tuo mirino e i tuoi sottotitoli sono tutti lavoro dell’overlay, esattamente come nella seconda parte. Un gioco 3D tiene il suo punteggio nell’angolo con le stesse cinque righe che usa un gioco 2D.

nodeGetRotation restituisce tre numeri, gli angoli attorno a X, Y e Z, e questa riga tiene i primi due in pitch e yaw. Sono i nomi che si usano di solito: il pitch (beccheggio) è il muso che va su e giù, lo yaw (imbardata) è girare a sinistra e a destra. math.floor butta via la parte decimale, così i numeri smettono di sfarfallare.

Guarda lo yaw mentre tieni premuta la freccia sinistra. Scende oltre -180 e ricomincia da 180, perché gli angoli vengono riportati come la rotazione più piccola che ti porta lì e non come un totale progressivo. Se il tuo gioco ha bisogno di sapere quante volte il giocatore ha girato su se stesso, contalo tu.

Prova tu

  1. Sposta la telecamera. Cambia nodeSetPosition(camera, 0, 2, 7) in (0, 8, 7), poi (7, 2, 7), poi (0, 0.2, 7). Ogni volta nodeLookAt tiene il cubo al centro, quindi cambiando un solo numero ottieni un’angolazione diversa della stessa scena.

  2. Cambia l’obiettivo. Prova cameraSetPerspective(30, 0.1, 100), poi (90, 0.1, 100), senza spostare la telecamera. Un gioco sembra veloce con un campo visivo ampio e solenne con uno stretto, e questa è la manopola dell’atmosfera più economica che esista.

  3. Metti un secondo cubo. Copia le due righe che hanno creato il cubo, rinomina la variabile in mark, e dagli nodeSetPosition(mark, 3, 0, 0) e nodeSetScale(mark, 0.3). Adesso hai un punto di riferimento con cui confrontare il primo cubo. Spostalo a turno in (0, 3, 0) e (0, 0, -3) e di' ad alta voce quale asse è quale.

  4. Condividi la mesh. Invece di chiamare meshBox due volte, tieni la prima in una variabile e passa lo stesso handle a tutti e due i nodi. All’aspetto non cambia niente. È proprio questo il punto: una forma, due posti.

  5. Appendi la telecamera al cubo. Tieni il secondo cubo del passo precedente, altrimenti non resterà niente rispetto a cui vedere il movimento. Poi cerca nodeSetParent nel riferimento e appendi la telecamera sotto il primo cubo. Tieni premuta una freccia: la telecamera segue la rotazione del cubo, quindi il cubo sta fermo e il resto della scena ti gira attorno. Sei a una riga da una visuale in prima persona, ed è anche così che scopri che una telecamera d’inseguimento vuole un genitore e non dei conti.

Rompilo apposta

Sbaglia a scrivere il nome del materiale. Cambia la riga nodeSetMesh in modo che usi pain invece di paint:

nodeSetMesh(box, meshBox(2, 2, 2), pain)

Singe si ferma prima che il gioco parta e scrive qualcosa del genere:

15:nodeSetMesh:  Argument 3 must be a number.

È un errore di forma diversa da quello della prima lezione, e viene dal motore invece che da Lua. Il numero davanti è la riga. Il nome che lo segue è la chiamata che si è lamentata. La lamentela vera e propria è che la terza cosa che le hai passato non era un numero.

Vale la pena seguire il motivo, perché spiega un’intera famiglia di errori. pain è una variabile a cui non è mai stato dato un valore, e in Lua una variabile vuota è nil — il valore che vuol dire «qui non c’è niente». Passare nil a una chiamata che vuole l’handle di un materiale dà proprio questo. Quando una chiamata del motore ti dice «must be a number», cerca su quella riga il nome di una variabile scritto male, o un handle che ti sei dimenticato di tenere.

Cosa hai imparato

  • sceneEnable(true) accende il livello 3D, e niente viene disegnato in 3D finché non la chiami.

  • Un nodo è un posto nel mondo con una posizione, una rotazione e una scala. Mesh, luci e telecamere sono tutte appese ai nodi.

  • Una mesh è la forma e un materiale è l’aspetto, e una di ciascuna può essere condivisa da quanti nodi vuoi.

  • X è a destra, Y è in alto, e la Z negativa è la direzione in cui guarda la telecamera.

  • nodeSetPosition e nodeSetRotation impostano un valore direttamente; nodeMove e nodeRotate lo cambiano di una certa quantità.

  • Qualsiasi nodo può essere la telecamera. nodeLookAt la punta e cameraSet la sceglie.

  • Il campo visivo in cameraSetPerspective cambia la sensazione della scena senza spostare niente.

  • Una scena senza luce è nera, ed è la prima cosa da controllare quando non compare niente.

  • L’overlay c’è ancora, sta ancora sopra, ed è ancora il posto del tuo punteggio.

La prossima volta

Un cubo è un drago piuttosto scarso. La prossima lezione carica un vero modello — uno che il motore ha già estratto nella tua cartella di lavoro, quindi non c’è niente da scaricare e niente da disegnare — lo mette sul pavimento e lo illumina come si deve. È la ventitreesima lezione.

Lezione 23: Modelli e luce

La lezione finita

Cubi e sfere ti porteranno lontano, ma prima o poi il gioco vuole un drago. Un modello è una forma che qualcun altro ha costruito in un programma di modellazione: centinaia di triangoli, i suoi colori e le sue superfici, a volte uno scheletro e dei movimenti che vanno con esso, tutto in un solo file. Caricarne uno sono due righe. Fargli avere un aspetto decente è questione di luce, e la luce è gran parte di questa lezione.

Non ti servono grafica né download. La primissima volta che hai eseguito Singe, il motore ha estratto una cartella chiamata Singe nella tua cartella di lavoro, e lì dentro ci sono due modelli: DragonModel.glb, il drago della schermata del titolo del motore, e SingeText.glb, la scritta che c’è sotto. Questa lezione usa il drago.

La scena attorno

Un modello ha bisogno di un posto dove stare. Crea una cartella, crea dragon.singe al suo interno, e comincia con un pavimento e una telecamera. Se hai fatto la ventiduesima lezione qui non c’è niente di nuovo; se non l’hai fatta, è una scena accesa, una lastra piatta su cui stare e un punto da cui guardare.

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

Eseguilo con Singe -R dragon. Una lastra grigia, vista leggermente dall’alto, su uno sfondo blu scuro. La lastra è larga ventiquattro unità e spessa poco meno di mezza unità, e appoggiarla a y = -0.2 mette la sua superficie superiore esattamente a y = 0, il che rende facile ragionare su tutto quello che metterai dopo: il pavimento è zero.

Caricare il drago

Due righe.

local dragonModel = modelLoad("Singe/DragonModel.glb")
local dragon      = modelInstance(dragonModel)

Mettile dopo il pavimento e salva. Compare un drago, ed è decisamente troppo grande per l’inquadratura — stai guardando la sua parte centrale.

Cos’è appena successo

Le due righe fanno lavori diversi, e la differenza conta.

modelLoad legge il file, passa le forme e le loro superfici alla scheda grafica, e tiene tutto pronto. È la chiamata lenta. Falla una volta, quando il gioco parte, e mai nel mezzo della partita.

modelInstance mette una copia nella scena e ti restituisce un nodo — un nodo normale, dello stesso tipo che ti dà nodeNew, che posizioni, ruoti, scali ed elimini con le chiamate che già conosci. Creare un’istanza è la chiamata economica. Carica un albero, creane quaranta istanze e hai un bosco, con una sola copia delle forme sulla scheda grafica e quaranta posti in cui vengono disegnate.

Con il modello arriva tutto ciò che il file conteneva: le forme, le superfici e i loro colori, il modo in cui sono disposte le parti, l’eventuale scheletro e gli eventuali movimenti. Per un modello caricato non costruisci i materiali; si è portato i suoi.

La scala, e la prima cosa che va storta

Il drago è alto circa sette unità e mezza. La tua telecamera è nove unità più indietro. Ecco perché riempie la finestra.

nodeSetScale(dragon, 0.5)

Aggiungila sotto la riga modelInstance. Adesso è alto meno di quattro unità, sta sul pavimento ed entra nell’inquadratura.

Non è un dettaglio; è il primo problema più comune con un modello, e ha due facce. Un modello costruito in centimetri arriva cento volte troppo grande e vedi un’unica superficie enorme che riempie lo schermo, cosa che di solito sembra «la mia scena è rotta» invece di «sono dentro il collo del drago». Un modello costruito in qualche altra unità arriva così piccolo da essere un puntino, o invisibile contro lo sfondo, e pensi che il file non si sia caricato.

La soluzione è sempre la stessa: una scala sul nodo dell’istanza. Non sulle parti, non nel programma di modellazione se puoi evitarlo, ma un solo nodeSetScale sul nodo che ti ha dato modelInstance, scelto provando un numero e guardando. 0.01 e 100 sono risposte perfettamente normali.

Quando non riesci a capire quanto è grande una cosa, datti un righello. Mettile accanto un cubo di un’unità:

local ruler = nodeNew()
nodeSetMesh(ruler, meshBox(1, 1, 1), stone)
nodeSetPosition(ruler, 3, 0.5, 0)

Un oggetto grande quanto una cassa accanto al modello ti dice con un’occhiata se il modello è un drago o una montagna. Togli il righello quando hai finito.

Mentre lo sistemi, giralo verso di te:

nodeSetRotation(dragon, 0, -60, 0)

Il drago è stato modellato rivolto lungo la X positiva, cioè verso destra, quindi parte di profilo. Girarlo attorno a Y lo porta verso la telecamera. Il «davanti» di un modello è la direzione che ha scelto chi l’ha costruito, quale che sia, e per scoprirla devi girarlo e guardare.

La luce

Esegui quello che hai adesso. Il drago c’è, ed è deprimente: una forma piatta e fioca, senza riflessi e senza ombra. È perché l’unica luce nella tua scena è quella ambiente, il debole chiarore da ogni direzione che imposta sceneSetAmbient.

È la delusione più comune in assoluto nel 3D, e capita a tutti: il modello si è caricato perfettamente e la scena è nera, o quasi, perché niente lo illumina. Prima di sospettare del file, metti una luce.

Ce ne sono di tre tipi, e ognuna è un nodo, quindi le posizioni e le punti con nodeSetPosition e nodeLookAt come tutto il resto.

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 è un sole. Viene trattato come se fosse infinitamente lontano, quindi conta solo la direzione in cui splende e tutto nella scena ne riceve la stessa quantità. La sua posizione serve a nodeLookAt per puntarlo. È la luce che dà a una scena la sua forma principale, e la maggior parte delle scene ne vuole esattamente una.

lightSetIntensity è la luminosità. Per una luce direzionale, 1 porta fino al bianco una superficie bianca rivolta dritta verso di lei, quindi 1.8 è una giornata luminosa. lightSetColor la tinge: un bianco un po' caldo per il sole, un blu freddo per la luce della luna, e per il resto la sezione sulle luci del riferimento.

lightSetShadow(sun, true) è quello che fa stare il drago sul pavimento invece di farlo fluttuare sopra. Le ombre sono spente per impostazione predefinita perché ogni luce che proietta ombre costa un altro passaggio su tutta la scena a ogni fotogramma. Accendile per l’unica luce che conta e lasciale spente per le altre; una macchina piccola ti ringrazierà.

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 è una lampadina. Sta in un punto, splende in tutte le direzioni e si affievolisce con la distanza. Quell’affievolirsi è il motivo per cui il numero è 14 e non 1: l’intensità di una luce puntiforme è la sua luminosità nel punto in cui si trova la luce, e dopo poche unità non ne resta molta. Una lampadina che illumina una stanza di solito vuole qualcosa nell’ordine delle decine. Se una luce puntiforme sembra non fare niente, il motivo è quasi sempre questo.

lightSetRange dice fin dove arriva prima di spegnersi del tutto, il che evita che una lampada in una stanza illumini debolmente quella accanto, e impostarlo non costa niente.

Il terzo tipo è LIGHT_SPOT, un cono che punta lungo la Z negativa del nodo stesso, con lightSetCone per l’angolo del centro luminoso e del bordo sfumato: una torcia elettrica, un faro d’auto, un riflettore. Possono splendere fino a otto luci contemporaneamente, più di quante ne servano alla maggior parte delle scene. Se ne vuoi di più, in realtà ne vuoi di meno.

Eseguilo adesso. Un sole quasi bianco da sinistra, un caldo bagliore arancione da destra, un’ombra sulla lastra, e un drago con un davanti e un dietro.

I materiali, quanto ti basta per oggi

Il drago si è portato i suoi materiali, e sono tre: un metallo scuro, un metallo più chiaro color champagne, e un vetro chiaro in cui lo sguardo entra un poco. La maggior parte delle sue parti è ricavata da più di uno. Non devi toccare niente di tutto questo, e la maggior parte delle volte non dovresti.

Quando vuoi davvero cambiare l’aspetto di una parte di un modello, crei un materiale come nella ventiduesima lezione e lo metti sulla parte:

local red = materialNew()
materialSetColor(red, 220, 50, 40)
materialSetRoughness(red, 0.4)
nodeSetMaterial(nodeFind("crest", dragon), red)

nodeFind(name, root) cerca in un’istanza di un modello una parte con il nome che aveva nel file e ne restituisce il nodo, oppure nil quando quel nome non c’è. È così che arrivi dentro un modello: una torretta, una ruota, una mano a cui appendere una torcia, o la cresta del drago.

La cresta è un pezzo solo di un solo materiale, quindi il suo nodo porta la forma stessa e la riga qui sopra la ridipinge. Una parte costruita con più materiali viene tenuta come un nodo con un figlio per ogni pezzo, e mettere un materiale sul genitore non cambia niente che tu possa vedere. Quando un nodeSetMaterial sembra non fare niente, il motivo è questo, e nodeGetChildren ti mostrerà che cosa c’è sotto.

Quattro numeri descrivono la maggior parte delle superfici. Il colore, da materialSetColor. materialSetRoughness, da 0 per uno specchio a 1 per il gesso. materialSetMetallic, che è 0 per quasi tutto — vernice, legno, plastica, pelle — e 1 per il metallo vero, e i valori intermedi servono a poco. E materialSetEmissive, che fa brillare una superficie del suo colore, per schermi, lampade e ferro rovente, senza illuminare niente attorno.

Una cosa da sapere sul metallo: una superficie metallica ti mostra i suoi riflessi invece di un colore suo, quindi in una scena senza niente da riflettere sembra scura e spenta. È per questo che il metallo scuro del drago ha bisogno del sole per prendere vita. La soluzione vera è un cielo (sceneSetSky), che avvolge la scena in un panorama che si vede dietro tutto e allo stesso tempo la illumina; ne parla «L’aspetto del fotogramma» nel riferimento.

I movimenti che il modello si porta dietro

Molti modelli contengono animazioni: una camminata, una corsa, una posa da fermo, una porta che si apre. Sono salvate nel file, e riprodurne una è una sola chiamata sul nodo radice dell’istanza.

animationPlay(dragon, "Walk", true)

Il secondo argomento è il nome della clip come lo salva il file, oppure il suo numero. true vuol dire ripeterla all’infinito. Altri due numeri facoltativi impostano la velocità e la dissolvenza incrociata: animationPlay(hero, "Run", true, 1.2, 0.4) riproduce la corsa un quinto più veloce e ci sfuma dentro in quattro decimi di secondo, così una camminata diventa una corsa senza scatti. animationStop, animationPause e animationIsPlaying fanno quello che dice il loro nome.

Quella riga non puoi ancora eseguirla, ed ecco il motivo onesto: il drago nella tua cartella Singe non ha animazioni. È un modello, non uno spettacolo. Chiedere una clip che non c’è ferma il gioco con un errore, quindi non dare mai niente per scontato — chiedi:

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 restituisce una tabella con i nomi delle clip nel file, in ordine, quindi clips[1] è la prima e #clips è quante ce ne sono — gli strumenti per le tabelle della sesta lezione, su una tabella che ha riempito il motore. Eseguilo e guarda la console: il messaggio compare, perché quel conteggio è zero.

Prendi l’abitudine di fare quel controllo con ogni modello che non hai fatto tu. Costa tre righe e trasforma «il gioco è morto all’avvio» in una frase nel log.

Muovere le parti da te

Un modello senza animazioni non è una statua. Le sue parti sono nodi, e i nodi girano.

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

Salvalo. Le ali battono, il drago gira lentamente su se stesso, e l’ombra sul pavimento batte con loro.

singeGetTicks è il numero di millisecondi da quando il motore è partito, quindi sale regolarmente per sempre. math.sin prende quel numero che sale e restituisce un valore che scivola dolcemente da -1 a 1 e indietro, un battito completo circa ogni secondo e mezzo con questo divisore. Moltiplicare per 22 lo trasforma in un angolo di ventidue gradi da ogni parte. Dividere per un numero più grande rallenta il battito; moltiplicare per un numero più grande lo allarga. Quella riga da sola è l’animazione più economica che esista, e vale la pena tenerla in tasca.

Le ali girano attorno al proprio asse X, e girano attorno alla spalla invece che attorno al centro dell’animale, perché chi ha costruito il file ha messo il nodo di ogni parte dove va l’articolazione. Un modello che non è stato costruito così farà girare le sue parti attorno al centro del modello, e la soluzione è spostare il nodo della parte, di cui parla la sezione sui nodi del riferimento.

Nota che il girare di tutto il drago non disturba il girare delle ali. Le parti sono appese sotto la radice dell’istanza, quindi ruotare la radice si porta dietro tutto, e la rotazione propria di ogni ala si aggiunge sopra. Quella disposizione — una cosa dentro una cosa dentro una cosa, ognuna che si muove nel mondo del suo genitore — è ciò a cui serve un albero della scena.

I tuoi modelli

Quando ne fai di tuoi, esportali da Blender — o da Maya, o da 3ds Max, o da qualsiasi altro programma moderno — come glTF 2.0 binario, cioè un file .glb. È la scelta predefinita di Blender ed è l’unico formato di modelli che Singe legge.

L’unica regola è che il file deve essere autosufficiente: le forme, le immagini sopra di esse e i movimenti, tutti dentro un solo .glb. Un file che fa riferimento a un .bin o a un .png che gli sta accanto viene rifiutato, con un messaggio che nomina quello che voleva. L’esportatore di Blender fa la cosa giusta con le sue impostazioni predefinite.

Non tutto quello che puoi costruire sopravvive al viaggio. La sezione «Modelli e animazione» del Riferimento, nel capitolo «Scene 3D», è l’elenco: che cosa viene letto, che cosa viene ignorato senza dire niente, e i limiti (uno scheletro può avere fino a centoventotto giunti, per esempio). Leggila una volta prima di passare un fine settimana su un modello, non dopo.

Prova tu

  1. Spegni le luci. Commenta tutto il blocco sun mettendo -- all’inizio di ogni riga, ed eseguilo. Poi fai lo stesso con sceneSetAmbient. Ricordati che aspetto ha, perché un giorno succederà senza che tu lo voglia.

  2. Sposta il sole. Cambia nodeLookAt(sun, 0, 1.5, 0) in nodeLookAt(sun, 0, 20, 0) così il sole punta sopra la testa del drago. Guarda l’ombra e i riflessi sparire. Puntare una luce non è decorazione.

  3. Scalda la torcia. Alza l’intensità della luce puntiforme da 14 a 60 e abbassa la sua portata a 4. Poi spostala in (0, 6, 0), sopra il drago. Una luce puntiforme è una lampadina, e stai scegliendo dove appenderla.

  4. Crea due istanze. Chiama modelInstance(dragonModel) una seconda volta, tienila in un’altra variabile, scalala e mettila in (-4, 0, -3). Un caricamento, due draghi. Poi prova invece a caricare il modello due volte e capisci perché non dovresti.

  5. Trova un’altra parte. Le parti del drago si chiamano head, jaw, neck, tail, body, crest, hornL, hornR, wingL, wingR, foreLegL, foreLegR, hindLegL e hindLegR. Fai ondeggiare la coda con un suo math.sin a una velocità diversa da quella delle ali. Poi prova nodeFind("wings", dragon) e guarda che cosa fa un nome sbagliato quando passi quel nil dritto a nodeSetRotation.

Rompilo apposta

Cambia il nome del file in Singe/Dragonmodel.glb — una sola maiuscola di differenza — ed eseguilo. Singe si ferma prima che il gioco parta:

13:modelLoad:  Unable to read Singe/Dragonmodel.glb.

La riga, la chiamata e la lamentela, in quest’ordine. «Unable to read» vuol dire che il motore ha cercato e non ha trovato niente, il che è quasi sempre una di tre cose: il nome è scritto male, le maiuscole sono sbagliate, o il file non è dove hai detto. Su Windows le maiuscole sarebbero state perdonate e poi il tuo gioco non avrebbe funzionato per nessuno su Linux, che è un bug peggiore di questo. Scrivi i nomi esattamente.

Lo stesso messaggio con un nome di file giusto vuol dire che il file non è dove l’ha cercato il motore. La cartella Singe viene creata nella cartella da cui esegui il motore, quindi se hai avviato Singe da un’altra parte, anche Singe/DragonModel.glb punta da un’altra parte.

Cosa hai imparato

  • modelLoad legge un .glb una volta; modelInstance ne mette delle copie tutte le volte che vuoi.

  • La radice di un’istanza è un nodo normale: posizionala, ruotala, scalala ed eliminala come qualsiasi altro.

  • Un modello si porta dietro le sue forme e i suoi materiali.

  • Un modello arriva alla dimensione che ha usato il suo autore, ed è per questo che un nodeSetScale sull’istanza fa parte del collocarlo.

  • Una scena senza luce è nera o quasi, ed è la prima cosa da controllare quando un modello ha un aspetto sbagliato.

  • Una luce direzionale è un sole, una luce puntiforme è una lampadina che si affievolisce con la distanza e vuole un’intensità molto più grande, e un faretto è un cono.

  • Le ombre sono spente finché lightSetShadow non le accende, e ognuna ha un costo.

  • nodeFind raggiunge una parte di un modello con il nome che ha nel file.

  • modelGetAnimations dice che cosa può riprodurre un modello, e chiedere una clip che non c’è è un errore.

  • Un modello senza animazioni si può comunque muovere una parte alla volta.

La prossima volta

Tutto in questa scena si muove perché gliel’hai detto tu, fotogramma per fotogramma. La prossima lezione passa quel lavoro a un motore fisico: casse che cadono, rotolano, si impilano e si fanno cadere a vicenda senza che tu scriva una riga di aritmetica — e la domanda più difficile di quando dovresti lasciarglielo fare. È la ventiquattresima lezione.

Lezione 24: Fisica

La lezione finita

Fino a ora ogni cosa che si muoveva nei tuoi giochi si muoveva perché i conti li facevi tu. Un numero saliva di due a ogni fotogramma; se superava un bordo lo facevi tornare indietro. È il modo onesto di far muovere un gioco, e la maggior parte dei giochi è fatta così.

Questa lezione passa i conti a qualcun altro. Un motore fisico simula il mondo — la gravità, le cadute, le scivolate, le pile, i rimbalzi, i rotolamenti e le cose che si urtano — e muove i tuoi nodi al posto tuo. Alla fine avrai un vassoio di casse e un cannone che le butta giù. L’ultima sezione parla di quando non fare niente di tutto questo, ed è la parte da leggere due volte.

Che cosa fa, e che cosa non fa

Dai a un nodo un corpo e la simulazione se ne prende carico. Da quel momento cade per gravità, atterra su qualunque cosa ci sia sotto, si inclina quando viene colpito fuori centro, resta fermo in una pila, scivola fino a fermarsi, e il nodo segue ovunque la simulazione lo metta. Smetti di impostarne la posizione. È questo il patto: cedi la posizione e la rotazione di quel nodo, e in cambio ottieni un comportamento che non hai dovuto scrivere.

Quello che non fa è qualsiasi cosa che riguardi il tuo gioco. Non sa che cos’è un punteggio, né che la cassa rossa è quella che vale punti, né che cadere dal bordo costa una vita. Non anima un personaggio che cammina, non sa che sensazione dovrebbe dare un salto, e non farà muovere un oggetto in un modo che puoi prevedere esattamente. La fisica è una macchina che produce un caos plausibile.

Le unità sono metri, chilogrammi e secondi. La gravità è 0, -9.81, 0 a meno che tu non dica altrimenti, cioè quella della Terra, verso il basso, in metri al secondo quadrato. Una cassa larga un’unità è larga un metro, e cade come tale. Se la tua scena è costruita a un’altra scala, tutto sembrerà cadere nello sciroppo o in un cartone animato, e la soluzione è costruire in metri.

Un pavimento e una cassa

Crea una cartella, crea crates.singe e scrivi questo. È una scena, una lastra, una cassa sopra la lastra e tre righe di fisica.

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

Eseguilo con Singe -R crates. La cassa cade da quattro metri d’altezza, atterra su uno spigolo perché l’hai inclinata, si rovescia su una faccia e si ferma. Premi F5 per eseguirlo di nuovo e guardala un’altra volta.

Niente in onOverlayUpdate muove qualcosa. Hanno fatto tutto le due chiamate a bodyNew.

Cos’è appena successo

bodyNew(floor, BODY_STATIC, SHAPE_BOX, 16, 0.4, 16)

bodyNew dà un corpo a un nodo. Prende il nodo, che tipo di corpo è, che forma deve usare la simulazione per lui, e le dimensioni di quella forma.

Ci sono tre tipi, e scegliere quello giusto è gran parte dell’abilità.

  • BODY_STATIC non si muove mai. Viene messo dove si trova il nodo quando crei il corpo, e lì resta per sempre. Pavimenti, muri, il terreno, il cabinato, il livello. Spostare il suo nodo dopo non sposta il corpo, ed è una trappola che vale la pena ricordare: statico vuol dire statico.

  • BODY_DYNAMIC viene mosso dalla simulazione. Cade, rimbalza, scivola, viene spinto, e si trascina dietro il suo nodo. Questo è una cassa, un barile, una palla, un pezzo di detrito.

  • BODY_KINEMATIC va dove metti tu il suo nodo, e spinge via i corpi dinamici senza mai essere spinto a sua volta. Una piattaforma mobile, una racchetta, una porta su un binario, il pugno che un personaggio fa partire. È il ponte tra i tuoi conti e la simulazione: tu guidi lui, lui guida loro.

La forma non è la mesh. È un sostituto approssimativo che la simulazione usa perché sa rispondere a domande su una scatola molto più in fretta che su novecento triangoli. SHAPE_BOX prende una larghezza, un’altezza e una profondità; SHAPE_SPHERE prende un raggio; SHAPE_CAPSULE e SHAPE_CYLINDER prendono un raggio e un’altezza. C’è SHAPE_HULL, che avvolge come una pellicola qualunque mesh ci sia sotto il nodo — la risposta solita per un modello — e SHAPE_MESH, i triangoli esatti, che lo scenario statico può usare e un oggetto che cade no.

Le dimensioni tocca a te azzeccarle. Niente controlla che il corpo che hai descritto corrisponda alla mesh che hai disegnato, e una cassa disegnata a 0.8 con un corpo fatto a 2 fluttuerà sopra il pavimento e farà cadere le cose a distanza. Quando qualcosa si comporta come se avesse un’altra dimensione, ce l’ha.

bodySetMass(crate, 4)

La massa di un corpo dinamico viene dalla sua forma alla densità dell’acqua, il che rende le cose molto più pesanti di quanto ti aspetti: una scatola grande quanto una porta pesa circa centoquaranta chilogrammi, e niente di quello che puoi lanciarle contro la sposterà. Imposta la massa di qualsiasi cosa debba sembrare leggera. Quattro chilogrammi sono una cassa che potresti sollevare.

La massa conta perché le forze vengono ripartite in base a essa. La stessa spinta sposta più lontano una cosa leggera, e un impulso pari a massa per velocità è quello che serve per mettere in moto qualcosa a quella velocità. Regola prima la massa e poi le forze, o finirai per inseguire la tua coda.

Far muovere le cose

Tre chiamate spingono in giro un corpo dinamico, e non sono intercambiabili.

bodySetVelocity(node, x, y, z) dice «adesso stai viaggiando a questa velocità», sostituendo qualunque cosa stesse facendo. È un servizio, un lancio, una comparsa con già un po' di velocità addosso.

bodyApplyImpulse(node, ix, iy, iz) è un colpo: un calcio, un’esplosione, una mazza che incontra una palla. Si aggiunge a quello che il corpo stava già facendo. Dagli un punto del mondo come altri tre numeri e colpisce lì invece che al centro, quindi una cassa colpita vicino alla cima si rovescia invece di scivolare.

bodyApplyForce(node, fx, fy, fz) è una spinta che dura: un razzo, un ventilatore, un nastro trasportatore. Una forza applicata per un solo fotogramma non fa quasi niente, il che sorprende chi si aspettava un impulso.

La gravità stessa è physicsSetGravity(x, y, z) e vale per tutto il mondo. La luna è physicsSetGravity(0, -1.62, 0), lo spazio è tutto zeri, e un gioco con la gravità di lato è a una riga di distanza.

Altre due impostazioni completano la sensazione di un oggetto. bodySetBounce(node, amount) va da 0, che si ferma di colpo, a 1, che torna indietro con tutto quello con cui è arrivato; il valore predefinito è un 0.1 appena percettibile. bodySetFriction(node, amount) è 0 per il ghiaccio e 0.5 per impostazione predefinita. Entrambe si combinano tra le due cose che si toccano, quindi un pavimento ghiacciato vuole il numero basso sul pavimento, non su tutto quello che ci cammina sopra.

Sapere quando le cose si toccano

function onCollision(nodeA, nodeB, x, y, z, speed)
    if speed > 4 then
        knocks = knocks + 1
    end
end

Lì knocks è una variabile tua, che aspetta in cima al file con local knocks = 0, e il giocattolo qui sotto la stampa.

onCollision è una callback, come onOverlayUpdate: la scrivi tu, il motore la chiama. Arriva una volta per ogni nuovo contatto — due corpi che restano a contatto non lo segnalano di nuovo — con entrambi i nodi, il punto del mondo in cui si sono incontrati, e la velocità con cui si sono incontrati. La velocità è quello che permette a una botta e a uno schianto di suonare diversi, ed è il motivo per cui il controllo qui sopra ignora il lento assestarsi di una pila.

L’altra metà della coppia è onTrigger. Rendi un corpo un trigger con bodySetTrigger(node, true) e smette di spingere le cose: diventa una zona che segnala che cosa ci entra e che cosa ne esce tramite onTrigger(trigger, other, entered). Un traguardo, una porta, una fossa, un oggetto da raccogliere. È il discendente 3D dei controlli di collisione dell’undicesima lezione, e per qualsiasi cosa che abbia la forma di «il giocatore è arrivato qui?» è la chiamata che vuoi, invece di un corpo solido.

Il giocattolo

Ora tutto quanto. Parti dallo script qui sopra e trasformalo in questo: un vassoio con quattro pareti, sei casse in piramide, e una palla d’acciaio che puoi puntare e sparare. I pezzi sono tutti cose che hai già incontrato.

Tutto quello che il nuovo codice ricorda va in cima al file, sopra la scena:

local crates     = {}
local balls      = {}
local aimX       = 0
local aimLeft    = false
local aimRight   = false
local knocks     = 0
local showShapes = false

Altri due handle condivisi vanno insieme ai materiali: un metallo lucido per la palla e per il segnalino di mira, e una sola mesh di cassa per tutte e sei le casse.

local steel = materialNew()
materialSetColor(steel, 200, 205, 215)
materialSetMetallic(steel, 1)
materialSetRoughness(steel, 0.25)

local crateMesh = meshBox(0.8, 0.8, 0.8)

Le pareti del vassoio sono quattro scatole statiche, fatte in un ciclo a partire da una tabella di posizioni, ed è la sesta lezione che fa un lavoro onesto:

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

Ogni voce è una X, una Z e una rotazione attorno a Y. Due pareti stanno di traverso dietro e davanti; due sono girate di novanta gradi per fare i lati. Una sola mesh basta per tutte e quattro, e il corpo viene creato dopo che il nodo è stato posizionato e girato, perché un corpo statico prende la posizione e la rotazione del nodo nel momento in cui viene creato.

Le casse vengono da una funzione, così sei casse sono sei righe:

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

Tiene ogni cassa che crea nella tabella crates, ed è così che più tardi la callback di disegno può fare una domanda a tutte. Sei chiamate costruiscono la piramide, tre sul pavimento, due sopra quelle e una in cima:

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)

Le file superiori stanno un dito più in alto di quelle sotto e cadono al loro posto appena il gioco parte. Lasciare un piccolo spazio è più facile che impilare con precisione, ed è più gentile verso la simulazione che consegnarle una pila già schiacciata.

Sparare crea ogni volta una palla nuova:

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

Guarda l’ordine. Il nodo viene creato, riceve una forma da disegnare, viene posizionato, e solo allora riceve un corpo. Un corpo dinamico parte da dove si trova il suo nodo, e dopo il traffico va nell’altro senso: è il corpo che muove il nodo. Impostare da te, dopo, la posizione di un nodo dinamico significa combattere la simulazione, e vince la simulazione. Quando qualcosa va spostato, dagli una velocità, colpiscilo con un impulso, o fai quello che fa questa funzione — creane uno nuovo e lascia andare quello vecchio.

Lasciar andare quello vecchio è nodeDelete, che libera il nodo, tutto quello che c’è sotto e il corpo che ci viaggiava sopra. Senza quelle tre righe ogni colpo resterebbe nel mondo per sempre, e qualche centinaio di palle dopo la simulazione farebbe un sacco di lavoro su cose che nessuno vede. Fare pulizia fa parte dell’usare la fisica.

I comandi e la visualizzazione sono il 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 spaziatrice spara, Maiusc accende e spegne la vista della fisica, e le frecce, tenute premute, fanno scorrere il punto di lancio. Una piastra di metallo piatta senza corpo, spostata a ogni fotogramma in aimX, mostra da dove partirà la prossima palla. Lo script completo, con la callback del rilascio e il resto della preparazione, è 24-physics.singe nella cartella learn.

physicsSetDebug è la chiamata più utile di questa lezione. Disegna quello che la simulazione contiene davvero — le forme vere in wireframe, e una croce rossa dovunque due corpi si sono toccati in questo passo — sopra la tua scena. La prima volta che una cassa fluttua un palmo sopra il pavimento, o ci cade attraverso, o fa cadere qualcosa da due metri di distanza, accendila e la risposta sarà sullo schermo. Aggiungi DEBUG_STATIC per vedere anche il pavimento e le pareti. Finché è spenta non costa niente.

Infine, il conteggio:

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 cassa conta come rovesciata quando è inclinata di più di trenta gradi, che è una regola del gioco scritta in una riga di aritmetica sopra qualunque cosa abbia fatto la simulazione. nodeGetRotation dà tre angoli e qui servono il primo e il terzo, quindi quello in mezzo viene raccolto in una variabile chiamata _. Quel trattino basso è un nome normale, senza niente di speciale, usato per convenzione per dire «questo lo ignoro».

bodyIsResting dice se la simulazione ha addormentato un corpo perché ha smesso di muoversi. È così che sai che un tiro è finito: non un timer, non una stima, ma ogni cassa addormentata. Un gioco di bowling conta i punti di ogni turno proprio lì.

Quando non usarla

La fisica è lo strumento più allettante di qualsiasi motore e quello che fa sprecare più fine settimana. Ci sono tre cose vere su di lei, e nessuna è colpa del motore.

È costosa. Ogni corpo dinamico è lavoro a ogni passo, sessanta volte al secondo, che qualcuno lo guardi o no. Quaranta casse vanno bene. Quattromila no, e su una macchina piccola nemmeno quattrocento.

È imprevedibile. Esegui il tuo giocattolo due volte e le casse atterrano in modo diverso. È ciò che la fa sembrare viva, ed è anche il motivo per cui un gioco non può contarci per niente che debba venire uguale ogni volta. Una porta che deve aprirsi, una piattaforma che deve arrivare, un salto che il giocatore deve poter fare: quelli sono aritmetica, o un tween, o un corpo cinematico su un percorso che hai scritto tu. Non lasciare mai una cosa che il giocatore deve fare a una simulazione che può farla finire dietro una cassa.

È difficile da regolare. La massa, l’attrito, il rimbalzo, la forma e la dimensione si tirano l’una con l’altra, e «non sembra giusto» raramente ha una causa sola. Ogni ora che passi a rendere convincente una cassa fisica è un’ora che non hai passato sul gioco.

Quindi usala quando il caos è il punto: cose che crollano, detriti che volano, una pila che si assesta, una palla che sbatacchia per una stanza, un veicolo che corre su un terreno accidentato, un ragdoll che ruzzola giù per una scala. Nessuno sa scriverlo a mano e nessuno sa dirti esattamente che aspetto dovrebbe avere.

Non usarla quando sai che cosa dovrebbe succedere. Un proiettile che vola dritto sono due righe della seconda lezione. Una piattaforma che va su e giù è math.sin. Un giocatore che cammina e salta come i giocatori si aspettano vuole un controller del personaggio (playerNew, nel riferimento), perché una persona non è una scatola e non si comporta mai come tale. Un nemico che pattuglia vuole un percorso. Un menu che entra scorrendo vuole un tween.

La regola che funziona meglio: usa la fisica per le cose che il giocatore guarda, e l’aritmetica per le cose che il giocatore fa.

Prova tu

  1. Cambia il mondo. Aggiungi physicsSetGravity(0, -1.62, 0) vicino all’inizio e spara di nuovo. Poi prova 0, -30, 0. Le stesse casse, un altro pianeta, una riga.

  2. Cambia la palla. Rendi la palla dieci volte più pesante con bodySetMass(ball, 30), poi dieci volte più leggera con 0.3, mantenendo la stessa velocità. Poi rimetti la massa com’era e cambia invece il -14. Due modi di colpire più forte, e non danno la stessa sensazione.

  3. Fai le casse di ghiaccio. Aggiungi bodySetFriction(crate, 0.02) in crateAt, e aggiungi una riga che dia un attrito basso anche al pavimento. Guarda la pila che si rifiuta di stare in piedi fin dall’inizio.

  4. Sbaglia apposta la forma. In crateAt, cambia le dimensioni del corpo in 2, 2, 2 lasciando la mesh a 0.8. Eseguilo, guarda le casse fluttuare e spingersi a vicenda dal nulla, poi premi Maiusc e guarda la vista di debug spiegarlo in una sola immagine.

  5. Conta i punti come si deve. Usa bodyIsResting su ogni cassa per accorgerti di quando il tiro è finito, e solo allora conta quante sono rovesciate e aggiungilo a un punteggio. Questa è la parte di un gioco di bowling che tiene il punteggio.

Rompilo apposta

Aggiungi una riga sotto il bodyNew del pavimento per renderlo pesante, che è una cosa ragionevole da pensare di volere:

bodySetMass(floor, 200)

Singe ferma il gioco con qualcosa del genere:

32:bodySetMass:  Node 1 is not a dynamic body, or the mass is not positive.

Il primo numero è la riga nel tuo file, quindi il tuo sarà diverso.

Il numero dopo Node è l’handle del nodo, il numero che ti ha restituito nodeNew. La lamentela è esatta: la massa appartiene alle cose che la simulazione muove, e un corpo statico non viene mosso da niente, quindi non ha una massa da impostare. Chiederlo è un segno che il corpo è del tipo sbagliato per quello che avevi in mente — e se vuoi davvero un pavimento pesante che si possa spostare, quello che vuoi è un corpo dinamico con una massa grande, o uno cinematico che sposti tu.

Lo stesso messaggio compare per una massa di 0, che la gente scrive intendendo «senza peso». Senza peso non è una massa. È un mondo senza gravità, oppure playerSetGravityScale su un controller del personaggio.

Cosa hai imparato

  • Un corpo si attacca a un nodo, e da quel momento il nodo e il corpo sono una cosa sola.

  • Statico non si muove mai, dinamico viene mosso dalla simulazione, e cinematico viene mosso da te e spinge via tutto il resto.

  • La forma di collisione è un sostituto della mesh, e tocca a te fare in modo che le sue dimensioni corrispondano a quello che hai disegnato.

  • La massa predefinita è il volume della forma alla densità dell’acqua, quindi impostala su qualsiasi cosa debba sembrare leggera.

  • bodySetVelocity sostituisce il moto di un corpo, bodyApplyImpulse è un colpo, e bodyApplyForce è una spinta che dura.

  • Non impostare la posizione di un nodo dinamico; eliminalo e creane uno nuovo quando devi farlo ripartire da capo.

  • onCollision segnala ogni nuovo contatto con il suo punto e la sua velocità, e un corpo trigger segnala arrivi e partenze tramite onTrigger.

  • bodyIsResting ti dice quando tutto si è fermato, che di solito è quando un turno è finito.

  • physicsSetDebug disegna la vista della simulazione stessa, e risponde alla maggior parte delle domande sulla fisica più in fretta che leggere il codice.

  • La fisica è costosa, irripetibile e pignola. Usala per il caos, non per le cose da cui dipende il gioco.

La prossima volta

Le casse che cadono sono un tipo di spettacolo. L’altro tipo è fatto di mille cosine che vivono mezzo secondo: scintille, fumo, fuoco, pioggia e polvere. La prossima lezione parla di emettitori, e finisce con un’esplosione. È la venticinquesima lezione.

Lezione 25: Particelle

La lezione finita

Alla fine di questa lezione una nave attraverserà la parte bassa dello schermo con una scia di fuoco dal motore, e un pulsante la farà saltare in aria in centoquaranta scintille rotanti che rimbalzano sul pavimento. Non scriverai una sola riga che disegni una scintilla.

L’idea di questa lezione è tutta qui. Tu descrivi il fuoco; il motore lo fa.

Perché le scintille non le disegni tu

Potresti farlo nell’altro modo. Ne sai abbastanza: una tabella di scintille come nella sesta lezione, ognuna con una x, una y e una velocità; un ciclo in onOverlayUpdate che le muove tutte, le fa sbiadire, le toglie quando muoiono e le disegna. Funziona. Sono anche duecento righe di contabilità che ogni gioco riscrive, e girano in Lua, una scintilla alla volta, sessanta volte al secondo.

Invece lo fa Singe per te. Gli consegni una ricetta — quante scintille al secondo, quanto vive ciascuna, quanto veloci e in che direzione partono, che cosa le tira, che aspetto hanno e verso quale colore sbiadiscono — e le scintille le gestisce lui. La cosa che contiene la ricetta e la esegue si chiama emettitore.

Un emettitore non è un’immagine e non è un oggetto del tuo gioco. È la descrizione di un tipo di fuoco, tenuta in un posto che puoi indicare, e può fare quel fuoco ovunque tu glielo chieda.

Comincia da qualcosa che si muove

Le particelle sono più convincenti quando escono da qualcosa, quindi comincia con una nave. Crea una cartella, copiaci dentro la cartella art del libro e metti questo in 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

Eseguilo con Singe -R particles e guida con i tasti freccia sinistra e destra. Qui non c’è niente di nuovo: uno sprite dalla nona lezione, gli interruttori dalla terza lezione e singeGetTicks, così la nave si muove alla stessa velocità qualunque sia la frequenza dei fotogrammi.

L’unica riga che vale la pena indicare è dofile("Singe/Framework.singe"). È quella che definisce DIR, la cartella in cui si trova il tuo script, così DIR .. "art/spaceship.png" trova l’immagine da qualunque cartella tu abbia avviato Singe.

Dagli uno scarico

Ora il fuoco. Aggiungi questo sopra le callback, dopo le variabili della 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)

E due righe dentro onOverlayUpdate. La prima va subito prima di overlayClear, la seconda subito dopo spriteDraw:

    emitterSetPosition(exhaust, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT - 2)
    emitterDraw(exhaust)

Salva. Adesso la nave sta sopra una corta lingua di fiamma gialla, e la fiamma la segue quando sterzi.

Falla esplodere

Uno scarico va avanti per sempre. Un’esplosione succede una volta sola, e il motore la tratta come un tipo diverso di richiesta allo stesso emettitore.

Prima, altri due file e un altro numero. Questi vanno in cima, accanto allo sprite della nave:

local sparkSprite = spriteLoad(DIR .. "art/star.png")
local boomSound   = soundLoad(DIR .. "art/boom.wav")

e questo va accanto a shipX e shipY, venti unità sopra il fondo dello schermo:

local ground = overlayGetHeight() - 20

Ora la seconda ricetta, sotto la prima:

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)

Nota che manca emitterStart. Questo non emetterà mai un flusso.

Aggiungi una funzione per farlo scattare, sopra 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

Servono altre tre cose: local RESPAWN_MS = 1400 con le altre costanti, local flying = true con le altre variabili e un ramo in onInputPressed:

    elseif what == SWITCH_BUTTON1 then
        explode()

Infine, la nave non dovrebbe esserci mentre è a pezzi. Racchiudi la guida e il disegno di onOverlayUpdate dentro if flying then …​ end, e aggiungi emitterDraw(boom) accanto all’altra chiamata di disegno. Lo script finito è learn/25-particles.singe.

Premi la barra spaziatrice — il pulsante uno, se non hai cambiato niente — e la nave va in pezzi in una nube di stelle che girano su se stesse, scendono ad arco, colpiscono il pavimento e rimbalzano.

Cos’è appena successo

In questa lezione ci sono moltissime chiamate nuove, e hanno tutte la stessa forma: prima l’emettitore, poi la cosa che stai impostando. Prendile a gruppi.

local exhaust = emitterNew()

Crea un emettitore e ti restituisce un handle: un numero che il motore usa per ritrovarlo, esattamente come il numero che ti dà spriteLoad. Senza argomenti ottieni un emettitore bidimensionale, che vive nelle coordinate dell’overlay e si disegna da onOverlayUpdate. Se invece dai a emitterNew un nodo, ne ottieni uno tridimensionale, che vive nella scena e si disegna da solo; tutto il resto di questa lezione vale per entrambi.

Un emettitore nuovo ha già una ricetta completa — cinquanta particelle al secondo, bianche, un secondo o due di vita, che salgono piano lungo lo schermo — quindi ogni chiamata dopo questa sei tu che non sei d’accordo con un valore predefinito. La voce del Riferimento per emitterNew li elenca tutti.

emitterSetRate(exhaust, 90)
emitterSetLife(exhaust, 0.15, 0.40)

Novanta particelle al secondo, ognuna che vive tra quindici centesimi e quattro decimi di secondo. Questi due numeri insieme decidono quanto fuoco c’è: novanta al secondo che vivono un terzo di secondo vuol dire circa trenta sullo schermo in ogni momento.

Ovunque una chiamata di un emettitore prenda un minimo e un massimo, ogni particella riceve un proprio valore scelto a caso tra i due. È da lì che viene l’irregolarità. Un fuoco in cui ogni fiamma vivesse esattamente quanto tutte le altre sembrerebbe una macchina.

emitterSetDirection(exhaust, 0, 1)
emitterSetSpread(exhaust, 12)
emitterSetSpeed(exhaust, 40, 90)

In che direzione partono, quanto è largo il ventaglio e quanto vanno veloci. La Y dell’overlay cresce verso il basso, come dalla prima lezione, quindi (0, 1) è verso il basso dello schermo — fuori dal retro di una nave che punta in alto. emitterSetSpread è metà dell’angolo del ventaglio: dodici gradi sono un getto stretto, novanta lo aprono a mezzo cerchio e centottanta sono tutte le direzioni insieme.

emitterSetSize(exhaust, 7, 1)
emitterSetColor(exhaust, 255, 240, 180, 255, 255, 60, 0, 0)

Sono queste due a far sembrare la fiamma una fiamma. Una particella non ha una dimensione e un colore; ha una dimensione e un colore alla nascita e altri alla morte, e scivola in modo uniforme dagli uni agli altri lungo la vita che le è toccata. Così ogni scintilla comincia larga sette unità dell’overlay e giallo pallido, e finisce larga un’unità e rosso arancio con un alfa di zero, cioè invisibile. Si rimpicciolisce e svanisce perché hai detto tu dove finisce, non perché qualcosa l’abbia fatta svanire.

emitterSetColor prende otto numeri, che sono tanti da leggere: rosso, verde, blu e alfa all’inizio, poi rosso, verde, blu e alfa alla fine.

emitterSetBlend(exhaust, PARTICLE_ADD)

Come una particella si combina con ciò che ha dietro. PARTICLE_ALPHA è la pittura normale ed è il predefinito: usalo per fumo, polvere, pioggia e macerie. PARTICLE_ADD invece aggiunge la sua luce all’immagine, quindi due scintille una sopra l’altra sono più luminose di una e niente diventa mai più scuro. Fuoco, scintille, laser e magia sono additivi. Il fumo no, e il fumo disegnato in modo additivo sembra vapore illuminato da dentro.

emitterSetMax(exhaust, 120)
emitterStart(exhaust)

emitterSetMax è la dimensione della riserva: quante particelle di questo emettitore possono esistere insieme. Quando la riserva è piena non nasce niente di nuovo finché qualcosa non muore. Novanta al secondo che vivono fino a quattro decimi di secondo ne richiedono circa trentasei, quindi centoventi bastano e avanzano. Impostalo prima di avviare, perché cambiarlo dopo butta via ogni particella viva.

emitterStart apre il rubinetto. Da lì in poi l’emettitore crea particelle a ogni fotogramma, che tu lo disegni o no, finché emitterStop non lo richiude. Nota che cosa emitterStop non fa: ferma le particelle nuove, e quelle già vive finiscono la loro vita e svaniscono normalmente. Ecco perché lo scarico si dissolve a poco a poco invece di sparire quando la nave esplode. Se le vuoi via all’istante, emitterClear le uccide.

    emitterSetPosition(exhaust, shipX + SHIP_WIDTH / 2, shipY + SHIP_HEIGHT - 2)

È così che un emettitore segue qualcosa. Un emettitore bidimensionale fa nascere le particelle in un solo punto, e quel punto è dove l’hai messo l’ultima volta, quindi lo imposti a ogni fotogramma da qualunque cosa si stia muovendo: la posizione di uno sprite, il nodo di un corpo fisico, il mouse. Le particelle nuove compaiono nel nuovo posto; quelle già in aria restano dove sono nate, ed è proprio quello che serve per uno scarico, perché lo scarico resta indietro.

Un emettitore tridimensionale viene creato su un nodo e segue quel nodo da solo, senza nessuna chiamata nel tuo aggiornamento. E quando vuoi che l’intera nube viaggi con la cosa — uno scudo, un’aura, il pennacchio di un propulsore visto da fuori — emitterSetLocal lo attiva.

    emitterDraw(exhaust)

Gli emettitori bidimensionali si disegnano quando lo chiedi tu, una volta per fotogramma, da onOverlayUpdate. L’ordine delle tue chiamate a emitterDraw è l’ordine in cui si sovrappongono. Dimenticare questa chiamata è l’errore che tutti fanno una volta: l’emettitore continua a funzionare, continua a consumare la sua riserva e non mostra niente.

Ora le chiamate tutte dell’esplosione.

emitterSetTexture(boom, sparkSprite)

Senza una texture ogni particella è un morbido disco rotondo che il motore disegna da sé, ed è quello che usa lo scarico, giusto per una fiamma. Con una texture, ogni particella indossa quell’immagine — qui star.png, otto pixel per otto. L’emettitore si tiene una sua copia dei pixel, quindi dopo puoi scaricare lo sprite e le particelle continuano a funzionare.

emitterSetGravity(boom, 0, 160)
emitterSetDrag(boom, 0.9)

La gravità è un’attrazione costante, in unità dell’overlay al secondo al secondo, ed è positiva verso il basso per lo stesso motivo per cui lo scarico spara con una Y positiva. La resistenza è il contrario: toglie velocità, un po' a ogni fotogramma, così le scintille partono forte e poi restano sospese. Scintille con la gravità e senza resistenza piovono dritte giù come un fuoco d’artificio; è la resistenza a farle sembrare in movimento nell’aria.

emitterSetSpin(boom, -240, 240)
emitterSetSize(boom, 10, 2, 0.4)

La rotazione è in gradi al secondo, e un intervallo a cavallo dello zero ti dà particelle che girano in tutti e due i versi. Si vede su una texture e non fa proprio niente al disco incorporato, che è rotondo.

Il terzo numero di emitterSetSize è la variazione. Scala entrambe le dimensioni di ogni particella per uno stesso fattore casuale — qui da sei decimi a uno e quattro decimi — così le scintille non sono tutte la stessa stella della stessa grandezza.

emitterSetCollide(boom, COLLIDE_FLOOR, 0.35, 0.3, ground)
emitterSetTrail(boom, 4, 2)

COLLIDE_FLOOR stende attraverso il mondo un pavimento piatto e invisibile all’altezza che indichi, e le particelle ci rimbalzano sopra. I due numeri che la precedono sono quanta velocità sopravvive a un rimbalzo e quanta velocità laterale viene strofinata via. Non costa niente, perché è un solo confronto per particella, e fa sembrare che i detriti siano atterrati da qualche parte invece di cadere attraverso il mondo. In un gioco tridimensionale COLLIDE_SCENE fa invece rimbalzare le particelle sulla geometria vera, e costa molto di più.

Una scia ricorda gli ultimi posti in cui è passata una particella e ci disegna attraverso un nastro che sbiadisce. Quattro posizioni e due unità di larghezza trasformano ogni stella in una breve striscia.

    emitterBurst(boom, 140)

E questo è l’altro modo di creare particelle. emitterStart è un rubinetto; emitterBurst è una manciata lanciata tutta in una volta. L’emettitore non deve per forza emettere un flusso, e questo non lo fa mai. Tutto il resto — la ricetta, la riserva, la posizione — funziona allo stesso modo.

Vale la pena tenere a mente questa distinzione. Tutto ciò che è continuo è un flusso che avvii e fermi: uno scarico, il fumo, la pioggia, una torcia, una cascata. Tutto ciò che succede in un istante è una raffica: un’esplosione, uno spruzzo, un passo nella polvere, un proiettile che colpisce, una vampata alla bocca di un’arma. Molti effetti sono tutte e due le cose, con uno o due emettitori: una granata scoppia e poi fuma.

Quante sono troppe

La risposta onesta è che le particelle costano poco da muovere e tanto da guardare.

Muovere diecimila particelle è aritmetica, e un computer che riesce a far girare un gioco lo fa senza accorgersene. Quello che costa è il disegno, e il disegno costa più o meno quanti pixel dello schermo coprono le particelle, sovrapposizioni comprese. Duecento scintille larghe otto pixel coprono meno schermo di uno sbuffo di fumo che lo riempie. La regola è questa: piccole e tante è quasi gratis, grandi e sovrapposte no.

La fusione additiva è il tipo costoso, perché niente di ciò che disegna si può saltare — ogni strato si aggiunge a ciò che c’è sotto, quindi la macchina li dipinge tutti. Una dozzina di lampi additivi a tutto schermo uno sopra l’altro riducono un Raspberry Pi 4 a passo di lumaca, mentre diecimila minuscole scintille che rimbalzano non gli danno nessun fastidio.

Quindi: qualche migliaio di particelle piccole non è niente di cui preoccuparsi. Prima di andare oltre, metti il conteggio sullo schermo e tienilo d’occhio.

    overlayPrint(2, 4, "Particles alive: " .. (emitterGetCount(exhaust) + emitterGetCount(boom)))

emitterGetCount è il modo onesto di dimensionare una riserva, invece di tirare a indovinare. Se il numero sta fermo esattamente sul tuo emitterSetMax, la riserva è piena e il motore si sta rifiutando in silenzio di creare particelle che hai chiesto. Se non ci arriva mai vicino, stai riservando memoria per niente.

Prova tu

  1. Trasforma lo scarico in fumo. Cambia emitterSetBlend(exhaust, PARTICLE_ADD) in PARTICLE_ALPHA, imposta il colore su un grigio che sfuma in un grigio trasparente, e fallo crescere invece di rimpicciolire con emitterSetSize(exhaust, 3, 14). Tre righe hanno fatto una macchina diversa.

  2. Togli la resistenza all’esplosione. Cancella la riga di emitterSetDrag e confronta. Poi rimetti la resistenza e togli invece la gravità. Una delle due sembra un fuoco d’artificio e l’altra sembra un incidente.

  3. Allarga lo scarico. Imposta emitterSetSpread(exhaust, 180). La nave smette di sembrare dotata di un motore. L’apertura lavora più di quanto pensi.

  4. Una raffica da mille. Cambia emitterBurst(boom, 140) in emitterBurst(boom, 1000) e guarda il conteggio sullo schermo. Non arriverà a mille. Capisci da emitterSetMax perché no, poi alza la riserva e fai le scintille quattro volte più grandi, e guarda che cosa succede alla frequenza dei fotogrammi.

  5. Fai esplodere dove la nave non c’è. Metti emitterSetPosition(boom, 40, 60) in explode al posto della posizione della nave. Un emettitore è la descrizione di un fuoco, non una cosa che vive da qualche parte, e puoi far scoppiare lo stesso in dieci posti nello stesso fotogramma.

Rompilo apposta

Le costanti — PARTICLE_ADD, COLLIDE_FLOOR, OVERLAY_UPDATED — sono nomi che Singe ha dato a dei numeri. Sbagliane una di poco e Lua non si lamenta, perché in Lua un nome a cui non è mai stato dato un valore non è un errore: è nil, il valore che vuol dire «qui non c’è niente».

Cambia la riga della fusione dello scarico con un nome che sembra altrettanto plausibile:

emitterSetBlend(exhaust, PARTICLE_ADDITIVE)

Singe si ferma prima che il gioco parta, indicando la riga del tuo file in cui si trova quella chiamata:

22:emitterSetBlend:  Argument 2 must be a number.

Questo errore ha una forma diversa dagli errori di Lua dell’ottava lezione, perché viene dal motore e non da Lua. C’è il numero di riga, poi la chiamata che ha protestato, poi la lamentela. L’argomento due di emitterSetBlend è il modo di fusione, e quello che è arrivato è nil, perché PARTICLE_ADDITIVE non è un nome che qualcosa abbia mai definito.

«Must be a number» vuol dire quasi sempre questo: una costante scritta male, o una variabile che pensavi di aver impostato. La soluzione è controllare il nome nel Riferimento, che lo scrive PARTICLE_ADD.

Cosa hai imparato

  • Un emettitore contiene la ricetta di un tipo di particella e gestisce da sé le particelle, così il tuo script non ne disegna mai una.

  • emitterNew senza argomenti crea un emettitore bidimensionale nelle coordinate dell’overlay; con un nodo ne crea uno tridimensionale nella scena.

  • Ogni emettitore parte con una ricetta completa, e ogni chiamata emitterSet…​ ne cambia una parte.

  • Ovunque una chiamata prenda un minimo e un massimo, ogni particella estrae a caso un suo valore tra i due, ed è da lì che viene l’irregolarità.

  • Dimensione e colore si impostano alla nascita e alla morte, e la particella scivola dagli uni agli altri lungo la sua vita.

  • emitterStart emette un flusso fino a emitterStop; emitterBurst lancia una manciata tutta in una volta. Gli effetti continui sono flussi, quelli momentanei sono raffiche.

  • emitterStop lascia finire le particelle vive; emitterClear le uccide subito.

  • Un emettitore bidimensionale si sposta con emitterSetPosition a ogni fotogramma e si disegna con emitterDraw a ogni fotogramma. Uno tridimensionale segue il suo nodo e si disegna da solo.

  • Le particelle costano quello che coprono sullo schermo, non quello che costa muoverle, e la fusione additiva è il tipo costoso.

  • emitterSetMax fissa il limite della riserva, e emitterGetCount ti dice se ne hai indovinato la dimensione.

La prossima volta

L’esplosione ha mosso centoquaranta cose senza che a nessuna venisse detto dove andare, ma erano scintille, e alle scintille non importa contro che cosa vanno a sbattere. La ventiseiesima lezione parla di qualcosa a cui importa: un personaggio che deve andare da qui a lì, con un muro in mezzo.

Lezione 26: Personaggi che si muovono da soli

La lezione finita

In questa lezione costruisci una stanza con un muro che la taglia a metà e ci metti dentro due personaggi. Uno lo mandi in un angolo premendo un pulsante. L’altro sceglie un posto a caso, ci va, e quando arriva ne sceglie un altro, all’infinito.

Nessuno dei due va a sbattere contro il muro, e tu non scrivi mai una riga che dica come aggirarlo. Questa è una novità. Ogni lezione fino a questa ha mosso le cose dove dicevi tu. Questa è la prima lezione in cui il gioco capisce qualcosa da solo.

Il problema di camminare verso qualcosa

Ecco il modo ovvio per far camminare un personaggio verso un punto, ed è il modo in cui tutti lo scrivono la prima volta. Prendi la destinazione, sottrai dove sei e fai un passettino lungo la linea tra le due, a ogni fotogramma, finché non ci arrivi.

In una stanza vuota funziona benissimo.

Metti un muro nella stanza e smette di funzionare, e smette in un modo che sembra stupido più che rotto: il personaggio marcia contro il muro e resta lì a strusciarcisi contro, a un metro da una porta che non riesce a vedere, perché niente in «fai un passo verso la destinazione» ha la minima idea che nel mondo ci siano delle forme.

Non puoi uscirne a forza di toppe. Girare di lato quando tocchi un muro fa incastrare il personaggio nel primo angolo che trova. E non basta nemmeno sapere dove sono i muri, perché la strada attorno a un muro può essere lunga, può allontanarsi dalla destinazione prima di tornare indietro, e può anche non esistere affatto.

Quello che serve è un modo per fare una vera domanda: come cammino da qui a lì? Per rispondere serve qualcosa che conosca la forma del pavimento.

Che cos’è una navmesh

Mettiti in piedi in una stanza e guarda il pavimento. Su una parte potresti camminare. Su un’altra no: è sotto un tavolo, dentro un muro, oltre il bordo di un balcone, o in cima a un gradino troppo alto da salire. Ora immagina di dipingere la parte su cui potresti camminare e di buttare via tutto il resto — i muri, i mobili, il soffitto, lo scenario. Quello che ti resta è una forma piatta, o più d’una, con dei buchi dove ci sono i pilastri e dei vuoti dove ci sono i dislivelli.

Quella forma dipinta è una navmesh (mesh di navigazione), ed è tutto ciò che serve a un personaggio per pianificare una camminata. Non è il livello. È una mappa semplificata delle parti del livello su cui una persona può stare in piedi, e siccome è semplice, alle domande su di essa si risponde in fretta.

Singe la crea per te dal livello che hai già. Gli dici quanto sono grandi i personaggi, gli consegni la geometria, e lui calcola che cosa è percorribile: pavimenti e rampe entro la pendenza che consenti, gradini non più alti di quanto consenti, con un margine tolto attorno a ogni muro e a ogni dislivello, così un personaggio che ha una sua larghezza non attraversa gli spigoli. Questo si chiama precalcolo, succede una volta sola, e il risultato si può salvare in un file e caricare la volta dopo.

Una stanza con un muro

Crea una cartella chiamata navigation e dentro comincia un file chiamato navigation.singe. Questa parte è una scena tridimensionale, che è l’argomento della ventiduesima lezione: una scena è un mondo disegnato in tre dimensioni, e tutto ciò che contiene è appeso a un nodo, cioè una posizione, una rotazione e una scala a cui puoi attaccare una forma.

Se hai saltato quella lezione, puoi seguire lo stesso questa. Prendi i prossimi due blocchi come «un pavimento grigio di venti unità per venti, tre muri color sabbia piantati sopra e una telecamera che guarda giù su tutto quanto».

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)

Qui le unità sono metri, perché è quello che presuppone il mondo tridimensionale di Singe. I primi due muri attraversano la stanza a metà con un varco di tre metri tra loro: una porta. Il terzo è un moncone che sporge nella metà lontana, per dare ai personaggi qualcosa da aggirare una volta passati.

Aggiungi una luce e una telecamera, così c’è qualcosa da vedere:

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

Eseguilo con Singe -R navigation. Un pavimento grigio, un muro con un varco e un moncone, visti dall’alto e da dietro.

Precalcola il pavimento

Sei righe trasformano quella stanza in una mappa:

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)

Mettile dopo i muri e prima della luce. Poi aggiungi una riga a onOverlayUpdate, sotto overlayClear, così puoi vedere che cosa hai ottenuto:

    navDraw(nav, 0, 170, 190)

Eseguilo di nuovo. Una ragnatela di triangoli verde-azzurri è stesa sul pavimento, e si ferma prima dei muri. Lo spazio che lascia non è una decorazione: è il margine di 0,4 metri che serve a un personaggio con un raggio di 0,4 metri perché le sue spalle non passino attraverso la pietra. La porta è ancora una porta nella mesh, perché tre metri bastano per passarci; fai il varco di mezzo metro e il blu si chiuderebbe sopra, e per tutti i personaggi del tuo gioco lì non ci sarebbe proprio nessuna porta.

Guardala per un momento, perché navDraw è lo strumento che prenderai in mano ogni volta che un personaggio fa qualcosa di inspiegabile. Nove volte su dieci la risposta è sul pavimento davanti a te.

Qualcuno che ci cammini

Un personaggio è un nodo. Che aspetto abbia non è affare della navigazione, quindi costruisci la cosa più economica che mostri da che parte è rivolto: una scatola con un naso.

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

Questa va insieme a addWall. Le serve un colore, quindi aggiungine uno accanto agli altri materiali:

local walkerLook = materialNew()
materialSetColor(walkerLook, 225, 85, 60)
materialSetEmissive(walkerLook, 70, 18, 10)

E adesso la riga per cui esiste questa lezione. Dopo navBuild:

local walker      = makeWalker(-7, 7, walkerLook)
local walkerAgent = navAgentNew(nav, walker, AGENT_RADIUS, AGENT_HEIGHT, WALK_SPEED)

navAgentNew mette il nodo sulla mesh e restituisce un agente: la parola del motore per una cosa che è disposto a far camminare al posto tuo. Da questo momento la posizione di quel nodo è del motore. A ogni fotogramma lo sposta e lo gira verso la direzione in cui va, e continuerà a farlo finché non gli dici dove andare o non gli togli l’agente.

Eseguilo. Una scatola rossa con un naso compare nell’angolo vicino e non fa assolutamente niente, perché non le hai ancora chiesto niente.

Mandarlo da qualche parte

Dagli un elenco di posti e un pulsante.

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

Stampa il messaggio, così vedi che cosa sta succedendo. In onOverlayUpdate, dopo navDraw:

    overlayPrint(2, 2, message)

Eseguilo e premi il pulsante uno — la barra spaziatrice, se non hai cambiato niente. La scatola si gira, cammina fino all’angolo lontano della sua metà della stanza e si ferma. Premi di nuovo. Cammina lungo il muro, trova la porta, la attraversa, esce dall’altra parte e si ferma nell’angolo lontano. Premi una terza volta e aggira il moncone fino al quarto angolo. Non le hai detto della porta. Niente nel tuo script parla della porta. L’ha trovata lei, perché la porta è un buco in una forma, e aggirare i buchi è proprio ciò a cui serve la mesh.

Ogni voce di posts è fatta di tre numeri, una x, una y e una z, perché un punto in un mondo tridimensionale ne vuole tre. La Y è in alto, e le tue sono tutte a zero perché qui tutto sta per terra. La tabella posts è una tabella di tabelle, come nella sesta lezione, e posts[post] è una di quelle interne.

Sapere quando arriva

La scatola si ferma quando arriva, ma il tuo script non sa che è arrivata. Chiedi di essere avvisato:

function onNavArrived(agent)
    message = string.format("Arrived at post %d.", post)
end

Questa è una callback, la stessa idea di onOverlayUpdate nella prima lezione: tu la scrivi, il motore la chiama. Questa viene eseguita una volta sola, nel momento in cui un agente raggiunge la destinazione che gli è stata data. Non quando è vicino, e non a ogni fotogramma dopo — una volta, all’arrivo.

Le viene passato l’agente, perché un gioco ne ha più di uno. Quell’argomento è il numero che ti ha restituito navAgentNew, e confrontarlo è il modo per capire quale dei tuoi personaggi è appena arrivato dove stava andando.

Quando non c’è un percorso

Premi il pulsante una quinta volta e il messaggio dice No path to post 5. Staying put., e la scatola non si muove.

La postazione cinque è a { 30, 0, 30 }, cioè venti metri fuori da una stanza larga venti metri. Lì non c’è pavimento percorribile, non c’è una strada per arrivarci e non c’è niente di sensato che un personaggio possa farci. navAgentMoveTo lo dice restituendo false, e lascia l’agente esattamente com’era.

Questa è la parte che i principianti saltano, ed è quella che morde. I giochi veri chiedono di continuo camminate impossibili, perché la destinazione di solito è il giocatore, e il giocatore va dappertutto: in piedi su una cassa, a metà di un salto, in acqua, dietro una porta che si è chiusa, o in un varco che la navmesh ha tolto perché troppo stretto. Ognuno di questi casi fa restituire false a un navAgentMoveTo perfettamente ragionevole.

Che cosa voglia dire lo decide il tuo script. Una guardia che non riesce a raggiungerti dovrebbe tornare a fare la ronda, o camminare fino al punto più vicino che può raggiungere e aspettare lì, o gridare. Quello che non deve fare è niente, mentre il tuo codice ignora in silenzio un false restituito e tu ti chiedi per un’ora perché un nemico su venti è congelato.

Qui aiutano altre due chiamate, e vale la pena conoscerle prima che ti servano. navNearest prende un punto qualsiasi e restituisce il posto più vicino sulla mesh, o nil se lì vicino non c’è niente, ed è così che trasformi «dov’è il giocatore» in «un posto dove un personaggio può davvero stare in piedi». E navPath fa la stessa domanda di navAgentMoveTo senza muovere nessuno: restituisce gli angoli del percorso come una tabella di punti, o nil quando un percorso non c’è. Puoi misurarlo, disegnarlo o decidere che la camminata è troppo lunga per prendersi il disturbo.

Disegnarlo è il trucco utile. Aggiungi questo 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

Ora una linea gialla va dalla scatola a dovunque stia andando, piegandosi attraverso la porta e accorciandosi mentre cammina. Mandala alla postazione cinque e la linea non viene proprio disegnata, perché navPath ha restituito nil e l’istruzione if l’ha intercettato. Stai guardando la decisione che sta prendendo l’agente, disegnata sul pavimento.

Un secondo camminatore

Un personaggio che evita i muri è navigazione. Due personaggi che evitano i muri e si evitano a vicenda sono quello che il motore ti dà davvero, e costano quattro righe in più.

Aggiungi un materiale blu accanto a quello rosso, poi questo sotto il primo agente:

local wanderer      = makeWalker(6, -6, wandererLook)
local wandererAgent = navAgentNew(nav, wanderer, AGENT_RADIUS, AGENT_HEIGHT, 1.4)

Mandalo da qualche parte per farlo partire, dopo la telecamera:

navAgentMoveTo(wandererAgent, navRandomPoint(nav))

E insegna a onNavArrived a distinguerli:

function onNavArrived(agent)
    if agent == wandererAgent then
        navAgentMoveTo(agent, navRandomPoint(nav))
    else
        message = string.format("Arrived at post %d.", post)
    end
end

navRandomPoint sceglie un posto sulla mesh percorribile — uno qualsiasi, mai dentro un muro — e restituisce tre numeri, che sono esattamente quello che navAgentMoveTo vuole subito dopo. Siccome la callback scatta all’arrivo e la sua risposta è un altro viaggio, adesso la scatola blu vaga per la stanza finché il gioco resta acceso, con quattro righe e nessuno stato.

Guarda i due incontrarsi nella porta. Nessuno si pianta di colpo e nessuno passa attraverso l’altro: tutti e due si scostano un po', per tempo, e si incrociano. Sono gli agenti che si girano attorno a vicenda, ed è la differenza tra personaggi e mobili.

Lo script finito è learn/26-navigation.singe.

Cos’è appena successo

local nav = navNew(AGENT_RADIUS, AGENT_HEIGHT, 45, 0.3)

Avvia una navmesh, e i quattro numeri sono la descrizione della persona a cui è destinata: larga 0,8 metri, alta 1,8 metri, capace di camminare su una pendenza fino a quarantacinque gradi e di salire un gradino fino a 0,3 metri.

Ognuno di questi cambia la forma che ne esce. Un personaggio più largo perde più pavimento nel margine attorno ai muri e può trovare chiusa una porta. Uno più alto non passa sotto una trave bassa. Consenti una pendenza più ripida e una rampa diventa una strada; consentine meno e diventa una scogliera.

Il raggio decide anche con quanta precisione viene misurato il pavimento, quindi un raggio molto piccolo su un livello molto grande richiede molto tempo di precalcolo. Prima di scegliere i tuoi numeri vale la pena leggere la voce del Riferimento per navNew.

navAddNode(nav, ground)
navBuild(nav)

navAddNode consegna la geometria — un nodo e tutto ciò che gli sta appeso sotto, così com’è nel mondo in quel momento, quindi sistema le cose prima di aggiungerle. Una chiamata prende un intero modello caricato. Contano solo le forme vere: una luce, un suono o un corpo fisico da soli non aggiungono niente.

navBuild fa il precalcolo, ed è la chiamata lenta di questa lezione: niente che noteresti per una stanza come questa, un decimo di secondo per una cattedrale su un computer desktop, parecchi secondi su un Raspberry Pi. Fallo mentre è visibile una schermata del titolo, non mentre il giocatore aspetta.

Dopo, la geometria viene buttata via e la mesh è chiusa. Non puoi aggiungere altro. Se il tuo livello cambia forma — si apre una porta, crolla un ponte — precalcoli un’altra mesh, e navDelete libera quella vecchia.

Su una macchina lenta preferiresti non precalcolare affatto, quindi navSave scrive la mesh finita in un file e navLoad la rilegge, costruita e pronta. Precalcola una volta sulla tua macchina, distribuisci il file con il gioco, e il giocatore non aspetta mai.

local walkerAgent = navAgentNew(nav, walker, AGENT_RADIUS, AGENT_HEIGHT, WALK_SPEED)

Un agente è un nodo che il motore ha accettato di far camminare al posto tuo. Il raggio e l’altezza qui sono quelli che usa per stare alla larga dagli altri agenti, e l’ultimo numero è la sua velocità massima in metri al secondo — 2,2 è un passo svelto, 1,4 è una passeggiata, 6 è uno scatto.

Da qui in poi, non impostare tu la posizione di quel nodo. Due cose che muovono lo stesso nodo si fanno la guerra, e la guerra si vede come un movimento a scatti. Se il tuo personaggio deve essere spintonato dalla fisica oltre che camminare, c’è una chiamata apposta — navAgentSetPlayer passa invece la guida a un controller della fisica — e la voce del riferimento che la riguarda spiega quando ti serve.

local ok = navAgentMoveTo(walkerAgent, x, y, z)

Imposta la destinazione. Non ci cammina; dice dov’è il «lì», e il motore se ne occupa nei fotogrammi successivi. Puoi richiamarla in qualsiasi momento e la nuova destinazione sostituisce quella vecchia, ed è così che una guardia insegue un giocatore che corre: la ripunti una o due volte al secondo, non sessanta.

E restituisce true o false, e tu devi guardare.

navAgentStop(walkerAgent)

Sopra non è usata, ma è l’altra metà della coppia: dimentica la destinazione, e l’agente rallenta fino a fermarsi dov’è. onNavArrived non scatta, perché non è arrivato. Usala quando il motivo del viaggio è venuto meno.

Il punto non è la velocità

Un’altra chiamata, perché è quella che trasforma tutto questo da una dimostrazione in qualcosa che sembra un gioco.

    local vx, vy, vz = navAgentGetVelocity(walkerAgent)
    local speed      = math.sqrt(vx * vx + vz * vz)
    overlayPrint(2, 4, string.format("Speed %.2f", speed))

navAgentGetVelocity ti dice come si sta muovendo l’agente in questo momento: non dove sta andando, ma quanto veloce e in che direzione si sta davvero spostando in questo fotogramma. Guarda il numero mentre la scatola parte e mentre si ferma. Accelera dolcemente e rallenta dolcemente.

Quel numero è ciò a cui appendi un’animazione. Un personaggio le cui gambe si muovono alla velocità a cui si sta davvero spostando sembra vivo; uno il cui ciclo di camminata va a ritmo fisso mentre accelera sembra che stia pattinando. Con un vero modello al posto della scatola confronteresti quella velocità con un paio di soglie e riprodurresti un’animazione da fermo, una camminata o una corsa — che è l’argomento della ventitreesima lezione, e l’esempio del riferimento sotto navAgentGetVelocity è scritto proprio per quello.

Ed è questo il vero punto della lezione. Un personaggio che prende la linea dritta e veloce e si struscia lungo un muro è peggio di uno che parte un secondo dopo, si gira come si deve, passa dalla porta e rallenta quando arriva. Nessuno che guarda un gioco misura quanto in fretta lo ha raggiunto un nemico. Se ne accorge subito, senza saper dire perché, quando qualcosa si muove in un modo in cui una cosa viva non si muoverebbe.

Prova tu

  1. Chiudi la porta. Cambia i primi due muri così che il varco tra loro sia di mezzo metro invece che di tre: addWall(-4, 0, 13, 0.6) e addWall(6.5, 0, 7, 0.6). Eseguilo e guarda che cosa mostra navDraw prima di premere qualsiasi cosa. Poi manda la scatola dall’altra parte e guarda che cosa fa.

  2. Fai ingrassare tutti. Imposta AGENT_RADIUS a 2.0 ed eseguilo. La porta è ancora larga tre metri e i triangoli blu lì sono spariti. Non c’è niente di rotto; la mesh adesso sta rispondendo a una domanda diversa.

  3. Mandala dove c’è il mouse. Prendi il punto sotto il puntatore del mouse con sceneUnproject, agganciale alla mesh con navNearest e manda lì la scatola quando premi il pulsante. navNearest che restituisce nil è il caso che devi gestire, e succede ogni volta che il puntatore è fuori dal pavimento.

  4. Aggiungi altri quattro vagabondi. Metti le quattro righe del camminatore blu in un ciclo for, come nella quarta lezione, tieni gli agenti in una tabella e lasciali vagare tutti. Guarda la porta quando tre di loro la vogliono nello stesso momento.

  5. Precalcolala una volta sola. Chiama navSave(nav, "room.nav") dopo navBuild, poi sostituisci navNew, le chiamate a navAddNode e navBuild con un unico navLoad("room.nav", AGENT_RADIUS, AGENT_HEIGHT). Ora cambia la posizione di un muro ed eseguilo di nuovo. Quello che vedi è la trappola che viene con le mesh precalcolate, e vale la pena incontrarla una volta apposta.

Rompilo apposta

Il precalcolo chiude la mesh. Prova ad aggiungere un’altra cosa a cose fatte — una cassa che hai messo tardi, o un muro che avevi dimenticato — mettendo questa riga subito dopo navBuild(nav):

navAddNode(nav, ground)

Singe si ferma prima che il gioco parta, indicando la riga del tuo file in cui si trova quella chiamata:

68:navAddNode:  The mesh is already built.

La forma di un errore del motore è la riga, la chiamata che ha protestato e la lamentela, e questa lamentela vuol dire quello che dice: navBuild ha consumato la geometria che gli era stata data e non c’è più niente a cui aggiungere.

La soluzione non è mai spostare la chiamata a navAddNode. È accorgerti che hai la geometria di due livelli e vuoi due mesh, o che hai precalcolato troppo presto. Aggiungi tutto, poi costruisci, e costruisci per ultimo.

Cosa hai imparato

  • Fare passi verso una destinazione funziona in una stanza vuota e fallisce appena c’è un muro, e nessuna quantità di toppe lo sistema.

  • Una navmesh è una mappa semplificata del pavimento su cui un personaggio può stare in piedi, con i muri, i dislivelli e il margine attorno a loro tolti.

  • navNew descrive il personaggio a cui è destinata la mesh, navAddNode consegna la geometria del livello e navBuild la precalcola. Dopo il precalcolo non si può aggiungere altro.

  • navSave e navLoad tengono una mesh precalcolata in un file, così il giocatore non deve mai aspettarla.

  • navDraw ti mostra la mesh, ed è la prima cosa da guardare quando un personaggio si comporta in modo strano.

  • navAgentNew affida un nodo al motore perché lo faccia camminare; da quel momento non spostare tu quel nodo.

  • navAgentMoveTo imposta una destinazione e restituisce false quando non c’è modo di arrivarci. Gestirlo è compito tuo, e succede spesso.

  • onNavArrived viene chiamata una volta quando un agente raggiunge la sua destinazione, e le viene detto quale agente.

  • navPath risponde alla stessa domanda senza muovere nessuno, e nil vuol dire nessun percorso.

  • Gli agenti si girano attorno l’un l’altro oltre che attorno al livello.

  • navAgentGetVelocity è il modo in cui un ciclo di camminata si accorda al terreno percorso.

La prossima volta

Le tue due scatole adesso girano per una stanza in silenzio. La ventisettesima lezione parla di quello che ci metti dietro: musica che va in loop come si deve e resta a tempo con il video, e il MIDI, che permette a un gioco di suonare uno strumento — o a un vero strumento di suonare il gioco.

Lezione 27: Musica e MIDI

La lezione finita

Questa lezione è fatta di due lezioni che per caso abitano insieme.

La prima metà è la musica: come un gioco riproduce come si deve un brano musicale, perché non è la stessa cosa che riprodurre un effetto sonoro, e che cosa fare quando la musica deve restare a tempo con il video.

La seconda metà è il MIDI, che quasi nessuno ha mai incontrato e che dà a un gioco qualcosa che nient’altro gli dà. Alla fine, una tastiera collegata al tuo computer suonerà il tuo gioco.

Un effetto sonoro e un brano musicale sono cose diverse

Sai già come riprodurre un suono. Nella decima lezione hai caricato un .wav con soundLoad e l’hai fatto partire con soundPlay, e se punti quelle due chiamate su una canzone di quattro minuti la suoneranno.

Non farlo. Singe tiene separati gli effetti sonori e la musica, e la separazione conviene per quattro motivi.

  • Hanno volumi propri. soundSetVolume non tocca mai la musica e musicSetVolume non tocca mai gli spari. Ogni gioco mai uscito ne ha avuto bisogno, perché i giocatori abbassano la musica e alzano gli effetti.

  • La musica non ha un limite di canali. Gli effetti sonori si dividono sedici canali, e quando sono occupati tutti e sedici il diciassettesimo non suona. Un brano musicale non sta su un canale, quindi niente può scalzarlo.

  • Un handle è un brano, e si mette in pausa, riprende, si ferma e sfuma per conto suo senza disturbare nient’altro.

  • La musica va in pausa con il gioco. Premi il tasto di pausa e resta dov’è. Torna e riprende. Non devi scrivere niente perché succeda.

Una cosa che non è diversa vale la pena saperla, perché si tende a pensare il contrario: Singe decodifica un file musicale in memoria fin dall’inizio, esattamente come fa con un effetto sonoro. Un brano lungo costa memoria. Non viene letto dal disco un pezzo alla volta. Cinque minuti di musica sono qualche decina di megabyte di memoria finché restano caricati, quindi carica il brano per il livello in cui sei e scaricalo con musicUnload quando lo lasci.

Riprodurre un brano

Ogni lettore di questo libro ha già un brano musicale, perché il motore ne ha estratto uno nella tua cartella di lavoro la prima volta che hai eseguito qualcosa. Comincia un file con queste tre righe:

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

Eseguilo con Singe -R music. Dieci secondi di musica, poi ricomincia, e continua a ricominciare.

È questo che fa il -1. musicPlay prende un numero di ripetizioni: omettilo o passa 0 e il brano suona una volta, passa 3 e suona quattro volte in tutto, passa -1 e si ripete finché qualcosa non lo ferma. Un menu, una schermata del titolo o il sottofondo di un livello sono quasi sempre -1.

In quel piccolo script ci sono due dettagli che meritano due parole. musicLoad prende un percorso normale e non un percorso con DIR .., perché Singe/menuIntro.flac è uno dei file del motore e sta nella cartella che il motore ha estratto nella tua cartella di lavoro. musicIsPlaying risponde true o false, e la coppia and …​ or …​ in mezzo a quel overlayPrint è la scorciatoia di Lua vista nella terza lezione per scegliere uno tra due valori.

La scala del volume non è quella che conosci

musicSetVolume(64) lo imposta più o meno a metà. Gli effetti sonori vanno da 0 a 63; la musica va da 0 a 128, cioè il doppio.

Non è un errore e non è uno scherzo. Singe può eseguire giochi scritti per Hypseus, un motore il cui volume della musica è sempre stato su una scala da 0 a 128, e cambiare i numeri renderebbe in silenzio la musica di quei giochi due volte più forte di quanto volevano i loro autori. Così Singe tiene tutte e due le scale, ognuna legata alla famiglia di chiamate a cui appartiene. Effetti: da 0 a 63. Musica: da 0 a 128. Dai a musicSetVolume un numero fuori dal suo intervallo e lo script si ferma, come vedrai tu stesso alla fine di questa lezione.

Che cosa riproduce Singe

Quasi tutto. WAV, Ogg Vorbis, Opus, MP3, FLAC, WavPack, AAC e un lungo elenco oltre a questi, tutti con lo stesso musicLoad.

Due famiglie sono più interessanti di quelle normali, ed esistono tutte e due perché sono minuscole.

I moduli tracker — .mod, .s3m, .xm, .it e una cinquantina di parenti — contengono una manciata di brevi strumenti registrati e un elenco delle note su cui suonarli. Un motivo di quattro minuti può stare sotto i cento kilobyte.

Le chiptune — .nsf, .spc, .vgm, .gbs e simili — vanno oltre: contengono le scritture nei registri per il vero chip sonoro di un Nintendo, di un Mega Drive o di uno Spectrum, e Singe emula il chip per suonarle. Se vuoi che un gioco suoni come il 1989 e non come una registrazione del 1989, si fa così.

Le une e gli altri si caricano con musicLoad come qualsiasi altra cosa. La sezione Formati video, audio e dei contenitori del Riferimento ha l’elenco completo, compreso quale contenitore va con quale codec.

Fermare, mettere in pausa e sfumare

musicPause(theme)
musicResume(theme)
musicStop(theme)
musicStop(theme, 2000)

musicPause ferma il brano dov’è e musicResume riprende da quel punto. musicStop lo termina, e la volta dopo che lo riproduci il brano riparte dall’inizio. Con un secondo numero, musicStop sfuma il brano in uscita in quel numero di millisecondi invece di troncarlo di netto — qui due secondi. Quella sfumatura è in assoluto la cosa più facile che puoi fare per dare a un gioco un’aria finita. Una musica che si interrompe a metà battuta quando il giocatore attraversa una porta sembra un bug, anche a chi non saprebbe dire perché.

Chiama una qualsiasi delle quattro senza nessun handle e agisce su tutta la musica insieme, che è quello che vuole una schermata di pausa.

Ora il limite, detto onestamente, perché lo cercherai e non c’è: Singe non sa fare una dissolvenza incrociata tra due brani. musicSetVolume è un unico guadagno su tutta la musica, non un volume per brano, quindi non c’è modo di alzare un brano mentre un altro si abbassa. Quello che puoi fare è sfumare in uscita quello vecchio e far partire quello nuovo mentre se ne va, il che basta per un cambio di livello e, a orecchio, non è la stessa cosa per un tema di battaglia che scivola sotto un tema di esplorazione. Se oggi ti serve una vera dissolvenza incrociata, il modo per ottenerla è fare dei due pezzi un solo file e saltare al suo interno, o accettare la sovrapposizione.

Musica, video e restare a tempo

Se il tuo gioco riproduce video — l’argomento della terza parte — c’è una cosa da sapere sul suono, e non è affatto una chiamata della musica.

Singe mostra un fotogramma video quando si sente il suono che gli appartiene, non a colpi di timer. L’audio è l’orologio e l’immagine lo segue. È il verso giusto, perché un orecchio si accorge di un quinto di secondo di scarto in una voce, e un occhio non si accorge dello stesso scarto in una bocca.

Il motore misura il proprio percorso audio quando parte. Quello che non può misurare è tutto ciò che viene dopo che il sistema operativo ha consegnato il suono: un amplificatore, un televisore, un ricevitore HDMI, delle cuffie Bluetooth. Ognuno aggiunge un ritardo suo, diverso su ogni macchina, e si nota come un suono che arriva un attimo dopo la cosa che l’ha prodotto.

La soluzione è un numero:

singeSetAudioDelay(45)

Quarantacinque millisecondi di «l’audio è in ritardo; trattieni l’immagine per andargli dietro». Puoi anche passarlo come --audiodelay=45 sulla riga di comando o metterlo nella voce del gioco in games.dat. singeGetAudioDelay rilegge il valore in vigore, ed è quello che un menu di servizio mostra accanto al suo cursore.

Non devi tirare a indovinare il numero. Il menu di Singe ha una schermata di calibrazione: fa un clic una volta al secondo e fa lampeggiare lo schermo di bianco, tu regoli finché il lampo e il clic non avvengono insieme, e lei salva il risultato per tutti i giochi di quella macchina. La sezione Sincronizzazione dell’audio del Riferimento la descrive e spiega perché funziona. Se costruisci un cabinato, eseguila una volta dopo aver collegato gli altoparlanti, e non pensarci mai più.

L’altra cosa che si chiama MIDI

MIDI è il nome di due cose che non hanno niente a che fare l’una con l’altra, e tenerle separate è quasi tutto quello che serve per capirlo.

Ecco la prima, in un paragrafo. Una registrazione — un .wav, un .mp3 — è una misura di un suono, presa quarantaquattromila volte al secondo. Il MIDI non è questo. Un file MIDI contiene che cosa è stato suonato: in questo momento, su questo canale, premi il tasto sessanta con questa forza; poco dopo, lascialo andare. È più vicino a uno spartito, o al rullo perforato di una pianola, che a una registrazione. Ecco perché un file MIDI pesa pochi kilobyte quando la stessa musica come audio pesa qualche megabyte, ed è anche il motivo per cui un file MIDI non contiene proprio nessun suono. Qualcosa deve suonare le note.

Un file MIDI è musica, quindi si riproduce come la musica:

local tune = musicLoad("music/overworld.mid")
musicPlay(tune, -1)

Ma la cosa che suona le note deve venire da qualche parte, e quella cosa è un soundfont: un file pieno di strumenti registrati — un pianoforte, una tromba, un rullante — con le note e i punti di loop segnati, così il motore può costruirci qualsiasi nota di qualsiasi strumento.

Singe non ne include uno. Un buon soundfont pesa decine di megabyte, e sarebbero decine di megabyte portate in giro da ogni copia del motore per un formato che la maggior parte dei giochi non tocca mai. Quindi ne indichi uno con --soundfont, o ne metti uno in Singe/soundfont.sf2 così che un gioco impacchettato si porti il suo, o lasci che Singe trovi quello installato dalla tua distribuzione Linux. Se non c’è un soundfont da nessuna parte, caricare un .mid fallisce e lo dice.

Ecco perché lo stesso file MIDI suona diverso su due macchine, e perché suonava così male sui computer degli anni novanta. Il file è un elenco di note. Quello che senti è il soundfont che si è trovato a suonarle: uno buono è una stanza piena di strumenti, uno scadente è una stanza piena di giocattoli, e le note sono identiche in entrambi. Se nel tuo gioco va un file MIDI, distribuisci il soundfont insieme. Altrimenti non hai scelto come suona la tua musica; l’hai lasciato a qualunque cosa sia installata sulla macchina del giocatore.

Il MIDI come cavo

Ora la seconda cosa, che è quella interessante.

Il MIDI è anche un cavo, e i messaggi che ci viaggiano sopra. Collega una tastiera musicale al tuo computer e ogni tasto che premi manda un messaggio: note on, canale 1, tasto 60, velocity 90. Gira una manopola su una superficie di controllo e manda il controller 7 sul canale 1 adesso vale 40. Questi messaggi esistono che ci sia o no qualcosa che suona musica. Sono un altro dispositivo di input, come un joystick con ottantotto pulsanti che sanno quanto forte li colpisci.

E funziona anche al contrario. Il tuo gioco può mandare fuori quei messaggi, a un sintetizzatore, a un modulo sonoro, a un controller per luci da palco o a qualsiasi altra cosa sul cavo.

Le porte sono numerate da zero, e Singe non apre niente finché non glielo chiedi — un gioco che non nomina mai il MIDI non paga mai per il MIDI. Possono essere aperte una porta di ingresso e una di uscita alla volta. Fai l’inventario della macchina così:

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

Su una macchina senza nessun MIDI i conteggi sono zero, le chiamate di apertura rispondono false e niente fallisce. Questo conta: vuol dire che puoi scrivere questo codice in un vero gioco e distribuirlo, e i novantanove giocatori su cento senza una tastiera MIDI non sapranno mai che c’è. I nomi servono per una schermata delle impostazioni che lasci scegliere al giocatore quale porta, perché la porta zero di rado è quella che vuole. midiRescan cerca di nuovo qualcosa che è stato collegato mentre il gioco è in esecuzione.

Ascoltare

Ogni messaggio che arriva va a una callback, così come ogni pressione di un tasto 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 maggior parte dei messaggi MIDI è lunga tre byte, e i tre numeri che ricevi sono quei byte esattamente come li ha mandati il dispositivo. Un messaggio con meno byte ti passa uno 0 al posto di ognuno che non ha.

status dice di che tipo di messaggio si tratta e da quale canale è arrivato, mescolati insieme: il tipo sono i quattro bit alti e il canale i quattro bassi. 0x90 è note on, e una nota sul canale 1 arriva come 0x90 mentre la stessa nota sul canale 5 arriva come 0x94. status & 0xF0 tiene la metà alta e butta via il canale, che è quello che vuoi a meno che non ti importi da quale canale veniva. (& è l’and bit a bit di Lua, e 0x90 è un numero scritto in esadecimale — base sedici — perché è così che li scrive ogni documento MIDI del mondo.)

data1 e data2 sono gli altri due byte, e che cosa vogliono dire dipende dal tipo. Per un note on sono il tasto e la velocity: il tasto 60 è il Do centrale, e la velocity è quanto forte è stato colpito, da 1 a 127.

Il controllo data2 == 0 non è pignoleria. Un note on con velocity zero vuol dire note off: è il modo in cui quasi ogni tastiera mai costruita dice «ho lasciato andare», e se non lo filtri il tuo gioco scatterà due volte per ogni tasto.

bytes è l’intero messaggio come stringa, ed è così che leggi un messaggio più lungo di tre byte.

Suonare

Mandare è più facile che ricevere.

midiNoteOn(1, 60, 100)
midiNoteOff(1, 60)

Do centrale sul canale 1, colpito a cento, e poi rilasciato. Qui i canali vanno da 1 a 16 come li conta una persona, non da 0 a 15 come fa il cavo: è Singe che è gentile con te.

Ogni midiNoteOn ha bisogno di un midiNoteOff. Una nota che non viene mai rilasciata suona finché qualcosa non la ferma, e il classico primo bug MIDI è un gioco che va in crash o si chiude con tre note premute e lascia un accordo sospeso nella stanza. Quindi abbinale, e abbinale con un timer invece che 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 fa un lavoro vero. timerAfter esegue la sua funzione quattro decimi di secondo dopo, e a quel punto target potrebbe essere passato a un’altra nota; copiarlo in una variabile locale vuol dire che il timer rilascia la nota che è stata davvero premuta. Copia tutto ciò che servirà più tardi a un timer.

Le altre chiamate di invio fanno il resto di quello che è il MIDI: midiProgramChange sceglie quale strumento suona un canale, midiControlChange muove un controller (il volume è 7, il pan è 10, il pedale di sustain è 64), midiPitchBend piega l’intonazione di un canale, e midiSend manda qualsiasi messaggio come byte grezzi per le cose che le chiamate con un nome non coprono.

Un motivo per interessarsene

Tutto questo è meccanica. Ecco a che cosa serve.

Metti insieme le due metà e il gioco chiede una nota, il giocatore la suona su un vero strumento, e il gioco sa se l’ha azzeccata:

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

Undici righe, e hai lo scheletro di un gioco per imparare la musica. Aggiungi un orologio e hai un gioco ritmico che dà punti a chi suona davvero invece che a quattro pulsanti di plastica. Aggiungi data2 alla verifica e al gioco importa quanto forte colpisci la nota. Confronta il momento in cui è arrivata la nota con quello in cui era attesa, e stai valutando la tempistica al millisecondo.

E siccome il MIDI esce oltre che entrare, un cabinato può fare cose che nient’altro può fare. Un vero strumento collegato alla macchina. Un modulo sonoro esterno che suona la partitura, così il motivo ha una profondità che nessun banco di campioni gli dà. Luci da palco sul cabinato che lampeggiano a tempo perché il gioco ha mandato loro il tempo. Se sei il tipo di persona che costruisce cabinati, questa è la chiamata che permette al cabinato di essere una cosa e non una scatola attorno a un computer.

Lo script finito è learn/27-midi.singe: i comandi della musica, l’elenco delle porte e il gioco a indovinare, in un centinaio di righe. La barra spaziatrice manda fuori la nota, Alt sinistro mette in pausa la musica, Maiusc sinistro la sfuma, e le frecce su e giù cambiano il volume. Eseguilo senza hardware MIDI e la metà della musica funziona, mentre la metà MIDI dice none due volte, che è proprio come dovrebbe comportarsi sulla macchina di un giocatore.

Fare pulizia

function onShutdown()
    midiCloseInput()
    midiCloseOutput()
    musicUnload(theme)
end

onShutdown viene chiamata una volta quando il gioco finisce, ed è il punto in cui uno script restituisce ciò che ha preso. Chiudere una porta che non è aperta non fa niente, quindi non c’è niente da controllare prima.

Prova tu

  1. Fallo ripetere quattro volte invece che all’infinito. Cambia musicPlay(theme, -1) in musicPlay(theme, 3) e conta. Il numero è quante volte si ripete, non quante volte suona.

  2. Sfuma più a lungo. Cambia la dissolvenza del pulsante che ferma la musica in musicStop(theme, 4000) e ascolta la differenza che fanno quattro secondi. Poi prova musicStop(theme, 100).

  3. Mostra il canale. In onMidiMessage, ricava il canale con (status & 0x0F) + 1 e stampalo. Suona la tua tastiera e guarda su quale canale è — poi trova le sue impostazioni e cambia quel canale, per dimostrare a te stesso che il numero è vero.

  4. Dai punti alla velocity. Dai un punto per la nota giusta, e tre punti se data2 è sopra cento, così il gioco premia chi suona con convinzione.

  5. Suona la risposta. Quando il giocatore azzecca una nota, fai suonare al gioco un piccolo accordo di risposta con tre chiamate a midiNoteOn a un paio di note di distanza e tre timer per rilasciarle. Per questo ti serve una vera porta di uscita o un sintetizzatore software, e su Linux va bene qualsiasi programma che si registri con ALSA.

Rompilo apposta

Le due scale del volume sono facili da confondere, e Singe preferisce fermarsi piuttosto che suonare la tua musica a un livello che non intendevi. Aggiungi una riga sotto musicPlay(theme, -1), usando il numero che sarebbe il volume massimo di un effetto sonoro se lo raddoppiassi a mente e sbagliassi il conto:

musicSetVolume(200)

Singe si ferma prima che il gioco parta, indicando la riga del tuo file in cui si trova quella chiamata:

107:musicSetVolume:  Invalid music volume value:  200

La riga, la chiamata che ha protestato e la lamentela, che qui ti ripete il numero, così non c’è discussione su che cosa è arrivato. La musica va da 0 a 128. Gli effetti sonori vanno da 0 a 63. Quando una chiamata del volume ferma il tuo gioco, la domanda da farti è a quale delle due famiglie stai parlando.

Cosa hai imparato

  • In Singe la musica e gli effetti sonori sono separati: volumi propri, nessun limite di canali per la musica e una pausa che segue la pausa del gioco.

  • Un file musicale viene decodificato in memoria fin dall’inizio, quindi un brano lungo costa memoria e va scaricato quando lasci il livello.

  • musicPlay(track, -1) si ripete all’infinito; un numero positivo è quante volte si ripete.

  • Il volume della musica va da 0 a 128 e quello degli effetti da 0 a 63, e la differenza è per compatibilità con Hypseus, non un errore.

  • musicStop(track, milliseconds) sfuma in uscita, e una sfumatura è la rifinitura più economica che ci sia. Non c’è la dissolvenza incrociata, perché un unico guadagno copre tutta la musica.

  • Singe mostra il video seguendo l’orologio dell’audio, e singeSetAudioDelay corregge il ritardo di qualunque cosa da cui esca il suono.

  • Un file MIDI contiene note, non suono, e ha bisogno di un soundfont per farsi sentire. Singe non ne include nessuno, quindi distribuisci il tuo, o la tua musica sarà qualunque cosa la macchina del giocatore si trovi ad avere.

  • Le porte MIDI sono tutt’altra cosa: messaggi dal vivo in entrata e in uscita, su un cavo, che non hanno niente a che fare con i file MIDI.

  • onMidiMessage ti passa i byte grezzi. I quattro bit alti di status sono il tipo, i quattro bassi sono il canale, e un note on con velocity zero vuol dire note off.

  • Ogni midiNoteOn ha bisogno di un midiNoteOff, e un timer è il modo per abbinarli.

  • Su una macchina senza MIDI ogni chiamata risponde false o zero e niente fallisce, quindi il supporto MIDI si può distribuire tranquillamente.

La prossima volta

Il tuo gioco ha la musica, e un punteggio che una tastiera MIDI può far salire. La ventottesima lezione porta quel punteggio fuori dalla macchina: account, classifiche dei punteggi record che possono vedere anche gli altri, e il catalogo che fa conoscere il tuo gioco al mondo.

Lezione 28: Online

La lezione finita

Nella dodicesima lezione hai salvato un punteggio record. La mattina dopo è ancora lì, che è quasi tutto quello a cui serve un punteggio record, ma è un punteggio record su una sola macchina. Questa lezione mette un punteggio su una classifica che possono vedere anche gli altri.

È anche la lezione sul fallimento. Tutto il resto che hai scritto fallisce per motivi che puoi trovare: manca un file, un numero è sbagliato, il nome di una funzione è scritto male. La rete fallisce per motivi che nessuno nella stanza può vedere. Qualcuno ha staccato un cavo in un edificio in cui non sei mai stato, e il tuo gioco deve continuare a girare. Quasi tutto quello che segue parla di questo.

Che cos’è il servizio

Singe può parlare con un servizio master, un server che custodisce tre cose:

  • un account, che appartiene alla macchina e non a un singolo gioco;

  • un catalogo di giochi da scaricare e aggiornare;

  • classifiche dei punteggi record, una o più per gioco.

Il servizio predefinito è master.singeengine.com, e un gestore che ha un servizio suo indirizza la macchina altrove. La sezione del manuale sul servizio online descrive entrambe le parti.

Ora la parte che tutti saltano. Il servizio non è multigiocatore: non c’è modo che due giocatori stiano nella stessa partita. Non è un cloud per i salvataggi; il salvataggio della dodicesima lezione resta sulla macchina. Non è una protezione dalla copia, e niente al suo interno impedisce a qualcuno di giocare al tuo gioco. Non è obbligatorio: un gioco che non accede mai funziona esattamente come ha sempre fatto, ed è l’unica impostazione predefinita sensata per qualcosa che ha bisogno di una connessione funzionante.

Quindi la classifica è un extra. Tieni il punteggio record locale della dodicesima lezione, continua a mostrarlo, e lascia che la classifica online sia la cosa che a volte c’è.

L’accesso si fa una volta, e non nel tuo gioco

L’account appartiene alla macchina. Lo si crea e ci si accede dal menu incluso, dietro il tasto assegnato a INPUT_SERVICE, nello strumento chiamato Online Account. Il token che ottiene viene scritto in master.dat nella radice dei dati, un livello sopra la cartella dei dati di ogni gioco, così ogni gioco sulla macchina invia i punteggi con lo stesso accesso.

Il tuo gioco non chiede mai un indirizzo email e non chiede mai una password. Non c’è nessuna funzione per farlo, ed è voluto: un giocatore che scrive una password in un gioco che ha scaricato non ha modo di sapere dove va a finire.

Quello con cui un giocatore compare su una classifica è un nickname: da tre a venti caratteri tra lettere, cifre, trattini e trattini bassi, che iniziano e finiscono con una lettera o una cifra. Niente spazi, niente punti e niente @, così un nickname non può nemmeno sembrare un indirizzo email. È tenuto separato dall’account, è l’unica cosa di un giocatore che gli altri giocatori vedono, e si sceglie una volta sola — un gestore può cambiarne uno, un giocatore no, perché una classifica i cui nomi continuano a cambiare non è davvero la storia di nessuno. Finché non è stato scelto un nickname i punteggi vengono rifiutati, dato che un punteggio senza il nome di nessuno sopra non sta su una classifica in nessun senso utile.

Lo strumento Online Account mostra il nome con cui questa macchina invia i punteggi, e il tuo gioco lo legge con scorePlayerName(), che risponde nil quando non ce n’è uno. Meglio saperlo prima che ti lasci perplesso: un punteggio inviato senza un nickname dietro viene rifiutato dal servizio, non da scoreSubmit, quindi al tuo gioco non viene detto niente. Se scorePlayerName() è nil, dillo sullo schermo finché c’è ancora qualcuno lì a leggerlo.

Il tuo gioco ha bisogno di un id

Una classifica deve essere conservata sotto qualcosa. Quel qualcosa è GAME_ID nella voce del tuo gioco in games.dat, il file che hai creato nella tredicesima lezione:

GAME_ID = "6f1e7b62-0a4e-4d9c-9b2f-1c7a5e3d8a10"

È un UUID, esattamente in quella forma: otto cifre esadecimali, tre gruppi di quattro, poi dodici, separati da trattini. Generane uno come preferisci e incollalo; non importa quale ti capita, solo che non cambi mai più. La voce del Riferimento per singeGetGameId spiega perché non viene accettato nient’altro.

singeGetGameId() lo restituisce, o nil quando la voce non ne ha uno. Un gioco senza id si può giocare ma non può finire in classifica, e chiedere prima è il modo per evitare di offrire una classifica che non potrà mai funzionare:

if singeGetGameId() then
    -- showLeaderboardButton è una tua funzione, non una di Singe.
    showLeaderboardButton()
end

Le sei chiamate

Tutto quello che un gioco fa con il servizio sono sei funzioni, e vengono da Singe/Framework.singe, quindi qui il dofile in cima al tuo script non è facoltativo:

dofile("Singe/Framework.singe")

scoreBegin() dice che sta cominciando una partita. scoreSubmit(value) mette in coda un punteggio. scoreBoard(onDone) recupera la classifica. scorePlayerName() è il nickname. scoreWaiting() è quanti punteggi non sono ancora partiti. E scoreUpdate() deve girare una volta per fotogramma, da onOverlayUpdate, altrimenti nessuna delle altre arriva mai in fondo.

Quest’ultima è tutto il trucco di questa lezione, quindi la diciamo due volte. Niente di tutto questo parla con la rete quando lo chiami. scoreSubmit scrive in una coda e ritorna subito. scoreBoard si ricorda che cosa vuoi e ritorna subito. Il lavoro vero avviene un pezzetto alla volta dentro scoreUpdate, tra un fotogramma e l’altro, ed è per questo che il tuo gioco non va mai a scatti quando la linea è lenta. Togli scoreUpdate e non si rompe niente, non c’è nessun errore, e non succede mai niente.

function onOverlayUpdate()
    scoreUpdate()
    overlayClear()
    return OVERLAY_UPDATED
end

Inviare un punteggio

Alla fine di una partita:

if scoreSubmit(score) then
    fetchBoard()
else
    saying = "Kept here only:  " .. whyNotPosted()
end

scoreSubmit risponde false quando non c’è un account o il gioco non ha un GAME_ID, e true quando il punteggio è entrato nella coda. Nota che cosa non fa il ramo else: non butta via il punteggio, non si profonde in scuse e non impedisce al giocatore di cominciare un’altra partita. Dice una sola riga breve, perché il giocatore non ha sbagliato niente e da qui non può rimediare.

La coda è il motivo per cui tutto questo è sicuro. Un punteggio in coda viene scritto su disco, quindi sopravvive allo spegnimento della macchina, e viene consegnato al servizio la volta dopo che c’è una connessione — un’ora dopo, o martedì prossimo. Ecco perché un cabinato in una sala con un wifi scadente finisce comunque sulla classifica.

Sii onesto con te stesso sul limite di quella promessa: la coda conserva i punteggi per una macchina che ha un account. Se nessuno ha mai effettuato l’accesso, scoreSubmit risponde false e il punteggio non viene conservato per dopo, perché non c’è nessuno per cui conservarlo. scoreWaiting() ti dice quanti sono ancora in coda, e mostrare quel numero da qualche parte è una gentilezza: è la differenza tra «il servizio è rotto» e «tre dei tuoi punteggi aspettano che torni internet».

scoreBegin() merita un paragrafo tutto suo. Chiamala quando comincia una partita, e il servizio annota il momento con il proprio orologio. Il punteggio che segue porta con sé quanto è durata la partita, misurato sul server, ed è l’unico numero di un invio che non è passato dalla macchina del giocatore. Niente viene rifiutato in base a quello: viene mostrato a chi gestisce il servizio, accanto al punteggio, e decide una persona. Una macchina che era offline quando è cominciata la partita non registra nessun tempo, il che è onesto, non rotto.

E visto che siamo onesti: un punteggio inviato è una dichiarazione. Il gioco gira sul computer del giocatore, quindi niente di ciò che può fare il client lo rende qualcosa di più, e una chiave segreta inclusa nel tuo gioco sembrerebbe soltanto sicurezza. Il servizio registra chi ha dichiarato che cosa, limita la velocità con cui possono arrivare i punteggi e segnala quelli assurdi perché li guardi una persona. Progetta la tua classifica sapendolo.

Rileggere la classifica

scoreBoard è la prima funzione di questo libro che prende una funzione come argomento.

scoreBoard(function(ok, result)
    ...
end)

Hai scritto delle funzioni nella quinta lezione e hai dato loro un nome. Questa non ha nome: è scritta dove viene usata, passata direttamente a scoreBoard e chiamata più tardi — magari secondi dopo — quando arriva la risposta. È di nuovo una callback, la stessa idea di onOverlayUpdate, solo che stavolta scegli tu chi la chiama.

ok è true o false. Quando è false, result è una breve stringa che dice perché. Quando è true, result è una tabella con due parti:

  • result.top, un elenco di righe, ognuna con un name e un value;

  • result.standing, il value di questo giocatore, il suo rank e il numero di players sulla classifica — che può mancare, se questo giocatore non ci ha niente sopra.

Tra la chiamata e la callback il tuo gioco continua a girare e a disegnare. Quell’intervallo è reale e il giocatore lo vede, quindi mettici qualcosa. Lo script qui sotto imposta una riga di testo a "Asking the service…​" prima della chiamata, e la callback sostituisce quella riga con la classifica o con il motivo per cui non c’è. Una schermata che non dice niente per quattro secondi sembra rotta; una schermata che dice che cosa sta facendo è solo lenta.

Il catalogo

La terza cosa che fa il servizio è elencare giochi. Lo strumento Get Games del menu mostra tutto quello che il servizio offre, segna ciò che è già installato su questa macchina, e lo scarica, lo aggiorna o lo rimuove. Un download viene controllato rispetto all’impronta pubblicata dal catalogo prima di sostituire qualsiasi cosa, così un trasferimento arrivato danneggiato fallisce invece di installare un gioco che non partirà. Un gioco che il servizio ha ritirato continua a funzionare e appare come installato ma non più offerto: smette soltanto di ricevere aggiornamenti, perché chi ha un gioco ce l’ha.

Il tuo gioco non chiama niente di tutto questo, e non dovrebbe. Il catalogo ti riguarda come autore di un gioco più che come chi scrive uno script: è dove va il tuo file .game quando lo pubblichi, che è l’argomento della trentesima lezione, ed è un altro motivo per cui il tuo games.dat ha bisogno di un GAME_ID che non cambi mai. Se un giorno vuoi davvero l’elenco da dentro uno script, Singe/Master.singe è il modulo che sta sotto tutto questo, e vale la pena leggerlo una volta.

Che cosa sa il servizio di un giocatore

Se distribuisci un gioco che invia punteggi, stai consegnando i dati di qualcun altro a un server, e questa è una tua responsabilità anche se il server non l’hai scritto tu. Quindi dillo chiaramente, nella schermata di informazioni o nel file leggimi del tuo gioco:

  • Il servizio conserva un indirizzo email e una password per l’account. L’indirizzo serve a recuperare una password dimenticata e a nient’altro. Non viene mai mostrato agli altri giocatori e non si può cambiare in seguito.

  • Il nickname è quello che compare sulle classifiche. È tenuto separato dall’account apposta, così che gli altri giocatori non vedano mai un indirizzo, e viene controllato rispetto a un elenco di nomi che nessuno dovrebbe rivendicare e di parole che non stanno bene su uno schermo in una sala pubblica.

  • Un punteggio porta con sé il suo valore, la classifica su cui sta, l’ora registrata dal servizio e il nickname. Tutto qui.

  • Il catalogo sa quali giochi sono installati sulla macchina, e in quale versione, perché è così che ti offre un aggiornamento.

Quello che nessuna di queste cose fa è seguire un giocatore da un gioco all’altro, vendere qualcosa o frugare nella macchina in cerca di qualcosa che non hai mandato tu. Il tuo gioco non dovrebbe allungare l’elenco. Se aggiungi informazioni extra a un punteggio — scoreSubmit prende un terzo argomento facoltativo apposta — fa' che riguardino il gioco.

Lo script

Un test di reazione: aspetta la parola, premi il pulsante, il punteggio è quello che resta di mille. È un piccolo gioco, e tutto il resto è la parte online.

Crea una cartella chiamata reaction e metti questo in reaction.singe, al suo interno. Dai alla cartella un games.dat come quello della tredicesima lezione, che indichi reaction/reaction.singe, con nella sua voce la riga GAME_ID di prima.

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

Eseguilo con Singe -R reaction. Su una macchina che non ha mai effettuato l’accesso, il gioco gira, tiene il tuo punteggio migliore e dice Kept here only: this machine is not signed in. Questa è l’esecuzione importante, ed è quella che avrà la maggior parte dei tuoi giocatori.

Cos’è appena successo

local top      = nil
local standing = nil

Due variabili che sono nil quasi sempre. nil vuol dire «qui non c’è niente», ed è quello che contiene una variabile prima che ci si metta dentro qualcosa. Queste contengono la classifica quando ce n’è una, e nil quando non c’è: mentre la richiesta è in viaggio, dopo un errore e prima della prima partita. Il codice che disegna chiede if top then e non disegna niente quando non c’è niente, che è la forma di quasi ogni pezzo di codice di rete che scriverai.

    saying   = "Asking the service..."
    scoreBoard(function(ok, result)

L’ordine conta. La riga di testo viene impostata prima della chiamata, perché la chiamata ritorna subito e la callback potrebbe non partire per qualche secondo. Se imposti il testo solo dentro la callback, lo schermo mostra il messaggio della partita precedente finché non arriva la risposta, cioè esattamente il messaggio sbagliato nel momento esattamente sbagliato.

        if not ok then
            saying = "No board:  " .. tostring(result)
            return
        end

Il fallimento viene per primo, ed è breve. tostring trasforma in testo qualunque cosa sia tornata, così che unirla con .. non possa fallire; result è una stringa quando ok è falso, ma una riga di codice di disegno che si fida del tipo di qualcosa ricevuto da un server è una riga che aspetta solo di andare in crash. Il giocatore vede una frase, e il gioco va avanti.

    if scoreSubmit(score) then
        fetchBoard()
    else
        saying = "Kept here only:  " .. whyNotPosted()
    end

scoreSubmit che risponde false non è un errore. È un fatto che riguarda questa macchina, e vale la pena distinguere i due fatti che può voler dire, che è quello che fa whyNotPosted: un GAME_ID mancante è un errore tuo, e una macchina che non ha effettuato l’accesso non è colpa di nessuno. Il punteggio migliore locale era già stato salvato, due righe sopra, prima di tentare tutto questo. Prima salva, poi invia, sempre.

    overlayPrint(2, 6, "Waiting to send:  " .. scoreWaiting())

La coda, sullo schermo. Su una macchina con una connessione segna 0 per sempre e nessuno ci fa caso. Su una macchina senza, sale, e il giocatore sa che il gioco sta conservando i suoi punteggi invece di mangiarseli.

function onOverlayUpdate()
    scoreUpdate()

Prima riga del fotogramma, prima di qualsiasi altra cosa. Mettila in un punto in cui un if non possa saltarla, perché uno scoreUpdate che gira solo nella schermata di game over è una coda che si svuota solo nella schermata di game over.

Prova tu

  1. Stacca la spina. Scollega la macchina dalla rete, gioca qualche partita e guarda il numero di Waiting to send. Ricollegala e guardalo scendere senza che tu faccia niente.

  2. Cancella l’id. Togli GAME_ID dal tuo games.dat ed eseguilo di nuovo. Il messaggio cambia. Rimettilo.

  3. Mostra più classifica. Il ciclo si ferma a cinque righe. L’overlay è alto diciotto righe di caratteri per impostazione predefinita, quindi calcola quante ne puoi far stare davvero, e sposta la riga di standing se serve.

  4. Dai un nome alla classifica. scoreSubmit(score, "reaction") e scoreBoard(onDone, "reaction") usano una classifica con quel nome invece di quella che porta il nome del tuo script. Invia a due classifiche dallo stesso gioco — per esempio, una per il punteggio e una per la singola reazione più rapida — e fai che il pulsante 2 cambi quale viene mostrata.

  5. Rendi visibile l’attesa. Tra la chiamata a scoreBoard e il momento in cui parte la callback, disegna un puntino che si muove. Poi scopri quanto dura davvero sulla tua connessione, e se valeva la pena disegnarlo.

Rompilo apposta

Togli la prima riga di onOverlayUpdate, così la chiamata a scoreUpdate() sparisce, e gioca una partita.

Non succede niente. Nessun errore, nessun messaggio, nessuna classifica, e il numero di Waiting to send sale e resta su per sempre. Il gioco funziona perfettamente.

Questo è il peggior tipo di bug, e vale la pena incontrarlo una volta apposta: un passo mancante che produce silenzio invece di una lamentela. Non c’è nessun numero di riga da guardare, perché non è andato storto niente — hai chiesto del lavoro e poi non gli hai mai dato occasione di succedere. Quando qualcosa in Singe che prende una callback non ti richiama mai, la prima domanda è sempre se la cosa che lo fa andare avanti gira a ogni fotogramma.

L’altro che incontrerai è più rumoroso. Rimetti scoreUpdate(), cancella la riga del dofile in cima ed eseguilo:

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 riga 89 è lo scoreUpdate() che hai rimesso, una riga più in alto ora che il dofile non c’è più. Leggi la prima riga come sempre: la funzione che il motore stava chiamando, il file, la riga e la lamentela. Di nuovo nil — il nome scoreUpdate non contiene niente, perché il file che lo definisce non è mai stato caricato. Tutte e sei queste chiamate vivono in Singe/Framework.singe.

Cosa hai imparato

  • Il servizio custodisce un account, un catalogo e le classifiche dei punteggi record. Non è multigiocatore, non è un cloud per i salvataggi e non è mai obbligatorio.

  • L’account appartiene alla macchina e l’accesso si fa dagli strumenti di servizio del menu. Un gioco non chiede mai una password.

  • Una classifica è conservata sotto GAME_ID in games.dat, un UUID che non deve cambiare mai. singeGetGameId() lo legge.

  • scoreSubmit mette in coda un punteggio su disco e ritorna subito; la coda sopravvive allo spegnimento della macchina.

  • scoreUpdate() deve girare a ogni fotogramma, altrimenti niente di quello che fa il servizio arriva mai in fondo.

  • scoreBoard consegna la sua risposta a una funzione che scrivi tu, che gira più tardi. Nel frattempo disegna qualcosa.

  • Ogni chiamata di rete può fallire, e fallire non è un errore. Di' una riga breve e continua a giocare.

  • Un punteggio inviato è una dichiarazione, e il servizio lo tratta come tale.

  • Tieni il punteggio record locale. È quello che funziona sempre.

La prossima volta

Un punteggio record è un numero solo, e il salvataggio della dodicesima lezione è il posto giusto per lui. La ventinovesima lezione è per tutto il resto che un gioco vuole conservare: ogni round giocato da chiunque, i livelli che distribuisci, e le domande che vuoi fare a entrambi. Prende questo test di reazione e gli dà un database.

Lezione 29: Conservare i dati

La lezione finita

La dodicesima lezione ha salvato un punteggio record: un numero, sotto un nome, ancora lì la mattina dopo. Per un punteggio record è esattamente la cosa giusta, ed è sbagliata per quasi tutto il resto che un gioco vuole conservare. L’elenco di tutte le partite che qualcuno abbia mai giocato. Il tempo migliore su ognuno di venti tracciati. Quaranta livelli che qualcuno ha progettato in un foglio di calcolo. La domanda «qual è il mio record nello stage difficile?», a cui un mucchio di numeri salvati non sa rispondere, a meno che la risposta non la scriva tu a mano.

È a questo che serve un database, e Singe ne ha uno incorporato. Questa lezione prende il test di reazione della ventottesima lezione, gli dà degli stage che vengono distribuiti con il gioco, e gli fa conservare ogni prova giocata da chiunque e rispondere a domande su di esse.

Che cos’è un database

Un database è un file di tabelle. Una tabella è fatta di righe e colonne, come un foglio di calcolo con i nomi delle colonne decisi in anticipo: una tabella di prove potrebbe avere uno stage, un punteggio e un momento per ogni riga. Le righe ce le metti tu, e per tirarle fuori fai delle domande, e le domande si scrivono in SQL, un piccolo linguaggio che fa questo lavoro da prima della maggior parte dei linguaggi di programmazione di cui hai sentito parlare.

Il database che Singe si porta dietro è SQLite. Non è un server da installare né un servizio a cui iscriversi. È una libreria, il database è un normale file, e lo stesso SQLite si trova nel tuo telefono, nel tuo browser e probabilmente nella tua auto. Per seguire questa lezione non devi conoscere SQL: ogni istruzione viene spiegata man mano che passa, e le tre che userai di più — CREATE TABLE, INSERT e SELECT — ci sono tutte.

Aprirne uno

local sqlite3 = require("sqlite3")

local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

require("sqlite3") carica una libreria che viene con Singe e te la restituisce come tabella, quindi tutto ciò che SQLite sa fare è sqlite3. qualcosa. sqlite3.open apre un file di database e lo crea se non c’è ancora, quindi la prima volta che avvii il gioco ne crea uno vuoto, e ogni volta successiva lo ritrova.

Il file va in singeGetDataPath(), per lo stesso motivo per cui ci va il salvataggio della dodicesima lezione: la cartella del gioco può stare su un disco, su una cartella condivisa in rete o impacchettata in un unico file, e in nessuno di questi si può scrivere. Tutto ciò che un gioco scrive va nella sua cartella dei dati.

Creare una tabella

Un database vuoto non ha tabelle. Ne crei una descrivendola:

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 esegue SQL che non restituisce niente. Le doppie parentesi quadre sono la stringa lunga di Lua: tutto quello che c’è in mezzo, a capo compresi, è un’unica stringa, ed è così che si tiene leggibile l’SQL.

CREATE TABLE dà un nome alla tabella e alle sue colonne, ognuna con un tipo: TEXT per le parole e INTEGER per i numeri interi. NOT NULL vuol dire che ogni riga deve avere un valore lì. INTEGER PRIMARY KEY è speciale: SQLite lo riempie da solo, contando in avanti, così ogni riga riceve il suo numero senza che tu ci debba pensare.

IF NOT EXISTS è ciò che rende sicuro eseguirlo ogni volta che il gioco parte. La prima volta crea la tabella. Tutte le volte successive la tabella c’è già e la riga non fa niente. Senza quelle tre parole, la seconda volta che avvii il gioco si fermerebbe con un errore che dice che la tabella esiste già.

Inserire una riga

Potresti costruire l’SQL per una nuova riga incollando insieme delle stringhe:

runs:exec("INSERT INTO runs (stage, score, at) VALUES ('" .. stage .. "', " .. score .. ", " .. os.time() .. ")")

Non farlo. Funziona finché un nome non contiene un apostrofo, e a quel punto l’apice chiude la stringa troppo presto e l’istruzione non ha più senso. In un gioco che lascia scrivere i giocatori va anche peggio: qualunque cosa scrivano diventa parte del tuo SQL.

Il modo giusto è scrivere l’istruzione una volta sola, con dei punti interrogativi dove vanno i valori, e consegnare i valori a parte:

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 trasforma l’SQL in un'istruzione che si può usare più e più volte. bind_values mette un valore in ogni punto interrogativo, in ordine. Qualunque cosa contenga un valore, apostrofi compresi, resta un valore e non diventa mai parte dell’SQL. step esegue l’istruzione, e reset la prepara per essere eseguita di nuovo. os.time() è Lua puro: l’ora attuale come numero di secondi, che è il modo più facile per memorizzare un «quando».

Preparare una volta e riusare l’istruzione è anche più veloce, perché SQLite capisce come eseguirla una volta sola. Per un gioco che scrive una riga al minuto non conta. Per un editor di livelli che ne scrive mille, sì.

Fare domande

Le righe tornano fuori con nrows, che esegue una SELECT e ti consegna ogni riga come una tabella con i nomi delle colonne come chiavi:

for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC LIMIT 5") do
    debugPrint(row.stage .. "  " .. row.score)
end

Leggi l’SQL da sinistra a destra. SELECT stage, score dice quali colonne vuoi. FROM runs dice da quale tabella. ORDER BY score DESC ordina le righe per punteggio, dal più alto, e LIMIT 5 si ferma dopo cinque. Questa è una tabella dei punteggi record, e non ha mai avuto bisogno di codice di ordinamento scritto da te.

Le domande possono essere più furbe di quelle che vorresti scrivere 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 raccoglie le righe in un gruppo per ogni stage, e MAX(score) e COUNT(*) vengono calcolati per ciascun gruppo: il punteggio migliore in quello stage e quante volte è stato giocato. AS top dà un nome alla risposta, ed è la chiave con cui la rileggi.

Quando una domanda ha una sola risposta, urows restituisce direttamente le colonne invece di una tabella, il che è più ordinato per un conteggio:

for count in runs:urows("SELECT COUNT(*) FROM runs") do
    played = count
end

Chiedi quando cambia

Nessuna di queste domande va messa in onOverlayUpdate. Una query è veloce, ma sessanta al secondo, per avere risposte che cambiano una volta al minuto, vuol dire che il gioco fa la stessa domanda e riceve la stessa risposta cinquantanove volte su sessanta.

Quindi il gioco chiede quando la risposta può essere cambiata — una volta all’inizio, e di nuovo ogni volta che viene registrata una prova — e tiene quello che torna indietro in normali tabelle:

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
    -- e lo stesso per le altre due domande
end

onOverlayUpdate disegna a partire da best, il che non costa niente. record chiama refresh dopo ogni nuova riga, così la tabella sullo schermo non è mai superata.

Dati che vengono distribuiti con il gioco

L’altra metà dei dati di un gioco è la parte che scrivi prima che qualcuno giochi: gli stage, i livelli, gli oggetti, le battute dei dialoghi. Anche quella può essere un database, creato con qualsiasi strumento per SQLite — il programma sqlite3 dalla riga di comando, o un programma con le finestre come DB Browser for SQLite — e messo nella cartella del gioco accanto alla sua grafica. Il kit di grafica ne ha uno, stages.db, con un nome e l’attesa più breve e più lunga per ogni stage.

Un gioco quello lo apre in modo diverso:

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 è la cartella del tuo gioco, dove si trova la grafica. sqlite3.OPEN_READONLY dice che intendi solo leggerlo, e questo conta il giorno in cui distribuisci il gioco. Quando nella prossima lezione impacchetterai il gioco in un unico file, un database aperto in sola lettura viene letto direttamente da quel file, senza estrarre niente. Uno aperto in scrittura viene copiato, una volta, nella cartella dei dati del gioco, e da quel momento in poi modifichi la copia; il file che hai distribuito non viene mai scritto.

Quindi tieni separati i due tipi. Quello che hai creato tu va nella tua cartella e si apre in sola lettura. Quello che crea il gioco va nella cartella dei dati. Qui gli stage vengono letti una volta all’inizio in una normale tabella e il database viene chiuso, perché per un elenco di quattro stage non vale la pena tenere aperto un file.

Chiudere tutto

Le istruzioni e i database tengono occupata la memoria e aperto un file finché non dici che hai finito, e il posto ordinato per dirlo è onShutdown:

function onShutdown()
    addRun:finalize()
    runs:close()
end

finalize è il close di un’istruzione. Un database non si chiude finché è ancora in giro un’istruzione creata da lui, quindi le istruzioni vanno per prime.

Lo script completo

Crea una cartella chiamata runs, copiaci dentro la cartella art del libro per avere stages.db, e metti questo in runs.singe:

dofile("Singe/Framework.singe")

local sqlite3 = require("sqlite3")

local PERFECT = 1000

-- Quello che viene distribuito con il gioco:  gli stage, letti una volta e chiusi.
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()

-- Quello che scrive il gioco:  ogni prova giocata da chiunque, tenuta nella cartella dei dati.
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


-- Le domande, fatte quando si aggiunge una prova invece che a ogni fotogramma.
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()

Avvialo con Singe -R runs. Il pulsante 1 fa partire una partita e la ferma, come nella ventottesima lezione, e il pulsante 2 tra una partita e l’altra passa allo stage successivo. Fanne qualcuna su ognuno. Poi esci e avvialo di nuovo: ogni prova è ancora lì, le cinque migliori a sinistra e il record di ogni stage a destra.

Cos’è appena successo

local runs = sqlite3.open(singeGetDataPath() .. "runs.db")

In gioco ci sono due file, e non sono uguali. art/stages.db è tuo: l’hai scritto tu, viene distribuito con il gioco, e il gioco lo legge soltanto. runs.db è del gioco: non esisteva finché il primo avvio non l’ha creato, vive nella cartella dei dati, e nessuno lo distribuisce.

    if state == "waiting" then
        state = "result"
        score = 0
        record(stages[stageAt].name, score)

Un pulsante premuto troppo presto registra comunque una prova, con zero punti. Il database è il registro di quello che è successo, e una falsa partenza è successa. Se mostrare o no quelle righe è una domanda per la SELECT, non qualcosa da nascondere non scrivendole mai.

    for row in runs:nrows("SELECT stage, score FROM runs ORDER BY score DESC, id LIMIT 5") do

ORDER BY score DESC, id ordina per punteggio e, dove due punteggi sono uguali, per id — l’ordine in cui sono state giocate. Senza la seconda chiave, due punteggi uguali tornano nell’ordine che fa più comodo a SQLite, che può cambiare da un avvio all’altro. Una tabella che si rimescola da sola senza un motivo visibile sembra rotta anche quando non lo è.

Prova tu

  1. Mostra la data. os.date("%Y-%m-%d", row.at) trasforma di nuovo un’ora memorizzata in qualcosa che una persona può leggere. Aggiungi la data a ognuna delle prove migliori.

  2. Ignora le false partenze. Aggiungi WHERE score > 0 alla domanda delle prove migliori, tra FROM runs e ORDER BY. Poi conta le false partenze in ogni stage con una domanda tutta tua.

  3. Aggiungi uno stage. Apri stages.db in uno strumento per SQLite, aggiungi una riga e avvia il gioco. Nello script non cambia niente. È proprio questo il senso di tenere i dati fuori dallo script.

  4. Azzera lo storico. runs:exec("DELETE FROM runs") svuota la tabella. Mettilo su un pulsante, chiama refresh subito dopo, e guarda tutto tornare a zero. È il «reset dei punteggi record» di un menu di servizio.

  5. Scrivi mille righe. Ripeti record mille volte in un ciclo e misura il tempo con singeGetTicks. Poi metti runs:exec("BEGIN") prima del ciclo e runs:exec("COMMIT") dopo, e misuralo di nuovo. Una transazione fa di molte scritture una sola, e la differenza è abbastanza grande da valere la pena di ricordarsela.

Rompilo apposta

Togli addRun:reset() da record e gioca tre partite su tre stage diversi.

Nessun errore. Il gioco funziona perfettamente. Ma la tabella a destra dice che hai giocato tre volte il primo stage, e le prove migliori sono tre copie del tuo primo punteggio. bind_values non poteva mettere nuovi valori in un’istruzione già eseguita e non azzerata, quindi ha rinunciato — in silenzio, restituendo un numero che non stavi controllando — e step ha eseguito di nuovo l’istruzione con i valori che aveva già.

Questo è il bug che conta in questa lezione, perché non sembra un bug. Una query che fallisce fa rumore. Una scrittura che scrive la cosa sbagliata è silenziosa, e la scopri una settimana dopo nei dati. Quando le righe di un database non sono quelle che ti aspetti, guarda il codice che ce le ha messe prima del codice che le legge.

Rimetti il reset e rompilo nel modo rumoroso: cambia score in scroe nella prima SELECT di 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 legge i nomi delle colonne quando prepara la domanda, quindi un nome scritto male ferma subito il gioco, e il messaggio lo indica con precisione. Il traceback si legge dall’interno verso l’esterno: si è lamentata nrows, l’ha chiamata refresh alla riga 42, e lo script stesso ha chiamato refresh alla riga 132, l’ultima, mentre il gioco partiva. Ecco perché dice running script invece di nominare una funzione chiamata dal motore: non è mai arrivato fino al primo fotogramma.

Cosa hai imparato

  • Un database è un file di tabelle; una tabella è fatta di righe con colonne che hanno un nome.

  • require("sqlite3") ti dà SQLite. sqlite3.open apre un file e lo crea se manca.

  • Quello che il gioco scrive va in singeGetDataPath(). Quello che distribuisci va nella tua cartella, aperto con sqlite3.OPEN_READONLY.

  • CREATE TABLE IF NOT EXISTS si può eseguire senza rischi ogni volta che il gioco parte.

  • I valori entrano attraverso prepare, bind_values, step e reset, mai incollando stringhe dentro l’SQL.

  • nrows restituisce le righe come tabelle; urows restituisce direttamente le colonne.

  • ORDER BY, LIMIT, GROUP BY, MAX e COUNT rispondono alle domande per cui altrimenti scriveresti dei cicli.

  • Chiedi quando la risposta può cambiare, non a ogni fotogramma.

  • In onShutdown si finalizzano le istruzioni, poi si chiude il database.

La prossima volta

Il tuo gioco ora ha una cartella piena di cose: uno script, la grafica, i suoni e un database o due. La trentesima lezione trasforma quella cartella in un unico file che uno sconosciuto può copiare sulla sua macchina e giocare — e il tuo database in sola lettura va con lui, e si apre ancora esattamente come adesso.

Lezione 30: Distribuirlo

La lezione finita

Hai una cartella. Dentro ci sono uno script, qualche immagine, un paio di suoni e il games.dat che hai scritto nella tredicesima lezione. Funziona, perché tutto quello che le serve è dove l’hai lasciato e tu sai dov’è.

Questa lezione trasforma quella cartella in un unico file che qualcuno che non ti ha mai conosciuto può copiare sulla sua macchina e giocare. Quasi tutto si riduce a due righe di comando. Il resto è la parte che nessuno insegna: che cosa va nel file, il lavoro di chi c’è dentro oltre al tuo, e come scoprire se funziona anche da qualche altra parte oltre che qui.

Un solo file

Un gioco Singe finito si distribuisce come un unico file .game. Per impacchettarne uno:

Singe --pack MyGame MyGame.game

Il primo nome è la cartella del tuo gioco, il secondo è il file da scrivere. Singe legge ogni file della cartella dentro un database e dice che cosa ha fatto:

>>> Packed 42 files (3819204 bytes) from MyGame into MyGame.game

Lo avvii come avvii qualsiasi altra cosa:

Singe MyGame.game

Così parte la prima voce del games.dat che contiene; --entry=2 avvia la seconda, per un file che contiene più di un gioco. Per installarlo, il giocatore copia MyGame.game accanto al programma Singe. Il menu incluso lo trova e lo elenca. Non c’è altro: niente programma di installazione, niente archivio da estrarre, niente cartella da mettere nel posto giusto.

Che cosa fa l’impacchettamento a ogni nome di file

Per essere impacchettato, nel tuo gioco non deve cambiare niente, e vale la pena sapere perché, perché è la cosa che ha più probabilità di sorprenderti.

Ogni nome che il tuo gioco usa — dofile, require, io.open, spriteLoad, soundLoad, fontLoad, videoLoad, un framefile, un controls.cfg — passa per un’unica ricerca. Per una cartella sciolta, quella ricerca è il normale file system. Per un gioco impacchettato, il nome viene cercato in tre posti e vince il primo che lo trova:

  1. una cartella sciolta con il nome del file senza estensione — MyGame/ accanto a MyGame.game;

  2. la cartella dei dati del gioco, sotto files/, che è dove è finito tutto ciò che il gioco scrive;

  3. il database stesso.

Dentro il database, i nomi vengono confrontati senza badare alle maiuscole, con l’uno o l’altro tipo di barra, e a partire dalla radice del gioco. Un nome di cartella iniziale uguale a quello del gioco viene ignorato, quindi MyGame/art/spaceship.png, art/spaceship.png e DIR .. "art/spaceship.png" trovano tutti lo stesso file.

Ne derivano due regole, e se hai seguito il libro le rispetti già tutte e due. Usa DIR per tutto quello che carichi, così un nome non dipende mai da dove è stato avviato Singe. E scrivi solo sotto singeGetDataPath(), che è dove saveSet mette già le cose — un gioco impacchettato viene aperto in sola lettura e non ci si scrive mai, quindi un gioco che salva accanto a sé funziona da sciolto e fallisce da impacchettato.

Due nomi vanno altrove di proposito. Tutto ciò che comincia con Singe/ resta sul file system vero, così dofile("Singe/Framework.singe") continua a funzionare, e lo stesso vale per la cartella dei dati. E un nome con dentro .. che cerca di arrampicarsi fuori dal gioco non porta da nessuna parte: io.open restituisce nil e un messaggio che dice che il nome esce dal gioco, e spriteLoad e i suoi parenti segnalano il file come mancante.

La cartella sciolta vince ancora

Il primo posto dell’elenco è quello che userai tutti i giorni. Una cartella con il nome del file impacchettato, che gli sta accanto, ha la meglio sulle copie impacchettate, file per file.

MyGame.game        il gioco impacchettato
MyGame/            una cartella con dentro un file modificato

Mettici dentro un solo art/spaceship.png corretto e il gioco impacchettato parte con la tua nuova immagine e con tutto il resto preso dal database. Per provare una modifica non bisogna reimpacchettare niente, e puoi tenere lì tutta la tua cartella di lavoro mentre finisci il gioco. È anche il modo in cui un giocatore ci fa una mod, e tu puoi considerarla o no una funzionalità.

Ne seguono due cose. Prova il gioco almeno una volta con quella cartella rinominata, o distribuirai un file che funziona solo sulla macchina che ha la cartella. E sappi che impacchettare non nasconde niente: --unpack è un’opzione documentata e chiunque può usarla. Impacchetta il gioco perché diventa un solo file, non perché diventa un file chiuso a chiave.

Applicare una patch a un gioco pubblicato

Qualcuno ha il tuo gioco, c’è un bug in uno script, e non vuoi mandargli di nuovo quaranta megabyte.

Singe --patch MyGame.game fixes

fixes è una cartella organizzata come il gioco — gli stessi nomi negli stessi posti — che contiene solo i file cambiati. I file che la patch non nomina restano come sono. L’intera modifica è un’unica transazione, quindi una patch interrotta lascia il gioco esattamente com’era invece che sostituito a metà.

Una patch può viaggiare come file a sé, creato con l’impacchettatore:

Singe --pack fixes MyGame-1.0.2.patch
Singe --patch MyGame.game MyGame-1.0.2.patch

Un .patch non ha bisogno di un games.dat, non si può avviare, e il menu lo ignora. Può anche portare una tabella removed(path) che nomina i file da cancellare, per la grafica che hai sostituito con qualcosa che ha un nome diverso. In un caso o nell’altro, dopo Singe controlla il gioco aggiornato nello stesso modo in cui controlla un gioco nuovo, quindi una patch non può lasciare il tuo games.dat a puntare a un file che non c’è più.

E per tirare fuori di nuovo tutto:

Singe --unpack MyGame.game MyGameUnpacked

Che cosa rifiuta l’impacchettatore

L’impacchettatore non costruisce un gioco con qualunque cosa, e ogni rifiuto riguarda qualcosa che più avanti si romperebbe. Rifiuta una cartella senza un games.dat alla radice. Rifiuta un Framework.singe, un controls.dat, qualunque cosa finisca in exe, sh, bat o cmd, e un file senza estensione il cui nome comincia con singe — in altre parole, una copia del motore o dei suoi file di supporto finita per sbaglio nella cartella del gioco. Rifiuta due file i cui nomi differiscono solo per le maiuscole, perché la ricerca non sa distinguerli. Rifiuta una voce al primo livello con lo stesso nome della cartella. E controlla il tuo games.dat prima di confermare: ogni voce ha bisogno di uno SCRIPT, e ogni SCRIPT, VIDEO, CABINET, MARQUEE e ATTRACT che nomina deve essere un file che c’è davvero. Un percorso sbagliato viene segnalato con il titolo della voce, e non viene scritto niente.

Ogni lamentela nomina il file, e ricevi l’elenco di tutte invece che solo della prima, così un solo tentativo ti dice tutto quello che c’è da correggere.

Che cosa includere e che cosa lasciare fuori

Guarda nella cartella del gioco. Una parte di quello che c’è dentro è il gioco, e un’altra parte è il modo in cui il gioco è stato fatto.

Da distribuire: lo script e tutto quello che carica, il games.dat, la grafica che mostra il menu (CABINET, MARQUEE e la clip ATTRACT), i tuoi file dei crediti e delle licenze, e un leggimi se ne hai uno.

Da lasciare fuori: i disegni da cui hai esportato la grafica, le registrazioni dei suoni che non hai usato, i tuoi appunti, gli script di prova, gli screenshot, qualunque cosa si chiami old o backup, la cartella data con dentro i tuoi salvataggi e i tuoi punteggi record, e qualunque cosa non vorresti far leggere a uno sconosciuto. Si impacchetta tutto benissimo, ed è proprio questo il problema: esce insieme al gioco, e chiunque ci arriva con un --unpack.

Il modo affidabile per scoprire che cosa hai distribuito davvero è estrarlo in una cartella vuota e guardare. Fallo una volta per ogni versione che pubblichi. Ci vuole un minuto, ed è l’unico controllo che vede quello che hai dimenticato invece di quello che ricordi.

Crediti e licenze

Se una qualunque immagine, suono, musica o font del tuo gioco l’ha fatta qualcun altro, stai distribuendo il suo lavoro, e le condizioni a cui te l’ha dato sono un obbligo, non una cortesia. Non è una formalità e non è una questione di avvocati: una persona ha fatto quella cosa e in cambio ha chiesto una cosa precisa, di solito il suo nome.

Tieni un registro mentre lavori, non alla fine. Un file di testo semplice nella cartella del gioco con una riga per ogni elemento: che file è, da dove viene, chi l’ha fatto, quale licenza e che cosa richiede quella licenza. Scriverlo man mano richiede pochi secondi. Ricostruirlo la sera prima dell’uscita, dalla cronologia del browser, è il modo in cui i crediti vengono dimenticati.

Alcune cose che vale la pena sapere prima che ti servano. «Scaricabile gratuitamente» non è una licenza: cerca le condizioni vere. Creative Commons BY vuol dire che devi dare il credito indicato, e non c’è nessuna eccezione per i giochi. CC0 e il pubblico dominio non chiedono niente, e citare l’autore comunque ti costa una riga. I font hanno le loro licenze, e alcune ne permettono l’incorporazione mentre altre no. La musica presa da un video non è quasi mai tua da usare. Tutto ciò che è generato da uno strumento è pulito solo quanto le condizioni di quello strumento.

Poi metti i crediti in un posto dove un giocatore possa raggiungerli, dentro il gioco. Non solo in un file di testo lì accanto — un gioco impacchettato è un solo file e il file di testo è là dentro, dove nessuno guarderà. Lo script alla fine di questa lezione è quella schermata.

Il Singe/LICENSES di Singe stesso è il modello da copiare: una riga per ogni libreria, con la sua versione, la sua licenza e da dove viene. L’elenco del tuo gioco sarà più corto, e il lavoro è lo stesso.

Un numero di versione che significa qualcosa

Il tuo gioco avrà una seconda versione. La prima resterà in giro finché durerà internet, e qualcuno ti manderà una segnalazione di bug su di essa senza avere idea di quale versione abbia.

Quindi scegli un numero, mettilo dove un giocatore possa leggerlo, e non riusarne mai uno. La forma comune è in tre parti — 1.0.2 — e che cosa significano le parti conta meno del fatto che salgano sempre e soltanto. Alza l’ultima per una correzione, quella in mezzo per qualcosa di nuovo, la prima quando hai fatto un gioco diverso. Qualunque cosa tu scelga, scrivila nel tuo leggimi, così la rispetterà anche il te del futuro.

games.dat non ha una chiave per la versione, quindi il numero te lo devi portare dietro tu. Mettilo nello script come costante, mostralo nella schermata dei crediti, e mettilo nel nome di quello che spedisci (MyGame-1.0.2.game, MyGame-1.0.2.patch). Così la segnalazione del bug riporta la versione sullo schermo, e tu sai di quali file si parla.

Provarlo su una macchina che non è la tua

La tua macchina è il posto peggiore in assoluto per provare una versione da pubblicare. Ha i font che hai installato, la cartella che stavi modificando, il file di salvataggio con dentro le tue impostazioni, e il motore nello stato in cui l’ha lasciato un mese di lavoro.

La prova minima, in ordine:

  1. Estrai la versione in una cartella vuota e leggi l’elenco dei file.

  2. Copia solo il file .game in un’altra cartella, con una copia nuova di Singe e nient’altro, e avvialo dal menu come farà un giocatore.

  3. Cancella la cartella data di quella cartella e avvialo di nuovo. È un primo avvio su una macchina nuova: niente impostazioni salvate, niente punteggi record, nessun account connesso. Un gioco che funziona solo al secondo avvio è un bug comune, ed è così che lo trovi.

  4. Dallo a una persona che non l’ha mai visto, e guarda senza aiutare.

Poi prova la macchina oltre al gioco. Avrà uno schermo con proporzioni diverse, quindi guarda il gioco in finestra e a schermo intero. Potrebbe non avere nessun dispositivo 3D, ed è per questo che il menu ha un secondo renderer. La pagina System Information degli strumenti di servizio elenca su una sola schermata la versione del motore, il sistema operativo, il processore, il renderer, i decoder e la cartella dei dati; una foto di quella pagina risponde a quasi tutta una segnalazione di bug, e dirlo ai tuoi giocatori nel leggimi ti risparmierà una settimana di congetture.

Lo script

Una schermata dei crediti e della versione. È una cosa piccola da scrivere, ed è la parte della distribuzione che la maggior parte dei giochi sbaglia.

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

Sostituisci ogni riga di CREDITS con la verità sul tuo gioco. I segnaposto sono lì per mostrare la forma: che cos’è, chi l’ha fatto, quale licenza e da dove viene.

Cos’è appena successo

local GAME_VERSION = "1.0.2"

Un solo posto, in cima, in maiuscolo perché non cambia mai mentre il gioco gira. Tutto ciò che mostra la versione legge questo, quindi alzarla è una modifica sola invece di una ricerca.

    "Music                  \"Night Drive\" by A. Composer",

Quelle barre rovesciate sono la sequenza di escape che hai incontrato nella prima lezione: una virgoletta doppia che fa parte del testo invece di chiudere la stringa. I titoli contengono virgolette, ed è per questo che un elenco di crediti ci si imbatte già alla prima riga.

    for row = 0, ROWS - 1 do
        line = CREDITS[scroll + row + 1]
        if line then

Dieci righe di schermo che mostrano dieci righe di un elenco più lungo di dieci. scroll dice quanto è scesa la finestra lungo l’elenco. Il + 1 c’è perché Lua conta un elenco a partire da uno e le righe dello schermo contano da zero, e l’if line then c’è perché la fine dell’elenco è nil — leggere oltre la fine di una tabella in Lua non è un errore, ti dà semplicemente niente, e stampare niente lo sarebbe.

    overlayPrint(2, 1, "Singe " .. SINGE_VERSION_STRING .. "   id " .. (singeGetGameId() or "none"))

Tre fatti di cui una segnalazione di bug ha bisogno e che un giocatore non può trovare altrimenti: la tua versione sulla riga sopra, la versione del motore e l’id del gioco. SINGE_VERSION_STRING è una variabile globale che il motore imposta prima che il tuo script parta. or "none" copre il caso in cui il gioco non ha una voce in games.dat, così la riga viene stampata invece di andare in crash su un nil.

    overlayPrint(2, FIRST_ROW + ROWS + 2, singeGetDataPath())

Dove scrive questo gioco. In un gioco impacchettato è l’unico posto in cui viene scritto qualcosa, ed è la cartella che un giocatore cancella per ripartire da zero. Mostrarla trasforma «dove sono i miei salvataggi» in una frase a cui non devi mai rispondere.

Se quel percorso esce dal bordo destro dello schermo, non è rotto: overlayPrint scarta i caratteri che andrebbero oltre il bordo. L’overlay predefinito è largo sessanta celle di carattere.

Prova tu

  1. Impacchettalo. Metti questo script nella cartella del tuo gioco, esegui --pack e avvia il file .game. Poi estrailo in una cartella vuota e leggi l’elenco di quello che è uscito.

  2. Sostituisci un file. Accanto al file impacchettato, crea una cartella con il suo nome senza l’estensione, e mettici dentro un file modificato. Avvia il gioco impacchettato e guarda il tuo file sciolto vincere.

  3. Crea una patch. Cambia la versione in 1.0.3, metti solo lo script in una cartella fixes, impacchettala come .patch e applicala al gioco che hai già creato. Controlla la versione sullo schermo.

  4. Rompi l’impacchettatore. Rinomina per un momento il tuo games.dat e prova a impacchettare. Poi rimettilo a posto, fai puntare uno dei suoi nomi SCRIPT a un file che non c’è, e riprova. Due rifiuti diversi, entrambi prima che venga scritto qualunque cosa.

  5. Scrivi i crediti veri. Passa la cartella del gioco file per file e scrivi una riga per ognuno che non hai fatto tu. Se non riesci a ricordare da dove viene qualcosa, quella è la risposta alla domanda se dovresti distribuirlo.

Rompilo apposta

Avvia Singe una volta da dentro la cartella del gioco, così il motore ci estrae i suoi file di supporto, e poi impacchettala:

Singe --pack MyGame MyGame.game
!!! MyGame has Framework.singe:  Singe/Framework.singe
!!! MyGame has sh file:  Menu.sh

Non viene scritto niente. Ogni riga è un file che non accetta e il perché, e potresti riceverle nell’altro ordine o riceverne anche altre. Dentro il tuo gioco c’è una copia della cartella di supporto del motore, e lo script launcher che il motore ha scritto lì accanto, perché a un certo punto hai avviato Singe da lì dentro. Un gioco non deve mai portarsi dietro né l’una né l’altro: i file di supporto appartengono al Singe che sta usando il giocatore, qualunque sia, non al tuo gioco, e un Framework.singe impacchettato verrebbe caricato al posto del suo. Su Windows la seconda riga nomina invece Menu.bat.

Cancella la cartella Singe e Menu.sh (o Menu.bat) da dentro il gioco, tieni la cartella del gioco come una cartella accanto al programma Singe invece che attorno a esso, e impacchetta di nuovo. È la stessa struttura descritta nella tredicesima lezione, e questo errore è quello che succede quando la si perde di vista.

Cosa hai imparato

  • Singe --pack folder name.game trasforma la cartella del gioco in un solo file, e copiare quel file accanto al programma Singe lo installa.

  • Ogni nome di file dentro un gioco impacchettato viene cercato prima in una cartella sciolta, poi nella cartella dei dati, poi nel database.

  • Una cartella sciolta con il nome del file impacchettato lo sostituisce file per file, ed è così che continui a lavorare — e così che pubblichi una versione rotta se ti dimentichi che è lì.

  • Carica con DIR e scrivi solo sotto singeGetDataPath(), o il tuo gioco funzionerà da sciolto e fallirà da impacchettato.

  • --patch sostituisce dei file in un gioco pubblicato con un’unica transazione; --unpack riscrive fuori tutto quanto.

  • L’impacchettatore rifiuta i file del motore, i nomi in conflitto e un games.dat che punta a file che non ha.

  • Estrai la tua versione e leggi che cosa c’è dentro prima di mandarla da qualunque parte.

  • La grafica e i suoni di qualcun altro arrivano con delle condizioni, e rispettarle vuol dire avere una schermata dei crediti dentro il gioco.

  • Un numero di versione sale sempre e soltanto, e il suo posto è sullo schermo.

  • Prova su una macchina che non è la tua, partendo senza nessuna cartella data.

La prossima volta

Un solo file, installato, con i crediti e con il suo numero. L’ultima lezione lo mette in una cassa di legno con una fessura per i gettoni e senza tastiera, il che cambia del tuo gioco più di quanto penseresti.

Lezione 31: In un cabinato

La lezione finita

C’è una differenza tra un gioco e una macchina da sala giochi, e non è il legno. Una macchina si accende da sola la mattina, gioca davanti a una sala vuota, prende un gettone da qualcuno che non ne ha mai letto una parola, ed è ancora in funzione a mezzanotte senza che nessuno abbia toccato una tastiera, perché la tastiera non c’è. Tutto quello che c’è in questa lezione viene da qui.

Per fare tutto questo non ti serve un cabinato. Una levetta e due pulsanti sulla scrivania, o un controller, bastano per trovare ogni errore di questa lezione, e quasi tutto quello che impari qui migliora un gioco anche su un normale computer.

La tastiera non c’è

Comincia da quello che manca, perché è la cosa che rompe i giochi.

Un cabinato ha una levetta, qualche pulsante, uno sportello per i gettoni, un pulsante Start e, da qualche parte all’interno, un piccolo interruttore che il gestore può raggiungere. Tutto qui. Niente Esc, niente lettere, niente mouse, nessun modo di scrivere. Quindi:

  • Ogni menu del tuo gioco deve essere raggiungibile con su, giù e un pulsante. Se una qualunque schermata del tuo gioco dice «premi Y per continuare», in un cabinato non funziona.

  • Inserire le iniziali vuol dire tre pulsanti e una lettera che scorre, non un campo di testo. È per questo che nei giochi da sala i nomi sono di tre lettere.

  • Una richiesta che nomina un tasto con la sua lettera è sbagliata. Scrivi «pulsante 1», o disegna il pulsante.

  • Non c’è via d’uscita. Un giocatore non può uscire, e non deve poterlo fare.

Ripercorri il tuo gioco una volta, schermata per schermata, e chiediti di ognuna: qualcuno riuscirebbe a superarla con una levetta e un pulsante? Quel giro sul tuo gioco vale più di tutto il resto di questa lezione.

controls.cfg

Dalla terza lezione leggi i comandi come SWITCH_UP, SWITCH_BUTTON1, SWITCH_COIN1 e così via, e non hai mai detto nemmeno una volta a quale tasto corrispondono. È proprio questo il loro scopo. Da qualche parte tra il microinterruttore del cabinato e il tuo onInputPressed c’è un file che decide, e il tuo gioco non fa parte di quella conversazione.

Il file è controls.cfg. È Lua, come il tuo script, ed è un elenco di tabelle — una per ogni interruttore — che nominano tutto ciò che può produrlo:

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 }

Ogni nome INPUT_ del file diventa il valore SWITCH_ corrispondente nel tuo gioco: INPUT_ACTION_1 è lo SWITCH_BUTTON1 che hai sempre controllato, e INPUT_1P_COIN è SWITCH_COIN1. Ogni voce di una tabella produce lo stesso interruttore, quindi a un gioco non importa se il giocatore ha premuto il tasto, il pulsante del controller o ha spinto la levetta.

Non devi scrivere tutto il file. Singe parte dalle sue impostazioni predefinite e legge controls.cfg da quattro posti, uno dopo l’altro — la cartella dello script del gioco, la cartella da cui è stato avviato Singe, la cartella sopra la cartella dei dati del gioco e la cartella dei dati del gioco — e ognuno che trova sostituisce quello che c’era prima, chiave per chiave. Così un cabinato ha un solo file in cima per tutta la macchina, e un gioco che ha bisogno di un pulsante in più ha un file tutto suo di quattro righe. Nella cartella Singe c’è un controls.cfg.example da cui copiare.

Lì dentro c’è anche DEAD_ZONE: di quanto deve muoversi una levetta prima di contare come premuta, nelle unità grezze che riporta l’hardware, dove l’inclinazione massima è 32767. Il valore predefinito è 15000. Una levetta consumata che si sposta da sola ha bisogno di un numero più grande, e DEAD_ZONES imposta un asse alla volta per quell’unica levetta stanca. La sezione del manuale sulla personalizzazione dei comandi spiega tutto.

Ogni dispositivo è un controller

I pulsanti di un cabinato sono collegati a una scheda encoder, che il computer vede come una specie di joystick, e che non somiglia per niente a un controller Xbox. Per un dispositivo del genere Singe scrive da solo un’assegnazione e poi lo apre come GAMEPAD_0, così arriva a controls.cfg e al tuo gioco esattamente come un controller riconosciuto. C’è una sola famiglia di dispositivi e nessun secondo vocabolario da imparare.

L’assegnazione che inventa è la più diretta: i pulsanti della scheda, in ordine, diventano BUTTON_A, BUTTON_B, BUTTON_X, BUTTON_Y e così via. Se i pulsanti del tuo cabinato non sono collegati in quell’ordine, finiranno nei posti sbagliati, e la correzione non sta nel tuo gioco: --program scrive nella traccia l’assegnazione creata da Singe, in una forma che puoi modificare e mettere in un gamecontrollerdb.txt accanto al gioco.

Quando un pulsante «non fa niente», lo strumento Input Test del menu risponde alla domanda in cinque secondi. Mostra ogni dispositivo che il motore riesce a vedere, e l’ultimo interruttore che sarebbe stato consegnato a un gioco. O l’interruttore arriva e il tuo gioco lo ignora, o non arriva mai e il problema è l’assegnazione o il filo.

Quattro interruttori non sono tuoi

Quasi tutti gli interruttori vanno dritti al tuo gioco. Quattro no: della pausa, dell’uscita, dello screenshot e del comando che cattura e rilascia il mouse si occupa il motore stesso.

La pausa è davvero utile, e gratis. Finché è del motore, il tasto assegnato a INPUT_PAUSE congela tutto — il disco, ogni video, ogni suono e il tuo script — disegna un suo indicatore, e scongela tutto alla pressione successiva. Tutto ciò che il tuo gioco credeva tenuto premuto viene rilasciato come si deve e premuto di nuovo dopo, così una levetta tenuta durante una pausa non resta mai bloccata.

L’uscita è quella da togliere, ed è quello che fa una sezione più avanti.

Gettoni, crediti e Start

Una macchina da sala giochi ha una forma più vecchia di tutti noi, e i giocatori la conoscono senza che nessuno gliela spieghi:

  1. Modalità attract. Non c’è nessuno. La macchina mostra che cos’è, fa lampeggiare INSERT COIN e non chiede niente.

  2. Credito. Un gettone arriva come SWITCH_COIN1. I gettoni diventano crediti al cambio deciso dal gestore — non sempre uno a uno.

  3. Partita. SWITCH_START1 spende un credito e fa partire il gioco.

  4. Game over. Il punteggio, per un attimo, e poi di nuovo in modalità attract da sola. Nessuno preme niente per uscire: il giocatore se n’è andato.

Due dettagli che si sbagliano spesso. I gettoni si contano, non si spendono: a due gettoni per credito, un gettone deve restare lì ad aspettare il suo compagno, e un giocatore che ne ha messo uno e se n’è andato l’ha lasciato alla persona successiva. E la macchina deve trovare da sola la strada per tornare alla modalità attract, perché l’ultima cosa che fa un giocatore è smettere di giocare.

Dietro l’interruttore di servizio

Dentro lo sportello dei gettoni c’è un pulsante che il giocatore non vede mai e che il gestore usa di continuo. È SWITCH_SERVICE, e il motore lo passa direttamente a te.

Un gestore che apre il tuo menu di servizio si aspetta di trovare, più o meno in quest’ordine:

  • il prezzo — i gettoni per credito, e un’impostazione di free play per una macchina in casa o a una fiera;

  • la difficoltà, perché una macchina in un bar e una in una sala giochi vogliono risposte diverse;

  • un modo per azzerare la tabella dei punteggi record, che è in assoluto la cosa più richiesta di questo elenco;

  • che macchina è — la versione del motore, lo schermo, dove stanno i dati — così una segnalazione di guasto contiene dei fatti;

  • un modo per uscire, senza spegnere niente.

Tutto ciò che un gestore cambia deve sopravvivere a un’interruzione di corrente, che in una sala giochi vuol dire un’interruzione nel mezzo di una partita, senza preavviso, da parte di qualcuno che stacca una spina. saveSet scrive alla fine del fotogramma, che è abbastanza presto per un punteggio e non abbastanza per un’impostazione che qualcuno ha appena regolato. saveFlush() scrive subito, e un menu di servizio è esattamente ciò a cui serve.

Gli strumenti di servizio del menu incluso, dietro lo stesso interruttore, vale la pena conoscerli, perché sono su ogni macchina su cui girerà il tuo gioco: il test dei comandi, i test del suono e delle pistole ottiche, la geometria dello schermo, il ritardo dell’audio, l’account online e una pagina che cancella i dati salvati di un singolo gioco. Il tuo non deve ripeterli.

Una macchina che si avvia da sola e non esce mai

Il cabinato si accende dalla presa a muro. Nessuno accede al computer. Un gioco deve comparire sullo schermo nel giro di un minuto o giù di lì, e restarci.

Far partire Singe all’accensione è compito del sistema operativo, non di Singe — la macchina avvia il Menu.sh o il Menu.bat che il motore scrive accanto ai tuoi giochi, oppure direttamente il tuo gioco. Compito tuo è quello che succede per il resto della giornata.

Togli di mezzo il tasto per uscire:

singeSetQuitKeyEnabled(false)

A quel punto il motore ignora l’interruttore assegnato a INPUT_QUIT e lo consegna a te come SWITCH_QUIT, come tutti gli altri, così puoi prima chiedere, prima salvare, o non fare proprio niente. Il pulsante di chiusura della finestra fa sempre uscire, qualunque cosa tu imposti, e tra un attimo questo conterà.

Poi ci sono alcune opzioni che appartengono alla macchina invece che al tuo script, e vanno in un settings.cfg accanto ai giochi — con gli stessi nomi delle opzioni da riga di comando, senza i trattini:

fullscreen  = true
screen      = 2
idleexit    = 900
startsilent = true

idleexit esce dopo quel numero di secondi senza nessun comando di nessun tipo, per un cabinato che deve restituire lo schermo a un menu o a un front-end. startsilent parte senza audio finché qualcuno non tocca qualcosa, ed è così che una sala piena di macchine diventa sopportabile. Ce ne sono altre; le sezioni del manuale sulle impostazioni e sulla riga di comando le elencano tutte.

Grafica attorno all’immagine

Un vero cabinato ha un bezel (una cornice decorativa) stampato attorno allo schermo: una grafica con un buco attraverso cui si vede il gioco. Singe ne disegna uno per te.

Singe --bezel cabinet.png MyGame.game

Il file viene cercato in una cartella bezels dentro il gioco — un gioco impacchettato può portarsi dietro la sua — e poi in una cartella bezels nella cartella dei dati, così un giocatore può mettere la sua grafica su un gioco senza toccarlo. Accanto al file della grafica, con il suo stesso nome, un piccolo file Lua dice dove va l’immagine del gioco, nei pixel della grafica stessa:

-- bezels/cabinet.cfg
CUTOUT = { x = 200, y = 120, width = 800, height = 500 }

Siccome quei numeri sono della grafica stessa, restano giusti con qualunque dimensione della finestra: l’immagine e il buco si ridimensionano insieme. Senza quel file l’immagine del gioco occupa tutta la finestra, come ha sempre fatto.

Di base la grafica sta dietro a tutto e il tuo gioco copre il buco. --bezelflip invece la mette davanti, così solo le sue parti trasparenti lasciano passare il gioco, che è quello che vuoi per bordi sfumati o sagomati — e a quel punto anche il tuo overlay finisce sotto, a meno che tu non dica altrimenti:

if mainBezelLoaded() then
    setOverlayOnTop(true)
end

mainBezelLoaded() ti dice anche se una grafica c’è o no, ed è così che un gioco decide di disegnare una cornice sua quando non ce n’è.

Un monitor su un fianco

Molti monitor da sala giochi sono montati in verticale. Ruota tutta la presentazione:

Singe --rotate=90 MyGame.game

L’immagine, l’overlay, l’eventuale GUI, una scena 3D e le particelle ruotano tutti insieme, e le posizioni del mouse e della pistola ottica vengono ruotate all’indietro, così un clic finisce ancora dove lo vede il giocatore. Un quarto di giro scambia anche la forma dell’area, così una finestra alta viene riempita invece di ridursi a una striscia tra due bande nere.

Sono accettati solo 0, 90, 180 e 270. Uno script può cambiare la rotazione mentre gira con vldpSetRotate, che per qualsiasi altro valore risponde false invece di terminare il gioco, e vldpGetRotate() la rilegge — e vale la pena metterla in una schermata di servizio, perché «l’immagine è girata» e «il monitor è girato» sono guasti diversi.

Quello che la rotazione non fa è riscrivere il tuo gioco. Un gioco disegnato per uno schermo largo, ruotato di novanta gradi, è un gioco largo messo su un fianco. Progettare per uno schermo alto vuol dire progettare per uno schermo alto.

Lo script

Tutta la forma: modalità attract, gettone, credito, partita, game over, servizio, e un’uscita che chiede conferma. Il gioco in mezzo è un pulsante e un timer di quindici secondi, perché stavolta il punto non è il gioco — è la macchina che gli sta attorno.

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

Avvialo e premi 5 per un gettone, 1 per Start e 9 per l’interruttore di servizio — sono le impostazioni predefinite del controls.cfg incluso. Poi premi Esc, e leggi che cosa dice prima di premerlo di nuovo.

Cos’è appena successo

local coinsPerCredit = saveGet("coinsPerCredit", 1)
local difficulty     = saveGet("difficulty", 2)
local freePlay       = saveGet("freePlay", false)

Le impostazioni del gestore vengono lette una volta, in cima, con un valore sensato per una macchina che non è mai stata configurata. saveGet con un secondo argomento restituisce quel valore quando non è stato salvato niente, ed è così che si distingue un primo avvio da uno successivo.

local function insertCoin()
    coins = coins + 1
    while coins >= coinsPerCredit do
        coins   = coins - coinsPerCredit
        credits = credits + 1
    end
end

Entrano gettoni, escono crediti, al cambio deciso dal gestore. Il while al posto di un if non è prudenza contro un input impossibile — è il gestore che abbassa il prezzo da quattro gettoni a uno mentre lì dentro ci sono tre gettoni in attesa.

    if what == SWITCH_QUIT then
        if state == "confirm" then
            singeQuit()
        else
            goBackTo = state
            state    = "confirm"
        end
        return
    end

L’interruttore per uscire arriva al tuo gioco solo grazie al singeSetQuitKeyEnabled(false) in fondo allo script. Premerlo una volta fa la domanda; premerlo di nuovo, dalla schermata della domanda, fa sì che sia tu a chiamare singeQuit(). goBackTo ricorda dov’era il giocatore, così rispondere di no lo rimette nella sua partita invece che sulla schermata attract.

Questo blocco è il primo della funzione e finisce con return, così nient’altro può inghiottire l’interruttore. Ogni altro stato del gioco viene gestito sotto.

    if state == "service" then
        serviceInput(what)
        return
    end

Di nuovo la stessa forma. Finché il menu di servizio è aperto, ogni interruttore appartiene a lui — la levetta non guida il gioco che c’è sotto, un gettone non arriva nel mezzo di una regolazione. Un if, presto, con un return. Ogni schermata che sta sopra un’altra ne ha bisogno, e un gioco che ne accumula tre senza averlo produce bug quasi impossibili da descrivere.

        saveSet("coinsPerCredit", coinsPerCredit)
    ...
    saveFlush()

Imposta, poi forza la scrittura. Senza forzarla, la scrittura avviene alla fine del fotogramma, il che è presto ma non subito. Un gestore regola un’impostazione e stacca la spina dieci secondi dopo, e questo è l’unico posto in un gioco in cui succede davvero.

    elseif (singeGetTicks() // 400) % 2 == 0 then
        overlayPrint(2, 4, "INSERT COIN")
    end

Il lampeggio. singeGetTicks() sono i millisecondi da quando è partito il motore, // divide e butta via il resto, quindi il numero cambia ogni quattrocento millisecondi, e % 2 lo fa alternare tra zero e uno. Nessuna variabile, nessun timer, niente da azzerare: l’orologio stava già contando.

    overlayPrint(2, 10, "Singe " .. SINGE_VERSION_STRING .. "   rotation " .. vldpGetRotate())

La metà della pagina di servizio che riguarda il gestore. Una versione, una rotazione, se c’è una grafica e dove stanno i dati. Niente di tutto ciò è per il giocatore, ed è tutto quello che vorresti avere quando qualcuno ti telefona per una macchina a cinquecento chilometri di distanza.

singeSetQuitKeyEnabled(false)
hasBezel = mainBezelLoaded()

In fondo, fuori da ogni funzione, così viene eseguito una volta quando lo script si carica. Nessuna delle due cose va fatta a ogni fotogramma, e mainBezelLoaded non può cambiare mentre il gioco gira.

Prova tu

  1. Cambia il prezzo. Apri il menu di servizio, imposta i gettoni per credito a due e inserisci un gettone. Guarda il credito non comparire, e guarda il contatore dei gettoni sulla riga in fondo. Poi esci, riavvialo e verifica che il prezzo sia rimasto.

  2. Gioca gratis. Attiva il free play e controlla che Start funzioni senza gettoni e che i crediti non vadano sotto zero.

  3. Aggiungi una pagina. Metti una seconda pagina di informazioni di servizio dietro il pulsante 3 — i campi di singeGetSystemInfo() sono un buon inizio, e la voce del riferimento li elenca tutti.

  4. Ruota lo schermo. Avvialo con --rotate=90 e guarda la tua disposizione. Poi rendi la pagina di servizio leggibile con quella rotazione, il che è più difficile di quanto sembri ed è esattamente il lavoro che chiede un cabinato verticale.

  5. Togli di mezzo la tastiera. Scollegala, o prometti a te stesso di non toccarla, e gioca tutte le schermate con un controller. Qualunque cosa tu non riesca a raggiungere è un bug.

Rompilo apposta

Cancella il blocco di SWITCH_QUIT da onInputPressed, lasciando singeSetQuitKeyEnabled(false) dov’è, e avvialo.

Ora niente fa uscire. Esc non fa niente, Q non fa niente, e il tuo gioco non ha via d’uscita, che è esattamente quello che hai chiesto. Non è un crash e non c’è nessun messaggio: il motore ha fatto esattamente quello che gli è stato detto.

Chiudi la finestra con il suo pulsante di chiusura. Quello funziona sempre, qualunque cosa dica uno script, ed è la porta che ti sei lasciato aperta. A schermo intero, prima Alt-Enter ti riporta in una finestra.

Vale la pena provarlo sulla tua pelle. Disattivare il tasto per uscire è l’unica cosa di questo libro che può lasciarti con un programma da cui non riesci a uscire, e l’abitudine che lo evita è semplice: scrivi la via d’uscita nella stessa seduta in cui disattivi il tasto per uscire, mai dopo.

Cosa hai imparato

  • Un cabinato non ha la tastiera, quindi ogni schermata del gioco deve funzionare con una levetta e un pulsante.

  • controls.cfg assegna tasti, pulsanti del controller e direzioni della levetta ai nomi SWITCH_ che il tuo gioco usa già, e il tuo gioco non viene mai a sapere che cosa è stato premuto.

  • Vengono letti, uno dopo l’altro, quattro file di assegnazioni, e ognuno sostituisce il precedente, così possono esistere sia un file per tutta la macchina sia un file per ogni gioco.

  • Ogni dispositivo che Singe apre è un controller, compresa una scheda encoder da sala giochi, e lo strumento Input Test dice che cosa sta arrivando.

  • Il motore tiene per sé pausa, uscita, screenshot e cattura del mouse; il resto è tuo.

  • I gettoni si contano e diventano crediti al cambio deciso dal gestore, e una macchina torna da sola alla modalità attract.

  • SWITCH_SERVICE è l’interruttore del gestore, e dietro ci sono il prezzo, la difficoltà, un modo per azzerare i punteggi e che macchina è.

  • saveFlush() scrive un’impostazione subito, perché un cabinato perde la corrente senza preavviso.

  • singeSetQuitKeyEnabled(false) consegna l’interruttore per uscire al tuo gioco. Scrivi la via d’uscita nello stesso momento.

  • Un bezel è una grafica con un buco, e --rotate ruota tutta la presentazione per un monitor verticale.

Fine

Sono trentuno lezioni, e sai scrivere un gioco.

Non un gioco perfetto, e non ancora un gioco grande, ma quello che ti separa da entrambi è tempo e pratica, non un altro libro. Hai cominciato con cinque righe che mettevano una parola su uno schermo nero. Ora sai che cos’è una variabile, a che cosa serve una funzione, come si disegna, come si fa un rumore, come si capisce quando due cose si sono toccate, come si tiene un punteggio in un posto dove sopravvive, come si usa un filmato come mondo, come si mette un modello in una stanza con una luce accesa, e come si consegna il tutto a uno sconosciuto.

Quello che ti serve adesso è il Riferimento di Singe, non questo libro. È il riferimento per ogni funzione, ogni argomento e ogni valore restituito, ed è quello che terrai davvero aperto mentre lavori. Viene con questo libro, come Reference.pdf e Reference.html. Leggi la voce prima di usare la chiamata; nella maggior parte delle voci c’è una nota sull’errore che si fa di solito con quella chiamata.

Leggi anche gli script che vengono con Singe. Singe/Menu.singe, Singe/Tools.singe e Singe/Framework.singe non sono dimostrazioni scritte per essere lette — sono il menu e gli strumenti di servizio che hai usato fin dall’inizio, e fanno un lavoro vero con le stesse funzioni che hai tu. Capire come il programma di qualcun altro fa una certa cosa è un’abilità a sé, e quelli sono un posto gentile in cui esercitarla.

E poi c’è Forge, uno strumento separato con un libro tutto suo, per descrivere un gioco invece di scriverlo. È una strada diversa. Non ti serve, ma c’è.

Il prossimo gioco è tuo. Fai prima quello piccolo, finiscilo, e mettilo davanti a qualcuno. Finire è la parte che nessuno ti dice che è quella difficile, ed è l’unica parte che trasforma una cartella piena di script in un gioco a cui qualcuno ha giocato.

Vai a costruirlo.