# 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:

Return to main page