Discovering GameShark cheat codes

There are a lot of popular cheat codes in Pokémon games: walk through walls, get Rare Candies and Master Balls, find wild shiny Pokémon, get all the Badges... Different physical cheat devices exist, like GameShark, Game Genie, Action Replay, and even Pokémon-specific ones like Monster Brain. Game Boy emulators tend to support GameShark-style cheat codes because they're popular and straightforward.

A GameShark cheat code looks like this: ttvvllhh

• tt is the code type. 01 stays in the current WRAM bank. 9x will switch to WRAM bank x. 8x will switch to SRAM bank x.
  • Some Pokémon cheat guides, like the Glitch City Wiki, suggest to start codes with 01 "but if it doesn't work, change it to 91". This is because many meaningful values in Pokémon GSC are in WRAM bank 1, and the game is often already in that bank (so 01 is fine), but in some circumstances a code may need to explicitly switch to it.
• vv is the value to write into RAM. It's a hexadecimal byte from $00 to $FF.
• hhll is the RAM address to write to. Note that it's little-endian in the code, low byte first.

We can reverse-engineer the meaning of particular codes, and discover our own new codes, with the symbol files. When we run make to build the ROM, along with the .gbc file it creates a .sym file. This file lists all the labels from the source code with their corresponding banks and addresses in the ROM.

For example, the code 010730D2 writes 07 to 01:D230. We can look up this address in pokecrystal.sym: it's wBattleType, from wram.asm. Its appropriate values are the BATTLETYPE_* constants, from constants/battle_constants.asm, of which #7 (remember, const_def counts up from 0) is BATTLETYPE_SHINY. So this looks like a cheat to force shiny battles like Red Gyarados. And sure enough, in Matthew Robinson's Pokemon Crystal Gameshark Code Archive, that code appears as "Fight Shiney Pokemon".

We can design new codes this way. If your pokecrystal-based hack project ended up shifting the location of wBattleType, or changed the value of BATTLETYPE_SHINY, then the code 010730D2 would affect something else, and might do nothing, cause glitches, or crash the game. But you can just find the new address of wBattleType in your own .sym file and edit the code to use that.

For example, if your hack's .sym file has a line 01:d345 wBattleType, that means it shifted wBattleType to address $D345. Then the edited code for shiny battles would be 010745D3.

Note that not every address has its own label. For example, Matthew Robinson lists these four codes as "skill modifiers":

Skill 1 Modifier 01??E1DC
Skill 2 Modifier 01??E2DC
Skill 3 Modifier 01??E3DC
Skill 4 Modifier 01??E4DC

But only one of those four addresses has a label in pokecrystal.sym:

01:dce1 wPartyMon1Moves

Nor is there any wPartyMon1Moves label in wram.asm. However, there is this:

wPartyMon1:: party_struct wPartyMon1

And macros/wram.asm defines the party_struct macro:

party_struct: MACRO
	box_struct \1
\1Status::         db
...
\1StructEnd::
ENDM

box_struct: MACRO
\1Species::        db
\1Item::           db
\1Moves::          ds NUM_MOVES
...
\1BoxEnd::
ENDM

That ds NUM_MOVES means that the label wPartyMon1Moves covers four bytes, not one (since NUM_MOVES EQU 4 in constants/battle_constants.asm). Cheat codes can affect any of the four move bytes, but only one label exists.