Sviluppo di un homebrew Nintendo 64 con LibDragon: la guida completa per i principianti
La Nintendo 64 ha avuto a lungo una reputazione di macchina ostile allo sviluppo dilettante. La sua architettura MIPS, il suo coprocessore RSP e la sua documentazione d'epoca gelosamente conservata hanno scoraggiato molte vocazioni. LibDragon ha cambiato le cose: è una libreria open source, con licenza permissiva e scritta in C, che fornisce tutto ciò che serve per parlare alla console senza passare attraverso l'SDK ufficiale di Nintendo. È lei che motorizza oggi la maggior parte della scena moderna N64, dalle demo tecniche alle portate complete come la Comix Zone 64 di Frogbull.
⚠️ Questa guida mira alla situazione al 1° settembre 2026. Gli strumenti citati si evolvono rapidamente: lo strumento in linea di comando libdragon-docker è alla v12.2.1, l'emulatore ares alla versione 148 e Gopher64 alla v1.1.36 del 21 agosto 2026. Controlla le pagine di rilascio prima di iniziare, i numeri di versione probabilmente si sono spostati da allora. Si noti anche: Simple64, a lungo consigliato per testare homebrews, è passato in archivio nel febbraio 2025 e non deve più servire da riferimento.
Prerequisiti
Hai bisogno di: un PC con Windows, Linux o macOS; Git installato; Docker nella versione 27.2.0 o superiore se scegli il metodo raccomandato di seguito; e alcune nozioni di C, anche solo sapere che cosa è un ciclo e un puntatore. Non è necessaria alcuna conoscenza del montatore MIPS per iniziare. Fornisci anche un emulatore preciso per testare, e alla fine una cartuccia flash se vuoi vedere il tuo programma girare sulla console stessa.
Passo 1: Installare l'ambiente di compilazione
Due strade sono a tua disposizione. Il più semplice, e quello che la documentazione consiglia ai principianti, passa attraverso libdragon-docker, un'utilità che incapsula tutto il toolchain in un contenitore: non hai bisogno di capire Docker per usarlo, solo di averlo installato. Su Windows, scarica e avvia l'installatore dalla pagina di rilascio, ignorando l'avviso di sicurezza del sistema. Su macOS e Linux, recupera l'eseguibile corrispondente al tuo sistema e mettilo nel tuo PATH, rispettivamente in /usr/local/bin e in ~/.local/bin, quest'ultimo caso richiedendo un chmod u+x ~/.local/bin/libdragon. Se Node.js 24 o superiore è già presente sulla tua macchina, un semplice npm install -g libdragon fa anche il trucco.
Il secondo modo consiste nell'installare il toolchain in modo nativo, senza container, recuperando i binari precompilati pubblicati sulla pagina di release dedicata: un pacchetto .deb per Debian e Ubuntu, un .rpm per Fedora, un archivio .zip per Windows. In questo caso è necessario impostare la variabile di ambiente N64_INST nella cartella di installazione, quindi compilare la libreria con ./build.sh. In Windows questo metodo richiede anche un terminale MSYS2 UCRT64. Esiste una terza opzione, la compilazione del toolchain da fonti via ./build-toolchain.sh, ma richiede più di un'ora e circa 7 GB di spazio temporaneo: conservalo per dopo.
Fase 2: creazione del primo progetto
Mettiti in una cartella vuota, preferibilmente un deposito Git appena inizializzato, quindi lancia libdragon init. Il comando crea un progetto scheletrico, include una copia di LibDragon con il tuo codice e scarica l'immagine del toolchain. La prima chiamata richiede pochi minuti, il tempo di download. Si ottiene un albero pronto per l'uso con un file sorgente, un Makefile e la libreria.
Un punto di vocabolario merita la tua attenzione: LibDragon propone due rami. trunk è il ramo stabile, con un impegno di compatibilità ascendente, ed è quello da scegliere per iniziare. preview contiene le funzionalità in fase di sviluppo, con un'API che potrebbe cambiare senza preavviso. Molti tutorial trovati online mescolano entrambi, il che spiega la maggior parte degli errori di compilazione riscontrati dai principianti.
Fase 3: compilare e ottenere la sua ROM
La compilazione è in un ordine: libdragon make. Se hai optato per l'installazione nativa, un semplice make è sufficiente. Il risultato è un file .z64, il formato ROM della console, direttamente eseguibile su emulatore come su hardware reale.
Il Makefile merita un'occhiata, perché è breve e tutto si gioca in due righe. La direttiva include $(N64_INST)/include/n64.mk importa le regole di compilazione ufficiali, quelle che trasformano automaticamente i file .c in oggetti, poi in file .elf, poi in ROM .z64. La variabile N64_ROM_TITLE definisce il titolo inserito nell'intestazione della cartuccia e BUILD_DIR la cartella in cui atterrano i file intermedi. Per aggiungere un file di origine al progetto, è sufficiente aggiungerlo all'elenco OBJS come oggetto da produrre.
Fase 4: comprendere lo scheletro di un programma
Un programma LibDragon inizia con un #include <libdragon.h>, accanto alle normali intestazioni C. Nel main(), due chiamate pongono le fondamenta: display_init(), che prende la risoluzione, la profondità del colore, il numero di tamponi e filtri, in una forma del tipo display_init(RESOLUTION_320x240, DEPTH_32_BPP, 2, GAMMA_NONE, FILTERS_RESAMPLE), e joypad_init() per la gestione dei controller.
Poi viene il ciclo principale, che segue sempre lo stesso ritmo: si recupera una superficie di disegno con display_get(), si disegna su di esso, si invia sullo schermo con display_show(), e si leggono le voci con joypad_poll() e poi joypad_get_buttons_pressed(). Inizializzazione, rendering, input, visualizzazione: questo schema si trova in quasi tutti i progetti della scena. La cartella examples del deposito è piena di programmi brevi che declinano questo scheletro, ed è di gran lunga il modo migliore per imparare.
Fase 5: testare la sua ROM su emulatore
Non tutti gli emulatori N64 valgono per lo sviluppo. Molti sono stati progettati per far girare i giochi commerciali del catalogo e prendono le libertà con l'hardware, dando risultati fuorvianti: un homebrew può apparire perfettamente a casa e piantarsi sulla console. Oggi ci sono due scelte. ares, in versione 148 dal maggio 2026, emula a basso livello e utilizza Parallel-RDP tramite Vulkan, che presuppone un PC dotato di una scheda grafica dedicata compatibile. Gopher64, in v1.1.36 dal 21 agosto 2026, costituisce l'alternativa moderna a Simple64, di cui ha ripreso la fiaccola. Test preferibilmente su entrambi: una differenza di comportamento tra di loro segnala quasi sempre un bug nel tuo codice.
Stadio 6: lanciare il suo homebrew su un vero Nintendo 64
Il passaggio su hardware reale richiede una cartuccia flash. La SummerCart64 è la scelta di riferimento per lo sviluppo: completamente open source, integra un collegamento USB di debug che consente di inviare una ROM appena compilata direttamente alla console, senza manipolare una scheda SD ad ogni prova. L'EverDrive 64 X7 di Krikzz offre anche una connessione USB e rimane un'opzione solida se ne hai già una. In entrambi i casi, copiare il file .z64 sulla scheda microSD della cartuccia è sufficiente per un semplice tentativo.
Un punto da tenere a mente: alcuni errori si manifestano solo sulla console, in particolare per quanto riguarda la gestione della memoria e le cache del processore. Un programma perfettamente stabile sotto l'aria può bloccarsi su un N64 originale, ed è proprio per questo che il collegamento USB di debug fa risparmiare così tanto tempo una volta che il progetto è serio.
Per andare oltre
La riferimento API documenta ogni funzione disponibile, e il wiki del progetto copre casi particolari di installazione di sistema per sistema. Il deposito awesome-n64-development individua strumenti, tutorial e documentazione tecnica della scena, e il sito N64 Squid offre una serie di tutorial progressivi particolarmente digeribili. Infine, il Discord n64brew, il cui invito figura sul deposito ufficiale, rimane il luogo in cui porre una domanda quando un crash resiste.