Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pmret/papermario/llms.txt

Use this file to discover all available pages before exploring further.

The world system is the outermost layer of Paper Mario’s game logic. It divides the overworld into areas — each a collection of related maps (rooms) — and manages loading, unloading, and transitioning between them. All world-facing source code lives under src/world/, while the structs that describe areas and maps are declared in include/map.h.

​
Area and map naming convention

Every overworld location maps to a three-letter area code. The area directories under src/world/ follow the pattern area_<code>/, and individual map IDs use the format <area>_<room> (e.g. kmr_02).
DirectoryArea codeLocation
area_kmr/kmrGoomba Road and surroundings
area_mac/macToad Town and Shooting Star Summit
area_nok/nokKoopa Bros. Fortress
area_trd/trdDry Dry Ruins
area_iwa/iwaMt. Rugged
area_sbk/sbkDry Dry Desert
area_isk/iskDry Dry Ruins interior
area_mim/mimForever Forest
area_arn/arnBoo’s Mansion
area_dgb/dgbGusty Gulch
area_omo/omoShy Guy’s Toy Box
area_kgr/kgrKoopa Village
area_jan/janJade Jungle
area_kzn/kznMt. Lavalava
area_flo/floFlower Fields
area_tik/tikTubba Blubba’s Castle
area_sam/samShiver Region
area_pra/praCrystal Palace
area_kpa/kpaBowser’s Castle
area_kkj/kkjPeach’s Castle
area_dro/droDry Dry Outpost
area_hos/hosShooting Star Summit
area_gv/gvGoomba Village
area_obk/obkBoo’s Mansion library
area_osr/osrOscar’s Ship
area_mgm/mgmMini-game island
area_end/endEnding sequence
area_tst/tstTest maps
The global area table is declared as extern AreaConfig gAreas[29] in include/map.h and is zero-terminated.

​
Core structs

include/map.h defines the two structs that describe the static layout of the overworld.

​
AreaConfig

typedef struct AreaConfig {
    /* 0x00 */ s32 mapCount;      // number of maps in this area
    /* 0x04 */ MapConfig* maps;   // pointer to map array
    /* 0x08 */ char* id;          // "area_xxx"
    /* 0x0C */ char* name;        // JP debug name
} AreaConfig; // size = 0x10

​
MapConfig

typedef struct MapConfig {
    /* 0x00 */ char* id;          // "xxx_yyy" — max 7 chars excluding null
    /* 0x04 */ MapSettings* settings;
    /* 0x08 */ void* dmaStart;    // overlay ROM start
    /* 0x0C */ void* dmaEnd;      // overlay ROM end
    /* 0x10 */ void* dmaDest;     // overlay RAM destination
    /* 0x14 */ char* bgName;      // background image name
    /* 0x18 */ MapInit init;      // return true to skip normal asset loading
    /* 0x1E */ s8 songVariation;  // 0 or 1, for BGM selection
    /* 0x1F */ s8 sfxReverb;      // reverb level for SFX
} MapConfig; // size = 0x20

​
MapSettings

MapSettings is populated at runtime when a map loads. Its most important authored fields are: 
typedef struct MapSettings {
    /* 0x10 */ EvtScript* main;         // entry-point EVT script for the map
    /* 0x14 */ EntryList* entryList;    // array of Vec4f spawn points
    /* 0x18 */ s32 entryCount;          // number of entries
    /* 0x38 */ BackgroundHeader* background;
    /* 0x3C */ union { s32 msgID; s32 (*get)(void); } tattle;
} MapSettings; // size = 0x40
The main EVT script is the first thing that runs when a map loads. It typically spawns NPCs via MakeNpcs, sets up collision triggers, starts ambient audio, and launches any map-specific scripts.

​
Map overlay structure

Each map is loaded as a DMA overlay. When you enter a room, the engine copies the overlay from ROM into dmaDest in RAM. The overlay contains:
  • The compiled map geometry and collision (shape/hit files)
  • The MapSettings struct with the main EVT script
  • All per-map NPC data, item data, and entity spawn calls
  • Area-specific texture and model assets
Entering a new area also loads area-specific entity graphics. The engine tracks this with isAreaSpecificEntityDataLoaded in src/entity.c.

​
World state machine

The overworld game loop runs in src/world/world.c. It manages a mode variable that selects between states such as WORLD_STATE_NORMAL (player in control), WORLD_STATE_CHANGE_MAP (transition in progress), and battle entry. The world state machine calls update_npcs, update_entities, and the per-map scripts every frame.

​
Map transitions

When Mario reaches an exit trigger, the engine picks a transition type based on the exit’s configuration. The transition EVT scripts are declared in include/script_api/map.h: 
extern EvtScript EnterWalk;          // walk in from off-screen
extern EvtScript EnterWalkShort;     // short walk-in
extern EvtScript EnterSavePoint;     // enter from save point
extern EvtScript ExitWalk;           // walk out of screen
extern EvtScript ExitSingleDoor;     // exit through single door
extern EvtScript EnterSingleDoor;    // enter through single door
extern EvtScript ExitDoubleDoor;     // exit through double doors
extern EvtScript EnterDoubleDoor;    // enter through double doors
extern EvtScript EnterPostPipe;      // emerge from a warp pipe
Entry points for each map are stored in EntryList — a zero-terminated array of Vec4f values encoding the position and facing direction where Mario spawns for each entry index.

​
EVT map scripting API

The following callables from include/script_api/map.h are available to map EVT scripts:
CallablePurpose
MakeNpcsSpawn an NpcGroup into the world
BasicAI_MainRun the standard enemy patrol and chase AI
MakeShopInitialise a shop with item list and prices
MakeShopOwnerSpawn the shop owner NPC
CreateMapRoomRegister a room sub-area for sound zone control
CheckActionStateQuery the player’s current action state
CreatePushBlockGridInitialise a grid of push blocks
SetPushBlockSet the state of a push block cell
GetPushBlockRead the state of a push block cell
TeleportPartnerToPlayerMove the partner NPC to Mario’s position
Use MakeNpcs with an NpcGroup macro rather than creating NPCs individually. The NPC_GROUP macro packs the NPC array, battle reference, and stage reference into one struct so the engine can associate an NPC encounter with the correct battle and stage data.

​
Partner in the overworld

Active partner NPCs are managed separately from map NPCs. Their overworld logic lives in src/world/partner/ and src/world/partners.c. The active partner follows Mario using NpcFollowData attached to its Npc::blur field.

Battle system

See how battles are loaded from area encounter data and how the state machine runs.

NPCs and entities

Learn about the NPC and entity structs that populate every map.

Build docs developers (and LLMs) love

Get started for freeTalk to us