Criar um homebrew para Nintendo 64 com LibDragon: o guia completo para principiantes

A Nintendo 64 arrastou durante muito tempo a fama de ser uma máquina hostil ao desenvolvimento amador. A sua arquitetura MIPS, o coprocessador RSP e a documentação da época, ciosamente guardada, desencorajaram muitas vocações. A LibDragon mudou o cenário: é uma biblioteca de código aberto, com licença permissiva e escrita em C, que fornece tudo o que é preciso para dialogar com a consola sem passar pelo SDK oficial da Nintendo. É ela que move hoje a maior parte da cena N64 moderna, das demos técnicas às conversões completas como o Comix Zone 64 do Frogbull.

⚠️ Este guia reflete a situação a 1 de setembro de 2026. As ferramentas citadas evoluem depressa: o utilitário de linha de comandos libdragon-docker vai na v12.2.1, o emulador ares na versão 148 e o Gopher64 na v1.1.36 de 21 de agosto de 2026. Consulta as páginas de lançamentos antes de começar, porque os números de versão terão certamente mudado. Atenção também ao Simple64: durante muito tempo recomendado para testar homebrews, passou a modo de arquivo em fevereiro de 2025 e já não deve servir de referência.

Pré-requisitos

Vais precisar de: um PC com Windows, Linux ou macOS; Git instalado; Docker na versão 27.2.0 ou superior se optares pelo método recomendado abaixo; e algumas noções de C, ao menos saber o que é um ciclo e um ponteiro. Não é necessário qualquer conhecimento de assembly MIPS para começar. Prevê ainda um emulador rigoroso para testar e, mais tarde, um cartucho flash se quiseres ver o teu programa a correr na própria consola.

Passo 1: instalar o ambiente de compilação

Abrem-se dois caminhos. O mais simples, e o que a documentação aconselha aos principiantes, passa pelo libdragon-docker, um utilitário que encapsula todo o toolchain num contentor: não precisas de perceber de Docker para o usar, apenas de o ter instalado. No Windows, descarrega e executa o instalador a partir da página de lançamentos, ignorando o aviso de segurança do sistema. No macOS e no Linux, obtém o executável correspondente ao teu sistema e coloca-o no PATH, respetivamente em /usr/local/bin e em ~/.local/bin, exigindo este último caso um chmod u+x ~/.local/bin/libdragon. Se já tiveres Node.js 24 ou superior na máquina, um simples npm install -g libdragon também resolve.

A segunda via consiste em instalar o toolchain de forma nativa, sem contentor, recorrendo aos binários pré-compilados publicados na página de lançamento dedicada: um pacote .deb para Debian e Ubuntu, um .rpm para Fedora e um arquivo .zip para Windows. Nesse caso é preciso definir a variável de ambiente N64_INST a apontar para a pasta de instalação e depois compilar a biblioteca com ./build.sh. No Windows este método exige ainda um terminal MSYS2 UCRT64. Existe uma terceira opção, compilar o toolchain a partir das fontes com ./build-toolchain.sh, mas leva mais de uma hora e cerca de 7 GB de espaço temporário: guarda-a para mais tarde.

Passo 2: criar o primeiro projeto

Coloca-te numa pasta vazia, de preferência um repositório Git acabado de iniciar, e executa libdragon init. O comando gera um projeto esqueleto, incorpora uma cópia da LibDragon junto ao teu código e descarrega a imagem do toolchain. A primeira chamada demora alguns minutos por causa da descarga. Ficas com uma árvore pronta a usar, com um ficheiro fonte, uma Makefile e a biblioteca.

Um pormenor de vocabulário merece atenção: a LibDragon tem dois ramos. O trunk é o ramo estável, com compromisso de compatibilidade retroativa, e é o que deves escolher para começar. O preview contém as funcionalidades em desenvolvimento, com uma API que pode mudar sem aviso. Muitos tutoriais que circulam online misturam os dois, o que explica boa parte dos erros de compilação com que os principiantes esbarram.

Passo 3: compilar e obter a ROM

A compilação resume-se a um comando: libdragon make. Se optaste pela instalação nativa, basta um make. O resultado é um ficheiro .z64, o formato de ROM da consola, executável diretamente tanto em emulador como em hardware real.

Vale a pena espreitar a Makefile, porque é curta e tudo se decide em duas linhas. A diretiva include $(N64_INST)/include/n64.mk importa as regras de compilação oficiais, as que transformam automaticamente os teus ficheiros .c em objetos, depois num ficheiro .elf e por fim numa ROM .z64. A variável N64_ROM_TITLE define o título inscrito no cabeçalho do cartucho, e BUILD_DIR a pasta onde aterram os ficheiros intermédios. Para acrescentar um ficheiro fonte ao projeto basta juntá-lo à lista OBJS como objeto a produzir.

Passo 4: perceber o esqueleto de um programa

Um programa LibDragon começa por um #include <libdragon.h>, a par dos cabeçalhos habituais de C. No main(), duas chamadas assentam os alicerces: display_init(), que recebe a resolução, a profundidade de cor, o número de buffers e os filtros, numa forma do tipo display_init(RESOLUTION_320x240, DEPTH_32_BPP, 2, GAMMA_NONE, FILTERS_RESAMPLE), e joypad_init() para a gestão dos comandos.

Segue-se o ciclo principal, que respeita sempre o mesmo ritmo: obténs uma superfície de desenho com display_get(), desenhas sobre ela, envias-la para o ecrã com display_show() e lês as entradas com joypad_poll() e depois joypad_get_buttons_pressed(). Inicialização, renderização, entradas, visualização: esse esquema aparece em praticamente todos os projetos da cena. A pasta examples do repositório está cheia de programas curtos que declinam este esqueleto, e é de longe a melhor forma de aprender.

Passo 5: testar a ROM num emulador

Nem todos os emuladores de N64 servem igualmente para desenvolver. Muitos foram concebidos para correr o catálogo comercial e tomam liberdades com o hardware, o que dá resultados enganadores: um homebrew pode aparecer na perfeição neles e bloquear na consola. Hoje destacam-se duas opções. O ares, na versão 148 desde maio de 2026, emula a baixo nível e usa Parallel-RDP através de Vulkan, o que pressupõe um PC com placa gráfica dedicada compatível. O Gopher64, na v1.1.36 desde 21 de agosto de 2026, é a alternativa moderna ao Simple64, cujo testemunho recolheu. Testa de preferência em ambos: uma diferença de comportamento entre eles denuncia quase sempre um bug no teu código.

Passo 6: executar o homebrew numa Nintendo 64 verdadeira

A passagem para hardware real exige um cartucho flash. A SummerCart64 é a referência para desenvolvimento: inteiramente de código aberto, integra uma ligação USB de depuração que envia uma ROM acabada de compilar diretamente para a consola, sem andar a trocar cartões SD a cada tentativa. O EverDrive 64 X7 da Krikzz também oferece ligação USB e continua a ser uma opção sólida se já tiveres um. Em ambos os casos, copiar o ficheiro .z64 para o cartão microSD do cartucho chega para um teste rápido.

Convém ter presente um pormenor: certos erros só se manifestam na consola, sobretudo os que envolvem a gestão de memória e as caches do processador. Um programa perfeitamente estável sob o ares pode ficar congelado numa N64 original, e é precisamente por isso que a ligação USB de depuração poupa tanto tempo quando o projeto começa a ficar sério.

Para ir mais longe

A referência da API documenta cada função disponível, e o wiki do projeto cobre os casos particulares de instalação sistema a sistema. O repositório awesome-n64-development reúne ferramentas, tutoriais e documentação técnica da cena, e o site N64 Squid propõe uma série de tutoriais progressivos particularmente digeríveis. Por fim, o Discord n64brew, cujo convite consta do repositório oficial, continua a ser o sítio onde perguntar quando um bloqueio resiste.

Fonte: LibDragon no GitHub