hackern64 / hackersm64

A Super Mario 64 decompilation repo based on CrashOveride95/ultrasm64 that aims to provide a flexible, easy-to-use base for creating romhacks.

HackerSM64

AFTER CLONING THE REPO, CHECK OUT THE include/config FOLDER BEFORE ANYTHING ELSE! THERE'S A LOT OF STUFF IN THIS REPO THAT CAN BE TOGGLED THERE.

HackerSM64 now has a discord server! https://discord.gg/brETAakcXr

This repo requires BOTH a US ROM and a JP ROM in order to build. Place baserom.us.z64 in the repo as usual and ALSO include baserom.jp.z64.

This repo needs gcc in order to be able to build it. To install it, run sudo apt install gcc-mips-linux-gnu

This is a fork of the ultrasm64 repo by CrashOveride which includes the following commonly used patches (patches marked with * are toggleable in the config files):

Credits

• ArcticJaguar725: Most audio configuration and layout changes, colored ia4 text, floombas, various bugfixes, and more
• CowQuack: Adjustable skybox sizes, area-specific skybox function
• thecozies: Water surface types, general maintenance, and time
• MrComit: General use object defines, JUMP_KICK_FIX
• aglab2: Bugfixes (particularly puppycam), refactor stuff
• someone2639: math.s and crash screen disam, stack trace, map packing, shiftable segments 2, S2DEX engine
• Arthurtilly: Platform Displacement 2
• Fazana: PuppyLib, ucode swapping, audio load time optimisations (with Arctic), general hacker qol improvements, visual debug
• Reonu: Starting the project/repo, widescreen, reonucam, various defines for hacker QoL
• JoshDuMan: Decomp guy, general assistance
• Arceveti: Silhouette, shadow optimisation, better hanging, breath meter, 4 controller support
• axollyon: Console testing, bugfixes, idea-guying, and had a hand in silhouettes
• Wiseguy: World scale reimplementation, silhouette, graph node optimisations, instant input patch, cake screen fix, segmented code support, and various optimizations/fixes
• Kaze: Graph node optimisations, automatic optimal collision distance
• Pyro Jay: Texture improvements, repo banner art, some QoL stuff
• CrashOveride: creating the ultrasm64 repo
• falcobuster: Original coordinate overflow fix (world scale), ASM version of extended bounds, emulator detector
• anonymous_moose: porting falco's extended bounds to decomp
• tuxlovesyou: LOAD_MIO0_TEXTURE macro and moral support
• devwizard: the PJ64 pre-v3.0 detection part of the emulator detector

Thanks to Frame#5375 and AloXado320 for also helping with silhouette stuff

Lighting Engine by Wiseguy

• Lighting Engine is available on a separate branch (base/lighting-engine). Instructions on how to use it are in the readme of that branch.

Puppycam

• Puppycam is available on the master branch now, you can toggle it in config/config_camera.h. *

Collision:

• Slope fix and exposed ceilings fix
• No false ledgegrabs fix *
• Jump kick fix *
• Configurable wallkick angle, in degrees *
• Possibility of disabling BLJs *
• Hanging fix (Mario can grab hangable ceilings from any state, instead of only jump or double jump) *
• Increased maximum pole length (The game will read bparam1 and bparam2 together as a single value, so you can have a very long pole) *
• Platform Displacement 2 by Arthurtilly *
• Water Surface Type patch by thecozies
• Better wall collision with rounded corners by FramePerfection, merged by Cheezepin & Arceveti
• Automatically calculate the optimal collision distance for an object based on its vertices, by Kaze *

Common Hack Changes:

• Better extended boundaries by anonymous_moose
• Mario head skip *
• Peach letter cutscene skip *
• Exit course while moving *
• Toggle to disable fall damage and the fall damage sound *
• Nonstop stars *
• Removed course-specific camera processing *
• Ability to set Mario's movement speed when hanging from a ceiling *
• Tighter hanging controls (Mario will face the direction of the analog stick directly while hanging from a ceiling) *
• reonucam3: custom camera by Reonu. This is included as a .patch file in the enhancements folder, you need to apply it if you want this camera. This video shows a rundown of the features: https://youtu.be/TQNkznX9Z3k
• Ability to disable Mario getting suck in snow or sand

Hacker QOL:

• Global, non-level based, star IDs (off by default) *
• Debug mode: prints mario's coordinates, angle and speed, and a FPS counter.
• Automatic console/emulator detection. If emulator is detected, LODs are disabled. *
• Ability to configure whether there's a 100 coin star at all and how many coins are required to spawn it *
• Ability to easily change the warp that EXIT COURSE takes you to via config/config_menu.h, or disable it entirely. *
• 16 bit model IDs by someone2639. This means you can have up to 65536 models (lol). You can set the maximum number of model IDs in config/config_game.h.
• Apply_patch.sh improved
• Removed the ifdef hell in file_select.c and ingame_menu.c
• Added Blake's custom function for object model stuff: obj_set_model and obj_has_model
• Added function to get the model ID from an object: obj_get_model_id (by Arceveti)
• The "far" variable is now u16, allowing you to increase the farclip (the max distance at which geometry is rendered). However, when increasing the farclip, make sure to increase the nearclip by the same ratio, or rendering will break on console and LLE plugins.
• Many general use defines for object struct members, meant for use in custom object behaviors. Check include/object_fields.h for more info on this. (By MrComit)
• Included actors/group0.c in behavior_data.c
• The internal ROM name is now set with a define in config/config_rom.h to make it simpler
• There is a gEmulator variable to detect console or specific emulators and emulator versions
• Expanded audio heap allows for a larger concurrent note count and the importing of more m64 sequences and sound banks (By ArcticJaguar725) *
• You can set a test level in config/config_debug.h in order to boot straight into it, so you can quickly test the level you're working on. *
• Allow all surfaces in the game to have a force parameter. Activating this doesn't REQUIRE you to set force for every surface: If you don't set, it will default to 0x0000 rather than crashing. Increases RAM usage of collision. *
• The clown font includes the entire English alphabet.
• Colored ia4 text support. Format: "@XXXXXXXX[YOUR TEXT]@--------" (By ArcticJaguar725)
  • Example Text: "@FF0000FFRED @00FF00FFGREEN @0000FFFFBLUE @FFFFFF00INVISIBLE @--------NORMAL"
  • NOTE: It is not mandatory to reset the text color with "@--------", but text will need to be recolored each time it scrolls in a dialog box, or the custom color will reset.
• Toggle visiblity of collision surfaces and object hitboxes with Visual Surface Debug. config/config_debug.h has VISUAL_DEBUG which can be turned on to enable this feature.
• Workaround for infinite death loops caused by using the wrong warp type for death warps. Mario's HP will be restored when being warped to any warp if (and only if) he was warped while dead. *

Other Bugfixes:

• Castle music fix (fixes the castle music sometimes triggering after getting a dialog) *
• bparam4 fix (the game no longer uses bparam4 to check if an object is Mario and therefore you can safely use it)
• Instant warp offset fix (makes the instant warp offset work even when warping to a different area) *
• haveyourcake, also known as cake screen fix. Made by Wiseguy and ported/PR'd by Cheezepin
• Tree particle fix (Whether a tree uses snow particles or not is decided via the model IDs instead of the course number) *
• Adjustable world scale. You can change the geometry scaling of your level, which allow large levels to render correctly on console and LLE emulators while not hurting anything on HLE plugins.
• A couple vanilla texture fixes
• Smoke fix (the smoke texture uses the correct texture format)

Neat Misc. Changes:

• Instant Input patch by Wiseguy (Removes all input lag caused by plugins supporting framebuffer)
  • This means that you'll have to do your framebuffer effects on buffer 0 for emulator, but NOT for console. You can use the gEmulator variable to check for console when doing your framebuffer effects.
• Widescreen (16:9) support toggleable by pressing L in the pause menu. *
• S2DEX engine by someone2639! To use it, compile with make TEXT_ENGINE=s2dex_text_engine or just set TEXT_ENGINE to s2dex_text_engine in the makefile.
• ia8 (64x64) coins, the vanilla coin texture is upgraded to accomodate. *
• ia8 (64x64) 30 FPS coins (Textures by InTheBeef, cleaned up by Arceveti). *
• Floombas! Simply just retextured goombas with customizable behaviors (does not overwrite standard goombas). *
• HD texture support for intro splash screen (with floombas if enabled). *
• Mario's silhouette is shown when behind most surfaces (By Frame#5375, Axollyon, AloXado320, Wiseguy, Arceveti) *
• Skybox size modifier. You can have 2x, 3x and 4x size skyboxes (you can select the skybox size in config/config_graphics.h.) Please note that this might affect console performance, especially 4x mode. 2x or 3x mode is recommended if aiming for console. By CowQuack *
• You can set the black border size to different values for console and emulator. It's set to 0 by default for both. *
• This repo supports a much better implementation of reverb over vanilla's fake echo reverb. Great for caves or eerie levels, as well as just a better audio experience in general. See audio/synthesis.c for more details and configuration info. (By ArcticJaguar725) *
• Fazana's "puppyprint" text engine. *
  • Use print_small_text to print normal text. The two last params are aligment and how many characters to print (-1 means PRINT_ALL).
  • Use render_multi_image to draw large texture rectangles consisting of multiple images on the screen.
  • More info in puppyprint.c
• Wiseguy's Farcall TLB mapping allows to store executable code inside uncompressed segments, that can be loaded and ran as needed, instead of it having to be loaded at all times. See farcall.h in the include folder for instructions and details.
• Red Coin Stars now support up to 99 red coins! In addition, multi-area red coin missions can now be created by setting the 2nd behavior paramater of the red coin star to the number of reds required for the star to spawn.

UltraSM64

• This repo contains a full decompilation of Super Mario 64 (J), (U), (E), and (SH).
• Naming and documentation of the source code and data structures are in progress.
• 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 gEmulator 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.

Requirements are the same as regular SM64, however a GCC MIPS cross compiler is also required. If you're on Debian-like Linux, you can use the gcc-mips-linux-gnu package. The toolchain that comes with my SDK is also supported.

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). 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 current default, and 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 gziping with libdeflate-gzip. This compresses at a slightly better ratio than standard gzip, with no real downside from a decompression standpoint.

To use libdeflate-gzip, first clone the repo, then make and make install it.

Then run make for sm64 with GZIPVER=libdef in addition to COMPRESS=gzip

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 help

Go read the original SM64 repo README.md

hackersm64's Issues

Disabling CLEAR_RAM causes an immediate crash

Game will start with WOOOAAAAWWWW, but black screen and no crash screen.

Fix shadow scaling

Ukiki falls through the star cage

When doing the mystery of the monkey cage star, instead of stomping on the top of the cage, ukiki fell straight through. The star was still able to spawn however.

Power caps bobbing up and down when sliding on the ground

the vanish, wing, and metal caps bob up and down while sliding on the ground after coming out of the boxes

Rumble building is broken

Reimplement a configurable WORLD_SCALE define (reassess usage)

World scale is hardcoded to 1 in math.s and should be configurable per hack. This should be a define, and its implementation could use a reassessment as well.

BBH crash going through second door to the left of the stairs on the second floor

Happens on every act, with defines ENABLE_VANILLA_LEVEL_SPECIFIC_CHECKS, KEEP_MARIO_HEAD enabled, and PEACH_SKIP, UNLOCK_ALL, DISABLE_DEMO disabled
Also, supposedly not actually in update_parallel_tracking_camera according to Wiseguy - crash screen inaccuracy?

Hi Score text doesn't flash

self explanatory, but while testing on console the hi score text was not flashing

Floating Point Crash

A crash occurs on console when messing around Castle Grounds. Seems to have been addressed in math utils already; just need it approved.

Fix still unknown.

Certain transparent objects render behind env boxes.

Mostly due to env boxes usually being on LAYER_TRANSPARENT_INTER.

Most noticeable on:

Trees which are close to the cutout/transparency switch threshold:

The flames in the castle basement:

Burn smoke in the LLL volcano:

This is technically a vanilla bug, but it is much more noticeable in HackerSM64 due to the proximity transparency, burn smoke fix, and camera angles that couldn't easily be achieved in vanilla.

HMC Crash

Loading into HMC via debug level select causes a crash in HANDLE_DP_COMPLETE, where sCurrentDisplaySPTask is NULL.
The intro demo HMC section also freezes, but with no crash screen.

There are several "half-fixes", such as null checking sCurrentDisplaySPTask, or increasing the number in alloc_display_list in geo_process_background from 7 to 8, and a few others. However, these "half-fixes" cause major flickering after entering another level after HMC, and cause HMC's starting screen transition to be delayed for 1 or 2 frames:

Frame 1

Frame 2

It may potentially be caused by there being too many objects on screen on frame 1, before the level geometry itself loads.

The crash also does not happen if the camera starts at a different angle than normal.

Removing some macro objects or increasing GFX_POOL_SIZE fixes it without the flickering issues, but it would be better to fix the underlying problem.

FAST_VERTICAL_CAMERA_MOVEMENT was removed

Add VERSION.txt to the repo (and git tag on merge to master)

dist_between_objects

So after alot of testing it seems like Koopa The Quick and Big Penguin Races cause crashes on Console aswell as Emulators (Project 64, Paralell 64 & Mupen64Plus Next)

It only happens when adding modifying those Trajectories i only have tested those cases tho dont know about Metal Balls and other Trajectories of that sort also it happens both in Debug and Normal Mode (aka when debug mode is disabled)

Here are also some Screenschots of the Crash Screen:

it seems to be because obj1 and/or obj2 is NULL

Global variable increments

There are many instances of game code incrementing or otherwise changing global variables by one value at a time. This is most common with gDisplayListHead getting incremented in gbi macros. These cause the compiler to generate a lot of unnecessary loads and stores, which hurt performance and potentially even hurt memory bandwidth. These should be changed to copying the global into a local, working on the local, and then overwriting the global with the local's value at the end of the function.

Fix shadow compatibility with fast64

Spinning Fire Bars in Lethal Lava Land Do Not Spit Fire

Billboarded geo issues

There seems to be some issues regarding manually billboarded geo, either not showing up or being warped

One of these may be the cause of a odd grey plane:

These two billboards aren't visible at all:

Investigate recompiling libultra from ultralib

The n32 ABI is more efficient as it allows the use of 8 registers for passing arguments to functions instead of just 4. It also allows using the native 64 bit operations that the N64 supports. Compiling libultra under a modern compiler instead of a 25 year old one might also net some performance gain as well.

This task will be a very large undertaking and may not yield a large enough performance boost to warrant that amount of work, so it's not high priority.

Chain chomp can unload if CHAIN_CHOMP_NUM_SEGMENTS is set too high

To replicate:

• set segments to 10 or above
• bait chain chomp towards bridge
• run towards bomb-clip bobomb and keep looking at chain chomp until it disappears
• approach chain chomp: it should be unloaded

Solution:
Source of issue needs to be found, but one idea is to modulate some unloading distance with chain chomp head width + (CHAIN_CHOMP_NUM_SEGMENTS * segment width)

Pyramid Visibility

The top of the pyramid in SSL is not visible unless you are very close to it. This is hopefully just an issue with the pyramid object itself, but it could be indicative of an issue related to global render distance for objects.

[Bug] Water surfaces facing downwards are ignored

This is a new bug on a new feature, the old implementation of water surfaces prevented downwards facing water surfaces whatsoever.

---

Here's how water surface types were used before:

While loading surfaces:

• Check if surface->normal.y > 0.01f (a floor)
• If surface is water, add to water list instead of floor list
• Downwards or sideways facing water surfs were added to ceil/wall lists respectively

While checking ceil/wall collision

• If surf->type is water surface then ignore

---

The feature/fix:

While loading:

• If surface is water type, add to water list
• That's it lol

This allowed me to get rid of the water surface checks in walls/ceils!
The issue is that water ceils in the water list are still being ignored even with the new change.

I believe that this is important for usability, like consider a floating water cube - typically a cube like that would have all of its faces facing outwards, including the bottom one. In the past implementation, the user would have to flip the normals of only the bottom face, making for awkward geo, and it would be confusing/difficult to figure out that that's needed. It should be allowed from any direction.

Thoughts on it being a v2.0 bug?

Z-fighting on doors with AUTO_LOD enabled

AUTO_LOD forces GEO_RENDER_RANGE to always read camera distance as 50. For doors this causes z-fighting issues, since doors rely on GEO_RENDER_RANGE to switch decal mode for their labels (star numbers & locks) on/off.

[QoL] Config Documentation

These would be good to label for repo accessibility! Should this be in 2.0?

• START_LEVEL has no safeguard, if undefined it wont compile

• START_LEVEL should have a comment explaining how to get it to work in other levels

• EXIT_COURSE_LEVEL should have a comment explaining how to get it to work in other levels

• DEFAULT_NUM_LIVES should have a comment for the max number of lives (s8)

Macro that switches between OR_INT and OR_LONG depending on value

It's hard to know or remember to switch out an OR_INT to OR_LONG depending on the oFlags used in a BehaviorScript, so there should be a catchall macro that only uses OR_LONG if it needs to.

Blast Away The Wall star doesn't appear

no i can't do cannonless

BUGFIX_DIALOG_TIME_STOP broken (prevents building if enabled)

it do be broken doe

Fix credits crash

Implement MAX_SIMULTANEOUS_NOTES define

When in the merry-go-round room in BBH on console, the game runs at around 23-24fps, and lower if fire is on screen.

Make eep4k the default again so the game doesn't fail to save on the most widely used flashcarts

PC Port

!!!IMPORTANT

fix puppyprint menu combo

(L/DUp) hold both and press one

Mario's shadow sometimes doesn't appear on a water surface

Example of it not working (water surface facing upwards)

Example of it working (water surface facing downwards)

Star Collect Momentum

Ground pounding into a star does not change Mario's velocity downward like in vanilla. This is mostly just unsatisfying, but can look jank at times. Likely related to poor implementation of GROUND_POUND_WALL_FIX.

LIST OF SUGGESTED DEFINE DEFAULTS

Should be the final issue that is taken care of right before merge

i think this also kinda needs to be on pc port 😳

Unagi transparent star check uses wrong course index

The save_file_get_star_flags() check in bhv_unagi_init needs COURSE_NUM_TO_INDEX(COURSE_JRB) instead of just COURSE_JRB.

This is unrelated to the Unagi star proximity detection issue.

JRB Eel Star

The eel in JRB Star 2 reportedly does not seem to spawn the star if you come into contact with the star on its tail

Mario flies strangely during cutscene after beating Bowser 3

It seems he doesn't follow the trajectory he's supposed to follow when flying during that cutscene, or at least doesn't follow it correctly.

Title screen demo crash

When the KEEP_MARIO_HEAD config option is enabled, the demo sequences will play through one by one like in the original game until it reaches the 6th (index 5, Hazy Maze Cave in the original US version) demo, where it hard crashes on Mupen64Plus/ParaLLEl64 with the error MTC0 instruction writing Index register with TLB index > 31. It works as intended on Project64 and doesn't throw an error; however, I'm unaware whether it also occurs on console or not as I don't have the equipment to properly test it.

==== Build Options ====
Version:        us
Microcode:      f3dzex
Console:        n64
Target:         sm64.us
Compare ROM:    no
Build Matching: no
=======================

BitDW Yellow Moving Platform

Attempting to jump on this platform will cause Mario to completely phase through it, often resulting in a crash. It's possible that this issue applies to more than just this platform, though most moving platforms I've seen appear fine.

Ensure README accuracy

The whole readme should be re-evaluated before this release. Correct incorrect statements, and perhaps an upgrade guide to v2.0?

This line in particular is incorrect and should be updated/clarified.

• Coordinate overflow fix by falcobuster. Your levels will render correctly on console and LLE emulators even when using 2x or 4x bounds, while not hurting anything on HLE plugins. This is automatic now, you don't have to set WORLD_SCALE manually.

JRB Ship Camera

JRB Ship interior camera roll goes absolutely ham like gmod ragdoll when you make the ship rise. Tested with Puppycamera, untested with vanilla cam.

Coin Score prints incorrectly

When you get > 99 coins in a stage, the coin score (in seemingly all places where the score can be viewed) will incorrectly print as 0XX instead of 1XX

eg. collecting 104 coins will be shown as 004

UNLOCK_FPS: too many vblanks get removed

On console this leads to flashing, so instead this should just unlock to 60fps instead

Optimize surface collision checks and `break` when upperY/lowerY is out of bounds

Right now collision checks will continue after finding a floor or ceil to be very certain that a another tri shouldn't have been hit instead.

In find_floor_from_list, it seems that having if (floor && surf->upperY < floor->lowerY) break; at the top of the loop could improve performance. This is a good check because it insures that you have found a floor, and that the current floors highest point is lower than the previously collided floor's lowest point. And because of sort order, there's no reason to continue checking after this point.

The same but reversed could be done for ceilings.

Debug level select freezes on the 6th time entering a level on RetroArch

When debug level select is enabled, entering 6 levels in one game session (they can be different levels or the same levels) freezes on the 6th level with no crash screen. The first 5 levels load normally. This happens RetroArch but not PJ64. Entering a level via painting does not count toward the 6 levels.

Considerable lag when displaying dialog

On console, the game chugs during a few specific spots in the baby penguin mission in CCM. Talking to the mother drops the game to around 25 FPS. The star dance cutscene also has lag for some reason, dropping to around 27 FPS and delaying the "HERE WE GO!" voice clip past when it should play in the song.

Credits black bars render over the end cake picture

self explanatory

Square Boxes Have Round Shadows

Self explanatory, presumably these should be square as well

Address Compiler Warnings

WARNING: this code sucks don't do the thing haha lmfao