[Dissassembly] Setting up and using the Pokeruby/Pokeemerald dissassembly

[ProjectRevoTPP]

Setting up and using Pokeruby/Pokeemerald​

Part 0: An Introduction

Spoiler:

I'm sure you've all heard of the recent gen 3 disassemblies and want to use them. That's good: but I'm sure an equal portion of you are on Windows and don't know how to make salad from scratch. So, how do you use pokeruby to make changes to things such as the code itself and what advantages does it offer me over traditional binary hacking, I hear you ask?

I'm glad you asked, but first we need to go over traditional methods of hacking gen 3.

1. Pre-Existing Tools
Currently, changing things in ROM requires just that: directly editing a ROM. The thing is though that pointers and data itself cant be moved without moving it to free space in the ROM, and whatever pointed there needs to be repointed by hand, manually, in order to avoid issues. This is particularly annoying if you're making a lot of changes.

2. Compiled C Injection
So what if you want to add new code? Well, you could write some C and compile it into ARM and thumb, and then manually change the pointers in your code to direct at the correct ROM data and redirect anything to use your new function. Still sounds very annoying? Well, lets talk about how this ROM was assembled in the first place.

The Pokemon games, in Game Freak's original source, were written in a programming language called C - specifically C90, a version of C published in 1990. This means all the data and code that make up the ROM were written in separate human-readable C files. These files are then run through a compiler to generate machine code. This machine code output is all joined together using a tool called a linker, which figures out how to combine these fragments into the final output (the ROM). This linking process determines the final offsets and recalculates every pointer for all the data and code automatically, meaning you don't have to keep track of the locations of data, only the labels given to that data.

By reversing this process, we can translate all the pointers and binary data (that you'd edit in a hex editor or another tool) back into human-readable C. This means that we can repeat the compiling and linking processes to get a modified ROM, but maintain the flexibility of being able to work with labeled data and code.

What is compilation you ask?

Compilation is the process that takes a higher level language and compiles it into assembly so the computer can understand and execute the instructions. This can be used for a number of reasons: but the main one here is that it makes a programmer's job easier when all they have to deal with is the higher level language and not things like register balancing and reallocation by hand.

There are a number of compiler/developer environments, but the one we will be using for this tutorial is Cygwin and thus assumes you have Windows at the moment. (Sorry Linux and Mac)

Part 1: Following pokeruby's INSTALL.md

Linux

Install devkitARM.

Then run the following commands.

	export DEVKITPRO=/opt/devkitPro
	echo "export DEVKITPRO=$DEVKITPRO" >> ~/.bashrc
	export DEVKITARM=$DEVKITPRO/devkitARM
	echo "export DEVKITARM=$DEVKITARM" >> ~/.bashrc

	git clone [url]https://github.com/pret/pokeruby[/url]
	git clone [url]https://github.com/pret/agbcc[/url]

	cd agbcc
	./build.sh
	./install.sh ../pokeruby

	cd ../pokeruby

To build pokeruby.gba:

make -j4

Mac

Install devkitARM.

Then in Terminal, run the following commands.

	xcode-select --install

	export DEVKITPRO=${HOME}/devkitPro
	echo "export DEVKITPRO=${DEVKITPRO}" >> ~/.bashrc
	export DEVKITARM=${DEVKITPRO}/devkitARM
	echo "export DEVKITARM=${DEVKITARM}" >> ~/.bashrc

	git clone [url]https://github.com/pret/pokeruby[/url]
	git clone [url]https://github.com/pret/agbcc[/url]

	cd agbcc
	./build.sh
	./install.sh ../pokeruby

	cd ../pokeruby

To build pokeruby.gba:

	make -j4

Windows

Install devkitARM to the default directory (C:/devkitpro).

Then download Cygwin setup-x86_64.exe for 64-bit Windows, setup-x86.exe for 32-bit.

Run the Cygwin setup and leave the default settings. At "Select Packages", set the view to "Full" and choose to install the following:

• make
• git
• gcc-core
• gcc-g++
• libpng-devel

In the Cygwin terminal, enter these commands:

	export DEVKITPRO=/cygdrive/c/devkitpro
	echo export DEVKITPRO=$DEVKITPRO >> ~/.bashrc
	export DEVKITARM=$DEVKITPRO/devkitARM
	echo export DEVKITARM=$DEVKITARM >> ~/.bashrc

	git clone [url]https://github.com/pret/pokeruby[/url]
	git clone [url]https://github.com/pret/agbcc[/url]

	cd agbcc
	./build.sh
	./install.sh ../pokeruby

	cd ../pokeruby

To build pokeruby.gba:

	make -j4

Compiling Sapphire and later revisions

When you simply enter make and don't specify a target, then Pokémon Ruby 1.0 will be built. However, Sapphire can also be built, along with revisions 1 and 2 of both Ruby and Sapphire. Here is a listing of each ROM that can be made, along with the command to make the ROM.

Version      | Command
-------------|---------------------
Ruby 1.0     | make ruby
Ruby 1.1     | make ruby_rev1
Ruby 1.2     | make ruby_rev2
Sapphire 1.0 | make sapphire
Sapphire 1.1 | make sapphire_rev1
Sapphire 1.2 | make sapphire_rev2

Faster builds

After the first build, subsequent builds are faster. You can further speed up the build:

Parallel build

This significantly speeds up the build on modern machines.

By default make only runs a single thread. You can tell make to run on multiple threads with make -j. See the manfile for usage (man make).

The optimal value for -j is the number of logical cores on your machine. You can run nproc to see the exact number.

	$ nproc
	8

If you have 8 cores, run:

	make -j8

-j on its own will spawn a new thread for each job. A clean build will have thousands of jobs, which will be slower than not using -j at all.

Disable the dependency scanning

If you've only changed .c or .s files, you can turn off the dependency scanning temporarily. Changes to any other files will be ignored, and the build will either fail or not reflect those changes.

	make NODEP=1

Part 2: Making changes and test them

Spoiler:

TODO: Make better guides

Conclusion:

You'll be able to make code changes with the disassembly similar to this fashion. To note: pokeemerald nor pokefirered is not ready for production yet, obviously, but this tutorial will teach you how to use it on a most basic level. Although this does and will open up gen 3 tremendously: there is much work to be done; we need to work more on pokefirered sometime down the line. Hopefully, now that you know how to setup the dissassemblies, you know how to make changes and eventually contribute to our cause. Thanks for reading.

 

[Delta231]

I prefer reading INSTALL.md instead of this tutorial as its outdated.

 

[Shachar700]

Any idea how to solve this issue with Msy2 or Cygwin?

Spoiler:

 

[Delta231]

Any idea how to solve this issue with Msy2 or Cygwin?

Spoiler:

Can you show us what you exactly did?

 

[Shachar700]

I installed devkitPro Updater v3.0.3 on my Windows 10 (64 bit) and followed the instructions and got 2 popped up messages through the installation process

Spoiler:

https://prnt.sc/mlf2z8

then opened msys2 and received an error message, I didn't encounter that error message in a different PC.

 

[Avara]

You might be better off following the INSTALL.md instructions for pokéemerald/pokéruby as those are updated more frequently and this guide is a little outdated at the moment.

 

[LCCoolJ95]

Okay, so I downloaded pokeemerald, got devkitARM, and got the tools from https://github.com/pret/pokeruby-tools and put it in pokeemerald.

I don't really understand the last part: You can then build pokeemerald using make in the MSYS environment provided with devkitARM.

It's kind of vague, no offense. Do I need a ROM? Is the ROM already made?

 

[TheXaman]

Okay, so I downloaded pokeemerald, got devkitARM, and got the tools from github and put it in pokeemerald.

I don't really understand the last part: You can then build pokeemerald using make in the MSYS environment provided with devkitARM.

It's kind of vague, no offense. Do I need a ROM? Is the ROM already made?

No ROM is needed, you basicly make your own ROM from the code.
You open the programm MSYS or MSYS2 depending on which one you have installed. Its, as far as I can tell, a alternate command line tool like cmd on windows.
In this window you navigate to the main folder of your downloaded source code of pokeemerald. To do so you use "cd DRIVELETTTER:/" to change drives, "ls" to list all files and folders and "cd FOLDERNAME" to enter a folder, "cd .." to get up one folder (all commands without "").
Once inside the correct folder you type in "make" and wait. Once it has finished, you can find the newly made ROM (.gba file) inside the same folder.
Hope it helps

PS: If my explanation isnt clear enough, look for a basic toturial on how to navigate a linux terminal.

 

[Delta231]

Okay, so I downloaded pokeemerald, got devkitARM, and got the tools from https://github.com/pret/pokeruby-tools and put it in pokeemerald.

I don't really understand the last part: You can then build pokeemerald using make in the MSYS environment provided with devkitARM.

It's kind of vague, no offense. Do I need a ROM? Is the ROM already made?

The ROM is already made when you are done with compiling.

 

[robinjea]

Okay, I'm just gonna say it. The INSTALL.md file is actually really bad. Just trying to make the file, it says "You can then build pokeemerald using make in the MSYS environment provided with devkitARM." First of all, MSys doesn;t open, only MSys does. Next, I did everything before that (get Devkit, put the pokeruby tools in the file). But then, it says make...make what? Look, I'm not a very good programmer, but don't you have to explain what you're using the command to do? What file executes the make command? Honestly, if these guys have the intelligence to do all this other stuff, why not "make" a better tutorial lol

Hey, don't take this offensively. Actually, if you try a little harder, I think you'll get it. After installing devkit, open MSys (labelled as MSys2 now for me). It's a batch file you can see in the Start Menu>devkitPro>MSys2. This is a command-line based application. You don't really need programming skills to run a command-line. All you need to know is how to change directory to the one where you store your pokeemerald or pokeruby. After changing directory, type "make" and press enter. That's all it takes. And by the way, if you still find it hard following what I just said, why don't you try your hand at pokeruby first. They have a more in-depth installation instructions. This is due to the fact that pokeemerald was based on pokeruby in some way, making pokeruby the predecessor. And maybe you are missing some pre-requisites which you can easily look up. I had a lot of trouble with this as well in the beginning. But I did my best, on my own, looking things up on Google, until I got it.

P.S. English is not my first language. Do excuse my sentence structure.

 

[Kekxile]

Hello; this is my first post. I have somewhat of a specific problem: I followed all the steps to the letter, but halfway through my "make" I get this error message:

>>tools/jsonproc/jsonproc.exe src/data/wild_encounters.json src/data/wild_encounters.json.txt src/data/wild_encounters.h
>>JSONPROC_ERROR: [inja.exception.render_error] function 'setVarInt' (2) not found
>>make: *** [json_data_rules.mk:6: src/data/wild_encounters.h] Error 1
>>make: *** Deleting file 'src/data/wild_encounters.h'

I had a dig around in "wild_encounters.json", and the function "setVarInt" doesn't seem to be defined there. Any insight you could give me would be very helpful.

 

[DizzyEgg]

Hello; this is my first post. I have somewhat of a specific problem: I followed all the steps to the letter, but halfway through my "make" I get this error message:

>>tools/jsonproc/jsonproc.exe src/data/wild_encounters.json src/data/wild_encounters.json.txt src/data/wild_encounters.h
>>JSONPROC_ERROR: [inja.exception.render_error] function 'setVarInt' (2) not found
>>make: *** [json_data_rules.mk:6: src/data/wild_encounters.h] Error 1
>>make: *** Deleting file 'src/data/wild_encounters.h'

I had a dig around in "wild_encounters.json", and the function "setVarInt" doesn't seem to be defined there. Any insight you could give me would be very helpful.

This is most likely caused by the tools being outdated. Re-build them using build_tools.sh.