Retry API

"Retry API" refers to a collection of routines that Retry provides that you can call from your UberASM files if needed.

NOTE: calling these routines from files in the "library" folder will result in an error, at least when using the standard UberASMTool.

Index

• Respawn in level
• Save game
• Reset level checkpoint
• Reset all checkpoints
• Configure sprite status bar
• Get Retry type
• Get SRAM variable address

Respawn in level

JSL retry_api_respawn_in_level

Call this to make the player respawn in the current level at the last checkpoint. This has the same effect as dying and hitting Retry, or dying with instant Retry enabled, but skipping everything related to death (animation, music, prompt, etc.).

• Inputs: N/A
• Outputs: N/A
• Preconditions: A/X/Y 8 bits
• Postconditions: A/X/Y 8 bits

Save game

JSL retry_api_save_game

Call this to save the game, which will also save the addresses defined in the sram_tables.asm file.

• Inputs: N/A
• Outputs: N/A
• Preconditions: N/A
• Postconditions: A/X/Y 8 bits, DB/X/Y preserved

Reset level checkpoint

JSL retry_api_reset_level_checkpoint

Call this to reset the checkpoint in the current level. Entering the level again or respawning will load the main sublevel's entrance. Note that this won't reflect to SRAM until the game is saved.

• Inputs: N/A
• Outputs: N/A
• Preconditions: A/X/Y 8 bits
• Postconditions: A/X/Y 8 bits, DB/X/Y preserved

Reset all checkpoints

JSL retry_api_reset_all_checkpoints

Call this to reset the checkpoint for every level in the game, effectively making it as if it were a fresh game. Note that this won't reflect to SRAM until the game is saved.

• Inputs: N/A
• Outputs: N/A
• Preconditions: N/A
• Postconditions: A/X/Y size preserved, DB/X/Y preserved

Configure sprite status bar

NOTE: this routine has no effect unless !sprite_status_bar = 1 in settings_global.asm.

Call this in UberASM level init code to configure graphics for the sprite status bar items (item box, timer, coin counter, lives counter, bonus stars counter) for a specific level. Calling this will override the default settings found in settings_global.asm, in case you want to hide some or all of the elements in some level or if you need to change their tile or palette.

Each item's configuration is set with a 16 bit value $PTTT. The first digit P will be the item's palette, starting from palette 8 with P = 8 and ending with palette F with P = F. TTT will determine the tile number: you can see this in Lunar Magic's "8x8 Tile Editor" if you hover over the desired tile (more specifically, the upper left 8x8 tile of the 16x16 tile you want to use). In the bottom bar you'll see "Tile 0xYYY": then, TTT = YYY - $400. For example, the Smiling Coin tile is "Tile 0x4C2", which results in TTT = $4C2 - $400 = $0C2. So, for example, to reserve that tile and use palette F, the full value will be $F0C2.

If an item's value is $0000, the item will simply not be displayed.

Note that you can also just write the $PTTT value to the RAM address for a specific item yourself, this routine is just a shorthand so set all values at the same time. To see the RAM addresses names, see RAM Info.

• Inputs: each item's $PTTT value is specified, in order, after the JSL (see example)
• Outputs: N/A
• Preconditions: A/X/Y 16 bits
• Postconditions: A/X/Y size preserved, DB/X/Y preserved
• Usage (example):

      JSL retry_api_configure_sprite_status_bar
      dw $B080 ; Item box: palette B, tile 0x80
      dw $8088 ; Timer: palette 8, tile 0x88
      dw $80C2 ; Coin counter: palette 8, tile 0xC2
      dw $904E ; Lives counter: palette 9, tile 0x4E
      dw $90CE ; Bonus stars counter: palette 9, tile 0xCE
      ... <- your code will continue here after the JSL
  

Get Retry type

Routine to get the current Retry type, i.e. if currently the level is set to have Retry prompt, instant Retry or no Retry.

• Inputs: N/A
• Outputs: A = Retry type
  This value can have one of the following values:
  • $01: Retry prompt enabled & play the vanilla death song when the player dies
  • $02: Retry prompt enabled & play only the death sfx when the player dies
  • $03: instant Retry enabled
  • $04: Retry disabled
• Preconditions: A 8 bits
• Postconditions: A/X/Y size preserved, DB/X/Y preserved
• Usage: JSL retry_api_get_retry_type

Get SRAM variable address

Routine to get the address in SRAM for a specific variable. By "variable" it's meant any of the RAM addresses that are saved to SRAM specified in the sram save table. The returned address will be coherent with the current save file loaded when this routine is called (so, make sure to not call it before a save file is loaded!).

This could be useful to read/write values in SRAM directly, for example if you need to update some SRAM value without the game being saved.

Note that if you call this on the title screen (for example, if you need to display something based on some value saved in the three files), you will need to set $010A to the value of the save file you want to check (0 for save file 1, 1 for save file 2, 2 for save file 3) before calling this.

NOTE: this will always return "variable not found" if !sram_feature = 0.

• Inputs: N/A
• Outputs:
  • Carry set = variable not found
  • Carry clear = variable found -> SRAM address stored in $00-$02. In this case the value in SRAM can be accessed indirectly with the LDA/STA [$00] and LDA/STA [$00],y instructions.
• Preconditions: N/A
• Postconditions: A/X/Y 8 bit and clobbered, DB preserved
• Usage (example):

  	JSL retry_api_get_sram_variable_address
  	dl retry_ram_death_counter ; Variable to search for
  	BCS not_found
  found:
  	LDY #$01
  	LDA #$09
  	STA [$00],y ; Set second death counter digit in SRAM to 9
  not_found: