{"id":16140893,"url":"https://github.com/networkfusion/sm64","last_synced_at":"2025-04-06T18:33:41.067Z","repository":{"id":85340667,"uuid":"319450390","full_name":"networkfusion/sm64","owner":"networkfusion","description":"SM64 Decomp Source","archived":false,"fork":false,"pushed_at":"2021-03-09T16:52:55.000Z","size":18306,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"develop-ultimate","last_synced_at":"2025-03-18T19:04:15.816Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/networkfusion.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-07T21:35:43.000Z","updated_at":"2021-03-07T01:40:44.000Z","dependencies_parsed_at":"2024-01-29T05:00:19.034Z","dependency_job_id":null,"html_url":"https://github.com/networkfusion/sm64","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkfusion%2Fsm64","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkfusion%2Fsm64/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkfusion%2Fsm64/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkfusion%2Fsm64/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/networkfusion","download_url":"https://codeload.github.com/networkfusion/sm64/tar.gz/refs/heads/develop-ultimate","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247532098,"owners_count":20954097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-09T23:54:03.107Z","updated_at":"2025-04-06T18:33:41.050Z","avatar_url":"https://github.com/networkfusion.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Super Mario 64\n\n- This repo contains a full decompilation of Super Mario 64 (J), (U), (E), and (SH).\n- Naming and documentation of the source code and data structures are in progress.\n\nIt builds the following ROMs:\n\n* sm64.jp.z64 `sha1: 8a20a5c83d6ceb0f0506cfc9fa20d8f438cafe51`\n* sm64.us.z64 `sha1: 9bef1128717f958171a4afac3ed78ee2bb4e86ce`\n* sm64.eu.z64 `sha1: 4ac5721683d0e0b6bbb561b58a71740845dceea9`\n* sm64.sh.z64 `sha1: 3f319ae697533a255a1003d09202379d78d5a2e0`\n* sm64.jpu.z64\n* sm64.usu.z64\n* sm64.euu.z64\n* sm64.shu.z64\n\nThis repo does not include all assets necessary for compiling the ROMs.\nA prior copy of the game is required to extract the assets.\n\n## Quick Start (for Ubuntu)\n\n1. Install prerequisites: `sudo apt install -y build-essential git binutils-mips-linux-gnu python3 libcapstone-dev`\n2. Clone the repo from within Linux: `git clone https://github.com/n64decomp/sm64.git`\n3. Place a Super Mario 64 ROM called `baserom.\u003cVERSION\u003e.z64` into the project folder for asset extraction, where `VERSION` can be `us`, `usu`, `jp`, `jpu`, `eu`, `euu`, `sh` or `shu`.\n4. Run `make` to build. Qualify the version through `make VERSION=\u003cVERSION\u003e`. Add `-j4` to improve build speed (hardware dependent).\n\nEnsure the repo path length does not exceed 255 characters. Long path names result in build errors.\n\n## Installation\n\n### Windows\n\nInstall WSL and a distro of your choice following\n[Windows Subsystem for Linux Installation Guide for Windows 10.](https://docs.microsoft.com/en-us/windows/wsl/install-win10)\nWe recommend either Debian or Ubuntu 18.04 Linux distributions under WSL.\nNote: WSL1 does not currently support Ubuntu 20.04.\n\nNext, clone the SM64 repo from within the Linux shell:\n`git clone https://github.com/n64decomp/sm64.git`\n\nThen continue following the directions in the [Linux](#linux) installation section below.\n\n### Linux\n\nThere are 3 steps to set up a working build.\n\n#### Step 1: Install dependencies\n\nThe build system has the following package requirements:\n * binutils-mips\n * capstone\n * pkgconf\n * python3 \u003e= 3.6\n\nThe diff system also requires:\n* python3-pip\n* pip packages: colorama ansiwrap watchdog python-Levenshtein cxxfilt\n\nDependency installation instructions for common Linux distros are provided below:\n\n##### Debian / Ubuntu\nTo install build dependencies:\n```\nsudo apt install -y binutils-mips-linux-gnu build-essential git libcapstone-dev pkgconf python3\n```\n\n##### Arch Linux\nTo install build dependencies:\n```\nsudo pacman -S base-devel capstone python\n```\nInstall the following AUR packages:\n* [mips64-elf-binutils](https://aur.archlinux.org/packages/mips64-elf-binutils) (AUR)\n\n\n##### Other Linux distributions\n\nMost modern Linux distributions should have equivalent packages to the other two listed above.\nYou may have to use a different version of GNU binutils. Listed below are fully compatible binutils\ndistributions with support in the makefile, and examples of distros that offer them:\n\n* `mips64-elf-` (Arch AUR)\n* `mips-linux-gnu-` (Ubuntu and other Debian-based distros)\n* `mips64-linux-gnu-` (RHEL/CentOS/Fedora)\n\nYou may also use [Docker](#docker-installation) to handle installing an image with minimal dependencies.\n\n#### Step 2: Copy baserom(s) for asset extraction\n\nFor each version (jp/us/eu/sh) for which you want to build a ROM, put an existing ROM at\n`./baserom.\u003cVERSION\u003e.z64` for asset extraction.\n\n##### Step 3: Build the ROM\n\nRun `make` to build the ROM (defaults to `VERSION=us`).\nOther examples:\n```\nmake VERSION=jp -j4       # build (J) version instead with 4 jobs\nmake VERSION=eu COMPARE=0 # build (EU) version but do not compare ROM hashes\n```\n\nResulting artifacts can be found in the `build` directory.\n\nThe full list of configurable variables are listed below, with the default being the first listed:\n\n* ``VERSION``: ``us``, ``jp``, ``eu``, ``sh``,``usu``, ``jpu``, ``euu``, ``shu``\n* ``GRUCODE``: ``f3d_old``, ``f3d_new``, ``f3dex``, ``f3dex2``, ``f3dzex``\n* ``COMPARE``: ``1`` (compare ROM hash), ``0`` (do not compare ROM hash)\n* ``NON_MATCHING``: Use functionally equivalent C implementations for non-matchings (Currently there aren't any non-matchings, but this will apply to Shindou and iQue). Also will avoid instances of undefined behavior.\n* ``CROSS``: Cross-compiler tool prefix (Example: ``mips64-elf-``).\n\n### macOS\n\nWith macOS, you may either use Homebrew or [Docker](#docker-installation).\n\n#### Homebrew\n\n#### Step 1: Install dependencies\nInstall [Homebrew](https://brew.sh) and the following dependencies:\n```\nbrew update\nbrew install capstone coreutils gcc make pkg-config tehzz/n64-dev/mips64-elf-binutils\n```\n\n#### Step 2: Copy baserom(s) for asset extraction\n\nFor each version (jp/us/eu) for which you want to build a ROM, put an existing ROM at\n`./baserom.\u003cVERSION\u003e.z64` for asset extraction.\n\n##### Step 3: Build the ROM\n\nUse Homebrew's GNU make because the version included with macOS is too old.\n\n```\ngmake VERSION=jp -j4       # build (J) version instead with 4 jobs\n```\n\n### Docker Installation\n\n#### Create Docker image\n\nAfter installing and starting Docker, create the docker image. This only needs to be done once.\n```\ndocker build -t sm64 .\n```\n\n#### Build\n\nTo build, mount the local filesystem into the Docker container and build the ROM with `docker run sm64 make`.\n\n##### macOS example for (U):\n```\ndocker run --rm --mount type=bind,source=\"$(pwd)\",destination=/sm64 sm64 make VERSION=us -j4\n```\n\n##### Linux example for (U):\nFor a Linux host, Docker needs to be instructed which user should own the output files:\n```\ndocker run --rm --mount type=bind,source=\"$(pwd)\",destination=/sm64 --user $UID:$GID sm64 make VERSION=us -j4\n```\n\nResulting artifacts can be found in the `build` directory.\n\n## Project Structure\n\t\n\tsm64\n\t├── actors: object behaviors, geo layout, and display lists\n\t├── asm: handwritten assembly code, rom header\n\t│   └── non_matchings: asm for non-matching sections\n\t├── assets: animation and demo data\n\t│   ├── anims: animation data\n\t│   └── demos: demo data\n\t├── bin: C files for ordering display lists and textures\n\t├── build: output directory\n\t├── data: behavior scripts, misc. data\n\t├── doxygen: documentation infrastructure\n\t├── enhancements: example source modifications\n\t├── include: header files\n\t├── levels: level scripts, geo layout, and display lists\n\t├── lib: SDK library code\n\t├── rsp: audio and Fast3D RSP assembly code\n\t├── sound: sequences, sound samples, and sound banks\n\t├── src: C source code for game\n\t│   ├── audio: audio code\n\t│   ├── buffers: stacks, heaps, and task buffers\n\t│   ├── engine: script processing engines and utils\n\t│   ├── game: behaviors and rest of game source\n\t│   ├── goddard: Mario intro screen\n\t│   └── menu: title screen and file, act, and debug level selection menus\n\t├── text: dialog, level names, act names\n\t├── textures: skybox and generic texture data\n\t└── tools: build tools\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to\ndiscuss what you would like to change.\n\nRun `clang-format` on your code to ensure it meets the project's coding standards.\n\nOfficial Discord: [discord.gg/DuYH3Fh](https://discord.gg/DuYH3Fh)\n\n\n## Using first-diff\nIt should be possible to get a matching ROM (at least against shu) when removing `VERSION_SH_ULTIMATE` from all bug fixes in `config.h`. To find out why non match is occuring, you can run a `first-diff`.\nAn example of using first-diff would be:\n`python3 first-diff.py --shu`\n\n## Using diff\nAfter running `first-diff` you can track down the issue using `diff`.\nan example of this would be (with the -m -w -i flags causing it to automatically rebuild and rediff when you modify a source file):\n\n### Base Rom\nan example using a regular -u (US) version would be `python3 diff.py -umwi rspF3DStart`\n\n### Ultimate Rom\nan example with an sh ultimate version would be:\n`python3 diff.py --shu -mwi rspF3DStart`","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworkfusion%2Fsm64","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetworkfusion%2Fsm64","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworkfusion%2Fsm64/lists"}