Cross-assembler between Game Boy Z80 and inventory payloads for the ACE glitch item 8F in the games Pokémon Red and Blue. Not affiliated with Game Freak, Nintendo, or The Pokémon Company.
Go to file
blujai831 b4d818b555
bump version number
2024-03-07 05:46:07 -08:00
payloads forgot to say what the B button does in the memory editor 2024-03-07 05:45:51 -08:00
LICENSE.txt Initial commit. 2024-03-03 00:53:17 -08:00
README.md Corrected broken link in readme. 2024-03-07 04:20:09 -08:00
poke-8f-util bump version number 2024-03-07 05:46:07 -08:00

README.md

poke-8f-util

Cross-assembler between Game Boy Z80 and inventory payloads for the ACE glitch item 8F in the games Pokémon Red and Blue. Not affiliated with Game Freak, Nintendo, or the Pokémon Company.

Copyright ©2024 alias blujai831 webmaster@blujai831.dev. Provided under Thufie's CNPLv7.

Background

The 1996 video games Pokémon Red and Blue for the Nintendo Game Boy were riddled with game-breaking bugs. The games stand the test of time in spite of this, because the more serious problems are buried behind convoluted rituals, and one won't tend to run into them in a casual playthrough. By seeking them out, however, we can derail the game so utterly, that in conjunction with a healthy sense of immersion, it feels like sorcery.

The most famous severe glitch that occurs in these games is the old man glitch, which grants access to MissingNo., an unofficial Pokémon defined entirely by garbage data. However, MissingNo. is far from the only case where it's possible for the player to cause the game to interpret data incorrectly. There are countless such instances, in the form of additional invalid Pokémon, as well as invalid skills, items, NPCs, and even maps.

The culmination of what can be accomplished by exploiting glitches to access this garbage data is the invalid item 8F. It's typically obtained via item underflow. Using it causes runtime execution to jump to the player's party and interpret it as instructions. From there, with an adversarially sequenced party, we can setup a bootstrap to jump to the third item slot in inventory, where we can spell out a more complex program, which might be our final payload, or we might choose to use that space as an additional bootstrap to spell out and jump to an even more complex payload in reserve item storage or the current reserve party box. The quantity of each item necessary to spell out any given program is typically absurd, but because every time one encounters MissingNo. the high bit of the quantity byte for the sixth item slot is set (thus increasing the quantity by 128 if it was below 128), these absurd quantities are more attainable than they might appear.

This general technique of exploiting glitches in software to cause it to generate and invoke additional software of the user's own adversarial design is called arbitrary code execution, or ACE. Per the name, it truly is arbitrary: people have used 8F to do everything from skipping to the end of the game, to forging signatures for otherwise-illegitimate copies of the distribution-only Pokémon Mew (typically obtained in the first place via the trainer escape glitch), to programming other simpler games such as Pong or Snake into Pokémon Red and Blue and playing them for demonstration purposes, to sending proof-of-concept viruses over multiplayer, to programming custom cutscenes that create the illusion that the game is dynamically transitioning into other later Game Boy titles, to cheating in other actual games via cartridge hot-swapping.

This cross-assembler is designed primarily to ease the task of writing small Game Boy assembly programs that correspond to viable in-game inventory or reserve item storage setups, and by extension the task of performing with 8F whatever nefarious tricks one might desire.

Dependencies

Requires Ruby. Tested on v3.0.6.

Installation

Windows

If you wish, rename the file poke-8f-util to poke-8f-util.rb for greater clarity. We will proceed assuming you've chosen to do so. (It ships without the file extension because it's developed on Linux, whose shebang feature allows it to be installed as a PATH executable, and such executables traditionally do not have file extensions.)

Ensure the folder containing the Ruby interpreter executable is registered to your PATH environment variable.

Put the file poke-8f-util.rb wherever you want it and run it by opening a Command Prompt or PowerShell session in the same folder and typing ruby poke-8f-util.rb. This should show you a help message. Under ---USAGE---, you will see a list of valid subcommands. When using those subcommands, replace poke-8f-util with ruby poke-8f-util.rb. For example, you can type ruby poke-8f-util.rb asm to bag < my-assembly.txt to cross-assemble the Game Boy Z80 assembly file my-assembly.txt to a Pokémon inventory payload.

Linux

Copy poke-8f-util to $HOME/.local/bin or analogous path on your system (or, if you prefer, /usr/local/bin or analogous path). Alternatively, if you prefer, you can run it in a terminal opened to its parent directory with ./poke-8f-util.

For further instructions, run poke-8f-util in a terminal (or ./poke-8f-util as applicable). This should show you a help message. Under ---USAGE---, you will see a list of valid subcommands. For example, you can type poke-8f-util asm to bag < my-assembly.txt to cross-assemble the Game Boy Z80 assembly file my-assembly.txt to a Pokémon inventory payload.

macOS

I don't have a mac. Theoretically, instructions should be very similar to those provided for Linux. You may have to install Ruby via Homebrew. It might not be possible or useful to install poke-8f-util to $HOME/.local/bin or /usr/local/bin; in this case, it should be harmless to simply store it anywhere you like and run it in a terminal opened to its parent directory with ./poke-8f-util.

Android

Check out Termux. You can install Ruby via its package manager. From there, instructions should be very similar to those provided for Linux. As with macOS, however, it might not be possible or useful to install to $HOME/.local/bin or /usr/local/bin, so it should be harmless to simply store the script anywhere you like and run it from its parent directory with ./poke-8f-util.

iOS

There are terminal apps out there for iOS. That is unfortunately the full extent of my knowledge on the subject. Sorry! At least one of them can probably run Ruby. I wouldn't know.

Resources

For using 8F in-game

You can obtain 8F via the Celadon looping map trick as described here.

You can find a list of various 8F bootstrap party loadouts here and a list of various inventory payloads here. I recommend TheZZAZZGlitch's polymorphic bootstrap, demonstrated here and documented in text here.

This project also provides several example asm scripts of my own design, documented with their intended usage, here.

You will need very large and often not naturally possible quantities of various items to sequence practically any 8F inventory payload. You can obtain such quantities by repeatedly encountering MissingNo., as each encounter will add 128 to the quantity of the sixth item slot if it is below 128. The most straightforward way to encounter MissingNo. is via the old man glitch.

You must have access to Cinnabar Island to perform the old man glitch, which requires Surf, so, excepting careful use of save corruption, you will have to have beaten Koga and found the Safari Zone Secret House. To advance to this point in the game as quickly as possible, you can obtain a level 100 Pokémon before the first gym via the trainer escape glitch (see section "Level 100 Pokémon before Brock (Red/Blue)" on that page).

Youtuber TheZZAZZGlitch's in-game memory editor, demonstrated here, can be used for much more streamlined arbitrary code execution. The original purpose of this project was to assist me in developing a more reliable way of installing that memory editor. Instructions on using the provided example payloads to install the memory editor are available here.

For scripting for 8F

If you want to write your own scripts, you can find ROM and RAM maps for the games here, unofficial documentation of Game Boy Z80 assembly here, and a list of particularly relevant addresses here.

Note that because of the way inventory works in Pokémon Red and Blue, an inventory payload requiring inconvenient or impossible item setups can often be ameliorated by prefixing offending instructions with spacer instructions that do nothing relevant (but bear in mind this lengthens the item setup, and inventory space is limited).