Retry RAM Map

This documents serves as a detailed reference on the purpose of the RAM addresses used by Retry, and how you can use them.

Overview

Retry uses a chunk of RAM at $7FB400 ($40A400 on SA-1 roms) by default. The size of this area is 241 + (4*!max_custom_midway_num) bytes (where !max_custom_midway_num is defined in settings.asm).

The default address should be fine in most cases, but if you want to change it because of some freeram conflict, open ram.asm and edit !retry_freeram (!retry_freeram_sa1 if you're using SA-1).

In the ram.asm file you can also see the name for the different addresses, defined as %retry_ram(name,$XX), where $XX specifies the offset from the base !retry_freeram address. The full address name is resolved to !ram_name and !ram_retry_name.

Usage

If you need to perform read/write operations on the Retry RAM addresses, you can do as follows:

For UberASM codes, the addresses can be referenced simply using the label retry_ram_name for a specific address name. For example, if you want to check if the player is respawning, you can do: LDA retry_ram_is_respawning : BNE respawning.
For all other codes, you'll need to copy the contents of the ram.asm file inside your patch/sprite/block file, then you can reference them either with the !retry_ram_name defines or the retry_ram_name label. If you need them for sprites, it's suggested to copy the contents inside PIXI's sa1def.asm file, and in case of blocks to copy them inside GPS's defines.asm. This way the addresses will be available in all sprites/blocks without having to copy them multiple times.

RAM information

Here is the table containing information about all addresses used by Retry, including their name and size.

Addresses that are labeled as "Internal" are used internally by Retry and shouldn't be written to outside of it (although you can read them to know the state of some of Retry's operations, such as the respawning example earlier). Addresses that are labeled as "User" are meant to be written by the user to enable or customize some of Retry's features.

Note that the first 13 bytes ($00-$0B) are laid out exactly as the original Retry patch (and have the same function), to keep compatibility with resources that used them or that expect them to be arranged in a certain way. For this reason it's recommended not to change them.

Name	Offset	Size	Purpose	Description
`timer`	`$00`	`$03`	Internal	Used to hold the level's initial timer value, to reset it to the correct value when respawning. You can read it at any time during a level to know what the initial timer was.
`respawn`	`$03`	`$02`	Internal	Destination value to go to when respawning. This value is written on level load depending on the current checkpoint and used when Retrying. You can see the format at `$7E19B8` (low byte) and `$7E19D8` (high byte) in the SMWCentral RAM Map. Note that the high byte is always `ORA`d with `$04` (i.e. it always uses the Lunar Magic entrance system rather than vanilla). Additionally, if the destination is a level's main entrance and the highest bit is set, then the entrance will act as a Yoshi Wings sublevel.
`is_respawning`	`$05`	`$01`	Internal	Flag set when a level is being reloaded by Retry after dying. It can be used to check if a room is being loaded by Retry or it's just a normal level entrance/transition.
`music_to_play`	`$06`	`$01`	Internal	Music number that has to be played after respawn. Only used when AddmusicK is patched. If `$FF`, the song's samples will be reloaded.
`hurry_up`	`$07`	`$01`	Internal	Flag set when the timer drops under 99 seconds and the music speeds up. When set, the death song will be played when dying even if it shouldn't, to reset the level's song's tempo.
`door_dest`	`$08`	`$02`	Internal	It holds the destination value for the current entrance, set when going to a sublevel via a door/pipe/etc. It's used to set the checkpoint to the current entrance when using the `$02` or `$03` option in the checkpoint table. It uses the same format as `respawn`.
`music_backup`	`$0A`	`$01`	Internal	Holds the song number that was playing right before playing the death song. It's copied to `$0DDA` when dying, which prevents the samples to be reloaded if the same song is played again afterwards (for AddmusicK).
`update_request`	`$0B`	`$01`	Internal	Flag set when dying if the Retry prompt is active. It makes the NMI handler upload the prompt letters to VRAM. It's set to `$00` right after. You can set this mid-level if you need the letters GFX to be loaded for some reason.
`prompt_phase`	`$0C`	`$01`	Internal	Holds the value for the current phase of the Retry prompt box. The values go as follows: $00: Retry prompt is off. $01: box is expanding. $02: box fully expanded, options are shown. $03: box is shrinking after `RETRY` was selected. $04: box finished shrinking after `RETRY` was selected. $05: box is shrinking after `EXIT` was selected. $06: box finished shrinking after `EXIT` was selected.
`update_window`	`$0D`	`$01`	Internal	The high bit is set during the Retry prompt handling to make the window change shape to properly show the options. Needed to avoid occasional flickering when updating it on the same frame it finished expanding. Additionally used as a timer (`$00-$7F`) when the Retry prompt opens to disable pressing up/down to move the cursor (as specified by `!prompt_cooldown` in `settings.asm`).
`is_dying`	`$0E`	`$01`	Internal	Flag set when Mario dies. It's used for a few processes that happen when Mario dies. Format: `srr----d` `s`: when not set but the `d` bit is set, the death sfx is played and this bit is set. This ensures the sfx is only played once. `rr`: when set to `10`, the current level is reloaded by switching to gamemode `$0F`. When set to `11`, the title screen is reloaded by switching to gamemode `$02`. `d`: when not set, if Mario is in the death animation, a few one-shot death activities are performed (e.g. increasing the death counter), then the bit is set. This ensures that those activites are not repeated. `-`: currently unused.
`9D_backup`	`$0F`	`$01`	Internal	Holds a backup of the `$9D` value when going through a normal transition, which is then restored when respawning. This is used when `!pipe_entrance_freeze = 2` in `settings.asm`.
`midway_powerup`	`$10`	`$01`	User	This can be used to override the `!midway_powerup` setting in certain situations. If this is `$00`, then midways won't give a mushroom, otherwise they will. This is only initialized on the title screen based on the `!midway_powerup` setting, but you can change it at any time. Just remember that you'll need to change it back to the default value yourself if needed.
`prompt_override`	`$11`	`$01`	User	This can be used to override the Retry settings of the current level or all levels depending on some condition (for example, if you want to let the player choose if to have instant Retry or not). It follows the same format as the `%retry` setting in settings_local.asm (see Local Settings - %retry for details). If this is set to `$00`, the value in the local settings will be used instead, or the default value in settings_global.asm if there's no local setting for the current sublevel. It's only reset on title screen load, meaning that its effect will last until you set it back to `$00` yourself.
`disable_exit`	`$12`	`$01`	User	If set to a value other than `$00`, the Retry prompt won't show the `EXIT` option. It's set to `!disable_exit_option` from `settings.asm` on title screen load, but you can also change it at any time to remove the option in certain situations. Remember that you'll need to change it back to the default value yourself if needed.
`set_checkpoint`	`$13`	`$02`	User	This address functions as a simple way to set the checkpoint for the current level to a certain entrance, without having to worry about all the internal Retry mechanism that makes it work. It's mainly used by the vanilla/custom midway objects, but you can also write to it yourself if you're making your own midways or you need to change the checkpoint dynamically. It can be used in 3 ways: If the low byte is set to any value other than `$FF` and `$80` (for example, `$00`), but you don't change the high byte, then a checkpoint will be triggered depending on this level's `checkpoint_effect` table settings. This would be the preferred way to use it if making a custom midway block/sprite. If the whole 16-bit value is set to an entrance value, following the format of `$7E19B8` and `$7E19D8`, then a checkpoint will be set using this entrance as the respawn destination. This can be used to have custom checkpoints that use any main/midway/secondary entrance as destination, similarly to Retry's custom midway objects. If the low byte is set to `$80`, then the current level's checkpoint will be reset to the main level's entrance, effectively erasing the current checkpoint. In this case the high byte is ignored.
`prompt_x_pos`	`$15`	`$01`	User	Holds the X position at which the Retry prompt should appear at. You can write to it at any time. Note that this address is only reset on title screen load to the `!text_x_pos` value in `settings.asm`.
`prompt_y_pos`	`$16`	`$01`	User	Holds the Y position at which the Retry prompt should appear at. You can write to it at any time. Note that this address is only reset on title screen load to the `!text_y_pos` value in `settings.asm`.
`disable_box`	`$17`	`$01`	User	If set, the Retry prompt's black box will be disabled. It's set to `!no_prompt_box` from `settings.asm` on title screen load, but you can also change it at any time. Suggested to be set if also changing `prompt_x_pos` and `prompt_y_pos` during gameplay.
`play_sfx`	`$18`	`$01`	Internal	Bitwise mask set on level load for different purposes. Format: `e------s`. `e`: set if using the `%sfx_echo` setting in settings_local.asm for the current sublevel (see Local Settings - %sfx_echo. Used to send the SFX echo command during level main. You can also set this manually in level init to enable SFX echo. `s`: Set if `!room_cp_sfx` is not `$00` and the current sublevel gives a room entrance checkpoint (unless using the `%no_room_cp_sfx` setting in settings_local.asm, see Local Settings - %no_room_cp_sfx for details). Used to play the midway SFX during level init. `-`: currently unused.
`midways_override`	`$19`	`$01`	User	This can be used to prevents midways and/or checkpoints from functioning. Changing this will take effect on the next level load. Possible values to use are as follows: `$01`: all future midway objects (both vanilla and Retry's custom objects) won't spawn. `$80`: all future automatic room checkpoints (i.e. checkpoints enabled by using `%checkpoint(xxx,2)` or `%checkpoint(xxx,3)` in settings_local.asm) won't activate. `$81`: enables the effect of both `$01` and `$80` (all midways and checkpoints won't work). Note that this is only reset on the title screen, so it's up to you to set it back to `$00` when needed.
`coin_backup`	`$1A`	`$01`	Internal	Keeps track of the last frame's coins value to check if it changed, to only upload the coin counter's sprite digits when necessary. Not used if `!sprite_status_bar = 0` in `settings.asm`.
`lives_backup`	`$1B`	`$01`	Internal	Keeps track of the last frame's lives values to check if it changed, to only upload the lives counter's sprite digits when necessary. Not used if `!sprite_status_bar = 0` in `settings.asm`.
`bonus_stars_backup`	`$1C`	`$01`	Internal	Keeps track of the last frame's bonus stars value to check if it changed, to only upload the bonus stars counter's sprite digits when necessary. Not used if `!sprite_status_bar = 0` in `settings.asm`.
`status_bar_item_box_tile`	`$1D`	`$02`	User	Current sprite status bar item box tile number and palette. Format: `$PTTT` (`P` = palette, `TTT` = tile number). See API - Configure sprite status bar for details.
`status_bar_timer_tile`	`$1F`	`$02`	User	Current sprite status bar timer tile number and palette. Format: `$PTTT` (`P` = palette, `TTT` = tile number). See API - Configure sprite status bar for details.
`status_bar_coins_tile`	`$21`	`$02`	User	Current sprite status bar coin counter tile number and palette. Format: `$PTTT` (`P` = palette, `TTT` = tile number). See API - Configure sprite status bar for details.
`status_bar_lives_tile`	`$23`	`$02`	User	Current sprite status bar lives counter tile number and palette. Format: `$PTTT` (`P` = palette, `TTT` = tile number). See API - Configure sprite status bar for details.
`status_bar_bonus_stars_tile`	`$25`	`$02`	User	Current sprite status bar bonus stars counter tile number and palette. Format: `$PTTT` (`P` = palette, `TTT` = tile number). See API - Configure sprite status bar for details.
`reserved`	`$27`	`$04`	Internal	Unused, but reserved for future expansion. Usage as freeram is not recommended.
`death_counter`	`$2B`	`$05`	Internal	Holds the amount of deaths occurred. Each byte holds the value of a digit in the counter (from left to right). Saved to SRAM/BW-RAM by default (if `!sram_feature = 1` in `settings.asm`).
`checkpoint`	`$30`	`$C0`	Internal	Checkpoint data for each level (2 bytes per level). Holds the destination value of the latest checkpoint obtained in each level (using the same format as `respawn`). Note that entry `0` (the first 2 bytes) hold the checkpoint value for the intro level, but it won't be used after the intro. Saved to SRAM/BW-RAM by default (if `!sram_feature = 1` in `settings.asm`).
`cust_obj_data`	`$F0`	Var.	Internal	Data for all the possible custom midway objects loaded in the current level, plus a counter for how many custom midways are in the level (used to prevent additional midways from spawning if reaching the `!max_custom_midway_num` value from `settings.asm`). Each midway uses 4 bytes, so this uses `(4*!max_custom_midway_num)+1` bytes. For each object, there's a 2 bytes identifier (based on its index in the level's map16 data) and the destination value that this midway will set when grabbed (based on the object's extension).

Return to main page