Développer un homebrew Nintendo 64 avec LibDragon : le guide complet pour débutant

La Nintendo 64 a longtemps eu une réputation de machine hostile au développement amateur. Son architecture MIPS, son coprocesseur RSP et sa documentation d'époque jalousement gardée ont découragé bien des vocations. LibDragon a changé la donne : c'est une bibliothèque open source, sous licence permissive et écrite en C, qui fournit tout ce qu'il faut pour parler à la console sans passer par le SDK officiel de Nintendo. C'est elle qui motorise aujourd'hui l'essentiel de la scène N64 moderne, des démos techniques aux portages complets comme le Comix Zone 64 de Frogbull.

⚠️ Ce guide vise la situation au 1er septembre 2026. Les outils cités évoluent vite : l'outil en ligne de commande libdragon-docker en est à la v12.2.1, l'émulateur ares à la version 148 et Gopher64 à la v1.1.36 du 21 août 2026. Vérifie les pages de releases avant de commencer, les numéros de version auront sans doute bougé depuis. À noter aussi : Simple64, longtemps recommandé pour tester des homebrews, est passé en archive en février 2025 et ne doit plus servir de référence.

Prérequis

Il te faut : un PC sous Windows, Linux ou macOS ; Git installé ; Docker en version 27.2.0 ou supérieure si tu choisis la méthode recommandée ci-dessous ; et quelques notions de C, ne serait-ce que savoir ce qu'est une boucle et un pointeur. Aucune connaissance de l'assembleur MIPS n'est nécessaire pour démarrer. Prévois aussi un émulateur précis pour tester, et à terme une cartouche flash si tu veux voir ton programme tourner sur la console elle-même.

Étape 1 : installer l'environnement de compilation

Deux chemins s'offrent à toi. Le plus simple, et celui que la documentation conseille aux débutants, passe par libdragon-docker, un utilitaire qui encapsule tout le toolchain dans un conteneur : tu n'as pas besoin de comprendre Docker pour t'en servir, seulement de l'avoir installé. Sur Windows, télécharge et lance l'installateur depuis la page des releases, en ignorant l'avertissement de sécurité du système. Sur macOS et Linux, récupère l'exécutable correspondant à ton système et place-le dans ton PATH, respectivement dans /usr/local/bin et dans ~/.local/bin, ce dernier cas nécessitant un chmod u+x ~/.local/bin/libdragon. Si Node.js 24 ou supérieur est déjà présent sur ta machine, un simple npm install -g libdragon fait aussi l'affaire.

La seconde voie consiste à installer le toolchain nativement, sans conteneur, en récupérant les binaires précompilés publiés sur la page de release dédiée : un paquet .deb pour Debian et Ubuntu, un .rpm pour Fedora, une archive .zip pour Windows. Dans ce cas il faut définir la variable d'environnement N64_INST vers le dossier d'installation, puis compiler la bibliothèque avec ./build.sh. Sous Windows cette méthode réclame en plus un terminal MSYS2 UCRT64. Une troisième option existe, la compilation du toolchain depuis les sources via ./build-toolchain.sh, mais elle demande plus d'une heure et environ 7 Go d'espace temporaire : garde-la pour plus tard.

Étape 2 : créer son premier projet

Place-toi dans un dossier vide, de préférence un dépôt Git fraîchement initialisé, puis lance libdragon init. La commande fabrique un projet squelette, y intègre une copie de LibDragon versionnée avec ton code, et télécharge l'image du toolchain. Le premier appel prend quelques minutes, le temps du téléchargement. Tu obtiens une arborescence prête à l'emploi avec un fichier source, un Makefile et la bibliothèque.

Un point de vocabulaire mérite ton attention : LibDragon propose deux branches. trunk est la branche stable, avec un engagement de compatibilité ascendante, et c'est celle qu'il faut choisir pour débuter. preview contient les fonctionnalités en cours de développement, avec une API susceptible de changer sans préavis. Beaucoup de tutoriels trouvés en ligne mélangent les deux, ce qui explique une bonne partie des erreurs de compilation rencontrées par les débutants.

Étape 3 : compiler et obtenir sa ROM

La compilation tient en une commande : libdragon make. Si tu as opté pour l'installation native, un simple make suffit. Le résultat est un fichier .z64, le format de ROM de la console, directement exécutable sur émulateur comme sur matériel réel.

Le Makefile mérite un coup d'oeil, car il est court et tout se joue dans deux lignes. La directive include $(N64_INST)/include/n64.mk importe les règles de compilation officielles, celles qui transforment automatiquement tes fichiers .c en objets, puis en fichier .elf, puis en ROM .z64. La variable N64_ROM_TITLE définit le titre inscrit dans l'en-tête de la cartouche, et BUILD_DIR le dossier où atterrissent les fichiers intermédiaires. Pour ajouter un fichier source à ton projet, il suffit de l'ajouter à la liste OBJS sous forme d'objet à produire.

Étape 4 : comprendre le squelette d'un programme

Un programme LibDragon commence par un #include <libdragon.h>, aux côtés des en-têtes C habituels. Dans le main(), deux appels posent les fondations : display_init(), qui prend la résolution, la profondeur de couleur, le nombre de tampons et les filtres, dans une forme du type display_init(RESOLUTION_320x240, DEPTH_32_BPP, 2, GAMMA_NONE, FILTERS_RESAMPLE), et joypad_init() pour la gestion des manettes.

Vient ensuite la boucle principale, qui suit toujours le même rythme : tu récupères une surface de dessin avec display_get(), tu dessines dessus, tu l'envoies à l'écran avec display_show(), et tu lis les entrées avec joypad_poll() puis joypad_get_buttons_pressed(). Initialisation, rendu, entrées, affichage : ce schéma se retrouve dans à peu près tous les projets de la scène. Le dossier examples du dépôt regorge de programmes courts qui déclinent ce squelette, et c'est de loin la meilleure façon d'apprendre.

Étape 5 : tester sa ROM sur émulateur

Tous les émulateurs N64 ne se valent pas pour du développement. Beaucoup ont été conçus pour faire tourner les jeux commerciaux du catalogue et prennent des libertés avec le matériel, ce qui donne des résultats trompeurs : un homebrew peut parfaitement s'afficher chez eux et planter sur la console. Deux choix s'imposent aujourd'hui. ares, en version 148 depuis mai 2026, émule à bas niveau et utilise Parallel-RDP via Vulkan, ce qui suppose un PC équipé d'une carte graphique dédiée compatible. Gopher64, en v1.1.36 depuis le 21 août 2026, constitue l'alternative moderne à Simple64, dont il a repris le flambeau. Teste de préférence sur les deux : une différence de comportement entre eux signale presque toujours un bug dans ton code.

Étape 6 : lancer son homebrew sur une vraie Nintendo 64

Le passage sur matériel réel nécessite une cartouche flash. La SummerCart64 est le choix de référence pour le développement : entièrement open source, elle intègre une liaison USB de débogage qui permet d'envoyer une ROM fraîchement compilée directement à la console, sans manipuler de carte SD à chaque essai. L'EverDrive 64 X7 de Krikzz propose également une connexion USB et reste une option solide si tu en possèdes déjà une. Dans les deux cas, copier le fichier .z64 sur la carte microSD de la cartouche suffit pour un simple essai.

Un point à garder en tête : certaines erreurs ne se manifestent que sur la console, notamment tout ce qui touche à la gestion mémoire et aux caches du processeur. Un programme parfaitement stable sous ares peut se figer sur une N64 d'origine, et c'est précisément pour cette raison que la liaison USB de débogage fait gagner tellement de temps une fois le projet sérieux.

Pour aller plus loin

La référence de l'API documente chaque fonction disponible, et le wiki du projet couvre les cas particuliers d'installation système par système. Le dépôt awesome-n64-development recense outils, tutoriels et documentation technique de la scène, et le site N64 Squid propose une série de tutoriels progressifs particulièrement digestes. Enfin, le Discord n64brew, dont l'invitation figure sur le dépôt officiel, reste l'endroit où poser une question quand un plantage résiste.

Source : LibDragon sur GitHub