Desarrollar un homebrew de Nintendo 64 con LibDragon: la guía completa para principiantes

La Nintendo 64 arrastró durante mucho tiempo la fama de ser una máquina hostil al desarrollo amateur. Su arquitectura MIPS, su coprocesador RSP y la documentación de la época, celosamente guardada, desanimaron a más de una vocación. LibDragon cambió las cosas: es una biblioteca de código abierto, con licencia permisiva y escrita en C, que aporta todo lo necesario para dialogar con la consola sin pasar por el SDK oficial de Nintendo. Hoy es la que mueve la mayor parte de la escena N64 moderna, desde demos técnicas hasta conversiones completas como el Comix Zone 64 de Frogbull.

⚠️ Esta guía refleja la situación a 1 de septiembre de 2026. Las herramientas citadas evolucionan deprisa: la utilidad de línea de comandos libdragon-docker va por la v12.2.1, el emulador ares por la versión 148 y Gopher64 por la v1.1.36 del 21 de agosto de 2026. Consulta las páginas de lanzamientos antes de empezar, porque los números de versión seguramente habrán cambiado. Ojo también con Simple64: durante mucho tiempo recomendado para probar homebrews, pasó a modo archivo en febrero de 2025 y ya no debe usarse como referencia.

Requisitos previos

Necesitas: un PC con Windows, Linux o macOS; Git instalado; Docker en versión 27.2.0 o superior si eliges el método recomendado más abajo; y algunas nociones de C, al menos saber qué es un bucle y un puntero. No hace falta ningún conocimiento de ensamblador MIPS para empezar. Prevé además un emulador preciso para las pruebas y, más adelante, un cartucho flash si quieres ver tu programa funcionando en la propia consola.

Paso 1: instalar el entorno de compilación

Se abren dos caminos. El más sencillo, y el que la documentación aconseja a los principiantes, pasa por libdragon-docker, una utilidad que encapsula todo el toolchain en un contenedor: no necesitas entender Docker para usarla, solo tenerlo instalado. En Windows, descarga y ejecuta el instalador desde la página de lanzamientos, ignorando la advertencia de seguridad del sistema. En macOS y Linux, coge el ejecutable correspondiente a tu sistema y colócalo en tu PATH, en /usr/local/bin y en ~/.local/bin respectivamente, requiriendo este último caso un chmod u+x ~/.local/bin/libdragon. Si ya tienes Node.js 24 o superior en la máquina, un simple npm install -g libdragon también sirve.

La segunda vía consiste en instalar el toolchain de forma nativa, sin contenedor, usando los binarios precompilados publicados en la página de lanzamiento dedicada: un paquete .deb para Debian y Ubuntu, un .rpm para Fedora y un archivo .zip para Windows. En ese caso hay que definir la variable de entorno N64_INST apuntando a la carpeta de instalación y después compilar la biblioteca con ./build.sh. En Windows este método exige además un terminal MSYS2 UCRT64. Existe una tercera opción, compilar el toolchain desde las fuentes mediante ./build-toolchain.sh, pero requiere más de una hora y unos 7 GB de espacio temporal: déjala para más adelante.

Paso 2: crear el primer proyecto

Sitúate en una carpeta vacía, preferiblemente un repositorio Git recién iniciado, y ejecuta libdragon init. El comando genera un proyecto esqueleto, incorpora una copia de LibDragon junto a tu código y descarga la imagen del toolchain. La primera llamada tarda unos minutos por la descarga. Obtienes un árbol listo para usar con un archivo fuente, un Makefile y la biblioteca.

Un detalle de vocabulario merece atención: LibDragon tiene dos ramas. trunk es la rama estable, con compromiso de compatibilidad hacia atrás, y es la que hay que elegir para empezar. preview contiene las funciones en desarrollo, con una API que puede cambiar sin aviso. Muchos tutoriales que circulan por internet mezclan ambas, lo que explica buena parte de los errores de compilación con los que topan los principiantes.

Paso 3: compilar y obtener la ROM

La compilación se resume en un comando: libdragon make. Si optaste por la instalación nativa, basta con un make. El resultado es un archivo .z64, el formato de ROM de la consola, ejecutable directamente tanto en emulador como en hardware real.

Vale la pena echar un vistazo al Makefile, porque es corto y todo se juega en dos líneas. La directiva include $(N64_INST)/include/n64.mk importa las reglas de compilación oficiales, las que convierten automáticamente tus archivos .c en objetos, luego en un archivo .elf y finalmente en una ROM .z64. La variable N64_ROM_TITLE define el título escrito en la cabecera del cartucho, y BUILD_DIR la carpeta donde aterrizan los archivos intermedios. Para añadir un archivo fuente al proyecto basta con incorporarlo a la lista OBJS como objeto a producir.

Paso 4: entender el esqueleto de un programa

Un programa LibDragon empieza con un #include <libdragon.h>, junto a las cabeceras habituales de C. En el main(), dos llamadas asientan los cimientos: display_init(), que recibe la resolución, la profundidad de color, el número de búferes y los filtros, con una forma del tipo display_init(RESOLUTION_320x240, DEPTH_32_BPP, 2, GAMMA_NONE, FILTERS_RESAMPLE), y joypad_init() para la gestión de los mandos.

Llega después el bucle principal, que sigue siempre el mismo ritmo: recuperas una superficie de dibujo con display_get(), dibujas sobre ella, la envías a la pantalla con display_show() y lees las entradas con joypad_poll() y luego joypad_get_buttons_pressed(). Inicialización, renderizado, entradas, visualización: ese esquema aparece en prácticamente todos los proyectos de la escena. La carpeta examples del repositorio está repleta de programas cortos que declinan este esqueleto, y es de lejos la mejor manera de aprender.

Paso 5: probar la ROM en un emulador

No todos los emuladores de N64 valen igual para desarrollar. Muchos se concibieron para ejecutar el catálogo comercial y se toman libertades con el hardware, lo que arroja resultados engañosos: un homebrew puede verse perfectamente en ellos y colgarse en la consola. Hoy destacan dos opciones. ares, en la versión 148 desde mayo de 2026, emula a bajo nivel y usa Parallel-RDP mediante Vulkan, lo que supone un PC con tarjeta gráfica dedicada compatible. Gopher64, en v1.1.36 desde el 21 de agosto de 2026, es la alternativa moderna a Simple64, cuyo testigo recogió. Prueba preferiblemente en ambos: una diferencia de comportamiento entre ellos casi siempre delata un fallo en tu código.

Paso 6: ejecutar el homebrew en una Nintendo 64 real

El salto al hardware real exige un cartucho flash. La SummerCart64 es la referencia para desarrollar: totalmente de código abierto, integra un enlace USB de depuración que envía una ROM recién compilada directamente a la consola, sin trasegar tarjetas SD en cada intento. El EverDrive 64 X7 de Krikzz también ofrece conexión USB y sigue siendo una opción sólida si ya tienes uno. En ambos casos, copiar el archivo .z64 en la tarjeta microSD del cartucho basta para una prueba rápida.

Conviene tener presente un detalle: ciertos errores solo se manifiestan en la consola, sobre todo los relacionados con la gestión de memoria y las cachés del procesador. Un programa perfectamente estable bajo ares puede quedarse congelado en una N64 original, y precisamente por eso el enlace USB de depuración ahorra tantísimo tiempo cuando el proyecto se pone serio.

Para ir más lejos

La referencia de la API documenta cada función disponible, y el wiki del proyecto cubre los casos particulares de instalación sistema por sistema. El repositorio awesome-n64-development recopila herramientas, tutoriales y documentación técnica de la escena, y el sitio N64 Squid ofrece una serie de tutoriales progresivos especialmente digeribles. Por último, el Discord n64brew, cuya invitación figura en el repositorio oficial, sigue siendo el lugar donde preguntar cuando un cuelgue se resiste.

Fuente: LibDragon en GitHub