SimpleN64Demo

⚠️ IMPORTANT: These demo applications are not affiliated with Nintendo. ⚠️
THEY ARE FOR EDUCATIONAL PURPOSES ONLY.

What is this?

A simple Nintendo 64 application using Nintendo libraries.
Includes a script for automatically setting up the N64 SDK on modern Linux distributions.

├── SimpleN64Demo       // Demo using libultra
└── SimpleN64DemoNusys  // Demo using NuSystem abstraction layer

🔨 Setup toolchain and SDK

Building using Docker

This will build the n64chain in Docker without the need to install any host dependencies.
This is the recommended way to setup the toolchain.

Run:

make dockersetup

Then optionally run:

make dockerbuild

To build the N64 apps (the Docker image takes about 3GB of disk space).

Otherwise if on Linux just run:

source init_n64_env.sh

to initialize the environment to enable direct builds on host PC.

[OPTIONAL] Building toolchain natively on host

⚠️ NOTE: This might not work on modern distros with new versions of GCC.

For Debian/Ubuntu/Fedora run:

make deps

For other Linux distributions you will have to install the dependencies manually.
Look in the package list for Debian or Fedora to get an idea of what is needed.

Then directly run:

./setup_n64_toolchain.sh

This will take a while (the n64chain will take about 1GB of disk space when done).
After that just source the init script like so (this will be done automatically in VSCodes integrated terminal):

source init_n64_env.sh

Problems

If you get an error message when building stating something like:

../mips64-elf/bin/as: error while loading shared libraries: libopcodes-2.34.so: cannot open shared object file: No such file or directory

You will need to set LD_LIBRARY_PATH to point to the lib directory of the toolchain:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$N64_TOOLCHAIN/tools/x86_64-pc-linux-gnu/mips64-elf/lib/

Emulators

gopher64 is included when setting up the n64chain.

Cen64 is also included when setting up the n64chain.

A useful alias for running cen64 with multithread support:

alias cen64mt="cen64 -multithread -noaudio $N64_TOOL_CHAIN/tools/bin"

More emulators here.

Debugging using VSCode and GDB

It is possible to debug the N64 app using GDB.
This has been setup with Visual Studio Code.

Prerequisites

• Visual Studio Code
• C/C++ Extension Pack
• gdb-multiarch (GNU Debugger with support for multiple architectures)

With cen64 setup as the N64 emulator just run:

make debug

to start the GDB server on port 8080.
Then press F5 in VSCode to connect to the GDB server.
If a breakpoint has been set in the code, GDB will pause the execution at that point.

⭐ Useful links

Developing software for the N64 can be challenging. Here are some useful links to help you get started.

Awesome N64 Development

Nintendo 64 Development Resource

Nintendo 64 Online Manuals

Nintendo 64 Architecture

Debugging Nintendo 64 ROMs with GDB and Cen64

Wavefront OBJ model converter

Nintendo 64 Programming notes

Nintendo 64 modern SDK

n64chain

Nintendo 64 homebrew demo & tutorial