Sei giochi portatili per l'ESP32 e lo XIAO ESP32-S3, giocabili nel browser

Uno schermo ILI9341 da 2,4 pollici, un D-pad fatto di quattro pulsanti e altri due pulsanti per A e B: ecco una console portatile, e un ESP32 è più che sufficiente per farla funzionare. Abbiamo creato cinque giochi per quel layout, poi un sesto, Skythread, per una console portatile più grande con un analogico, e li abbiamo messi tutti e sei nella galleria di esempi di Velxio. Ognuno è uno sketch Arduino, e ognuno gira nel tuo browser: premi Run e gioca, senza scheda, senza schermo, senza saldature.

Il primo, Doom, è arrivato per primo e gira sul classico ESP32. I quattro successivi girano sul Seeed Studio XIAO ESP32-S3, la scheda grande quanto un pollice del nostro partner Seeed, e condividono un piccolo motore. L’ultimo, Skythread, gira sullo XIAO ESP32-S3 Sense, lo stesso chip con 8 MB di PSRAM, che gli servono per tenere in memoria un intero paesaggio. Questo articolo spiega come si gioca a ciascuno e come funziona al suo interno.

Come giocarci in Velxio

1. Apri uno qualsiasi dei giochi dalla tabella qui sopra. Lo sketch, le librerie e il circuito si caricano insieme.
2. Premi Run. Velxio compila lo sketch e lo avvia. La prima compilazione di uno sketch richiede fino a un minuto; dopo arriva dalla cache di build.
3. Ogni gioco inizia con una demo in attract mode che si gioca da sola. Premi un tasto o un pulsante qualsiasi per prendere il controllo.
4. Gioca con la tastiera: le frecce sono il D-pad, Z è A e X è B. Ogni pulsante sulla tela mostra il suo tasto in un piccolo keycap. Puoi anche cliccare i pulsanti con il mouse e tenerne uno premuto per mantenerlo pigiato. Skythread ha un analogico e più pulsanti; i suoi controlli sono nella sua sezione qui sotto.
5. Apri il monitor Serial per vedere il log del gioco: una riga STAT con il frame rate e una riga EVT per ogni uccisione, livello, oggetto raccolto e morte. Skythread stampa una propria riga ogni due secondi, con il frame rate, il tempo impiegato da ogni frame per essere disegnato e inviato, e il punteggio.

Qualsiasi pulsante in Velxio può essere azionato dalla tastiera, non solo questi. Fai clic con il tasto destro su un pulsante e usa la scheda Keyboard control: cliccala, premi un tasto e da quel momento tenere premuto quel tasto preme il pulsante mentre la simulazione è in esecuzione.

Il simulatore esegue il firmware stesso, compilato per il chip reale: Velxio emula l’ESP32 e l’ESP32-S3 istruzione per istruzione, nel tuo browser, e disegna tutto ciò che lo sketch invia all’ILI9341.

La console portatile

Lo XIAO ha solo 11 pin GPIO, e uno schermo e sei pulsanti ne richiedono dodici. Il trucco è che lo schermo non ha bisogno di due delle sue linee abituali: non viene mai letto nulla da esso, quindi MISO resta scollegato, e il suo pin di reset è collegato a 3,3 V così si resetta insieme alla scheda. Questo lascia esattamente il numero giusto.

Ogni pulsante collega il suo pin a massa. Lo sketch attiva le resistenze di pull-up interne del chip con pinMode(pin, INPUT_PULLUP), così un pin legge HIGH quando il pulsante è rilasciato e LOW quando è premuto. Non servono resistenze, né sulla tela né su una breadboard reale. Doom usa la stessa idea sul più grande ESP32 DevKit, con i suoi pin (sono elencati nella sua sezione qui sotto).

Perché lo XIAO ESP32-S3

I quattro giochi per XIAO disegnano l’intera immagine prima in memoria e poi la inviano allo schermo in un colpo solo. Un’immagine di 320 x 240 a due byte per pixel è di 153.600 byte, e deve stare in un unico blocco contiguo di RAM.

È qui che i due chip differiscono. Abbiamo stampato il più grande blocco libero da uno sketch su ciascuno: 110.592 byte sul classico ESP32 e 278.528 byte sull’ESP32-S3. L’S3 può contenere l’intero frame con spazio in abbondanza; il classico ESP32 non può, ed è per questo che Doom disegna la sua immagine una colonna alla volta (ne parliamo più avanti).

L’S3 è anche il più veloce dei due nel simulatore. Con lo stesso benchmark del frame buffer su entrambe le schede, il motore in-browser di Velxio ha eseguito l’ESP32 a 81-90 milioni di istruzioni al secondo e l’ESP32-S3 a 96-106 milioni, e l’S3 ha spinto 33 frame completi al secondo contro i 31 dell’ESP32.

Un motore per quattro giochi

I quattro sketch per XIAO iniziano con le stesse 200 righe: il motore. Gestisce il frame buffer, i pulsanti, una manciata di funzioni di disegno e il ciclo dei frame.

Disegnare in RAM significa che l’ordine non conta. Un gioco può dipingere il cielo, poi le colline, poi gli aerei, poi le esplosioni sopra, e lo schermo vede solo l’immagine finita, così nulla sfarfalla. Inviarla sono tre chiamate alla libreria Adafruit ILI9341:

static void present() {
  tft.startWrite();
  tft.setAddrWindow(0, 0, SCR_W, SCR_H);  // the whole 320 x 240 screen
  tft.writePixels(fb, SCR_W * SCR_H);     // 153,600 bytes in one burst
  tft.endWrite();
}

A 40 MHz quei 153.600 byte richiedono circa 31 ms sui fili SPI, quindi il solo trasferimento fissa il limite vicino ai 30 frame al secondo. Il resto del frame, la logica del gioco e il disegno, deve stare in ciò che rimane, ed è per questo che le funzioni di disegno sono semplici: rettangoli pieni, linee, cerchi, testo nel font 5 x 7 fornito con Adafruit GFX e sprite.

Gli sprite sono scritti come testo, un carattere per pixel, con . per i pixel trasparenti e una palette di 128 voci per il resto. Questo è il robot di Gear Hop:

"........a.......",
"....mmmmmmmm....",
"...mMMMMMMMMm...",
"...mMllMMllMm...",   // l = the eyes, light cyan
"...mMllMMllMm...",
"...mMMMMMMMMm...",
"....mmmrrmmm....",   // r = the red mouth

Niente in questi giochi proviene da un file immagine. Le tessere della mappa, le texture e gli effetti sono disegnati dal codice in RAM all’avvio della scheda, così ogni sketch è testo semplice che puoi leggere e modificare nell’editor.

Sky Duel: un combattimento aereo con un modello di volo

Piloti un biplano sopra un mondo largo quattro schermate che si avvolge su se stesso: vola oltre il bordo destro e rientri da sinistra. Uno squadrone rosso ti dà la caccia, cannoni antiaerei e camion attendono a terra, e ogni ondata porta un aereo nemico in più.

Come si gioca. Punta il D-pad dove vuoi volare, diagonali incluse; l’aereo vira verso quella direzione. Tieni premuto A per le mitragliatrici e tocca B per sganciare una bomba (sei per ondata). Le bombe sono l’unico modo per distruggere gli obiettivi a terra. Il radar in alto mostra il mondo intero, così puoi trovare gli aerei fuori schermo.

Come funziona. L’aereo non si muove a velocità fissa. Ogni frame lo sketch esegue un piccolo modello di volo:

La velocità tende verso un valore di crociera, ma salire costa velocità e scendere ne guadagna, in proporzione all’angolo. Tira su dritto per troppo tempo e l’aereo scende sotto la velocità di stallo: il muso cade verso terra da solo, e devi scendere in picchiata per tornare a volare. I piloti nemici usano lo stesso modello, con lo stesso stallo, ed è questo che lo rende un combattimento aereo invece di un tiro al bersaglio.

L’aereo è un singolo sprite di 16 x 16 pixel rivolto a destra. All’avvio lo sketch lo ruota in 32 direzioni e le memorizza tutte, rispecchiando quelle che puntano a sinistra così l’aereo non vola capovolto. Disegnare un aereo è quindi una ricerca in tabella, ingrandita due volte sullo schermo. I nemici sterzano verso un punto appena davanti a te, sparano quando sei davanti ai loro cannoni e si allontanano dopo un passaggio ravvicinato per non speronarti.

XIAO Quest: un piccolo GDR

Un eroe, un villaggio, una foresta e una caverna. L’anziano presso la fontana ti dice che il Re delle Ombre ha portato il cristallo del villaggio nella vecchia caverna e ti dà la chiave del cancello che blocca la strada. Nella foresta e nella caverna i mostri attaccano e li combatti a turni.

Come si gioca. Cammina con il D-pad. A parla con le persone, legge i cartelli, apre i forzieri e conferma; B mostra le tue statistiche e i tuoi oggetti. La fontana ti cura, il mercante vende pozioni per 10 monete d’oro, e tre forzieri contengono due pozioni, una spada di ferro e un anello d’argento. In battaglia, scegli con il D-pad e conferma con A: attacca, lancia fuoco (3 MP, danno doppio, ignora la difesa), bevi una pozione o fuggi.

Come funziona. Il gioco è una piccola macchina a stati. Ogni stato ha la propria gestione degli input e il proprio disegno, e questi sono gli eventi che lo fanno passare da uno all’altro:

Le tre mappe sono 20 x 14 tile da 16 pixel, scritte nello sketch come stringhe, un carattere per tile: # è un albero, ~ l’acqua, = un sentiero, K il cancello chiuso. L’eroe si muove una tile alla volta e scivola tra le tile in 0,16 secondi, così il movimento è fluido ma le collisioni restano semplici: un passo è permesso oppure no.

Le battaglie usano piccole formule con numeri interi. Un attacco fa il tuo attacco più un tiro da 0 a 3, meno la difesa del nemico. L’esperienza porta livelli, e ogni livello aggiunge salute, magia, attacco e difesa. La caverna è buia: dopo aver disegnato la mappa, lo sketch riduce a metà luminosità ogni pixel tra 50 e 70 pixel dall’eroe e a un quarto tutto ciò che è più lontano, così porti una lanterna. Misurare la distanza di ogni pixel ha fatto scendere il frame rate da circa 27 a 16. Calcolarla una volta per riga invece, come un intervallo illuminato, uno attenuato e il resto al buio, lo riporta a circa 22.

Gear Hop: un platform

Un piccolo robot corre attraverso due livelli raccogliendo ingranaggi. Gli scarafaggi camminano a terra, i droni fluttuano in aria, le punte rivestono alcuni pavimenti, e i vuoti più ampi si possono attraversare solo su piattaforme mobili. Raggiungi la bandiera alla fine di ogni livello.

Come si gioca. Cammina con SINISTRA e DESTRA, tieni premuto B per correre, premi A per saltare. Tieni premuto A più a lungo per un salto più alto. Atterra su un nemico per schiacciarlo, e salta in un blocco ? dal basso per farne uscire un ingranaggio. Hai tre cuori; le punte e i nemici ne tolgono uno, e così anche cadere in un vuoto.

Come funziona. I livelli sono 128 x 14 tile, generati da un piccolo script e incollati nello sketch come stringhe. Il robot è una scatola di 10 x 14 pixel, e ogni frame si muove in due passi: prima lateralmente, spinto fuori da qualsiasi muro in cui finisce dentro; poi verticalmente, atterrando sul terreno, su una tavola a senso unico o su una piattaforma mobile, oppure battendo la testa su un blocco. Fare i due assi separatamente è ciò che impedisce al robot di incollarsi ai muri o di scivolare attraverso gli angoli.

Tre piccole regole rendono il salto piacevole. Un salto premuto fino a 0,12 secondi prima dell’atterraggio avviene comunque quando il robot tocca terra (un buffer di salto). Un salto premuto fino a 0,08 secondi dopo essere uscito da una sporgenza conta comunque (coyote time). E rilasciare A in anticipo riduce la velocità verso l’alto, ed è così che tenere premuto il pulsante dà un salto più alto. Due strati di colline scorrono a un quinto e a meno della metà della velocità della camera, il che dà profondità alla scena.

Circuit Defense: tower defense su una scheda elettronica

I bug strisciano su una scheda elettronica verso il chip. Costruisci componenti elettronici sulla scheda per fermarli: un LED spara un laser veloce contro un bug, un condensatore si scarica su ogni bug intorno a sé, e una bobina rallenta i bug. Ogni bug che raggiunge il chip gli costa un punto di salute, e le ondate continuano a diventare più forti.

Come si gioca. Muovi il cursore con il D-pad. B sceglie il componente, A lo costruisce, e A su un componente già costruito lo potenzia, fino al livello 3. I bug distrutti pagano monete, e ogni ondata completata paga un bonus. Il cerchio attorno al cursore mostra la portata del componente che stai per costruire.

Come funziona. I bug non seguono un percorso fisso. Camminano sulla scheda aperta, e puoi guidarli con ciò che costruisci: la pista di rame sulla scheda è sempre la rotta che prenderanno. Dietro c’è una ricerca in ampiezza, eseguita di nuovo dopo ogni costruzione:

La ricerca parte dalle celle accanto al chip, le numera 0 e si diffonde verso l’esterno: ogni vicino libero di una cella numerata riceve quel numero più uno. Al termine, ogni cella contiene la sua distanza dal chip, muri di torri inclusi. Un bug che si trova su una cella si sposta semplicemente verso un vicino con un numero più piccolo. Non c’è pianificazione del percorso per ogni bug: una sola ricerca, 260 celle, serve per tutti.

Gli stessi numeri rendono facile far rispettare l’unica regola del gioco: puoi allungare il percorso, ma mai chiuderlo. Quando costruisci, lo sketch posiziona il componente, esegue di nuovo la ricerca e guarda la cella d’ingresso. Se non ha più un numero, i bug non potrebbero passare: il componente viene rimosso e il gioco dice THAT BLOCKS THE PATH.

ESP32 Doom: uno sparatutto in prima persona

Il più vecchio dei cinque gira sul classico ESP32 DevKit. Cammini in un labirinto di muri texturizzati, spari a robot che ti inseguono e a slime che sputano acido, apri porte, raccogli kit medici e munizioni, e completi ondata dopo ondata.

Come si gioca. Il D-pad cammina e gira, A spara (tienilo premuto per il fuoco automatico), B apre la porta davanti a te, e B tenuto premuto con LEFT o RIGHT fa lo strafe. I pin sono diversi da quelli dei giochi per XIAO: UP su GPIO 32, DOWN 33, LEFT 25, RIGHT 15, A su 22, B su 21, e lo schermo sul bus VSPI dell’ESP32 (SCK 18, MOSI 23, MISO 19, CS 5, D/C 2, RST 4).

Come funziona. Doom è un raycaster, la tecnica di Wolfenstein 3D (1992): per ogni colonna dello schermo invia un raggio dal giocatore in una mappa a griglia 20 x 20 e lo ferma al primo muro. La distanza determina quanto alta viene disegnata la fetta di muro. Poiché il classico ESP32 non ha spazio per un frame completo, lo sketch costruisce una colonna alla volta in un buffer da 200 pixel, con pavimento, soffitto, muro, nemici, arma ed effetti già composti, e la invia in un’unica raffica:

I robot camminano dritti verso di te e graffiano per 5 punti salute al secondo; gli slime mantengono le distanze e sputano acido che costa 7. Un colpo centra il nemico più vicino sotto il mirino, purché nessun muro sia più vicino. Ogni nemico eliminato porta l’ondata successiva con due in più, un po’ più veloci e un po’ più resistenti.

Skythread: volo 3D su un mondo generato

Doom è 3D al chiuso. Skythread è 3D all’aperto: voli con un aliante a delta basso sopra una campagna aperta, lungo valli fluviali, oltre montagne e sopra laghi, con la nebbia verso l’orizzonte e un cielo che passa dal giorno all’ora d’oro alla notte. Anelli sospesi nell’aria ti attendono davanti, e il cronometro corre. Parti con 45 secondi, e ogni anello ne aggiunge altri. Ogni anello di fila aumenta la combo, fino a cinque volte i punti, e volare attraverso il centro di un anello vale un PERFECT. Se manchi un anello la combo ricomincia da capo; se tocchi il suolo rimbalzi, più lento e tre secondi più povero. Come gli altri, inizia con una demo che vola da sola.

Il portatile. Skythread è stato scritto per il portatile che esegue i nostri port di Metal Gear Solid e Castlevania, non per il layout a D-pad degli altri quattro: un Seeed Studio XIAO ESP32-S3 Sense, lo stesso schermo ILI9341, uno stick analogico a due assi, due pulsanti su pin propri e altri sei su un unico pin. In Velxio l’esempio si apre disposto come quel portatile: lo stick a sinistra, lo schermo al centro, i pulsanti a destra e sotto lo schermo.

Come si gioca. Guida con lo stick: clicca su di esso nella tela e usa i tasti freccia, oppure tieni premuto il mouse su una delle sue frecce. Tira indietro (giù) per salire, spingi avanti per scendere in picchiata, e a sinistra o a destra per inclinarti e girare. FIRE (Z) è un boost che consuma la barra blu, e avvia anche una partita. BRAKE (X) ti rallenta per le curve strette. START (Invio) avvia e mette in pausa, CROSS (C) avvia anch’esso una partita, SELECT (Q) torna alla demo, CIRCLE (T) cambia l’ora del giorno, TRIANGLE (W) genera un nuovo mondo e L1 (F) mostra il frame rate.

Sei pulsanti su un solo pin. Lo XIAO ha 11 pin, e lo schermo, lo stick e otto pulsanti ne richiederebbero 16. Il trucco per sei dei pulsanti è una scala di resistori. Un resistore da 10 kΩ porta D2 a 3,3 V, e ogni pulsante collega D2 a massa attraverso un resistore diverso, così ognuno forma un partitore di tensione diverso. Il pin legge 3,3 V × R / (R + 10 kΩ):

Lo sketch legge D2 con analogReadMilliVolts() e sceglie il pulsante la cui tensione è più vicina, con soglie a metà strada tra i vicini (300, 824, 1350, 1960, 2496 e 2960 mV). Velxio risolve la scala come un vero circuito: l’ultima colonna è ciò che lo sketch ha stampato sul monitor seriale quando abbiamo premuto ciascun pulsante nella tela. Una scala legge un pulsante alla volta, dato che due premuti insieme sembrano un unico pulsante con un resistore più piccolo. Ecco perché il gioco tiene FIRE e BRAKE, i due che si tengono premuti mentre si vola, su pin propri. Ignora inoltre la scala finché non l’ha vista rilasciata una volta, così un D2 lasciato scollegato non può mai premere pulsanti fantasma.

Come funziona. Il mondo viene generato all’avvio della scheda: una mappa 512 x 512 del paesaggio realizzata con rumore diamond-square, dove ogni cella occupa due byte, uno per l’altezza e uno per un colore della palette. Con una copia a metà dimensione per la distanza lontana e due frame buffer, sono circa 940 KB, ed è per questo che Skythread richiede il Sense e la sua PSRAM. In Velxio il mondo impiega 3 secondi di tempo simulato per essere costruito, e il primo frame raggiunge lo schermo 3,4 secondi dopo l’accensione.

Il disegno usa il ray casting per colonne dei giochi di volo voxel dei primi anni ‘90. Per ogni colonna dello schermo, lo sketch percorre un raggio dalla camera verso l’esterno sopra la mappa, da vicino a lontano, fino a 160 passi e 340 celle di distanza; dopo 110 celle legge invece la mappa a metà dimensione. A ogni passo trasforma l’altezza del terreno in una riga sullo schermo. Se quella riga è più alta di qualsiasi cosa disegnata finora nella colonna, riempie lo spazio con il colore di quella cella e ricorda la nuova cima:

Quella cima ricordata per colonna si chiama y-buffer. Il terreno vicino viene sempre disegnato per primo, così quello lontano può mostrarsi solo sopra di esso, e nessun pixel viene mai dipinto due volte. La nebbia è composta da 20 palette, ognuna sfumata un po’ di più verso il colore del cielo, una per fascia di distanza. L’inclinazione è una trasformazione di taglio: l’orizzonte di ogni colonna si sposta su o giù in proporzione alla sua distanza dal centro dello schermo, il che sembra un rollio. Gli anelli, l’ombra dell’aliante e il sole vengono verificati contro lo stesso y-buffer alla loro distanza, così una montagna davanti a un anello lo nasconde.

Il frame è memorizzato colonna per colonna, già nell’ordine di byte che l’ILI9341 si aspetta. Nell’indirizzamento verticale del pannello, una colonna dell’immagine del paesaggio è una delle sue righe, così l’intero frame esce in un’unica raffica. Con due frame buffer, i due core del chip lavorano contemporaneamente: un task sul core 0 invia un frame allo schermo via SPI a 40 MHz mentre il core 1 disegna il successivo.

Lo sketch controlla anche la propria velocità. Quando disegnare un frame richiede in media più di 22 ms, lancia 160 raggi invece di 320 e disegna ogni colonna larga due pixel, e torna alla larghezza piena sotto i 7 ms. Oltre i 45 ms, un caso che i suoi commenti riservano a un host lento come un simulatore nel browser, smette di sovrapporre i due core e attende che ogni frame finisca di uscire prima di disegnare il successivo, così il pannello simulato riceve sempre frame interi. In Velxio ha funzionato in quella modalità per tutto il tempo, a 160 colonne, disegnando ogni frame in 33-50 ms di tempo simulato.

Frame rate

Abbiamo misurato ogni gioco su velxio.dev in un browser Chrome headless sul nostro server, giocando per circa un minuto ciascuno.

Due numeri per gioco. Il primo è ciò che il gioco stesso riporta sul monitor seriale, dal millis() del chip: il frame rate della scheda simulata. Il secondo è quanti frame il browser ha effettivamente mostrato al secondo di tempo reale. Differiscono quando il computer che esegue la simulazione non riesce a mantenere il chip simulato a piena velocità; il tempo simulato scorre allora un po’ più lento dell’orologio da parete. I tuoi numeri dipendono dal tuo computer.

I quattro giochi 2D per XIAO girano a quasi il doppio del frame rate di Doom. Parte è il lavoro: un raycaster lancia 320 raggi e calcola pavimento e soffitto pixel per pixel. Parte è il trasferimento: un’unica raffica per frame invece di 320 piccole, ognuna con la propria finestra di indirizzamento. Skythread, l’unico che disegna un paesaggio 3D, mantiene circa 20 frame al secondo lanciando 160 raggi invece di 320, il compromesso che il suo stesso codice adotta ogni volta che disegnare un frame richiede più di 22 ms.

Rendili tuoi

Ogni gioco è un singolo sketch, e il codice è organizzato in blocchi: il motore, la grafica, lo stato del gioco, l’aggiornamento e il disegno. Alcune modifiche che richiedono un minuto:

• Sky Duel: cambia la velocità di crociera (125) o la velocità di stallo (50) in fly() e senti come cambia l’aereo.
• XIAO Quest: le mappe sono le stringhe in MAP_V, MAP_F e MAP_C; i numeri dei mostri sono nella tabella FOES.
• Gear Hop: la forza del salto è -335 in movePlayer(), la gravità è 950; prova la luna.
• Circuit Defense: aggiungi una quarta parte a TW_NAME, TW_COST e updateTowers().
• Doom: MAP_SRC è composto da 20 stringhe di 20 cifre; ogni cifra è una texture di muro, e un 9 è una porta.
• Skythread: WORLD_SEED in cima allo sketch sceglie il mondo in cui ti avvii, e PITCH_PULL_TO_CLIMB impostato a 0 fa salire lo stick quando lo spingi in avanti.

Premi Run dopo una modifica e Velxio compila lo sketch modificato, così puoi cambiare un numero e vedere il risultato pochi secondi dopo. Quando funziona come preferisci, lo stesso sketch gira su un vero XIAO ESP32-S3 con un ILI9341 e sei pulsanti collegati come sopra, e Skythread su un XIAO ESP32-S3 Sense con lo stick e i pulsanti della sua sezione.

Apri la galleria di esempi