Archipelago/worlds/pokemon_emerald/docs/region data.md

Region Data

Regions, connections, and associated locations are defined in data/regions. If you know what you're doing, it should be pretty clear how the data works by taking a quick look through the files. But the quick tl;dr is:

• Every map, even trivial ones, gets a region definition, and they cannot be coalesced (because of warp rando)
• Stick to the naming convention for regions and events (look at Route 103 and Petalburg City for guidance)
• Locations and warps can only be claimed by one region
• Events are declared here

A Map, which you will see referenced in parent_map attribute in the region JSON, is an id from the source code. Maps are sets of tiles, encounters, warps, events, and so on. Route 103, Littleroot Town, the Oldale Town Mart, the second floor of Devon Corp, and each level of Victory Road are all examples of Maps. You transition between Maps by stepping on a warp (warp pads, doorways, etc.) or walking over a border between Maps in the overworld. Some warps don't go to a different Map.

Regions usually describe physical areas which are subsets of a Map. Every Map must have one or more defined regions. A region should not contain area from more than one Map. We'll need to draw those lines now even when there is no logical boundary (like between two the first and second floors of your rival's house), for warp rando.

Most Maps have been split into multiple regions. In the example below, MAP_ROUTE103 was split into REGION_ROUTE_103/WEST, REGION_ROUTE_103/WATER, and REGION_ROUTE_103/EAST (this document may be out of date; the example is demonstrative). Keeping the name consistent with the Map name and adding a label suffix for the subarea makes it clearer where we are in the world and where within a Map we're describing.

Every region (except Menu) is configured here. All files in this directory are combined with each other at runtime, and are only split and ordered for organization. Regions defined in data/regions/unused are remnants from automatically generated regions and represent places that exist but aren't reachable or aren't currently relevant to the randomizer. Any locations or warps in there should be ignored. Data for a single region looks like this:

"REGION_ROUTE103/EAST": {
  "parent_map": "MAP_ROUTE103",
  "locations": [
    "ITEM_ROUTE_103_GUARD_SPEC",
    "ITEM_ROUTE_103_PP_UP"
  ],
  "events": [],
  "exits": [
    "REGION_ROUTE103/WATER",
    "REGION_ROUTE110/MAIN"
  ],
  "warps": [
    "MAP_ROUTE103:0/MAP_ALTERING_CAVE:0"
  ]
}

• [key]: The name of the object, in this case REGION_ROUTE103/EAST, should be the value of parent_map where the MAP prefix is replaced with REGION. Then there should be a following / and a label describing this specific region within the Map. This is not enforced or required by the code, but it makes things much more clear.
• parent_map: The name of the Map this region exists under. It can relate this region to information like encounter tables.
• locations: Locations contained within this region. This can be anything from an item on the ground to a badge to a gift from an NPC. Locations themselves are defined in data/extracted_data.json, and the names used here should come directly from it.
• events: Events that can be completed in this region. Defeating a gym leader or Aqua/Magma team leader, for example, can trigger story progression and unblock roads and buildings. Events are defined here and nowhere else, and access rules are set in rules.py.
• exits: Names of regions that can be directly accessed from this one. Most often regions within the same Map, neighboring maps in the overworld, or transitions from using HM08 Dive. Most connections between maps/regions come from warps. Any region in this list should be defined somewhere in data/regions/.
• warps: Warp events contained within this region. Warps are defined in data/extracted_data.json, and must exist there to be referenced here. More on warps in ../docs/warps.md.

Think of this data as defining which regions are "claiming" a given location, event, or warp. No more than one region may claim ownership of a location. Even if some "thing" may happen in two different regions and set the same flag, they should be defined as two different events and anything conditional on said "thing" happening can check whether either of the two events is accessible. (e.g. Interacting with the Poke Ball in your rival's room and going back downstairs will both trigger a conversation with them which enables you to rescue Professor Birch. It's the same "thing" on two different Maps.)

Conceptually, you shouldn't have to "add" any new regions. You should only have to "split" existing regions. When you split a region, make sure to correctly reassign locations, events, exits, and warps according to which new region they now exist in. Make sure to define new exits to link the new regions to each other if applicable. And especially remember to rename incoming exits defined in other regions which are still pointing to the pre-split region. sanity_check.py should catch you if there are other regions that point to a region that no longer exists, but if one of your newly-split regions still has the same name as the original, it won't be detected and you may find that things aren't connected correctly.