> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pret/pokeemerald/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)
```

<Note>
  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/`.
</Note>

## 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.

```c theme={null}
// 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:

<AccordionGroup>
  <Accordion title="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).

    ```asm theme={null}
    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`.
  </Accordion>

  <Accordion title="Warp events">
    Warp events teleport the player to another map and position when stepped on.

    ```asm theme={null}
    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`.
  </Accordion>

  <Accordion title="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.

    ```asm theme={null}
    coord_event 5, 12, 3, Route1_EventScript_ArrivalFromPalletTown
    ```
  </Accordion>

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

    ```asm theme={null}
    bg_event 5, 3, 0, BG_EVENT_PLAYER_FACING_ANY, PalletTown_EventScript_Sign1
    ```
  </Accordion>
</AccordionGroup>

## 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

<Steps>
  <Step title="Map load">
    On a map transition, `LoadMapFromCameraTransition` or `LoadMap` sets up tileset data, object events, scripts, and BGM.
  </Step>

  <Step title="Field loop">
    `FieldCB_ContinueScriptHandleMusic` runs every frame: it updates objects, checks coordinate events, and steps the script engine.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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

<Tip>
  Use **porymap** ([https://github.com/huderlem/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.
</Tip>