Powerstar Engine

this is based on ultrasm64 with some custom changes and patches from other projects

• This repo contains a full decompilation of Super Mario 64 (J), (U), (E), and (SH).
• It has been edited to allow for the usage of the final "N64 OS" library, version 2.0L
• Shindou Rumble Pak code is on for all regions.
• Targeting the iQue Player is supported.
• Saving to 32kbyte/256kbit SRAM is supported.
• Newer compression options are supported.
• UNFLoader (flashcart USB library) is supported, allowing for debugging on EverDrive/64Drive.
• It has been patched with someone2639's shiftable segments patch
• Wiseguy's instant input patch has been added to allow for less input lag on emulation (Does not affect console) This does mean that any framebuffer effects will have to be done on buffer 0 if targeting emulators
• Automatic console and emulator detection: Use the gIsConsole variable to wrap your code in an emulator check.
• Separate defines for emulator and console black border height.
• Getting HVQM FMV support to work with the game is WIP.
• odyssey and sunshine movement
• reonucam3 ~ disabled aa
• and minor options like to disable texture filtering, enable debug level select, skip peach

Additional Prerequisites

BinPNG (the CI texture converter) requires some python3 dependencies. Use pip to install them.

pip install pypng bitstring

UNFLoader support

The repository supports UNFLoader for debugging.

To build with UNF, run make with UNF=1.

Further instructions can be found at the official repository

NOTE: Closing the UNFLoader window will result in your game eventually hanging due to lacking a USB device to send messages to, so beware of that

Multi-Save support

The repository supports SRAM in addition to EEPROM. The standard save data functions are #ifdef'd to accommedate this.

To build with SRAM support, run make with SAVETYPE=sram.

I may attempt FlashRAM in the future.

Multi-Console support

The repository supports targeting the iQue Player in addition to the N64. The iQue libultra is NOT compatible with N64 in many ways, so it is currently NOT possible to have one build for both consoles.

To target iQue, run make with the CONSOLE=bb argument.

Compression

The repo also supports RNC (Rob Northen Compression). and gzip.

gzip with libdeflate is the default.

RNC has two methods.

Method 1 is designed to compress as small as possible, while method 2 is designed so that decompression is as fast as possible.

Method 1 is the best all-rounder in terms of speed and ratio.

Both methods are fast. Method 1 has better compression than 2, so I suggest using method 1 if using RNC.

To switch to RNC, run make with either COMPRESS=rnc1 or COMPRESS=rnc2, depending on preferred method.

The repository also supports using DEFLATE compression. This boasts a better compression ratio, but at a slight cost to load times.

On average I'd estimate that the bottleneck on decompression is about 1-2 seconds.

To switch to gzip, run make with the COMPRESS=gzip argument.

The repo also supports building a ROM with no compression.

This is not recommended as it increases ROM size significantly, with little point other than load times decreased to almost nothing.

To switch to no compression, run make with the COMPRESS=uncomp argument.

FAQ

Q: Why in the hell are you bundling your own build of ld?

A: Newer binutils (Like the one bundled with Ubuntu, 2.34) break linking with libultra builds due to local asm symbols.

This puts me at a crossroads of either touching leaked code and requiring GCC, or just using an older linker that works just fine.

I went with the latter.

Thanks to "someone2639" for this hacky-ass idea

Q: Will this allow me to use FlashRAM/Transfer Pak/microcode swapping/Other Cool N64 Features?

A: Theoretically, all yes.

Installation

Linux

There are 3 steps to set up a working build.

Step 1: Install dependencies

The build system has the following package requirements:

• binutils-mips
• capstone
• pkgconf
• python3 >= 3.6
• libdeflate

Dependency installation instructions for common Linux distros are provided below:

Arch Linux

To install build dependencies:

sudo pacman -S base-devel capstone python libdeflate

Install the following AUR packages:

• mips64-elf-binutils (AUR)
• mips64-elf-gcc-stage1 (AUR)

Debian / Ubuntu

To install build dependencies:

sudo apt install -y binutils-mips-linux-gnu build-essential git libcapstone-dev pkgconf python3 gcc-mips-linux-gnu

Other Linux distributions

Most modern Linux distributions should have equivalent packages to the other two listed above. You may have to use a different version of GNU binutils. Listed below are fully compatible binutils distributions with support in the makefile, and examples of distros that offer them:

• mips64-elf- (Arch AUR)
• mips-linux-gnu- (Ubuntu and other Debian-based distros)
• mips64-linux-gnu- (RHEL/CentOS/Fedora)

Step 2: Copy baserom(s) for asset extraction

For each version (jp/us/eu/sh) for which you want to build a ROM, put an existing ROM at ./baserom.<VERSION>.z64 for asset extraction.

Step 3: Build the ROM

Run make to build the ROM (defaults to VERSION=us). Other examples:

make VERSION=jp -j4       # build (J) version instead with 4 jobs
make VERSION=eu COMPARE=0 # build (EU) version but do not compare ROM hashes

Resulting artifacts can be found in the build directory.

The full list of configurable variables are listed below, with the default being the first listed:

• VERSION: us, jp, eu, sh
• GRUCODE: f3d_old, f3d_new, f3dex, f3dex2, f3dzex
• COMPARE: 1 (compare ROM hash), 0 (do not compare ROM hash)
• NON_MATCHING: Use functionally equivalent C implementations for non-matchings (Currently there aren't any non-matchings, but this will apply to iQue). Also will avoid instances of undefined behavior.
• CROSS: Cross-compiler tool prefix (Example: mips64-elf-).

macOS

Homebrew

Step 1: Install dependencies

Install Homebrew and the following dependencies:

brew update
brew install capstone coreutils make pkg-config tehzz/n64-dev/mips64-elf-binutils

Step 2: Copy baserom(s) for asset extraction

For each version (jp/us/eu/sh) for which you want to build a ROM, put an existing ROM at ./baserom.<VERSION>.z64 for asset extraction.

Step 3: Build the ROM

Use Homebrew's GNU make because the version included with macOS is too old.

gmake VERSION=jp -j4       # build (J) version instead with 4 jobs

Resulting artifacts can be found in the build directory.

Project Structure

sm64
├── actors: object behaviors, geo layout, and display lists
├── asm: handwritten assembly code, rom header
│   └── non_matchings: asm for non-matching sections
├── assets: animation and demo data
│   ├── anims: animation data
│   └── demos: demo data
├── bin: C files for ordering display lists and textures
├── build: output directory
├── data: behavior scripts, misc. data
├── doxygen: documentation infrastructure
├── enhancements: example source modifications
├── include: header files
├── levels: level scripts, geo layout, and display lists
├── lib: SDK library code
├── rsp: audio and Fast3D RSP assembly code
├── sound: sequences, sound samples, and sound banks
├── src: C source code for game
│   ├── audio: audio code
│   ├── buffers: stacks, heaps, and task buffers
│   ├── engine: script processing engines and utils
│   ├── game: behaviors and rest of game source
│   ├── goddard: Mario intro screen
│   └── menu: title screen and file, act, and debug level selection menus
├── text: dialog, level names, act names
├── textures: skybox and generic texture data
└── tools: build tools