World and Maps

Map structure, events, and the overworld engine.

The overworld (field) is the layer players explore between battles. It is driven by src/overworld.c and composed of maps, tilesets, event objects, scripts, weather, and field move effects.

Map structure

Each in-game map lives in its own subdirectory under data/maps/. A map consists of:

data/maps/PalletTown/
├── header.inc       # Map group/number, layout, tilesets, connection count, music, etc.
├── map.json         # porymap-compatible map metadata
├── events.inc       # Object events, warp events, coord events, background events
└── scripts.pory     # Event scripts (or .inc for raw assembly)

Map headers reference a layout by name. Layouts live under data/layouts/ and point to the two tilesets the map uses:

data/layouts/PalletTown/
├── layout.json      # Dimensions, tileset references, border metatile block
└── PalletTown.bin   # Compiled metatile index grid (width × height × 2 bytes)

Every map uses exactly two tilesets: a primary tileset (terrain, water, ground) and a secondary tileset (buildings, decoration, map-specific tiles). Both are defined under data/tilesets/.

Metatile behaviors

Metatile behaviors control how the player and NPCs interact with each tile. Constants are defined in include/metatile_behavior.h as MB_* values.

// include/metatile_behavior.h (selected constants)
#define MB_NORMAL                       0x00  // walkable, no effect
#define MB_BLOCKED_FROM_BELOW           0x01
#define MB_BLOCKED_FROM_ABOVE           0x02
#define MB_BLOCKED_FROM_LEFT            0x03
#define MB_BLOCKED_FROM_RIGHT           0x04
#define MB_TALL_GRASS                   0x06  // triggers wild encounter
#define MB_LONG_GRASS                   0x07
#define MB_SHALLOW_WATER                0x0D
#define MB_DEEP_WATER                   0x32  // Surf required
#define MB_WATERFALL                    0x3B  // Waterfall required
#define MB_NO_RUNNING                   0x62
#define MB_CAVE                         0x4E  // dark cave tile
#define MB_ROCK_SMASH                   0x2D  // breakable rock
#define MB_STRENGTH_PUZZLE_BOULDER      0x6E
#define MB_CUT                          0x50  // cuttable tree
#define MB_IMPASSABLE_EAST              0x09
#define MB_IMPASSABLE_WEST              0x0A
#define MB_IMPASSABLE_NORTH             0x0B
#define MB_IMPASSABLE_SOUTH             0x0C

Metatile behavior is checked in src/field_player_avatar.c and src/metatile_behavior.c.

Event types

Events are defined per-map in the events.inc file and fall into four categories:

Object events (NPCs)

Object events are sprites placed on the map. Each has a movement type, script pointer, flag, and trainer sight range (if applicable).

object_event 1, EVENT_OBJ_GFX_MAN_1, 0, 7, 3, 3, MOVEMENT_TYPE_FACE_DOWN, 1, 1, 0, 0, PalletTown_EventScript_Man1, 0

Object event graphics and movement types are defined in include/constants/event_objects.h and src/event_object_movement.c.

Warp events

Warp events teleport the player to another map and position when stepped on.

warp_event 7, 8, MAP_PALLET_TOWN_PLAYERS_HOUSE_1F, 1

Warp processing is handled in src/overworld.c and src/field_control_avatar.c.

Coordinate events

Coordinate events trigger a script when the player steps on a specific tile. Used for invisible triggers, zone transitions, and forced camera pans.

coord_event 5, 12, 3, Route1_EventScript_ArrivalFromPalletTown

Background events

Background events are scriptable tiles the player can interact with by pressing A while facing them (signs, bookshelves, item balls, hidden items).

bg_event 5, 3, 0, BG_EVENT_PLAYER_FACING_ANY, PalletTown_EventScript_Sign1

Field move effects

HM and field move effects are implemented in dedicated source files:

Source file	Field move
src/fldeff_cut.c	Cut — removes cuttable trees (MB_CUT)
src/fldeff_dig.c	Dig / Escape Rope — warps player out of dungeon
src/fldeff_flash.c	Flash — reveals dark cave lighting
src/fldeff_rocksmash.c	Rock Smash — breaks MB_ROCK_SMASH boulders
src/fldeff_strength.c	Strength — enables pushing MB_STRENGTH_PUZZLE_BOULDER boulders
src/fldeff_sweetscent.c	Sweet Scent — triggers a wild encounter immediately
src/fldeff_teleport.c	Teleport — warps player to last Pokémon Center
src/fldeff_softboiled.c	Soft-Boiled / Milk Drink — field HP restore
src/fldeff_misc.c	Miscellaneous field effects
src/fldeff_escalator.c	Escalator movement effect

Each file contains the effect’s activation check, animation, and script callback.

Overworld engine

src/overworld.c is the main field game loop. It manages:

• Loading and transitioning between maps
• Player input routing (movement, menu, interaction)
• Field object (NPC) step-cycle updates
• Script context execution each frame
• Camera and background scrolling

1. Map load

   On a map transition, LoadMapFromCameraTransition or LoadMap sets up tileset data, object events, scripts, and BGM.

2. Field loop

   FieldCB_ContinueScriptHandleMusic runs every frame: it updates objects, checks coordinate events, and steps the script engine.

3. Interaction

   When the player presses A, TryInteractWithObjectEvent scans the tile in front of them for a background event or NPC and starts the associated script context.

Weather

Weather state is managed by two source files:

Source file	Role
src/field_weather.c	Weather type tracking, transition scheduling, palette fade
src/field_weather_effect.c	Per-weather-type particle effects (rain drops, snowflakes, sandstorm tiles, etc.)

Weather types are defined in include/constants/weather.h as WEATHER_* constants. The current weather is set via the setweather and doweather script commands.

Map editing tool

Use porymap (https://github.com/huderlem/porymap) for visual map editing. It reads the data/maps/ and data/layouts/ directories directly and writes back the same file format the build system expects.