From f880e6c5699389ad214f6d0fc2bfadbd243c4974 Mon Sep 17 00:00:00 2001
From: Agent X <44549182+AgentXLP@users.noreply.github.com>
Date: Tue, 31 Dec 2024 19:39:36 -0500
Subject: [PATCH] Document level_update.h and add new instant warp function
 (70.1%)

---
 autogen/convert_functions.py          |  2 +-
 autogen/lua_definitions/functions.lua | 14 +++++++++
 docs/lua/functions-3.md               | 44 +++++++++++++++++++++++++++
 docs/lua/functions.md                 |  1 +
 src/game/level_update.c               | 12 ++++++--
 src/game/level_update.h               | 12 +++++++-
 src/pc/lua/smlua_functions_autogen.c  | 18 +++++++++++
 7 files changed, 99 insertions(+), 4 deletions(-)

diff --git a/autogen/convert_functions.py b/autogen/convert_functions.py
index 69771d770..63bb597db 100644
--- a/autogen/convert_functions.py
+++ b/autogen/convert_functions.py
@@ -84,7 +84,7 @@ override_allowed_functions = {
     "src/game/object_list_processor.h":     [ "set_object_respawn_info_bits" ],
     "src/game/mario_misc.h":                [ "bhv_toad.*", "bhv_unlock_door.*", "geo_get_.*_state" ],
     "src/pc/utils/misc.h":                  [ "update_all_mario_stars" ],
-    "src/game/level_update.h":              [ "level_trigger_warp", "get_painting_warp_node", "initiate_painting_warp", "warp_special", "lvl_set_current_level", "level_control_timer_running", "fade_into_special_warp" ],
+    "src/game/level_update.h":              [ "level_trigger_warp", "get_painting_warp_node", "initiate_painting_warp", "warp_special", "lvl_set_current_level", "level_control_timer_running", "fade_into_special_warp", "get_instant_warp" ],
     "src/game/area.h":                      [ "area_get_warp_node" ],
     "src/engine/level_script.h":            [ "area_create_warp_node" ],
     "src/game/ingame_menu.h":               [ "set_min_dialog_width", "set_dialog_override_pos", "reset_dialog_override_pos", "set_dialog_override_color", "reset_dialog_override_color", "set_menu_mode", "create_dialog_box", "create_dialog_box_with_var", "create_dialog_inverted_box", "create_dialog_box_with_response", "reset_dialog_render_state", "close_dialog_box", ],
diff --git a/autogen/lua_definitions/functions.lua b/autogen/lua_definitions/functions.lua
index 1d613c0bc..bf3186ecd 100644
--- a/autogen/lua_definitions/functions.lua
+++ b/autogen/lua_definitions/functions.lua
@@ -4764,21 +4764,32 @@ end
 
 --- @param arg integer
 --- @param color integer
+--- Fades into a special warp with `arg` and using `color`
 function fade_into_special_warp(arg, color)
     -- ...
 end
 
+--- @param index integer
+--- @return InstantWarp
+--- Gets an instant warp from the current area's instant warp array (0-3)
+function get_instant_warp(index)
+    -- ...
+end
+
 --- @return WarpNode
+--- Gets a painting warp node from the local mario's floor type
 function get_painting_warp_node()
     -- ...
 end
 
 --- @param paintingIndex integer
+--- Initiates a painting warp of `paintingIndex`
 function initiate_painting_warp(paintingIndex)
     -- ...
 end
 
 --- @return integer
+--- Returns if the level timer is running
 function level_control_timer_running()
     -- ...
 end
@@ -4786,6 +4797,7 @@ end
 --- @param m MarioState
 --- @param warpOp integer
 --- @return integer
+--- Triggers a warp (WARP_OP_*) for the level. Pass in `gMarioStates[0]` for `m`
 function level_trigger_warp(m, warpOp)
     -- ...
 end
@@ -4793,11 +4805,13 @@ end
 --- @param arg0 integer
 --- @param levelNum integer
 --- @return integer
+--- Sets the level number and handles the act select screen
 function lvl_set_current_level(arg0, levelNum)
     -- ...
 end
 
 --- @param arg integer
+--- Special warps to arg (`SPECIAL_WARP_*`)
 function warp_special(arg)
     -- ...
 end
diff --git a/docs/lua/functions-3.md b/docs/lua/functions-3.md
index e27015918..9cf764130 100644
--- a/docs/lua/functions-3.md
+++ b/docs/lua/functions-3.md
@@ -6045,6 +6045,9 @@ Creates a warp node in the current level and area with id `id` that goes to the
 
 ## [fade_into_special_warp](#fade_into_special_warp)
 
+### Description
+Fades into a special warp with `arg` and using `color`
+
 ### Lua Example
 `fade_into_special_warp(arg, color)`
 
@@ -6064,8 +6067,34 @@ Creates a warp node in the current level and area with id `id` that goes to the
 
 <br />
 
+## [get_instant_warp](#get_instant_warp)
+
+### Description
+Gets an instant warp from the current area's instant warp array (0-3)
+
+### Lua Example
+`local InstantWarpValue = get_instant_warp(index)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| index | `integer` |
+
+### Returns
+[InstantWarp](structs.md#InstantWarp)
+
+### C Prototype
+`struct InstantWarp *get_instant_warp(u8 index);`
+
+[:arrow_up_small:](#)
+
+<br />
+
 ## [get_painting_warp_node](#get_painting_warp_node)
 
+### Description
+Gets a painting warp node from the local mario's floor type
+
 ### Lua Example
 `local WarpNodeValue = get_painting_warp_node()`
 
@@ -6084,6 +6113,9 @@ Creates a warp node in the current level and area with id `id` that goes to the
 
 ## [initiate_painting_warp](#initiate_painting_warp)
 
+### Description
+Initiates a painting warp of `paintingIndex`
+
 ### Lua Example
 `initiate_painting_warp(paintingIndex)`
 
@@ -6104,6 +6136,9 @@ Creates a warp node in the current level and area with id `id` that goes to the
 
 ## [level_control_timer_running](#level_control_timer_running)
 
+### Description
+Returns if the level timer is running
+
 ### Lua Example
 `local integerValue = level_control_timer_running()`
 
@@ -6122,6 +6157,9 @@ Creates a warp node in the current level and area with id `id` that goes to the
 
 ## [level_trigger_warp](#level_trigger_warp)
 
+### Description
+Triggers a warp (WARP_OP_*) for the level. Pass in `gMarioStates[0]` for `m`
+
 ### Lua Example
 `local integerValue = level_trigger_warp(m, warpOp)`
 
@@ -6143,6 +6181,9 @@ Creates a warp node in the current level and area with id `id` that goes to the
 
 ## [lvl_set_current_level](#lvl_set_current_level)
 
+### Description
+Sets the level number and handles the act select screen
+
 ### Lua Example
 `local integerValue = lvl_set_current_level(arg0, levelNum)`
 
@@ -6164,6 +6205,9 @@ Creates a warp node in the current level and area with id `id` that goes to the
 
 ## [warp_special](#warp_special)
 
+### Description
+Special warps to arg (`SPECIAL_WARP_*`)
+
 ### Lua Example
 `warp_special(arg)`
 
diff --git a/docs/lua/functions.md b/docs/lua/functions.md
index 0dea8f455..8002203a4 100644
--- a/docs/lua/functions.md
+++ b/docs/lua/functions.md
@@ -933,6 +933,7 @@
 
 - level_update.h
    - [fade_into_special_warp](functions-3.md#fade_into_special_warp)
+   - [get_instant_warp](functions-3.md#get_instant_warp)
    - [get_painting_warp_node](functions-3.md#get_painting_warp_node)
    - [initiate_painting_warp](functions-3.md#initiate_painting_warp)
    - [level_control_timer_running](functions-3.md#level_control_timer_running)
diff --git a/src/game/level_update.c b/src/game/level_update.c
index 7bfb7d669..80fdf0a3f 100644
--- a/src/game/level_update.c
+++ b/src/game/level_update.c
@@ -634,6 +634,14 @@ void warp_credits(void) {
     }
 }
 
+struct InstantWarp *get_instant_warp(u8 index) {
+    if (index >= 4) { return NULL; }
+    if (!gCurrentArea) { return NULL; }
+    if (gCurrentArea->instantWarps == NULL) { return NULL; }
+
+    return &gCurrentArea->instantWarps[index];
+}
+
 void check_instant_warp(void) {
     if (!gCurrentArea) { return; }
     s16 cameraAngle;
@@ -747,7 +755,7 @@ s16 music_changed_through_warp(s16 arg) {
 /**
  * Set the current warp type and destination level/area/node.
  */
-void initiate_warp(s16 destLevel, s16 destArea, s16 destWarpNode, s32 arg3) {
+void initiate_warp(s16 destLevel, s16 destArea, s16 destWarpNode, s32 arg) {
     if (destWarpNode >= WARP_NODE_CREDITS_MIN) {
         sWarpDest.type = WARP_TYPE_CHANGE_LEVEL;
     } else if (destLevel != gCurrLevelNum) {
@@ -761,7 +769,7 @@ void initiate_warp(s16 destLevel, s16 destArea, s16 destWarpNode, s32 arg3) {
     sWarpDest.levelNum = destLevel;
     sWarpDest.areaIdx = destArea;
     sWarpDest.nodeId = destWarpNode;
-    sWarpDest.arg = arg3;
+    sWarpDest.arg = arg;
 }
 
 /**
diff --git a/src/game/level_update.h b/src/game/level_update.h
index 22856952a..0a869ff20 100644
--- a/src/game/level_update.h
+++ b/src/game/level_update.h
@@ -166,20 +166,30 @@ enum HUDDisplayFlag {
     HUD_DISPLAY_DEFAULT = HUD_DISPLAY_FLAG_LIVES | HUD_DISPLAY_FLAG_COIN_COUNT | HUD_DISPLAY_FLAG_STAR_COUNT | HUD_DISPLAY_FLAG_CAMERA_AND_POWER | HUD_DISPLAY_FLAG_CAMERA | HUD_DISPLAY_FLAG_POWER | HUD_DISPLAY_FLAG_KEYS | HUD_DISPLAY_FLAG_UNKNOWN_0020
 };
 
+/* |description|Returns if the level timer is running|descriptionEnd| */
 u8 level_control_timer_running(void);
 u16 level_control_timer(s32 timerOp);
+/* |description|Fades into a special warp with `arg` and using `color`|descriptionEnd| */
 void fade_into_special_warp(u32 arg, u32 color);
 void load_level_init_text(u32 arg);
 void warp_credits(void);
+/* |description|Gets an instant warp from the current area's instant warp array (0-3)|descriptionEnd| */
+struct InstantWarp *get_instant_warp(u8 index);
+/* |description|Gets a painting warp node from the local mario's floor type|descriptionEnd| */
 struct WarpNode *get_painting_warp_node(void);
+/* |description|Initiates a painting warp of `paintingIndex`|descriptionEnd| */
 void initiate_painting_warp(s16 paintingIndex);
+/* |description|Triggers a warp (WARP_OP_*) for the level. Pass in `gMarioStates[0]` for `m`|descriptionEnd| */
 s16 level_trigger_warp(struct MarioState *m, s32 warpOp);
 void level_set_transition(s16 length, void (*updateFunction)(s16 *));
+/* |description|Special warps to arg (`SPECIAL_WARP_*`)|descriptionEnd| */
 void warp_special(s32 arg);
-void initiate_warp(s16 destLevel, s16 destArea, s16 destWarpNode, s32 arg3);
+/* |description|Initiates a warp to `destLevel` in `destArea` at `destWarpNode` with `arg`. This function is unstable and it's generally recommended to use `warp_to_level` instead|descriptionEnd| */
+void initiate_warp(s16 destLevel, s16 destArea, s16 destWarpNode, s32 arg);
 
 s32 lvl_init_or_update(s16 initOrUpdate, UNUSED s32 unused);
 s32 lvl_init_from_save_file(UNUSED s16 arg0, s16 levelNum);
+/* |description|Sets the level number and handles the act select screen|descriptionEnd| */
 s32 lvl_set_current_level(s16 arg0, s16 levelNum);
 s32 lvl_play_the_end_screen_sound(UNUSED s16 arg0, UNUSED s32 arg1);
 void basic_update(UNUSED s16 *arg);
diff --git a/src/pc/lua/smlua_functions_autogen.c b/src/pc/lua/smlua_functions_autogen.c
index 940f44a7a..a46d64f67 100644
--- a/src/pc/lua/smlua_functions_autogen.c
+++ b/src/pc/lua/smlua_functions_autogen.c
@@ -14749,6 +14749,23 @@ int smlua_func_fade_into_special_warp(lua_State* L) {
     return 1;
 }
 
+int smlua_func_get_instant_warp(lua_State* L) {
+    if (L == NULL) { return 0; }
+
+    int top = lua_gettop(L);
+    if (top != 1) {
+        LOG_LUA_LINE("Improper param count for '%s': Expected %u, Received %u", "get_instant_warp", 1, top);
+        return 0;
+    }
+
+    u8 index = smlua_to_integer(L, 1);
+    if (!gSmLuaConvertSuccess) { LOG_LUA("Failed to convert parameter %u for function '%s'", 1, "get_instant_warp"); return 0; }
+
+    smlua_push_object(L, LOT_INSTANTWARP, get_instant_warp(index));
+
+    return 1;
+}
+
 int smlua_func_get_painting_warp_node(UNUSED lua_State* L) {
     if (L == NULL) { return 0; }
 
@@ -32838,6 +32855,7 @@ void smlua_bind_functions_autogen(void) {
 
     // level_update.h
     smlua_bind_function(L, "fade_into_special_warp", smlua_func_fade_into_special_warp);
+    smlua_bind_function(L, "get_instant_warp", smlua_func_get_instant_warp);
     smlua_bind_function(L, "get_painting_warp_node", smlua_func_get_painting_warp_node);
     smlua_bind_function(L, "initiate_painting_warp", smlua_func_initiate_painting_warp);
     smlua_bind_function(L, "level_control_timer_running", smlua_func_level_control_timer_running);