Ho realizzato un port di Doom con Flutter e dart:ffi

1. Proviamo a compilare il codice sorgente su un sistema moderno Linux
2. Proviamo a compilare il codice sorgente su Flutter
3. Come diavolo leggo il file WAD?
4. Un solo Thread non basta
5. Ho bisogno del framebuffer
6. E ora che faccio con il framebuffer?
7. A quanto pare sono costretto a mappare gli input (e a renderli Thread Safe)
8. La palette dei colori non è un argomento banale
9. Risolviamo i bug che io stesso ho introdotto
10. Un po' di frontend: creiamo un controller comodo e funzionale
11. Compiliamo su iOS
12. Conclusioni

CAPITOLO 1 - Proviamo a compilare il codice sorgente su un sistema moderno Linux

Prima di importare il codice sorgente su Flutter, ho voluto provare a compilarlo nativamente su Linux.
Se avviene la compilazione, di sicuro avrò meno lavoro da fare all'interno dell'ambiente di Flutter.

Quindi ho clonato il progetto e ho lanciato il classico comando make. Come prevedibile non ha funzionato. Stiamo parlando di un sorgente rilasciato nel 1997, troppe cose sono cambiate nei compilatori da allora, e soprattutto i sistemi non sono più a 32 ma a 64 bit.

Occorreva mettersi un po’ a lavoro. Diciamo che i primi errori non sono stati difficili da risolvere.
Per esercizio e per forzarmi a ragionare, alcuni errori sono riuscito a risolverli da solo.
Per altri, dove indicato, ho seguito questo fantastico post sul blog Deus In Machina.
Inutile dire che senza quel post a un certo punto sarei arrivato a un punto morto, quindi ringrazio Diego Crespo per il suo utilissimo post.

Iniziamo. Primo errore.

Questo si è risolto semplicemente togliendo la s di troppo da errnos.h
La libreria errno è una standard del C, non ho idea del perchè ci fosse quella s.

Andiamo avanti.
Qui le cose si fanno più complesse.

Il pezzo di codice incriminato è questo.
Si tratta dell'inizializzazione della Struct che contiene le impostazioni di default.

Ecco una delle tante stranezze del C. Abbiamo una stringa che viene convertita in un valore intero.
Si tratta del terzo elemento della Struct, chiamato defaultvalue, che dovrebbe essere un intero.
Infatti ad esempio vediamo che il valore con chiave "mouse_sensitivity" ha come default 5.

Cosa sta facendo quella conversione? Sta convertendo l'indirizzo del primo carattere di quella stringa in un intero.
Quindi abbiamo l'intero che rappresenta un indirizzo di memoria.
Un trucchetto davvero furbo, perchè di solito gli indirizzi di memoria sono rappresentati da puntatori a un tipo. In questo modo è possibile avere sia dei valori interi reali, sia degli indirizzi di memoria che rappresentano l'inizio di una stringa.
Una soluzione che farebbe rabbrividire in molti di questi tempi, ma stiamo parlando di una codebase di più di 30 anni fa, questi trucchetti erano all'ordine del giorno.

Il problema è che un int è un valore a 32 bit, mentre un puntatore in un sistema a 64 bit è appunto grande 64 bit, quindi quel cast non può funzionare.
Occorre quindi fare in modo che il tipo di defaultvalue nella Struct sia abbastanza grande da contenere un valore a 64 bit, quindi long long (64 bit) è sufficiente. Anche tutti gli altri cast dovranno essere modificati da int a long long.
Osservazione: quelle stringhe sono definite come valore globale, non si trovano in nessuna funzione, quindi quegli indirizzi saranno validi per tutta la durata del programma.

Andiamo avanti.
A parte tanti warning assolutamente ignorabili, tutto il codice è stato compilato correttamente (almeno in apparenza), c’è solo un problema con il linker. Quello che si capisce è che si tratta di un problema sul file i_sound.c, anche se non ci viene detto null’altro.
Ci ho messo un po’ a capire il problema, fallendo miseramente. Da questo punto in poi ammetto di aver seguito pedissequamente il blog di Diego, quindi se volete approfondire questo aspetto vi rimando al suo articolo.

Alla fine il codice è stato compilato su Linux e il gioco è partito.

Questa sarà la base da cui iniziare su Flutter.

CAPITOLO 2 - Proviamo a compilare il codice sorgente su Flutter

flutterdoom/android/app/src/main/linuxdoom-1.10/doomtype.h:42:10:
fatal error: 'values.h' file not found
   42 | #include <values.h>
      |          ^~~~~~~~~~
1 error generated.

A quanto pare values.h era il vecchio nome di limits.h, quindi effettuo una sostituzione.
Ok funziona, adesso l’errore è un altro.

flutterdoom/android/app/src/main/linuxdoom-1.10/l_net.c:76:17:
error: use of undeclared identifier 'IPPORT_USERRESERVED'
   76 | int   DOOMPORT =  (IPPORT_USERRESERVED +0x1d );

Manca IPPORT_USERRESERVED, che non è definita nelle librerie di Android. Aggiungo la definizione nel file i_net.h, il valore dovrebbe essere 5000 (ho cercato online).
Non mi servirà a nulla in ogni caso, perchè il supporto di rete ovviamente non ci sarà.

Altro flutter run, altri errori (oh boy sarà lunga).

flutterdoom/android/app/src/main/linuxdoom-1.10/m_fixed.c:63:19:
error: use of undeclared identifier 'MININT'
     63 |         return (a^b)<0 ? MININT : MAXINT;
        |                          ^

flutterdoom/android/app/src/main/linuxdoom-1.10/m_fixed.c:63:28:
error: use of undeclared identifier 'MAXINT'
     63 |         return (a^b)<0 ? MININT : MAXINT;
        |                                   ^

MININT e MAXINT erano definiti nel vecchio values.h e non sono presenti in limits.h (dove invece sono presenti INT_MIN e INT_MAX).
Quindi torno in doomtype.h e li aggiungo.
Faccio la stessa cosa su m_bbox.h

flutterdoom/android/app/src/main/linuxdoom-1.10/am_map.c:786:12:
error: type specifier missing, defaults to 'int'; ISO C99 and later do not support implicit int [-Wimplicit-int]
    786 |     static nexttic = 0;
        |     ~~~~~~ ^
        |     int

flutterdoom/android/app/src/main/linuxdoom-1.10/am_map.c:859:14:
error: type specifier missing, defaults to 'int'; ISO C99 and later do not support implicit int [-Wimplicit-int]
859 |     register    outcode1 = 0;
    |     ~~~~~~~~    ^
    |     int
    
flutterdoom/android/app/src/main/linuxdoom-1.10/am_map.c:860:14:
error: type specifier missing, defaults to 'int'; ISO C99 and later do not support implicit int [-Wimplicit-int]
860 |     register    outcode2 = 0;
    |     ~~~~~~~~    ^
    |     int

flutterdoom/android/app/src/main/linuxdoom-1.10/am_map.c:861:14:
error: type specifier missing, defaults to 'int'; ISO C99 and later do not support implicit int [-Wimplicit-int]
861 |     register    outside;
    |     ~~~~~~~~    ^
    |     int
    
flutterdoom/android/app/src/main/linuxdoom-1.10/am_map.c:992:12:
error: type specifier missing, defaults to 'int'; ISO C99 and later do not support implicit int [-Wimplicit-int]
992 |     static fuck = 0;
    |     ~~~~~~ ^
    |     int

Questi sono facili, basta aggiungere int dopo static e register.
Notare la variabile fuck, qualcuno non sapeva che nome dare a quella variabile. xD

flutterdoom/android/app/src/main/linuxdoom-1.10/i_video.c:32:10:
fatal error: 'X11/Xlib.h' file not found
    32 | #include <X11/Xlib.h>
    |          ^~~~~~~~~~~~
1 error generated

Ok, ci stiamo avvicinando. Il compilatore mi sta dicendo che non trova nessun header di X11, e questo va benissimo perchè Android non utilizza X11 ma un sottosistema grafico proprietario.
Quello che farò successivamente sarà utilizzare direttamente il framebuffer scritto da Doom, quindi non mi serve nessun sottosistema grafico.
Ho eliminato tutti i riferimenti a X11 presenti in i_video.c. Successivamente ci tornerò spesso su questo file.

Andiamo avanti. Questi errori non finiscono mai.

flutterdoom/android/app/src/main/linuxdoom-1.10/r_segs.c:165:32:
error: use of undeclared identifier 'MAXSHORT'
165 |         if (maskedtexturecol[dc_x] != MAXSHORT)
    |                                       ^

flutterdoom/android/app/src/main/linuxdoom-1.10/r_segs.c:185:31:
error: use of undeclared identifier 'MAXSHORT'
185 |             maskedtexturecol[dc_x] = MAXSHORT;
    |                                      ^

La definizione di MAXSHORT è in realtà presente in doomtype.h, ma non sul branch Linux, quindi semplicemente la faccio uscire dal branch e la rendo universale.

flutterdoom/android/app/src/main/linuxdoom-1.10/m_misc.c:257:48:
error: initializer element is not a compile-time constant
257 |     {"sndserver", (int *) &sndserver_filename, (long long) "sndserver"},
    |                                                ^~~~~~~~~~~~~~~~~~~~~~~

Guarda chi si rivede, la stuttura dati dei defaults. A quanto pare Clang diversamente da gcc vuole che defaultvalue sia una costante già conosciuta in fase di compilazione. Le ho provate un po’ tutte qui, ma nessuna soluzione ha funzionato. Ho anche interpellato un LLM (non lo faccio così spesso) ma nessuna soluzione è stata trovata. Alla fine ho deciso di mettere l’intero 0 al posto di quegli indirizzi, visto che non è una sezione critica del codice, e per il momento l’audio in ogni caso non ci sarà.

La compilazione finalmente va a buon fine, anche se c’è un altro errore.

L’errore visualizzato non mi da alcuna informazione utile.
A questo punto devo necessariamente attivare la stampa a video dei messaggi generati dall’engine di Doom.
Per fare questo avevo già pronto l’header debug.h realizzato per il progetto dell’Omnichord, che non contiene altro che una macro chiamata LOG che richiama la funzione di Android __android_log_print.
Tutto quello che devo fare è sostituire nel progetto tutti i printf che trovo con LOG, e importare l’header dove serve.

Fatto questo, altri errori di compilazione. Questa non l’avevo vista arrivare.

flutterdoom/android/app/src/main/linuxdoom-1.10/doomtype.h:34:22:
error: expected identifier
    34 | typedef enum {false, true} boolean;
    |                      ^
Android/Sdk/ndk/28.2.13676358/toolchains/llvm/prebuilt/linux-x86_64/lib/clang/19/include/stdbool.h:21:14:
note: expanded from macro 'true'
    21 | #define true 1
    |              ^
2 errors generated.

Il motivo è presto detto, in debug.h includo android/log.h che include a sua volta stdbool.h, e questo genera un conflitto.

Ecco la parte di codice incriminata. 30 anni fa non avevano il tipo boolean quindi se lo sono creati in questo modo, con un enum.

La mia soluzione. Semplice e funzionale.
In tutti i punti di codice in cui si fa riferimento a true e false, saranno compilati come interi 1 e 0.

Ci siamo, la compilazione va a buon fine, questa volta senza errori scritti in rosso. Anche se ottengo Lost connection to device e nessun messaggio a video.
In effetti è corretto così, perchè ho dimenticato una cosa fondamentale.
Anche se ora il codice C viene compilato, non viene mai invocato da dart:ffi, quindi adesso occorre andare su Flutter e mettere in piedi tutto quello che serve per permettere la comunicazione tra Flutter e C.

Prima di fare questo, devo individuare la funzione main di Doom. Si trova in i_main.c, e tutto quello che fa è leggere i parametri della riga di comando e invocare la funzione D_DoomMain().

Andiamo su Dart. Metto in piedi il caricamento della libreria libdoom.so e l’invocazione diretta di D_DoomMain(). Per adesso devo solo verificare che tutto funzioni, quindi la codebase sarà il più minimale possibile.
Devo solo verificare che D_DoomMain() si avvii correttamente.

Il momento della verità è arrivato…

FUNZIONA!!!
Cioè, non funziona, ma è entrato in D_DoomMain e ha iniziato a stampare messaggi. Sono felicissimo :-)
Si blocca dicendo “Init WADfiles”, perchè in effetti il file WAD non c’è.

Breve spiegazione: l’engine di Doom non contiene nessun tipo di asset hardcodato, nè alcuna descrizione dei livelli. Tutto questo si trova in un file con estensione WAD. L’unica differenza tra Doom Shareware, Doom 1 e Doom 2 è il file WAD, per il resto il motore è sempre lo stesso.

Il motore si aspetta di trovarlo nella stessa directory in cui si trova l’eseguibile, o il file .so in questo caso. Quindi mi sorge un quesito amletico.

CAPITOLO 3 - Come diavolo leggo il file WAD?

La domanda non è banale, perchè il path di installazione dell'app sul sistema (Android o iOS) è nascosto dal sistema operativo. Non ho idea di dove si trovi e neanche come recuperarlo. E non sono neanche sicuro che sia lo stesso path dove viene inclusa libdoom.so.

Quello che ho pensato come soluzione è questo: includo il file WAD come asset del progetto, e quando l'app si avvia, recupero l'asset e lo copio nella directory utente associata all'app, che è l'unica directory in cui l'app ha i permessi di scrittura.

Il team di Flutter mette a disposizione la libreria path_provider, che espone il path della directory utente grazie alla funzione getApplicationDocumentsDirectory().

Questo è il boilerplate che ho messo su. Nulla di particolarmente complesso.

La copia del WAD avviene solo la prima volta che si avvia l'app.

doomMain = dylib.lookup<NativeFunction<Void Function(Pointer<Utf8>)>>('D_DoomMain').asFunction();
doomMain(widget.wadPath.toNativeUtf8());   // Occorre convertire l'oggetto String in questo modo

Quindi questa stringa la passo al Widget MainApp, che a sua volta la passa al D_DoomMain tramite dart:ffi, e infine la passa alla funzione IdentifyVersion, che ho opportunamente modificato.
Questa funzione si occupa di riconoscere quale versione di Doom abbiamo, in base al nome del file WAD.
Il WAD della shareware si chiama doom1.wad, quello della versione completa è doom.wad, e infine abbiamo doom2.wad. Io sto usando la versione shareware.
L’articolo sta diventando troppo lungo quindi evito di riportare qui la funzione IdentifyVersion, che è molto lunga e non fa nulla di interessante se non tanti confronti.

Il trucco ha funzionato, adesso la versione Shareware viene riconosciuta, e in questo modo l’engine ha a disposizione il path utente dell’app, che mi tornerà utile più avanti per la gestione dei savestate del gioco.

Il messaggio D_DoomLoop STARTED l’ho inserito io all’inizio di D_DoomLoop, che è il punto di non ritorno.
Si tratta della funzione in cui parte il loop while infinito dove è gestito il gioco.
Tecnicamente, la schermata iniziale di Doom sta andando, anche se chiaramente non si vede.
Quello che non si vede, anche, è l’Hello World di Flutter sul mio dispositivo, che mostra pagina bianca, e questo era prevedibile. Vediamo perchè.

CAPITOLO 4 - Un solo Thread non basta

1. provo l'Isolate di Dart;
2. creo un nuovo Thread con C.

1. aggiungere #include <pthread.h> nel file d_main.c;
2. creare la funzione FlutterDoomStart che si occuperà di creare il Thread per D_DoomMain. Gli argomenti per D_DoomMain li passo tramite la struct ThreadArgs. ThreadArgs lo alloco nell'heap perchè diversamente, nello stack, sarebbe stato distrutto al termine della funzione FlutterDoomStart.

   typedef struct ThreadArgs {
       char* wad_path;
   } ThreadArgs;
   
   // ...
   
   void FlutterDoomStart(char* wad_path) {
       pthread_t doom_thread;
   
       ThreadArgs* thread_args = malloc(sizeof(ThreadArgs));
       if (thread_args == NULL) {
           LOG("ThreadArgs error");
           return;
       }
       thread_args->wad_path = wad_path;
   
       if (pthread_create(&doom_thread, NULL, &D_DoomMain, thread_args) != 0) {
           LOG("pthread_create error");
           return;
       }
   
       return;
   }
   

3. modificare opportunamente D_DoomMain.

   void* D_DoomMain (void* args)
   {
       ThreadArgs* thread_args = (ThreadArgs*)args;
       // ...
   

CAPITOLO 5 - Ho bisogno del framebuffer

// init subsystems
LOG ("V_Init: allocate screens.\n");
V_Init ();

Direi che non ci sono dubbi, è questo il pezzo di codice che mi interessa. Vediamo cosa c’è dentro V_Init()

void V_Init (void) 
{ 
    int		i;
    byte*	base;
        
    // stick these in low dos memory on PCs

    base = I_AllocLow (SCREENWIDTH*SCREENHEIGHT*4);

    for (i=0 ; i<4 ; i++)
    screens[i] = base + i*SCREENWIDTH*SCREENHEIGHT;
}

Eccolo qui. Non mi aspettavo di trovare ben 4 framebuffer. Faccio qualche ricerca e ho conferma che il framebuffer che mi interessa è screens[0], gli altri sono utilizzati per la transizione wipe (di questa ne parleremo approfonditamente dopo) e la barra di stato del gioco.

La mia strategia sarà questa: il framebuffer lo creo all’interno di Flutter, e passo il suo indirizzo come argomento a D_DoomMain.

Prima di tutto facciamo in modo che Doom allochi internamente solo screens[1], screens[2], screens[3].

void V_Init (void) 
{ 
    int		i;
    byte*	base;
		
    // stick these in low dos memory on PCs

    base = I_AllocLow (SCREENWIDTH*SCREENHEIGHT*3);

    for (i=1 ; i<4 ; i++)
	screens[i] = base + i*SCREENWIDTH*SCREENHEIGHT;
}

C’è qualcosa che non va vero? Qualcuno di voi avrà già notato un bug grande quanto una casa. Io purtroppo me ne accorgerò molto più in là, ma a questo ci arriveremo :-)

Lato Flutter, quindi devo allocare un buffer abbastanza grande per Doom, di dimensione 320 * 200.
Il tipo richiesto è byte, che non è altro che un alias per unsigned char.
dart:ffi mette a disposizione anche questo formato nativo, insieme alla funzione malloc.
Il puntatore al framebuffer lo passo a FlutterDoomStart. Per adesso il codice è tutto nel main e il framebuffer è una variabile globale, ma a fine progetto farò un grosso refactoring per dare una struttura più sensata al codice.
A questo punto sto sperimentando e non bado tanto ai formalismi.

Pointer<UnsignedChar> framebuffer = malloc<UnsignedChar>(320 * 200);

// ...

class MainApp extends StatefulWidget {
  final String wadPath;

  const MainApp({super.key, required this.wadPath});
  
  @override
  State<MainApp> createState() => _MainAppState();
}

class _MainAppState extends State<MainApp> {
  @override
  void initState() {
    super.initState();
    final dylib = DynamicLibrary.open('libdoom.so');
    final void Function(Pointer<Utf8>, Pointer<UnsignedChar>) flutterDoomStart
      = dylib.lookup<NativeFunction<Void Function(Pointer<Utf8>, Pointer<UnsignedChar>)>>('FlutterDoomStart').asFunction();
    flutterDoomStart(widget.wadPath.toNativeUtf8(), framebuffer);
  }

  /// ...

Torniamo in C, FlutterDoomStart è diventata così:

typedef struct ThreadArgs {
    char* wad_path;
    byte* external_fb;
} ThreadArgs;

// ...

void FlutterDoomStart(char* wad_path, byte* external_fb) {
    pthread_t doom_thread;

    ThreadArgs* thread_args = malloc(sizeof(ThreadArgs));
    if (thread_args == NULL) {
        LOG("ThreadArgs error");
        return;
    }
    thread_args->wad_path = wad_path;
    thread_args->external_fb = external_fb;

    if (pthread_create(&doom_thread, NULL, &D_DoomMain, thread_args) != 0) {
        LOG("pthread_create error");
        return;
    }

    return;
}

Infine devo anche assegnare a screen[0] l’indirizzo del framebuffer di Flutter:

// init subsystems
LOG ("V_Init: allocate screens.\n");
V_Init ();
screens[0] = thread_args->external_fb;

Lo so avrei dovuto farlo dentro V_Init, ma poi mi sono detto “chi se ne frega”.
Quindi è tutto pronto. Rilancio “flutter run” per vedere che non ci siano errori, e tutto viene compilato correttamente.

CAPITOLO 6 - E ora che faccio con il framebuffer?

1. Nella codebase di Doom ho creato una cartella chiamata dart e ho importato tutti i file che si trovano nella directory del Flutter SDK bin/cache/dart-sdk/include
2. Ho creato ex-novo una piccola interfaccia, chiamata dart_interface.c

   #include "dart_interface.h"
   
   Dart_Port dart_receive_port = ILLEGAL_PORT;
   
   void registerDartPort(Dart_Port port) {
       dart_receive_port = port;
   }
   
   void notifyDartFrameReady() {
       if (dart_receive_port == ILLEGAL_PORT) {
           return;
       }
       Dart_PostInteger_DL(dart_receive_port, 0);
   }
   

3. In D_DoomLoop, subito dopo la chiamata a D_Display, ho aggiunto la chiamata a notifyDartFrameReady() (questo più tardi scopriremo che è stato un errore):

   // Update display, next frame, with current state.
   D_Display ();
   notifyDartFrameReady();
   

4. Ho aggiunto dart/dart_api_dl.c e dart_interface.c nelle SOURCES di CMakeLists.txt
5. Lato Flutter, ho creato un nuovo StatefulWidget chiamato Doom che viene inizializzato in questo modo:

   framebuffer = malloc<UnsignedChar>(framebufferSize);
   framebuffer32 = Uint32List(framebufferSize);
   
   ui.Image? frame;
   
   @override
     void initState() {
       super.initState();
       nativePort = receivePort.sendPort.nativePort;
       final dylib = DynamicLibrary.open('libdoom.so');
   
       final int Function(Pointer<Void>) dartInitializeApiDL =
         dylib.lookup<NativeFunction<IntPtr Function(Pointer<Void>)>>('Dart_InitializeApiDL').asFunction();
   
       dartInitializeApiDL(NativeApi.initializeApiDLData);
       
       final void Function(int) registerDartPort =
         dylib.lookup<NativeFunction<Void Function(Int64)>>('registerDartPort').asFunction();
   
       registerDartPort(nativePort);
   
       receivePort.listen((dynamic message) async {
         // Invoked at new frame ready
   
         for (int i=0; i<framebufferSize; i++) {
           framebuffer32[i] = 0xFF000000 | (framebuffer[i] << 16) | (framebuffer[i] << 8) | (framebuffer[i]);
         }
   
         var immutableBuffer = await ImmutableBuffer.fromUint8List(framebuffer32.buffer.asUint8List());
   
         final ui.Codec codec = await ui.ImageDescriptor.raw(
           immutableBuffer,
           width: 320,
           height: 200,
           rowBytes: null,
           pixelFormat: ui.PixelFormat.rgba8888, 
         ).instantiateCodec();
   
         final ui.FrameInfo frameInfo = await codec.getNextFrame();
         frame = frameInfo.image;
         
         setState(() {});
       });
   
       final void Function(Pointer<Utf8>, Pointer<Uint8>) flutterDoomStart
         = dylib.lookup<NativeFunction<Void Function(Pointer<Utf8>, Pointer<Uint8>)>>('FlutterDoomStart').asFunction();
   
       flutterDoomStart(widget.wadPath.toNativeUtf8(), framebuffer);
     }
   

Questa funzione è quasi tutta un boilerplate poco comprensibile. Mea culpa, ma come già detto quando sono in piena sperimentazione scrivo le cose nel modo più sporco e veloce possibile; solo molto più avanti nei progetti mi preoccupo di rifattorizzare e magari scrivere qualche commento.

Quello che ci interessa sapere di questa funzione è questo:
la callback collegata a receivePort.listen viene invocata ogni volta che D_DoomLoop chiama notifyDartFrameReady.

(Per essere precisi, ogni volta che viene chiamata Dart_PostInteger_DL, il valore 0 che allego alla funzione arriva alla callback ricevente tramite l’argomento dynamic message; in questo specifico caso non è necessario gestire i message ricevuti perchè mi serve soltanto sapere quando Doom ha terminato di scrivere un nuovo frame)

A quel punto avviene la conversione del framebuffer in un frame digeribile dal CustomPaint di Flutter, e infine viene chiamato setState per rebuildare il widget. Tutto questo avviene, come abbiamo detto prima, 35 volte ogni secondo.

Punto di attenzione su questa conversione:

for (int i=0; i<framebufferSize; i++) {
  framebuffer32[i] = 0xFF000000 | (framebuffer[i] << 16) | (framebuffer[i] << 8) | (framebuffer[i]);
}

Abbiamo detto che il framebuffer di Doom è 8 bit, cioè 256 colori, mentre il CustomPaint accetta immagini a 24 bit, ovvero circa 16 milioni di colori.
Occorre quindi convertire i singoli pixel da 8 a 24 bit.
Il problema è che la palette di Doom mi è “ignota”, almeno per ora. Più avanti ci sarà un capitolo intero dedicato ad essa.
Per visualizzare comunque qualcosa a schermo decido di convertire i byte in input in valori a 24 bit a scala di grigi, ovvero stessa quantità di rosso, verde e blu. Ai colori ci penserò dopo.

Il CustomPaint è così:

@override
  Widget build(BuildContext context) {
    if (frame == null) {
      return Text("Doom is starting...");
    }
    else {
      return CustomPaint(
        painter: FramebufferPainter(),
        size: const ui.Size(320, 200)
      );
    }
  }
}

class FramebufferPainter extends CustomPainter {  
  FramebufferPainter();

  @override
  void paint(ui.Canvas canvas, ui.Size size) {
    final Rect src = Rect.fromLTWH(0, 0, frame!.width.toDouble(), frame!.height.toDouble());
    
    canvas.drawImageRect(
      frame!,
      src,
      src,
      Paint()
    );
  }
  
  @override
  bool shouldRepaint(covariant CustomPainter oldDelegate) => true;
}

Basta, mi sono annoiato con tutto questo codice insensato, vediamo se abbiamo ottenuto qualcosa.

CAPITOLO 7 - A quanto pare sono costretto a mappare gli input (e a renderli Thread Safe)

// DOOM keyboard definition.
// This is the stuff configured by Setup.Exe.
// Most key data are simple ascii (uppercased).
//
#define KEY_RIGHTARROW	0xae
#define KEY_LEFTARROW	0xac
#define KEY_UPARROW	0xad
#define KEY_DOWNARROW	0xaf
#define KEY_ESCAPE	27
#define KEY_ENTER	13
#define KEY_TAB		9
#define KEY_F1		(0x80+0x3b)
#define KEY_F2		(0x80+0x3c)
#define KEY_F3		(0x80+0x3d)
#define KEY_F4		(0x80+0x3e)
#define KEY_F5		(0x80+0x3f)
#define KEY_F6		(0x80+0x40)
#define KEY_F7		(0x80+0x41)
#define KEY_F8		(0x80+0x42)
#define KEY_F9		(0x80+0x43)
#define KEY_F10		(0x80+0x44)
#define KEY_F11		(0x80+0x57)
#define KEY_F12		(0x80+0x58)

#define KEY_BACKSPACE	127
#define KEY_PAUSE	0xff

#define KEY_EQUALS	0x3d
#define KEY_MINUS	0x2d

#define KEY_RSHIFT	(0x80+0x36)
#define KEY_RCTRL	(0x80+0x1d)
#define KEY_RALT	(0x80+0x38)

#define KEY_LALT	KEY_RALT

Creo in C una chiamata DartPostInput che dovrà prendere in input i segnali inviati da Dart e inviarli a sua volta alla funzione D_PostEvent, che è la funzione di Doom che prende in input tutti i tipi di eventi (tastiera, mouse, controller).
L’input di questa funzione è una Struct event_t composta da 2 campi: il codice ASCII del tasto premuto, e il tipo di gesture (down/up).

void DartPostInput(int dart_key, int dart_pressed_down) {
  event_t new_event;
  new_event.data1 = dart_key;
  new_event.type = dart_pressed_down ? ev_keydown : ev_keyup;
  D_PostEvent(&new_event);
}

//
// D_PostEvent
// Called by the I/O functions when input is detected
//
void D_PostEvent (event_t* ev)
{
  events[eventhead] = *ev;
  eventhead = (++eventhead)&(MAXEVENTS-1);
}

Lato Flutter creo una classe dove riporto tutta la mappatura completa dei tasti.

class AsciiKeys {
  static const Map<String, int> keyCodes = {
    "KEY_RIGHTARROW": 0xae,
    "KEY_LEFTARROW": 0xac,
    "KEY_UPARROW": 0xad,
    "KEY_DOWNARROW": 0xaf,
    // ...
    "5": 53,
    "6": 54,
    "7": 55,
    "Y": 121
  };
}

Definisco lato dart:ffi la funzione dartPostInput, che verrà chiamata da ogni eventDown ed eventUp dei pulsanti. Questa funzione prenderà in input i 2 interi che devono essere mandati a Doom, ovvero l’ASCII del tasto e il gesture, che in questo caso sarà 1 per indicare il tasto premuto, 0 per indicare il tasto rilasciato.

final void Function(int, int) dartPostInput =
  dylib.lookup<NativeFunction<Void Function(Int32, Int32)>>('DartPostInput').asFunction();

Tutta questa procedura dovrebbe funzionare, ma ha un grosso difetto: non è Thread Safe. Ne sono perfettamente consapevole.
La chiamata a DartPostInput avviene dal Thread principale, che non è quello dove sta girando il motore di Doom.
Dallo stesso Thread viene quindi poi chiamata D_PostEvent che va a scrivere sul buffer circolare events.
Potrebbe succedere che il thread UI venga messo in pausa quando non ha ancora finito di scrivere la struttura event_t sull’indice attuale di events. Potrebbe quindi succedere che la funzione “worker” che si occupa di leggere events legga dei dati errati e che il software vada in crash o che abbia un comportamento indesiderato.
Il problema potrebbe porsi anche con l’indice eventhead, anch’esso una risorsa condivisa tra i due Threads.

Proviamo quindi a rendere il tutto Thread Safe. la libreria pthread.h mette a disposizione il sistema di mutex, che è quello che fa al caso mio. Il funzionamento è semplice: quando entro in D_PostEvent blocco il mutex, e dopo aver eseguito le operazione di scrittura, lo sblocco.
La funzione che legge il buffer dovrà attendere lo sblocco del mutex per per poter accedere a events.

Modifichiamo D_PostEvent:

#include <pthread.h>
pthread_mutex_t event_mutex = PTHREAD_MUTEX_INITIALIZER;

// ...

void D_PostEvent (event_t* ev)
{
  pthread_mutex_lock(&event_mutex);

  events[eventhead] = *ev;
  eventhead = (++eventhead)&(MAXEVENTS-1);

  pthread_mutex_unlock(&event_mutex);
}

La funzione che si occupa di leggere il buffer circolare events è D_ProcessEvents:

void D_ProcessEvents (void)
{
    event_t*	ev;

    // IF STORE DEMO, DO NOT ACCEPT INPUT
    if ( ( gamemode == commercial ) && (W_CheckNumForName("map01")<0) )
        return;

    for ( ; eventtail != eventhead ; eventtail = (++eventtail)&(MAXEVENTS-1) )
    {
        ev = &events[eventtail];
        if (M_Responder (ev))
            continue;               // menu ate the event
        G_Responder (ev);
    }
}

La modifico così:

void D_ProcessEvents (void)
{
    event_t*	ev;
    event_t 	ev_copy;
    int 	localhead;

    // IF STORE DEMO, DO NOT ACCEPT INPUT
    if ( ( gamemode == commercial ) && (W_CheckNumForName("map01")<0) )
        return;

    pthread_mutex_lock(&event_mutex);
    localhead = eventhead;

    for ( ; eventtail != localhead ; eventtail = (++eventtail)&(MAXEVENTS-1) )
    {
        ev_copy = events[eventtail];
        pthread_mutex_unlock(&event_mutex);

        ev = &ev_copy;

        if (M_Responder (ev))
            goto continue_loop;               // menu ate the event
        G_Responder (ev);

        continue_loop:
        pthread_mutex_lock(&event_mutex);
    }

    pthread_mutex_unlock(&event_mutex);
}

D_ProcessEvents acquisisce il lock, e questo avviene solo se il lock non è già occupato da D_PostEvent, copia localmente l’indice eventhead, entra nel loop e copia localmente anche la struttura event_t. A questo punto il lock viene rilasciato.

D_PostEvent è quindi libero di fare quello che vuole, e questo perchè D_ProcessEvents lavorerà su dati presenti solo al suo interno e non più su variabili globali.
Quindi vengono chiamate le funzioni M_Responder e G_Responder che si occupano di processare effettivamente i dati, e alla fine del loop viene riacquisito il lock. In questo modo, quando il loop ricomincia, anche l’aggiornamento di eventtail viene protetto, che ricordiamo essere una variabile globale.
Viene eseguita nuovamente la copia del nuovo evento in locale e così via.
Una volta usciti dal ciclo, il lock viene rilasciato definitivamente.

Fatto questo, realizzo abbastanza velocemente su Flutter con una combinazione di Container, Row e Column un rudimentale controller, davvero molto brutto.

Vediamo se riesco ad entrare nel gioco vero e proprio.

La buona notizia è che i tasti funzionano, riesco ad entrare nel menu.
La cattiva invece è non riesco ad entrare nel gioco, ottengo un errore di tipo SIGSEGV e il programma termina.

F/libc    (18384): Fatal signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr 0x14 in tid 18771 (ple.flutterdoom), pid 18384 (ple.flutterdoom)
*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
Build fingerprint: 'samsung/j6ltexx/j6lte:10/QP1A.190711.020/J600FNXXSACVB1:user/release-keys'
Revision: '2'
ABI: 'arm'
Timestamp: 2025-12-04 23:14:47+0100
pid: 18384, tid: 18771, name: ple.flutterdoom  >>> com.example.flutterdoom <<<
uid: 10568
signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr 0x14
Cause: null pointer dereference
    r0  00000000  r1  00000001  r2  00000000  r3  00000000
    r4  a7a2a230  r5  a7a2a230  r6  a7a2a230  r7  a7a29f30
    r8  000047d0  r9  000047d0  r10 ebe4e034  r11 a7a2a230
    ip  a5bd62b4  sp  a7a29f08  lr  a5ba523d  pc  a5bd17e6
backtrace:
      #00 pc 000497e6  /data/app/com.example.flutterdoom-BK0haLh0jGqqgyyiCtgFXw==/base.apk!libdoom.so (offset 0x330000) (Z_Malloc+42) (BuildId: 84f93e185bf2460ea002e280cde72fee54022427)
      #01 pc 0001d239  /data/app/com.example.flutterdoom-BK0haLh0jGqqgyyiCtgFXw==/base.apk!libdoom.so (offset 0x330000) (wipe_initMelt+104) (BuildId: 84f93e185bf2460ea002e280cde72fee54022427)
      #02 pc 0001d61f  /data/app/com.example.flutterdoom-BK0haLh0jGqqgyyiCtgFXw==/base.apk!libdoom.so (offset 0x330000) (wipe_ScreenWipe+74) (BuildId: 84f93e185bf2460ea002e280cde72fee54022427)
      #03 pc 0001dbb5  /data/app/com.example.flutterdoom-BK0haLh0jGqqgyyiCtgFXw==/base.apk!libdoom.so (offset 0x330000) (D_Display+908) (BuildId: 84f93e185bf2460ea002e280cde72fee54022427)
      #04 pc 0001ddc3  /data/app/com.example.flutterdoom-BK0haLh0jGqqgyyiCtgFXw==/base.apk!libdoom.so (offset 0x330000) (D_DoomLoop+274) (BuildId: 84f93e185bf2460ea002e280cde72fee54022427)
      #05 pc 0001f453  /data/app/com.example.flutterdoom-BK0haLh0jGqqgyyiCtgFXw==/base.apk!libdoom.so (offset 0x330000) (D_DoomMain+3026) (BuildId: 84f93e185bf2460ea002e280cde72fee54022427)
      #06 pc 000a8147  /apex/com.android.runtime/lib/bionic/libc.so (__pthread_start(void*)+20) (BuildId: 68663d64ac44a935374eee374ddf6c9d)
      #07 pc 00061467  /apex/com.android.runtime/lib/bionic/libc.so (__start_thread+30) (BuildId: 68663d64ac44a935374eee374ddf6c9d)
Lost connection to device.

L’errore specifico è null pointer dereference, e abbiamo anche un backtrace abbastanza chiaro, si capisce infatti che il problema è legato alla transizione wipe, che è quella transizione tipo sangue che scivola verso il basso che avviene tra una schermata e l’altra.

Quello che posso provare, momentaneamente, è disattivare la transizione.
Per farlo, basta commentare un paio di sezioni di codice nella funzione D_Display, che è quella che si occupa di disegnare a schermo.

  boolean wipe = false;
    
  //
  // ...
  //

  // save the current screen if about to wipe
  if (gamestate != wipegamestate)
  {
    wipe = true;
    wipe_StartScreen(0, 0, SCREENWIDTH, SCREENHEIGHT);
  }
  else
    wipe = false;

  //
  //...
  //

  // wipe update
  wipe_EndScreen(0, 0, SCREENWIDTH, SCREENHEIGHT);

  wipestart = I_GetTime () - 1;

  do
  {
    do
    {
      nowtime = I_GetTime ();
      tics = nowtime - wipestart;
    } while (!tics);
    wipestart = nowtime;
    done = wipe_ScreenWipe(wipe_Melt, 0, 0, SCREENWIDTH, SCREENHEIGHT, tics);
    I_UpdateNoBlit ();
    M_Drawer ();                            // menu is drawn even on top of wipes
    I_FinishUpdate ();                      // page flip or blit buffer
  } while (!done);

Queste sono le righe di codice che ho commentato. Ho anche forzato a false la variabile wipe.

Non mi resta che riprovare:

Stavolta funziona davvero. Sto davvero giocando a Doom usando Flutter come motore grafico :-)
Questa palette a scala di grigi tutto sommato non è così male, ha il suo fasciono e sembra quasi di giocare con un vecchio GameBoy.
Ma adesso è arrivato il momento di gestire i colori.

CAPITOLO 8 - La palette dei colori non è un argomento banale

final Pointer<Uint32> palette = malloc<Uint32>(256);

// ...

final void Function(Pointer<Utf8>, Pointer<UnsignedChar>, Pointer<Uint32>) flutterDoomStart
  = dylib.lookup<NativeFunction<Void Function(Pointer<Utf8>, Pointer<UnsignedChar>, Pointer<Uint32>)>>('FlutterDoomStart').asFunction();

flutterDoomStart(widget.wadPath.toNativeUtf8(), framebuffer, palette);

Lato C modifico la funzione ricevente FlutterDoomStart e dichiaro la variabile globale external_palette:

uint32_t* external_palette;

// ...

void FlutterDoomStart(char* wad_path, byte* external_fb, uint32_t* _external_palette) {
  external_palette = _external_palette;

  pthread_t doom_thread;

  ThreadArgs* thread_args = malloc(sizeof(ThreadArgs));
  if (thread_args == NULL) {
    LOG("ThreadArgs error");
    return;
  }
  thread_args->wad_path = wad_path;
  thread_args->external_fb = external_fb;

  if (pthread_create(&doom_thread, NULL, &D_DoomMain, thread_args) != 0) {
    LOG("pthread_create error");
    return;
  }

  return;
}

Adesso che ho la variabile su cui scrivere la palette, devo solo trovare il punto nel codice di Doom che mi permetta di farlo.

Il punto corretto è nel file i_video.c, e in modo specifico nella funzione I_SetPalette. Tutto il file i_video.c lo si può proprio intendere allo stesso modo delle interfacce della OOP, ovvero un contratto che definisce delle funzioni vuote da implementare.
Infatti è su questo file dove era stato definito tutto il boilerplate per comunicare con il sottosistema grafico di Linux, X11. Tutti i port di Doom devono quindi implementare opportunamente queste funzioni per comunicare con lo specifico sottosistema grafico del proprio sistema operativo.

Vediamo come ho implementato I_SetPalette:

extern uint32_t* external_palette;

// ...

void I_SetPalette (byte* palette)
{
  for (int i=0 ; i<255 ; i++) {
    external_palette[i] = 0xFF000000;
    external_palette[i] |= (gammatable[usegamma][*palette++] & ~3) << 16;
    external_palette[i] |= (gammatable[usegamma][*palette++] & ~3) << 8;
    external_palette[i] |= (gammatable[usegamma][*palette++] & ~3);
  }
}

Itero per tutto l’array palette, che ricordiamo essere formato da 768 bytes. Sono 256 iterazioni del ciclo for, e per ogni iterazione leggo 3 bytes. Per ogni byte mantengo i primi 6 bit azzerando gli ultimi 2 tramite l’operazione di mascheramento.
Ogni byte letto viene inserito tramite OR e bitshifting nella locazione di external_palette, che è un valore a 32 bit in formato PixelFormat.rgba8888, dove il primo byte da sinistra rappresenta il canale alpha, poi il blu, il verde e infine il rosso.

Punto di attenzione: per poter permettere a Doom di gestire la gamma dei colori, che è modificabile da interfaccia con il tasto F11, pesco il valore finale del componente dall’array gammatable che è definito come costante all’interno della codebase di Doom.
La correzione gamma è importante perchè permette di schiarire complessivamente i colori, infatti su alcuni schermi l’immagine potrebbe ad esempio risultare troppo scura, e tramite la correzione gamma è possibile applicare una compensazione.

Tornando su Flutter, modifico la funzione che viene invocata ad ogni nuovo fotogramma disponibile:

receivePort.listen((dynamic message) async {
  // Invoked at new frame ready

  for (int i=0; i<framebufferSize; i++) {
    framebuffer32[i] = palette[framebuffer[i]];
  }

  // ...

La conversione a 32 bit è già avvenuta su I_SetPalette, quindi su questa funzione devo andare a convertire il framebuffer da 8 a 32 bit semplicemente pescando il colore corrispondente dall’array condiviso palette.

Proviamo a vedere se il tutto funziona.

Ci siamo quasi, ho solo invertito il blu con il rosso, poco male.

void I_SetPalette (byte* palette)
{
  for (int i=0 ; i<255 ; i++) {
    external_palette[i] = 0xFF000000;
    external_palette[i] |= (gammatable[usegamma][*palette++] & ~3);
    external_palette[i] |= (gammatable[usegamma][*palette++] & ~3) << 8;
    external_palette[i] |= (gammatable[usegamma][*palette++] & ~3) << 16;
  }
}

Visto che nel capitolo precedente abbiamo parlato di Thread Safety, è doveroso fare un’osservazione anche per il framebuffer e la palette.
La lettura e la scrittura di questi due array infatti non è atomica, e durante la lettura anche parziale da parte di Flutter, L’array potrebbe essere modificato da Doom. Quindi tutto il sottosistema grafico che ho messo in piedi NON è Thread Safe, ma secondo me possiamo convivere tranquillamente con questo difetto.
Il peggio che può succedere è che ci sia un glitch grafico e nulla di più. In tutti i test che ho fatto non si è mai verificata questa condizione, perchè Flutter è abbastanza veloce da convertire il framebuffer prima che Doom crei un nuovo frame.

Capitolo 9 - Risolviamo i bug che io stesso ho introdotto

  boolean wipe;
    
  //
  // ...
  //

  // save the current screen if about to wipe
  if (gamestate != wipegamestate)
  {
    wipe = true;
    wipe_StartScreen(0, 0, SCREENWIDTH, SCREENHEIGHT);
  }
  else
    wipe = false;

  //
  //...
  //

  // wipe update
  wipe_EndScreen(0, 0, SCREENWIDTH, SCREENHEIGHT);

  wipestart = I_GetTime () - 1;

  do
  {
    do
    {
      nowtime = I_GetTime ();
      tics = nowtime - wipestart;
    } while (!tics);
    wipestart = nowtime;
    done = wipe_ScreenWipe(wipe_Melt, 0, 0, SCREENWIDTH, SCREENHEIGHT, tics);
    I_UpdateNoBlit ();
    M_Drawer ();                            // menu is drawn even on top of wipes
    I_FinishUpdate ();                      // page flip or blit buffer
  } while (!done);

Rilanciando l’app, noto qualcosa di strano, cioè che l’errore che viene visualizzato in console non è sempre lo stesso. Inoltre è capitato qualche volta che il gioco partisse, anche se comunque senza effetto wipe.
Si tratta quindi di un comportamento indefinito, probabilmente le funzioni collegate all’effetto staranno provando ad accedere a delle locazioni di memoria non inizializzate correttamente.

Proviamo a vedere cosa c’è dentro wipe_StartScreen.

int
wipe_StartScreen
( int	x,
  int	y,
  int	width,
  int	height )
{
  wipe_scr_start = screens[2];
  I_ReadScreen(wipe_scr_start);
  return 0;
}

Sembra che faccia la copia dello schermo nel framebuffer screens[2].
Vediamo cosa fa I_ReadScreen.

void I_ReadScreen (byte* scr)
{
}

Ho capito cosa è successo. Quando sono andato a togliere tutti i riferimenti a X11 nel file i_video.c ci sono andato pesante con la mannaia :-)
Ho eliminato più di quello che dovevo. Quindi procedo a ripristinare questa funzione, si tratta semplicemente del comando che permette la copia della memoria da una locazione ad un’altra.

void I_ReadScreen (byte* scr)
{
  memcpy (scr, screens[0], SCREENWIDTH*SCREENHEIGHT);
}

Provo a rilanciare il gioco.
Il problema persiste, non è cambiato nulla. C’è quindi un altro bug da qualche altra parte.

Lo stacktrace che ho pubblicato più in alto purtroppo non è consistente, come ho già scritto prima ogni volta che avvio il gioco ottengo un errore diverso.

A volte il gioco parte, ma ho notato una cosa: la status bar è spesso corrotta.

void V_Init (void) 
{ 
  int		i;
  byte*	base;

  // stick these in low dos memory on PCs

  base = I_AllocLow (SCREENWIDTH*SCREENHEIGHT*3);

  for (i=1 ; i<4 ; i++)
    screens[i] = base + i*SCREENWIDTH*SCREENHEIGHT;
}

Cosa è successo: non dovendo più allocare la memoria per 4 framebuffer ma solo 3, avevo modificato il parametro di I_AllocLow per allocare la memoria necessaria per soli 3 framebuffer.
Il ciclo for assegna l’indirizzo di memoria di base a ciascuno dei 3 framebuffer.
Il problema è che, nell’ultimo framebuffer, il 3, assegno l’indirizzo di un’area di memoria non allocata, a causa dell’offset errato ottenuto con l’indice i.
Ecco la funzione corretta:

void V_Init (void) 
{ 
  int		i;
  byte*	base;

  // stick these in low dos memory on PCs

  base = I_AllocLow (SCREENWIDTH*SCREENHEIGHT*3);

  for (i=0 ; i<3 ; i++)
    screens[i+1] = base + i*SCREENWIDTH*SCREENHEIGHT;
}

Adesso il gioco non crasha più in modo randomico. Purtroppo però ancora nessun effetto wipe.
Questo problema però è stato più semplice da risolvere.
La funzione notifyDartFrameReady che ricordiamo serve a segnalare a Flutter che è pronto un nuovo frame, la chiamo all’interno di D_DoomLoop, subito dopo D_Display.

#include "dart_interface.h"

// ...

void D_DoomLoop (void)
{
  // ...

  // Update display, next frame, with current state.
  D_Display ();
  notifyDartFrameReady();

  // ...
}

Guardando dentro D_Display, è chiaro perchè non si vede il wipe.

void D_Display (void)
{
  // ...
      // normal update
  if (!wipe)
  {
    I_FinishUpdate ();              // page flip or blit buffer
    return;
  }

  // wipe update
  wipe_EndScreen(0, 0, SCREENWIDTH, SCREENHEIGHT);

  wipestart = I_GetTime () - 1;

  do
  {
    do
    {
      nowtime = I_GetTime ();
      tics = nowtime - wipestart;
    } while (!tics);
    wipestart = nowtime;
    done = wipe_ScreenWipe(wipe_Melt, 0, 0, SCREENWIDTH, SCREENHEIGHT, tics);
    I_UpdateNoBlit ();
    M_Drawer ();                            // menu is drawn even on top of wipes
    I_FinishUpdate ();                      // page flip or blit buffer
  } while (!done);
}

Ovvero: quando non c’è il wipe, viene chiamata I_FinishUpdate e poi esce da D_Display. Quando c’è il wipe, parte il ciclo che genera l’effetto, chiamando I_FinishUpdate per ogni iterazione.
Il problema è che la segnalazione del nuovo frame viene fatta solo all’uscita di D_Display, quando in realtà va fatta all’interno di I_FinishUpdate. Modifico la funzione.

void I_FinishUpdate (void)
{
  // ...
  notifyDartFrameReady();
}

CAPITOLO 10 - Un po' di frontend: creiamo un controller comodo e funzionale

Alla fine, dopo parecchie prove, ho ottenuto questo layout di cui sono molto soddisfatto.

Non entrerò troppo nei dettagli del codice, però come scrivevo sopra, i Tasti Direzionali forse meritano un piccolo approfondimento.

Premetto che non ho utilizzato GestureDetector, ma ho usato il Listener, perchè a differenza del GestureDetector non introduce latenza, essendo il Widget più a basso livello per quanto riguarda gli input.

I tasti direzionali, sono un unico Listener, a differenza di tutti gli altri tasti dove invece ognuno di essi è un Listener.

Avere un unico Listener mi ha permesso di gestire oltre che il gesture down e up, anche il move. Ad ogni movimento del dito, viene invocata una callback che si occupa di capire quale tasto si sta premendo in quel momento, in base alle coordinate x/y del puntatore (il dito) rispetto all'area occupata dal quadrato che racchiude tutti i Tasti Direzionali.

Sto semplificando molto, la questione è meno banale di così perchè ad esempio durante l'operazione di move il puntatore può uscire fuori dall'area del controller, quindi va rilasciato il pulsante che si stava premendo, ed eventualmente il puntatore potrebbe anche strisciare nuovamente nell'area del controller, quindi premendo un nuovo tasto (o lo stesso rilasciato il precedenza).

Se volete approfondire, trovate tutto su lib/keyboard/directional_keys.dart.

CAPITOLO 11 - Compiliamo su iOS

Sono perfettamente consapevole che usare un Hackintosh per sviluppare su Flutter è una pratica sconsigliata, ma è solo ai fini di testing.

Non ho intenzione di pubblicare sullo store app compilate sull'Hackintosh, anche perchè si rischierebbe un grosso ban da parte di Apple.

Per quello eventualmente userò qualche servizio di CI/CD tipo Codemagic. Per questo progetto non è necessario, in ogni caso.

Conclusioni

1. Audio
   Al momento il gioco è completamente muto. Nella versione Linux gli effetti audio venivano invocati asincronamente su un altro applicativo che fungeva da server audio. Nella versione Flutter bisogna capire come gestire la cosa. Non ho assolutamente guardato come il codice sorgente di Doom gestisce tutta la parte audio, quindi questa cosa me la metto da parte per il futuro.
   Penso che ci tornerò, perchè potrebbe essere interessante a livello didattico.
2. Modalità landscape
   Con magari un controller a video, semitrasparente e integrato con la schermata del gioco.
3. Gestione di controller hardware
   Ad esempio con una tastiera esterna collegata tramite la porta USB, e magari anche con un mouse (cosa che non ho mai usato per giocare a Doom, ma so che molti lo fanno).
4. Caricamento di WAD da parte dell'utente
   Attualmente, solo il WAD della versione shareware funziona. Con delle piccolissime modifiche al codice è comunque possibile caricare anche altri WAD, ma sarebbe bello che fosse l'utente finale ad aprirli sull'app.
5. Gestione dell'uscita dall'app
   Questo è divertente: attualmente quando si va nel menu del gioco, e si sceglie di quittare, effettivamente l'app si chiude.
   Ma questo in realtà non me lo aspettavo, perchè quello che succede è che avviene un Segmentation Fault e l'app crasha completamente :-)
   Ad onor di cronaca, questo succede anche nella versione compilata su Linux. Non è un problemone, ma prima o poi proverò a risolverlo.

Sono veramente soddisfatto di come è venuto questo articolo. Ho cercato di mettere più informazioni possibili. Spero possiate trovarlo utile.