HackerSM64 is a Super Mario 64 decompilation used as a base for ROM hacks

A decompilation used as a starting point

HackerSM64 is described as a commonly used base repository for Super Mario 64 ROM hacking projects, and the repository description says it is a decompilation based on CrashOveride95's ultrasm64 that aims to provide a flexible, easy-to-use base for creating romhacks. That distinction from UltraSM64 is the first thing to understand, and the README has an FAQ entry for it. HackerSM64 is best suited for ROM hacks with custom levels and content, while if you want to make a ROM hack that is TAS-accurate to the vanilla game and its levels, UltraSM64 may be a better choice. The project is written in C, the licence field on the repository is not one GitHub can classify, and the repository is not archived with the last push on 2026-09-21. The release history shows v2.4.0 on 2026-09-12, after v2.3.0 in July 2024 and v2.2.0 in March 2024. The README also says the project is a community effort with many contributors and points at CREDITS.md for the list of major ones.

Building it needs a US ROM and a cross toolchain

The build instructions live on the HackerSM64 wiki rather than in the README, and the README only states the requirement that matters most: this repo requires a US ROM in order to build, with JP and EU ROMs optional for some assets. That is a licensing question you answer yourself, and it is also the practical constraint that shapes every installation. The repository ships a Dockerfile that makes the toolchain reproducible, and it installs the cross-compilation packages the build needs: the MIPS binutils, gcc-mips-linux-gnu, build-essential, libcapstone-dev, pkgconf, python3 and bsdextrautils on an ubuntu:22.04 base. It then sets the working directory to /hackersm64 and puts the repository's own tools/ directory on the PATH, which matters because the build expects its own tools to be found first. The image's default command prints a usage line rather than building anything, and that line carries the exact invocation the author expects.

CMD echo 'Usage: docker run --rm -v ${PWD}:/hackersm64 hackersm64 make VERSION=us -j4\n' \
         'See https://github.com/HackerN64/HackerSM64/blob/master/README.md for more information'

The repository also carries a Makefile and a Makefile.split, a .clang-format and a .clang-tidy for the C sources, compile_flags.txt for editor tooling, and the directories you would expect from a decompilation: actors/, asm/, assets/, compression/, data/, levels/, rsp/, sound/, src/, text/, textures/ and tools/, plus include/, lib/, util.mk and an assets.json.

Build options that change what you get

The Makefile is where the engineering decisions are visible. The options can be set by building with make SETTING=value, and the README of the makefile notes that make clean may be required first. The console is selected with CONSOLE, defaulting to n64, and the two accepted values are n64 and bb, where bb targets the iQue Player and adds the BBPLAYER=1 define and a different include and lib directory. The compiler is chosen with COMPILER, accepting gcc or clang. The LIBGCCDIR setting selects the libgcc configuration used for the divide-by-zero check, with trap described as the GCC default using teq instructions which some emulators do not like, divbreak described as similar to IDO behaviour and the default, and nocheck described as never checking for division by zero, technically the fastest but also undefined behaviour and therefore not recommended. The save type is chosen with SAVETYPE, offering eep4k for EEPROM 4kbit, eep16k for EEPROM 16kbit, which the makefile notes has no syntax differences but is provided just in case, and sram for SRAM 256Kbit.

The gameplay changes you inherit from the base

The README lists the common hack changes that a new project gets by default, and these are the toggles that decide what kind of hack you are making. Extended boundaries come in 1x, 2x and 4x variants, which means the camera can leave the intended bounds of a level. The instant input patch does not affect console, which matters because an input buffer behaves differently on hardware than in an emulator. Mario head skip is one of the listed toggles. The Peach letter cutscene skip removes a cutscene. And there are toggles for fall damage, lives, 100 coin stars and other vanilla mechanics, which is the phrase that matters, because toggles mean you can turn vanilla behaviour off rather than patching it out later. The README is explicit that many of these tweaks and features may be toggled by editing the files in the include/config folder, and it strongly recommends looking through them when starting a brand new project and before doing anything else in the repository. That advice is the single most useful line in the README for a newcomer.

The debug and engine features for hack authors

The features for hackers section is where the repository earns its place. There is a rich debug set: a debug fly mode, a much improved crash screen, visual surface and object hitbox debug, a live display of several game state variables, and detailed performance profiling information. That is a development environment, not just a modified game. There is automatic console and emulator detection, so you can use gEmulator and gSystemCapabilities to determine which emulator is running or whether you are on console, and to check which features such as framebuffer emulation are available. There is an option for global, non-level based star IDs, which is what makes a custom level in a custom world behave predictably. There are 16 bit model IDs, so you can have up to 65536 models, and an expanded audio heap allowing a larger concurrent note count and the importing of more m64 sequences and sound banks. The puppyprint text engine lives in src/game/puppyprint.c, and there is a new water surface type that is easier to use and more flexible than vanilla water boxes, plus an option to show Mario's silhouette when behind most surfaces.

Farcall, collision fixes and the lighting branch

Two engineering items deserve their own reading. Farcall TLB mapping allows executable code to be stored inside uncompressed segments that are loaded and run as needed, instead of it having to be loaded all the time, with the instructions and details in include/farcall.h. On a N64 that is a real constraint, since ROM space and load times are hard limits, so a mechanism to page code in on demand is not a small optimisation. The bug fix and physics section covers fixes for common collision issues such as the slope fix, the exposed ceilings fix and the false ledgegrabs fix, and improved wall collision with rounded corners, which the README says also helps reduce potential softlocks in custom levels. The rounded corner collision is exactly the kind of change that removes a class of bug reports from a hack's issue tracker. There is also a lighting engine available on a separate branch, base/lighting-engine, which allows dynamic lights in your levels with ambient, directional and point lights supported, and the instructions for using it are in that branch's readme. That branch structure is worth noting: it means the main line stays conservative and the experimental work lives elsewhere.

Coloured text and the asset pipeline

Coloured text support is a small feature with a memorable syntax. You add colours to text boxes by adding an @RRGGBBAA prefix to the text, where each letter is a hex digit representing red, green, blue and alpha for transparency, and you reset the colour by adding @--------. The README is candid about the catch: it is not mandatory to do this, but text will need to be recoloured each time it scrolls in a dialog box, or the custom colour will reset. The example given is the string @FF0000FFRED @00FF00FFGREEN @0000FFFFBLUE @FFFFFF00INVISIBLE @--------NORMAL. For levels, the FAQ answers how to make your own: use Blender with the Fast64 plugin to create and export levels as 3D models, and the repository contains a fast64.json file at the root along with extract_assets.py for pulling assets out of a ROM. The asset pipeline is therefore a Python script plus a Blender export, not a level editor, which is the practical cost of custom content.

Where HackerSM64 is the wrong base

Four limits are worth stating. The first is the legal and practical one: building requires a US ROM, and if you do not have one you cannot build at all. That is not a limitation of the repository, it is a property of the decompilation approach, and it is the reason a Docker image cannot remove the constraint. The second is that this is a base for hacks, not a game engine with an editor. Custom levels come from Blender and Fast64 exports, and the toolchain around it, the object behaviours, the defines in include/object_fields.h and the text and audio formats, all follow the original game's conventions rather than a modern toolchain. A team wanting a modern engine with an editor, a debugger and an asset pipeline should be looking at a different project. The third is the maintenance and licence question. The repository is not archived and was pushed to on 2026-09-21, and v2.4.0 was tagged on 2026-09-12, so the project is being worked on, but GitHub does not classify the licence at all, so for a commercial project the licensing terms are something you have to establish yourself rather than something the repository page tells you. The fourth is that the changes are cumulative by default. Extended boundaries, instant input and skipped cutscenes are all toggleable in include/config, so a hack that wants vanilla behaviour should review these toggles first, and a player comparison test against the retail game may show differences that are not bugs. The honest alternative is UltraSM64 itself, which the README names for TAS accurate work, and the difference between the two bases is precisely the accumulated modifications.

Editorial conclusion

Adopt HackerSM64 if you are making a Super Mario 64 ROM hack with custom levels or altered gameplay, because it gives you a configurable engine with extended boundaries, an instant input patch, model IDs up to 65536 and a debug feature set that the vanilla game never had. Do not adopt it for a TAS accurate project, since the README itself points you to UltraSM64 for that, and do not adopt it if you cannot legally obtain a US ROM, since the build requires one. Verify two things first: which game version your hack targets, since the Makefile's VERSION setting selects the ROM revision and JP and EU ROMs are only optional for some assets, and that the config files in include/config are reviewed before you start, because the README strongly recommends looking through those toggles before doing anything else in the repository. The practical first step is to install the cross-compilation toolchain described on the HackerSM64 wiki and run a build for your target version before you change a single line of game code.

Frequently asked questions

Official sources

1. HackerN64/HackerSM64 on GitHub
2. Issues
3. README
4. Releases