Engine Modules Reference - Pokémon Red/Blue Disassembly

Overview

The Pokémon Red/Blue engine is organized into specialized modules located in the engine/ directory. Each module handles a specific aspect of the game, from battles to overworld movement to menu systems. This modular architecture makes the codebase easier to understand and modify, with clear separation of concerns between different game systems.

Engine Architecture

engine/
├── battle/         - Battle system and combat mechanics
├── overworld/      - Map navigation and field interactions
├── menus/          - Menu systems and UI
├── pokemon/        - Pokémon management and data
├── items/          - Inventory and item effects
├── events/         - Scripting and event handling
├── gfx/            - Graphics and visual effects
├── link/           - Link cable communication
├── math/           - Mathematical utilities
├── debug/          - Debug features
├── slots/          - Game Corner slot machines
└── movie/          - Intro sequences

Battle System

Combat mechanics, moves, and AI

Overworld

Map navigation and field movement

Menu Systems

UI and player interactions

Pokémon Management

Party and PC storage

Item System

Inventory and item effects

Event System

Scripts and triggers

Battle System

Location: engine/battle/ The battle engine handles all combat mechanics including damage calculation, status effects, AI behavior, and battle animations.

Core Files

core.asm - Battle Core Loop

Key Functions:

BattleCore:
    ; Main battle initialization and loop
    ; Handles turn flow and battle state

SlidePlayerAndEnemySilhouettesOnScreen:
    ; Battle intro animation
    call LoadPlayerBackPic
    call DisplayTextBoxID
    call LoadFontTilePatterns

Battle Flow:

Initialize battle variables
Display battle intro
Main turn loop:
- Player chooses action
- AI chooses action
- Determine move order
- Execute moves
- Apply residual effects
- Check for battle end
Handle battle outcome

effects.asm - Move Effects

Key Responsibilities:

Damage calculation
Status effect application
Stat modification
Special move effects (Substitute, Transform, etc.)

Example Effect:

BurnEffect:
    ; Apply burn status
    ld a, 1 << BRN
    ld [hl], a  ; Set status byte
    call PlayBurnAnimation
    ; Burn does damage each turn

experience.asm - EXP & Leveling

Key Functions:

GainExperience:
    ; Calculate experience gain
    ; Apply EXP share if held
    ; Check for level up
    ; Learn new moves

CalcExpGain:
    ; Formula: (base_exp * level) / 7
    ; Modified by trainer battle (1.5x)
    ; Modified by trade status (1.5x)

Move Effects System

Location: engine/battle/move_effects/ Each complex move effect has its own file:

substitute_effect.asm - Creates substitute doll
confusion_side_effect.asm - Confusion mechanics
haze_effect.asm - Removes all stat changes
recoil_effect.asm - Recoil damage calculation
mist_effect.asm - Prevents stat reduction

Battle State Variables

; Key battle variables in WRAM
wBattleType::          db  ; NORMAL, OLD_MAN, SAFARI
wIsInBattle::          db  ; $FF during battle
wBattleResult::        db  ; WIN, LOSE, DRAW, RAN

; Player battle state
wPlayerBattleStatus1:: db  ; Status flags
wPlayerBattleStatus2:: db  ; More status flags
wPlayerBattleStatus3:: db  ; Even more status
wPlayerMovePower::     db  ; Current move power
wPlayerMoveEffect::    db  ; Current move effect

; Enemy battle state (parallel structure)
wEnemyBattleStatus1::  db
wEnemyBattleStatus2::  db

Overworld System

Location: engine/overworld/ Manages map navigation, sprite movement, collision detection, and field interactions.

Core Components

map_sprites.asm - Sprite Management

InitMapSprites:

InitMapSprites::
    call InitOutsideMapSprites
    ret c  ; Return if outside map
    ; For indoor maps, load sprite tiles individually
    ld hl, wSpritePlayerStateData1PictureID

LoadMapSpriteTilePatterns:
    ; Load sprite graphics to VRAM
    ; Handle 4-tile sprites vs 2-tile sprites

Sprite System:

Up to 16 sprites per map
Each sprite has two data structures:
- SpriteStateData1 - Animation and position
- SpriteStateData2 - Map coordinates and movement

movement.asm - Movement Engine

Key Functions:

UpdateSprites::
    ; Update all sprite positions
    ; Handle walking animations
    ; Check for collisions
    ; Process NPC movement patterns

CheckCollision::
    ; Check map collision data
    ; Check sprite-to-sprite collision
    ; Handle warp tiles
    ; Handle ledges

Movement Patterns:

STAY - Stand still
WANDER - Random movement
WALK - Predefined path
LOOK - Turn to face player
SPINRANDOM - Spin randomly
SPINCLOCKWISE - Rotate clockwise

player_state.asm - Player Control

HandlePlayerInput:

CheckForPlayerMovement::
    ; Read joypad input
    ; Check if player can move
    ; Initiate walking animation
    ; Handle running (held B button)
    ; Update facing direction

DoPlayerMovement::
    ; Move player sprite
    ; Scroll map if needed
    ; Check for wild encounters
    ; Check for trainer battles

hidden_events.asm - Item Balls & Signs

Hidden Item System:

CheckForHiddenObject::
    ; Check if player facing hidden item
    ; Check if already obtained
    ; Display message
    ; Add item to bag
    ; Set obtained flag

CheckForSign::
    ; Check if player facing sign
    ; Display sign text

Field Moves

Location: engine/overworld/ (various files)

cut.asm - Cut down trees
surf.asm - Water navigation
strength.asm - Push boulders (push_boulder.asm)
flash.asm - Illuminate dark caves

Location: engine/menus/ Handles all menu interfaces including the start menu, party menu, bag, and PC systems.

Key Menus

start_sub_menus.asm - Start Menu

Start Menu Options:

StartMenuItems:
    db "POKéDEX@"
    db "POKéMON@"
    db "ITEM@"
    db "PLAYER@"
    db "SAVE@"
    db "OPTION@"
    db "EXIT@"

DisplayStartMenu::
    ; Draw menu window
    ; Handle cursor movement
    ; Process selection
    ; Call submenu handlers

party_menu.asm - Pokémon Menu

Party Menu Features:

View Pokémon summary
Switch Pokémon order
Use items on Pokémon
Teach TMs/HMs
Select for battle

Key Functions:

DisplayPartyMenu::
    ; Draw party status boxes
    ; Show HP bars
    ; Display status conditions
    ; Handle selection

PartyMenuSwap::
    ; Swap two party Pokémon
    ; Update internal data
    ; Redraw menu

pokedex.asm - Pokédex Interface

Pokédex Modes:

PokedexMode_List::
    ; Alphabetical listing
    ; Shows caught/seen status
    ; Search functionality

PokedexMode_Entry::
    ; Display Pokémon entry
    ; Show sprite and description
    ; Display height/weight
    ; Show area caught

pc.asm - PC System

PC Types:

Someone’s PC - Pokémon storage
Bill’s PC - Box management
Player’s PC - Item storage
Prof. Oak’s PC - Pokédex rating
League PC - Hall of Fame

Key Files:

players_pc.asm - Item storage
oaks_pc.asm - Pokédex rating
league_pc.asm - Hall of Fame records

Pokémon Management

Location: engine/pokemon/ Handles Pokémon data loading, storage, evolution, and status management.

Core Systems

load_mon_data.asm - Data Loading

LoadMonData:

LoadMonData::
    ; Input: wcf91 = species ID
    ; Load base stats
    ; Load types
    ; Load learnset
    ; Calculate stats from DVs

CalcStats::
    ; Formula: ((Base + DV) * 2 + EV^0.5) * Level / 100 + Level + 10
    ; For HP: add 10 instead of Level + 10

add_mon.asm - Adding Pokémon

AddPartyMon:

AddPartyMon::
    ; Check if party is full
    ; Initialize Pokémon data
    ; Generate DVs
    ; Set initial moves
    ; Calculate stats
    ; Set current HP to max

GivePokemon::
    ; Used for gift Pokémon
    ; Displays nickname screen
    ; Adds to party or PC

evos_moves.asm - Evolution & Moves

Evolution Types:

EVOLVE_LEVEL  ; Level up evolution
EVOLVE_ITEM   ; Stone evolution
EVOLVE_TRADE  ; Trade evolution

TryEvolvingMon::
    ; Check evolution conditions
    ; Play evolution animation
    ; Transform to new species
    ; Learn evolution moves

bills_pc.asm - Box Storage

Box System:

; 12 boxes with 20 Pokémon each
DEF MONS_PER_BOX EQU 20
DEF NUM_BOXES    EQU 12

WithdrawPokemon::
    ; Move from box to party
    ; Verify party has space

DepositPokemon::
    ; Move from party to box
    ; Verify box has space

ReleasePokemon::
    ; Permanently delete Pokémon

Item System

Location: engine/items/ Manages inventory, item effects, and TM/HM mechanics.

Key Components

inventory.asm - Bag Management

Inventory Functions:

AddItemToInventory::
    ; wcf91 = item ID
    ; wItemQuantity = amount
    ; Check if item exists in bag
    ; Stack with existing or add new slot
    ; Sort key items separately

RemoveItemFromInventory::
    ; Decrease quantity
    ; Remove slot if quantity = 0
    ; Compress item list

item_effects.asm - Item Usage

Effect Types:

Medicine (Potions, Full Heal, etc.)
Status healing (Antidote, Awakening, etc.)
Battle items (X Attack, Dire Hit, etc.)
Evolution stones
Poké Balls
Key items

Effect Handler:

ItemUsePtrTable:
    dw ItemUsePotion
    dw ItemUseAntidote
    dw ItemUsePokeBall
    ; ... etc

UseItem::
    ; Get item effect pointer
    ; Call effect function
    ; Update menu if needed

tmhm.asm - TM/HM System

Teaching Moves:

TeachTMMove::
    ; Check if Pokémon can learn
    ; Select move slot (delete if needed)
    ; Learn new move
    ; Don't consume HM (only TMs consumed)

CheckCanLearnTMHM::
    ; Check compatibility bitfield
    ; 7 bytes = 56 bits for 55 TM/HMs

Event System

Location: engine/events/ Handles scripting, hidden items, gifts, trades, and special events.

Event Types

Hidden Events

Location: engine/events/hidden_events/Hidden Items:

HiddenItemPositions::
    ; Each map has hidden item data
    db map_id
    db y, x          ; Position
    db item_id       ; What item
    db flag_id       ; Obtained flag

Hidden Objects:

Item balls
Hidden items (Itemfinder)
PC terminals
Vending machines
Signs and posters

in_game_trades.asm - NPC Trades

Trade System:

TradeData:
    db TRADE_FOR, TRADE_GIVE  ; Pokémon species
    dw nickname               ; Traded Pokémon's nickname
    dw OTID                   ; Original Trainer ID
    db DVs                    ; Individual values

DoInGameTrade::
    ; Check player has requested Pokémon
    ; Show trade animation
    ; Swap Pokémon
    ; Set trade flag

give_pokemon.asm - Gift Pokémon

Receiving Pokémon:

GivePokemon::
    ; Starter Pokémon (Oak's lab)
    ; Gift Pokémon (Eevee, Lapras, etc.)
    ; Fossil resurrection
    ; Game Corner prizes

Graphics System

Location: engine/gfx/ Handles graphics loading, animation, and visual effects.

Key Systems

screen_effects.asm - Screen transitions
sprite_oam.asm - Sprite rendering
load_pokedex_tiles.asm - Pokédex graphics
mon_icons.asm - Menu icons

Module Interactions

Best Practices

Understand Module Boundaries

Each module has clear responsibilities. Keep related functionality together.

Use Existing Functions

Many common operations have dedicated functions. Don’t reinvent the wheel.

Follow Data Flow

Understand how data moves between modules through RAM variables.

Test Module Changes

Changes to core modules can have wide-reaching effects. Test thoroughly.

Key RAM Variables

Global Variables

; Temp storage used across modules
wcf91::  db  ; Universal temp (often holds species/item ID)
wd11e::  db  ; Another common temp
hld::    db  ; HRAM temp

; System state
wJoyIgnore::          db
wUpdateSpritesEnabled:: db
wAutoTextBoxDrawingControl:: db

Module-Specific Variables

Each module typically has a dedicated WRAM section for its variables. For example:

Battle: wBattle* variables
Menu: wMenu* variables
Sprite: wSprite* variables

Constants Reference - Constants used by modules
Macros Reference - Helper macros
Data Structures - Memory layouts

Get Started

Architecture

Game Systems

Code Reference

Development

​Overview

​Engine Architecture

Battle System

Overworld

Menu Systems

Pokémon Management

Item System

Event System

​Battle System

​Core Files

​Move Effects System

​Battle State Variables

​Overworld System

​Core Components

​Field Moves

​Menu Systems

​Key Menus

​Pokémon Management

​Core Systems

​Item System

​Key Components

​Event System

​Event Types

​Graphics System

​Key Systems

​Module Interactions

​Best Practices

Understand Module Boundaries

Use Existing Functions

Follow Data Flow

Test Module Changes

​Key RAM Variables

​Global Variables

​Module-Specific Variables

​Related Pages

Build docs developers (and LLMs) love

Overview

Engine Architecture

Battle System

Core Files

Move Effects System

Battle State Variables

Overworld System

Core Components

Field Moves

Menu Systems

Key Menus

Pokémon Management

Core Systems

Item System

Key Components

Event System

Event Types

Graphics System

Key Systems

Module Interactions

Best Practices

Key RAM Variables

Global Variables

Module-Specific Variables

Related Pages