Map Files

Much of the game's content comes from data located in map files.

Map files are the .BIN files located in the ST/* and BOSS/* directories of the game's filesystem.

These files are loaded into address 0x80180000 in RAM.

Map Header

Each map file contains a series of pointers at the beginning of the file that determine key properties of the map.

Below is a list of pointers common between nearly all map files.

Address Type Name Description
0x80180000 Function Update Entities Causes each entity's update function to run, which effectively populates all of the data for the entity, including how the object should behave, which sprite it should currently have, etc.
0x80180004 Function Process Entity Collision Processes collision for each entity.
0x80180008 Function Spawn On-Screen Entities Spawns entities that enter the screen's spawning radius.
0x8018000C Function Initialize Entities Initializes the entities in the room using an entry in the Entity Layouts list.
0x80180010 Data Room Layouts A pointer to a list of room structures, with each denoting the room's starting and ending X/Y coordinates, alongside graphic IDs and layout IDs for both tiles and entities.
0x80180014 Data Sprites A pointer to a list of frames, with each frame being a pointer to a list of sprite parts that compose the frame.
0x80180018 Data CLUT Banks A pointer to a list of Color Look-Up Table (CLUT) banks for the map, with each CLUT bank being a pointer to a list of CLUT entries.
0x8018001C Data Entity Layouts A pointer to a list of entity layouts, with each entity layout itself being a pointer to a list of entity initialization data.
0x80180020 Data Tile Layers A pointer to a paired list of tile layouts, with each entry having both a foreground and background entry.
0x80180024 Data Entity Graphics A pointer to a list of graphics definitions. Each graphics definition is a pointer to a series of structures that describe where compressed sprite pages should be placed in VRAM.
0x80180028 Function Pause Entities Processes entity update functions while the screen is paused due to some event, such as picking up a Life Max Up or using a Heart Refresh.

Room Layouts

This is a collection of Room structures that define the properties of each room.

Each Room structure has the following layout:

  1. struct RoomEntry {
  2. byte x_start;
  3. byte y_start;
  4. byte x_end;
  5. byte y_end;
  6. byte tile_layer_id;
  7. byte load_flags;
  8. byte entity_graphics_id;
  9. byte entity_layout_id;
  10. };

The x_start and y_start properties dictate the map cell where the top-left part of the room is located, with each map cell being a 256x256 square.

Similarly, the x_end and y_end properties dictate map cell where the bottom-right part of the room is located.

The tile_layer_id property is multiplied by 2 and then used as an index into the Tile Layers array to determine the layout of tiles in the room.

The load_flags property is used to either load an area (0xFF) or to dynamically load CLUTs from map data (0 < flag < 0xFF).

The entity_graphics_id property is used as an index into the Entity Graphics array to load entity tilesets into VRAM.

The entity_layout_id property is used as an index into the Entity Layouts array to determine where to place entities in the room.

Sprites

Each sprite is a pointer to an array of Frame structures.

Each Frame structure has the following layout:

  1. struct Frame {
  2. ushort num_parts;
  3. SpritePart parts[num_parts];
  4. };

  6. struct SpritePart {
  7. ushort flags;
  8. short offset_x;
  9. short offset_y;
  10. ushort width;
  11. ushort height;
  12. ushort clut_offset;
  13. ushort tileset_offset;
  14. ushort texture_start_x;
  15. ushort texture_start_y;
  16. ushort texture_end_x;
  17. ushort texture_end_y;
  18. };

The num_parts property identifies the number of SpritePart entries that compose the full frame.

The flags proprty dictates whether the sprite part should be vertically flipped (bit 0 set) or horizontally flipped (bit 1 set).

The offset_x and offset_y proprties determine the sprite part's X/Y offsets from the entity's actual X/Y coordinates.

The width and height properites determine the sprite part's width and height in pixels.

The clut_offset property is used to determine the CLUT for the entity. Its usage depends on the type of entity being processed.

The tileset_offset property identifies the specific quandrant offset from the entity's texture page.

The texture_start_x and texture_start_y properties determine the top-left coordinate of a square to copy from the entity's texture page.

Similarly, the texture_end_x and texture_end_y properties determine the bottom-right coordinate of a square to copy from the entity's texture page.

CLUT Banks

Each CLUT bank is a pointer a CLUT Layout, which is essentially an array of CLUT Entry structures that define how CLUTs should be loaded into VRAM.

The CLUT Layout and CLUT Entry structures have the following layout:

  1. struct ClutLayout {
  2. ushort type;
  3. ushort subtype;
  4. ClutEntry data[];
  5. };

  7. struct ClutEntry {
  8. int offset;
  9. int count;
  10. byte* clut_data;
  11. };

The type and subtype properties dictate how each CLUT entry is structured and how it should be copied into RAM.

Note: The structure above is indicative of the first entry in the CLUT Layouts table (a type 0x0005 CLUT entry), which is referenced every time a new map is loaded.

The offset property dictates where the CLUT should be stored relative to the CLUT storage location in RAM (0x8006CBCC).

The count property identifies how many bytes should be copied to the destination identified by the offset property.

The clut_data property is a pointer to CLUT data in RAM.

Entity Layouts

Each entity layout is a pointer to an array of Entity Data structures that define how entities should be placed in the room.

Each Entity Data structure has the following layout:

  1. struct EntityData {
  2. short pos_x;
  3. short pos_y;
  4. ushort entity_id;
  5. ushort slot;
  6. ushort initial_state;
  7. };

The pos_x and pos_y properties determine where the entity should be placed in the room.

The entity_id property identifies which update function should be run for the entity.

Note: The entity's update function not only determines how the entity should behave, but it also determines the entity's tileset, sprite, CLUT, HP, attack damage, hitbox dimensions, and effectively all of the entity's properties.

The slot property dictates where there entity should be placed in RAM relative to the dynamic entity storage location in RAM (0x800762D8).

The initial_state property is used within the entity's update function to determine various properties about the entity.

Tile Layers

Each entry in this section is a pair of pointers to Layer structures, with the first being a pointer to the Foreground layer and the second being a pointer to the Background layer.

Each Layer structure has the following layout:

  1. struct Layer {
  2. ushort* tile_indices;
  3. TileData tile_data;
  4. byte dimensions[3];
  5. byte load_flags;
  6. byte z_index;
  7. ushort drawing_flags;
  8. };

  10. struct TileData {
  11. byte* tileset_ids;
  12. byte* tile_positions;
  13. byte* clut_ids;
  14. byte* collision_ids;
  15. };

The tile_indices property is a list of indices to be used for the TileData arrays.

The tileset_ids property is an array of tileset IDs that indicate which tileset should be used for the given tile.

The tile_positions property is an array of 4-bit Y/X coordinates that determine where the tile graphic is located within the tileset.

The clut_ids property is an array of CLUT IDs that determine which CLUT should be used for the tile.

The collision_ids property is an array of collision IDs that determine what type of collision the tile should have.

The dimensions property is a 3-byte value that dictates the starting and ending map cells for each layer, with coordinate being a 6-bit value.

Note: The starting and ending X/Y coordinates (and the layer's dimensions in tiles) can be calculated in the following manner:
  1. x_start = dimensions & 0x3F;
  2. y_start = (dimensions >> 6) & 0x3F;
  3. x_end = (dimensions >> 12) & 0x3F;
  4. y_end = (dimensions >> 18) & 0x3F;
  5. width = (x_end - x_start + 1) * 16;
  6. height = (y_end - y_start + 1) * 16;

The load_flags property is used to determine which type of room is currently being loaded. (e.g. Load ("CD") room, Save room, etc.)

The z_index property dictates the Z-index of the current layer, which controls where entities are drawn in relation to the layer's tiles.

The drawing_flags property is used to determine which CLUTs to use for the layer.

Entity Graphics

Each entity graphics entry is a pointer to an array of Entity Graphic structures that define how entity graphics should be loaded into VRAM.

Each Entity Graphic structure has the following layout:

  1. struct EntityGraphic {
  2. ushort vram_x;
  3. ushort vram_y;
  4. ushort width;
  5. ushort height;
  6. byte* compressed_data;
  7. };

The vram_x and vram_y properties determine where the decompressed graphics should be placed in VRAM.

The width and height properties dictate the dimensions of the decompressed graphics.

The compressed_data property is a pointer to the compressed graphics data.