Introduction to ASM Hacks
wip
Requirements
Guide
(blah blah introduction) To introduce you to the basic ASM build system, we will be making a small patch to disable the music speedup after 100 seconds.
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 a nop 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
What this does is replace the instruction at address 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/ called nohurryup.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
Let's break down what this does. The .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 the nohurryup.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
What does this code do exactly? The 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, because we want it to branch unconditionally no matter what. 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
(insert video of it working)
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.