Custom Code/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

 * Setup NSMBU-Haxx
 * asmsetup.S

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  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  which corresponds to. Let's make a hook to disable it!

Patching the function
To try and disable the function, we can try and insert a  function that does nothing. To do this first we create a YAML file called. Inside it, we can insert the following lines: What this does is replace the instruction at address  with a   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  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  and then return with. Another issue we will run into is that a YAML hook cannot just do this by itself. For that we will need a, or assembly file.

Creating the assembly file
Let's create a file in /source/ called. 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. Let's break down what this does. The  indicates that the following is code to be executed. The  will include the   file into our own file. The NoHurryUp label contains a load immediate instruction that sets register 3 to 0x0, or , and then it has a   instruction that returns back to the link register. The  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  file that we just created. In the YAML write the following: What does this code do exactly? The  includes the nohurryup.S assembly file that we just created, from the path. The  section is a bit more complicated though. First we declare the type to be, because we will be branching to a different part of the code (The possible types are  ,  ,  , and  ). The instruction is  instead of   because we want it to branch without a link register so when we do   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  as that is what we named our function to be in the assembly. Finally, the address is  because that is what the address for the target function was in the symbol map. Make sure to include the YAML in  too. Let's compile and test it out!

Conclusion and Review
uS3-trjqwQM

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.