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.
- Setup a custom code environment
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.
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 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 functionTo 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:
- type: nop
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 fileLet'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.
li r3, 0x0
.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 hookNow instead of having the code in the YAML, lets include the
nohurryup.S file that we just created. In the YAML write the following:
- type: branch
Files: includes the nohurryup.S assembly file that we just created, from the path
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
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.