From 5fd55ffac1db3ebdd63a76014755491101444e64 Mon Sep 17 00:00:00 2001
From: Cooliokid956 <68075390+Cooliokid956@users.noreply.github.com>
Date: Wed, 29 Oct 2025 12:41:27 -0500
Subject: [PATCH] djui_hud_is_mouse_locked() (#986)

* djui_hud_get_mouse_locked()

Adds a total of 1 function:
# `bool djui_hud_get_mouse_locked()`
Returns the DJUI mouse lock status

Tip: This won't return the true state of mouse lock, so make sure to use `get_first_person_enabled()` and `camera_config_is_mouse_look_enabled()` as well

---
This also fills in some descriptions left out by Isaac in his viewport/scissor functions

* djui_hud_is_mouse_locked()

Same as before but is

* this is better imo
---
 autogen/lua_definitions/functions.lua | 26 +++++++++++++---------
 docs/lua/functions-3.md               | 31 ++++++++++++++++++++++-----
 docs/lua/functions-4.md               |  4 ++--
 docs/lua/functions-6.md               |  6 +++---
 docs/lua/functions.md                 |  1 +
 src/audio/seqplayer.h                 |  6 +++---
 src/game/mario_step.h                 |  4 ++--
 src/pc/djui/djui_hud_utils.c          |  6 +++++-
 src/pc/djui/djui_hud_utils.h          | 14 ++++++------
 src/pc/lua/smlua_functions_autogen.c  | 16 ++++++++++++++
 10 files changed, 82 insertions(+), 32 deletions(-)

diff --git a/autogen/lua_definitions/functions.lua b/autogen/lua_definitions/functions.lua
index 3ba796772..40b6f9855 100644
--- a/autogen/lua_definitions/functions.lua
+++ b/autogen/lua_definitions/functions.lua
@@ -3914,8 +3914,14 @@ function djui_hud_get_raw_mouse_y()
     -- ...
 end
 
+--- @return boolean
+--- Checks if the cursor is locked to the window
+function djui_hud_is_mouse_locked()
+    -- ...
+end
+
 --- @param locked boolean
---- Sets if the cursor is hidden and constrainted to the window
+--- Locks (or unlocks) the cursor to the window
 function djui_hud_set_mouse_locked(locked)
     -- ...
 end
@@ -3954,12 +3960,12 @@ end
 --- @param y number
 --- @param width number
 --- @param height number
---- Sets the viewport to the specified position and size, this will resize
+--- Sets the viewport to the specified position and size, this will resize any subsequent DJUI graphics
 function djui_hud_set_viewport(x, y, width, height)
     -- ...
 end
 
---- put the description here
+--- Resets the viewport to a fullscreen state
 function djui_hud_reset_viewport()
     -- ...
 end
@@ -3968,12 +3974,12 @@ end
 --- @param y number
 --- @param width number
 --- @param height number
---- put the description here
+--- Sets the scissor rectangle to the specified position and size, this will cut off any subsequent DJUI graphics not within the rectangle
 function djui_hud_set_scissor(x, y, width, height)
     -- ...
 end
 
---- put the description here
+--- Resets the scissor rectangle to a fullscreen state
 function djui_hud_reset_scissor()
     -- ...
 end
@@ -6443,14 +6449,14 @@ end
 
 --- @param m MarioState
 --- @return integer
---- Performs a full Mario stationary physics step (4 substeps) and returns an `GROUND_STEP_*` result
+--- Performs a full Mario stationary physics step (4 substeps) and returns a `GROUND_STEP_*` result
 function stationary_ground_step(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
---- Performs a full Mario ground physics step (4 substeps) and returns an `GROUND_STEP_*` result
+--- Performs a full Mario ground physics step (4 substeps) and returns a `GROUND_STEP_*` result
 function perform_ground_step(m)
     -- ...
 end
@@ -10029,7 +10035,7 @@ end
 
 --- @param player integer
 --- @return integer
---- Gets the tempo of `player`
+--- Gets the `tempo` of `player`
 function sequence_player_get_tempo(player)
     -- ...
 end
@@ -10043,7 +10049,7 @@ end
 
 --- @param player integer
 --- @return integer
---- Gets the tempoAcc (tempo accumulation) of `player`
+--- Gets the `tempoAcc` (tempo accumulation) of `player`
 function sequence_player_get_tempo_acc(player)
     -- ...
 end
@@ -10057,7 +10063,7 @@ end
 
 --- @param player integer
 --- @return integer
---- Gets the transposition (pitch) of `player`
+--- Gets the `transposition` (pitch) of `player`
 function sequence_player_get_transposition(player)
     -- ...
 end
diff --git a/docs/lua/functions-3.md b/docs/lua/functions-3.md
index 5754e7d88..cc6eb0c0f 100644
--- a/docs/lua/functions-3.md
+++ b/docs/lua/functions-3.md
@@ -3140,10 +3140,31 @@ Returns the y coordinate of the mouse relative to the screen
 
 <br />
 
+## [djui_hud_is_mouse_locked](#djui_hud_is_mouse_locked)
+
+### Description
+Checks if the cursor is locked to the window
+
+### Lua Example
+`local booleanValue = djui_hud_is_mouse_locked()`
+
+### Parameters
+- None
+
+### Returns
+- `boolean`
+
+### C Prototype
+`bool djui_hud_is_mouse_locked(void);`
+
+[:arrow_up_small:](#)
+
+<br />
+
 ## [djui_hud_set_mouse_locked](#djui_hud_set_mouse_locked)
 
 ### Description
-Sets if the cursor is hidden and constrainted to the window
+Locks (or unlocks) the cursor to the window
 
 ### Lua Example
 `djui_hud_set_mouse_locked(locked)`
@@ -3271,7 +3292,7 @@ Returns the amount scrolled vertically (-down/up+)
 ## [djui_hud_set_viewport](#djui_hud_set_viewport)
 
 ### Description
-Sets the viewport to the specified position and size, this will resize
+Sets the viewport to the specified position and size, this will resize any subsequent DJUI graphics
 
 ### Lua Example
 `djui_hud_set_viewport(x, y, width, height)`
@@ -3297,7 +3318,7 @@ Sets the viewport to the specified position and size, this will resize
 ## [djui_hud_reset_viewport](#djui_hud_reset_viewport)
 
 ### Description
-put the description here
+Resets the viewport to a fullscreen state
 
 ### Lua Example
 `djui_hud_reset_viewport()`
@@ -3318,7 +3339,7 @@ put the description here
 ## [djui_hud_set_scissor](#djui_hud_set_scissor)
 
 ### Description
-put the description here
+Sets the scissor rectangle to the specified position and size, this will cut off any subsequent DJUI graphics not within the rectangle
 
 ### Lua Example
 `djui_hud_set_scissor(x, y, width, height)`
@@ -3344,7 +3365,7 @@ put the description here
 ## [djui_hud_reset_scissor](#djui_hud_reset_scissor)
 
 ### Description
-put the description here
+Resets the scissor rectangle to a fullscreen state
 
 ### Lua Example
 `djui_hud_reset_scissor()`
diff --git a/docs/lua/functions-4.md b/docs/lua/functions-4.md
index 358633568..7d4b7c5f1 100644
--- a/docs/lua/functions-4.md
+++ b/docs/lua/functions-4.md
@@ -4070,7 +4070,7 @@ Sets all of Mario's velocity variables to 0 and sets his Y position to the floor
 ## [stationary_ground_step](#stationary_ground_step)
 
 ### Description
-Performs a full Mario stationary physics step (4 substeps) and returns an `GROUND_STEP_*` result
+Performs a full Mario stationary physics step (4 substeps) and returns a `GROUND_STEP_*` result
 
 ### Lua Example
 `local integerValue = stationary_ground_step(m)`
@@ -4093,7 +4093,7 @@ Performs a full Mario stationary physics step (4 substeps) and returns an `GROUN
 ## [perform_ground_step](#perform_ground_step)
 
 ### Description
-Performs a full Mario ground physics step (4 substeps) and returns an `GROUND_STEP_*` result
+Performs a full Mario ground physics step (4 substeps) and returns a `GROUND_STEP_*` result
 
 ### Lua Example
 `local integerValue = perform_ground_step(m)`
diff --git a/docs/lua/functions-6.md b/docs/lua/functions-6.md
index de205a965..7106da178 100644
--- a/docs/lua/functions-6.md
+++ b/docs/lua/functions-6.md
@@ -5276,7 +5276,7 @@ Returns the current sound mode (e.g., stereo, mono) stored in the save file. Use
 ## [sequence_player_get_tempo](#sequence_player_get_tempo)
 
 ### Description
-Gets the tempo of `player`
+Gets the `tempo` of `player`
 
 ### Lua Example
 `local integerValue = sequence_player_get_tempo(player)`
@@ -5323,7 +5323,7 @@ Sets the `tempo` of `player`. Resets when another sequence is played
 ## [sequence_player_get_tempo_acc](#sequence_player_get_tempo_acc)
 
 ### Description
-Gets the tempoAcc (tempo accumulation) of `player`
+Gets the `tempoAcc` (tempo accumulation) of `player`
 
 ### Lua Example
 `local integerValue = sequence_player_get_tempo_acc(player)`
@@ -5370,7 +5370,7 @@ Sets the `tempoAcc` (tempo accumulation) of `player`. Resets when another sequen
 ## [sequence_player_get_transposition](#sequence_player_get_transposition)
 
 ### Description
-Gets the transposition (pitch) of `player`
+Gets the `transposition` (pitch) of `player`
 
 ### Lua Example
 `local integerValue = sequence_player_get_transposition(player)`
diff --git a/docs/lua/functions.md b/docs/lua/functions.md
index 9fe4cc414..ec4053cd3 100644
--- a/docs/lua/functions.md
+++ b/docs/lua/functions.md
@@ -770,6 +770,7 @@
    - [djui_hud_get_mouse_y](functions-3.md#djui_hud_get_mouse_y)
    - [djui_hud_get_raw_mouse_x](functions-3.md#djui_hud_get_raw_mouse_x)
    - [djui_hud_get_raw_mouse_y](functions-3.md#djui_hud_get_raw_mouse_y)
+   - [djui_hud_is_mouse_locked](functions-3.md#djui_hud_is_mouse_locked)
    - [djui_hud_set_mouse_locked](functions-3.md#djui_hud_set_mouse_locked)
    - [djui_hud_get_mouse_buttons_down](functions-3.md#djui_hud_get_mouse_buttons_down)
    - [djui_hud_get_mouse_buttons_pressed](functions-3.md#djui_hud_get_mouse_buttons_pressed)
diff --git a/src/audio/seqplayer.h b/src/audio/seqplayer.h
index b2b863876..d70326ca1 100644
--- a/src/audio/seqplayer.h
+++ b/src/audio/seqplayer.h
@@ -15,15 +15,15 @@ void sequence_channel_set_volume(struct SequenceChannel *seqChannel, u8 volume);
 void process_sequences(s32 iterationsRemaining);
 void init_sequence_player(u32 player);
 void init_sequence_players(void);
-/* |description|Gets the tempo of `player`|descriptionEnd| */
+/* |description|Gets the `tempo` of `player`|descriptionEnd| */
 u16 sequence_player_get_tempo(u8 player);
 /* |description|Sets the `tempo` of `player`. Resets when another sequence is played|descriptionEnd| */
 void sequence_player_set_tempo(u8 player, u16 tempo);
-/* |description|Gets the tempoAcc (tempo accumulation) of `player`|descriptionEnd| */
+/* |description|Gets the `tempoAcc` (tempo accumulation) of `player`|descriptionEnd| */
 u16 sequence_player_get_tempo_acc(u8 player);
 /* |description|Sets the `tempoAcc` (tempo accumulation) of `player`. Resets when another sequence is played|descriptionEnd| */
 void sequence_player_set_tempo_acc(u8 player, u16 tempoAcc);
-/* |description|Gets the transposition (pitch) of `player`|descriptionEnd| */
+/* |description|Gets the `transposition` (pitch) of `player`|descriptionEnd| */
 u16 sequence_player_get_transposition(u8 player);
 /* |description|Sets the `transposition` (pitch) of `player`. Resets when another sequence is played|descriptionEnd| */
 void sequence_player_set_transposition(u8 player, u16 transposition);
diff --git a/src/game/mario_step.h b/src/game/mario_step.h
index 960e040d9..7ebbbfa0b 100644
--- a/src/game/mario_step.h
+++ b/src/game/mario_step.h
@@ -36,9 +36,9 @@ u32 mario_update_moving_sand(struct MarioState *m);
 u32 mario_update_windy_ground(struct MarioState *m);
 /* |description|Sets all of Mario's velocity variables to 0 and sets his Y position to the floor height|descriptionEnd| */
 void stop_and_set_height_to_floor(struct MarioState *m);
-/* |description|Performs a full Mario stationary physics step (4 substeps) and returns an `GROUND_STEP_*` result|descriptionEnd| */
+/* |description|Performs a full Mario stationary physics step (4 substeps) and returns a `GROUND_STEP_*` result|descriptionEnd| */
 s32 stationary_ground_step(struct MarioState *m);
-/* |description|Performs a full Mario ground physics step (4 substeps) and returns an `GROUND_STEP_*` result|descriptionEnd| */
+/* |description|Performs a full Mario ground physics step (4 substeps) and returns a `GROUND_STEP_*` result|descriptionEnd| */
 s32 perform_ground_step(struct MarioState *m);
 /* |description|Performs a full Mario air physics step (4 substeps) and returns an `AIR_STEP_*` result|descriptionEnd| */
 s32 perform_air_step(struct MarioState *m, u32 stepArg);
diff --git a/src/pc/djui/djui_hud_utils.c b/src/pc/djui/djui_hud_utils.c
index ae2485891..31db875d2 100644
--- a/src/pc/djui/djui_hud_utils.c
+++ b/src/pc/djui/djui_hud_utils.c
@@ -33,7 +33,7 @@ static struct DjuiColor sRefColor = { 255, 255, 255, 255 };
 static bool sLegacy = false;
 
 f32 gDjuiHudUtilsZ = 0;
-u8 gDjuiHudLockMouse = false;
+bool gDjuiHudLockMouse = false;
 
 extern ALIGNED8 const u8 texture_hud_char_camera[];
 extern ALIGNED8 const u8 texture_hud_char_lakitu[];
@@ -297,6 +297,10 @@ f32 djui_hud_get_raw_mouse_y(void) {
     return mouse_y;
 }
 
+bool djui_hud_is_mouse_locked(void) {
+    return gDjuiHudLockMouse;
+}
+
 void djui_hud_set_mouse_locked(bool locked) {
     gDjuiHudLockMouse = locked;
 }
diff --git a/src/pc/djui/djui_hud_utils.h b/src/pc/djui/djui_hud_utils.h
index 13efed6c8..62f590e75 100644
--- a/src/pc/djui/djui_hud_utils.h
+++ b/src/pc/djui/djui_hud_utils.h
@@ -52,7 +52,7 @@ struct GlobalTextures {
 
 extern struct GlobalTextures gGlobalTextures;
 extern f32 gDjuiHudUtilsZ;
-extern u8 gDjuiHudLockMouse;
+extern bool gDjuiHudLockMouse;
 
 /* |description|Gets the current DJUI HUD resolution|descriptionEnd| */
 u8 djui_hud_get_resolution(void);
@@ -92,7 +92,9 @@ f32 djui_hud_get_mouse_y(void);
 f32 djui_hud_get_raw_mouse_x(void);
 /* |description|Returns the y coordinate of the mouse relative to the screen|descriptionEnd| */
 f32 djui_hud_get_raw_mouse_y(void);
-/* |description|Sets if the cursor is hidden and constrainted to the window|descriptionEnd| */
+/* |description|Checks if the cursor is locked to the window|descriptionEnd| */
+bool djui_hud_is_mouse_locked(void);
+/* |description|Locks (or unlocks) the cursor to the window|descriptionEnd| */
 void djui_hud_set_mouse_locked(bool locked);
 /* |description|Returns the flags of the mouse buttons held down|descriptionEnd| */
 u8 djui_hud_get_mouse_buttons_down(void);
@@ -104,13 +106,13 @@ u8 djui_hud_get_mouse_buttons_released(void);
 f32 djui_hud_get_mouse_scroll_x(void);
 /* |description|Returns the amount scrolled vertically (-down/up+)|descriptionEnd| */
 f32 djui_hud_get_mouse_scroll_y(void);
-/* |description|Sets the viewport to the specified position and size, this will resize |descriptionEnd| */
+/* |description|Sets the viewport to the specified position and size, this will resize any subsequent DJUI graphics|descriptionEnd| */
 void djui_hud_set_viewport(f32 x, f32 y, f32 width, f32 height);
-/* |description|put the description here|descriptionEnd| */
+/* |description|Resets the viewport to a fullscreen state|descriptionEnd| */
 void djui_hud_reset_viewport(void);
-/* |description|put the description here|descriptionEnd| */
+/* |description|Sets the scissor rectangle to the specified position and size, this will cut off any subsequent DJUI graphics not within the rectangle|descriptionEnd| */
 void djui_hud_set_scissor(f32 x, f32 y, f32 width, f32 height);
-/* |description|put the description here|descriptionEnd| */
+/* |description|Resets the scissor rectangle to a fullscreen state|descriptionEnd| */
 void djui_hud_reset_scissor(void);
 
 /* |description|Measures the length of `message` in the current font|descriptionEnd| */
diff --git a/src/pc/lua/smlua_functions_autogen.c b/src/pc/lua/smlua_functions_autogen.c
index a76b089fb..db7fbdab4 100644
--- a/src/pc/lua/smlua_functions_autogen.c
+++ b/src/pc/lua/smlua_functions_autogen.c
@@ -12698,6 +12698,21 @@ int smlua_func_djui_hud_get_raw_mouse_y(UNUSED lua_State* L) {
     return 1;
 }
 
+int smlua_func_djui_hud_is_mouse_locked(UNUSED lua_State* L) {
+    if (L == NULL) { return 0; }
+
+    int top = lua_gettop(L);
+    if (top != 0) {
+        LOG_LUA_LINE("Improper param count for '%s': Expected %u, Received %u", "djui_hud_is_mouse_locked", 0, top);
+        return 0;
+    }
+
+
+    lua_pushboolean(L, djui_hud_is_mouse_locked());
+
+    return 1;
+}
+
 int smlua_func_djui_hud_set_mouse_locked(lua_State* L) {
     if (L == NULL) { return 0; }
 
@@ -37431,6 +37446,7 @@ void smlua_bind_functions_autogen(void) {
     smlua_bind_function(L, "djui_hud_get_mouse_y", smlua_func_djui_hud_get_mouse_y);
     smlua_bind_function(L, "djui_hud_get_raw_mouse_x", smlua_func_djui_hud_get_raw_mouse_x);
     smlua_bind_function(L, "djui_hud_get_raw_mouse_y", smlua_func_djui_hud_get_raw_mouse_y);
+    smlua_bind_function(L, "djui_hud_is_mouse_locked", smlua_func_djui_hud_is_mouse_locked);
     smlua_bind_function(L, "djui_hud_set_mouse_locked", smlua_func_djui_hud_set_mouse_locked);
     smlua_bind_function(L, "djui_hud_get_mouse_buttons_down", smlua_func_djui_hud_get_mouse_buttons_down);
     smlua_bind_function(L, "djui_hud_get_mouse_buttons_pressed", smlua_func_djui_hud_get_mouse_buttons_pressed);