Contributing - Pokémon Red/Blue Disassembly

Welcome Contributors

The Pokémon Red/Blue disassembly is a community project maintained by pret (Pokémon Reverse Engineering Team). We welcome contributions of all kinds, from documentation improvements to code cleanup to new discoveries.

Getting Started

Before contributing, make sure you can build the project:

Fork the Repository

Visit github.com/pret/pokered and click “Fork” to create your own copy.

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/pokered.git
cd pokered

Build the ROM

make

Verify you can build successfully before making changes.

Verify Matching Build

make compare

This confirms your build matches the original ROMs.

If make compare fails on a fresh clone, there’s an issue with your build environment. Ask for help on Discord before continuing.

Types of Contributions

Code Improvements

What we’re looking for:

Label Names

Rename generic labels to descriptive names that explain what the code does.

Function Documentation

Add comments explaining complex routines, algorithms, and data structures.

Data Identification

Identify unknown data blocks and convert them to proper structures.

Macro Creation

Create macros to make repeated patterns more readable.

Code Organization

Reorganize files to group related functionality together.

Bug Documentation

Document known bugs and their behavior in the original game.

Documentation

Wiki articles - Tutorials and explanations
Code comments - Inline documentation
README updates - Improve setup instructions
Technical documentation - Document game mechanics

Bug Fixes

The primary goal is to disassemble the original game, not fix its bugs. However, documenting bugs is valuable.

Acceptable bug-related contributions:

Documenting bugs with comments
Creating separate branches with bug fixes
Explaining why bugs exist in the original code

Not acceptable:

Fixing bugs in the main branch (breaks matching build)

Contribution Guidelines

Code Style

Follow the existing code style:

Labels
Indentation
Comments
Constants

Function labels: PascalCase

HandleMenuInput:
    ; code here

Local labels: .camelCase starting with a dot

.loop
    ; code here
    jr .loop

Data labels: PascalCase or SCREAMING_SNAKE_CASE for constants

PokemonNames:
MAX_PARTY_SIZE EQU 6

Use tabs for indentation:

Function:
	ld a, 5        ; instruction
	ld [wValue], a ; store
	ret

Align comments at column 40 if space allows:

	ld a, [wPartyCount]              ; get party size
	call PrintNumber                  ; display it

Use comments to explain intent:

; Calculate damage: (Attack * 2 / 5) + 2
	ld a, [wAttack]
	sla a           ; multiply by 2
	ld b, 5
	call DivideAByB
	add 2

Not the obvious:

; BAD: Don't state the obvious
	ld a, 5         ; load 5 into a
	
; GOOD: Explain why
	ld a, 5         ; set battle type to Old Man tutorial

Use constants instead of magic numbers:

; BAD
	ld a, 151
	cp [hl]
	
; GOOD
	ld a, MEW
	cp [hl]

Define constants at the top of files or in constants/:

DEF PARTY_LENGTH EQU 6
DEF NAME_LENGTH EQU 11

Testing Your Changes

Build Successfully

make clean
make

Ensure no compilation errors.

Verify Matching Build

make compare

This must pass. Your changes should not alter the generated ROM unless you’re intentionally making a non-matching change (rare and requires approval).

Test with DEBUG=1

make clean
make DEBUG=1 compare

Verify symbols are generated correctly.

Test in Emulator

Load the ROM in BGB, mGBA, or another emulator.

Navigate to affected code areas
Test any functionality you documented
Verify behavior matches the original

Check Formatting

Review your changes:

git diff

No trailing whitespace
Consistent indentation (tabs)
No unintended changes

make compare uses SHA-1 checksums to verify your ROM matches the original exactly. This is the gold standard for disassembly projects.

Submitting Changes

Creating a Pull Request

Create a Branch

git checkout -b descriptive-branch-name

Use descriptive names like document-battle-system or rename-menu-functions.

Make Your Changes

Edit files, test thoroughly, and commit:

git add .
git commit -m "Document the DoBattleMenu function"

Write a Good Commit Message

Good commit messages:

“Document the battle damage calculation”
“Rename generic labels in the menu system”
“Identify wUnknownData as wTempMoveData”

Bad commit messages:

“Update main.asm”
“Changes”
“Fixed stuff”

Push to GitHub

git push origin descriptive-branch-name

Open Pull Request

Go to your fork on GitHub
Click “Pull Request”
Select your branch
Write a description of your changes
Submit the PR

Pull Request Description

Include in your PR description:

What changed: Brief summary of modifications
Why: Explanation of the improvement
Testing: How you verified it still matches
References: Link to wiki pages, issues, or research

Example:

## Summary
This PR documents the battle damage calculation functions in `engine/battle/core.asm`.

## Changes
- Renamed `Func_3c000` to `CalculateDamage`
- Added comments explaining the damage formula
- Identified data structure at `wBattleTempData`

## Testing
- `make compare` passes
- Verified in BGB debugger that function is called during battle
- Checked against similar code in pokeyellow

## References
- [Damage Calculation Wiki](https://bulbapedia.bulbagarden.net/wiki/Damage)

Community Guidelines

Getting Help

Discord

pret Discord#pokered channel for questions and discussion

GitHub Issues

pokered issuesReport bugs or discuss large changes

Wiki

pokered wikiTutorials and documentation

Symbols Branch

Symbols referenceComplete symbol files

Best Practices

Start Small

Begin with small contributions:

Fix typos in comments
Rename a few labels
Document a single function

Build up to larger changes as you learn the codebase.

Ask Before Big Changes

For major refactoring or reorganization:

Open an issue describing your plan
Get feedback from maintainers
Proceed once there’s consensus

This avoids wasted effort on changes that won’t be accepted.

One Thing Per PR

Keep pull requests focused:

One feature or improvement
Related changes grouped together
Easier to review and merge

Split unrelated changes into separate PRs.

Reference Your Research

When documenting game mechanics:

Link to Bulbapedia articles
Reference other gen 1 games (Yellow, GSC)
Cite community research

This helps reviewers verify accuracy.

Be Patient

Maintainers review PRs as time permits:

May take days or weeks for review
Feedback may request changes
Discussion is part of the process

Be responsive to feedback and willing to revise.

Code of Conduct

Be respectful - Treat all contributors with kindness
Be constructive - Focus on improving the project
Be patient - Not everyone has the same skill level
Be collaborative - Work together toward common goals
Be open-minded - Consider different perspectives

Advanced Topics

Comparing with Other Games

When documenting code, compare with:

Pokémon Yellow - pret/pokeyellow
Pokémon Gold/Silver - pret/pokegold
Japanese Red/Green - Similar code, different versions

Many functions are identical across games. If something is documented in Yellow, you can often apply the same labels to Red/Blue.

Understanding the Build System

Key files to understand:

Makefile - Build rules and targets
layout.link - Memory layout
rgbdscheck.asm - RGBDS version verification
includes.asm - Common definitions pre-included in all files

Working with Graphics

Graphics workflow:

Export PNG from ROM using tools
Edit PNG in graphics editor
Convert back to 2bpp with rgbgfx
Process with gfx tool if needed
Compress Pokémon sprites with pkmncompress

Resources:

gb-asm-tools - Additional utilities
GB Studio - Visual Game Boy tools
RGBDS documentation - Toolchain reference

Finding Undocumented Code

Areas that need work:

Search for Func_ or Unknown in the codebase
Check for generic labels like asm_ or Data_
Look for sparse comments
Compare with pokeyellow to find documented equivalents

# Find functions that need names
grep -r "Func_" --include="*.asm"

# Find unknown data
grep -r "Unknown" --include="*.asm"

Recognition

Major contributors are listed in the project’s commit history and may be mentioned in the README. The pret community values all contributions, large and small. Notable contributions that make a difference:

Documenting entire game systems (battle, menu, map)
Identifying and labeling large data structures
Creating comprehensive wiki articles
Mentoring new contributors

Additional Resources

pokeyellow - Pokémon Yellow
pokegold - Pokémon Gold/Silver
pokecrystal - Pokémon Crystal
pokepinball - Pokémon Pinball
poketcg - Pokémon TCG

Learning Resources

Game Boy ASM Tutorial

GB ASM TutorialLearn Game Boy assembly from scratch

Pan Docs

Pan DocsComplete Game Boy technical reference

RGBDS Documentation

RGBDS DocsAssembler and toolchain documentation

Awesome Game Boy Dev

Awesome ListCurated Game Boy development resources

Debugging Resources

BGB - bgb.bircd.org - Best Windows debugger
Emulicious - emulicious.net - Cross-platform with great debugging
SameBoy - github.com/LIJI32/SameBoy - Accurate emulator with debugger

Thank You

Thank you for contributing to the Pokémon Red/Blue disassembly project. Every contribution helps preserve and understand this classic game’s code.

Don’t be intimidated if you’re new to assembly or disassembly projects. Everyone starts somewhere, and the community is here to help you learn.

Join us on Discord: discord.gg/d5dubZ3 (#pokered channel) Project repository: github.com/pret/pokered

Get Started

Architecture

Game Systems

Code Reference

Development

​Welcome Contributors

​Getting Started

​Types of Contributions

​Code Improvements

Label Names

Function Documentation

Data Identification

Macro Creation

Code Organization

Bug Documentation

​Documentation

​Bug Fixes

​Contribution Guidelines

​Code Style

​Testing Your Changes

​Submitting Changes

​Creating a Pull Request

​Pull Request Description

​Community Guidelines

​Getting Help

Discord

GitHub Issues

Wiki

Symbols Branch

​Best Practices

​Code of Conduct

​Advanced Topics

​Comparing with Other Games

​Understanding the Build System

​Working with Graphics

​Finding Undocumented Code

​Recognition

​Additional Resources

​Related Projects

​Learning Resources

Game Boy ASM Tutorial

Pan Docs

RGBDS Documentation

Awesome Game Boy Dev

​Debugging Resources

​Thank You

Build docs developers (and LLMs) love

Welcome Contributors

Getting Started

Types of Contributions

Code Improvements

Documentation

Bug Fixes

Contribution Guidelines

Code Style

Testing Your Changes

Submitting Changes

Creating a Pull Request

Pull Request Description

Community Guidelines

Getting Help

Best Practices

Code of Conduct

Advanced Topics

Comparing with Other Games

Understanding the Build System

Working with Graphics

Finding Undocumented Code

Recognition

Additional Resources

Related Projects

Learning Resources

Debugging Resources

Thank You