0 Overworld Scripting ‐ Map Header Scripts

ShinyTillDawn edited this page 2025-11-26 14:40:46 -05:00

Table of Contents

• Making Your Own Map Scripts

Click to return to the main scripting page

At the bottom of the map header panel, you can see a special set of scripts called "Map Header Scripts."

These are special scripts that are associated with an entire map, rather than being assigned to a specific event. This lets you run code any time you enter a map, unpause the game in a map, or even just every time-step that your character spends in that map.

Below is an explanation of all of the types of header scripts, as well as examples of where they're used in the vanilla games.

Script Type	Description	Examples
Load	Before Layout is Drawn. Almost exclusively used to set metatiles on the map before it's first drawn.	Seafoam Island (1-87)
Per-Frame	Table of scripts that run every frame. Only the first script whose condition is satisfied is run. Used to trigger events.	Cinnabar Island (3-8) Bill Event
Transition	Run when switching maps. Used to set map-specific flags/vars, update object positions/movement types, set weather, etc	Power Plant (1-95) Reset Zapdos encounter (See Legendary Pokémon Encounters)
Warp into Map	Table of scripts to run after objects are loaded. Only the first script whose condition is satisfied is run. Used to update facing / visibility or to add objects to the scene.	Route 16 (3-34) (Bicycle Road) Force player onto bike
Resume	Run after loading the map, or exiting the bag, or finishing a battle, etc. Used to hide defeated static pokemon, or maintain some map state.	Route 12 (3-30) Hide the Snorlax
Dive Warp	Run after the player dives or emerges	Only used to determine whether the player should emerge in the sealed chamber
Return to Field	Run after exiting bag or finishing battle, but not when entering a map. Used rarely, when something must only happen on reload.	Trainer Town (2-10) to show sprites

Making Your Own Map Scripts

King Cradi has a more in-depth video guide on map scripting for ROM hackers to watch: It also covers some examples and use cases.