Difference between revisions of "Metroid:Item data format"

From Data Crystal
Jump to: navigation, search
(Item Types (<tt>T</tt>): - added to list of item types)
(Rewrote article to better represent a more thorough understanding of item data)
Line 8: Line 8:
 
|totallength=Varies. See [[Metroid:ROM map|ROM Map]]
 
|totallength=Varies. See [[Metroid:ROM map|ROM Map]]
 
}}
 
}}
The following describes the format of the data for items in the Metroid ROM.
+
The following describes the format of the data for items in the Metroid ROM. For each level there is a '''set''' of entries. Each entry defines all of the items on a single horizontal row of the map. Each entry can define any number of items.
  
There are five sets of entries: one for each level. Each entry can contain multiple items. All items in a single entry will appear in a single horizontal row of the map.
+
In this article, the term "item" is used as a generic term to refer to a variety of in-game objects such as elevators, enemies, and power-ups. This article contains a mixture of formal and informal information to compromise between clarity, brevity, and ease of understanding.
== Entry Format ==
 
The following is the binary format for a single item data entry. Each pair of letters represents a byte, where the first letter represents the high nibble and the second letter represents the low nibble. Each entry can contain multiple items. The brackets indicate data that may or may not be present, depending on the types of objects represented and the number of items defined in the entry.
 
YY BB AA XX CC FT [II [yx]] 00 [ XX CC FT [II [yx]] 00 [XX CC FT [II [yx]] 00 [...]]]
 
:* <tt>XX</tt>: Map X coordinate for single item.
 
:* <tt>YY</tt>: Map Y coordinate for all items in this entry.
 
:* <tt>AA BB</tt>: Memory address (RAM) of next item data entry.
 
:* <tt>CC</tt>: Size of a "screen entry" (see ''Terminator'' below), or bytes between '''CC''' value for this item and that of the next item. A value of <code>0xFF</code> indicates that this is the last item in the entry.
 
:* <tt>F</tt>: "Sprite Slot" value for enemy data. Disregarded for item data.
 
:* <tt>T</tt>: Item type (see below).
 
:* <tt>II</tt>: Power-up type (see below) or elevator destination. This data is not present for palette switches.
 
:* <tt>x</tt>: Screen x coordinate. Not present for palette switches or elevators.
 
:* <tt>y</tt>: Screen y coordinate. Not present for palette switches or elevators.
 
:* <tt>00</tt>: Terminator. Always has a value of zero. Indicates end of data for an item.
 
  
The first three bytes (<tt>YY BB AA</TT>) are defined once per row of items. The remaining data (<tt>XX CC FT II yx 00</tt>) is repeated for each item. The<tt> II </tt>and<tt> yx </tt>values may not necessarily be present, depending on what type of item is being defined. There are some interesting things to note about item data, though they may not be necessary or relevant to ROM hacking.
+
== About Item Data ==
 +
Item data is defined for each level. Item data is in the form of a linked list of "item data entries," each of which define all of the items on a single horizontal map row for a single level. Each item data entry contains a number of screen entries, each of which contains zero or more (usually one) item entries that define all of the items in that screen.
  
The<tt> '''FT II yx''' </tt>data is the same exact format as used in Room data (see [[Metroid:Room_data_format|Room Format]]) for enemies (and is interpreted by the same exact program code). It is entirely possible to add items to a room in that room's enemy data, and even add enemies into the level's item data. Apparently, however, the programmers saw fit to make item data independent from room data, which allows the same screen to appear with different items or without items at all.
+
When a level is loaded into RAM, the location of the item data varies, but the offset of the item table can always be found at the RAM address 0x9598. To calculate the ROM address, see [[Metroid:Pointer_format|Pointer Format]].
  
It would also probably be possible to place multiple items in the same room (see ''Terminator'' below).
+
== Item Data Entries ==
====Map Coordinates (<tt>YY, XX</tt>)====
 
The y-coordinate is specified only once and applies to all items in the entry, hence all items in an entry must appear in the same row of the map. The x-coordinate is specified for each item.
 
====Memory Address (<tt>AA BB</tt>)====
 
This value specifies the memory address for the next item data entry. The memory address specified is a RAM address, which is offset from the ROM address. See [[Metroid:Pointer_format|Pointer Format]]. A value of <code>0xFFFF</code> indicates that this is the last entry for the level.
 
====Special Items====
 
Special items, such as elevators and palette switches, have less data. Elevators are missing the last byte of data (screen coordinates). Palette swaps are missing the last two bytes (type and screen coordinates). There may be other special object types.
 
====Item Types (<tt>T</tt>)====
 
This specifies what type of object the data represents. The following are known possibilities. Other values are unknown or undefined. Hexadecimal values are used.
 
:*0: Nothing
 
:*1: Enemy
 
:*2: Power-up
 
:*3: Mella (fly-like creatures)
 
:*4: Elevator
 
:*6: Tourain Access Bridge
 
:*7: Respawning Enemy
 
:*8: Rinkas (cheerio-like enemies from Tourain)
 
:*A: Palette Switch
 
  
====Power-up Type (II)====
+
Each item entry can define multiple items in multiple screens. The linked list of item data entries must be logically ordered by their vertical map coordinate (though they aren't required to appear in order in memory).
This specifies what item the data represents. Values marked "Nothing" don't seem to manifest in the game. Values in parentheses aren't used in the game. Hexadecimal values are used.
+
 
:*0: Maru Mari Bombs
+
The binary format of an "item data entry" (not to be confused with a simple "item entry") is defined below. Italicized words refer to data where the format is defined elsewhere. Each pair of letters represents a byte, where the first letter represents the high nibble and the second letter represents the low nibble.
 +
 
 +
The following is the formal definition of an item data entry.
 +
 
 +
''itemDataEntry'' := YY ''pointer'' ''screenEntries''
 +
:* YY: Map Y coordinate for all items in the item data entry.
 +
:* ''pointer'': This is a pointer to the RAM address of the next item data entry. To convert to a ROM pointer, see [[Metroid:Pointer_format]]. The pointer is a two byte pointer, ''low byte first''. A hexadecimal value of FFFF denotes the end of a level's item data. The formal definition for the pointer is:
 +
::* <tt>pointer := BB AA</tt>
 +
:* ''screenEntries'': zero or more entries that define item data for screens. See Screen Entries below for the format of this information.
 +
 
 +
== Screen Entries ==
 +
 
 +
Item data entries tend to contain multiple screen entries, although they do sometimes contain only one and it would be valid for them to contain zero. A screen entry can define multiple items in the same map screen, but they typically contain one. Screen entries must be ordered by horizontal map position.
 +
 
 +
The formal definition of a screen entry is as follows:
 +
''screenEntry'' := XX SS ''itemEntries'' 00
 +
:*XX: The map x-coordinate of the screen.
 +
:*SS: The size, in bytes, of this screen entry, or the value of FF (hexadecimal) to indicate that this is the last screen entry in the containing item data entry.
 +
:*''itemEntries'': zero or more item entries defining the items in this room.
 +
:*00: Literal value (zero). Terminates this screen data.
 +
 
 +
== Item Entries ==
 +
An item entry defines a single item. The format and size of an item entry depends on the type of item being defined (i.e. elevator, power-up, enemy, etc.). The type of item is defined by the lower nibble of the first byte of the item entry. This value corresponds to the following types (hexadecimal is used). Values not listed are '''undefined''' (not to be confused with unknown).
 +
 
 +
:*0 - This value is reserved as a terminator for a screen entry.
 +
:*1 - Enemy
 +
:*2 - Item
 +
:*3 - Mella (small fly enemies)
 +
:*4 - Elevator
 +
:*5 - Unknown
 +
:*6 - Unknown (probably Tourain access bridge)
 +
:*7 - Unknown
 +
:*8 - Rinkas (Cheerio-like enemies from Tourain)
 +
:*9 - Unknown
 +
:*A - Palette switch
 +
 
 +
The mella (3), palette switch (A), and rinkas (8) are single-byte items, requiring only the byte that specifies the item type and no other data.
 +
 
 +
==== Elevator Entry ====
 +
 
 +
An elevator item entry is two bytes: the item type and a byte indicating which elevator is being defined. The formal definition is:
 +
 
 +
''elevatorEntry'' := TT EE
 +
:*TT: Item type (4), specifies an elevator
 +
:*EE: Elevator type.
 +
 
 +
The elevator type can have the following values (hexadecimal):
 +
 
 +
:*1: to Norfair
 +
:*2: to Kraid
 +
:*3: to Tourain
 +
:*4: to Ridley
 +
:*80: Norfair exit (to Brinstar)
 +
:*81: Kraid exit (to Brinstar)
 +
:*82: Tourain exit (to Brinstar)
 +
:*83: Ridley exit (to Norfair)
 +
:*8F: Game end
 +
 
 +
==== Enemy Entry ====
 +
 
 +
An enemy entry is three bytes. The format is as follows:
 +
 
 +
''enemyEntry'' := SI DT YX
 +
:*S: "Sprite Slot" (en enemy will not be loaded if there is already another enemy loaded into the same sprite slot)
 +
:*I: Item type (1), specifies an enemy
 +
:*D: Difficulty. Has a value of 8 (adding 0x80 to the total value of the byte) if the enemy is of a harder difficulty than normal, otherwise 0.
 +
:*T: Enemy type. The types available vary between levels.
 +
:*Y: Screen y-coordinate of the enemy.
 +
:*X: Screen x-coordinate of the enemy.
 +
 
 +
Note that enemy data is generally incorporated into Metroid's screen data rather than item data. Adding enemies via item data is only used in unusual circumstances.
 +
 
 +
==== Power-Up Entry ====
 +
 
 +
A power-up entry has three bytes. The format is as follows:
 +
 
 +
''powerupEntry'' := II TT YX
 +
:*II: Item type (2), specifies a power-up.
 +
:*TT: Power-up type. See below:
 +
:*Y: Screen y-coordinate.
 +
:*X: Screen x-coordinate.
 +
 
 +
The following are defined power-up types (using hexadecimal):
 +
:*0: Bombs
 
:*1: High Jump Boots
 
:*1: High Jump Boots
 
:*2: Long Beam
 
:*2: Long Beam
Line 60: Line 114:
 
:*8: Energy Tank
 
:*8: Energy Tank
 
:*9: Missile
 
:*9: Missile
:*A: (Dot Missile)
+
:*A: "Dot missile": Appears as a dot. Gives the player five missiles, but this item won't be saved in the password.
:*B: (Arrow Missile)
+
:*B: "Arrow Missile": Appears as an arrow. Behaves just like the "dot missile."
:*C: (Nothing)
+
 
:*D: (Nothing)
+
== Passwords ==
:*E: (Nothing)
+
 
:*F: (nothing)
+
The way that inventory is saved to the password is unusual and un-intuitive, and employs highly redundant data. See [[Metroid:Password_data]].
====Terminator (<tt>00</tt>)====
+
 
This byte has a value of zero and must be present for the Metroid game program to run properly. It is probably possible to add data for a second item (or more) that will appear in the same screen by providing more <tt>FT II yx</tt> entries preceding the <tt>00</tt> terminator. In light of this understanding, it might be more appropriate to think of the data<tt> XX CC FT II yx</tt>, where the last three bytes can be repeated, as a screen entry rather than a simple item entry.
+
== Examples ==
==Passwords==
+
 
[[Metroid:Password_Data|Password data]] stored in the ROM specifies the significance of each bit of a decoded Metroid password. Each entry in this data specifies a map location and item type found at that location. When an item is moved, or its type is changed, there will be no valid reference to the newly modified data unless the password data is changed to reflect the changes in item data. In other words, generally, when an item is edited it will no longer permanently disappear after it is gotten. While this isn't generally an issue with most power-ups, it becomes a serious problem with missile expansions and energy tanks. It is a must for password data to be changed to reflect moved or modified energy tanks and missiles.
+
==== Long Beam/Bombs ====
==Examples==
+
The following data defines the long beam and bombs found in Brinstar.
====Long Beam/Bombs====
+
 
The following defines the long beam and bombs from Brinstar.
+
  | 05 02 A4  07 06 02 02 37     00   19 FF 02 00 37     00
YY BB AA  XX CC FT II yx 00  XX CC FT II yx 00
+
|
  05 02 A4  07 06 02 02 37 00   19 FF 02 00 37 00
+
| --''itemDataEntry''------------------------------------------
:*'''05''': Map Y position is 5
+
|            --''screenEntry1''-------    --''screenEntry2''-------
:*'''02 A4''': RAM address of next entry is <tt>A402</tt>.
+
|                  -''itemEntry1''-            -''itemEntry2''-
:*'''07''': Map X position is 7
+
|
:*'''06''': Six bytes until next <tt>CC</tt> value.
+
|
:*'''02''': Object type 2: Power-up.
+
| ''itemDataEntry''
:*'''02''': Power-up type 2: Long beam.
+
|    '''05''': Map Y position is 5
:*'''37''': Screen position is three down and seven over.
+
|    '''02 A4''': RAM address of next entry is A402.
:*'''00''': End of this item's data.
+
|    ''screenEntry1''
:*'''19''': Map X position for second item is 19 (hex).
+
|        '''07''': Map X position is 7
:*'''FF''': This is the last item in the entry.
+
|        '''06''': Six bytes in screen entry.
:*'''02''': Object type 2: Item.
+
|        ''itemEntry1''
:*'''00''': Item type 2: Bombs.
+
|            '''02''': Item type 2: Power-up.
:*'''37''': Screen position is three down and seven over.
+
|            '''02''': Power-up type 2: Long beam.
:*'''00''': End of this item's data.
+
|            '''37''': Screen position is three down and seven over.
====Elevator====
+
|        '''00''': End of this screen's data.
The following data defines the elevator to Kraid's hideout from Brinstar.
+
|    ''screenEntry2''
  YY BB AA  XX CC FT II 00
+
|        '''19''': Map X position for second item is 19 (hex).
12 FF FF  07 FF 04 02 00
+
|        '''FF''': This is the last item in the entry.
:*'''12''': Map Y position is 12 (hex).
+
|        ''itemEntry2''
:*'''FFFF''': This is the last entry for Brinstar item data.
+
|            '''02''': Item type 2: Item.
:*'''07''': Map X position is 7.
+
|            '''00''': Power-up type 0: Bombs.
:*'''FF''': This is the last item in this entry.
+
|            '''37''': Screen position is three down and seven over.
:*'''04''': Object type 4: Elevator.
+
|        '''00''': End of this screen's data.  
:*'''02''': Destination is level 2: Kraid's hideout.
+
 
:*'''00''': The end.
+
==== Elevator ====
 +
The following defines the elevator from Brinstar to Kraid.
 +
  | 12 FF FF  07 FF   04 02       00
 +
|
 +
| -''itemDataEntry''-------------------
 +
|            -''screenEntry''----------
 +
|                    -''itemEntry''-
 +
|
 +
| ''itemDataEntry''
 +
|    '''12''': Map Y position is 12 (hex).
 +
|    '''FF FF''': This is the last entry for Brinstar item data.
 +
|    ''screenEntry''
 +
|        '''07''': Map X position is 7.
 +
|        '''FF''': This is the last screen in this item data entry.
 +
|        ''itemEntry''
 +
|            '''04''': Object type 4: Elevator.
 +
|            '''02''': Destination is level 2: Kraid's hideout.
 +
|        '''00''': The end.
  
  
 
=See Also=
 
=See Also=
  
[[Category:Metroid|Room data format]]
+
*[[Metroid:Password_data|Password Data]]
 +
*[[Metroid:ROM_map|Metroid Rom Map]]
 +
*[[Metroid | Metroid]]

Revision as of 21:39, 19 September 2007

Item data format
Game Metroid
Start Address Varies by bank. See ROM Map
End Address Varies by bank. See ROM Map
# of Entries Varies by bank. See ROM Map
Entry Length Varies.
Total Length Varies. See ROM Map
Back to the ROM map

The following describes the format of the data for items in the Metroid ROM. For each level there is a set of entries. Each entry defines all of the items on a single horizontal row of the map. Each entry can define any number of items.

In this article, the term "item" is used as a generic term to refer to a variety of in-game objects such as elevators, enemies, and power-ups. This article contains a mixture of formal and informal information to compromise between clarity, brevity, and ease of understanding.

About Item Data

Item data is defined for each level. Item data is in the form of a linked list of "item data entries," each of which define all of the items on a single horizontal map row for a single level. Each item data entry contains a number of screen entries, each of which contains zero or more (usually one) item entries that define all of the items in that screen.

When a level is loaded into RAM, the location of the item data varies, but the offset of the item table can always be found at the RAM address 0x9598. To calculate the ROM address, see Pointer Format.

Item Data Entries

Each item entry can define multiple items in multiple screens. The linked list of item data entries must be logically ordered by their vertical map coordinate (though they aren't required to appear in order in memory).

The binary format of an "item data entry" (not to be confused with a simple "item entry") is defined below. Italicized words refer to data where the format is defined elsewhere. Each pair of letters represents a byte, where the first letter represents the high nibble and the second letter represents the low nibble.

The following is the formal definition of an item data entry.

itemDataEntry := YY pointer screenEntries
  • YY: Map Y coordinate for all items in the item data entry.
  • pointer: This is a pointer to the RAM address of the next item data entry. To convert to a ROM pointer, see Metroid:Pointer_format. The pointer is a two byte pointer, low byte first. A hexadecimal value of FFFF denotes the end of a level's item data. The formal definition for the pointer is:
  • pointer := BB AA
  • screenEntries: zero or more entries that define item data for screens. See Screen Entries below for the format of this information.

Screen Entries

Item data entries tend to contain multiple screen entries, although they do sometimes contain only one and it would be valid for them to contain zero. A screen entry can define multiple items in the same map screen, but they typically contain one. Screen entries must be ordered by horizontal map position.

The formal definition of a screen entry is as follows:

screenEntry := XX SS itemEntries 00
  • XX: The map x-coordinate of the screen.
  • SS: The size, in bytes, of this screen entry, or the value of FF (hexadecimal) to indicate that this is the last screen entry in the containing item data entry.
  • itemEntries: zero or more item entries defining the items in this room.
  • 00: Literal value (zero). Terminates this screen data.

Item Entries

An item entry defines a single item. The format and size of an item entry depends on the type of item being defined (i.e. elevator, power-up, enemy, etc.). The type of item is defined by the lower nibble of the first byte of the item entry. This value corresponds to the following types (hexadecimal is used). Values not listed are undefined (not to be confused with unknown).

  • 0 - This value is reserved as a terminator for a screen entry.
  • 1 - Enemy
  • 2 - Item
  • 3 - Mella (small fly enemies)
  • 4 - Elevator
  • 5 - Unknown
  • 6 - Unknown (probably Tourain access bridge)
  • 7 - Unknown
  • 8 - Rinkas (Cheerio-like enemies from Tourain)
  • 9 - Unknown
  • A - Palette switch

The mella (3), palette switch (A), and rinkas (8) are single-byte items, requiring only the byte that specifies the item type and no other data.

Elevator Entry

An elevator item entry is two bytes: the item type and a byte indicating which elevator is being defined. The formal definition is:

elevatorEntry := TT EE
  • TT: Item type (4), specifies an elevator
  • EE: Elevator type.

The elevator type can have the following values (hexadecimal):

  • 1: to Norfair
  • 2: to Kraid
  • 3: to Tourain
  • 4: to Ridley
  • 80: Norfair exit (to Brinstar)
  • 81: Kraid exit (to Brinstar)
  • 82: Tourain exit (to Brinstar)
  • 83: Ridley exit (to Norfair)
  • 8F: Game end

Enemy Entry

An enemy entry is three bytes. The format is as follows:

enemyEntry := SI DT YX
  • S: "Sprite Slot" (en enemy will not be loaded if there is already another enemy loaded into the same sprite slot)
  • I: Item type (1), specifies an enemy
  • D: Difficulty. Has a value of 8 (adding 0x80 to the total value of the byte) if the enemy is of a harder difficulty than normal, otherwise 0.
  • T: Enemy type. The types available vary between levels.
  • Y: Screen y-coordinate of the enemy.
  • X: Screen x-coordinate of the enemy.

Note that enemy data is generally incorporated into Metroid's screen data rather than item data. Adding enemies via item data is only used in unusual circumstances.

Power-Up Entry

A power-up entry has three bytes. The format is as follows:

powerupEntry := II TT YX
  • II: Item type (2), specifies a power-up.
  • TT: Power-up type. See below:
  • Y: Screen y-coordinate.
  • X: Screen x-coordinate.

The following are defined power-up types (using hexadecimal):

  • 0: Bombs
  • 1: High Jump Boots
  • 2: Long Beam
  • 3: Screw Attack
  • 4: Maru Mari
  • 5: Varia
  • 6: Wave Beam
  • 7: Ice Beam
  • 8: Energy Tank
  • 9: Missile
  • A: "Dot missile": Appears as a dot. Gives the player five missiles, but this item won't be saved in the password.
  • B: "Arrow Missile": Appears as an arrow. Behaves just like the "dot missile."

Passwords

The way that inventory is saved to the password is unusual and un-intuitive, and employs highly redundant data. See Metroid:Password_data.

Examples

Long Beam/Bombs

The following data defines the long beam and bombs found in Brinstar.

| 05 02 A4   07 06 02 02 37     00    19 FF 02 00 37     00
| 
| --itemDataEntry------------------------------------------
|            --screenEntry1-------    --screenEntry2-------
|                  -itemEntry1-             -itemEntry2-
| 
| 
| itemDataEntry
|     05: Map Y position is 5
|     02 A4: RAM address of next entry is A402.
|     screenEntry1
|         07: Map X position is 7
|         06: Six bytes in screen entry.
|         itemEntry1
|             02: Item type 2: Power-up.
|             02: Power-up type 2: Long beam.
|             37: Screen position is three down and seven over.
|         00: End of this screen's data.
|     screenEntry2
|         19: Map X position for second item is 19 (hex).
|         FF: This is the last item in the entry.
|         itemEntry2
|             02: Item type 2: Item.
|             00: Power-up type 0: Bombs.
|             37: Screen position is three down and seven over.
|         00: End of this screen's data. 

Elevator

The following defines the elevator from Brinstar to Kraid.

| 12 FF FF   07 FF   04 02       00
| 
| -itemDataEntry-------------------
|            -screenEntry----------
|                    -itemEntry-
| 
| itemDataEntry
|     12: Map Y position is 12 (hex).
|     FF FF: This is the last entry for Brinstar item data.
|     screenEntry
|         07: Map X position is 7.
|         FF: This is the last screen in this item data entry.
|         itemEntry
|             04: Object type 4: Elevator.
|             02: Destination is level 2: Kraid's hideout.
|         00: The end.


See Also