RGBY Map Headers

[iimarckus]

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

RGBY Map Headers & Stuff That Goes With It
Version 1.1
-Feel free to distribute this document and/or edit it.
-Try and credit people you get info from and/or write how you updated.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Things that need adding:
------------------------
More information about tilesets, and info about what sprites get loaded for
which maps.

Updates:
--------
v1.1: By Hat, minor improvements.
v1.0: Original version typed up by Hat.

Main Credits (Structure Information):
-------------------------------------
[Xeon]
Wrote some stuff about Map Headers and Object Data.
Which this document expands upon, a bit.

[F-Zero] & [Tauwasser]
Wrote a document (in German) explaining how GSC connection data is stored.
RGBY connection data is stored almost the same way, it turns out, so
that helped a great deal. All that is really different is the values you
add the amount of blocks to.
...............................................................................

Notes:
R/B Pointers to Map Headers: 0x01AE
R/B Map Header Banks: 0xC23D
R/B Pointer to Tileset Headers: 0xC767

Maximum tileset size in VRAM: 6 rows of 16 tiles (9000-95FF)

...............................................................................

===============================================================================

Tileset Header Structure (*Incomplete*)

===============================================================================

12 bytes per header...

Format:
~~~~~~~
[1 BYTE: Bank No. of Blocks/Tiles]
[2 BYTES: Pointer to Blocks (-10 for some reason)]
[2 BYTES: Pointer to Tiles]
[7 BYTES: ???]

last 7 bytes ideas: collison data pointer? something to do with animations?

===============================================================================

Map Header Structure

===============================================================================

Explanation:
~~~~~~~~~~~~
This contains all the data (pointers count as data) to build the map.

Format:
~~~~~~~
#1: [Tileset Number]
#2: [(Y Size) Map Height]
#3: [(X Size) Map Width]
#4-5: [*2 Bytes*: Pointer to Map]
#6-7: [*2 Bytes*: Pointer to Maps Text Pointers]
#8-9: [*2 Bytes*: Pointer to Maps "Script"]
#10: [Connection Byte:
00 = No Connections
01 = East
02 = West
03 = West + East
04 = South
05 = South + East
06 = South + West
07 = South + West + East
08 = North
09 = North + East
0A = North + West
0B = North + West + East
0C = North + South
0D = North + South + East
0E = North + South + West
0F = North + South + West + East]
?: [*11 Bytes per Connection*, No connections? Straight to "Object Data"!]
Last: [*2 Bytes*: Pointer to Object Data]

===============================================================================
1) Tileset Numbers
===============================================================================

The tileset descriptions are copied from a document compiled by Cartmic,
called "Pokemon Red Documents", which may help you with other stuff too.

Unchanged R/B Locations/Tileset No./Tileset Descriptions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
C7BE; 00: "Outside"C7CA; 01: "Ash's House (#1)"
C7D6; 02: "Pokemon Center (#1)"
C7E2; 03: "Viridian Forest"
C7EE; 04: "Ash's House (#2)"
C7FA; 05: "Gym (#1)"
C806; 06: "Pokemon Center (#2)"
C812; 07: "Gym (#2)"
C81E; 08: "House"
C82A; 09: "Museum (#1)"
C836; 0A: "Museum (#2)"
C842; 0B: "Underground Path"
C84E; 0C: "Museum (#3)"
C85A; 0D: "S.S. Anne"
C866; 0E: "Vermilion Port"
C872; 0F: "Pokemon Cemetery"
C87E; 10: "Silph Co."
C88A; 11: "Cave"
C896; 12: "Celadon Mart"
C8A2; 13: "Game Freak HQ"
C8AE; 14: "Lab"
C8BA; 15: "Bike Shop/Cable Center"
C8C6; 16: "Cinnabar Mansion/Power Plant etc"
C8D2; 17: "Indigo Plateau"

NOTE: As you can see there's multiple copies of some tileset headers. They are
literally copies, you only need 1 copy, but you will need to make sure all maps
using that tileset are set to using that tileset number, then you can use the
free space for more tilesets.

===============================================================================
2 & 3) Map Height (Y) & Width (X)
===============================================================================

Exactly that, the amount of blocks high and wide the map data is.

===============================================================================
4 & 5) Map Data Pointer
===============================================================================

You can use the GoldMap engine for hacking map data quite easily.

The map you walk around on and stuff is stored as block indexes.
A single block consists of 4*4 tiles.

===============================================================================
6 & 7) Pointer to Maps Text Pointers
===============================================================================

2 byte pointers to text that is used on that map.

===============================================================================
8 & 9) Pointer to Maps "Script"
===============================================================================

ASM used on that map, chances are if there's something on a map you can't find
elsewhere you might easily be able to find it here, using a hex search
function. You can find things like XY positions of Poke Balls and 1-time
only Pokemon.

===============================================================================
10) Connection Byte
===============================================================================

Note:
~~~~~
If this value is 00h it is immediately followed by the Object Data
Pointer, no gap. Repeated list...

Connection Byte:
00 = No Connections
01 = East
02 = West
03 = West + East
04 = South
05 = South + East
06 = South + West
07 = South + West + East
08 = North
09 = North + East
0A = North + West
0B = North + West + East
0C = North + South
0D = North + South + East
0E = North + South + West
0F = North + South + West + East

===============================================================================
?) Connection Data (0-44 bytes, explained in more depth: further down)
===============================================================================

===============================================================================
Last) Object Data Pointer
===============================================================================

The last thing in the Map Header. It points to a bunch of certain stuff that
is stored in similar structures.

Object Data is discussed at the end of this document.
...............................................................................


===============================================================================

*** Hacking Connections ***
This will certainly require planning, with no background distractions.
Unless a editor gets built that can hack the connections for RGBY.

===============================================================================

Explanation:
~~~~~~~~~~~~
The "Connection Byte" determines how many connections are in this space,
including none at all.

Structure:
~~~~~~~~~~
#1: [Map Index of Connected Map]
#2-3: [Pointer to "Connection Strip"s Upperleft Block (Connected Map)]
#4-5: [Pointer to "Connection Strip"s Upperleft Block (Current Map)]
#6: ["Bigness"]
#7: [Map Width]
#8: [Y alignment]
#9: [X alignment]
#10-11: [Window]

PKMN Red Example -- Saffron City (Header: 0x509A4) Diagram:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Saffrons need-to-know stats:

Block Height (Y): 12
Block Width (X): 14
Connection Byte: 0F (North + South + West + East)
- - - -
+ = current maps border blocks

++++++++NNNNNNNNNN++++++++
++++++++NNNNNNNNNN++++++++
++++++++NNNNNNNNNN++++++++
+++####################+++
+++####################+++
+++####### My #########+++
+++####################+++
WWW####### Name's #####EEE
WWW####################EEE
WWW###### Saffron #####EEE
WWW####################EEE
WWW###### City! #######EEE
WWW####################EEE
WWW####################EEE
WWW####################EEE
WWW####################EEE
+++####################+++
+++####################+++
+++####################+++
+++####################+++
+++####################+++
++++++++SSSSSSSSSS++++++++
++++++++SSSSSSSSSS++++++++
++++++++SSSSSSSSSS++++++++

Connection to Route 5 (to the North)
*Y: 12
*X: 0A
*X_Movement_of_Connection Strip = 5
Map Index: 10
Connection Strip: 4668
Where Connected: C6F0 (C6EB + 5)
"Bigness": 0A
Width: 0A
Y alignment: 23 (12 * 2 - 1)
X alignment: F6 (5 * -2)
Window: C809 (C6E9 + (12 * (0A + 6)))

Connection to Route 6 (to the South)
*Y: 12
*X: 0A
*X_Movement_of_Connection Strip = 5
Map Index: 11
Connection Strip: 4079
Where Connected: C912 (C6EB + ((12 + 3) * (14 + 6)) + 5)
"Bigness": 0A
Width: 0A
Y alignment: 00
X alignment: F6 (5 * -2)
Window: C6F9 (C6EF + 0A)

Connection to Route 7 (to the West)
*Y: 09
*X: 0A
*Y_Movement_of_Connection Strip = 4
Map Index: 12
Connection Strip: 4058
Where Connected: C79E (C6E8 + (14 + 6) * (4 + 3))
"Bigness": 09
Width: 0A
Y alignment: F8 (4 * -2)
X alignment: 13 ((0A * 2) - 1)
Window: C702 (C6EE + (0A * 2))

Connection to Route 8 (to the East)
*Y: 09
*X: 1E
*Y_Movement_of_Connection Strip = 4
Map Index: 13
Connection Strip: 41C6
Where Connected: C7B5 (C6E5 + (14 + 6) * (4 + 4))
"Bigness": 09
Width: 1E
Y alignment: F8 (4 * -2)
X alignment: 00
Window: C70D (C6EF + 1E)

===============================================================================
#1 : Map Indexes
===============================================================================

Not included! Download UltraMap, the text file known as "RedEnglish.ini"
contains all the Map Indexes in decimal for R/B, which you'll obviously need
to convert to hex.

===============================================================================
#2-#3 : "Connection Strip" Location
===============================================================================

The "connection strip" pointer -- points to the area of the connected map that
is visible when standing before you even enter it. Points to the upperleft
block of the "connection strip".
* connection strip is always 3 blocks wide (E/W connection)
3 blocks high (N/S connection)

===============================================================================
#4-#5 : Current Map Position
===============================================================================

This points to the part of the current map (further up in RAM)
that the connection strips upperleft block is placed on the current map.

____________________
Connection |
Direction | Formula
___________|_______

North: C6EB + X_Movement_of_Connection Strip

South: C6EB + (Height of Map + 3) * (Width of Map + 6) +
X_Movement_of_Connection Strip

West: C6E8 + (Width of Map + 6) * (Y_Movement_of_"Connection Strip" + 3)

East: C6E5 + (Width of Map + 6) * (Y_Movement_of_"Connection Strip" + 4)

===============================================================================
#6 : Map "Bigness"
===============================================================================

North/South Connection = Connected Maps Width
East/West Connection = Connected Maps Height

===============================================================================
#7 : Map Width
===============================================================================

The width of the connected map.

===============================================================================
#8 : Y alignment
===============================================================================

Relative Y-position of player after entering connected map.

____________________
Connection |
Direction | Formula
___________|_______
North: (Height_of_connected_map * 2) - 1
South: 0
West/East: (Y_movement_of_connection_strip_in_blocks * -2)

===============================================================================
#9 : X alignment
===============================================================================

Relative X-Position of player after entering connected map.

____________________
Connection |
Direction | Formula
___________|_______
North/South: (X_movement_of_connection_strip_in_blocks * -2)
West: (Width_of_connected_map * 2) - 1
East: 0

===============================================================================
#10-#11 : Window
===============================================================================

Position of the upper left block after entering the Map.

____________________
Connection |
Direction | Formula
___________|_______
Above: C6E9h + Height_of_connected_map * (Width_of_connected_map + 6)
South/East: C6EFh + Width_of_connected_map
West: C6EEh + 2 * Width_of_connected_map
...............................................................................


===============================================================================

Object Data: General Structure

===============================================================================

Object Data
===========
[Maps Border Tile]
[Number of Warps][Warp Data]
[Number of Signs][Sign Data]
[Number of People/Trainers/Items]
[People Data]
[Trainer Data]
[Item Data]
[Warp-To Data]

Warps:
------
[Y position][X position][Warp-To Point][Warp-To Map]

Signposts:
----------
[Y position][X position][Text String Number]

Normal People:
--------------
[Picture Number][Y position + 4][X position + 4]
[Movement 1][Movement 2][Text String Number]

Trainers:
---------
[Picture Number][Y position + 4][X position + 4]
[Movement 1][Movement 2][Text String Number]
[Trainer Type][Pokemon Set]

Items:
---------------------
[Picture Number][Y position + 4][X position + 4]
[Movement 1][Movement 2][Text String Number]
[Item Number]

Warp-To Points
--------------
[*2 Bytes*: Event Displacement][Y position][X position]

Event Displacement Formula:
~~~~~~~~~~~~~~~~~~~~~~~~~~~
C6E3 + ((Map width + 8) * (rows above + 1)) + (X movement + 4)

#############################################################################

[Sawakita]

I'm really sorry to bump this thread but after trying to manage by myself I haven't solved a problem.. I don't understand fully what you say in this part:

Warp-To Points
--------------
[*2 Bytes*: Event Displacement][Y position][X position]

Event Displacement Formula:
~~~~~~~~~~~~~~~~~~~~~~~~~~~
C6E3 + ((Map width + 8) * (rows above + 1)) + (X movement + 4)

1) When you say "warp-to points" do you mean the place where you are warped exiting from a door?
2) Is map width meant to be calculated in blocks (2x2 tiles) or in tiles (example: pallet town's width is 0x0A in blocks, but 0x14 in tiles)?
3)What do you mean with "X movement"?
4)Looking in the hex, the event displacement bytes look switched, or am i looking the wrong address? Here they are (starting offset 0x182f1):

Hiro's house...........1B C7 05 05
Rival's house..........1F C7 05 0D
Lab......................4F C7 0B 0C

first two bytes are event displacement formula, while the two following are Y and X position, isn't it?
I have troubles when exiting from two houses, while the other house's warp works fine..

[Cartmic]

Here's a little update on that:

================

v1.1.2: Edit by Cartmic to include almost completed tileset header information
and Hat's further clarification on what the X/Y Movement of the Connection means.

================================================================
Tileset Header Structure

===============================================================================

12 bytes per header.

Format:
~~~~~~~

[1 BYTE: Bank No. of Blocks/Tiles]
[2 BYTES: Pointer to Blocks (-10 for some reason)]
[2 BYTES: Pointer to Tiles]
[7 BYTES:
00 00 00 00 00 00 00
|| || || || || || ||
|| || || || || || __ Amount of animated tiles.
|| || || || || _____ x,y location on tileset of 'Grass' tile
|| || || || ________ X,Y Location of 'talking over tiles': East/West
|| || || ___________ X,Y Location of 'talking over tiles': North/South 1
|| || ______________ X,Y Location of 'talking over tiles': North/south 2
|| _________________ Colision Indication - Pointer?
____________________ Colision Indication - Pointer?

===============================================================================

1) Tileset Numbers

===============================================================================

The tileset descriptions are copied from a document compiled by Cartmic,
called "Pokemon Red Documents", which may help you with other stuff too.

Unchanged R/B Locations/Tileset No./Tileset Descriptions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
C7BE; 00: "Outside"
C7CA; 01: "Ash's House (#1)"
C7D6; 02: "Pokemon Center (#1)"
C7E2; 03: "Viridian Forest"
C7EE; 04: "Ash's House (#2)"
C7FA; 05: "Gym (#1)"
C806; 06: "Pokemon Center (#2)"
C812; 07: "Gym (#2)"
C81E; 08: "House"
C82A; 09: "Museum (#1)"
C836; 0A: "Museum (#2)"
C842; 0B: "Underground Path"
C84E; 0C: "Museum (#3)"
C85A; 0D: "S.S. Anne"
C866; 0E: "Vermilion Port"
C872; 0F: "Pokemon Cemetery"
C87E; 10: "Silph Co."
C88A; 11: "Cave"
C896; 12: "Celadon Mart"
C8A2; 13: "Game Freak HQ"
C8AE; 14: "Lab"
C8BA; 15: "Bike Shop/Cable Center"
C8C6; 16: "Cinnabar Mansion/Power Plant etc"
C8D2; 17: "Indigo Plateau"

NOTE: As you can see there's multiple copies of some tileset headers. They are
literally copies, you only need 1 copy, but you will need to make sure all maps
using that tileset are set to using that tileset number, then you can use the
free space for more tilesets.

=====================
X/Y_Movement_Of_Connection
~~~~~~~~~~~~~~~~~~~~~~~~~~

A X movement is how many map blocks there are to the left of one of your north/south connections.
A Y movement is how many map blocks there are above your west/east connection.

[Sawakita]

I try to explain what is wrong (I use the lab in Pallet town as example)
[map width = 0x0A;
rows above lab door = 0x0B;
X movement = 0]

The formula is

0xC6E3 + ((Map width + 8) * (rows above + 1)) + (X movement + 4)

.
So i do:

0xC6E3 + ((0x0A + 8) * (0x0B + 1)) + ([here I put zero] + 4) = 0xC7BF

instead of "4F C7" that I think is bigendian for C74F. I really don't understand what's wrong..

[Harrison]

Ah, but that 4F C7 is C7 BF! It's a pointer, which you can learn about here

I think?

[Sawakita]

Jul 28, 2010 13:42:01 GMT -5 Harrison said:

Ah, but that 4F C7 is C7 BF! It's a pointer

I don't think so. what's the sense of a pointer, since the task of "event displacement" is to define how tiles and events are displaced when you re-enter the map from a warp (a door) and not from a border.

which you can learn about here

Do I look such a noob? I clearly know what a pointer is and how it works, thanks for concern...

[...going to light a candle to invoke IIMarkus...]


EDIT: sorry, I become ill-mannered sometimes..

[Harrison]

Don't worry about it, I was being an idiot when I posted that.

Anyways, I have my own question regarding bytes 6-7 of the MapHeader. "Pointers to Maps Text Pointers" What text, exactly? In RedMap, those two bytes are referred to as "ObjectScriptPointers".

In fact, RedMap mentions one byte that isn't mentioned here, one at the end of the MapHeaders. It's the Border Block.

[iimarckus]

Jul 29, 2010 21:03:16 GMT -5 Harrison said:

Don't worry about it, I was being an idiot when I posted that.

Anyways, I have my own question regarding bytes 6-7 of the MapHeader. "Pointers to Maps Text Pointers" What text, exactly? In RedMap, those two bytes are referred to as "ObjectScriptPointers".

Let’s look at an existing map, Erika’s gym. Header is at 488FE. Bytes 6–7 point to 489A6. Going there, we find a lot of pointers:
48A11
48A81
etc etc. Eleven pointers total. (The list isn’t terminated, so your event count had better match up. 0220 is where other data starts.)

So what’s at 48A11? Well, text. But it starts with 08, which signals the text engine to start an ASM routine:

ld a,[$D77C]
bit 1,a
jr z,.ErikaBattle\@
bit 0,a
jr nz,.ErikaLater\@
call z,$4963
call $30B6
jr .end\@
.ErikaLater\@
ld hl,ErikaLaterText
call PrintText
jr .end\@
.ErikaBattle\@
ld hl,ErikaIntroText
call PrintText
ld hl,$D72D
set 6,[hl]
set 7,[hl]
ld hl,ErikaDefeatText
ld de,ErikaDefeatText;

call $3354
ld a,[$FF8C]
ld [$CF13],a ;
call PrepareTrainer
call $32D7
ld a,4 ; Monsters will use Mega Drain
ld [$D05C],a
ld a,3
ld [$D5FF],a
ld [$DA39],a
.end\@ jp $24D7

Those labels in the code point to more text, by the way. It’s obvious by following the pointers that this block of code is Erika’s script, and (among other things) prints text and starts a battle with a trainer named Erika who uses Mega Drain. Suffice it to say that the rest of the Object Script Pointers determine the behavior of the rest of the trainers in the gym, and they always point to text data (which may of course call an ASM subroutine, as all of these do).

Note that this is not as simple as “one person, one pointer”: the last three pointers in ObjectScriptPointers are for the Rainbow Badge text, the “got Mega Drain” text, and the “bag is full, no Mega Drain” text. There’s more to it but it’s 11PM and I have work tomorrow… you can figure it out on your own. (But feel free to ask if anything is still unclear.)

Jul 28, 2010 13:36:54 GMT -5 Sawakita said:

I try to explain what is wrong (I use the lab in Pallet town as example)
[map width = 0x0A;
rows above lab door = 0x0B;
X movement = 0]

The formula is

0xC6E3 + ((Map width + 8) * (rows above + 1)) + (X movement + 4)

.
So i do:

0xC6E3 + ((0x0A + 8) * (0x0B + 1)) + ([here I put zero] + 4) = 0xC7BF

instead of "4F C7" that I think is bigendian for C74F. I really don't understand what's wrong..

I think you have that reversed… here 4FC7 is little‐endian for C74F, I believe. I think it points to the map data in WRAM0 (C000–CFFF).

[Harrison]

Jul 30, 2010 0:15:48 GMT -5 iimarckus said:

Let’s look at an existing map, Erika’s gym. Header is at 488FE. Bytes 6–7 point to 489A6. Going there, we find a lot of pointers:
48A11
48A81
etc etc. Eleven pointers total. (The list isn’t terminated, so your event count had better match up. 0220 is where other data starts.)

So what’s at 48A11? Well, text. But it starts with 08, which signals the text engine to start an ASM routine:

ld a,[$D77C]
bit 1,a
jr z,.ErikaBattle\@
bit 0,a
jr nz,.ErikaLater\@
call z,$4963
call $30B6
jr .end\@
.ErikaLater\@
ld hl,ErikaLaterText
call PrintText
jr .end\@
.ErikaBattle\@
ld hl,ErikaIntroText
call PrintText
ld hl,$D72D
set 6,[hl]
set 7,[hl]
ld hl,ErikaDefeatText
ld de,ErikaDefeatText;

call $3354
ld a,[$FF8C]
ld [$CF13],a ;
call PrepareTrainer
call $32D7
ld a,4 ; Monsters will use Mega Drain
ld [$D05C],a
ld a,3
ld [$D5FF],a
ld [$DA39],a
.end\@ jp $24D7

Those labels in the code point to more text, by the way. It’s obvious by following the pointers that this block of code is Erika’s script, and (among other things) prints text and starts a battle with a trainer named Erika who uses Mega Drain. Suffice it to say that the rest of the Object Script Pointers determine the behavior of the rest of the trainers in the gym, and they always point to text data (which may of course call an ASM subroutine, as all of these do).

Note that this is not as simple as “one person, one pointer”: the last three pointers in ObjectScriptPointers are for the Rainbow Badge text, the “got Mega Drain” text, and the “bag is full, no Mega Drain” text. There’s more to it but it’s 11PM and I have work tomorrow… you can figure it out on your own. (But feel free to ask if anything is still unclear.)

:o RedMap is going to be fun

[Sawakita]

I was trying to figure out the lab's script, and in the same time I gave a look to the object data in the mapheader.
I've seen that rival'object is defined as a trainer instead of a normal people as I expected (normale people is defined with 6 bytes, while trainer has 2 more bytes that define respectively "trainer type" and "pokemon set").
So I tried to change his "trainer type" (&hE1=rival1) to another one (i put &hCA=bugcatcher, just to say one), and i found out that supposedly nothing really changed.
Eventually I found out where the information of the battle_enemy is stored (it's hardcoded in a subroutine of the "Lab's script"), I edited it and this time it actually worked.

So I was wondering: what actually does that "trainer type" byte do?
Anyone knows something about that?

[Mateo]

My understanding is that on normal trainers, it does exactly what it sounds like. However, Gary is not a "normal" trainer, and his battle is called by a trigger instead of his event. There is really no point in him being a trainer event as far as I know. But like I say on most trainer events, editing those seems to work.

[Sawakita]

Aug 14, 2010 12:00:17 GMT -5 Mateo said:

There is really no point in him being a trainer event as far as I know.

In fact that's what i was trying to understand: why wasting 2 bytes with useless datas? (also considering that the whole rom is so chaotic because of the programmers' will of reducing space used!!).
Anyway you reassured me saying so. I think I'm going to not giving too much importance to those two bytes..

[~Red]

Wow! I tried modifying the connection data for Cinnabar Island so that the north connection points to Route 5. So far I managed to get it to go there, but once you step out of cinnabar you end up in a zone filled with Route 5's border block. Walking north a while will cause you to come out in Route 5. How do I pull the map down to touch Cinnabar?

[Mateo]

The garbage might be because you need to edit the connection data on route 5 as well to connect to Cinnabar

[~Red]

This is hard. No matter what I try it doesn't work. I also don't understand the documentation. It's either I change the connection data or add warps to Route 21...