Getting Started Resources

N64brew’s Getting Started Resources page has been needing a bit of a cleanup for a while, so we’ve compiled this Google Docs as it’s better than dealing with Discord’s character limits. Use the labels on the left side of this document to quickly navigate through all the information. Alternatively, this video presentation covers a lot of the stuff here (and more), although it is a bit more technical due to being at a programmer’s event.

N64brew is catered towards making homebrew software or hardware. If you are interested in game modding, reverse engineering, emulator development, or other aspects related to the N64, you are welcome to ask at N64brew, but be aware that there are a lot of other servers where you are more likely to get help related to the other topics!

We have a Wiki!

It has a lot of useful accurate hardware documentation.

Brief notes about N64 Development

The Nintendo64 is not a beginner friendly platform. If you are a programmer and have absolutely no experience with low level programming (especially C), then it is highly recommended you instead learn that first (go to your local library or buy a book about C, any book will do). The N64 doesn’t have many safeguards in place if you make mistakes because it is expected that you know what you are doing, and you don’t really have access to strong step by step debuggers like you would on the PC (you can use GDB with a flashcart, but with some caveats). Programmers should be very familiar with pointers + structs, and have a decent understanding of operating systems. This free book is a fantastic resource for learning about Operating Systems if you need a place to start. You are not required to have any experience with Assembly (no retail game was made entirely with it), but it helps! If you want to use assembly, check out these videos made by fraser (the code for which is available here).

There is no such thing as “Unity for N64”. Do not expect to have a fully fledged engine you can just make anything with. This is because of how tight the constraints are on the system, you don’t really have the luxury of making generalized engines. For the most part, you are either going to have to make your own tools, or rely on community made ones. It’s also a good idea to temper your expectations. Don’t expect to jump into the system and make the next Goldeneye. This article titled 9 Reasons Why N64 Projects Fail is a very light and comprehensive read. Start small, and take it one step at a time!

A generative AI model will not generate a valid N64 ROM for you. GenAI models such as ChatGPT and similar are required to be trained on source code to generate source code. Almost all retail N64 games are closed source, so a model has no way to train on them. Furthermore, the source code which is available on the internet (ethics aside) is often using wildly disparate and incompatible SDKs (or even outdated versions of the same SDK), and are not even guaranteed to compile or work on hardware. If a model uses this as training data it will similarly generate source code which will not work. You will be wasting your time at best, or be told wildly inaccurate statements at worst.

Nowadays, it is possible to successfully develop a homebrew game that runs on a real N64 by using almost exclusively the most accurate emulator: Ares (see below). Ares will reproduce many weird corner cases of the N64 hardware, and in general what you obtain there is the same as what you would get on hardware. This said, there will always be differences and bugs, so remember to get your ROM tested on hardware every once in a while (the #rom-testing channel on N64brew will help with this). To test on hardware yourself, you need a N64 (which goes for $70 on eBay) and a flashcart (see below for options).

SDKs

In order to write software for the N64, you’ll need a Software Development Kit. You have two main SDKs of choice, libultra and libdragon. Installation instructions for both are provided below.

Libultra

This is the official Nintendo SDK (all commercial N64 games were made with this). Unfortunately it is proprietary, but historically Nintendo has never cared for homebrew so you should be safe using it as long as you don’t go boasting about it or sharing your source code with the proprietary libraries included (you can reference them in your code, just don’t include it in your project’s files). By using Libultra, you are assuming the risks of using an official SDK without a license and/or permission explicitly given by Nintendo.

There are many environments and methods to install Libultra, pick whichever one you prefer. Originally, Libultra was only available on either SGI systems or for up-to 32-Bit Windows machines. Thankfully, through many dedicated members of our community, we have alternative solutions available; the most popular of these is Modern SDK by CrashOveride. Modern SDK is not a completely different SDK, it is exactly the same as Libultra, however it swaps out the old and crusty 16-bit compilers + tools for modern equivalents. Be aware that moving projects between both SDKs will require some tweaking, as Modern SDK uses linker scripts for assembling the final ROM over Nintendo’s proprietary specfile solution. Not only that, the more modern compiler might introduce new behaviour in your ROM if you used any sort of undefined behaviour.

Linux with Modern SDK

Instructions for this setup can be found here.

Windows 10 with WSL (Modern SDK)

Pretty much the same as the above, but with WSL in Windows 10. Use the same instructions linked in the Linux with Modern SDK section.

Windows 95, 98, or XP (32-Bit)

This is arguably the “easiest” method, but not necessarily the best as you’re stuck using really old tools and sharing files between machines. You can use either an actual old computer, or a virtual machine. We’re not going to cover how to install the OS, we’ll assume that’s already taken care of. Get a copy of the latest OS CD (OS/PC – v2.0L), toolkit (Developer Toolkit – v5.2), and developer tools (Developer Tools – v1.06). Burn them to a CD or mount the ISOs, and then install the OS first, then the toolkit, then finally the developer tools. While not required, highly recommended you get the Developer Documents v5.2 disk as well. If you prefer, you can use this easy install CD maintained by CrashOveride, which includes all four disks.

You can also get SN64 or CodeWarrior, but these are really not recommended to be used because they’re incredibly finicky and even require special hardware to be used to their full extent. If you really insist, instructions for these are available here.

Linux or macOS with Wine

The official SDK should work fine with Wine for both Linux and macOS.

Modern Windows with DOSBox

If you really want to, you can use the official SDK (not the Modern one) on a modern 64-Bit Windows using DOSBox. Instructions for that can be found in this comment by Magstriker on N64brew. You also have this upgrade to that, created by Agahnim.

Silicon Graphics

If you have a Silicon Graphics machine, the ultra64 website also has CDs for those devices. However SGI’s are not recommended for development because the hardware is becoming very old and hard to replace, and most community tools will not support these machines.

Libdragon

Libdragon is a free and open source SDK. It is the work of many community members, and has its own pros and cons versus the official SDK. Libdragon is much easier to use and program for, is actively developed, has great tools for asset importing, and works out of the box on any modern operating system. It has support for 3D via either a complete OpenGL 1.1 implementation, currently available as a preview in the development branch, or the Tiny3D third party microcode. It also supports FMV via a RSP-accelerated MPEG1 player. Libdragon is fully compatible with N64 hardware and designed to use any corner of the hardware, so that it might not work well on some older emulators (Typically the ones that don’t care about accuracy, such as Project64).

You can learn more about how to make games with Libdragon reading: N64Brew: how to make a game with libdragon (2022)

Windows / Linux / Mac installation

Installing Libdragon requires two steps: first downloading a toolchain (or recompiling it from scratch, if you’re inclined to do so), and second downloading and building Libdragon itself with the toolchain.

The complete installation guide is available on Libdragon wiki. Remember that if you want to use 3D, you must stick to the preview branch of Libdragon.

Docker (Any OS)

An available alternative to install Libdragon is to use Docker. Instructions for this can be found here. Alternatively, if you have a Linux machine and you want to get Libdragon working well with Visual Studio Code, there’s a comprehensive video available by James Lambert here.

Other SDKs

Here is a list of other SDKs you can use, but be aware that they are currently in their infancy and are not really mature enough to make full projects with:

alt-libn64
pseultra
libreultra (a reverse engineering project of Libultra)

Tools

https://n64.dev contains a massive list of everything you’ll need in terms of community made tools for importing assets and stuff. For the most part, you can do everything you need from the comfort of your machine (no need to get an XP computer).

Development Hardware

This section will focus on flashcarts and not the official development hardware, because you are likely not part of the 1% that owns some. It is super recommended that you get a flashcart with USB because this will make your development process faster (no need to fiddle with SD cards), but also because this will let you use the USB for debugging with the help of a tool such as UNFLoader. There is also some support for gdb for both flashcarts and Ares

The best flashcart for development as of right now is the SummerCart64 (SC64). It is an open source flashcart with very fast USB and good development tooling. It is supported natively by Libdragon for all main debugging functionality (USB logging and SD file access), and you can get this same functionality on Libultra too using UNFLoader and Libcart.

If possible, you should try and get a SummerCart64 (or build it yourself if you have the skills!). If you can’t, the only other commercially available alternative right now with USB support is the EverDrive X7. Compared to SC64, it has much slower USB connection, and also it doesn’t allow for true booting of ROMs (you always have to go through the menu).

SummerCart64 (SC64)

https://summercart64.dev/

https://github.com/Polprzewodnikowy/SummerCart64

A fully open source flashcart. It’s 100% developer oriented with good documentation and Libdragon/Libcart integration. If you only care about playing games, you can use the open source N64FlashcartMenu available here.

Check the website for buying options, as they tend to evolve over time. At the time of writing, there is one shop regularly building and selling SC64 (Phenom Mod store). There are also group buys sometimes run on Discord, check the #sc64-forum channel at N64brew.

EverDrive 64 - KRIKzz

https://krikzz.com/our-products/cartridges/ed64x7.html

Recommended X7 or 3.0 (if you can get it secondhand). The USB is a bit slow (1MB per second), and it doesn’t boast the compatibility of the SummerCart64, but it works well enough.

64Drive (Out of Stock) - retroactive.be

https://64drive.retroactive.be/

This used to be the best flashcart option for development, but it is unfortunately out of market since 2020, and it is almost impossible to find second hand. Luckily, SummerCar64 was born meanwhile. If you have or can get your hand on a 64Drive, it will be just as good as the SC64.

PicoCart64

https://github.com/kbeckmann/PicoCart64

N64 flashcart based on a Raspberry Pi Pico. It is a cheap alternative, but consider that uploading a ROM is very slow as it must reflash. Currently under development, check GitHub and their Discord for buying options.

DREAMDrive64

https://dreamcraftindustries.com/products/dreamdrive64

Fork of PicoCart64 project. Instead of single flash memory for storage, an array of PSRAM chips are used. ROMs are loaded only through SD card. No Libdragon/Libcart/UNFLoader integration is implemented at this moment.

DaisyDrive64

https://github.com/nopjne/DaisyDrive64

Another in-development N64 flashcart, using a Daisy Seed MCU board.

El Barato 64

https://github.com/Hazematman/El-Barato-64

Open source, but currently untested.

Emulators

Currently, there is only one emulator which is recommended for development: Ares. All other emulators (including and especially those with a long history, like Project64 and mupen64-plus) are unfortunately very inaccurate and will fail to reproduce corner cases of hardware behaviors which are very easy to hit during development. You might be able to use them to play your game when it’s finished, but they are not recommended during development.

ares

https://ares-emu.net/

It is the most accurate N64 emulator to date, with also advanced tools to support homebrew development, like GDB step-by-step debugging, and DMA cache coherency checks. It requires a powerful computer and a vulkan compatible graphics card. By default, on Linux and macOS, the emulator opens with a terminal where printfs are piped to. For Windows users, you must run the emulator passing “--terminal”. Make sure to activate the “Homebrew mode” in settings.

The last version of Ares to support non-vulkan cards is v132, which can be downloaded from here.

gopher64

https://github.com/gopher64/gopher64

An N64 emulator written in Go. While not as accurate as ares, it sees regular fixes by its dev in order to ensure that Libdragon ROMs continue to work on it. Its dev was originally working on Simple64, but they have decided to switch their efforts to gopher64.

BizHawk

https://tasvideos.org/BizHawk

BizHawk is mostly used for Tool Assisted Speedrun development, however it comes with a lot of useful features, such as a RAM watch tool, Memory inspector, and debugger. Originally it came with a really old mupen64 core, but as of v2.8 it features ares core as a choice, so its emulation accuracy should be on par. This option might need to be purposefully selected, as it might not be the default.

CEN64

https://github.com/n64dev/cen64

CEN64 was designed to be as cycle accurate as possible (even though it’s not quite there yet), at the cost of the games running very slowly compared to other emulators. Lots of debugging capabilities, including GDB. Unfortunately, development has stalled, so the emulator does not get many updates, and its accuracy level has not kept up with Ares and gopher64. Given that it’s discontinued now, we advise against using it.

RetroArch + ParaLLEl

https://www.libretro.com/index.php/category/parallel/

One of the most accurate RDP emulators available, but no debugging tools.

MAME

https://www.mamedev.org/

Decently accurate emulator, with an assembly-level debugger and memory inspector. Struggles with emulating custom microcode, and doesn’t seem to support Libdragon ROMs.

Project64

https://www.pj64-emu.com/

Project64 is the most popular of emulators, and can run games at excellent performance... But it is also the worst one in terms of accuracy (it fails to run Libdragon games). Its biggest benefit, however, is the built-in debugger and its JavaScript Scripting capabilities. We would only recommend it as a last resort and recommend strict hardware testing.

I am an artist, what do I need to know?

You will need to know a bit about the system so that you can make stuff with the correct limitations in mind. If you have a programmer, ask them what approach you should take to models, audio, etc… The Nintendo 64’s graphics and audio is handled by a processor called the RCP, which uses something called “microcode” to tell it how to behave. The microcode being used, as well as how the project is set up, can vary significantly between homebrew, so always consult your team. They should be able to direct you regarding best practices. Tools for converting stuff should be available from the same places linked in the Tools section of this document.

Textures

The Nintendo 64 has a 4 kilobyte texture cache, and there is no way around this limitation. This means that large textures will need to be split up, or your color depth will need to be reduced. The first section of this document covers pretty much everything you need to know (the second section might not be relevant to you unless you’re using the texture converter the guide was written for).

3D Models

The N64 doesn’t really have any vertex or triangle limits, although typically keeping your vertex count as a power of two (2, 4, 8, 16, 32) is a good idea for optimization reasons. There are lots of numbers thrown around for how many polygons one should use to keep a game at 30fps, but this can vary based on a lot of factors (namely, microcode). 100,000 polygons per second is a good rough number (which means 3300 per frame at 30fps) but there are a lot of asterisks involved in that value. Mario in Super Mario 64 is composed of 752 triangles. The best way to ensure performance is to use as few textures as possible to reduce the need to load them into memory (which takes time). Use vertex colors when you can!

Typically, character models are either designed in “sausage link” form (where characters are made up of many completely separate shapes), but you can also use classic vertex skinning instead. Tiny3D supports a skeleton system out of the box with each vertex weight only assigned to one bone, while Libultra can support this but requires the feature to be implemented by the programmer. Which approach to take will, again, depend on the engine you’re making models for. Go bug your programmer!

Audio and Music

The N64 does not have a dedicated audio chip like many retro consoles, it mostly works with uncompressed or compressed sounds which are handled by the RCP. This means that it also depends on microcode, so you should ask your programmer what approach to take. But in general:

If you’re using the Libultra SDK, sounds should be in .aiff format and music should be MIDI.
If you’re using the Libdragon SDK, sounds should be in .wav format and music should be .xm tracker format.

Either SDK should have its own set of tools for sound and music conversion. Libultra has a set of command line tools called the SGI Audio Tools (instructions for which are here), but it also has a GUI program called the N64 SoundTools. This program is very finicky to use because it requires special hardware, but a guide for using and programming for it (without the special hardware) can be found here. Libdragon users should use audioconv64 (comes with the SDK).

Getting Started with N64 Programming

If you are using Libultra, there is a library called Nusys that comes with the Toolkit which is a great resource for when you’re getting started as it abstracts away a lot of the OS boilerplate. When you start becoming more familiar with the system, it’s recommended you ease your way out of it so that you can really use the system to its full potential. However both Libultra and Libdragon have a set of sample demos for you to learn from, showcasing all sorts of things that you can do with the SDK. You should definitely take a look at them first.

The Libultra samples are located in ultra\usr\src\pr\demos

In Modern SDK, they're in /usr/src/PR/demos/. You must install the demos via sudo apt install n64-demos

The Nusys samples are in nintendo\n64kit\nusys\sample

In Modern SDK, they're in /usr/src/PR/nusys/. You must install the demos via sudo apt install nusys-demos

If you installed the Libultra documents v5.2, you have extra samples inside the sample_prog folder
The Libdragon samples are inside the examples folder.

There are a few primer series for N64 development:

Libultra

Pyoro64 - This is a set of documents that contains step by step instructions on making a game from the ground up with Libultra, with the help of Nusys. Great for people who don’t have much experience with making games in C, but already have a strong understanding of the language.
N64 Squid’s Articles - Breaks down the nu0 and nu1 demos from Nusys, step by step.
Vanadium’s Articles - Written during the development of their Game Jam 2020 project, goes through all sorts of aspects regarding making a N64 game with Libultra on a modern system, without Nusys.

Libdragon

N64Squid Libdragon Tutorial - A tutorial series written by N64Squid about getting started with Libdragon.
Flappy Bird 64 - A set of blog posts by Meeq that covers how to make a clone of Flappy Bird using Libdragon.

Example Homebrew

Unfortunately, there is no “one stop place” for N64 homebrew, but we intend to fix this sometime in the future by making some pages for the wiki. In the meantime, this is a non comprehensive list of other open source homebrew games that you can use to learn from until we’ve migrated the links over to somewhere else:

Miscellaneous Useful Resources

If you are using libultra, READ THE PROGRAMMING MANUAL. If you are using libdragon, READ THE DOCUMENTATION. Seriously, RTFM.

N64 RSP (Reality Signal Processor) Documentation and Breakdown: https://github.com/rasky/r64emu/blob/master/doc/rsp.md

OpenGL SuperBible: First Edition - 1996 (BE AWARE THAT N64 DOES NOT USE OPENGL! CHECK FREQUENTLY ASKED QUESTIONS FOR MORE INFORMATION):

https://drive.google.com/drive/folders/1vGinpMXKWNFMDumBLV7hMZrK7Shb013-

Turok programmer "Steve Broumley" also recommended the "LEGACY TUTORIALS" section on this OpenGL website.

http://nehe.gamedev.net/

3D Computer Graphics using OpenGL

https://www.youtube.com/playlist?list=PLRwVmtr-pp06qT6ckboaOhnm9FxmzHpbY

Game Engine Development:

https://www.youtube.com/playlist?list=PLRwVmtr-pp04XomGtm-abzb-2M1xszjFx

Collision Detection Samples/Explanation

http://www.peroxide.dk/papers/collision/collision.pdf

3D Game Programming in C (1995)

https://archive.org/details/BlackArt3DEBook

Frequently Asked Questions

Q: Is the N64 any good at 2D?

A: Do not sleep on the N64’s 2D capabilities! It can do pretty much everything the SNES does, but just as good if not better. The only thing that the N64 struggles with is with raster effects, unless you are able to leverage the RCP in some way. The N64’s RAM latency is just too horrible to perform raster effects on the CPU.

Q: Can I use C++?

A: Yes, although be aware that official support for it is poor and that you should avoid using STL (due to memory and speed reasons).

Q: I've been told that the N64 uses OpenGL...

A: While it is true that the OpenGL API was created by Silicon Graphics (the developers of the N64 hardware), neither it nor its predecessor IrisGL are used directly by the N64. Libultra (used in commercial games) has a different graphics API that might recall some GL concepts, but it is quite different at every level. On the other hand, Libdragon now has a full OpenGL 1.1 implementation, with some N64-specific extensions to better use the hardware. So it is nowadays indeed possible to make a game with OpenGL on N64.

Q: I have questions about game hacking or reverse engineering.

A: You are free to ask, but be aware that this is a homebrew development server (AKA making our own games or hardware from scratch), so people's expertise will be more catered towards that. There are many, much more relevant servers regarding specific game hacking or reversing, and you are more likely to get useful answers there! A list of cool places is in the Other Servers to Check Out section.

Q: I have other doubts or questions.

A: You are always free to ask questions, don't be afraid! It is recommended that you show that you've put effort into your question, because people are less likely to assist you if you're being rude or not willing to learn. An example of a good structured question: "I'm trying to do X, but I got Y, but from my understanding of the manual section Z, that shouldn't be happening. How come?".

Other Servers to Check Out

If you are interested in other aspects regarding N64 development (be it hacking, reverse engineering, emulation, etc…) you should definitely check out some of these servers (please note that we are not affiliated with them):

Nintendo64 - General N64 discussion, emulators, and tech support.

https://discord.gg/jqPzxUVVMJ

Discord64 - General N64 development

https://discord.gg/sSkQTBpFhv

iQueBrew - Like us, but for the iQue Player specifically

https://discord.gg/SeZ3RPb

Project64 - The most popular N64 emulator

https://discord.gg/Cg3zquF

Emulation Development - While not N64 specific, it contains a vast wealth of resources and knowledgeable people, even for N64

https://discord.gg/dkmJAes

Hack64 - Hacking and modding N64 games

https://discord.gg/68WJ4TP