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 257 + (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 !retry_ram_name.

At the end of the file you'll also find the !amk_freeram define that's used to interact with AddmusicK. The default value is the same as what's used in AddmusicK by default, so you'll only need to change it if you also changed it in the tool.

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 ram.asm file inside the patch/block/sprite folder, then add this line to the patch/block/sprite asm file:

  incsrc "ram.asm"
  

  Then you'll be able to reference them with the !retry_ram_<name> defines.

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. Note that the high bit in each byte is used as a flag to fix an error in the timer drawing during respawning, so you should do AND #$0F when reading the timer digits from these addresses.
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 ORAd 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.
gm_backup	$0F	$01	Internal	Contains a backup of the current gamemode ($0100), so that the main and end labels can run properly on the frame the gamemode is changed.
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 by Retry at startup 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 by Retry at startup, meaning that its effect will last until you set it back to $00 yourself.
disable_prompt_exit	$12	$01	User	If set to a value other than $00, the Retry prompt won't show the second option (EXIT). Retry sets it to !disable_exit_option from settings_global.asm at startup, 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. Normally the address contains $FFFF, which indicates it's not triggering anything, but you can change it in 3 ways: If the low byte is set to $80, and you don't change the high byte, then the current level's checkpoint will be reset to the main level's entrance, effectively erasing the current checkpoint. If the low byte is set to any value other than $FF and $80 (for example, $00), and 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.
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 by Retry at startup (to the !prompt_box_text_x_pos/!prompt_bar_text_x_pos value in settings_global.asm, depending on !prompt_type). Changing this at runtime while having the prompt black background enabled is not recommended, as the black box/bar is fixed in place regardless of this position.
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 by Retry at startup (to the !prompt_box_text_y_pos/!prompt_bar_text_y_pos value in settings_global.asm, depending on !prompt_type). Changing this at runtime while having the prompt black background enabled is not recommended, as the black box/bar is fixed in place regardless of this position.
disable_prompt_bg	$17	$01	User	If set, the Retry prompt's black background will be disabled. Retry sets to !no_prompt_bg from settings_global.asm at startup, 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 the Local Settings - %checkpoint command with value between 2 and 7) 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 by Retry at startup, 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). Additionally bits 1 and 2 of $PT are used to prevent coins and dragon coins respectively from being drawn (if you just want either of those but not both). 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.
status_bar_death_tile	$27	$02	User	Current sprite status bar death counter tile number and palette. Format: $PTTT (P = palette, TTT = tile number). See API - Configure sprite status bar for details.
status_bar_force_upload	$29	$01	Internal	Flag that forces all visible elements of the status bar to be uploaded freshly in the sprite GFX (for 1 frame, it is reset after being used in NMI). Normally elements are only uploaded when changed (e.g. the frame when the timer ticks down) to not waste NMI time, but sometimes it is necessary to be uploaded regardless: on level load and when the status bar element got unhidden during the level. You can set it yourself, if writing to the other RAM addresses manually, but normally you should just use the API routines which handles this for you (see API - Configure sprite status bar and API - Hide sprite status bar for details).
canary	$2A	$02	Internal	Contains a fixed value and it is used to detect invalid game states (like if loading a bogus save state or if the memory gets corrupted). If the value is not the expected one, an error message will show in game when loading a level. You should never write to it unless you want to force the error message (which is basically a hardlock).
reserved	$2C	$0F	Internal	Unused, but reserved for future expansion. Usage as freeram is not recommended.
death_counter	$3B	$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	$40	$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	$100	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).