Modding API ‐ Events

Event Reference

Timing Events

Initialization

• Function: recomp_on_init()
• Versions: 1.0.0+
• Description: Runs right after the red Nintendo logo has shown, and only once per session. Note: If you want to modify overlays, do not place the modification code here.

Every Frame

• Function: dk64recomp_every_frame()
• Versions: 1.0.0+
• Description: Runs every frame before the game's logic has taken place for that frame.

---

Asset Events

Music Load

• Function: recomp_on_music_bin_load(s32 song, s32 bank, u8 *bin)
• Versions: 1.0.0+
• Description: Runs upon the vanilla binary file being loaded into the storage slot in RDRAM. To modify the binary file in storage, your hook into this event will need to modify D_global_asm_8076BF38[], where the index is the value of bank. DK64 has 4 banks for songs/musical jingles, with decreasing sizes as the indexes go up.

---

Load File Events

File Start

• Function: recomp_on_file_start()
• Versions: 1.0.0+
• Description: Runs whenever a file is booted up, regardless of the state of the file.

New File Start

• Function: recomp_on_new_file_start()
• Versions: 1.0.0+
• Description: Similar to the above, but only runs when a new file is created.

Dirty File Start

• Function: recomp_on_dirty_file_start()
• Versions: 1.0.0+
• Description: Similar to the above, but only runs when a file with existing data is loaded.

---

Flag Events

Flag Check

• Function: recomp_on_flag_check(s16 *flag, u8 *flag_type)
• Versions: 1.0.0+
• Description: Runs whenever the game checks a certain file's flag before it reads the file data, allowing you to mutate the flag index.
  • Flag Types:
    • 0 = Permanent flags
    • 1 = Temporary flags
    • 2 = Global flags
• Useful hacks
  • To always return false, run *flag = -1
  • To always return true, run *flag = 0x17A
    • This checks the checked flag to the waterfall cutscene flag that you get upon file init, which is generally always set no matter what with a file.

Flag Set/Clear

• Function: recomp_on_flag_change(s16 *flag, u8 *target_state, u8 *flag_type)
• Versions: 1.0.0+
• Description: Runs whenever a flag's state is changed (typically setting a flag, but can also be used to clear one).
  • Target State: 1 (set) or 0 (clear)
  • Flag Types:
    • 0 = Permanent flags
    • 1 = Temporary flags
    • 2 = Global flags