Skip to main content

​
Introduction

The Pokémon Red and Blue disassembly is a complete reverse-engineering of the original Game Boy games, reconstructed into human-readable assembly language. This project allows developers to understand, modify, and learn from the original game’s implementation.

​
Project Structure

The disassembly is organized into several key components:

Source Code

Assembly files organized by functionality (engine, data, graphics)

Build System

Makefile-based build process using RGBDS toolchain

ROM Banks

Code and data distributed across 45 ROM banks (16KB each)

Memory Layout

Structured RAM, VRAM, and SRAM for game state

​
Directory Organization

The project follows a clear organizational structure: 
source/
├── constants/          # Game constants and definitions
│   ├── hardware.inc   # Game Boy hardware registers
│   └── ram_constants.asm
├── engine/            # Game logic and systems
│   ├── battle/       # Battle system
│   ├── overworld/    # Map and movement
│   ├── menus/        # UI systems
│   └── pokemon/      # Pokémon data management
├── data/             # Game data
│   ├── pokemon/      # Species data
│   ├── moves/        # Move definitions
│   └── maps/         # Map data
├── gfx/              # Graphics assets
│   ├── pics/         # Pokémon sprites
│   └── tilesets/     # Map tilesets
├── home/             # Bank 0 (always loaded)
├── ram.asm           # RAM layout definitions
├── main.asm          # ROM sections and includes
└── layout.link       # Linker script

​
Code Organization

​
Section-Based Structure

The code is organized using RGBDS SECTION directives that define where code and data are placed in the ROM: 
SECTION "bank1", ROMX

INCLUDE "data/sprites/facings.asm"
INCLUDE "engine/events/black_out.asm"
INCLUDE "data/pokemon/mew.asm"
INCLUDE "engine/battle/safari_zone.asm"

​
Bank System

The Game Boy’s banking system allows access to more memory than the addressable 64KB space:
  • Bank 0 (ROM0): Always accessible at $0000-$3FFF, contains core routines
  • Banks 1-44 (ROMX): Switchable at $4000-$7FFF, contain game content
  • Banking is managed through the MBC3 memory bank controller

​
Build Process

1

Assembly

RGBDS assembler (rgbasm) processes .asm files into object files
rgbasm -D _RED -Q8 -P includes.asm -o main_red.o main.asm
2

Linking

RGBDS linker (rgblink) combines object files using the layout script
rgblink -l layout.link -m pokered.map -n pokered.sym -o pokered.gbc
3

Fixing

RGBDS fix (rgbfix) sets ROM header and checksums
rgbfix -jsv -p 0x00 -t "POKEMON RED" pokered.gbc
4

Graphics Processing

RGBGFX converts PNG images to Game Boy tile format
rgbgfx --colors dmg -o gfx/file.2bpp gfx/file.png

​
Key Build Targets

From the Makefile: 
roms := \
	pokered.gbc \
	pokeblue.gbc \
	pokeblue_debug.gbc

rom_obj := \
	audio.o \
	home.o \
	main.o \
	maps.o \
	ram.o \
	text.o \
	gfx/pics.o \
	gfx/sprites.o \
	gfx/tilesets.o
The build system supports both Pokémon Red and Blue versions by using conditional assembly directives (-D _RED or -D _BLUE).

​
Assembly to ROM Flow

​
Memory Map Overview

RegionAddress RangeDescription
ROM Bank 0$0000-$3FFFFixed home bank
Switchable ROM$4000-$7FFFBanks 1-44
VRAM$8000-$9FFFVideo memory
External RAM$A000-$BFFFCartridge save data
Work RAM$C000-$DFFFMain game state
Echo RAM$E000-$FDFFMirror of WRAM
OAM$FE00-$FE9FSprite attributes
I/O Registers$FF00-$FF7FHardware control
High RAM$FF80-$FFFEFast access RAM

​
Toolchain Requirements

The project uses the RGBDS (Rednex Game Boy Development System) toolchain:

rgbasm

Assembler that processes Z80-like assembly into object files

rgblink

Linker that combines objects and places sections in the ROM

rgbfix

ROM fixer that sets header values and checksums

rgbgfx

Graphics converter for PNG to Game Boy tile format

​
Version-Specific Features

The build system handles differences between versions: 
IF DEF(_RED)
    ; Red version specific code
    db RED_VERSION_BYTE
ELSE
    ; Blue version specific code
    db BLUE_VERSION_BYTE
ENDC
The disassembly maintains byte-perfect accuracy with the original ROMs, verified through SHA-1 checksums.

​
Next Steps

Game Boy Hardware

Learn about the Game Boy’s CPU, memory, and hardware

Memory Layout

Explore how RAM and variables are organized

ROM Structure

Understand how the ROM is organized

Bank System

Deep dive into ROM banking mechanics

Build docs developers (and LLMs) love

Get started for freeTalk to us