Skip to main content

​
Overview

This guide will walk you through cloning the repository, building ROM files, and verifying your build. The entire process takes just a few minutes once you have RGBDS installed.
Make sure you’ve completed the Installation guide for your platform before continuing.

​
Building Your First ROMs

1

Clone the Repository

Open your terminal and download the source code using Git:
git clone https://github.com/pret/pokered
cd pokered
This creates a pokered directory containing all the source files, including:
  • Assembly source files (.asm)
  • Graphics data
  • Maps and scripts
  • The build system (Makefile)
2

Build the ROMs

From the pokered directory, run the build command:
make
This will:
  1. Assemble all .asm source files into object files
  2. Convert graphics from PNG to Game Boy format
  3. Link everything together into ROM files
  4. Apply ROM fixes and headers
The build process typically takes 30-60 seconds on modern hardware. You’ll see output showing which files are being processed.
The first build may take longer as it compiles the build tools and processes all graphics files.
3

Find Your ROMs

After a successful build, you’ll find these files in the project root:
  • pokered.gbc - Pokémon Red ROM
  • pokeblue.gbc - Pokémon Blue ROM
  • pokeblue_debug.gbc - Debug build of Pokémon Blue
These are complete, playable Game Boy Color ROMs that you can load in an emulator!
4

Verify Your Build

To confirm your ROMs match the original games exactly, run:
make compare
This compares the SHA1 checksums of your built ROMs against the known checksums of the original games. You should see:
ea9bcae617fdf159b045185467ae58b2e4a48b9a *pokered.gbc
d7037c83e1ae5b39bde3c30787637ba1d4c48ce2 *pokeblue.gbc
5b1456177671b79b263c614ea0e7cc9ac542e9c4 *pokeblue_debug.gbc
If the checksums match, congratulations! Your build is byte-for-byte identical to the original games. This confirms the disassembly is accurate and your environment is set up correctly.

​
Understanding the Build Targets

The Makefile supports several build targets for different purposes: 
make
# or
make all

​
Build Target Reference

TargetOutputDescription
allpokered.gbc, pokeblue.gbc, pokeblue_debug.gbcBuilds all ROM files (default)
redpokered.gbcBuilds only Pokémon Red
bluepokeblue.gbcBuilds only Pokémon Blue
blue_debugpokeblue_debug.gbcDebug build with special features
compare-Verifies ROM checksums match originals
clean-Removes all build artifacts including graphics
tidy-Removes ROMs and object files only
The debug build (pokeblue_debug.gbc) includes development features that weren’t in the original release. Look for _DEBUG conditionals in the source code to see what’s different.

​
What Gets Built?

When you run make, several types of files are generated:

​
ROM Files

  • pokered.gbc - The complete Pokémon Red game
  • pokeblue.gbc - The complete Pokémon Blue game
  • pokeblue_debug.gbc - Debug version with extra features

​
Symbol Files (.sym)

Symbol files map memory addresses to function and label names. Useful for debugging in emulators:
  • pokered.sym
  • pokeblue.sym
  • pokeblue_debug.sym

​
Map Files (.map)

Map files show how data is laid out in the ROM:
  • pokered.map
  • pokeblue.map
  • pokeblue_debug.map

​
Graphics Files

Converted graphics in Game Boy format:
  • .1bpp - 1 bit per pixel (2 colors)
  • .2bpp - 2 bits per pixel (4 colors)
  • .pic - Compressed Pokémon sprites
Symbol files are incredibly useful when debugging or reverse engineering. Load them in emulators like BGB or mGBA to see function names instead of memory addresses.

​
Testing Your ROMs

To play your built ROMs, you’ll need a Game Boy emulator:

BGB

Best for development/debugging
  • Windows (works on Linux via Wine)
  • Excellent debugger with symbol support
  • bgb.bircd.org

mGBA

Best for casual play
  • Cross-platform (Windows, macOS, Linux)
  • Accurate emulation
  • mgba.io

SameBoy

Highly accurate

Gambatte

Accuracy-focused
Simply open pokered.gbc or pokeblue.gbc in your emulator of choice!

​
Cleaning Up

To remove build artifacts and start fresh: 
make clean
Difference between clean and tidy:
  • make clean - Removes ROMs, object files, AND converted graphics (.1bpp, .2bpp, .pic)
  • make tidy - Removes only ROMs and object files, keeps converted graphics
After make clean, graphics will need to be regenerated on the next build, which takes longer. Use make tidy if you just want to rebuild the ROMs quickly.

​
Advanced Build Options

​
Using a Local RGBDS Version

If you have RGBDS installed in a local directory: 
make RGBDS=rgbds-1.0.1/

​
Debug Builds with Symbols

To generate extra debugging information: 
make DEBUG=1
This creates .sym and .map files even for release builds.

​
Building Virtual Console Patches

To create patches for 3DS Virtual Console releases: 
make red_vc    # Creates pokered.patch
make blue_vc   # Creates pokeblue.patch
These patches contain the differences needed to run on the 3DS Virtual Console.

​
What’s Inside the ROMs?

Your built ROMs contain everything from the original games:

Game Engine

Battle system, overworld movement, menus, events, and all core game logic

Pokémon Data

All 151 Pokémon with stats, moves, types, and evolution data

Maps & Scripts

Every town, route, building, and dungeon with NPC dialogue and events

Graphics & Audio

All sprites, tilesets, animations, music, and sound effects
The ROM layout is organized into banks (memory sections):
  • Bank 0 (Home) - Essential functions always accessible
  • Banks 1-31 - Switchable banks containing specific features
  • Each bank is 16KB (except Home which is 8KB)

​
Troubleshooting

​
Build Fails with “rgbasm: command not found”

Solution: RGBDS isn’t installed or not in your PATH. Revisit the Installation guide.

​
”Error: Unknown symbol” During Assembly

Solution: Usually means dependencies aren’t up to date. Try: 
make clean
make

​
Checksums Don’t Match

Solution: Could be using wrong RGBDS version or source code modified. Try: 
git status          # Check for modified files
git diff            # See what changed
rgbasm --version    # Verify RGBDS 1.0.1

​
Build is Very Slow

Solution: First build is slower due to graphics processing. Subsequent builds are much faster. Use make tidy instead of make clean to avoid reconverting graphics.
For more help, ask on Discord in the #pokered channel or check the GitHub Issues.

​
Next Steps

Now that you have a working build environment, here’s what to explore next:
1

Explore the Source Code

Open the .asm files in a text editor and start reading. Key files to start with:
  • main.asm - Shows the overall code organization
  • constants/pokemon_constants.asm - Pokémon species definitions
  • engine/battle/core.asm - Main battle engine
  • data/pokemon/base_stats.asm - Pokémon stats
2

Make a Simple Modification

Try changing something simple like:
  • Starting money in engine/movie/oak_speech/init_player_data.asm
  • Pokémon stats in data/pokemon/base_stats.asm
  • Starter Pokémon levels
Then rebuild with make and test your changes!
3

Read the Documentation

Check out these resources:
4

Join the Community

Connect with other ROM hackers and developers:

GitHub Wiki Tutorials

Browse community-created tutorials for adding features, creating new content, and understanding the codebase

Build docs developers (and LLMs) love

Get started for freeTalk to us