Introduction to ASM Hacks
In order to do very low-level modifications to the game, C++ cannot just be used by itself. For these purposes we need assembly, or "ASM" hacks to patch or alter functions in the code. The game uses 32-bit PowerPC assembly code, so that is what all patches will need to be written in. To introduce you to the basic ASM build system, we will be making a small patch to disable the music speedup after 100 seconds.
Requirements
Steps
All assembly hacks contain a YAML file, which contains hooks that will patch areas of the code to have branch instructions to our custom functions. These hooks can also do some basic tasks by themselves, but for more complex tasks, a .S file is also necessary, which contains pure assembly.
Preparation
Before we start creating our patch, first we need to include the asmsetup.S file in our project. Simply download the file from here, and place it in your /include/ directory in the NSMBU-Haxx project files.
Finding our target function
To find our target function, we can refer to the Symbol Map to see the address for the specific function. In our case, the symbol is shouldHurryUp__11MusicPlayerFv which corresponds to 0xF5783D8. Let's make a hook to disable it!
Patching the function
To try and disable the function, we can try and insert anop function that does nothing. To do this first we create a YAML file called nohurryup.yaml. Inside it, we can insert the following lines:---
Files: []
Hooks:
- type: nop
addr: F5783D8
F5783D8 with a nop instruction which does nothing. This should work right? Well, let's test it out.
(insert video of crash)
It seems like this just crashes the game. Why is this so?
Patching the function (the correct way)
(insert technical reason of why this doesn't work)
The correct way of doing this, is to instead do a blr instruction, which will skip the function and return. The thing is, the function returns a bool (a 1 or a 0), but a blr would just return what is in register 3 (the return register). So what we need to do is set register 3 to zero, or 0x0 and then return with blr. Another issue we will run into is that a YAML hook cannot just do this by itself. For that we will need a .S, or assembly file.
Creating the assembly file
Let's create a file in /source/ callednohurryup.S. The assembly we will be writing is quite simple. All it has to do is set register 3 to 0x0 and then return. In addition to that we also need to add some setup lines..text
.include "asmsetup.S"
.global NoHurryUp
NoHurryUp:
li r3, 0x0
blr
.text indicates that the following is code to be executed. The .include will include the asmsetup.S file into our own file. The NoHurryUp label contains a load immediate (li) instruction that sets register 3 to 0x0, or 00 00 00 00, and then it has a blr instruction that returns back to the link register. The .global means that the NoHurryUp label will be accessible from anywhere. Don't forget to end the file in a newline! (If you're confused, feel free to download the completed source files. YAML, and Assembly.
Creating the hook
Now instead of having the code in the YAML, lets include thenohurryup.S file that we just created. In the YAML write the following:---
Files: [source/nohurryup.S]
Hooks:
- type: branch
instr: b
func: NoHurryUp
addr: F5783D8
Files: includes the nohurryup.S assembly file that we just created, from the path source/. The Hooks: section is a bit more complicated though. First we declare the type to be branch, because we will be branching to a different part of the code (The possible types are patch, nop, branch, and funcptr). The instruction is b instead of bl because we want it to branch without a link register so when we do blr it will return to the function that called the music speedup function, and not just return to the music speedup function. The function (label) it will branch to is NoHurryUp as that is what we named our function to be in the assembly. Finally, the address is F5783D8 because that is what the address for the target function was in the symbol map. Make sure to include the YAML in project.yaml too. Let's compile and test it out!
Conclusion and Review
So, what did we learn? First we have to find the address for our target function, preferably from the symbol map. Next we create a .S assembly file to patch the function with our desired effects. Finally, we include the assembly file in our YAML hook with the correct type, instruction, function, and address.