Map System

The map system defines the game’s world structure, from outdoor routes to indoor buildings, with a sophisticated organization of tiles, connections, and map data.

Map Organization

Maps are organized into three categories defined in constants/map_constants.asm:

Towns and Cities

The 11 main population centers, numbered sequentially from $00 to $0A.

Routes

The 25 outdoor routes connecting cities, from Route 1 to Route 25.

Indoor and Dungeon Maps

Buildings, caves, and special locations, grouped by their associated outdoor map.

Map Constants

The map_const macro defines each map with its ID, width, and height:

const_def
map_const PALLET_TOWN,      10,  9  ; $00
map_const VIRIDIAN_CITY,    20, 18  ; $01
map_const PEWTER_CITY,      20, 18  ; $02
map_const CERULEAN_CITY,    20, 18  ; $03
map_const LAVENDER_TOWN,    10,  9  ; $04
map_const VERMILION_CITY,   20, 18  ; $05
map_const CELADON_CITY,     25, 18  ; $06  ; Largest city!
map_const FUCHSIA_CITY,     20, 18  ; $07
map_const CINNABAR_ISLAND,  10,  9  ; $08
map_const INDIGO_PLATEAU,   10,  9  ; $09
map_const SAFFRON_CITY,     20, 18  ; $0A
DEF NUM_CITY_MAPS EQU const_value

The map_const macro automatically generates three constants:

PALLET_TOWN = $00 (map ID)
PALLET_TOWN_WIDTH = 10 (width in tiles)
PALLET_TOWN_HEIGHT = 9 (height in tiles)

Map Dimensions

Maps vary significantly in size:

Map Type	Typical Width	Typical Height	Example
Small Town	10 tiles	9 tiles	Pallet Town
Large City	20-25 tiles	18 tiles	Celadon City
Small Route	10 tiles	18-27 tiles	Route 1
Long Route	10 tiles	36-72 tiles	Route 2, Route 17
Wide Route	30-45 tiles	9 tiles	Route 4
Indoor	4-7 tiles	4-9 tiles	Red’s House

Route 17 (10×72 tiles) is the tallest map, representing the long bike path. Route 4 (45×9 tiles) is the widest route.

Indoor Map Groups

Indoor maps are grouped with their outdoor locations using end_indoor_group:

map_const REDS_HOUSE_1F,  4, 4  ; $25
map_const REDS_HOUSE_2F,  4, 4  ; $26
map_const BLUES_HOUSE,    4, 4  ; $27
map_const OAKS_LAB,       5, 6  ; $28
end_indoor_group PALLET_TOWN

map_const VIRIDIAN_POKECENTER,    7, 4  ; $29
map_const VIRIDIAN_MART,          4, 4  ; $2A
map_const VIRIDIAN_SCHOOL_HOUSE,  4, 4  ; $2B
map_const VIRIDIAN_NICKNAME_HOUSE,4, 4  ; $2C
map_const VIRIDIAN_GYM,          10, 9  ; $2D
end_indoor_group VIRIDIAN_CITY

Grouping tracks which maps belong to each location, useful for the Town Map and for organizing the 248 total maps in the game.

Map Data Files

Each map has associated data files:

Block Data (.blk)

Tile layout stored in maps/*.blk as binary block data:

PalletTown.blk
ViridianCity.blk
Route1.blk

Each byte represents a block ID (4×4 tiles), making maps memory-efficient.

Block vs Tile System

Maps use a two-level tile system:

Blocks: 4×4 tile groups with a single ID
Tiles: Individual 8×8 pixel graphics

This reduces map data size by ~16× compared to storing individual tiles.

Map Headers

Map headers in data/maps/map_header_pointers.asm point to:

Tileset ID
Map dimensions
Block data pointer
Text pointers
Script pointers
Connection data

Map Connections

Large outdoor maps can connect to adjacent maps:

; Example connection structure:
; - Direction (North, South, East, West)
; - Connected map ID
; - Strip pointer (which part of the map connects)
; - Strip length

When the player walks to the edge of a connected map, the game seamlessly loads the adjacent map without a transition screen.

Map Headers Structure

Each map header contains:

; Tileset ID (determines available blocks)
db TILESET_ID

; Map dimensions
db HEIGHT, WIDTH

; Pointers
dw BlockData
dw TextPointers
dw ScriptPointers

; Connections (if any)
db CONNECTION_FLAGS
; ... connection data ...

Tilesets

Tilesets define which blocks are available on a map. From constants/tileset_constants.asm:

const_def
const TILESET_OVERWORLD    ; $00 - Outdoor areas
const TILESET_REDS_HOUSE   ; $01 - Interior
const TILESET_MART         ; $02 - Poké Marts
const TILESET_FOREST       ; $03 - Viridian Forest
const TILESET_GYM          ; $04 - Gym interiors
const TILESET_POKECENTER   ; $05 - Pokémon Centers
; ... more tilesets ...

Each tileset includes:

Block definitions (which tiles make up each block)
Collision data (which blocks are walkable)
Graphic tile pointers
Animated tile data

Maps using the same tileset share the same block palette. This is why all Pokémon Centers look similar—they use the same tileset.

Sprite Sets

Maps reference sprite sets that determine which overworld sprites can appear:

MapSpriteSets:
    db SPRITE_SET_PALLET_TOWN
    db SPRITE_SET_VIRIDIAN_CITY
    db SPRITE_SET_PEWTER_CITY
    ; ...

Each sprite set defines which NPC sprites (characters, Pokémon, items) are loaded into VRAM for that map.

Map Scripts

Maps can have scripts that execute when:

Player enters the map
Player presses A on an object
Player walks on specific tiles (script tiles)
Special events trigger

Scripts are written in a custom scripting language and stored per-map.

Map Objects

Each map can contain:

NPCs

Trainers, Gym Leaders, shopkeepers, and other characters with dialogue and behavior.

Items

Visible Poké Balls containing items, retrievable once per save file.

Hidden Items

Invisible items found with the Itemfinder, tracked via bit flags.

Warps

Tile-based teleporters that move the player to different maps.

Signs

Readable signs with text messages.

Warp System

Warps connect maps together:

; Warp data format:
db WARP_TO_MAP_ID
db WARP_TO_X
db WARP_TO_Y

When the player steps on a warp tile:

Fade out current map
Load destination map
Place player at warp destination coordinates
Fade in new map

Warps are bidirectional—entering a building and exiting use the same warp system with different destinations.

Wild Encounter Data

Maps with wild Pokémon reference encounter tables from data/wild/:

; Wild data format:
db ENCOUNTER_RATE  ; 0-255, chance per step
db 10 Pokémon species and levels

Each map can have separate encounter tables for:

Grass encounters
Water encounters (Surf)
Fishing encounters (Old/Good/Super Rod)

Map Music

Each map has an associated music track stored in data/maps/songs.asm:

MapSongBanks:
    db MUSIC_PALLET_TOWN
    db MUSIC_CITIES1      ; Viridian City
    db MUSIC_CITIES1      ; Pewter City
    db MUSIC_CITIES2      ; Cerulean City

Music changes automatically when entering a new map.

Special Maps

Route 23

The longest route in the game (10×72 tiles), with badge requirement gates.

Seafoam Islands

Multi-level dungeon with puzzle elements requiring Strength to manipulate boulders.

Safari Zone

Multiple connected maps with a step counter and special battle mechanics.

Unused Map

map_const UNUSED_MAP_0B,  0, 0  ; $0B

An unused map ID exists in the constants, likely a leftover from development.

Overworld

Player movement and collision

Audio

Map music assignments

Reference

Map constants and data

Architecture

Map data organization

Key Files

constants/map_constants.asm - Map IDs and dimensions
constants/tileset_constants.asm - Tileset definitions
maps/*.blk - Binary map block data
data/maps/map_header_pointers.asm - Map header pointers
data/maps/map_header_banks.asm - ROM bank organization
data/maps/sprite_sets.asm - Sprite set assignments
data/maps/songs.asm - Music track assignments
maps.asm - Main map assembly file

Get Started

Architecture

Game Systems

Code Reference

Development

Map Organization

Map Constants

Map Dimensions

Indoor Map Groups

Map Data Files

Block Data (.blk)

Map Headers

Map Connections

Map Headers Structure

Tilesets

Sprite Sets

Map Scripts

Map Objects

Warp System

Wild Encounter Data

Map Music

Special Maps

Route 23

Seafoam Islands

Safari Zone

Unused Map

Overworld

Audio

Reference

Architecture

Key Files

Build docs developers (and LLMs) love

Get Started

Architecture

Game Systems

Code Reference

Development

​Map Organization

​Map Constants

​Map Dimensions

​Indoor Map Groups

​Map Data Files

​Block Data (.blk)

​Map Headers

​Map Connections

​Map Headers Structure

​Tilesets

​Sprite Sets

​Map Scripts

​Map Objects

​Warp System

​Wild Encounter Data

​Map Music

​Special Maps

​Route 23

​Seafoam Islands

​Safari Zone

​Unused Map

Overworld

Audio

Reference

Architecture

​Key Files

Build docs developers (and LLMs) love

Map Organization

Map Constants

Map Dimensions

Indoor Map Groups

Map Data Files

Block Data (.blk)

Map Headers

Map Connections

Map Headers Structure

Tilesets

Sprite Sets

Map Scripts

Map Objects

Warp System

Wild Encounter Data

Map Music

Special Maps

Route 23

Seafoam Islands

Safari Zone

Unused Map

Key Files