Pseultra

From N64brew Wiki
Jump to navigation Jump to search

pseultra is feature-rich, open-source alternative to the official N64 SDK. The biggest benefit of developing with an open-source SDK is that open-source code is legal to redistribute in your homebrew game (as long as you ensure you're not using any proprietary Nintendo code at all or infringing on other copyrights), and better support for modern operating systems (such as Windows 10 and Linux). The official pseultra repository is available on GitHub, and the "Getting Started" section of the readme explains how to set it up on macOS or Linux. Please note that there is a slight error in the current "Getting Started" instructions, as some users have reported that you must run scons && sudo scons install in the tools directory before running it in the root directory.

There is also a fork of pseultra with pre-built binaries for MSYS2 (Windows) x64, along with several merged features, updates, and patches. The following section describes how to set up an MSYS2 environment with pre-built pseultra binaries.

Windows

The following instructions will help you set up a pseultra development environment on Windows with MSYS2 and n64chain.

  1. Download and install the latest 64-bit MSYS2 from: msys2.org.
  2. Download the latest n64chain binaries from: cen64.com. Make sure you download the binaries under the section titled "n64chain Downloads" rather than the CEN64 emulator.
  3. Extract the n64chain package, move the tools directory into C:\msys64\opt, and rename tools to n64chain.
  4. Download and extract pseultra-chksum64-binaries.zip, open the extracted pseultra-chksum64-binaries folder, and move the pseultra and chksum64 directories into C:\msys64\opt.

macOS & Linux

Please follow the "Getting Started" instructions in either of the linked repositories above. While the Windows one is an unofficial fork, it does contain some updates and patches that are likely to be beneficial to UNIX users also.

Initializing a Project

pseultra's build system integration is still a work-in-progress. Thus, currently a simple shell script is used to automate the building of a ROM from a single C source file. This section explains how to download and use the template project and build script, which you can then customize as much as you want. (Here, we assume the Windows setup described above; if you're using a different platform or toolchain, the most important thing to adjust will be the assignment of the PATH environment variable in build.sh. Additionally, make sure you have a copy of the chksum64 application which is bundled with pseultra in the binaries linked above).

  1. Download and extract pseultra-project.zip, optionally renaming the extracted pseultra-project directory to something more appropriate for your project.
  2. Take the first 4096 bytes of a big-endian N64 ROM and copy them to a separate file called nintendo-boot-template.n64, placing that file in the root directory of your project (next to build.sh). If you want, you can keep a copy of this file in another location, separate from your project, and re-use it again later. This is the non-free part discussed below in the section "A Note About Bootloaders."
  3. Run build.sh inside an MSYS2 shell. The final output should be located inside build\main-linked-nintendo-boot.n64. Run this ROM with CEN64, and you should see a spinning cube!
  4. Use this project as a starting point for your own N64 software.

A Note About Bootloaders

The official Nintendo bootloader (known more specifically as the IPL3) is the only non-open-source component required to build N64 games with pseultra, thus inhibiting free and unencumbered distribution of your homebrew games. Thankfully, though, work is ongoing in the N64brew community to write a completely open-source replacement for the IPL3, and once that is accomplished, the template project and above instructions will be adjusted accordingly.