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.
-
Ciao — uno script, una funzione, una stringa e qualcosa sullo schermo.
-
Numeri che cambiano — variabili, aritmetica e far muovere le cose.
-
Prendere decisioni —
if, i confronti e la lettura dei comandi. -
Ancora una volta —
forewhile, e disegnare cento copie di qualcosa. -
Funzioni tutte tue — argomenti, valori restituiti e perché prendersi il disturbo.
-
Elenchi di cose — tabelle,
ipairs, aggiungere e togliere. -
Un gioco — tutto quello visto finora, giocabile, in circa centoventi righe.
-
Quando qualcosa va storto — leggere gli errori,
debugPrinte ricaricare con F5.
Seconda parte: un vero gioco. Grafica, suono e la forma che prende un gioco finito.
-
Immagini — sprite, caricamento, disegno e fotogrammi.
-
Suono — effetti, musica e quando caricare che cosa.
-
Colpire le cose — collisioni, il kit di gioco e le hitbox.
-
Punteggio, vite e game over — stato, salvataggio e ricominciare da capo.
-
La cartella del gioco —
games.dat, la grafica per il menu e l’avvio da lì.
Terza parte: video. Riprodurre filmati come mondo del gioco, e le convenzioni da sala giochi che sono nate attorno a questo. Salta questa parte se il tuo gioco non vuole video; niente di ciò che viene dopo dipende da questa parte.
-
Riprodurre video — il disco, i fotogrammi, la ricerca e l’attesa.
-
L’altro modo di scriverlo — il modello a thread («threaded»), e perché si adatta al video.
-
Diramazioni — scelte, percorsi e la forma di un gioco video a diramazioni.
-
Pistole ottiche — mirare, sparare e la calibrazione di cui ha bisogno un cabinato.
-
Quick-time event — richieste a schermo, finestre di tempo e il punteggio sul tempismo del giocatore.
Quarta parte: tutto il resto. Ogni lezione sta in piedi da sola; affrontale nell’ordine che preferisci.
-
Testo che fa bella figura — font, qualità e misure.
-
Menu e schermate — la GUI, i documenti e gli stili.
-
Sottotitoli — e perché sono un sistema a parte.
-
Nel 3D — scene, telecamere e coordinate.
-
Modelli e luce — glTF, materiali e animazione.
-
Fisica — corpi, forze, giunti e quando non usarli.
-
Particelle — emettitori, e come fare un’esplosione.
-
Personaggi che si muovono da soli — navigazione e ricerca del percorso.
-
Musica e MIDI — tracce, soundfont e strumenti.
-
Online — account, classifiche dei punteggi record e il catalogo.
-
Conservare i dati — database, tabelle e le domande che poni loro.
-
Distribuirlo — impacchettare, applicare patch, licenze e l’uscita.
-
In un cabinato — comandi, menu di servizio, bezel (cornici decorative) e le cose che contano solo sull’hardware vero.
Lezione 1: Ciao
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.
-
Sposta il testo. Cambia
overlayPrint(2, 2, "Hello!")inoverlayPrint(10, 5, "Hello!"). Poi prova(0, 0). Poi prova(200, 2), e scopri perché è sparito. -
Di' qualcos’altro. Metti il tuo nome tra le virgolette.
-
Di' due cose. Aggiungi una seconda riga
overlayPrintsotto la prima, con un numero di riga diverso e un testo diverso. Niente ti impedisce di averne quante ne vuoi. -
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
functionraggruppa delle istruzioni sotto un nome e si ferma al suoend. -
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
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
-
Cambia le velocità. Prova
speedX = 1espeedY = 1. Poi prova0.05per entrambe. Poi rendine una molto più grande dell’altra. -
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.lenche fa il suo lavoro. -
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. -
Impediscile di andare di lato. Metti
speedX = 0ed eseguilo. Scopri perché ora la parola non lascia mai la colonna zero, e perché il bloccoifdel bordo sinistro non scatta mai. -
Rompi apposta il contatore dei fotogrammi. Riporta la riga
frames = 0dentro la funzione, sopraframes = 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 + 1calcola 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
onOverlayUpdateviene 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.
-
overlayGetWidtheoverlayGetHeightti dicono le dimensioni della superficie su cui disegni, così non devi mai tirare a indovinare. -
overlayClearconta 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
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 è minore di b |
|
a è maggiore di b |
|
a è minore o uguale a b |
|
a è maggiore o uguale a b |
|
a è uguale 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 trannefalseenil.
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
-
Cambia la velocità.
BOX_SPEED = 1eBOX_SPEED = 8. A otto, guarda che cosa fa il contenimento quando spingi il riquadro in un angolo. -
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 iltostringe leggi l’errore che ti dà Lua. -
Fallo andare più veloce quando un pulsante è premuto. Aggiungi un flag
runningcomandato daSWITCH_BUTTON1nelle due callback dei comandi, e usa unifinonOverlayUpdateper muoverti del doppio diBOX_SPEEDfinché è vero. -
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à
andper unire quattro confronti, ed è più difficile di quanto sembri. Sbagliarlo un po' è normale; l’undicesima lezione lo fa per bene. -
Togli i rilasci. Cancella tutta la funzione
onInputReleaseded 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 … endesegue un corpo solo quando la risposta è vera. -
elsedà l’altro caso, eelseifne 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. -
trueefalsesono valori, e puoi tenerli in delle variabili. -
and,orenotuniscono e capovolgono quelle risposte. -
nilè quello che ottieni da un nome che non hai mai impostato, e non è zero. -
Tutto è vero tranne
falseenil. -
onInputPressedeonInputReleasedsono callback che Singe chiama con un valoreSWITCH_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.
-
overlayBoxdisegna un contorno in pixel, ecolorForegroundè 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
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
forquando 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
whilequando 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
-
Di più e di meno. Prova
STARS_PER_LAYER = 200, poi4. PoiLAYERS = 8e guarda che cosa falayer * LAYER_BRIGHTashadequando il numero dello strato diventa grande. I numeri che accettacolorForegroundsi fermano a 255. -
Cambia la spaziatura. Metti
ACROSS_STEPa 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. -
Ferma lo scintillio. Sostituisci la riga con
math.randomcon un sempliceshade = layer * 70e confronta. Decidi quale preferisci; non c’è una risposta giusta, e accorgerti di avere una preferenza fa parte del lavoro. -
Falle cadere verso l’alto. Un carattere.
-
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 … endesegue 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.
-
forha bisogno di undo, e ogni ciclo ha bisogno di unend. -
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 … endripete finché la domanda è vera, e qualcosa nel corpo devi cambiarlo tu. -
Usa
forquando sai quante volte, ewhilequando 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.floorbutta 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 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
-
Rinomina un parametro. In
drawStar, cambiaxeyinacrossedown, ovunque dentro la funzione. Non toccare niente fuori. Eseguilo. Scopri perché non si è rotto niente. -
Disegnali al contrario. Scambia
drawStars()edrawPlayer()inonOverlayUpdatee 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. -
Usa
clampsu una sfumatura. CambiashadeForinreturn clamp(math.random(60, 90) + layer * 90, 0, 200)e guarda i tre strati. Poi togli ilclampe guarda di nuovo:colorForegroundti teneva in silenzio i numeri sotto il limite da sempre, e ora puoi vedere dove. -
Chiama
drawStarcon due argomenti. ScrividrawStar(100, 100)da qualche parte indrawLayered eseguilo. L’errore nomina esattamente la cosa che è mancata. Leggilo prima di rimettere il terzo argomento. -
Sposta una locale. Prendi la riga
local drift = 0e 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.
-
returnrestituisce un valore e ferma la funzione lì dov’è, e una funzione che finisce senza di esso restituiscenil. -
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.
-
localcrea 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
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.
-
ivale1. La stella uno va bene. -
ivale2. 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. -
ivale3. È 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. -
ivale4. 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
-
Rendilo più profondo. Cambia
math.random(1, 3)inmath.random(1, 6)eSTAR_SHADEin25. Più velocità, più sfumature, un cielo più profondo. -
Meno stelle, raffica più grande. Imposta
STAR_COUNTa10eBURST_COUNTa100, poi premi il pulsante tre o quattro volte. Guarda salire il conteggio sullo schermo, e cronometra quanto ci mette a svuotarsi. -
Dai a una stella un altro campo. Aggiungi
age = 0anewStar, aggiungi uno astar.ageinmoveStarse mettistars[1].agesullo schermo accanto al conteggio. Per portarsi dietro un fatto nuovo su ogni stella, nel resto del programma non serve cambiare niente. -
Smetti di toglierle. Cancella le tre righe del blocco
if star.y >= heightdamoveStarsed eseguilo. Aspetta dieci secondi, poi leggi il conteggio sullo schermo e guarda il cielo. Scopri come possono essere vere entrambe le cose insieme. -
Fallo in avanti. Cambia
for i = #stars, 1, -1infor i = 1, #starsed 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, elist[#list]è l’ultimo. -
table.insertaggiunge un elemento, in fondo o nella posizione che indichi;table.removene toglie uno e chiude il vuoto. -
Un indice o un campo mai riempito è
nil, e niente ti avvisa finché non lo usi. -
ipairspercorre 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
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. -
SCANCODEeMODIFIER, nomi per ogni tasto di una tastiera, per un gioco che legge quello che si digita invece di un joystick. -
Da
GAMEPAD_0aGAMEPAD_3e daMOUSE_0aMOUSE_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
-
Rendilo più facile, poi ingiusto. Cambia
PLAYER_WIDTHin80e gioca una partita. Poi cambialo in12, 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. -
Accelera più in fretta. Cambia
BLOCK_FASTERda0.05a0.5e guarda quanti punti riesci a fare. Poi prova0, e chiediti se vale ancora la pena di giocarci. -
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. -
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. AncheTEXT_COLUMNSl’ha chiesto. -
Mettilo in pausa. Aggiungi un quarto stato,
"paused".SWITCH_BUTTON2dovrebbe passare da"playing"a"paused"e viceversa, e durante la pausa non dovrebbe muoversi niente. Fatto bene, sono tre righe e non devi toccareupdatePlayingper 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.
-
collideRectsrisponde 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
stateche 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
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 unlocaldavanti, da nessuna parte. -
local— un nome che hai dichiarato conlocalnella funzione in cui ti trovi. -
field— un nome dopo un punto, come layinblock.y. -
upvalue— una variabilelocaldi un livello più esterno che questa funzione riesce a vedere, ed è ciò che sono tutte le variabili didodge.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:
-
Hai scritto male una delle tue funzioni.
-
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.
-
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.
-
L’hai resa
locale l’hai chiamata da un punto che sta sopra quello in cui è dichiarata. È esattamente per questo che le funzioni didodge.singesono 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
-
Conoscili tutti. Fai apposta in
dodge.singeciascuno dei cinque errori di questa lezione, uno alla volta, e leggi il messaggio prima di correggerlo. Non ne avrai mai più paura. -
Osserva chi crea i blocchi. Metti dentro
spawnBlockundebugPrintche stampi laxdel nuovo blocco. Gioca per trenta secondi, poi guarda i numeri. Sono sparsi su tutto lo schermo, o preferiscono un lato? -
Spegnilo. Cambia
DEBUGinfalsenello script della lezione, e assicurati che non venga stampato niente e che il gioco non cambi. -
Un bug senza errore. In
updatePlaying, cambiaif spawnTimer ⇐ 0 theninif 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 undebugLogdentrospawnBlock, aggiungispawnTimeralla prima riga che stampadebugReporte 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. -
Rompi il nome di una callback. Rinomina
onInputPressedinonInputPressed 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 scriptvuol 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
endmancante 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.
-
debugPrintti mostra che cosa contiene davvero una variabile.tostringrende stampabile qualsiasi cosa, e un interruttore comeDEBUGspegne 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
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.glbeSinge/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
-
Centra l’astronave sulla sua posizione. Aggiungi
truecome quarto argomento allospriteDrawdell’astronave. Guarda dove salta l’astronave, e dalla distanza di cui si è spostata deduci che cosa ha fatto davvero il quarto argomento. -
Più rocce. Cambia
ROCK_COUNTin 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. -
Fai crescere l’astronave. Aggiungi
spriteScale(shipSprite, 2)proprio in fondo al file, sulla riga soprastartGame(). 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 chiamatespriteGetWidthe guarda le cose sistemarsi. La voce dispriteScalenel Riferimento spiega che cosa fa la scalatura alle misure. -
Metti dentro chi cammina. Carica
walk.pngnel 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 dionOverlayUpdateva il disegno — davanti alle stelle, dietro le rocce. -
Scarica qualcosa che stai ancora usando. Aggiungi
spriteUnload(starSprite)in fondo al file, dopostartGame(), 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. -
spriteLoadrestituisce 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 dentroonOverlayUpdate. Un quarto argomentotrueindica invece il centro. -
Carica una volta, in cima al file. Caricare dentro
onOverlayUpdatesi mangia la memoria finché il gioco muore. -
spriteUnloadrestituisce un’immagine, di solito daonShutdown, e dopo l’handle è morto. -
Il PNG porta con sé la trasparenza, ed è per questo che gli angoli dell’astronave non sono riquadri neri.
-
spriteGetWidthespriteGetHeightmisurano 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, espriteDrawFrame(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
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.
-
musicStoppuò 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
-
Rendi il colpo ancora più piano. Cambia il
35nelsoundPlaydel colpo in10, poi in63. Trova il numero in cui sta sotto le esplosioni invece che sopra. -
Abbassa la musica senza toccare gli effetti. Cambia
musicSetVolume(50)inmusicSetVolume(15). Verifica che i botti siano forti esattamente quanto prima, che è tutto il motivo per cui la musica è un sistema a parte. -
Taglia il finale. In
endGame, cambiamusicStop(theme, 1500)inmusicStop(theme). Ascolta entrambi i finali due volte. La differenza è un numero in un argomento, e non è una piccola differenza. -
Dai un motore alla nave. Avvia
soundPlay(clickClip, -1, 12)instartGame, tieni il canale che ti dà in una variabile tutta sua e fermalo inendGame. 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 ilsoundStop, gioca tre partite di fila e ascolta che cosa hai costruito. -
Conta i canali. Stampa il numero del canale ogni volta che una roccia esplode. Poi aumenta
ROCK_COUNTfinché 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
-
soundLoadlegge una clip e restituisce un handle. Carica una volta, in cima al file. -
soundPlayavvia una clip e restituisce un canale, che è un tipo di numero diverso dall’handle. -
Singe mescola sedici canali. Quando sono tutti occupati,
soundPlayrestituisce-1e 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. -
soundUnloadnon 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
0a63. Il volume della musica va da0a128. 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
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:
-
collideCirclesecollidePointCircle, 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 numerix,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
-
Togli il margine. Metti
ROCK_PADa0e gioca per un minuto. Poi mettilo a8e gioca di nuovo. In uno dei due casi sembra che il gioco ti stia mentendo. -
Guarda che cosa stai controllando. Metti
SHOW_BOXESatruee osserva i contorni verdi mentre una roccia passa accanto alla nave. Ora mettiSHIP_PAD_Xa16, gioca, e nota che niente riesce più a colpirti. Scopri perché dai calcoli inshipBox. -
Rendi il colpo troppo veloce. Metti
SHOT_SPEEDa40. Conta quante rocce colpisci su dieci. Prima di rimetterlo com’era, ricava dai numeri perché succede. -
Usa tutto il colpo. Riscrivi
shotHitsRockin modo che usicollideRectscon il rettangolo intero del colpo invece dicollidePointRectcon la sua punta. Provale tutte e due e decidi quale preferisci; non c’è una risposta giusta, ed è una cosa che vale la pena sapere. -
Rendi rotonda la roccia. Dai alla roccia un cerchio invece di un riquadro: il suo centro è a
rock.x + rockWidth / 2in orizzontale e arock.y + rockHeight / 2in verticale, e un raggio di10va più o meno bene. UsacollideRectCircleper la nave ecollidePointCircleper il colpo, e disegna il cerchio indrawBoxesconoverlayCircle, 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.
-
collideRectsprende un angolo e una dimensione per ciascuno di due rettangoli e rispondetrueofalse. 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.
-
collidePointRectchiede 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
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
-
Torna al titolo. Un cabinato non resta su GAME OVER per sempre. Cerca
timerAfternella sezione Timer del Riferimento, un’altra parte del kit di gioco, e usalo inendGameper riportare lo stato aTITLEcinque secondi dopo la fine della partita. Poi premi1subito dopo la fine di una partita e controlla che il timer non rispedisca al titolo la tua nuova partita dopo tre secondi. -
Mostra le vite come navi. Disegna
shipSpriteuna volta per ogni vita nell’angolo in alto a destra conspriteDraw, invece di stampare il numero. Un ciclofordella quarta lezione, eshipWidthti dice quanto distanziarle. -
Salva più di un numero. Aggiungi
saveSet("gamesPlayed", saveGet("gamesPlayed", 0) + 1)astartGame, e stampalo sulla schermata del titolo. Esci, eseguilo di nuovo e guarda che se lo ricorda. -
Trova il file e rompilo. Apri
data/rocks/save.jsonnel 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. -
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, esaveClearnon 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.
-
onOverlayUpdatedecide 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.
-
saveSetconserva un valore sotto una chiave, esaveGetlo rilegge in un avvio successivo. -
saveFlushscrive 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. -
saveGetsenza valore predefinito rispondenilquando non è stato salvato niente, enilrompe il primo fotogramma su una macchina che non ha mai eseguito il tuo gioco. -
Quando mescoli
andeor, 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
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
-
Fai una grafica migliore. Se hai un programma di disegno, fai un
marquee.pngcome si deve: una striscia larga con ROCKS scritto a lettere grandi. Mettilo al posto dello screenshot e guarda di nuovo il menu. -
Dai un games.dat a Dodge. Scrivi un
games.datnella tua cartelladodgedella settima lezione e avvia il menu. Adesso i giochi sono due, in ordine di titolo. Poi cambia ilTITLEdi Rocks inAsteroid Fielde guardalo salire sopra Dodge: l’elenco è ordinato per titolo, non per cartella. -
Rompi games.dat per il menu. Cancella una delle graffe di chiusura nel
games.datdirockse avvia il menu. Il tuo gioco è sparito dall’elenco, e il terminale dice perché. Rimettila a posto. -
Sbaglia SCRIPT. Metti
CANVAS_Xa1280eCANVAS_Ya720, ed eseguiSinge rocks. Il campo di gioco è più largo. Ora cambiaSCRIPTinrocks.singeed 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. -
Trova il tuo salvataggio. Avvia il gioco dal menu, fai un punteggio record, esci tornando al menu ed esci dal menu. Esegui
Singe rockse guarda il titolo. Poi cerca indata/rocksil 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 cartellaSingedel 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 elencoGAMES, e ogni voce è un gioco. -
A una voce servono
TITLEeSCRIPTe nient’altro; i percorsi al suo interno partono dalla cartella sopra ilgames.dat. -
CABINET,MARQUEE,YEAR,GENRE,DEVELOPER,PUBLISHEReDESCRIPTIONsono quello che il menu mostra al giocatore, e F12 fa un’immagine che puoi usare per i primi due. -
REQUIRESdice 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.shoMenu.batavvia 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 ungames.datche 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
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
-
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.
-
Procedi un passo alla volta. Cambia
discSkipForward(30)indiscSkipForward(1)e tieni premuto il tasto freccia destra. Ora cambiastopAtin un fotogramma a metà del drago e usadiscSearche il tasto freccia per atterrarci esattamente. -
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. -
Chiedi un fotogramma che non c’è. Cambia la riga di
SWITCH_RIGHTindiscSkipToFrame(100000). Non va in crash. Leggi la voce didiscSkipToFramenel Riferimento e trova la frase che dice perché. -
Giocaci senza il video. Esegui
Singe -R moviee 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
discnon 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.
-
discGetFramechiede dove si trova il disco;discGetFrameCountdice quanti fotogrammi ci sono;discGetStatedice che cosa sta facendo il disco. -
discPlay,discPauseediscStoplo comandano.discSearchva a un fotogramma e si mette in pausa;discSkipToFrameva a un fotogramma e riproduce. -
Un disco che arriva in fondo riparte dal fotogramma zero senza dirtelo.
-
Senza disco ogni chiamata
discè innocua, eSINGE_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
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:
-
Fai partire il filmato dall’inizio e riproducilo fino al fotogramma 120.
-
Fermati lì e chiedi al giocatore di premere la barra spaziatrice.
-
Quando la preme, continua a riprodurre fino al fotogramma 300.
-
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
-
Aggiungi un passo. Dopo
waitForButton, fai invece tornare indietro il filmato:discSkipToFrame(0), poiplayTo(60), poi continua come prima. Due righe nuove in un posto solo, e nient’altro nello script deve saperlo. -
Aggiungi lo stesso passo all’altro. Ora fallo in
events.singe. Conta quanti punti hai dovuto toccare. -
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. UsadiscGetFramee ricordati da dove sei partito. -
Togli uno yield. Cancella il
singeYield()dentroplayToed eseguilo. Tieniti pronto a chiudere il terminale, perché nient’altro lo ferma. Ora rimettilo e cancella invecedrawFrame(), e da quello che vedi capisci perché il contatore dei fotogrammi si ferma ma il filmato no. -
Fanne un ciclo. Metti tutta
singeMaindentrowhile true do … endcosì 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
singeMainoppure 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
whilecon dentro unsingeYield. 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
onOverlayUpdatequando esistesingeMain. -
Tutte le altre callback vengono ancora chiamate, quindi eventi e passi si mescolano liberamente.
-
Quando
singeMainfinisce, 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
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 |
|---|---|---|
|
da 0 a 119 |
Fuoco, e il drago atterra. Sinistra o destra? |
|
da 120 a 259 |
Sputa fuoco. Ti abbassi a sinistra o corri a destra? |
|
da 260 a 339 |
Vieni mangiato. Perdi una vita. |
|
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:
firstelast-
I fotogrammi tra cui va la scena.
ask-
Il fotogramma in cui compare la domanda. Il giocatore ha da
askalastper rispondere, e questo è il timer. prompt-
Che cosa dice la domanda.
lefteright-
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
-
Aggiungi un finale. Da' a
escapeuna domanda e una seconda scena finale che riusa fotogrammi da qualche parte del filmato. Cambia solo la tabella. -
Rendilo equo. Abbassa
askin 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. -
Sposta il checkpoint. Cambia il
goesTodipitin"sunset"e giocaci. Poi pensa a che cosa succede se un giocatore muore inarrive— e se la scena della morte dovrebbe sapere da dove è arrivata invece di sentirselo dire. -
Conta quello che il giocatore ha visto. Aggiungi una tabella accanto a
scenesche 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». -
Rompi la mappa. Cambia il
leftdiarrivein"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.leftescene["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 —
deathin tre record su quattro — mantiene la descrizione breve e onesta. -
Confrontare
nilcon un numero è un errore, eandè 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
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
-
Sposta un bersaglio. Cambia la
xdel terzo bersaglio in680ed 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. -
Rendi i bersagli più facili. Cambia
TARGET_SIZEin140. 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. -
Tieni il conto della precisione. Aggiungi una riga che stampa
hitscome percentuale dishots. Proteggiti dalla divisione per zero prima del primo colpo, e scopri che cosa stampa Lua se non lo fai. -
Fai in modo che un bersaglio ti punisca. Aggiungi un campo
penalty = truea 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. -
Togli il
returndal ciclo inonInputPressed, 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.
-
onInputPressedriceve un secondo argomento che dice quale mouse o pistola ha sparato, ed ènilquando 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 bti dàbquandoaè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
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
-
Rendilo più difficile. Cambia il
lastdella prima mossa da105a75. Quindici fotogrammi sono mezzo secondo. Giocaci e scopri se ce la fai. -
Aggiungi una mossa. Metti una quinta riga nella tabella con una finestra tra i fotogrammi
370e400, e portaLAST_FRAMEa418. Non dovresti dover toccare nessun’altra riga. Se devi farlo, qualcosa nel codice sa troppo della tabella. -
Dai punti alla velocità. Assegna più punti a chi risponde presto. In
onInputPressed, dove viene premiata la risposta giusta, calcolaleftespana partire damoveediscGetFrame()come fa l’indicatore, e aggiungiRIGHT_SCORE * left // spaninvece diRIGHT_SCORE. Decidi se così il gioco diventa migliore o solo più movimentato. -
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. -
Due richieste insieme. Sovrapponi le finestre di due mosse e guarda che cosa succede.
moveAtrestituisce 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.
-
nilin 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
returnanticipato per i casi che non ti interessano — evitano di annidare il lavoro vero. -
//divide e butta via la parte frazionaria; moltiplica prima di dividere. -
overlayBoxdisegna un contorno, quindi una barra piena è una pila di chiamate aoverlayLine. -
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
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
-
Cambia la qualità. Metti
FONT_QUALITY_SOLIDnella riga difontQualitye guarda la curva dellaSinASTEROID. Poi provaFONT_QUALITY_SHADEDe guarda che cosa succede dietro ogni stringa. -
Fai diventare giallo il suggerimento. Sposta la riga
colorForeground(140, 200, 255)da soprafontToSpritea subito sopra lospriteDrawche disegnahintImage, e cambia i numeri. Capisci perché non succede niente. Poi rimettila a posto, fai invece il suggerimento bianco, e fallo diventare giallo conspriteSetTintsubito prima che venga disegnato. -
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. -
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 chefontPrintti risparmia quando lo lasci fare. Poi togli anche lospriteUnloadinrenderScore, lascialo girare per un minuto, e guarda la memoria che usa il tuo gioco. -
Stampa un orologio in millisecondi. Cambia la riga dell’orologio perché stampi
singeGetTicks()senza il// 1000. Funziona ancora; adesso è una stringa chefontPrintnon ha mai visto, a ogni fotogramma. Su una macchina lenta, è questo il tipo di testo che costa. -
Usa un font tuo. Trova un
.ttfsul tuo computer, copialo accanto al tuo script e caricalo conDIR .. "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
-
fontLoadapre un file TrueType a una dimensione in punti fissa e restituisce un handle. Una dimensione, un handle. -
Caricare un font lo seleziona;
fontSelectsceglie tra i font caricati. -
fontPrintconta in pixel eoverlayPrintconta in celle di carattere. -
Il colore non è un argomento.
colorForegroundè un’impostazione: impostala, poi disegna. -
fontQualitysceglie come vengono rasterizzate le lettere, eFONT_QUALITY_BLENDEDè la risposta normale. -
fontPrintsi tiene quello che disegna, quindi stampare lo stesso testo a ogni fotogramma costa poco; quello che costa è il testo diverso a ogni fotogramma. -
fontToSpritedisegna dentro uno sprite, chespriteGetWidthmisura e le chiamatesprite*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.
-
colorForegroundarriva al testo quando viene creato, mai a uno sprite quando viene disegnato;spriteSetTintè il modo per ricolorare uno sprite dopo. -
fontUnloadlibera 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
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
-
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. -
Cambiagli stile. Nel blocco
<style>, cambia#frameinwidth: 260dp; margin: 20dp;e guarda il pannello spostarsi e il testo andare a capo di nuovo da solo. -
Togli il
guiSetInput(gui, true)inopenMenu. La pagina compare ancora. Capisci, solo guardando lo schermo, che cosa hai perso. -
Lascia la pagina sempre visibile. Cancella le chiamate a
guiHide, cambia entrambe le chiamateguiSetInput(gui, false)intruee 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). -
Metti il punteggio sulla pagina invece che nell’HUD. Chiama
guiSetValueperscorea ogni fotogramma invece che solo inopenMenu, e cancella la rigafontPrint. 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;
guiNewne crea una eguiDeletela libera. -
guiLoadmette un documento RML in una GUI e lo mostra;guiHide,guiShoweguiCloselo gestiscono in seguito. -
guiDrawcompone la GUI sopra l’overlay per un fotogramma, quindi va inonOverlayUpdatecome ogni altra chiamata di disegno. -
Una GUI nuova si limita a mostrare; è
guiSetInputa renderla utilizzabile. -
guiSetHandleresegue la tua funzione quando un elemento viene cliccato o cambiato,guiSetValuescrive dentro un elemento eguiGetValuene 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
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 dasrtPosition, 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
-
Aggiungi una quarta battuta a
subtitles.srt, tra gli undici e i tredici secondi. Salva ed esegui. Poi mettila fuori ordine, come battuta99, per prima nel file, e verifica che funzioni ancora. -
Dai a una battuta una marca temporale sbagliata — scrivi
00:00:05.500con 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. -
Cambia il loro stile. Nel tuo
subtitle.rcss— la copia accanto al tuo script, non quella inSinge— cambia.cue .textin 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. -
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.
-
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 consaveSet, 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. -
srtLoadtrasforma 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
falsequando non riesce, anche quando non c’è un disco. Controlla la risposta. -
srtEnableli accende, e uno script parte sempre con i sottotitoli spenti. -
srtPositionli colloca a una percentuale dell’altezza dell’immagine, contata dall’alto, da1a95. -
srtCleartoglie quello che si vede, eoverlayBannercondivide lo stesso documento. -
srtLoadTracklegge i sottotitoli dal file video stesso, quando li contiene. -
Singe riscrive la sua cartella
Singea ogni avvio, quindi per cambiare lo stile dei sottotitoli copisubtitle.rmlesubtitle.rcssaccanto 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
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
-
Sposta la telecamera. Cambia
nodeSetPosition(camera, 0, 2, 7)in(0, 8, 7), poi(7, 2, 7), poi(0, 0.2, 7). Ogni voltanodeLookAttiene il cubo al centro, quindi cambiando un solo numero ottieni un’angolazione diversa della stessa scena. -
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. -
Metti un secondo cubo. Copia le due righe che hanno creato il cubo, rinomina la variabile in
mark, e daglinodeSetPosition(mark, 3, 0, 0)enodeSetScale(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. -
Condividi la mesh. Invece di chiamare
meshBoxdue 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. -
Appendi la telecamera al cubo. Tieni il secondo cubo del passo precedente, altrimenti non resterà niente rispetto a cui vedere il movimento. Poi cerca
nodeSetParentnel 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.
-
nodeSetPositionenodeSetRotationimpostano un valore direttamente;nodeMoveenodeRotatelo cambiano di una certa quantità. -
Qualsiasi nodo può essere la telecamera.
nodeLookAtla punta ecameraSetla sceglie. -
Il campo visivo in
cameraSetPerspectivecambia 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
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
-
Spegni le luci. Commenta tutto il blocco
sunmettendo--all’inizio di ogni riga, ed eseguilo. Poi fai lo stesso consceneSetAmbient. Ricordati che aspetto ha, perché un giorno succederà senza che tu lo voglia. -
Sposta il sole. Cambia
nodeLookAt(sun, 0, 1.5, 0)innodeLookAt(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. -
Scalda la torcia. Alza l’intensità della luce puntiforme da
14a60e abbassa la sua portata a4. Poi spostala in(0, 6, 0), sopra il drago. Una luce puntiforme è una lampadina, e stai scegliendo dove appenderla. -
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. -
Trova un’altra parte. Le parti del drago si chiamano
head,jaw,neck,tail,body,crest,hornL,hornR,wingL,wingR,foreLegL,foreLegR,hindLegLehindLegR. Fai ondeggiare la coda con un suomath.sina una velocità diversa da quella delle ali. Poi provanodeFind("wings", dragon)e guarda che cosa fa un nome sbagliato quando passi quelnildritto anodeSetRotation.
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
-
modelLoadlegge un.glbuna volta;modelInstancene 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
nodeSetScalesull’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é
lightSetShadownon le accende, e ognuna ha un costo. -
nodeFindraggiunge una parte di un modello con il nome che ha nel file. -
modelGetAnimationsdice 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
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_STATICnon 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_DYNAMICviene 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_KINEMATICva 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
-
Cambia il mondo. Aggiungi
physicsSetGravity(0, -1.62, 0)vicino all’inizio e spara di nuovo. Poi prova0, -30, 0. Le stesse casse, un altro pianeta, una riga. -
Cambia la palla. Rendi la palla dieci volte più pesante con
bodySetMass(ball, 30), poi dieci volte più leggera con0.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. -
Fai le casse di ghiaccio. Aggiungi
bodySetFriction(crate, 0.02)incrateAt, 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. -
Sbaglia apposta la forma. In
crateAt, cambia le dimensioni del corpo in2, 2, 2lasciando la mesh a0.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. -
Conta i punti come si deve. Usa
bodyIsRestingsu 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.
-
bodySetVelocitysostituisce il moto di un corpo,bodyApplyImpulseè un colpo, ebodyApplyForceè una spinta che dura. -
Non impostare la posizione di un nodo dinamico; eliminalo e creane uno nuovo quando devi farlo ripartire da capo.
-
onCollisionsegnala ogni nuovo contatto con il suo punto e la sua velocità, e un corpo trigger segnala arrivi e partenze tramiteonTrigger. -
bodyIsRestingti dice quando tutto si è fermato, che di solito è quando un turno è finito. -
physicsSetDebugdisegna 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
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
-
Trasforma lo scarico in fumo. Cambia
emitterSetBlend(exhaust, PARTICLE_ADD)inPARTICLE_ALPHA, imposta il colore su un grigio che sfuma in un grigio trasparente, e fallo crescere invece di rimpicciolire conemitterSetSize(exhaust, 3, 14). Tre righe hanno fatto una macchina diversa. -
Togli la resistenza all’esplosione. Cancella la riga di
emitterSetDrage confronta. Poi rimetti la resistenza e togli invece la gravità. Una delle due sembra un fuoco d’artificio e l’altra sembra un incidente. -
Allarga lo scarico. Imposta
emitterSetSpread(exhaust, 180). La nave smette di sembrare dotata di un motore. L’apertura lavora più di quanto pensi. -
Una raffica da mille. Cambia
emitterBurst(boom, 140)inemitterBurst(boom, 1000)e guarda il conteggio sullo schermo. Non arriverà a mille. Capisci daemitterSetMaxperché no, poi alza la riserva e fai le scintille quattro volte più grandi, e guarda che cosa succede alla frequenza dei fotogrammi. -
Fai esplodere dove la nave non c’è. Metti
emitterSetPosition(boom, 40, 60)inexplodeal 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.
-
emitterNewsenza 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.
-
emitterStartemette un flusso fino aemitterStop;emitterBurstlancia una manciata tutta in una volta. Gli effetti continui sono flussi, quelli momentanei sono raffiche. -
emitterStoplascia finire le particelle vive;emitterClearle uccide subito. -
Un emettitore bidimensionale si sposta con
emitterSetPositiona ogni fotogramma e si disegna conemitterDrawa 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.
-
emitterSetMaxfissa il limite della riserva, eemitterGetCountti 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
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
-
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)eaddWall(6.5, 0, 7, 0.6). Eseguilo e guarda che cosa mostranavDrawprima di premere qualsiasi cosa. Poi manda la scatola dall’altra parte e guarda che cosa fa. -
Fai ingrassare tutti. Imposta
AGENT_RADIUSa2.0ed 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. -
Mandala dove c’è il mouse. Prendi il punto sotto il puntatore del mouse con
sceneUnproject, agganciale alla mesh connavNeareste manda lì la scatola quando premi il pulsante.navNearestche restituiscenilè il caso che devi gestire, e succede ogni volta che il puntatore è fuori dal pavimento. -
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. -
Precalcolala una volta sola. Chiama
navSave(nav, "room.nav")doponavBuild, poi sostituiscinavNew, le chiamate anavAddNodeenavBuildcon un uniconavLoad("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.
-
navNewdescrive il personaggio a cui è destinata la mesh,navAddNodeconsegna la geometria del livello enavBuildla precalcola. Dopo il precalcolo non si può aggiungere altro. -
navSaveenavLoadtengono una mesh precalcolata in un file, così il giocatore non deve mai aspettarla. -
navDrawti mostra la mesh, ed è la prima cosa da guardare quando un personaggio si comporta in modo strano. -
navAgentNewaffida un nodo al motore perché lo faccia camminare; da quel momento non spostare tu quel nodo. -
navAgentMoveToimposta una destinazione e restituiscefalsequando non c’è modo di arrivarci. Gestirlo è compito tuo, e succede spesso. -
onNavArrivedviene chiamata una volta quando un agente raggiunge la sua destinazione, e le viene detto quale agente. -
navPathrisponde alla stessa domanda senza muovere nessuno, enilvuol 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
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.
soundSetVolumenon tocca mai la musica emusicSetVolumenon 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
-
Fallo ripetere quattro volte invece che all’infinito. Cambia
musicPlay(theme, -1)inmusicPlay(theme, 3)e conta. Il numero è quante volte si ripete, non quante volte suona. -
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 provamusicStop(theme, 100). -
Mostra il canale. In
onMidiMessage, ricava il canale con(status & 0x0F) + 1e 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. -
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. -
Suona la risposta. Quando il giocatore azzecca una nota, fai suonare al gioco un piccolo accordo di risposta con tre chiamate a
midiNoteOna 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
0a128e quello degli effetti da0a63, 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
singeSetAudioDelaycorregge 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.
-
onMidiMessageti passa i byte grezzi. I quattro bit alti distatussono il tipo, i quattro bassi sono il canale, e un note on con velocity zero vuol dire note off. -
Ogni
midiNoteOnha bisogno di unmidiNoteOff, e un timer è il modo per abbinarli. -
Su una macchina senza MIDI ogni chiamata risponde
falseo 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
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 unnamee unvalue; -
result.standing, ilvaluedi questo giocatore, il suoranke il numero diplayerssulla 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
-
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. -
Cancella l’id. Togli
GAME_IDdal tuogames.dated eseguilo di nuovo. Il messaggio cambia. Rimettilo. -
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
standingse serve. -
Dai un nome alla classifica.
scoreSubmit(score, "reaction")escoreBoard(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. -
Rendi visibile l’attesa. Tra la chiamata a
scoreBoarde 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_IDingames.dat, un UUID che non deve cambiare mai.singeGetGameId()lo legge. -
scoreSubmitmette 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. -
scoreBoardconsegna 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 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
-
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. -
Ignora le false partenze. Aggiungi
WHERE score > 0alla domanda delle prove migliori, traFROM runseORDER BY. Poi conta le false partenze in ogni stage con una domanda tutta tua. -
Aggiungi uno stage. Apri
stages.dbin 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. -
Azzera lo storico.
runs:exec("DELETE FROM runs")svuota la tabella. Mettilo su un pulsante, chiamarefreshsubito dopo, e guarda tutto tornare a zero. È il «reset dei punteggi record» di un menu di servizio. -
Scrivi mille righe. Ripeti
recordmille volte in un ciclo e misura il tempo consingeGetTicks. Poi mettiruns:exec("BEGIN")prima del ciclo eruns: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.openapre un file e lo crea se manca. -
Quello che il gioco scrive va in
singeGetDataPath(). Quello che distribuisci va nella tua cartella, aperto consqlite3.OPEN_READONLY. -
CREATE TABLE IF NOT EXISTSsi può eseguire senza rischi ogni volta che il gioco parte. -
I valori entrano attraverso
prepare,bind_values,stepereset, mai incollando stringhe dentro l’SQL. -
nrowsrestituisce le righe come tabelle;urowsrestituisce direttamente le colonne. -
ORDER BY,LIMIT,GROUP BY,MAXeCOUNTrispondono alle domande per cui altrimenti scriveresti dei cicli. -
Chiedi quando la risposta può cambiare, non a ogni fotogramma.
-
In
onShutdownsi 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
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:
-
una cartella sciolta con il nome del file senza estensione —
MyGame/accanto aMyGame.game; -
la cartella dei dati del gioco, sotto
files/, che è dove è finito tutto ciò che il gioco scrive; -
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:
-
Estrai la versione in una cartella vuota e leggi l’elenco dei file.
-
Copia solo il file
.gamein un’altra cartella, con una copia nuova di Singe e nient’altro, e avvialo dal menu come farà un giocatore. -
Cancella la cartella
datadi 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. -
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
-
Impacchettalo. Metti questo script nella cartella del tuo gioco, esegui
--packe avvia il file.game. Poi estrailo in una cartella vuota e leggi l’elenco di quello che è uscito. -
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.
-
Crea una patch. Cambia la versione in
1.0.3, metti solo lo script in una cartellafixes, impacchettala come.patche applicala al gioco che hai già creato. Controlla la versione sullo schermo. -
Rompi l’impacchettatore. Rinomina per un momento il tuo
games.date prova a impacchettare. Poi rimettilo a posto, fai puntare uno dei suoi nomiSCRIPTa un file che non c’è, e riprova. Due rifiuti diversi, entrambi prima che venga scritto qualunque cosa. -
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.gametrasforma 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
DIRe scrivi solo sottosingeGetDataPath(), o il tuo gioco funzionerà da sciolto e fallirà da impacchettato. -
--patchsostituisce dei file in un gioco pubblicato con un’unica transazione;--unpackriscrive fuori tutto quanto. -
L’impacchettatore rifiuta i file del motore, i nomi in conflitto e un
games.datche 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
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:
-
Modalità attract. Non c’è nessuno. La macchina mostra che cos’è, fa lampeggiare
INSERT COINe non chiede niente. -
Credito. Un gettone arriva come
SWITCH_COIN1. I gettoni diventano crediti al cambio deciso dal gestore — non sempre uno a uno. -
Partita.
SWITCH_START1spende un credito e fa partire il gioco. -
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
-
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.
-
Gioca gratis. Attiva il free play e controlla che Start funzioni senza gettoni e che i crediti non vadano sotto zero.
-
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. -
Ruota lo schermo. Avvialo con
--rotate=90e 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. -
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.cfgassegna tasti, pulsanti del controller e direzioni della levetta ai nomiSWITCH_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
--rotateruota 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.