Symbols and Addresses

Introduction

This BizHawk tool uses symbols to read addresses and access data. The first advantage of using this encoding is that decompilation projects provide these files (.sym). The second advantage is that it allows developers to use names rather than addresses, making it easier to read what's been done. Finally, it allows you to read at different addresses depending on the game, but always using the same name.

Each pokémon game has its own folder (Symbols/emerald) with 1 or more files inside. There's always the main file, which is the name of the game, such as pokeemerald.sym, and then patch files. These patch files are generally mandatory for the different languages (fr, de, it, sp, jp).

Existing game

If the game you wish to correct is already supported by the tool, but some of the symbols are incorrect or missing, follow these steps to correct them.

Step 1: Create the file

Basic but necessary, create the file inside Symbols/<game> folder. The file must use the name patch<game>_<lang>.sym.

Step 2: Understand the format

Each symbol file use the same format: 030048B0 c 00000000 gObjectEvents. Corresponding to address (hexa) - type (global, local, ...) - size (hexa) - name. In patch file you are authorized to put # at the beginning of any line to ignore this line when reading. In patch file you can only use 2 custom types:

• 'c' for custom -> it will replace an existing symbol with this new address or ignore if the name doesn't exists
• 'a' for add -> it will add this symbol if it doesn't exists (not recommanded to use because you need to do that for every game) For more example, check patchemerald_fr.sym.

Step 3: Find new addresses

Run the code in debug mode and the debug window should appear. You'll have access to data such as the player's position and current tasks. Find the problem addresses and try to correct them using the tools provided (Finder tab or even BizHawk's RAM search).

If you find value in 0x03xx address, check the difference between en (original file) and your language. In most case the difference is 16 decimal. You just need to add 16 to every addresses you need.

Here's a list of addresses that is used in this tool and can cause problems and how to find the correct address:

be aware that some of the symbols below may not exist in the chosen game, in which case ignore them

Symbol Name	Mandatory	Games	Description	How to find
gMain	✅	All	Get callbacks to know what's the current callback (overworld, battle, ...)	FSAllthis address is quite complicated to find. You can try to find all adresses that have the first 4 bytes don't move and the 4 next moves when you open / close your bag (from the map). In Fire Red I search for all addresses that changes when I open the bag. The changes must be 3 when you open and 3 when you close. When you find this address check if the prvevious one (-4 bytes) change or not. If it doesn't, you find it.
CB2_Overworld	✅	All	This callback from main tell the player is in a map	be on the map (ouside) and select gMain, size 4 and offset 4 and click 'reverse addr'. Address will be show
CB2_StarterChoose	❌	Emerald	This callback from main tell the player is selecting a starter	be in the starter bag and select gMain, size 4 and offset 4 and click 'reverse addr'. Address will be show
BattleMainCB2	✅	All	This callback from main tell the player is in battle	be in battle and select gMain, size 4 and offset 4 and click 'reverse addr'. Address will be show
CB2_NamingScreen	✅	Fire Red / Leaf Green	This callback from main tell the player is renaming a pokemon	open pokemon naming screen and select gMain, size 4 and offset 4 and click 'reverse addr'. Address will be show
Task_Fishing	❌	All	This task tell the player is fishing	fish and check tasks tab
Task_HandleStarterChooseInput	✅	Emerald	This task tell the player is choosing a starter	use tasks tab and open starter bag, the number is the address in decimal
Task_HandleConfirmStarterInput	✅	Emerald	This task tell the player is confirming a starter	use tasks tab and open starter bag and select a starter, the number is the address in decimal
Task_StarterChoose2	✅	Sapphire / Ruby	This task tell the player is choosing a starter	use tasks tab and open starter bag, the number is the address in decimal
Task_StarterChoose5	✅	Sapphire / Ruby	This task tell the player is confirming a starter	use tasks tab and open starter bag and select a starter, the number is the address in decimal
gPlayerAvatar	✅	All	Contains some information about player (gender, flag, direction, bike state)	expected value is 2, size is 1 and click 'run 3s delay' and walk no stop. Address with 0 as value when you stop moving is the correct one. Address will be result - 2
gObjectEvents	✅	All	Contains some information about player (position, direction, ...)	go in front of starter bag, expected value 14 (X position), size is 2 and click 'run'. Address will be result - 10
gPlayerPartyCount	✅	All	Contains how many pokemon has the player	use RAM Seacher with BizHawk and remove / add pokemon to your party to find the address
gPlayerParty	✅	All	Contains all pokemon information from the player's party	often gPlayerPartyCount address + 10 (hexa) or default gPlayerParty + 10 (hexa)
gEnemyParty	✅	All	Contains all pokemon information from the opponent's party	often default gEnemyPartyCount + 10 (hexa)
gTasks	✅	All	Contains all the tasks currently running	Quite difficult, try to find another address in the same domains and deduct the new address using the difference between original and correction. Then compare the result with game in US and another language. The number of tasks with data should be similar
gActionSelectionCursor	✅	All	Contains the index of the selected action in battle (moves, bag, party or escape)	use BizHawk RAM Search while in combat and switch between (attack = 0, sac = 1, party = 2 and escape = 3)
gRngValue	✅	All	Contains the current rng seed (changed every frame)	check all addresses from the domains every the value is quite big and change every frame
gSaveblock2	❌	Emerald	Contains the saved data
gSaveBlock2	✅	Fire Red / Leaf Green / Sapphire / Ruby	Contains the saved data
gSaveBlock2Ptr	✅	Fire Red / Leaf Green / Emerald	Contains the pointer to the saved data

Step 4: Fix new addresses

When you agree with the corrective, add the created or modified file to ResourceSymbols.resx - very important! When it's done, go to app.config in your game's hash and add the patch to the list.

New game (rom hack or other generation)

This page is not adapted for this case. Please check this page.