____________________________________ 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 | | | | | | | | | | ____ State conditions list | | | | | | | | | | | | | | | | | | | | | | ii aa xx yy ww hh uu dd cc dddd [...]
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 event header list) with E5E6
as a terminator.
The state conditions list defines conditions to load alternative state headers, they are checked in order and the first state condition whose check passes determines the state header to load. Due to this, state conditions must be specified in backwards chronological order.
Notes:
1 | Disable layer 1 during door transitions into and out of the room |
2 | Reload the CRE |
4 | Load extra large tileset |
______________ State condition | _________ State condition parameters | | ___ State header pointer | | | eeee [...] ssss ; First state condition eeee [...] ssss ; Second state condition [...] ; Other state conditions E5E6 ; Default state condition (terminator)
State conditions are two-byte pointers to code in bank $8F that may have parameters. If the check defined in the state conditions is passed, the state header pointer in that state condition header is used to load the room. The only exception is state condition $E5E6, the default, which doesn't have a state header pointer (the default state header simply follows this state condition header instead).
_________________ First door pointer (door BTS 0) | ____________ Second door pointer (door BTS 1) | | _______ Other door pointers (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.
_____________________________ 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. If the distance from door to spawn Samus is negative (8000h..FFFFh), the standard value of 0x00C8 is used for horizontal doors or 0x0180 for vertical doors.
The elevator properties are as follows:
0x80 | Door is an elevator |
0x40 | Switch map to new area |
0x0i | Marks elevator index i as used (for debug mode) |
The orientation values are as follows:
0 | Right |
1 | Left |
2 | Down |
3 | Up |
4+ | Door spawns a closing door cap |
_______________________________________________________________ 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 (FX2 in old SMILE) | | | | | | | | | | | | ___________ PLM population | | | | | | | | | | | | | ______ Library background | | | | | | | | | | | | | | _ Setup ASM (Layer1_2 in old SMILE) | | | | | | | | | | | | | | | 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.
Notes:
sssssssb
b
= 1, then the library background is used, otherwise custom layer 2 (defined in level data) is useds
= 0 is a special case that depends on b
b
= 0 (custom layer 2), then layer 2 and layer 1 scroll together at the same speed (like an extension of layer 1)b
= 1 (library background), then layer 2 does not scroll at all (static image background)s
!= 0), layer 2 scroll speed = (layer 1 scroll speed) * (s
/ 0x80)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 bbbbbbbb ; First block BTS bbbbbbbb ; Second block BTS [...] Optional: 0000yxnnnnnnnnnn ; First block layer 2 0000yxnnnnnnnnnn ; Second block layer 2 [...] ; Other blocks 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:
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.
__________________________________________ 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.
____________________________________ Enemy ID | _______________________________ X position | | __________________________ Y position | | | _____________________ Initialisation parameter (orientation in old SMILE, tilemaps in SMILE RF) | | | | ________________ Properties (special in SMILE) | | | | | ___________ Extra properties (special GFX bitset in SMILE, graphics in SMILE RF) | | | | | | ______ General purpose parameter (speed in SMILE) | | | | | | | _ General purpose parameter (speed 2 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 nn ; Number of enemy deaths needed to clear current room
Enemy population defines the placement of enemies, as well as some generic and enemy specific properties. They're stored in bank $A1 with each enemy being 16 bytes, plus a 3 byte overhead. The initialisation parameter is overwritten by generic enemy routines and so is often only used during enemy initialisation, the other two general purpose parameters do not have this restriction.
The properties are as follows:
8000h | Hitbox solid to Samus |
4000h | Respawns if killed |
2000h | Process instructions |
1000h | Block plasma beam |
800h | Process whilst off-screen |
400h | Intangible |
200h | Delete |
100h | Invisible |
The extra properties are as follows:
4 | Enable extended spritemap format |
1 | Disable enemy AI. Isn't disabled if intangible |
______ Enemy ID | _ Palette index | | iiii pppp ; First enemy iiii pppp ; Second enemy [...] ; Other enemies FFFF ; Terminator
Enemy set defines which enemies are allowed inside the room and which palette slot to use. They're stored in bank $B4 with each enemy being 4 bytes, plus the 2 byte terminator. Enemies that use the same palette may share the same palette index. Valid palette indices are 1, 2, 3 and 7; note that only palette 7 is affected by colour math.
_______ First scroll | ____ Second scroll | | _ Other scrolls | | | aa bb [...]
Scrolls define how the camera works for each 16×16 block (256px x 256px) area in left-to-right, top-down order (reading order). They're stored in bank $8F and are one byte per scroll.
Scroll values are as follows:
0 | Red. Cannot scroll into this area |
1 | Blue. Hides the bottom 2 rows of the area |
2 | Green. Unrestricted |
_______ X position | ____ Y position | | _ Block | | | xx yy nnnn ; First x-ray block xx yy nnnn ; Second x-ray block [...] ; Other x-ray blocks 0000 ; Terminator
Special x-ray blocks display custom x-ray graphics for blocks at given positions in the room. They're stored in bank $8F with each block being 4 bytes, plus the 2 byte terminator.
Special x-ray blocks are used in exactly one place in vanilla Super Metroid: the Bomb Torizo room during the escape sequence. It's a hacky way of allowing Samus to x-ray the shootable block in the bottom-right corner of the screen. Note that even after you've shot the shootable block, x-ray will still show the shootable block graphics.
The X/Y position is specified in (16px x 16px) block units. The block uses the level data block format, except that the block type is ignored.
Note that flexglow uses this pointer for the flexglow table instead.
____________ PLM ID | _______ X position | | ____ Y position | | | _ Parameter | | | | iiii xx yy pppp ; First PLM iiii xx yy pppp ; Second PLM [...] ; Other PLMs 0000 ; Terminator
PLM population defines the placement of PLMs, as well as some PLM specific properties. They're stored in bank $8F with each PLM being 6 bytes, plus the 2 byte terminator.
PLMs with PLM ID >= $DF89 are considered to be “item PLMs”, meaning the PLM argument specified in the PLM populations will be used as a unique ID and cannot be negative.
______ 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 Metroid has lots of specialised object formats, which are defined with an instruction list possibly combined with an “initialisation ASM”. In general, object formats have a handler that, for each object, executes a pre-instruction and then interprets the instruction list.
The instruction list is a list of ASM instructions and special instructions. ASM instructions have a negative value (meaning $8000..FFFF), which is a pointer to a function to be executed, followed by any parameter values that the function requires. Special instructions (usually graphical in nature) have a positive value (meaning $0000..7FFF), usually a timer value, followed by any parameter values.
Common ASM instructions include looping, conditional execution, setting the pre-instruction, deleting the object and sleeping. The pre-instruction is a function that's executed before the object's instruction list is processed for the current frame. Objects that are sleeping are suspended from handling until they are awakened (usually by a pre-instruction set earlier in the object instruction list).
PLMs (post-load modifications) are objects that modify level data blocks in real-time. They exist in bank $84 and are typically loaded with a room from a room header (e.g. items, doors) or spawned as part of a block interaction (e.g. shot block crumbling).
PLM header:
______ Initialisation ASM pointer | _ Instruction list pointer | | aaaa iiii
Door PLM header:
___________ Initialisation ASM pointer | ______ Instruction list pointer | | _ Instruction list pointer - door closing | | | aaaa iiii dddd
The third pointer for door PLMs is used instead of the second pointer when the PLM is placed where a blue door would normally be closing when Samus enters a room.
The special instructions for PLMs have the format:
______ Draw timer | _ Pointer to draw instruction | | tttt dddd
The draw timer is how many frames to wait until the next instruction in the instruction list is proceeded to.
The draw instruction format is a list of:
nnnn ; Number of blocks bbbb [...] ; Blocks xx yy ; X and Y offsets from origin to start drawing from
where the list is terminated by xx yy = 00 00
.
Blocks are drawn from the PLM's position, the direction they're drawn in is given by the most significant bit of n
.
If n
< 8000h, the blocks are drawn in a horizontal line to the right.
If n
>= 8000h, n
& 7FFFh blocks are drawn in a vertical line downwards.
Enemy projectiles exist in bank $86 and are typically spawned by enemies and can use their graphics and palette.
Enemy projectile header:
__________________________________ Initialisation AI | _____________________________ (Initial) pre-instruction | | ________________________ Instruction list pointer | | | ___________________ X radius | | | | ________________ Y radius | | | | | _____________ Damage/properties | | | | | | ________ Touch AI | | | | | | | ___ Shot AI | | | | | | | | iiii pppp IIII xx yy Pddd tttt ssss
The properties are as follows:
8000h | Detect collisions with projectiles |
4000h | Don't die on contact |
2000h | Disable collisions with Samus |
1000h | Low priority (drawn under enemies/Samus/projectiles) |
The special instructions for enemy projectiles have the format:
______ Spritemap timer | _ Pointer to spritemap | | tttt ssss
The spritemap timer is how many frames to wait until the next instruction in the instruction list is proceeded to. Within the spritemap, the tile numbers added to the base tile number set when the enemy projectile was spawned (so the projectile can access enemy graphics).
Animated tiles objects are objects that modify tile graphics in real-time. They exist in bank $87 and are loaded with a room from an FX header.
Animated tiles object header format:
___________ Instruction list pointer | ______ Size | | _ VRAM address | | | iiii ssss vvvv
The special instructions for animated tiles objects have the format:
______ Animation timer | _ Pointer to tile graphics | | tttt ssss
The animation timer is how many frames to wait until the next instruction in the instruction list is proceeded to.
HDMA objects exist in bank $88 and are typically loaded with a room as part of FX or spawned by power bombs / x-ray.
HDMA object header format:
_______ HDMA options | ____ PPU register index | | _ Instruction list pointer | | | dd pp iiii
The special instructions for HDMA objects have the format:
______ Table timer | _ Pointer to HDMA table | | tttt ssss
The table timer is how many frames to wait until the next instruction in the instruction list is proceeded to.
Palette FX objects are objects that modify palette data in real-time. They exist in bank $8D and are loaded with a room from an FX header.
Palette FX object header format:
______ Initialisation ASM pointer | _ Instruction list pointer | | aaaa iiii
The special instructions for palette FX objects have the format:
______ Palette timer | _ Palette instruction list | | tttt [...]
The palette timer is how many frames to wait until the next instruction in the instruction list is proceeded to.
The ASM instructions are usually used for setting the initial colour index,
which is an index into CGRAM equal to (p * 10h + c) * 2
where p
is the palette number and c
is the colour index within the palette.
Palette instructions are a mix of colours (which are positive values) and ASM instructions (negative values). Colours are written to successive positions in CGRAM starting from initial colour index. ASM instructions can modify the colour index between listed colour values, and the instruction $C595 is used to terminate the palette instruction list.