README.md (7105B)
1 # Super Mario 64 2 3 - This repo contains a full decompilation of Super Mario 64 of the following releases: Japan (jp), North America (us), Europe (eu), Shindou (sh) and iQue Player (cn). 4 - Naming and documentation of the source code and data structures are in progress. 5 6 It builds the following ROMs: 7 8 * sm64.jp.z64 `sha1: 8a20a5c83d6ceb0f0506cfc9fa20d8f438cafe51` 9 * sm64.us.z64 `sha1: 9bef1128717f958171a4afac3ed78ee2bb4e86ce` 10 * sm64.eu.z64 `sha1: 4ac5721683d0e0b6bbb561b58a71740845dceea9` 11 * sm64.sh.z64 `sha1: 3f319ae697533a255a1003d09202379d78d5a2e0` 12 * sm64.cn.z64 `sha1: 2e1db2780985a1f068077dc0444b685f39cd90ec` 13 14 This repo does not include all assets necessary for compiling the ROMs. 15 A prior copy of the game is required to extract the assets. 16 17 ## Quick Start (for Ubuntu) 18 19 1. Install prerequisites: `sudo apt install -y binutils-mips-linux-gnu build-essential git pkgconf python3` 20 2. Clone the repo from within Linux: `git clone https://github.com/n64decomp/sm64.git` 21 3. Place a Super Mario 64 ROM called `baserom.<VERSION>.z64` into the project folder for asset extraction, where `VERSION` can be `jp`, `us`, `eu`, `sh`, or `cn`. 22 4. Run `make` to build. Specify the version through `make VERSION=<VERSION>`. Add `-j4` to improve build speed (hardware dependent). 23 24 Ensure the repo path length does not exceed 255 characters. Long path names result in build errors. 25 26 ## Installation 27 28 ### Windows 29 30 Install WSL and a distro of your choice following 31 [Windows Subsystem for Linux Installation Guide for Windows 10.](https://docs.microsoft.com/en-us/windows/wsl/install-win10) 32 We recommend either Debian or Ubuntu 18.04 Linux distributions under WSL. 33 Note: WSL1 does not currently support Ubuntu 20.04. 34 35 Next, clone the SM64 repo from within the Linux shell: 36 `git clone https://github.com/n64decomp/sm64.git` 37 38 Then continue following the directions in the [Linux](#linux) installation section below. 39 40 ### Linux 41 42 There are 3 steps to set up a working build. 43 44 #### Step 1: Install dependencies 45 46 The build system has the following package requirements: 47 * binutils-mips 48 * pkgconf 49 * python3 >= 3.6 50 51 Dependency installation instructions for common Linux distros are provided below: 52 53 ##### Debian / Ubuntu 54 To install build dependencies: 55 ``` 56 sudo apt install -y binutils-mips-linux-gnu build-essential git pkgconf python3 57 ``` 58 59 ##### Arch Linux 60 To install build dependencies: 61 ``` 62 sudo pacman -S base-devel python 63 ``` 64 Install the following AUR packages: 65 * [mips64-elf-binutils](https://aur.archlinux.org/packages/mips64-elf-binutils) (AUR) 66 67 ##### Other Linux distributions 68 69 Most modern Linux distributions should have equivalent packages to the other two listed above. 70 You may have to use a different version of GNU binutils. Listed below are fully compatible binutils 71 distributions with support in the makefile, and examples of distros that offer them: 72 73 * `mips64-elf-` (Arch AUR) 74 * `mips-linux-gnu-` (Ubuntu and other Debian-based distros) 75 * `mips64-linux-gnu-` (RHEL/CentOS/Fedora) 76 77 You may also use [Docker](#docker-installation) to handle installing an image with minimal dependencies. 78 79 #### Step 2: Copy baserom(s) for asset extraction 80 81 For each version (jp/us/eu/sh/cn) for which you want to build a ROM, put an existing ROM at 82 `./baserom.<VERSION>.z64` for asset extraction. 83 84 ##### Step 3: Build the ROM 85 86 Run `make` to build the ROM (defaults to `VERSION=us`). 87 Other examples: 88 ``` 89 make VERSION=jp -j4 # build (J) version instead with 4 jobs 90 make VERSION=eu COMPARE=0 # build (EU) version but do not compare ROM hashes 91 ``` 92 93 Resulting artifacts can be found in the `build` directory. 94 95 The full list of configurable variables are listed below, with the default being the first listed: 96 97 * ``VERSION``: ``jp``, ``us``, ``eu``, ``sh``, ``cn`` 98 * ``GRUCODE``: ``f3d_old``, ``f3d_new``, ``f3dex``, ``f3dex2``, ``f3dzex`` 99 * ``COMPARE``: ``1`` (compare ROM hash), ``0`` (do not compare ROM hash) 100 * ``NON_MATCHING``: Use functionally equivalent C implementations for non-matchings. Also will avoid instances of undefined behavior. 101 * ``CROSS``: Cross-compiler tool prefix (Example: ``mips64-elf-``). 102 103 ### macOS 104 105 With macOS, you may either use Homebrew or [Docker](#docker-installation). 106 107 #### Homebrew 108 109 #### Step 1: Install dependencies 110 Install [Homebrew](https://brew.sh) and the following dependencies: 111 ``` 112 brew update 113 brew install coreutils make pkg-config tehzz/n64-dev/mips64-elf-binutils 114 ``` 115 116 #### Step 2: Copy baserom(s) for asset extraction 117 118 For each version (jp/us/eu/sh/cn) for which you want to build a ROM, put an existing ROM at 119 `./baserom.<VERSION>.z64` for asset extraction. 120 121 ##### Step 3: Build the ROM 122 123 Use Homebrew's GNU make because the version included with macOS is too old. 124 125 ``` 126 gmake VERSION=jp -j4 # build (J) version instead with 4 jobs 127 ``` 128 129 ### Docker Installation 130 131 #### Create Docker image 132 133 After installing and starting Docker, create the docker image. This only needs to be done once. 134 ``` 135 docker build -t sm64 . 136 ``` 137 138 #### Build 139 140 To build, mount the local filesystem into the Docker container and build the ROM with `docker run sm64 make`. 141 142 ##### macOS example for (U): 143 ``` 144 docker run --rm --mount type=bind,source="$(pwd)",destination=/sm64 sm64 make VERSION=us -j4 145 ``` 146 147 ##### Linux example for (U): 148 For a Linux host, Docker needs to be instructed which user should own the output files: 149 ``` 150 docker run --rm --mount type=bind,source="$(pwd)",destination=/sm64 --user $UID:$GID sm64 make VERSION=us -j4 151 ``` 152 153 Resulting artifacts can be found in the `build` directory. 154 155 ## Project Structure 156 157 sm64 158 ├── actors: object behaviors, geo layout, and display lists 159 ├── asm: handwritten assembly code, rom header 160 │ └── non_matchings: asm for non-matching sections 161 ├── assets: animation and demo data 162 │ ├── anims: animation data 163 │ └── demos: demo data 164 ├── bin: C files for ordering display lists and textures 165 ├── build: output directory 166 ├── data: behavior scripts, misc. data 167 ├── doxygen: documentation infrastructure 168 ├── enhancements: example source modifications 169 ├── include: header files 170 ├── levels: level scripts, geo layout, and display lists 171 ├── lib: SDK library code 172 ├── rsp: audio and Fast3D RSP assembly code 173 ├── sound: sequences, sound samples, and sound banks 174 ├── src: C source code for game 175 │ ├── audio: audio code 176 │ ├── buffers: stacks, heaps, and task buffers 177 │ ├── engine: script processing engines and utils 178 │ ├── game: behaviors and rest of game source 179 │ ├── goddard: Mario intro screen 180 │ └── menu: title screen and file, act, and debug level selection menus 181 ├── text: dialog, level names, act names 182 ├── textures: skybox and generic texture data 183 └── tools: build tools 184 185 ## Contributing 186 187 Pull requests are welcome. For major changes, please open an issue first to 188 discuss what you would like to change. 189 190 Run `clang-format` on your code to ensure it meets the project's coding standards. 191 192 Official Discord: [discord.gg/DuYH3Fh](https://discord.gg/DuYH3Fh)