User Tools

Site Tools


super:technical_information:data_structures

This is an old revision of the document!


Room header

 _______________________________________ Room index
|   ____________________________________ Area index
|  |   _________________________________ X position (of top left corner) on the map
|  |  |   ______________________________ Y position (of top left corner) on the map
|  |  |  |   ___________________________ Room width (in units of screens = 16 blocks = 256 pixels)
|  |  |  |  |   ________________________ Room height (in units of screens = 16 blocks = 256 pixels)
|  |  |  |  |  |   _____________________ Up scroller
|  |  |  |  |  |  |   __________________ Down scroller
|  |  |  |  |  |  |  |   _______________ CRE bitset
|  |  |  |  |  |  |  |  |   ____________ Door list pointer
|  |  |  |  |  |  |  |  |  |     _______ Optional event headers
|  |  |  |  |  |  |  |  |  |    |      _ Mandatory event header, specifies that the default state follows this room header
|  |  |  |  |  |  |  |  |  |    |     |
ii aa xx yy ww hh uu dd cc dddd [...] E5E6

Room headers define rooms, they exist in bank $8F and room header pointers are what SMILE displays as a dropdown box for room selection. They are variable length (due to the optional event headers) with E5E6 as an effective terminator.

The event headers define conditions to load alternative state headers, they are checked in order and the first event header whose check passes is to determine the state header to load. Due to this, event headers must be specified in backwards chronological order.

Area indices

Area indices

0 Crateria
1 Brinstar
2 Norfair
3 Wrecked Ship
4 Maridia
5 Tourian
6 Ceres
7 Debug

Notes:

  • The room index is almost unused, aside from some specific checks to do with atmospheric graphics in some areas.
  • The room width may not exceed 15 due to the way block collision calculations are implemented
  • Room width * room height may not exceed 0x50 due to memory constraints
  • The up scroller defines the threshold Y position that Samus needs to exceed (relative to the screen) for the screen to start scolling downwards when the camera is at the top of the room
  • The down scroller defines the threshold Y position that Samus needs to exceed (relative to the screen) for the screen to start scolling upwards when the camera is at the bottom of the room
  • The CRE bitset defines some flags that affect how the CRE is loaded during door transitions:
1 Disable layer 1 during door transitions into and out of the room
2 Reload the CRE
4 Load extra large tileset

Event header

 ____________ Event
|     _______ Event parameters
|    |      _ State header pointer
|    |     |
eeee [...] ssss

Events are two-byte pointers to code in bank $8F that may have parameters depending on the event in question. If the check defined in the event is passed, the state header pointer for that event is used to load the room. The only exception is event $E5E6, the default event, which doesn't have a state header pointer (the default state header simply follows this event header instead).

List of events used in Super Metroid

List of events used in Super Metroid

Event Event parameters Description
$E5E6 Default
$E5EB dddd Check passes if the current door pointer = d
$E5FF Check passes if main area boss is dead
$E612 ee Check passes if event e is set
$E629 bb Check passes if area boss b is dead
$E640 Check passes if morph ball has been collected
$E652 Check passes if morph ball and missiles have been collected
$E669 Check passes if power bombs have been collected
$E678 Check passes if speed booster has been collected

Event numbers are given as follows:

00 Zebes is awake
01 Shitroid ate sidehopper
02 Mother Brain's glass is broken
03 Zebetite 1 is destroyed
04 Zebetite 2 is destroyed
05 Zebetite 3 is destroyed
06 Phantoon statue is grey
07 Ridley statue is grey
08 Draygon statue is grey
09 Kraid statue is grey
0A Entrance to Tourian is unlocked
0B Maridia noobtube is broken
0C Lower Norfair chozo has lowered the acid
0D Shaktool cleared a path
0E Zebes timebomb set
0F Critters escaped
10 1st Metroid hall cleared
11 1st Metroid shaft cleared
12 2nd Metroid hall cleared
13 2nd Metroid shaft cleared
14 Unused
15 Outran speed booster lavaquake

Boss bits are given as follows:

1 Area boss (Kraid, Phantoon, Draygon, both Ridleys)
2 Area mini-boss (Spore Spawn, Botwoon, Crocomire, Mother Brain)
4 Area torizo (Bomb Torizo, Golden Torizo)

Door list

 _________________ First door pointer (door BTS 0)
|     ____________ Second door pointer (door BTS 1)
|    |     _______ Other door pointerd (door BTS 2+)
|    |    |
aaaa bbbb [...]

Door lists are a list of door pointers that can be used in a room, they exist in bank $8F. They are variable length with no terminator, and are indexed by door BTS (thus, there is an effective maximum of 128 door pointers).

The door pointers themselves are two-byte pointers to door headers in bank $83.

Door header

 _____________________________ Destination room header pointer (bank $8F)
|     ________________________ Elevator properties
|    |   _____________________ Orientation
|    |  |   __________________ X position low byte
|    |  |  |   _______________ Y position low byte
|    |  |  |  |   ____________ X position high byte
|    |  |  |  |  |   _________ Y position high byte
|    |  |  |  |  |  |   ______ Distance from door to spawn Samus
|    |  |  |  |  |  |  |     _ Custom door ASM to execute (bank $8F)
|    |  |  |  |  |  |  |    |
rrrr ee oo xx yy XX YY dddd aaaa

Door headers define doors, they exist in bank $83 and have a fixed length of 12 bytes. The door ASM can execute any arbitrary ASM and is often used to set scroll values for the new room where the door would normally be hidden inside a red scroll.

The elevator properties are as follows:

0x80 Door is an elevator
0x40 Switch map to new area
0x0i Marks elevator i as used

The orientation values are as follows:

0 Right
1 Left
2 Down
3 Up
4+ Door spawns a closing door cap

State header

 _______________________________________________________________ Level data
|       ________________________________________________________ Tileset
|      |   _____________________________________________________ Music data index
|      |  |   __________________________________________________ Music track
|      |  |  |   _______________________________________________ FX ($83)
|      |  |  |  |     __________________________________________ Enemy population ($A1)
|      |  |  |  |    |     _____________________________________ Enemy set ($B4)
|      |  |  |  |    |    |     ________________________________ Layer 2 scroll X
|      |  |  |  |    |    |    |   _____________________________ Layer 2 scroll Y
|      |  |  |  |    |    |    |  |     ________________________ Scroll
|      |  |  |  |    |    |    |  |    |      __________________ Special x-ray blocks
|      |  |  |  |    |    |    |  |    |    |     ______________ Main ASM
|      |  |  |  |    |    |    |  |    |    |    |     _________ PLM population
|      |  |  |  |    |    |    |  |    |    |    |    |     ____ Library background
|      |  |  |  |    |    |    |  |    |    |    |    |    |   _ Setup ASM
|      |  |  |  |    |    |    |  |    |    |    |    |    |  |
llllll tt MM mm ffff eeee EEEE xx yy ssss xxxx AAAA pppp bbbb aaaa

State headers define the parts of rooms that can change due to different events.

Tilesets

Tilesets

0 Upper Crateria
1 Red Crateria
2 Lower Crateria
3 Old Tourian
4 Wrecked Ship - power on
5 Wrecked Ship - power off
6 Green/blue Brinstar
7 Red Brinstar / Kraid's lair
8 Pre Tourian entrance corridor
9 Heated Norfair
Ah Unheated Norfair
Bh Sandless Maridia
Ch Sandy Maridia
Dh Tourian
Eh Mother Brain's room
Fh Blue Ceres
10h White Ceres
11h Blue Ceres elevator
12h White Ceres elevator
13h Blue Ceres Ridley's room
14h White Ceres Ridley's room
15h Map room / Tourian entrance
16h Wrecked Ship map room - power off
17h Blue refill room
18h Yellow refill room
19h Save room
1Ah Kraid's room
1Bh Crocomire's room
1Ch Draygon's room

Music data indices

Music data indices

0 No change
3 Title sequence
6 Empty Crateria
9 Lower Crateria
Ch Upper Crateria
Fh Green Brinstar
12h Red Brinstar
15h Upper Norfair
18h Lower Norfair
1Bh Maridia
1Eh Tourian
21h Mother Brain
24h Boss fight 1
27h Boss fight 2
2Ah Miniboss fight
2Dh Ceres
30h Wrecked Ship
33h Zebes boom
36h Intro
39h Death
3Ch Credits
3Fh “The last Metroid is in captivity”
42h “The galaxy is at peace”
45h Shitroid (same as boss fight 2)
48h Samus theme (same as upper Crateria)

Music track values

Music track values

0 No change
1 Samus fanfare
2 Item fanfare
3 Elevator
4 Pre-statue hall
5 Song 0
6 Song 1
7 Song 2

Notes:

  • Level data is a three-byte pointer to compressed data defining the placement of layer 1 tiles, block properties (including BTS) and optionally custom layer 2 tile placement
  • The tileset is an index into a table that defines the tile table, tile graphics and palette
  • The music data index is an index into a music pointers that define songs 0, 1 and 2
  • The FX is an (optional) pointer to data defining graphical effects such as animated tiles, palette glows and layer 3 (e.g. water, lava, spores)
  • The enemy population is a pointer to data defining enemy placement and other parameters
  • The enemy set is a pointer to data defining which enemies use which palettes
  • The layer 2 scroll X/Y is a value that determines whether or not custom layer 2 is used, and how fast layer 2 scrolls compared to layer 1 (parallax effect)
    • In binary, let layer 2 scroll X/Y = sssssssb
    • If b = 1, then the library background is used, otherwise custom layer 2 (defined in level data) is used
    • s = 0 is a special case that depends on b
      • If b = 0 (custom layer 2), then layer 2 and layer 1 scroll together at the same speed (like an extension of layer 1)
      • If b = 1 (library background), then layer 2 does not scroll at all (static image background)
    • Otherwise (if s != 0), layer 2 scroll speed = (layer 1 scroll speed) * (s / 0x80)
  • The scroll is an (optional) pointer to data defining which 16×16 regions are scrollable
    • If scroll = 0, then every scroll region is set to green, except for the bottom row, which is set to blue
    • If scroll = 1, then every scroll region is set to green
  • The special x-ray blocks is an (optional) pointer to data defining custom x-ray block graphics
  • The main ASM is an (optional) pointer to code run every frame
  • The PLM population is an (optional) pointer to data defining PLM placement and parameters
  • The library background is an (optional) pointer to data defining operations for loading layer 2
  • The setup ASM is an (optional) pointer to code run upon loading the room

Level data

ssssssssssssssss ; Size of decompressed layer 1 data (2 x the number of blocks)
 _______ Block type
|    ___ Y flip
|   | __ X flip
|   || _ Block number
|   |||
ttttyxnnnnnnnnnn ; First block
ttttyxnnnnnnnnnn ; Second block
[...]            ; Other blocks
ttttyxnnnnnnnnnn ; Last block
bbbbbbbb         ; First block BTS
bbbbbbbb         ; Second block BTS
[...]
bbbbbbbb         ; Last block BTS
Optional:
0000yxnnnnnnnnnn ; First block layer 2
0000yxnnnnnnnnnn ; Second block layer 2
[...]            ; Other blocks layer 2
0000yxnnnnnnnnnn ; Last block layer 2

Level data is defined by specifying data for each 16px x 16px block in the room. This data is split into layer 1 blocks, BTS and optionally layer 2 blocks. Layer 1/2 are two bytes per block, BTS is one byte per block, and a two byte “decompressed layer 1” size. The decompressed size is followed by layer 1 data, followed by BTS, followed by layer 2 (if used) in that order. Level data is compressed in ROM.

Layer 1 blocks uses the binary format shown above where:

  • Block type specifies the primary type of the block
  • X/Y flip flips the graphics of the block
  • Block number specifies the index of the block into the tile table (provides the graphics of the block)

Layer 2 blocks use the same format, except that they have no block type (they are padded with zeros instead).

BTS data further specifies the type of a block, depending on the primary block type used, e.g. different slope types.

Block types and BTS values

Block types and BTS values

Air types Solid types
0 Air 8 Solid block
1 Slope 9 Door block
2 Spike air Ah Spike block
3 Special air Bh Special block
4 Shootable air Ch Shootable block
5 Horizontal extension Dh Vertical extension
6 Unused air Eh Grapple block
7 Bombable air Fh Bombable block
Block type BTS Description
2 / Ah Spike 0 Solid only. Generic spike (60 damage)
1 Solid only. Kraid's lair spike (10h damage)
2 Air only. Air spike (10h damage)
3 Solid only. Draygon's broken turret (10h damage)
Fh Solid only. Enemy breakable block (used in Shaktool's room)
3 / Bh Special 0 1×1 respawning crumble block
1 2×1 respawning crumble block
2 1×2 respawning crumble block
3 2×2 respawning crumble block
4 1×1 crumble block
5 2×1 crumble block
6 1×2 crumble block
7 2×2 crumble block
8 Air only. Rightwards treadmill, disabled in Wrecked Ship unless Phantoon is dead
9 Air only. Leftwards treadmill, disabled in Wrecked Ship unless Phantoon is dead
Ah Air only. Rightwards treadmill, always on
Bh Air only. Leftwards treadmill, always on
Eh Respawning speed boost block
Fh Speed boost block
44h Generic PLM shot trigger
45h Item collision detection
46h Scroll PLM trigger
47h Map station right access
48h Map station left access
49h Energy station right access
4Ah Energy station left access
4Bh Missile station right access
4Ch Missile station left access
4Dh Save station trigger
Crateria/debug 80h Air only. Ice physics
Brinstar 80h Floor plant
81h Ceiling plant
82h Respawning speed block, slower crumble animation
83h Speed block, slower crumble animation
84h Respawning speed block (used by dechora pit)
85h Speed boost block
Norfair 83h Lower Norfair chozo hand trigger
Wrecked Ship 80h Wrecked Ship chozo hand trigger
Maridia 80h Quicksand surface, can run on without sinking (used in snail room)
81h Quicksand surface
82h Quicksand surface
83h Submerging quicksand (used in sand falls rooms)
84h Sand falls - slow. Used in the ceilings of pre-Draygon mochtroid rooms (so basically unused)
85h Sand falls - fast
7 / Fh Bombable 0 1×1 respawning bomb block
1 2×1 respawning bomb block
2 1×2 respawning bomb block
3 2×2 respawning bomb block
4 1×1 bomb block
5 2×1 bomb block
6 1×2 bomb block
7 2×2 bomb block
4 / Ch Shootable 0 1×1 respawning shot block
1 2×1 respawning shot block
2 1×2 respawning shot block
3 2×2 respawning shot block
4 1×1 shot block
5 2×1 shot block
6 1×2 shot block
7 2×2 shot block
8 Respawning power bomb block
9 Power bomb block
Ah Respawning super missile block
Bh Super missile block
10h Gate blocks
40h Blue door facing left
41h Blue door facing right
42h Blue door facing up
43h Blue door facing down
44h Generic shot trigger
45h Item trigger
46h Left blue gate trigger
47h Right blue gate trigger
48h Left red gate trigger
49h Right red gate trigger
4Ah Left green gate trigger
4Bh Right green gate trigger
4Ch Left orange gate trigger
4Dh Right orange gate trigger
4Fh Critters escape block

FX

 __________________________________________ Door pointer
|     _____________________________________ Base Y position
|    |     ________________________________ Target Y position
|    |    |     ___________________________ Y velocity
|    |    |    |     ______________________ Timer
|    |    |    |    |   ___________________ Layer 3 type
|    |    |    |    |  |   ________________ Default layer blending configuration (FX A)
|    |    |    |    |  |  |   _____________ FX layer 3 layer blending configuration (FX B)
|    |    |    |    |  |  |  |   __________ Liquid options (FX C)
|    |    |    |    |  |  |  |  |   _______ Palette FX bitset
|    |    |    |    |  |  |  |  |  |   ____ Animated tiles bitset
|    |    |    |    |  |  |  |  |  |  |   _ Palette blend
|    |    |    |    |  |  |  |  |  |  |  |
dddd,bbbb,tttt,vvvv,tt,ff,AA,BB,CC,pp,aa,bb ; First FX entry
dddd,bbbb,tttt,vvvv,tt,ff,AA,BB,CC,pp,aa,bb ; Second FX entry
[...]                                       ; Other FX entries
0000,bbbb,tttt,vvvv,tt,ff,AA,BB,CC,pp,aa,bb ; Default FX entry

OR

FFFF ; No FX

FX defines roomwide graphical effects, they're stored in bank $83. A room either has a two byte FFFF entry specifying there is no FX, or it has optional door-dependent FX entries followed by the default entry. A door-dependent FX entries is used if the door taken into the room matches the entry's door pointer, if no doors match (or if there are no entries) the default entry is used.

Layer 3 types

Layer 3 types

0 None
2 Lava
4 Acid
6 Water
8 Spores
Ah Rain
Ch Fog
20h Scrolling sky
22h Unused
24h Fireflea
26h Tourian entrance statue
28h Ceres Ridley
2Ah Ceres elevator
2Ch Haze

Layer blending configurations

Layer blending configurations

2/Eh/20h Normal. BG1/BG2/sprites are drawn with BG3 added on top
4 Normal, but BG2 is disabled Used by Phantoon
6 Normal, but sprites aren't affected by BG3 and sprites are added to BG1/BG2 (instead of hidden) Unused
8 Normal, but BG1/sprites aren't affected by BG3 and sprites are added to BG2 (instead of hidden) Used in some power off Wrecked Ship rooms
Ah Normal, but BG1 isn't affected by BG3 Used with FX layer 3 type = spores
Ch Normal, but BG3 is disabled and colour math is subtractive Used with FX layer 3 type = fireflea
10h/12h Normal, but BG3 is disabled inside window 1 Used by morph ball eye and varia/gravity suit pickup
14h/22h Normal, but BG1 isn't affected by BG3 and colour math is subtractive Sometimes use with FX layer 3 type = water
16h BG1/sprites are drawn after the result of drawing BG2/BG3 is subtracted Sometimes use with FX layer 3 type = water
18h/1Eh/30h BG3 is drawn with the result of drawing BG1/BG2/sprites added on top Used with FX layer 3 type = lava / acid / fog / Tourian entrance statue, sometimes use with FX layer 3 type = water
1Ah Normal, but BG2 and BG3 have reversed roles Used by Phantoon
1Ch Normal, but BG2 and BG3 have reversed roles, colour addition is halved and backdrop is disabled Unused
24h BG1/BG2/sprites are drawn the backdrop is added on top inside window 1 Used by Mother Brain
26h Normal, but colour addition is halved Unused
28h Normal, but BG3 is disabled, colour math is subtractive, and the backdrop subtracts red if there is no power bomb explosion Used in some default state Crateria rooms, some power off Wrecked Ship rooms, pre plasma beam rooms
2Ah Normal, but BG3 is disabled, colour math is subtractive, and the backdrop subtracts orange if there is no power bomb explosion Used in blue Brinstar rooms, Kraid's lair entrance, n00b tube side rooms, plasma beam room, some sand falls rooms
2Ch Normal, but BG3 is disabled Used by FX layer 3 type = haze and torizos
2Eh Normal, but colour math is subtractive Unused
32h Normal, but BG1 isn't affected by BG3 and colour math is subtractive Unused
34h Normal, but power bombs don't affect BG2 Unused

Liquid options

Liquid options

1 Liquid flows (leftwards)
2 Layer 2 is wavy
4 Liquid physics are disabled (used in n00b tube room)
40h Big tide (liquid fluctuates up and down, a la the gauntlet)
80h Small tide (liquid fluctuates up and down)

Enemy population

 ____________________________________ Enemy ID
|     _______________________________ X position
|    |     __________________________ Y position
|    |    |     _____________________ Initialisation parameter (orientation in SMILE)
|    |    |    |     ________________ Properties (special in SMILE)
|    |    |    |    |     ___________ Extra properties (special graphics bitset in SMILE)
|    |    |    |    |    |     ______ General purpose parameter (speed in SMILE)
|    |    |    |    |    |    |     _ General purpose parameter (speed2 in SMILE)
|    |    |    |    |    |    |    |
iiii xxxx yyyy oooo pppp gggg aaaa bbbb ; First enemy
iiii xxxx yyyy oooo pppp gggg aaaa bbbb ; Second enemy
[...]                                   ; Other enemies
FFFF                                    ; Terminator
nnnn                                    ; Number of enemy deaths needed to clear current room

Enemy set

 ______ Enemy ID
|     _ Palette index
|    |
iiii pppp ; First enemy
iiii pppp ; Second enemy
[...]     ; Other enemies
FFFF      ; Terminator

Scroll

 _______ First scroll
|   ____ Second scroll
|  |   _ Other scrolls
|  |  |
aa bb [...]

Special x-ray blocks

 _______ X position
|   ____ Y position
|  |   _ Block number
|  |  |
xx yy nnnn ; First x-ray block
xx yy nnnn ; Second x-ray block
[...]      ; Other x-ray blocks
0000       ; Terminator

PLM population

 ____________ PLM ID
|     _______ X position
|    |   ____ Y position
|    |  |   _ Parameter
|    |  |  |
iiii xx yy pppp ; First PLM
iiii xx yy pppp ; Second PLM
[...]           ; Other PLMs
0000            ; Terminator

Library background

 ______ Type
|     _ Parameters
|    |
tttt [...] ; First background command
tttt [...] ; Second background command
[...]      ; Other background commands
0000       ; Terminator

The list of commands used in Super Metroid is as follows:

Type Parameters Description
2 ssssss dddd nnnn Transfer n bytes from s to d in VRAM
4 ssssss dddd Decompress s to d in bank $7E
6 Clear layer 3
8 ssssss dddd nnnn Transfer n bytes from s to d in VRAM and set BG3 tiles base address = $2000
Ah Clear layer 2
Ch Clear Kraid's layer 2
Eh DDDD ssssss dddd nnnn Transfer n bytes from s to d in VRAM if the current door pointer = D
super/technical_information/data_structures.1540176927.txt.gz · Last modified: 2018/10/22 02:55 by p.jboy