ASM Hacking Tutorial

Basic ASM Tutorial

I learned how to do this from both Jordy and the following in-depth tutorial:
http://n64vault.wdfiles.com/local--files/ssb-guides%3Agenerally-assembly-hacking-tutorials/Tarek%27s%20ASM_Mips%20Guide
There's an Immense amount to learn from the link above. I'm showing a small portion using No Mercy as my reference.

What uses do we have with ASM hacking? Personally, I use it to create GameShark-like actions to customize the game and hack it directly to the ROM so that no GS codes are needed.

In this small tutorial I'll show you how to write values to addresses at specific moments via ASM.

You will need an emulator with a R4300i Commands viewer. I use PJ64 2.4.x beta
Nightly builds are available here: https://www.pj64-emu.com/nightly-builds

With Debugging enabled, this is available under Debugger>R4300i>R4300i Commands

Looks like this

Show Pic:

First, I'll show you how to read and understand my custom ASM, then I will show you how to make the game read what we've written.
This won't be the order you perform your own customizations, I just feel like it's easier to understand in this order.

Show Pic:

Looking at each column in this pic from left to right first we see
Visual colored arrows representing branches
Address column
Command column
Parameters column
General Purpose Registers

COMMANDS
The commands we will be using are all in this pic. I'll also list a few useful ones that aren't.
NOP = No operation
LUI = Load Upper Immediate (load the first part of your address)
LBU = Load Byte Unsigned (load the second half of your address)
ADDIU = Add Immediate Unsigned word (checks for specified value)
BNE = Branch on not Equal (go to specified ASM action if value is NOT equal)
BEQ = Branch Equal (go to specified ASM action if value IS equal)
J = Jump (Jump to specified ASM action) This action in most cases must be followed by a NOP
LW = Load word (word = 4 bytes "xxxxxxxx")
LH = Load halfword (halfword = 2 bytes "xxxx")
LB = Load byte (byte = 1 byte "xx")
SW = Store word
SH = Store halfword
SB = Store byte

PARAMETERS
These must be typed in correctly or else they won't set.
They contain what registers to use for each action then what addresses or values to use per command.
Addresses and values MUST start with "0x" or they won't work.

GENERAL PURPOSE REGISTERS
I'm not too knowledgeable on these. I just understand that they're used to temporarily store info to compare and decide actions.
You can learn a lot more about these or anything else in the Tutorial linked at the top of this page.

BREAKDOWN
Ok, let's read what we have in our commands.
This example looks for the current menu, then changes the background value depending on the menu value.
(You might want to open this image in a separate window)

Show Pic:

In the reference above first we see
800430C0 LUI V0, 0x8004
Load the first half of desired address and store it to register "V0"
800430C4 LBU V0, 0x5845 (V0)
Load the second half of desired address and store it to register "V0"
800430C8 ADDIU S1, R0, 0x000F
Store the value 000F to register "S1"
800430CC BNE V0, S1, 0x800430DC
Compare the values at "V0" and "S1". If they are not the same or not "equal", go to command at 800430DC

If you look at the branch arrow at 800430CC, it will skip the command directly after BNE. Meaning if they ARE equal, instead of branching it will follow the next command.

So lets breakdown the commands at
800430D0 ADDIU V1, R0, 0x44DC
Load value 44DC (background) to register "V1"
800430D4 LUI V0, 0x8015
Load first half of address we want to store the value to
800430D8 SH V1, 0xA2F8 (V0)
Store the Halfword (2 byte value) from "V1" to the address loaded to "V0"
BOOM background will change if it's on the correct page (000F)

NOTE: ASM rule: If the second half of your address is greater than 0x7FFF then we need to add 0x0001 to the first half of the desired address.
Meaning our address isn't really "8015A2F8", it's actually "8014A2F8"
This is because in hex, a value greater than 7FFF is considered an negative number. This is not the case for Jump or Branch commands.
There's a better explanation of this in the tutorial link above.

Regardless if the value is equal or not, the game will follow the next command lines in order unless the Jump or Branch commands tell it otherwise.
If you understand this so far, then you can see in the reference pic that the next steps 800430E4-80043140 all check for each page value, then branch to seperate commands to load their specified values (backgrounds)
These changes can be seen at
80043150
80043164

After this, I get a bit more complicated, looking for the main menu page, the in-game timer, and a few other things to make for different backgrounds at certain times all on the same page (0002).
I won't be going over this because it's not really important for the sake of this tutorial.

All you need to remember is that the commands will go down the line and NEED to go somewhere. But where? and how did it start at 800430C0 to begin with?



RUN YOUR CUSTOM COMMANDS
To run our custom ASM, we need to cut into the game's pre-set ASM routine. To do this we need to alter the pre-exsisting ASM order then Jump (J) to our custom location.
Once we finish our custom ASM, we MUST Jump back to where our cut-in left off. Or else....GAME CRASH.
Looking at the last reference pic, you'll notice after following all the jumps and branches (or just looking at the bottom of the pic) that it Jumps to 0x80109A28
This is where I jumped from to begin with.

How do we know where to jump from?
We look into our memory viewer at a value that changes the moment we want our custom ASM to occur. 
An "activator" of sorts.
We right click the value and choose "toggle write breakpoint". Usually, when the value changes it will cause the game to point to the ASM commands that make this occur in the R4300i command viewer.
From here, I look for a clean J command.
This isn't always easy (for me at least). For instance, the page change value 80045845, did not cause a breakpoint.
So instead, I used the timer values that changes when highlighted on menu items. (this is available in my menu reference tool).
https://www.tapatalk.com/groups/generation_hex/every-menu-selection-addy-t894.html
Each menu item has their own timer, but thankfully, they all stem from the same ASM.

Show Pic:

The blue line, greyish/purple "6F" in the memory viewer is my chosen breakpoint, the timer value that constantly changes when selected on Exhibition.
This breakpoint shows in the command window where it stems from: 8010924C in yellow.
looking below this value I see a Jump command at 80109280.
I copy down this command "J 0x80109A28" then replace it with my own J command, pointing it to where I want it to go.
In my case it's at J 0x800430C0. A blank area of memory that I've noticed is also blank in the ROM.
Then, after writing our custom commands at our custom location, make sure to end it with the original Jump command that we've copied down. "J 0x80109A28"

And hopfully if your jump point is a good one, it won't crash your game.


NOTES:
When a breakpoint occurs, the game will pause until you click the address added to the box in the top right portion of the command window, click the minus button, then click "Go".

If you're altering the commands without an active breakpoint, be sure to pause the emu (F2) to avoid game crashes.

After writing commands in the command window, you'll notice the memory viewer will show new values at the same address. They look different but mean the same thing. These are the values you need to copy/paste if you wish to ROM hack them.

Here are some blank section in the RAM/ROM if you wish to ROM hack them. Otherwise you can write GS codes in any section of blank memory.

ROM                MEM                LENGTH
00042940    80041D50      310
00043CC0   800430C0    340
00055E70     80055270     D0
00056290     80055690     D0
000FB200    80154A60      930
I try to keep about 0x16 blank bytes before writing to avoid crashes.

Hopefully I didn't forget an important part in this tutorial. Let me know if anyone has any questions or reference the tutorial at the beginning for more in-depth explanations and many more commands that are above my head.