User Tools

Site Tools

return_of_samus:technical_information:screen_transitions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
return_of_samus:technical_information:screen_transitions [2023/05/29 19:12] – [B* - Load Graphics Page] rt-55jreturn_of_samus:technical_information:screen_transitions [2023/07/02 17:36] (current) – [B* - Load Graphics Page] rt-55j
Line 1: Line 1:
 ====== Screen Transitions ====== ====== Screen Transitions ======
-{{..:data_locations:rosamus.png | MII Samus}} Here we shall discuss how to dissect these pesky screen transitions, hopefully once and for all. It is advised that you first read the page on [[return_of_samus:technical_information:level_data_banks |Level Data Banks]] before continuing on.+{{..:data_locations:rosamus.png | MII Samus}} Screen transitions (sometimes referred to as "doors") in Metroid II use a bytecode interpreter to perform the various actions needed when moving between different rooms, such as changing the tileset, activating a fadeout, and so forth. A basic knowledge of the screen transition bytecode language and how to easily edit it are essential skills for making more elaborate hacks of this game.
  
-Now, as discussed on the previously linked page, every screen has a screen transition index assigned to it. The index refers to a pointer table that starts at 0x142E5 in the ROM. These pointers point to scripts that define the transition's behavior. The scripting "language" used in these transitions will be described below.+It is recommended that you have a basic understanding of [[return_of_samus:technical_information:level_data_banks |Level Data Banks]] before continuing on.
  
-===== The Language =====+===== Internal Workings =====
  
-Once the game identifies the script to use, it copies it to $D700 in RAM (which is the easiest place to inspect how they work). From there, it interprets the script byte by byte in a big loop.+Each screen on each map has a screen transition index associated with it. As long as the index is not zero, the screen transition corresponding to the room will be activated once Samus touches any edge of the screen. (The pointer table indexed by the transition number starts at 0x142E5 in rom.)
  
-First it checks if it has reached the terminating operator ($FF), and exits if that's the case. After that, it masks the right nybble of the current byte (e.g. $B2 becomes $B0), and then goes through the low-level equivalent of a switch statement (or rather, a bunch of if-else statements) to find the routine that matches the operator. After processing the operator's operands, the interpreter loops back to the beginning, where it processes the next operand.+Once the game identifies the script to use, it copies the next $40 bytes to ''$D700'' in RAM (which is the easiest place to inspect how they work). From there, it interprets the script byte-by-byte in a big loop. (Note that this means the //maximum// effective size of a door script is 64 (0x40) bytes, but you will probably never hit that limit.)
  
-Scripts are limited to 64 (0x40) bytes in length, but you'll literally never hit that limit.+The interpreter first checks if it has reached the end of the script ($FF), and exits if that is the case. After that, it masks out the lower nybble of the current byte (e.g. $B2 becomes $B0), and then proceeds through a bunch of if-else statements to find the routine that matches the upper nybble (the "B" in $B2, for example), and then executes the command. After executing the command, the interpreter loops back to the beginning and repeats the process for the next operation.
  
 (Note that all 16-bit values (pointers, etc.) are assumed to be little-endian, as usual.) (Note that all 16-bit values (pointers, etc.) are assumed to be little-endian, as usual.)
 +
 +===== Tokens/Operators =====
 +
 +Here is a list of valid tokens/operators used by the bytecode interpreter
  
 ==== FF - Terminating Operator ==== ==== FF - Terminating Operator ====
Line 22: Line 26:
 Copies a block of data starting at a specified bank and address to somewhere in RAM. Copies a block of data starting at a specified bank and address to somewhere in RAM.
  
-Cases:+Syntax:
  
-   * 01 bb ssss dddd llll - Saves bb:ssss as the source of a BG tileset (necessary for saving properly) +   * ''01 bb ssss dddd llll'' - Saves bb:ssss as the source of a BG tileset (meaning the tiles will be loaded when reloading a save) 
-   * 02 bb ssss dddd llll - Saves ssss as the source of a sprite tileset (necessary for saving properly) +   * ''02 bb ssss dddd llll'' - Saves ssss as the source of a sprite tileset (meaning the tiles will be loaded when reloading a save) 
-   * 0* bb ssss dddd llll - Just copies the data.+   * ''0* bb ssss dddd llll'' - Just copies the data.
  
 Operands: Operands:
Line 41: Line 45:
 Copies the desired metatile table to $DA00-$DBFF in WRAM. Copies the desired metatile table to $DA00-$DBFF in WRAM.
  
-The metatile table pointer list begins at 0x23F1A in ROM. 
- 
-For some reason, the pointers are a little out of order.  
 <code> <code>
-80 4C (final ruins) should be 3rd +0 - finalLab 
-80 4A (inside ruins) should be second +1 - ruinsInside 
-80 48 (bubbles/ruins 3 catacombs) should be first +2 - plantBubbles 
-80 4E (queen room) +3 - queen 
-80 50 (first/last caves) +4 - caveFirst 
-80 52 (outside/ship) +5 - surface 
-94 55 (acid caves down) should be eighth +6 - lavaCavesEmpty 
-A8 56 (acid caves up) should be ninth +7 - lavaCavesFull 
-80 54 (acid caves mid) should be seventh +8 - lavaCavesMid 
-BC 57 (outside ruins)+9 - ruinsExt
 </code> </code>
 +
 +The lava caves adjust their lava levels by changing their metatiles to sets with more or fewer lava tiles during door transitions.
 +
 +The metatile table pointer list begins at ''0x23F1A'' in ROM. (For some reason, these pointers slightly out of order compared to how the data is stored in the rom.)
 +
 ==== 2x - Select collision table ==== ==== 2x - Select collision table ====
  
 Copies the desired collision table to $DC00-$DCFF in WRAM. Copies the desired collision table to $DC00-$DCFF in WRAM.
 +
 +<code>Collision Tables
 +0 - plantBubbles
 +1 - ruinsInside
 +2 - queen
 +3 - caveFirst
 +4 - surface
 +5 - lavaCaves
 +6 - ruinsExt
 +7 - finalLab</code>
  
 The collision table pointer list begins at 0x23EEA in ROM. The collision table pointer list begins at 0x23EEA in ROM.
Line 64: Line 80:
 ==== 3x - Select solidity indexes ====  ==== 3x - Select solidity indexes ==== 
  
-Copies the desired solidity indexes to WRAM.+Copies the desired solidity indexes to WRAM, for Samus, enemies, and Samus' projectiles. 
 + 
 +Basically, the way it works is that if an 8x8 tile is less than the specified index, then it is treated as a solid. While Samus, enemies, and projectiles may use different values, the process remains the same. 
 + 
 +<code>Solidity Values 
 +0 - plantBubbles 
 +1 - ruinsInside 
 +2 - queen 
 +3 - caveFirst 
 +4 - surface 
 +5 - lavaCaves 
 +6 - ruinsExt 
 +7 - finalLab</code> 
 + 
 +Note that (by default) these match up perfectly with the collision values previously.
  
 The solidity indexes are stored in a table starting at 0x23EFA. Each entry row is four bytes wide, though only three are used. The solidity indexes are stored in a table starting at 0x23EFA. Each entry row is four bytes wide, though only three are used.
Line 73: Line 103:
    * $D056 & $D813 - Enemy solidity index    * $D056 & $D813 - Enemy solidity index
    * $D08A & $D814 - Projectile solidity index    * $D08A & $D814 - Projectile solidity index
- 
-Basically, for Samus, the way it works is that if an 8x8 tile is less than the specified index, then it is treated as a solid. It works the same for enemies and projectiles as well. 
  
 ==== 4* - Warp ==== ==== 4* - Warp ====
Line 80: Line 108:
 Warps Samus to the specified map and screen. Warps Samus to the specified map and screen.
  
-Form: 4byx+Syntax: ''4b yx''
  
 Operands: Operands:
Line 100: Line 128:
 ==== 6* - Change acid & spike damage ==== ==== 6* - Change acid & spike damage ====
  
-Form: 6* xx yy+Syntax: ''6* xx yy''
  
 Operands: Operands:
Line 107: Line 135:
    * yy - spike damage    * yy - spike damage
  
-I'm not sure if this is ever used, but it's cool at least.+This is used towards the end of the game to increase the acid damage from $02 to $06.
  
-For reference, the default starting values are $02 and $08.+For reference, the default starting values are $02 and $08. (Note that damage values for Samus in this game are binary-coded decimal.)
  
 ==== 7* - Exit Room After Last Boss Death ==== ==== 7* - Exit Room After Last Boss Death ====
Line 118: Line 146:
   - Disables LCD interrupt from last boss fight   - Disables LCD interrupt from last boss fight
   - Reloads the status bar into the window   - Reloads the status bar into the window
 +
 ==== 8* - Transition to the Queen Fight ==== ==== 8* - Transition to the Queen Fight ====
  
 Handles a lot of special stuff regarding the queen fight, but not everything. Handles a lot of special stuff regarding the queen fight, but not everything.
  
-Form: 8a bbbb cccc dddd eeee+Form: ''8a bbbb cccc dddd eeee''
   * a: Bank for current room ($F)   * a: Bank for current room ($F)
   * b: Scroll Y position ($F48)   * b: Scroll Y position ($F48)
Line 128: Line 157:
   * d: Samus Y position ($F02)   * d: Samus Y position ($F02)
   * e: Samus X position ($EDE)   * e: Samus X position ($EDE)
 +
 ==== 9* - Conditional Operator ==== ==== 9* - Conditional Operator ====
  
-Form: 9* nn xxxx+Syntax: ''9* nn xxxx''
  
 Operands: Operands:
Line 150: Line 180:
  
 Forms: Forms:
-   - B1 bb xxxx - Load BG graphics page (128 tiles) to $9000 in VRAM. +   - ''B1 bb xxxx'' - Load BG graphics page (128 tiles) to $9000 in VRAM. 
-   - B2 bb xxxx - Load Sprite graphics page (64 tiles) to $8B00 in VRAM.+   - ''B2 bb xxxx'' - Load Sprite graphics page (64 tiles) to $8B00 in VRAM. 
 + 
 +Note that these opcodes update the variables that keep track of what tilesets to use when loading a save.
  
 Operators: Operators:
Line 235: Line 267:
 The game does not account for operators in the form of E* or F*. Using these will cause the game to freeze, because the interpreter will get stuck in an infinite loop. However, an intrepid hacker could use these to extend this language to do other radical things. The game does not account for operators in the form of E* or F*. Using these will cause the game to freeze, because the interpreter will get stuck in an infinite loop. However, an intrepid hacker could use these to extend this language to do other radical things.
  
-===== Example 1 =====+===== Shortcomings =====
  
-This the transition from the save room in the first ruins to the exterior area:+Each screen can only have one transition assigned to it, meaning that if (for example) you need the left and right exits of a room to lead to different areas, then the room needs to be at least 2 screens wide (this limitation becomes very apparent when examining the original game's map design).
  
-<code>A0 B1 08 BC 69 26 36 19 B2 06 20 5D C5 49 E7 FF</code>+Also, the only conditional operator that exists is for the metroid count. Checking any other byte of the save data (such as if a particular enemy or item has been collected) is unsupported.
  
-Let's make this easier to read:+With the disassembly, however, both of these limitations could be overcome relatively trivially.
  
-<code> +===== Usage =====
-A0 +
-B1 08 BC 69  +
-26  +
-36  +
-19  +
-B2 06 20 5D  +
-C5  +
-49 E7  +
-FF +
-</code>+
  
-Hypothetically, we could convert this into some sort of mnemonic or macro-based form (like assembly):+Transition scripts can be edited in one of two ways:
  
-<code> +1) Using the transition editor in LAMP.
-FADE +
-GFX_BG    08:69BC  +
-COLLISION 6  +
-SOLID     6  +
-METATILE  9  +
-GFX_SPR   06:5D20  +
-SONG      5  +
-WARP      9,E,7  +
-END +
-</code>+
  
-But that would be just silly.+2) Editing [[https://github.com/alex-west/M2RoS/blob/main/SRC/maps/doors.asm|doors.asm]] in the disassembly, using the macros included in [[https://github.com/alex-west/M2RoS/blob/main/SRC/maps/door%20macros.asm|door_macros.asm]].
  
-(Someone please do this.)+For reference, the macros the disassembly uses are as follows:
  
-===== Example 2 =====+^ Opcode ^ Macro ^ 
 +| 00 bb ssss dddd llll | COPY_DATA | 
 +| 01 bb ssss dddd llll | COPY_BG | 
 +| 02 bb ssss dddd llll | COPY_SPR | 
 +| 1x | TILETABLE | 
 +| 2x | COLLISION | 
 +| 3x | SOLIDITY | 
 +| 4b yx | WARP | 
 +| 50 | ESCAPE_QUEEN | 
 +| 60 xx yy | DAMAGE | 
 +| 70 | EXIT_QUEEN | 
 +| 8a bbbb cccc dddd eeee | ENTER_QUEEN | 
 +| 90 nn xxxx | IF_MET_LESS | 
 +| A0 | FADEOUT | 
 +| B1 bb xxxx | LOAD_BG | 
 +| B1 bb xxxx | LOAD_SPR | 
 +| Cx | SONG | 
 +| Dx | ITEM | 
 +| FF | END_DOOR |
  
-Here's the transition to the first cave with acid.+==== Example ====
  
-<code>A0 B1 07 00 68 25 35 B2 06 20 61 4B 0C 90 46 E1 01 18 FF</code>+This the transition from the save room in the first ruins to the exterior area: 
 + 
 +<code>A0 B1 08 BC 69 26 36 19 B2 06 20 5D C5 49 E7 FF</code>
  
-For reference, this is the transition script referred to in the conditional operator it uses.+Editing this by hand would by tedious and error-prone. However, with the disassembly it becomes fairly rudimentary:
  
-<code>16 FF</code>+<code>door10C: 
 +    FADEOUT 
 +    LOAD_BG gfx_ruinsExt 
 +    COLLISION $6 
 +    SOLIDITY $6 
 +    TILETABLE $9 
 +    LOAD_SPR gfx_enemiesB 
 +    SONG $5 
 +    WARP $9, $E7 
 +    END_DOOR</code>
  
-Deciphering this will be left as an exercise for the reader.+Notice how this is largely human-readable, and how one can use the //label names// for the graphics locations in the ROM, rather than hardcoded offsets.
return_of_samus/technical_information/screen_transitions.txt · Last modified: 2023/07/02 17:36 by rt-55j

Page Tools

Top

JP Wiki Metroid DB M2K2 AM2R