diff --git a/autogen/convert_functions.py b/autogen/convert_functions.py index 7c3c07921..3e06d0c95 100644 --- a/autogen/convert_functions.py +++ b/autogen/convert_functions.py @@ -1076,7 +1076,7 @@ def build_function(function, do_extern): else: global total_functions total_functions += 1 - if function['description'] != "": + if function['description'][0] != "": global total_doc_functions total_doc_functions += 1 elif verbose: @@ -1212,7 +1212,7 @@ def process_functions(fname, file_str, extracted_descriptions): rejects += line + '\n' continue line = line.strip() - description = extracted_descriptions.get(line, "") + description = extracted_descriptions.get(line, [""]) fn = process_function(fname, line, description) if fn == None: continue @@ -1354,14 +1354,15 @@ def doc_function(fname, function): fid = function['identifier'] s = '\n## [%s](#%s)\n' % (fid, fid) - description = function.get('description', "") + description = function.get('description', [""]) rtype, rlink = translate_type_to_lua(function['type']) param_str = ', '.join([x['identifier'] for x in function['params'] if 'RET' not in x]) - if description != "": + if description[0] != "": s += '\n### Description\n' - s += f'{description}\n' + for line in description: + s += f'{line}\n' s += "\n### Lua Example\n" rvalues = [] @@ -1510,7 +1511,7 @@ def def_function(fname, function): rid = param['identifier'] rtypes.append((rtype, rid)) - if function['description'].startswith("[DEPRECATED"): + if function['description'][0].startswith("[DEPRECATED"): s += "--- @deprecated\n" for param in fparams: @@ -1532,8 +1533,9 @@ def def_function(fname, function): if rtype != "nil": s += ('--- @return %s' % rtype) + (' %s' % rid if rid else '') + '\n' - if function['description'] != "": - s += "--- %s\n" % (function['description']) + if function['description'][0] != "": + for n, line in enumerate(function['description']): + s += "--- %s%s\n" % (line, "
" if n != len(function['description']) - 1 else "") s += "function %s(%s)\n -- ...\nend\n\n" % (fid, param_str) return s diff --git a/autogen/extract_functions.py b/autogen/extract_functions.py index a73db339d..b69d7619d 100644 --- a/autogen/extract_functions.py +++ b/autogen/extract_functions.py @@ -144,12 +144,13 @@ def extract_functions(filename): description_lines.insert(0, raw_lines[k].strip()) if found_description_start and description_lines: - # Combine all lines, remove trailing |descriptionEnd| and normalize whitespace - combined_description = ' '.join(description_lines) - combined_description = re.sub(r'\|\s*descriptionEnd\s*\|.*', '', combined_description).strip() - # Normalize whitespace - combined_description = re.sub(r'\s+', ' ', combined_description).strip() - descriptions[re.sub(r'\)\s*\{', ');', line)] = combined_description + # Remove trailing |descriptionEnd| + if description_lines[0] == '': description_lines.pop(0) + description_lines[-1] = re.sub(r'\|\s*descriptionEnd\s*\|.*', '', description_lines[-1]).strip() + if description_lines[-1] == '': description_lines.pop(-1) + + if len(description_lines) > 0: + descriptions[re.sub(r'\)\s*\{', ');', line)] = description_lines break # normalize function ending diff --git a/autogen/lua_definitions/functions.lua b/autogen/lua_definitions/functions.lua index 1ceff4917..925623f9f 100644 --- a/autogen/lua_definitions/functions.lua +++ b/autogen/lua_definitions/functions.lua @@ -9,7 +9,8 @@ end --- @param id integer --- @return ObjectWarpNode ---- Finds a warp node in the current area by its ID. The warp node must exist in the list of warp nodes for the current area. Useful for locating a specific warp point in the level, such as teleportation zones or connections to other areas +--- Finds a warp node in the current area by its ID. The warp node must exist in the list of warp nodes for the current area.
+--- Useful for locating a specific warp point in the level, such as teleportation zones or connections to other areas function area_get_warp_node(id) -- ... end @@ -22,7 +23,8 @@ end --- @param o Object --- @return ObjectWarpNode ---- Finds a warp node in the current area using parameters from the provided object. The object's behavior parameters are used to determine the warp node ID. Useful for associating an object (like a door or warp pipe) with its corresponding warp node in the area +--- Finds a warp node in the current area using parameters from the provided object. The object's behavior parameters are used to determine the warp node ID.
+--- Useful for associating an object (like a door or warp pipe) with its corresponding warp node in the area function area_get_warp_node_from_params(o) -- ... end @@ -1071,7 +1073,8 @@ function bhv_tox_box_loop() end --- @return integer ---- Checks if Mario is moving fast enough to make Piranha Plant bite. This one is a mouthful +--- Checks if Mario is moving fast enough to make Piranha Plant bite.
+--- This one is a mouthful function mario_moving_fast_enough_to_make_piranha_plant_bite() -- ... end @@ -3035,19 +3038,22 @@ function get_id_from_behavior_name(name) -- ... end ---- Skips camera interpolation for a frame, locking the camera instantly to the target position. Useful for immediate changes in camera state or position without smooth transitions +--- Skips camera interpolation for a frame, locking the camera instantly to the target position.
+--- Useful for immediate changes in camera state or position without smooth transitions function skip_camera_interpolation() -- ... end --- @param shake integer ---- Applies a shake effect to the camera based on a hit type. Different shake types simulate various impacts, such as attacks, falls, or shocks +--- Applies a shake effect to the camera based on a hit type.
+--- Different shake types simulate various impacts, such as attacks, falls, or shocks function set_camera_shake_from_hit(shake) -- ... end --- @param shake integer ---- Applies an environmental shake effect to the camera. Handles predefined shake types triggered by environmental events like explosions or platform movements +--- Applies an environmental shake effect to the camera.
+--- Handles predefined shake types triggered by environmental events like explosions or platform movements function set_environmental_camera_shake(shake) -- ... end @@ -3056,20 +3062,23 @@ end --- @param posX number --- @param posY number --- @param posZ number ---- Applies a shake effect to the camera, scaled by its proximity to a specified point. The intensity decreases with distance from the point +--- Applies a shake effect to the camera, scaled by its proximity to a specified point.
+--- The intensity decreases with distance from the point function set_camera_shake_from_point(shake, posX, posY, posZ) -- ... end --- @param c Camera ---- Moves Mario's head slightly upward when the C-Up button is pressed. This function aligns the camera to match the head movement for consistency +--- Moves Mario's head slightly upward when the C-Up button is pressed.
+--- This function aligns the camera to match the head movement for consistency function move_mario_head_c_up(c) -- ... end --- @param c Camera --- @param frames integer ---- Transitions the camera to the next state over a specified number of frames. This is typically used for cutscenes or scripted sequences +--- Transitions the camera to the next state over a specified number of frames.
+--- This is typically used for cutscenes or scripted sequences function transition_next_state(c, frames) -- ... end @@ -3077,38 +3086,44 @@ end --- @param c Camera --- @param mode integer --- @param frames integer ---- Changes the camera to a new mode, optionally interpolating over a specified number of frames. Useful for transitioning between different camera behaviors dynamically +--- Changes the camera to a new mode, optionally interpolating over a specified number of frames.
+--- Useful for transitioning between different camera behaviors dynamically function set_camera_mode(c, mode, frames) -- ... end --- @param c Camera ---- Resets the camera's state while retaining some settings, such as position or mode. This is often used when soft-resetting gameplay without reinitialization +--- Resets the camera's state while retaining some settings, such as position or mode.
+--- This is often used when soft-resetting gameplay without reinitialization function soft_reset_camera(c) -- ... end --- @param c Camera ---- Fully resets the camera to its default state and reinitializes all settings. This is typically used when restarting gameplay or loading a new area +--- Fully resets the camera to its default state and reinitializes all settings.
+--- This is typically used when restarting gameplay or loading a new area function reset_camera(c) -- ... end ---- Selects the appropriate camera mode for Mario based on the current gameplay context. Adapts camera behavior dynamically to match Mario's environment or state +--- Selects the appropriate camera mode for Mario based on the current gameplay context.
+--- Adapts camera behavior dynamically to match Mario's environment or state function select_mario_cam_mode() -- ... end --- @param dst Vec3f --- @param o Object ---- Converts an object's position to a `Vec3f` format. Useful for aligning object behaviors or interactions with the camera system +--- Converts an object's position to a `Vec3f` format.
+--- Useful for aligning object behaviors or interactions with the camera system function object_pos_to_vec3f(dst, o) -- ... end --- @param o Object --- @param src Vec3f ---- Converts a `Vec3f` position to an object's internal format. Useful for syncing 3D positions between objects and the game world +--- Converts a `Vec3f` position to an object's internal format.
+--- Useful for syncing 3D positions between objects and the game world function vec3f_to_object_pos(o, src) -- ... end @@ -3143,27 +3158,31 @@ end --- @param angle integer --- @return integer ---- Selects an alternate camera mode based on the given angle. Used to toggle between predefined camera modes dynamically +--- Selects an alternate camera mode based on the given angle.
+--- Used to toggle between predefined camera modes dynamically function cam_select_alt_mode(angle) -- ... end --- @param mode integer --- @return integer ---- Sets the camera's angle based on the specified mode. Handles rotation and focus adjustments for predefined camera behaviors +--- Sets the camera's angle based on the specified mode.
+--- Handles rotation and focus adjustments for predefined camera behaviors function set_cam_angle(mode) -- ... end --- @param mode integer ---- Applies a handheld camera shake effect with configurable parameters. Can be used to simulate dynamic, realistic camera movement +--- Applies a handheld camera shake effect with configurable parameters.
+--- Can be used to simulate dynamic, realistic camera movement function set_handheld_shake(mode) -- ... end --- @param pos Vec3f --- @param focus Vec3f ---- Activates a handheld camera shake effect. Calculates positional and focus adjustments to simulate manual movement +--- Activates a handheld camera shake effect.
+--- Calculates positional and focus adjustments to simulate manual movement function shake_camera_handheld(pos, focus) -- ... end @@ -3172,7 +3191,8 @@ end --- @param buttonsPressed integer --- @param buttonsDown integer --- @return integer ---- Determines which C-buttons are currently pressed by the player. Returns a bitmask indicating the active buttons for camera control +--- Determines which C-buttons are currently pressed by the player.
+--- Returns a bitmask indicating the active buttons for camera control function find_c_buttons_pressed(currentState, buttonsPressed, buttonsDown) -- ... end @@ -3181,7 +3201,8 @@ end --- @param offsetY number --- @param radius number --- @return integer ---- Checks for collisions between the camera and level geometry. Adjusts the camera's position to avoid clipping into walls or obstacles +--- Checks for collisions between the camera and level geometry.
+--- Adjusts the camera's position to avoid clipping into walls or obstacles function collide_with_walls(pos, offsetY, radius) -- ... end @@ -3191,7 +3212,8 @@ end --- @param maxPitch integer --- @param minPitch integer --- @return integer ---- Clamps the camera's pitch angle between a maximum and minimum value. Prevents over-rotation and maintains a consistent viewing angle +--- Clamps the camera's pitch angle between a maximum and minimum value.
+--- Prevents over-rotation and maintains a consistent viewing angle function clamp_pitch(from, to, maxPitch, minPitch) -- ... end @@ -3200,7 +3222,8 @@ end --- @param posY number --- @param posZ number --- @return integer ---- Checks if a position is within 100 units of Mario's current position. Returns true if the position is within the specified radius and false otherwise +--- Checks if a position is within 100 units of Mario's current position.
+--- Returns true if the position is within the specified radius and false otherwise function is_within_100_units_of_mario(posX, posY, posZ) -- ... end @@ -3210,7 +3233,9 @@ end --- @param scale number --- @return integer --- @return number dst ---- Smoothly transitions or directly sets a floating-point value (`dst`) to approach a target (`goal`). Uses asymptotic scaling for gradual adjustments or direct assignment. Returns FALSE if `dst` reaches `goal` +--- Smoothly transitions or directly sets a floating-point value (`dst`) to approach a target (`goal`).
+--- Uses asymptotic scaling for gradual adjustments or direct assignment.
+--- Returns FALSE if `dst` reaches `goal` function set_or_approach_f32_asymptotic(dst, goal, scale) -- ... end @@ -3220,7 +3245,8 @@ end --- @param multiplier number --- @return integer --- @return number current ---- Gradually adjusts a floating-point value (`current`) towards a target (`target`) using asymptotic smoothing. Returns FALSE if `current` reaches the `target` +--- Gradually adjusts a floating-point value (`current`) towards a target (`target`) using asymptotic smoothing.
+--- Returns FALSE if `current` reaches the `target` function approach_f32_asymptotic_bool(current, target, multiplier) -- ... end @@ -3229,7 +3255,9 @@ end --- @param target number --- @param multiplier number --- @return number ---- Gradually approaches a floating-point value (`target`) using asymptotic smoothing. The rate of approach is controlled by the `multiplier`. Useful for smoothly adjusting camera parameters like field-of-view or position +--- Gradually approaches a floating-point value (`target`) using asymptotic smoothing.
+--- The rate of approach is controlled by the `multiplier`.
+--- Useful for smoothly adjusting camera parameters like field-of-view or position function approach_f32_asymptotic(current, target, multiplier) -- ... end @@ -3239,7 +3267,8 @@ end --- @param divisor integer --- @return integer --- @return integer current ---- Gradually adjusts a signed 16-bit integer (`current`) towards a target (`target`) using asymptotic smoothing. Returns FALSE if `current` reaches `target` +--- Gradually adjusts a signed 16-bit integer (`current`) towards a target (`target`) using asymptotic smoothing.
+--- Returns FALSE if `current` reaches `target` function approach_s16_asymptotic_bool(current, target, divisor) -- ... end @@ -3248,7 +3277,9 @@ end --- @param target integer --- @param divisor integer --- @return integer ---- Gradually approaches a signed 16-bit integer (`target`) using asymptotic smoothing. The divisor controls the rate of the adjustment. Useful for adjusting angles or positions smoothly +--- Gradually approaches a signed 16-bit integer (`target`) using asymptotic smoothing.
+--- The divisor controls the rate of the adjustment.
+--- Useful for adjusting angles or positions smoothly function approach_s16_asymptotic(current, target, divisor) -- ... end @@ -3258,7 +3289,8 @@ end --- @param xMul number --- @param yMul number --- @param zMul number ---- Smoothly transitions a 3D vector (`current`) towards a target vector (`target`) using asymptotic scaling. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component +--- Smoothly transitions a 3D vector (`current`) towards a target vector (`target`) using asymptotic scaling.
+--- Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component function approach_vec3f_asymptotic(current, target, xMul, yMul, zMul) -- ... end @@ -3268,7 +3300,8 @@ end --- @param xMul number --- @param yMul number --- @param zMul number ---- Smoothly transitions a 3D vector (`current`) toward a target vector (`goal`) using asymptotic scaling. Allows gradual or instantaneous alignment of 3D positions. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component +--- Smoothly transitions a 3D vector (`current`) toward a target vector (`goal`) using asymptotic scaling.
+--- Allows gradual or instantaneous alignment of 3D positions. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component function set_or_approach_vec3f_asymptotic(dst, goal, xMul, yMul, zMul) -- ... end @@ -3278,7 +3311,8 @@ end --- @param increment integer --- @return integer --- @return integer current ---- Adjusts a signed 16-bit integer (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). Returns FALSE if `current` reaches the `target` +--- Adjusts a signed 16-bit integer (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`).
+--- Returns FALSE if `current` reaches the `target` function camera_approach_s16_symmetric_bool(current, target, increment) -- ... end @@ -3288,7 +3322,9 @@ end --- @param increment integer --- @return integer --- @return integer current ---- Smoothly transitions or directly sets a signed 16-bit value (`current`) to approach a target (`target`). Uses symmetric scaling for gradual or immediate adjustments. Returns FALSE if `current` reaches the `target` +--- Smoothly transitions or directly sets a signed 16-bit value (`current`) to approach a target (`target`).
+--- Uses symmetric scaling for gradual or immediate adjustments.
+--- Returns FALSE if `current` reaches the `target` function set_or_approach_s16_symmetric(current, target, increment) -- ... end @@ -3298,7 +3334,8 @@ end --- @param increment number --- @return integer --- @return number current ---- Adjusts a floating-point value (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). Returns FALSE if `current` reaches the `target` +--- Adjusts a floating-point value (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`).
+--- Returns FALSE if `current` reaches the `target` function camera_approach_f32_symmetric_bool(current, target, increment) -- ... end @@ -3307,7 +3344,8 @@ end --- @param target number --- @param increment number --- @return number ---- Symmetrically approaches a floating-point value (`target`) with a fixed increment (`increment`) per frame. Limits the rate of change to ensure gradual transitions +--- Symmetrically approaches a floating-point value (`target`) with a fixed increment (`increment`) per frame.
+--- Limits the rate of change to ensure gradual transitions function camera_approach_f32_symmetric(value, target, increment) -- ... end @@ -3316,7 +3354,8 @@ end --- @param xRange integer --- @param yRange integer --- @param zRange integer ---- Generates a random 3D vector with short integer components. Useful for randomized offsets or environmental effects +--- Generates a random 3D vector with short integer components.
+--- Useful for randomized offsets or environmental effects function random_vec3s(dst, xRange, yRange, zRange) -- ... end @@ -3328,7 +3367,8 @@ end --- @param zMax number --- @param zMin number --- @return integer ---- Clamps a position within specified X and Z bounds and calculates the yaw angle from the origin. Prevents the camera from moving outside of the designated area +--- Clamps a position within specified X and Z bounds and calculates the yaw angle from the origin.
+--- Prevents the camera from moving outside of the designated area function clamp_positions_and_find_yaw(pos, origin, xMax, xMin, zMax, zMin) -- ... end @@ -3339,7 +3379,8 @@ end --- @param range integer --- @param surfType integer --- @return integer ---- Determines if a range is obstructed by a surface relative to the camera. Returns true if the range is behind the specified surface +--- Determines if a range is obstructed by a surface relative to the camera.
+--- Returns true if the range is behind the specified surface function is_range_behind_surface(from, to, surf, range, surfType) -- ... end @@ -3348,7 +3389,9 @@ end --- @param from Vec3f --- @param to Vec3f --- @param scale number ---- Scales a point along a line between two 3D points (`from` and `to`). The scaling factor determines how far along the line the resulting point will be. The result is stored in the destination vector (`dest`) +--- Scales a point along a line between two 3D points (`from` and `to`).
+--- The scaling factor determines how far along the line the resulting point will be.
+--- The result is stored in the destination vector (`dest`) function scale_along_line(dest, from, to, scale) -- ... end @@ -3356,7 +3399,8 @@ end --- @param from Vec3f --- @param to Vec3f --- @return integer ---- Calculates the pitch angle (rotation around the X-axis) from one 3D point (`from`) to another (`to`). Returns the pitch as a signed 16-bit integer +--- Calculates the pitch angle (rotation around the X-axis) from one 3D point (`from`) to another (`to`).
+--- Returns the pitch as a signed 16-bit integer function calculate_pitch(from, to) -- ... end @@ -3364,7 +3408,8 @@ end --- @param from Vec3f --- @param to Vec3f --- @return integer ---- Determines the yaw angle (rotation around the Y-axis) from one 3D position (`from`) to another (`to`). Returns the yaw as a signed 16-bit integer +--- Determines the yaw angle (rotation around the Y-axis) from one 3D position (`from`) to another (`to`).
+--- Returns the yaw as a signed 16-bit integer function calculate_yaw(from, to) -- ... end @@ -3381,7 +3426,9 @@ end --- @param a Vec3f --- @param b Vec3f --- @return number ---- Calculates the absolute distance between two 3D points (`a` and `b`). Returns the distance as a floating-point value. Useful for determining proximity between objects in 3D space +--- Calculates the absolute distance between two 3D points (`a` and `b`).
+--- Returns the distance as a floating-point value.
+--- Useful for determining proximity between objects in 3D space function calc_abs_dist(a, b) -- ... end @@ -3389,7 +3436,9 @@ end --- @param a Vec3f --- @param b Vec3f --- @return number ---- Calculates the horizontal (XZ-plane) distance between two 3D points (`a` and `b`). Returns the distance as a floating-point value. Useful for terrain navigation or collision detection +--- Calculates the horizontal (XZ-plane) distance between two 3D points (`a` and `b`).
+--- Returns the distance as a floating-point value.
+--- Useful for terrain navigation or collision detection function calc_hor_dist(a, b) -- ... end @@ -3397,7 +3446,9 @@ end --- @param dst Vec3f --- @param src Vec3f --- @param yaw integer ---- Rotates a vector around the XZ-plane by a specified yaw angle. The result is stored in the destination vector (`dst`). Useful for rotating camera positions or object coordinates horizontally +--- Rotates a vector around the XZ-plane by a specified yaw angle.
+--- The result is stored in the destination vector (`dst`).
+--- Useful for rotating camera positions or object coordinates horizontally function rotate_in_xz(dst, src, yaw) -- ... end @@ -3405,7 +3456,9 @@ end --- @param dst Vec3f --- @param src Vec3f --- @param pitch integer ---- Rotates a vector around the YZ-plane by a specified pitch angle. The result is stored in the destination vector (`dst`). Useful for vertical camera rotations or object transformations +--- Rotates a vector around the YZ-plane by a specified pitch angle.
+--- The result is stored in the destination vector (`dst`).
+--- Useful for vertical camera rotations or object transformations function rotate_in_yz(dst, src, pitch) -- ... end @@ -3413,7 +3466,9 @@ end --- @param mag integer --- @param decay integer --- @param inc integer ---- Applies a pitch-based shake effect to the camera. The shake's magnitude, decay, and increment are configurable. Simulates vertical disturbances like impacts or explosions +--- Applies a pitch-based shake effect to the camera.
+--- The shake's magnitude, decay, and increment are configurable.
+--- Simulates vertical disturbances like impacts or explosions function set_camera_pitch_shake(mag, decay, inc) -- ... end @@ -3421,7 +3476,8 @@ end --- @param mag integer --- @param decay integer --- @param inc integer ---- Applies a yaw-based shake effect to the camera. Simulates horizontal vibrations or rotational impacts +--- Applies a yaw-based shake effect to the camera.
+--- Simulates horizontal vibrations or rotational impacts function set_camera_yaw_shake(mag, decay, inc) -- ... end @@ -3429,7 +3485,8 @@ end --- @param mag integer --- @param decay integer --- @param inc integer ---- Applies a roll-based shake effect to the camera. Simulates rotational disturbances for dynamic camera effects +--- Applies a roll-based shake effect to the camera.
+--- Simulates rotational disturbances for dynamic camera effects function set_camera_roll_shake(mag, decay, inc) -- ... end @@ -3441,28 +3498,32 @@ end --- @param posX number --- @param posY number --- @param posZ number ---- Applies a pitch shake effect to the camera, scaled by proximity to a specified point. Simulates vibrations with intensity decreasing further from the point +--- Applies a pitch shake effect to the camera, scaled by proximity to a specified point.
+--- Simulates vibrations with intensity decreasing further from the point function set_pitch_shake_from_point(mag, decay, inc, maxDist, posX, posY, posZ) -- ... end --- @param pos Vec3f --- @param focus Vec3f ---- Activates a pitch-based shake effect. Adds vertical vibrational movement to the camera's behavior +--- Activates a pitch-based shake effect.
+--- Adds vertical vibrational movement to the camera's behavior function shake_camera_pitch(pos, focus) -- ... end --- @param pos Vec3f --- @param focus Vec3f ---- Activates a yaw-based shake effect. Adds horizontal vibrational movement to the camera's behavior +--- Activates a yaw-based shake effect.
+--- Adds horizontal vibrational movement to the camera's behavior function shake_camera_yaw(pos, focus) -- ... end --- @param roll integer --- @return integer roll ---- Applies a roll-based shake effect to the camera. Simulates rotational disturbances caused by impacts or other events +--- Applies a roll-based shake effect to the camera.
+--- Simulates rotational disturbances caused by impacts or other events function shake_camera_roll(roll) -- ... end @@ -3470,52 +3531,62 @@ end --- @param c Camera --- @param areaYaw integer --- @return integer ---- Calculates an outward radial offset based on the camera's yaw angle. Returns the offset yaw, used for positioning or alignment +--- Calculates an outward radial offset based on the camera's yaw angle.
+--- Returns the offset yaw, used for positioning or alignment function offset_yaw_outward_radial(c, areaYaw) -- ... end ---- Plays a buzzing sound effect when the camera attempts to move downward but is restricted. Provides feedback for invalid C-Down input actions +--- Plays a buzzing sound effect when the camera attempts to move downward but is restricted.
+--- Provides feedback for invalid C-Down input actions function play_camera_buzz_if_cdown() -- ... end ---- Plays a buzzing sound effect when a blocked C-button action is attempted. Used to signal invalid input or restricted camera movement +--- Plays a buzzing sound effect when a blocked C-button action is attempted.
+--- Used to signal invalid input or restricted camera movement function play_camera_buzz_if_cbutton() -- ... end ---- Plays a buzzing sound effect when the camera's position is misaligned with the player's perspective. Used as audio feedback for incorrect camera behavior +--- Plays a buzzing sound effect when the camera's position is misaligned with the player's perspective.
+--- Used as audio feedback for incorrect camera behavior function play_camera_buzz_if_c_sideways() -- ... end ---- Plays a sound effect when the C-Up button is pressed for camera movement. Provides feedback for vertical camera adjustments +--- Plays a sound effect when the C-Up button is pressed for camera movement.
+--- Provides feedback for vertical camera adjustments function play_sound_cbutton_up() -- ... end ---- Plays a sound effect when the C-Down button is pressed for camera movement. Provides auditory feedback for valid camera input +--- Plays a sound effect when the C-Down button is pressed for camera movement.
+--- Provides auditory feedback for valid camera input function play_sound_cbutton_down() -- ... end ---- Plays a sound effect when the C-Side button (left or right) is pressed for camera movement. Used as audio feedback for horizontal adjustments to the camera +--- Plays a sound effect when the C-Side button (left or right) is pressed for camera movement.
+--- Used as audio feedback for horizontal adjustments to the camera function play_sound_cbutton_side() -- ... end ---- Plays a sound effect when a blocked action changes the camera mode. This provides feedback for invalid attempts to switch the camera state +--- Plays a sound effect when a blocked action changes the camera mode.
+--- This provides feedback for invalid attempts to switch the camera state function play_sound_button_change_blocked() -- ... end ---- Plays a sound effect when the R-Button camera mode is changed. Provides feedback for toggling camera behaviors +--- Plays a sound effect when the R-Button camera mode is changed.
+--- Provides feedback for toggling camera behaviors function play_sound_rbutton_changed() -- ... end ---- Plays a sound effect when the camera switches between Lakitu and Mario perspectives. Signals a successful change in camera mode +--- Plays a sound effect when the camera switches between Lakitu and Mario perspectives.
+--- Signals a successful change in camera mode function play_sound_if_cam_switched_to_lakitu_or_mario() -- ... end @@ -3523,34 +3594,39 @@ end --- @param c Camera --- @param unused number --- @return integer ---- Handles radial camera movement based on player input. Updates the camera's position or orientation accordingly +--- Handles radial camera movement based on player input.
+--- Updates the camera's position or orientation accordingly function radial_camera_input(c, unused) -- ... end --- @param trigger integer --- @return integer ---- Triggers a dialog sequence during a cutscene. The dialog is synchronized with the camera's position and movement +--- Triggers a dialog sequence during a cutscene.
+--- The dialog is synchronized with the camera's position and movement function trigger_cutscene_dialog(trigger) -- ... end --- @param c Camera ---- Handles camera movement based on input from the C-buttons. Updates the camera's position or angle to match directional player input +--- Handles camera movement based on input from the C-buttons.
+--- Updates the camera's position or angle to match directional player input function handle_c_button_movement(c) -- ... end --- @param c Camera --- @param cutscene integer ---- Starts a cutscene based on the provided ID. The camera transitions to predefined behaviors for the duration of the cutscene +--- Starts a cutscene based on the provided ID.
+--- The camera transitions to predefined behaviors for the duration of the cutscene function start_cutscene(c, cutscene) -- ... end --- @param c Camera --- @return integer ---- Gets the appropriate cutscene to play based on Mario's current gameplay state. This function helps determine transitions for cinematic or scripted sequences +--- Gets the appropriate cutscene to play based on Mario's current gameplay state.
+--- This function helps determine transitions for cinematic or scripted sequences function get_cutscene_from_mario_status(c) -- ... end @@ -3558,7 +3634,8 @@ end --- @param displacementX number --- @param displacementY number --- @param displacementZ number ---- Moves the camera to a specified warp destination. This function handles transitions between levels or areas seamlessly +--- Moves the camera to a specified warp destination.
+--- This function handles transitions between levels or areas seamlessly function warp_camera(displacementX, displacementY, displacementZ) -- ... end @@ -3566,7 +3643,8 @@ end --- @param c Camera --- @param goal number --- @param inc number ---- Adjusts the camera's height toward a target value (`goalHeight`) while respecting terrain and obstructions. This is really wonky and probably shouldn't be used, prefer `gLakituStates` +--- Adjusts the camera's height toward a target value (`goalHeight`) while respecting terrain and obstructions.
+--- This is really wonky and probably shouldn't be used, prefer `gLakituStates` function approach_camera_height(c, goal, inc) -- ... end @@ -3575,7 +3653,8 @@ end --- @param from Vec3f --- @param to Vec3f --- @param rotation Vec3s ---- Offsets a vector by rotating it in 3D space relative to a reference position. This is useful for creating radial effects or dynamic transformations +--- Offsets a vector by rotating it in 3D space relative to a reference position.
+--- This is useful for creating radial effects or dynamic transformations function offset_rotated(dst, from, to, rotation) -- ... end @@ -3588,7 +3667,8 @@ end --- @param oldFoc Vec3f --- @param yaw integer --- @return integer ---- Transitions the camera to the next Lakitu state, updating position and focus. This function handles smooth transitions between different gameplay scenarios +--- Transitions the camera to the next Lakitu state, updating position and focus.
+--- This function handles smooth transitions between different gameplay scenarios function next_lakitu_state(newPos, newFoc, curPos, curFoc, oldPos, oldFoc, yaw) -- ... end @@ -3601,14 +3681,16 @@ end --- @param c Camera --- @return integer ---- Processes course-specific camera settings, such as predefined positions or modes. Adjusts the camera to match the design and gameplay requirements of the current course +--- Processes course-specific camera settings, such as predefined positions or modes.
+--- Adjusts the camera to match the design and gameplay requirements of the current course function camera_course_processing(c) -- ... end --- @param pos Vec3f --- @param lastGood Vec3f ---- Resolves collisions between the camera and level geometry. Adjusts the camera's position to prevent clipping or intersecting with objects +--- Resolves collisions between the camera and level geometry.
+--- Adjusts the camera's position to prevent clipping or intersecting with objects function resolve_geometry_collisions(pos, lastGood) -- ... end @@ -3619,14 +3701,16 @@ end --- @param yawRange integer --- @return integer --- @return integer avoidYaw ---- Rotates the camera to avoid walls or other obstructions. Ensures clear visibility of the player or target objects +--- Rotates the camera to avoid walls or other obstructions.
+--- Ensures clear visibility of the player or target objects function rotate_camera_around_walls(c, cPos, avoidYaw, yawRange) -- ... end --- @param cutscene integer --- @return integer ---- Starts a cutscene focused on an object without requiring focus to remain locked. This is useful for dynamic events where the camera adjusts freely +--- Starts a cutscene focused on an object without requiring focus to remain locked.
+--- This is useful for dynamic events where the camera adjusts freely function start_object_cutscene_without_focus(cutscene) -- ... end @@ -3635,7 +3719,8 @@ end --- @param o Object --- @param dialogID integer --- @return integer ---- Starts a cutscene involving an object and displays dialog during the sequence. The camera focuses on the object while synchronizing dialog with the scene +--- Starts a cutscene involving an object and displays dialog during the sequence.
+--- The camera focuses on the object while synchronizing dialog with the scene function cutscene_object_with_dialog(cutscene, o, dialogID) -- ... end @@ -3643,7 +3728,8 @@ end --- @param cutscene integer --- @param o Object --- @return integer ---- Starts a cutscene involving an object without dialog. The camera transitions smoothly to focus on the object +--- Starts a cutscene involving an object without dialog.
+--- The camera transitions smoothly to focus on the object function cutscene_object_without_dialog(cutscene, o) -- ... end @@ -3651,13 +3737,15 @@ end --- @param cutscene integer --- @param o Object --- @return integer ---- Initiates a cutscene focusing on a specific object in the game world. The camera transitions smoothly to the object, adapting its position as needed +--- Initiates a cutscene focusing on a specific object in the game world.
+--- The camera transitions smoothly to the object, adapting its position as needed function cutscene_object(cutscene, o) -- ... end --- @param c Camera ---- Starts the execution of a predefined cutscene. The camera transitions dynamically to follow the scripted sequence +--- Starts the execution of a predefined cutscene.
+--- The camera transitions dynamically to follow the scripted sequence function play_cutscene(c) -- ... end @@ -3665,7 +3753,8 @@ end --- @param obj integer --- @param frame integer --- @return integer ---- Spawns an object as part of a cutscene, such as props or interactive elements. Returns the spawned object's reference for further manipulation +--- Spawns an object as part of a cutscene, such as props or interactive elements.
+--- Returns the spawned object's reference for further manipulation function cutscene_spawn_obj(obj, frame) -- ... end @@ -3673,19 +3762,22 @@ end --- @param amplitude integer --- @param decay integer --- @param shakeSpeed integer ---- Applies a field-of-view shake effect to simulate zoom or focus disruptions. Shake parameters, such as amplitude and decay, control the intensity +--- Applies a field-of-view shake effect to simulate zoom or focus disruptions.
+--- Shake parameters, such as amplitude and decay, control the intensity function set_fov_shake(amplitude, decay, shakeSpeed) -- ... end --- @param func integer ---- Assigns a custom function for dynamic field-of-view adjustments. This allows precise control over the camera's zoom behavior during gameplay +--- Assigns a custom function for dynamic field-of-view adjustments.
+--- This allows precise control over the camera's zoom behavior during gameplay function set_fov_function(func) -- ... end --- @param preset integer ---- Applies a preset field-of-view shake effect during a cutscene. This creates dynamic visual effects, such as zoom or focus disruptions +--- Applies a preset field-of-view shake effect during a cutscene.
+--- This creates dynamic visual effects, such as zoom or focus disruptions function cutscene_set_fov_shake_preset(preset) -- ... end @@ -3694,7 +3786,8 @@ end --- @param posX number --- @param posY number --- @param posZ number ---- Applies a preset field-of-view shake effect relative to a specific point. The intensity diminishes as the distance from the point increases +--- Applies a preset field-of-view shake effect relative to a specific point.
+--- The intensity diminishes as the distance from the point increases function set_fov_shake_from_point_preset(preset, posX, posY, posZ) -- ... end @@ -3705,7 +3798,8 @@ end --- @param yawOff integer --- @param pitchDiv integer --- @param yawDiv integer ---- Rotates an object toward a specific point in 3D space. Gradually updates the object's pitch and yaw angles to face the target +--- Rotates an object toward a specific point in 3D space.
+--- Gradually updates the object's pitch and yaw angles to face the target function obj_rotate_towards_point(o, point, pitchOff, yawOff, pitchDiv, yawDiv) -- ... end @@ -3715,25 +3809,29 @@ end --- @param y integer --- @param z integer --- @return integer ---- Activates a fixed camera mode and aligns the camera to specific X, Y, Z coordinates. This is useful for predefined static views in specific areas +--- Activates a fixed camera mode and aligns the camera to specific X, Y, Z coordinates.
+--- This is useful for predefined static views in specific areas function set_camera_mode_fixed(c, x, y, z) -- ... end --- @param angle integer --- @return integer ---- Takes in an SM64 angle unit and returns the nearest 45 degree angle, also in SM64 angle units. Useful when needing to align angles (camera, yaw, etc.) +--- Takes in an SM64 angle unit and returns the nearest 45 degree angle, also in SM64 angle units.
+--- Useful when needing to align angles (camera, yaw, etc.) function snap_to_45_degrees(angle) -- ... end --- @param enable integer ---- Toggles whether the camera uses course-specific settings. This is useful for enabling or disabling custom behaviors in specific courses or areas +--- Toggles whether the camera uses course-specific settings.
+--- This is useful for enabling or disabling custom behaviors in specific courses or areas function camera_set_use_course_specific_settings(enable) -- ... end ---- Centers the ROM hack camera. This function is designed for non-standard level layouts and modded game environments +--- Centers the ROM hack camera.
+--- This function is designed for non-standard level layouts and modded game environments function center_rom_hack_camera() -- ... end @@ -3747,7 +3845,8 @@ end --- @param m MarioState --- @param characterSound CharacterSound ---- Plays a character-specific sound based on the given `characterSound` value. The sound is tied to Mario's current state (`m`). Useful for triggering sound effects for actions like jumping or interacting with the environment +--- Plays a character-specific sound based on the given `characterSound` value. The sound is tied to Mario's current state (`m`).
+--- Useful for triggering sound effects for actions like jumping or interacting with the environment function play_character_sound(m, characterSound) -- ... end @@ -3755,7 +3854,8 @@ end --- @param m MarioState --- @param characterSound CharacterSound --- @param offset integer ---- Plays a character-specific sound with an additional `offset`, allowing variations or delays in the sound effect. Uses Mario's current state (`m`). Useful for adding dynamic sound effects or syncing sounds to specific animations or events +--- Plays a character-specific sound with an additional `offset`, allowing variations or delays in the sound effect. Uses Mario's current state (`m`).
+--- Useful for adding dynamic sound effects or syncing sounds to specific animations or events function play_character_sound_offset(m, characterSound, offset) -- ... end @@ -3763,14 +3863,16 @@ end --- @param m MarioState --- @param characterSound CharacterSound --- @param flags integer ---- Plays a character-specific sound only if certain flags are not set. This ensures that sounds are not repeated unnecessarily. The sound is based on `characterSound`, and the flags are checked using `flags`. Useful for avoiding duplicate sound effects in rapid succession or conditional actions +--- Plays a character-specific sound only if certain flags are not set. This ensures that sounds are not repeated unnecessarily. The sound is based on `characterSound`, and the flags are checked using `flags`.
+--- Useful for avoiding duplicate sound effects in rapid succession or conditional actions function play_character_sound_if_no_flag(m, characterSound, flags) -- ... end --- @param m MarioState --- @return number ---- Calculates the animation offset for Mario's current animation. The offset is determined by the type of animation being played (e.g., hand, feet, or torso movement). Useful for smoothly syncing Mario's model height or positional adjustments during animations +--- Calculates the animation offset for Mario's current animation. The offset is determined by the type of animation being played (e.g., hand, feet, or torso movement).
+--- Useful for smoothly syncing Mario's model height or positional adjustments during animations function get_character_anim_offset(m) -- ... end @@ -3778,13 +3880,15 @@ end --- @param m MarioState --- @param characterAnim CharacterAnimID --- @return integer ---- Gets the animation ID to use for a specific character and animation combination. The ID is based on `characterAnim` and the character currently controlled by Mario (`m`). Useful for determining which animation to play for actions like walking, jumping, or idle states +--- Gets the animation ID to use for a specific character and animation combination. The ID is based on `characterAnim` and the character currently controlled by Mario (`m`).
+--- Useful for determining which animation to play for actions like walking, jumping, or idle states function get_character_anim(m, characterAnim) -- ... end --- @param m MarioState ---- Updates Mario's current animation offset. This adjusts Mario's position based on the calculated offset to ensure animations appear smooth and natural. Useful for keeping Mario's animations visually aligned, particularly when transitioning between animations +--- Updates Mario's current animation offset. This adjusts Mario's position based on the calculated offset to ensure animations appear smooth and natural.
+--- Useful for keeping Mario's animations visually aligned, particularly when transitioning between animations function update_character_anim_offset(m) -- ... end @@ -4530,7 +4634,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles Mario's interaction with coins. Collecting a coin increases Mario's coin count and heals him slightly. Useful for score, and coin management +--- Handles Mario's interaction with coins. Collecting a coin increases Mario's coin count and heals him slightly.
+--- Useful for score, and coin management function interact_coin(m, interactType, o) -- ... end @@ -4539,7 +4644,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interactions with water rings that heal Mario. Passing through water rings increases his health counter. Useful for underwater stages +--- Handles interactions with water rings that heal Mario. Passing through water rings increases his health counter.
+--- Useful for underwater stages function interact_water_ring(m, interactType, o) -- ... end @@ -4548,7 +4654,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with Stars or Keys. If Mario collects a star or key, it triggers a specific star grab cutscene and progression is updated. Also handles no-exit variants (like the wing cap stage star). Useful for the main progression system of collecting Stars and unlocking new areas +--- Handles interaction with Stars or Keys. If Mario collects a star or key, it triggers a specific star grab cutscene and progression is updated. Also handles no-exit variants (like the wing cap stage star).
+--- Useful for the main progression system of collecting Stars and unlocking new areas function interact_star_or_key(m, interactType, o) -- ... end @@ -4566,7 +4673,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with warps, including warp pipes and hole warps. If Mario steps onto a warp, he either transitions into another area or level. Useful for connecting different parts of the game world and controlling transitions between levels as well as custom warp areas +--- Handles interaction with warps, including warp pipes and hole warps. If Mario steps onto a warp, he either transitions into another area or level.
+--- Useful for connecting different parts of the game world and controlling transitions between levels as well as custom warp areas function interact_warp(m, interactType, o) -- ... end @@ -4575,7 +4683,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with warp doors that lead to other areas or require keys. If Mario can open the door (has enough stars or a key), he proceeds. Otherwise, it may show a dialog. Useful for restricting access to certain areas based on progression +--- Handles interaction with warp doors that lead to other areas or require keys. If Mario can open the door (has enough stars or a key), he proceeds. Otherwise, it may show a dialog.
+--- Useful for restricting access to certain areas based on progression function interact_warp_door(m, interactType, o) -- ... end @@ -4584,7 +4693,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction when Mario touches a door. If Mario meets the star requirement or has the key, he can unlock/open the door. Otherwise, it may display dialog indicating the requirement. Useful for controlling access to locked areas and providing progression gating in the game +--- Handles interaction when Mario touches a door. If Mario meets the star requirement or has the key, he can unlock/open the door. Otherwise, it may display dialog indicating the requirement.
+--- Useful for controlling access to locked areas and providing progression gating in the game function interact_door(m, interactType, o) -- ... end @@ -4593,7 +4703,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction when Mario touches a cannon base. If the cannon is ready, Mario enters the cannon, triggering a special action and camera behavior. Useful for transitioning to cannon-aiming mode and enabling cannon travel within levels +--- Handles interaction when Mario touches a cannon base. If the cannon is ready, Mario enters the cannon, triggering a special action and camera behavior.
+--- Useful for transitioning to cannon-aiming mode and enabling cannon travel within levels function interact_cannon_base(m, interactType, o) -- ... end @@ -4602,7 +4713,9 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with another player (in multiplayer scenarios). Checks if Mario and another player collide and resolves any special behavior like bouncing on top. Useful for multiplayer interactions, such as PvP or cooperative gameplay mechanics +--- Handles interaction with another player (in multiplayer scenarios).
+--- Checks if Mario and another player collide and resolves any special behavior like bouncing on top.
+--- Useful for multiplayer interactions, such as PvP or cooperative gameplay mechanics function interact_player(m, interactType, o) -- ... end @@ -4611,7 +4724,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with the igloo barrier found in Snowman's Land. If Mario runs into the barrier, this function pushes him away and prevents passage without the vanish cap. Useful for enforcing require-caps to access certain areas +--- Handles interaction with the igloo barrier found in Snowman's Land. If Mario runs into the barrier, this function pushes him away and prevents passage without the vanish cap.
+--- Useful for enforcing require-caps to access certain areas function interact_igloo_barrier(m, interactType, o) -- ... end @@ -4620,7 +4734,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with tornados. If Mario touches a tornado, he enters a spinning twirl action, losing control temporarily. Useful for desert levels or areas where environmental hazards lift Mario into the air +--- Handles interaction with tornados. If Mario touches a tornado, he enters a spinning twirl action, losing control temporarily.
+--- Useful for desert levels or areas where environmental hazards lift Mario into the air function interact_tornado(m, interactType, o) -- ... end @@ -4629,7 +4744,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with whirlpools. If Mario gets caught in a whirlpool, he's pulled toward it, resulting in a unique "caught" action. Useful for hazards that trap Mario like whirlpools +--- Handles interaction with whirlpools. If Mario gets caught in a whirlpool, he's pulled toward it, resulting in a unique "caught" action.
+--- Useful for hazards that trap Mario like whirlpools function interact_whirlpool(m, interactType, o) -- ... end @@ -4638,7 +4754,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with strong wind gusts. These gusts push Mario back, often knocking him off platforms or sending him flying backwards. Useful for environmental wind hazards +--- Handles interaction with strong wind gusts. These gusts push Mario back, often knocking him off platforms or sending him flying backwards.
+--- Useful for environmental wind hazards function interact_strong_wind(m, interactType, o) -- ... end @@ -4647,7 +4764,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with flame objects. If Mario touches a flame and is not invulnerable or protected by certain caps, he takes damage and may be set on fire, causing a burning jump. Useful for simulating fire damage and hazards in levels +--- Handles interaction with flame objects. If Mario touches a flame and is not invulnerable or protected by certain caps, he takes damage and may be set on fire, causing a burning jump.
+--- Useful for simulating fire damage and hazards in levels function interact_flame(m, interactType, o) -- ... end @@ -4665,7 +4783,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interactions with objects like Clams or Bubbas, which can damage Mario or, in Bubba's case, eat Mario. If Bubba eats Mario, it triggers a unique "caught" action. Otherwise, it deals damage and knockback if hit by a Clam +--- Handles interactions with objects like Clams or Bubbas, which can damage Mario or, in Bubba's case, eat Mario.
+--- If Bubba eats Mario, it triggers a unique "caught" action. Otherwise, it deals damage and knockback if hit by a Clam function interact_clam_or_bubba(m, interactType, o) -- ... end @@ -4674,7 +4793,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with Bully enemies. Determines if Mario attacks the Bully or gets knocked back. Updates Mario's velocity and state accordingly, and can defeat the Bully if attacked successfully. Useful for enemy encounters that involve pushing and shoving mechanics rather than just stomping like the bullies +--- Handles interaction with Bully enemies. Determines if Mario attacks the Bully or gets knocked back. Updates Mario's velocity and state accordingly, and can defeat the Bully if attacked successfully.
+--- Useful for enemy encounters that involve pushing and shoving mechanics rather than just stomping like the bullies function interact_bully(m, interactType, o) -- ... end @@ -4683,7 +4803,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with shocking objects. If Mario touches an electrified enemy or hazard, he takes damage and may be stunned or shocked. Useful for electric-themed enemies and obstacles +--- Handles interaction with shocking objects. If Mario touches an electrified enemy or hazard, he takes damage and may be stunned or shocked.
+--- Useful for electric-themed enemies and obstacles function interact_shock(m, interactType, o) -- ... end @@ -4692,7 +4813,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with Mr. Blizzard (the snowman enemy) or similar objects. If Mario is attacked or collides with Mr. Blizzard, it applies damage and knockback if not protected or attacking +--- Handles interaction with Mr. Blizzard (the snowman enemy) or similar objects.
+--- If Mario is attacked or collides with Mr. Blizzard, it applies damage and knockback if not protected or attacking function interact_mr_blizzard(m, interactType, o) -- ... end @@ -4701,7 +4823,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interactions where Mario hits an object from below (e.g., hitting a block from underneath). Determines if Mario damages/destroys the object, or if it damages Mario. Useful for handling upward attacks, hitting coin blocks, or interacting with certain NPCs from below +--- Handles interactions where Mario hits an object from below (e.g., hitting a block from underneath). Determines if Mario damages/destroys the object, or if it damages Mario.
+--- Useful for handling upward attacks, hitting coin blocks, or interacting with certain NPCs from below function interact_hit_from_below(m, interactType, o) -- ... end @@ -4710,7 +4833,9 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interactions where Mario bounces off the top of an object (e.g., Goombas, Koopas). Checks if Mario attacks the object from above and applies the appropriate knockback, sound effects, and object state changes. Useful for enemy defeat mechanics and platform bouncing +--- Handles interactions where Mario bounces off the top of an object (e.g., Goombas, Koopas).
+--- Checks if Mario attacks the object from above and applies the appropriate knockback, sound effects, and object state changes.
+--- Useful for enemy defeat mechanics and platform bouncing function interact_bounce_top(m, interactType, o) -- ... end @@ -4719,7 +4844,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with Spiny-walking enemies. If Mario attacks it (e.g., by punching), the enemy is hurt. If he fails to attack properly (say bouncing on top), Mario takes damage and knockback. Useful for enemies that cannot be stomped from above and require direct attacks +--- Handles interaction with Spiny-walking enemies. If Mario attacks it (e.g., by punching), the enemy is hurt. If he fails to attack properly (say bouncing on top), Mario takes damage and knockback.
+--- Useful for enemies that cannot be stomped from above and require direct attacks function interact_spiny_walking(m, interactType, o) -- ... end @@ -4728,7 +4854,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles damaging interactions from various objects (e.g., enemies, hazards). If Mario takes damage, it applies knockback and reduces health. Useful for enemy attacks, environmental hazards, and managing damage related behaviors +--- Handles damaging interactions from various objects (e.g., enemies, hazards). If Mario takes damage, it applies knockback and reduces health.
+--- Useful for enemy attacks, environmental hazards, and managing damage related behaviors function interact_damage(m, interactType, o) -- ... end @@ -4737,7 +4864,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interactions with breakable objects (e.g., breakable boxes or bob-ombs). If Mario hits the object with a valid attack (like a punch or kick), the object is destroyed or changes state. Useful for managing collectible items hidden in breakable objects and level progression through destructible blocks or walls +--- Handles interactions with breakable objects (e.g., breakable boxes or bob-ombs). If Mario hits the object with a valid attack (like a punch or kick), the object is destroyed or changes state.
+--- Useful for managing collectible items hidden in breakable objects and level progression through destructible blocks or walls function interact_breakable(m, interactType, o) -- ... end @@ -4746,7 +4874,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction when Mario touches a Koopa Shell. If conditions are met, Mario can hop onto the shell and start riding it, changing his movement mechanics. Useful for implementing Koopa Shell behavior +--- Handles interaction when Mario touches a Koopa Shell. If conditions are met, Mario can hop onto the shell and start riding it, changing his movement mechanics.
+--- Useful for implementing Koopa Shell behavior function interact_koopa_shell(m, interactType, o) -- ... end @@ -4755,7 +4884,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with poles (e.g., climbing poles). If Mario runs into a vertical pole, he can grab it and start climbing. Useful for platforming mechanics +--- Handles interaction with poles (e.g., climbing poles). If Mario runs into a vertical pole, he can grab it and start climbing.
+--- Useful for platforming mechanics function interact_pole(m, interactType, o) -- ... end @@ -4764,7 +4894,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with Hoot, the owl. If Mario can grab onto Hoot, this sets Mario onto a riding action, allowing him to fly around the level. Useful for special traversal mechanics and shortcuts within a course +--- Handles interaction with Hoot, the owl. If Mario can grab onto Hoot, this sets Mario onto a riding action, allowing him to fly around the level.
+--- Useful for special traversal mechanics and shortcuts within a course function interact_hoot(m, interactType, o) -- ... end @@ -4773,7 +4904,9 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction when Mario picks up a cap object. This includes normal caps, wing caps, vanish caps, and metal caps. Updates Mario's state (e.g., cap timers, sound effects) and may initiate putting on the cap animation. Useful for managing cap statuses +--- Handles interaction when Mario picks up a cap object. This includes normal caps, wing caps, vanish caps, and metal caps.
+--- Updates Mario's state (e.g., cap timers, sound effects) and may initiate putting on the cap animation.
+--- Useful for managing cap statuses function interact_cap(m, interactType, o) -- ... end @@ -4782,7 +4915,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with grabbable objects (e.g., crates, small enemies, or Bowser). Checks if Mario can pick up the object and initiates the grab action if possible. Useful for course mechanics, throwing items, and Bowser +--- Handles interaction with grabbable objects (e.g., crates, small enemies, or Bowser). Checks if Mario can pick up the object and initiates the grab action if possible.
+--- Useful for course mechanics, throwing items, and Bowser function interact_grabbable(m, interactType, o) -- ... end @@ -4791,7 +4925,8 @@ end --- @param interactType integer --- @param o Object --- @return integer ---- Handles interaction with signs, NPCs, and other text-bearing objects. If Mario presses the interact button facing them, he enters a dialog reading state. Useful for managing hints, story elements, or gameplay instructions through in-game dialogue +--- Handles interaction with signs, NPCs, and other text-bearing objects. If Mario presses the interact button facing them, he enters a dialog reading state.
+--- Useful for managing hints, story elements, or gameplay instructions through in-game dialogue function interact_text(m, interactType, o) -- ... end @@ -4799,58 +4934,72 @@ end --- @param m MarioState --- @param o Object --- @return integer ---- Calculates the angle between Mario and a specified object. Used for determining Mario's orientation relative to the object. Useful for deciding directions between Mario and NPCs +--- Calculates the angle between Mario and a specified object. Used for determining Mario's orientation relative to the object.
+--- Useful for deciding directions between Mario and NPCs function mario_obj_angle_to_object(m, o) -- ... end --- @param m MarioState ---- Stops Mario from riding any currently ridden object (e.g., a Koopa shell or Hoot), updating the object's interaction status and Mario's state. Useful for cleanly dismounting ridden objects +--- Stops Mario from riding any currently ridden object (e.g., a Koopa shell or Hoot), updating the object's interaction status and Mario's state.
+--- Useful for cleanly dismounting ridden objects function mario_stop_riding_object(m) -- ... end --- @param m MarioState ---- Grabs the object currently referenced by Mario's `usedObj` if it's not already being held. Changes the object's state to indicate it is now held by Mario. Useful for handling the moment Mario successfully picks up an object +--- Grabs the object currently referenced by Mario's `usedObj` if it's not already being held.
+--- Changes the object's state to indicate it is now held by Mario.
+--- Useful for handling the moment Mario successfully picks up an object function mario_grab_used_object(m) -- ... end --- @param m MarioState ---- Causes Mario to drop the object he is currently holding. Sets the held object's state accordingly and places it in front of Mario. Useful for releasing carried objects, such as throwing Bob-ombs or setting down crates +--- Causes Mario to drop the object he is currently holding. Sets the held object's state accordingly and places it in front of Mario.
+--- Useful for releasing carried objects, such as throwing Bob-ombs or setting down crates function mario_drop_held_object(m) -- ... end --- @param m MarioState ---- Throws the object Mario is currently holding. The object is placed in front of Mario and given a forward velocity. Useful for attacking enemies with thrown objects, solving puzzles by throwing crates, or interacting with environment items +--- Throws the object Mario is currently holding. The object is placed in front of Mario and given a forward velocity.
+--- Useful for attacking enemies with thrown objects, solving puzzles by throwing crates, or interacting with environment items function mario_throw_held_object(m) -- ... end --- @param m MarioState ---- Causes Mario to stop riding any object (like a shell or Hoot) and also drop any held object. Resets related states to ensure Mario is no longer attached to or holding anything. Useful when changing Mario's state after certain actions, transitions, or to prevent exploits +--- Causes Mario to stop riding any object (like a shell or Hoot) and also drop any held object.
+--- Resets related states to ensure Mario is no longer attached to or holding anything.
+--- Useful when changing Mario's state after certain actions, transitions, or to prevent exploits function mario_stop_riding_and_holding(m) -- ... end --- @param m MarioState --- @return integer ---- Checks if Mario is currently wearing his normal cap on his head. Returns true if Mario's flag state matches that of having the normal cap equipped on his head, otherwise false. Useful for determining Mario's cap status +--- Checks if Mario is currently wearing his normal cap on his head.
+--- Returns true if Mario's flag state matches that of having the normal cap equipped on his head, otherwise false.
+--- Useful for determining Mario's cap status function does_mario_have_normal_cap_on_head(m) -- ... end --- @param m MarioState --- @return boolean ---- Checks if Mario has already had a cap blown off of his head in the current level, Returns true if a blown cap can be found for Mario, false if not. Useful to check if a blown cap exists in the level currently. +--- Checks if Mario has already had a cap blown off of his head in the current level,
+--- Returns true if a blown cap can be found for Mario, false if not.
+--- Useful to check if a blown cap exists in the level currently. function does_mario_have_blown_cap(m) -- ... end --- @param m MarioState --- @param capSpeed number ---- Makes Mario blow off his normal cap at a given speed. Removes the normal cap from Mario's head and spawns it as a collectible object in the game world. Useful for simulating events where Mario loses his cap due to enemy attacks or environmental forces +--- Makes Mario blow off his normal cap at a given speed.
+--- Removes the normal cap from Mario's head and spawns it as a collectible object in the game world.
+--- Useful for simulating events where Mario loses his cap due to enemy attacks or environmental forces function mario_blow_off_cap(m, capSpeed) -- ... end @@ -4858,13 +5007,17 @@ end --- @param m MarioState --- @param arg integer --- @return integer ---- Makes Mario lose his normal cap to an enemy, such as Klepto or Ukiki. Updates flags so that the cap is no longer on Mario's head. Returns true if Mario was wearing his normal cap, otherwise false. Useful for scenarios where enemies steal Mario's cap +--- Makes Mario lose his normal cap to an enemy, such as Klepto or Ukiki. Updates flags so that the cap is no longer on Mario's head.
+--- Returns true if Mario was wearing his normal cap, otherwise false.
+--- Useful for scenarios where enemies steal Mario's cap function mario_lose_cap_to_enemy(m, arg) -- ... end --- @param m MarioState ---- Retrieves Mario's normal cap if it was previously lost. Removes the cap from Mario's hand state and places it on his head. Useful when Mario recovers his normal cap from enemies, finds it in a level, or if it were to disappear +--- Retrieves Mario's normal cap if it was previously lost.
+--- Removes the cap from Mario's hand state and places it on his head.
+--- Useful when Mario recovers his normal cap from enemies, finds it in a level, or if it were to disappear function mario_retrieve_cap(m) -- ... end @@ -4872,21 +5025,24 @@ end --- @param m MarioState --- @param interactType integer --- @return Object ---- Returns a collided object that matches a given interaction type from Mario's current collision data. Useful for determining which object Mario has come into contact with +--- Returns a collided object that matches a given interaction type from Mario's current collision data.
+--- Useful for determining which object Mario has come into contact with function mario_get_collided_object(m, interactType) -- ... end --- @param m MarioState --- @return integer ---- Checks if Mario can grab the currently encountered object (usually triggered when Mario punches or dives). If conditions are met, initiates the grabbing process. Useful for picking up objects, throwing enemies, or grabbing special items +--- Checks if Mario can grab the currently encountered object (usually triggered when Mario punches or dives). If conditions are met, initiates the grabbing process.
+--- Useful for picking up objects, throwing enemies, or grabbing special items function mario_check_object_grab(m) -- ... end --- @param door Object --- @return integer ---- Retrieves the save file flag associated with a door, based on the number of stars required to open it. Used to check if the player has unlocked certain star doors or progressed far enough to access new areas +--- Retrieves the save file flag associated with a door, based on the number of stars required to open it.
+--- Used to check if the player has unlocked certain star doors or progressed far enough to access new areas function get_door_save_file_flag(door) -- ... end @@ -4894,7 +5050,9 @@ end --- @param attacker MarioState --- @param victim MarioState --- @return integer ---- Checks if the necessary conditions are met for one player to successfully attack another player in a PvP scenario. Considers factors like invincibility, action states, and whether the attack is valid. Useful for multiplayer where players can harm each other +--- Checks if the necessary conditions are met for one player to successfully attack another player in a PvP scenario.
+--- Considers factors like invincibility, action states, and whether the attack is valid.
+--- Useful for multiplayer where players can harm each other function passes_pvp_interaction_checks(attacker, victim) -- ... end @@ -4902,7 +5060,8 @@ end --- @param m MarioState --- @param o Object --- @return integer ---- Determines whether Mario should push or pull a door when he interacts with it, based on his orientation and position. Useful for animating door interactions realistically, depending on which side Mario approaches from +--- Determines whether Mario should push or pull a door when he interacts with it, based on his orientation and position.
+--- Useful for animating door interactions realistically, depending on which side Mario approaches from function should_push_or_pull_door(m, o) -- ... end @@ -4910,14 +5069,17 @@ end --- @param m MarioState --- @param o Object --- @return integer ---- Handles the logic of Mario taking damage and being knocked back by a damaging object. Decreases Mario's health, sets his knockback state, and triggers appropriate sound and camera effects. Useful for implementing enemy attacks, hazards, and ensuring Mario receives proper feedback upon taking damage +--- Handles the logic of Mario taking damage and being knocked back by a damaging object.
+--- Decreases Mario's health, sets his knockback state, and triggers appropriate sound and camera effects.
+--- Useful for implementing enemy attacks, hazards, and ensuring Mario receives proper feedback upon taking damage function take_damage_and_knock_back(m, o) -- ... end --- @param capObject Object --- @return integer ---- Determines the type of cap an object represents. Depending on the object's behavior, it returns a cap type (normal, metal, wing, vanish). Useful for handling the logic of picking up, wearing, or losing different kinds of caps +--- Determines the type of cap an object represents. Depending on the object's behavior, it returns a cap type (normal, metal, wing, vanish).
+--- Useful for handling the logic of picking up, wearing, or losing different kinds of caps function get_mario_cap_flag(capObject) -- ... end @@ -4925,7 +5087,9 @@ end --- @param m MarioState --- @param o Object --- @return integer ---- Determines how Mario interacts with a given object based on his current action, position, and other state variables. Calculates the appropriate interaction type (e.g., punch, kick, ground pound) that should result from Mario's contact with the specified object (`o`). Useful for handling different types of player-object collisions, attacks, and object behaviors +--- Determines how Mario interacts with a given object based on his current action, position, and other state variables.
+--- Calculates the appropriate interaction type (e.g., punch, kick, ground pound) that should result from Mario's contact with the specified object (`o`).
+--- Useful for handling different types of player-object collisions, attacks, and object behaviors function determine_interaction(m, o) -- ... end @@ -4959,7 +5123,8 @@ end --- @param areaIndex integer --- @param charCase integer --- @return string ---- Returns the name of the level corresponding to `courseNum`, `levelNum` and `areaIndex` as an ASCII (human readable) string. Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string +--- Returns the name of the level corresponding to `courseNum`, `levelNum` and `areaIndex` as an ASCII (human readable) string.
+--- Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string function get_level_name_ascii(courseNum, levelNum, areaIndex, charCase) -- ... end @@ -4969,7 +5134,9 @@ end --- @param areaIndex integer --- @param charCase integer --- @return Pointer_integer ---- Returns the name of the level corresponding to `courseNum`, `levelNum` and `areaIndex` as an SM64 encoded string. This function should not be used in Lua mods. Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string +--- Returns the name of the level corresponding to `courseNum`, `levelNum` and `areaIndex` as an SM64 encoded string.
+--- This function should not be used in Lua mods.
+--- Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string function get_level_name_sm64(courseNum, levelNum, areaIndex, charCase) -- ... end @@ -4987,7 +5154,8 @@ end --- @param starNum integer --- @param charCase integer --- @return string ---- Returns the name of the star corresponding to `courseNum` and `starNum` as an ASCII (human readable) string. Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string +--- Returns the name of the star corresponding to `courseNum` and `starNum` as an ASCII (human readable) string.
+--- Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string function get_star_name_ascii(courseNum, starNum, charCase) -- ... end @@ -4996,7 +5164,9 @@ end --- @param starNum integer --- @param charCase integer --- @return Pointer_integer ---- Returns the name of the star corresponding to `courseNum` and `starNum` as an SM64 encoded string. This function should not be used in Lua mods. Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string +--- Returns the name of the star corresponding to `courseNum` and `starNum` as an SM64 encoded string.
+--- This function should not be used in Lua mods.
+--- Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string function get_star_name_sm64(courseNum, starNum, charCase) -- ... end @@ -5016,7 +5186,9 @@ end --- @param checkpoint integer --- @param o Object --- @return ObjectWarpNode ---- Creates a warp node in the current level and area with id `id` that goes to the warp node `destNode` in level `destLevel` and area `destArea`, and attach it to the object `o`. To work properly, object `o` must be able to trigger a warp (for example, with interact type set to `INTERACT_WARP`.) `checkpoint` should be set only to WARP_NO_CHECKPOINT (0x00) or WARP_CHECKPOINT (0x80.) If `checkpoint` is set to `0x80`, Mario will warp directly to this node if he enters the level again (after a death for example) +--- Creates a warp node in the current level and area with id `id` that goes to the warp node `destNode` in level `destLevel` and area `destArea`, and attach it to the object `o`.
+--- To work properly, object `o` must be able to trigger a warp (for example, with interact type set to `INTERACT_WARP`.)
+--- `checkpoint` should be set only to WARP_NO_CHECKPOINT (0x00) or WARP_CHECKPOINT (0x80.) If `checkpoint` is set to `0x80`, Mario will warp directly to this node if he enters the level again (after a death for example) function area_create_warp_node(id, destLevel, destArea, destNode, checkpoint, o) -- ... end @@ -5279,14 +5451,16 @@ end --- @param m MarioState --- @return integer ---- Checks if Mario's current animation has reached its final frame (i.e., the last valid frame in the animation). Useful for deciding when to transition out of an animation-driven action +--- Checks if Mario's current animation has reached its final frame (i.e., the last valid frame in the animation).
+--- Useful for deciding when to transition out of an animation-driven action function is_anim_at_end(m) -- ... end --- @param m MarioState --- @return integer ---- Checks if Mario's current animation has passed the second-to-last valid frame (i.e., effectively at or beyond its final frames). Useful for advanced checks where slightly early transitions or timing are needed before the final frame +--- Checks if Mario's current animation has passed the second-to-last valid frame (i.e., effectively at or beyond its final frames).
+--- Useful for advanced checks where slightly early transitions or timing are needed before the final frame function is_anim_past_end(m) -- ... end @@ -5303,7 +5477,8 @@ end --- @param targetAnimID integer --- @param accel integer --- @return integer ---- Sets Mario's current animation to `targetAnimID` with a custom `accel` value to speed up or slow down the animation. Useful for controlling animation timing, e.g., slow-motion or fast-forward effects +--- Sets Mario's current animation to `targetAnimID` with a custom `accel` value to speed up or slow down the animation.
+--- Useful for controlling animation timing, e.g., slow-motion or fast-forward effects function set_mario_anim_with_accel(m, targetAnimID, accel) -- ... end @@ -5320,7 +5495,8 @@ end --- @param targetAnimID CharacterAnimID --- @param accel integer --- @return integer ---- Sets a character-specific animation where the animation speed is adjusted by `accel`. Useful for varying animation speeds based on context or dynamic conditions (e.g., slow-motion) +--- Sets a character-specific animation where the animation speed is adjusted by `accel`.
+--- Useful for varying animation speeds based on context or dynamic conditions (e.g., slow-motion) function set_character_anim_with_accel(m, targetAnimID, accel) -- ... end @@ -5335,7 +5511,8 @@ end --- @param m MarioState --- @param animFrame integer --- @return integer ---- Checks if Mario's current animation is past a specified `animFrame`. Useful for conditional logic where an action can branch after reaching a specific point in the animation +--- Checks if Mario's current animation is past a specified `animFrame`.
+--- Useful for conditional logic where an action can branch after reaching a specific point in the animation function is_anim_past_frame(m, animFrame) -- ... end @@ -5344,7 +5521,8 @@ end --- @param yaw integer --- @param translation Vec3s --- @return integer ---- Retrieves the current animation flags and calculates the translation for Mario's animation, rotating it into the global coordinate system based on `yaw`. Useful for determining positional offsets from animations (e.g., stepping forward in a walk animation) and applying them to Mario's position +--- Retrieves the current animation flags and calculates the translation for Mario's animation, rotating it into the global coordinate system based on `yaw`.
+--- Useful for determining positional offsets from animations (e.g., stepping forward in a walk animation) and applying them to Mario's position function find_mario_anim_flags_and_translation(o, yaw, translation) -- ... end @@ -5357,7 +5535,8 @@ end --- @param m MarioState --- @return integer ---- Determines the vertical translation from Mario's animation (how much the animation moves Mario up or down). Returns the y-component of the animation's translation. Useful for adjusting Mario's vertical position based on an ongoing animation (e.g., a bounce or jump) +--- Determines the vertical translation from Mario's animation (how much the animation moves Mario up or down). Returns the y-component of the animation's translation.
+--- Useful for adjusting Mario's vertical position based on an ongoing animation (e.g., a bounce or jump) function return_mario_anim_y_translation(m) -- ... end @@ -5377,7 +5556,8 @@ function play_mario_jump_sound(m) end --- @param m MarioState ---- Adjusts the pitch/volume of Mario's movement-based sounds according to his forward velocity (`m.forwardVel`). Useful for adding dynamic audio feedback based on Mario's running or walking speed +--- Adjusts the pitch/volume of Mario's movement-based sounds according to his forward velocity (`m.forwardVel`).
+--- Useful for adding dynamic audio feedback based on Mario's running or walking speed function adjust_sound_for_speed(m) -- ... end @@ -5414,14 +5594,16 @@ end --- @param m MarioState --- @param soundBits integer ---- Plays a heavier, more forceful landing sound, possibly for ground pounds or large impacts. Takes into account whether Mario has a metal cap equipped. Useful for making big impact landings stand out aurally +--- Plays a heavier, more forceful landing sound, possibly for ground pounds or large impacts. Takes into account whether Mario has a metal cap equipped.
+--- Useful for making big impact landings stand out aurally function play_mario_heavy_landing_sound(m, soundBits) -- ... end --- @param m MarioState --- @param soundBits integer ---- A variant of `play_mario_heavy_landing_sound` that ensures the sound is only played once per action (using `play_mario_action_sound` internally). Useful for consistent heavy landing effects without repetition +--- A variant of `play_mario_heavy_landing_sound` that ensures the sound is only played once per action (using `play_mario_action_sound` internally).
+--- Useful for consistent heavy landing effects without repetition function play_mario_heavy_landing_sound_once(m, soundBits) -- ... end @@ -5463,21 +5645,24 @@ end --- @param m MarioState --- @param speed number ---- Sets Mario's forward velocity (`m.forwardVel`) and updates `slideVelX/Z` and `m.vel` accordingly, based on `m.faceAngle.y`. Useful for controlling Mario's speed and direction in various actions (jumping, walking, sliding, etc.) +--- Sets Mario's forward velocity (`m.forwardVel`) and updates `slideVelX/Z` and `m.vel` accordingly, based on `m.faceAngle.y`.
+--- Useful for controlling Mario's speed and direction in various actions (jumping, walking, sliding, etc.) function mario_set_forward_vel(m, speed) -- ... end --- @param m MarioState --- @return integer ---- Retrieves the slipperiness class of Mario's current floor, ranging from not slippery to very slippery. Considers terrain types and special surfaces. Useful for controlling friction, movement speed adjustments, and whether Mario slips or walks +--- Retrieves the slipperiness class of Mario's current floor, ranging from not slippery to very slippery. Considers terrain types and special surfaces.
+--- Useful for controlling friction, movement speed adjustments, and whether Mario slips or walks function mario_get_floor_class(m) -- ... end --- @param m MarioState --- @return integer ---- Computes a value added to terrain sounds, depending on the floor's type (sand, snow, water, etc.) and slipperiness. This returns a sound 'addend' used with sound effects. Useful for playing context-specific footstep or movement sounds +--- Computes a value added to terrain sounds, depending on the floor's type (sand, snow, water, etc.) and slipperiness. This returns a sound 'addend' used with sound effects.
+--- Useful for playing context-specific footstep or movement sounds function mario_get_terrain_sound_addend(m) -- ... end @@ -5486,7 +5671,8 @@ end --- @param offset number --- @param radius number --- @return Surface ---- Checks for and resolves wall collisions at a given position `pos`, returning the last wall encountered. Primarily used to prevent Mario from going through walls. Useful for collision detection when updating Mario's movement or adjusting his position +--- Checks for and resolves wall collisions at a given position `pos`, returning the last wall encountered. Primarily used to prevent Mario from going through walls.
+--- Useful for collision detection when updating Mario's movement or adjusting his position function resolve_and_return_wall_collisions(pos, offset, radius) -- ... end @@ -5504,7 +5690,8 @@ end --- @param height number --- @return number --- @return Surface ceil ---- Finds the ceiling from a vec3f horizontally and a height (with 80 vertical buffer). Returns the ceiling height and surface +--- Finds the ceiling from a vec3f horizontally and a height (with 80 vertical buffer).
+--- Returns the ceiling height and surface function vec3f_find_ceil(pos, height) -- ... end @@ -5513,7 +5700,9 @@ end --- @param height number --- @return number --- @return Surface ceil ---- Finds the ceiling from a vec3f horizontally and a height (with 80 vertical buffer). Prevents exposed ceiling bug. Returns the ceiling height and surface +--- Finds the ceiling from a vec3f horizontally and a height (with 80 vertical buffer).
+--- Prevents exposed ceiling bug.
+--- Returns the ceiling height and surface function vec3f_mario_ceil(pos, height) -- ... end @@ -5521,14 +5710,16 @@ end --- @param m MarioState --- @param turnYaw integer --- @return integer ---- Determines if Mario is facing downhill relative to his floor angle, optionally accounting for forward velocity direction. Returns true if he is oriented down the slope. Useful for deciding if Mario will walk or slide on sloped floors +--- Determines if Mario is facing downhill relative to his floor angle, optionally accounting for forward velocity direction. Returns true if he is oriented down the slope.
+--- Useful for deciding if Mario will walk or slide on sloped floors function mario_facing_downhill(m, turnYaw) -- ... end --- @param m MarioState --- @return integer ---- Checks whether Mario's current floor is slippery based on both the floor's surface class and Mario's environment (e.g., special slides). Useful for deciding if Mario should transition to sliding or maintain normal traction +--- Checks whether Mario's current floor is slippery based on both the floor's surface class and Mario's environment (e.g., special slides).
+--- Useful for deciding if Mario should transition to sliding or maintain normal traction function mario_floor_is_slippery(m) -- ... end @@ -5542,7 +5733,8 @@ end --- @param m MarioState --- @return integer ---- Checks whether Mario's floor is steep enough to cause special behavior, such as forcing slides or preventing certain actions. Returns true if the slope is too steep. Useful for restricting normal movement on surfaces with extreme angles +--- Checks whether Mario's floor is steep enough to cause special behavior, such as forcing slides or preventing certain actions. Returns true if the slope is too steep.
+--- Useful for restricting normal movement on surfaces with extreme angles function mario_floor_is_steep(m) -- ... end @@ -5551,7 +5743,8 @@ end --- @param angleFromMario integer --- @param distFromMario number --- @return number ---- Finds the floor height relative to Mario's current position given a polar displacement (`angleFromMario`, `distFromMario`). Useful for determining height differentials ahead or behind Mario, e.g. for slope checks or collision logic +--- Finds the floor height relative to Mario's current position given a polar displacement (`angleFromMario`, `distFromMario`).
+--- Useful for determining height differentials ahead or behind Mario, e.g. for slope checks or collision logic function find_floor_height_relative_polar(m, angleFromMario, distFromMario) -- ... end @@ -5559,19 +5752,22 @@ end --- @param m MarioState --- @param yawOffset integer --- @return integer ---- Returns a slope angle based on comparing the floor heights slightly in front and behind Mario. It essentially calculates how steep the ground is in a specific yaw direction. Useful for slope-based calculations such as setting walking or sliding behaviors +--- Returns a slope angle based on comparing the floor heights slightly in front and behind Mario. It essentially calculates how steep the ground is in a specific yaw direction.
+--- Useful for slope-based calculations such as setting walking or sliding behaviors function find_floor_slope(m, yawOffset) -- ... end --- @param m MarioState ---- Updates the background noise and camera modes based on Mario's action. Especially relevant for actions like first-person view or sleeping. Useful for synchronizing camera behavior and ambient sounds with Mario's state changes +--- Updates the background noise and camera modes based on Mario's action. Especially relevant for actions like first-person view or sleeping.
+--- Useful for synchronizing camera behavior and ambient sounds with Mario's state changes function update_mario_sound_and_camera(m) -- ... end --- @param m MarioState ---- Transitions Mario into ACT_STEEP_JUMP if the floor is too steep, adjusting his forward velocity and orientation accordingly. Useful for forcing special jump states on surfaces exceeding normal slope limits +--- Transitions Mario into ACT_STEEP_JUMP if the floor is too steep, adjusting his forward velocity and orientation accordingly.
+--- Useful for forcing special jump states on surfaces exceeding normal slope limits function set_steep_jump_action(m) -- ... end @@ -5630,7 +5826,8 @@ end --- @param m MarioState --- @return integer ---- Checks for inputs that cause common action transitions (jump, freefall, walking, sliding). Useful for quickly exiting certain stationary actions when Mario begins moving or leaves the floor +--- Checks for inputs that cause common action transitions (jump, freefall, walking, sliding).
+--- Useful for quickly exiting certain stationary actions when Mario begins moving or leaves the floor function check_common_action_exits(m) -- ... end @@ -5644,7 +5841,8 @@ end --- @param m MarioState --- @return integer ---- Transitions Mario from being underwater to a walking state. Resets camera to the default mode and can handle object-holding states. Useful for restoring standard ground movement when emerging from water +--- Transitions Mario from being underwater to a walking state. Resets camera to the default mode and can handle object-holding states.
+--- Useful for restoring standard ground movement when emerging from water function transition_submerged_to_walking(m) -- ... end @@ -5665,7 +5863,8 @@ end --- @param m MarioState --- @return integer ---- Forces Mario into an idle state, either `ACT_IDLE` or `ACT_WATER_IDLE` depending on whether he is submerged. Useful for quickly resetting Mario's state to an idle pose under special conditions (e.g., cutscene triggers) +--- Forces Mario into an idle state, either `ACT_IDLE` or `ACT_WATER_IDLE` depending on whether he is submerged.
+--- Useful for quickly resetting Mario's state to an idle pose under special conditions (e.g., cutscene triggers) function force_idle_state(m) -- ... end @@ -5702,26 +5901,31 @@ end --- @param frame1 integer --- @param frame2 integer --- @param frame3 integer ---- Plays a spinning sound at specific animation frames for flips (usually side flips or certain jump flips). If the current animation frame matches any of the specified frames, it triggers `SOUND_ACTION_SPIN` +--- Plays a spinning sound at specific animation frames for flips (usually side flips or certain jump flips).
+--- If the current animation frame matches any of the specified frames, it triggers `SOUND_ACTION_SPIN` function play_flip_sounds(m, frame1, frame2, frame3) -- ... end --- @param m MarioState ---- Plays a unique sound when Mario has fallen a significant distance without being invulnerable, twirling, or flying. If the fall exceeds a threshold, triggers a "long fall" exclamation. Also sets a flag to prevent repeated triggering +--- Plays a unique sound when Mario has fallen a significant distance without being invulnerable, twirling, or flying.
+--- If the fall exceeds a threshold, triggers a "long fall" exclamation. Also sets a flag to prevent repeated triggering function play_far_fall_sound(m) -- ... end --- @param m MarioState ---- Plays a knockback sound effect if Mario is hit or knocked back with significant velocity. The specific sound differs depending on whether Mario's forward velocity is high enough to be considered a strong knockback +--- Plays a knockback sound effect if Mario is hit or knocked back with significant velocity. The specific sound differs
+--- depending on whether Mario's forward velocity is high enough to be considered a strong knockback function play_knockback_sound(m) -- ... end --- @param m MarioState --- @return integer ---- Allows Mario to 'lava boost' off a lava wall, reorienting him to face away from the wall and adjusting forward velocity. Increases Mario's hurt counter if he's not metal, plays a burning sound, and transitions his action to `ACT_LAVA_BOOST`. Useful for handling collisions with lava walls, giving Mario a strong upward/forward boost at the cost of health +--- Allows Mario to 'lava boost' off a lava wall, reorienting him to face away from the wall and adjusting forward velocity.
+--- Increases Mario's hurt counter if he's not metal, plays a burning sound, and transitions his action to `ACT_LAVA_BOOST`.
+--- Useful for handling collisions with lava walls, giving Mario a strong upward/forward boost at the cost of health function lava_boost_on_wall(m) -- ... end @@ -5729,21 +5933,27 @@ end --- @param m MarioState --- @param hardFallAction integer --- @return integer ---- Evaluates whether Mario should take fall damage based on the height difference between his peak and current position. If the fall is large enough and does not occur over burning surfaces or while twirling, Mario may get hurt or enter a hard fall action. If the fall is significant but not extreme, minimal damage and a squish effect may be applied. Useful for determining if Mario's fall warrants a health penalty or a special landing action +--- Evaluates whether Mario should take fall damage based on the height difference between his peak and current position.
+--- If the fall is large enough and does not occur over burning surfaces or while twirling, Mario may get hurt or enter
+--- a hard fall action. If the fall is significant but not extreme, minimal damage and a squish effect may be applied.
+--- Useful for determining if Mario's fall warrants a health penalty or a special landing action function check_fall_damage(m, hardFallAction) -- ... end --- @param m MarioState --- @return integer ---- Checks if Mario should perform a kick or a dive while in mid-air, depending on his current forward velocity. Pressing the B button in the air can trigger a jump kick (at lower speeds) or a dive (at higher speeds) +--- Checks if Mario should perform a kick or a dive while in mid-air, depending on his current forward velocity.
+--- Pressing the B button in the air can trigger a jump kick (at lower speeds) or a dive (at higher speeds) function check_kick_or_dive_in_air(m) -- ... end --- @param m MarioState --- @return integer ---- Determines whether Mario should become stuck in the ground after landing, specifically for soft terrain such as snow or sand, provided certain conditions are met (height of the fall, normal of the floor, etc.). Returns true if Mario should be stuck, false otherwise +--- Determines whether Mario should become stuck in the ground after landing, specifically for soft terrain such as snow
+--- or sand, provided certain conditions are met (height of the fall, normal of the floor, etc.).
+--- Returns true if Mario should be stuck, false otherwise function should_get_stuck_in_ground(m) -- ... end @@ -5751,50 +5961,59 @@ end --- @param m MarioState --- @param hardFallAction integer --- @return integer ---- Checks if Mario should get stuck in the ground after a large fall onto soft terrain (like snow or sand) or if he should just proceed with regular fall damage calculations. If the terrain and height conditions are met, Mario's action changes to being stuck in the ground. Otherwise, normal fall damage logic applies +--- Checks if Mario should get stuck in the ground after a large fall onto soft terrain (like snow or sand) or if he
+--- should just proceed with regular fall damage calculations. If the terrain and height conditions are met, Mario's
+--- action changes to being stuck in the ground. Otherwise, normal fall damage logic applies function check_fall_damage_or_get_stuck(m, hardFallAction) -- ... end --- @param m MarioState --- @return integer ---- Checks for the presence of a horizontal wind surface under Mario. If found, applies a push force to Mario's horizontal velocity. Caps speed at certain thresholds, updates Mario's forward velocity and yaw for sliding/wind movement +--- Checks for the presence of a horizontal wind surface under Mario. If found, applies a push force to Mario's horizontal
+--- velocity. Caps speed at certain thresholds, updates Mario's forward velocity and yaw for sliding/wind movement function check_horizontal_wind(m) -- ... end --- @param m MarioState ---- Updates Mario's air movement while allowing him to turn. Checks horizontal wind and applies a moderate amount of drag, approaches the forward velocity toward zero if no input is pressed, and modifies forward velocity/angle based on stick input +--- Updates Mario's air movement while allowing him to turn. Checks horizontal wind and applies a moderate amount of drag,
+--- approaches the forward velocity toward zero if no input is pressed, and modifies forward velocity/angle based on stick input function update_air_with_turn(m) -- ... end --- @param m MarioState ---- Updates Mario's air movement without directly turning his facing angle to match his intended yaw. Instead, Mario can move sideways relative to his current facing direction. Also checks horizontal wind and applies drag +--- Updates Mario's air movement without directly turning his facing angle to match his intended yaw. Instead, Mario can
+--- move sideways relative to his current facing direction. Also checks horizontal wind and applies drag function update_air_without_turn(m) -- ... end --- @param m MarioState ---- Updates Mario's movement when in actions like lava boost or twirling in mid-air. Applies player input to adjust forward velocity and facing angle, but in a more restricted manner compared to standard jump movement. Used by `ACT_LAVA_BOOST` and `ACT_TWIRLING` +--- Updates Mario's movement when in actions like lava boost or twirling in mid-air. Applies player input to adjust forward velocity
+--- and facing angle, but in a more restricted manner compared to standard jump movement. Used by `ACT_LAVA_BOOST` and `ACT_TWIRLING` function update_lava_boost_or_twirling(m) -- ... end --- @param m MarioState ---- Calculates and applies a change in Mario's yaw while flying, based on horizontal stick input. Approaches a target yaw velocity and sets Mario's roll angle to simulate banking turns. This results in a more natural, curved flight path +--- Calculates and applies a change in Mario's yaw while flying, based on horizontal stick input. Approaches a target yaw velocity
+--- and sets Mario's roll angle to simulate banking turns. This results in a more natural, curved flight path function update_flying_yaw(m) -- ... end --- @param m MarioState ---- Calculates and applies a change in Mario's pitch while flying, based on vertical stick input. Approaches a target pitch velocity and clamps the final pitch angle to a certain range, simulating a smooth flight control +--- Calculates and applies a change in Mario's pitch while flying, based on vertical stick input. Approaches a target pitch velocity
+--- and clamps the final pitch angle to a certain range, simulating a smooth flight control function update_flying_pitch(m) -- ... end --- @param m MarioState ---- Handles the complete flying logic for Mario (usually with the wing cap). Continuously updates pitch and yaw based on controller input, applies drag, and adjusts forward velocity. Also updates Mario's model angles for flight animations +--- Handles the complete flying logic for Mario (usually with the wing cap). Continuously updates pitch and yaw based on controller input,
+--- applies drag, and adjusts forward velocity. Also updates Mario's model angles for flight animations function update_flying(m) -- ... end @@ -5804,7 +6023,9 @@ end --- @param animation integer --- @param stepArg integer --- @return integer ---- Performs a standard step update for air actions without knockback, typically used for jumps or freefalls. Updates Mario's velocity (and possibly checks horizontal wind), then calls `perform_air_step` with given `stepArg`. Handles how Mario lands, hits walls, grabs ledges, or grabs ceilings. Optionally sets an animation +--- Performs a standard step update for air actions without knockback, typically used for jumps or freefalls.
+--- Updates Mario's velocity (and possibly checks horizontal wind), then calls `perform_air_step` with given `stepArg`.
+--- Handles how Mario lands, hits walls, grabs ledges, or grabs ceilings. Optionally sets an animation function common_air_action_step(m, landAction, animation, stepArg) -- ... end @@ -5815,34 +6036,40 @@ end --- @param animation integer --- @param speed number --- @return integer ---- A shared step update used for airborne knockback states (both forward and backward). Updates velocity, calls `perform_air_step`, and handles wall collisions or landing transitions to appropriate ground knockback actions. Also sets animation and speed +--- A shared step update used for airborne knockback states (both forward and backward). Updates velocity, calls `perform_air_step`,
+--- and handles wall collisions or landing transitions to appropriate ground knockback actions. Also sets animation and speed function common_air_knockback_step(m, landAction, hardFallAction, animation, speed) -- ... end --- @param m MarioState --- @return integer ---- Checks if Mario should wall kick after performing an air hit against a wall. If the input conditions (e.g., pressing A) and the `wallKickTimer` allow, Mario transitions to `ACT_WALL_KICK_AIR` +--- Checks if Mario should wall kick after performing an air hit against a wall. If the input conditions (e.g., pressing A)
+--- and the `wallKickTimer` allow, Mario transitions to `ACT_WALL_KICK_AIR` function check_wall_kick(m) -- ... end --- @param m MarioState --- @return integer ---- Checks for and handles common conditions that would cancel Mario's current air action. This includes transitioning to a water plunge if below the water level, becoming squished if appropriate, or switching to vertical wind action if on certain wind surfaces. Also resets `m.quicksandDepth` +--- Checks for and handles common conditions that would cancel Mario's current air action. This includes transitioning
+--- to a water plunge if below the water level, becoming squished if appropriate, or switching to vertical wind action
+--- if on certain wind surfaces. Also resets `m.quicksandDepth` function check_common_airborne_cancels(m) -- ... end --- @param m MarioState --- @return integer ---- Executes Mario's current airborne action by first checking common airborne cancels, then playing a far-fall sound if needed. Dispatches to the appropriate action function, such as jump, double jump, freefall, etc +--- Executes Mario's current airborne action by first checking common airborne cancels, then playing a far-fall sound if needed.
+--- Dispatches to the appropriate action function, such as jump, double jump, freefall, etc function mario_execute_airborne_action(m) -- ... end --- @param m MarioState ---- Spawns leaf particles when Mario climbs a tree, if he is sufficiently high above the floor. In Shifting Sand Land, the leaf effect spawns higher due to the taller palm trees +--- Spawns leaf particles when Mario climbs a tree, if he is sufficiently high above the floor.
+--- In Shifting Sand Land, the leaf effect spawns higher due to the taller palm trees function add_tree_leaf_particles(m) -- ... end @@ -5857,7 +6084,8 @@ end --- @param m MarioState --- @param offsetY number --- @return integer ---- Sets Mario's position and alignment while he is on a climbable pole or tree. This function checks collisions with floors and ceilings, and updates Mario's action if he leaves the pole or touches the floor. Useful for ensuring Mario's correct placement and transitions when climbing poles or trees +--- Sets Mario's position and alignment while he is on a climbable pole or tree. This function checks collisions with floors and ceilings, and updates Mario's action if he leaves the pole or touches the floor.
+--- Useful for ensuring Mario's correct placement and transitions when climbing poles or trees function set_pole_position(m, offsetY) -- ... end @@ -5925,7 +6153,8 @@ end --- @param m MarioState --- @return integer ---- Executes Mario's current automatic action (e.g., climbing a pole, hanging, ledge-grabbing) by calling the corresponding function. It also checks for common cancellations, like falling into water. Returns true if the action was canceled and a new action was set, or false otherwise +--- Executes Mario's current automatic action (e.g., climbing a pole, hanging, ledge-grabbing) by calling the corresponding function. It also checks for common cancellations, like falling into water.
+--- Returns true if the action was canceled and a new action was set, or false otherwise function mario_execute_automatic_action(m) -- ... end @@ -6042,7 +6271,8 @@ end --- @param m MarioState --- @return integer ---- Tilts Mario's body according to his running speed and slope angle. Calculates a pitch offset used while running to simulate leaning forward at higher speeds or on slopes +--- Tilts Mario's body according to his running speed and slope angle.
+--- Calculates a pitch offset used while running to simulate leaning forward at higher speeds or on slopes function tilt_body_running(m) -- ... end @@ -6050,7 +6280,8 @@ end --- @param m MarioState --- @param frame1 integer --- @param frame2 integer ---- Checks the current animation frame against two specified frames to trigger footstep sounds. Also chooses specific sounds if Mario is wearing Metal Cap or is in quicksand +--- Checks the current animation frame against two specified frames to trigger footstep sounds.
+--- Also chooses specific sounds if Mario is wearing Metal Cap or is in quicksand function play_step_sound(m, frame1, frame2) -- ... end @@ -6072,7 +6303,8 @@ function begin_walking_action(m, forwardVel, action, actionArg) end --- @param m MarioState ---- Checks if Mario is near an edge while moving slowly and the floor below that edge is significantly lower. If the conditions are met, transitions Mario into a ledge-climb-down action and positions him accordingly on the edge +--- Checks if Mario is near an edge while moving slowly and the floor below that edge is significantly lower.
+--- If the conditions are met, transitions Mario into a ledge-climb-down action and positions him accordingly on the edge function check_ledge_climb_down(m) -- ... end @@ -6097,7 +6329,9 @@ end --- @param m MarioState --- @param accel number --- @param lossFactor number ---- Adjusts Mario's slide velocity and facing angle when on a slope. Calculates slope direction and steepness, then modifies velocity accordingly (speed up downhill, slow uphill). Handles facing-direction changes and maximum speed limits +--- Adjusts Mario's slide velocity and facing angle when on a slope.
+--- Calculates slope direction and steepness, then modifies velocity accordingly (speed up downhill, slow uphill).
+--- Handles facing-direction changes and maximum speed limits function update_sliding_angle(m, accel, lossFactor) -- ... end @@ -6105,13 +6339,16 @@ end --- @param m MarioState --- @param stopSpeed number --- @return integer ---- Updates Mario's sliding state each frame, applying additional friction or acceleration based on the surface's slipperiness. Also checks if speed has slowed below a threshold to end the slide. Returns `true` if sliding has stopped +--- Updates Mario's sliding state each frame, applying additional friction or acceleration based on the surface's slipperiness.
+--- Also checks if speed has slowed below a threshold to end the slide.
+--- Returns `true` if sliding has stopped function update_sliding(m, stopSpeed) -- ... end --- @param m MarioState ---- Applies acceleration or deceleration based on the slope of the floor. On downward slopes, Mario gains speed, while on upward slopes, Mario loses speed +--- Applies acceleration or deceleration based on the slope of the floor.
+--- On downward slopes, Mario gains speed, while on upward slopes, Mario loses speed function apply_slope_accel(m) -- ... end @@ -6119,7 +6356,8 @@ end --- @param m MarioState --- @param frictionFactor number --- @return integer ---- Applies friction-like deceleration if the floor is flat, or slope-based acceleration if the floor is sloped. Capped in such a way that Mario eventually stops or stabilizes on flatter ground +--- Applies friction-like deceleration if the floor is flat, or slope-based acceleration if the floor is sloped.
+--- Capped in such a way that Mario eventually stops or stabilizes on flatter ground function apply_landing_accel(m, frictionFactor) -- ... end @@ -6133,66 +6371,76 @@ end --- @param m MarioState --- @param decelCoef number --- @return integer ---- Approaches Mario's forward velocity toward zero at a rate dependent on the floor's slipperiness. This function can completely stop Mario if the slope is gentle enough or if friction is high +--- Approaches Mario's forward velocity toward zero at a rate dependent on the floor's slipperiness.
+--- This function can completely stop Mario if the slope is gentle enough or if friction is high function apply_slope_decel(m, decelCoef) -- ... end --- @param m MarioState --- @return integer ---- Gradually reduces Mario's forward speed to zero over time on level ground, unless otherwise influenced by slope or friction. Returns true if Mario's speed reaches zero, meaning he has stopped +--- Gradually reduces Mario's forward speed to zero over time on level ground, unless otherwise influenced by slope or friction.
+--- Returns true if Mario's speed reaches zero, meaning he has stopped function update_decelerating_speed(m) -- ... end --- @param m MarioState ---- Updates Mario's walking speed based on player input and floor conditions (e.g., a slow floor or quicksand). Caps speed at a certain value and may reduce it slightly on steep slopes +--- Updates Mario's walking speed based on player input and floor conditions (e.g., a slow floor or quicksand).
+--- Caps speed at a certain value and may reduce it slightly on steep slopes function update_walking_speed(m) -- ... end --- @param m MarioState --- @return integer ---- Checks if Mario should begin sliding, based on player input (facing downhill, pressing the analog stick backward, or on a slide terrain), and current floor steepness. Returns true if conditions to slide are met. +--- Checks if Mario should begin sliding, based on player input (facing downhill, pressing the analog stick backward, or on a slide terrain), and current floor steepness.
+--- Returns true if conditions to slide are met. function should_begin_sliding(m) -- ... end --- @param m MarioState --- @return integer ---- Checks if the analog stick is held significantly behind Mario's current facing angle. Returns true if the stick is far enough in the opposite direction, indicating Mario wants to move backward +--- Checks if the analog stick is held significantly behind Mario's current facing angle.
+--- Returns true if the stick is far enough in the opposite direction, indicating Mario wants to move backward function analog_stick_held_back(m) -- ... end --- @param m MarioState --- @return integer ---- Checks if the B button was pressed to either initiate a dive (if moving fast enough) or a punch (if moving slowly). Returns `true` if the action was changed to either a dive or a punching attack +--- Checks if the B button was pressed to either initiate a dive (if moving fast enough) or a punch (if moving slowly).
+--- Returns `true` if the action was changed to either a dive or a punching attack function check_ground_dive_or_punch(m) -- ... end --- @param m MarioState --- @return integer ---- Begins a braking action if Mario's forward velocity is high enough or transitions to a decelerating action otherwise. Also handles the scenario where Mario is up against a wall, transitioning to a standing state +--- Begins a braking action if Mario's forward velocity is high enough or transitions to a decelerating action otherwise.
+--- Also handles the scenario where Mario is up against a wall, transitioning to a standing state function begin_braking_action(m) -- ... end --- @param m MarioState ---- Handles the animation and audio (footstep sounds) for normal walking or running. The specific animation used (tiptoe, walk, or run) depends on Mario's current speed +--- Handles the animation and audio (footstep sounds) for normal walking or running.
+--- The specific animation used (tiptoe, walk, or run) depends on Mario's current speed function anim_and_audio_for_walk(m) -- ... end --- @param m MarioState ---- Plays the appropriate animation and footstep sounds for walking while carrying a lighter object (like a small box). Adjusts the animation speed dynamically based on Mario's velocity +--- Plays the appropriate animation and footstep sounds for walking while carrying a lighter object (like a small box).
+--- Adjusts the animation speed dynamically based on Mario's velocity function anim_and_audio_for_hold_walk(m) -- ... end --- @param m MarioState ---- Plays the appropriate animation and footstep sounds for walking while carrying a heavy object. Sets the character animation speed based on Mario's intended movement speed +--- Plays the appropriate animation and footstep sounds for walking while carrying a heavy object.
+--- Sets the character animation speed based on Mario's intended movement speed function anim_and_audio_for_heavy_walk(m) -- ... end @@ -6206,20 +6454,23 @@ end --- @param m MarioState --- @param startYaw integer ---- Applies a left/right tilt to Mario's torso (and some pitch if running fast) while walking or running. The tilt is based on his change in yaw and current speed, giving a leaning appearance when turning +--- Applies a left/right tilt to Mario's torso (and some pitch if running fast) while walking or running.
+--- The tilt is based on his change in yaw and current speed, giving a leaning appearance when turning function tilt_body_walking(m, startYaw) -- ... end --- @param m MarioState --- @param startYaw integer ---- Tilts Mario's torso and head while riding a shell on the ground to reflect turning. Similar to other tilt functions but tuned for shell-riding speeds and angles +--- Tilts Mario's torso and head while riding a shell on the ground to reflect turning.
+--- Similar to other tilt functions but tuned for shell-riding speeds and angles function tilt_body_ground_shell(m, startYaw) -- ... end --- @param m MarioState ---- Tilts Mario's torso while butt sliding based on analog input direction and magnitude. Gives the appearance that Mario is balancing or leaning into a turn +--- Tilts Mario's torso while butt sliding based on analog input direction and magnitude.
+--- Gives the appearance that Mario is balancing or leaning into a turn function tilt_body_butt_slide(m) -- ... end @@ -6239,7 +6490,8 @@ end --- @param airAction integer --- @param animation integer --- @return integer ---- Builds on `common_slide_action` by also allowing Mario to jump out of a slide if A is pressed after a short delay. If the sliding slows enough, Mario transitions to a specified stopping action +--- Builds on `common_slide_action` by also allowing Mario to jump out of a slide if A is pressed after a short delay.
+--- If the sliding slows enough, Mario transitions to a specified stopping action function common_slide_action_with_jump(m, stopAction, jumpAction, airAction, animation) -- ... end @@ -6249,7 +6501,8 @@ end --- @param airAction integer --- @param animation integer --- @return integer ---- Updates Mario's sliding state where he is on his stomach. Similar to other slide actions but has a chance to roll out if A or B is pressed. Uses `common_slide_action` for the core movement logic +--- Updates Mario's sliding state where he is on his stomach. Similar to other slide actions but has a chance to roll out if A or B is pressed.
+--- Uses `common_slide_action` for the core movement logic function stomach_slide_action(m, stopAction, airAction, animation) -- ... end @@ -6280,7 +6533,8 @@ end --- @param endAction integer --- @param airAction integer --- @return integer ---- Handles a special landing in quicksand after a jump. Over several frames, Mario emerges from the quicksand. First part of the animation reduces his quicksand depth. Ends with a normal landing action or transitions back to air if he leaves the ground +--- Handles a special landing in quicksand after a jump. Over several frames, Mario emerges from the quicksand.
+--- First part of the animation reduces his quicksand depth. Ends with a normal landing action or transitions back to air if he leaves the ground function quicksand_jump_land_action(m, animation1, animation2, endAction, airAction) -- ... end @@ -6316,14 +6570,17 @@ end --- @param m MarioState --- @return integer ---- Checks for and handles common conditions that would cancel Mario's current object action. This includes transitioning to a water plunge if below the water level, becoming squished if appropriate, or switching to standing death action if Mario is dead +--- Checks for and handles common conditions that would cancel Mario's current object action. This includes transitioning
+--- to a water plunge if below the water level, becoming squished if appropriate, or switching to standing death action
+--- if Mario is dead function check_common_object_cancels(m) -- ... end --- @param m MarioState --- @return integer ---- Executes Mario's current object action by first checking common object cancels, then updating quicksand state. Dispatches to the appropriate action function, such as punching, throwing, picking up Bowser, etc +--- Executes Mario's current object action by first checking common object cancels, then updating quicksand state.
+--- Dispatches to the appropriate action function, such as punching, throwing, picking up Bowser, etc function mario_execute_object_action(m) -- ... end @@ -6392,7 +6649,8 @@ end --- @param m MarioState --- @return integer ---- Executes Mario's current object action by first checking common stationary cancels, then updating quicksand state. Dispatches to the appropriate action function, such as idle, sleeping, crouching, ect +--- Executes Mario's current object action by first checking common stationary cancels, then updating quicksand state.
+--- Dispatches to the appropriate action function, such as idle, sleeping, crouching, ect function mario_execute_stationary_action(m) -- ... end @@ -6434,7 +6692,8 @@ end --- @param m MarioState --- @return integer ---- Executes Mario's current submerged action by first checking common submerged cancels, then setting quicksand depth and head angles to 0. Dispatches to the appropriate action function, such as breaststroke, flutterkick, water punch, ect +--- Executes Mario's current submerged action by first checking common submerged cancels, then setting quicksand depth and head angles to 0.
+--- Dispatches to the appropriate action function, such as breaststroke, flutterkick, water punch, ect function mario_execute_submerged_action(m) -- ... end @@ -6836,7 +7095,8 @@ function degrees_to_sm64(degreesAngle) end --- @param mtx Mat4 ---- Sets the 4x4 floating-point matrix `mtx` to all zeros. Unless you really need this-It's reccomended to use mtxf_identity instead. +--- Sets the 4x4 floating-point matrix `mtx` to all zeros.
+--- Unless you really need this-It's reccomended to use mtxf_identity instead. function mtxf_zero(mtx) -- ... end @@ -7696,14 +7956,19 @@ end --- @param offset integer --- @param origin ModFsFileSeek --- @return boolean ---- Sets the current position of a modfs `file`. If `origin` is `FILE_SEEK_SET`, file position is set to `offset`. If `origin` is `FILE_SEEK_CUR`, `offset` is added to file current position. If `origin` is `FILE_SEEK_END`, file position is set to `end of file + offset`. Returns true on success +--- Sets the current position of a modfs `file`.
+--- If `origin` is `FILE_SEEK_SET`, file position is set to `offset`.
+--- If `origin` is `FILE_SEEK_CUR`, `offset` is added to file current position.
+--- If `origin` is `FILE_SEEK_END`, file position is set to `end of file + offset`.
+--- Returns true on success function mod_fs_file_seek(file, offset, origin) -- ... end --- @param file ModFsFile --- @return boolean ---- Sets the current position of a modfs `file` to its beginning. Returns true on success +--- Sets the current position of a modfs `file` to its beginning.
+--- Returns true on success function mod_fs_file_rewind(file) -- ... end @@ -8058,19 +8323,22 @@ function obj_splash(waterY, objY) end --- @return integer ---- Generic object move function. Handles walls, water, floors, and gravity. Returns flags for certain interactions +--- Generic object move function. Handles walls, water, floors, and gravity.
+--- Returns flags for certain interactions function object_step() -- ... end --- @return integer ---- Takes an object step but does not orient with the object's floor. Used for boulders, falling pillars, and the rolling snowman body +--- Takes an object step but does not orient with the object's floor.
+--- Used for boulders, falling pillars, and the rolling snowman body function object_step_without_floor_orient() -- ... end --- @param obj Object ---- Don't use this function outside of of a context where the current object and `obj` are the same. Moves `obj` based on a seemingly random mix of using either the current obj or `obj`'s fields +--- Don't use this function outside of of a context where the current object and `obj` are the same.
+--- Moves `obj` based on a seemingly random mix of using either the current obj or `obj`'s fields function obj_move_xyz_using_fvel_and_yaw(obj) -- ... end @@ -8209,7 +8477,8 @@ end --- @param goal integer --- @param range integer --- @return integer ---- A series of checks using sin and cos to see if a given angle is facing in the same direction of a given angle, within a certain range +--- A series of checks using sin and cos to see if a given angle is facing in the same direction
+--- of a given angle, within a certain range function obj_check_if_facing_toward_angle(base, goal, range) -- ... end @@ -8249,13 +8518,15 @@ end --- @param collisionFlags integer --- @param floor Surface ---- Checks if `floor`'s type is burning or death plane and if so change the current object's action accordingly +--- Checks if `floor`'s type is burning or death plane and if so change the
+--- current object's action accordingly function obj_check_floor_death(collisionFlags, floor) -- ... end --- @return integer ---- Controls an object dying in lava by creating smoke, sinking the object, playing audio, and eventually despawning it. Returns TRUE when the obj is dead +--- Controls an object dying in lava by creating smoke, sinking the object, playing
+--- audio, and eventually despawning it. Returns TRUE when the obj is dead function obj_lava_death() -- ... end @@ -8487,7 +8758,10 @@ end --- @param endScale number --- @return integer --- @return number scaleVel ---- Begin by increasing the current object's scale by `scaleVel`, and slowly decreasing `scaleVel`. Once the object starts to shrink, wait a bit, and then begin to scale the object toward `endScale`. The first time it reaches below `shootFireScale` during this time, return 1. Return -1 once it's reached endScale +--- Begin by increasing the current object's scale by `scaleVel`, and slowly decreasing `scaleVel`.
+--- Once the object starts to shrink, wait a bit, and then begin to scale the object toward `endScale`.
+--- The first time it reaches below `shootFireScale` during this time, return 1.
+--- Return -1 once it's reached endScale function obj_grow_then_shrink(scaleVel, shootFireScale, endScale) -- ... end @@ -8873,7 +9147,12 @@ end --- @param m Mat4 --- @param dst Vec3f --- @param v Vec3f ---- Multiplies a vector by a matrix of the form: `| ? ? ? 0 |` `| ? ? ? 0 |` `| ? ? ? 0 |` `| 0 0 0 1 |` i.e. a matrix representing a linear transformation over 3 space +--- Multiplies a vector by a matrix of the form:
+--- `| ? ? ? 0 |`
+--- `| ? ? ? 0 |`
+--- `| ? ? ? 0 |`
+--- `| 0 0 0 1 |`
+--- i.e. a matrix representing a linear transformation over 3 space function linear_mtxf_mul_vec3f(m, dst, v) -- ... end @@ -8881,7 +9160,12 @@ end --- @param m Mat4 --- @param dst Vec3f --- @param v Vec3f ---- Multiplies a vector by the transpose of a matrix of the form: `| ? ? ? 0 |` `| ? ? ? 0 |` `| ? ? ? 0 |` `| 0 0 0 1 |` i.e. a matrix representing a linear transformation over 3 space +--- Multiplies a vector by the transpose of a matrix of the form:
+--- `| ? ? ? 0 |`
+--- `| ? ? ? 0 |`
+--- `| ? ? ? 0 |`
+--- `| 0 0 0 1 |`
+--- i.e. a matrix representing a linear transformation over 3 space function linear_mtxf_transpose_mul_vec3f(m, dst, v) -- ... end @@ -9996,20 +10280,23 @@ end --- @param fileIndex integer --- @param courseIndex integer ---- Marks the coin score for a specific course as the newest among all save files. Adjusts the age of other scores to reflect the update. Useful for leaderboard tracking or displaying recent progress +--- Marks the coin score for a specific course as the newest among all save files. Adjusts the age of other scores to reflect the update.
+--- Useful for leaderboard tracking or displaying recent progress function touch_coin_score_age(fileIndex, courseIndex) -- ... end --- @param fileIndex integer --- @param forceSave integer ---- Saves the current state of the game into a specified save file. Includes data verification and backup management. Useful for maintaining game progress during play or when saving manually +--- Saves the current state of the game into a specified save file. Includes data verification and backup management.
+--- Useful for maintaining game progress during play or when saving manually function save_file_do_save(fileIndex, forceSave) -- ... end --- @param fileIndex integer ---- Erases all data in a specified save file, including backup slots. Marks the save file as modified and performs a save to apply the changes. Useful for resetting a save file to its default state +--- Erases all data in a specified save file, including backup slots. Marks the save file as modified and performs a save to apply the changes.
+--- Useful for resetting a save file to its default state function save_file_erase(fileIndex) -- ... end @@ -10020,14 +10307,16 @@ function save_file_erase_current_backup_save() end --- @param load_all integer ---- Reloads the save file data into memory, optionally resetting all save files. Marks the save file as modified. Useful for reloading state after data corruption or during development debugging +--- Reloads the save file data into memory, optionally resetting all save files. Marks the save file as modified.
+--- Useful for reloading state after data corruption or during development debugging function save_file_reload(load_all) -- ... end --- @param courseIndex integer --- @return integer ---- Determines the maximum coin score for a course across all save files. Returns the score along with the file index of the save containing it. Useful for leaderboard-style comparisons and overall progress tracking +--- Determines the maximum coin score for a course across all save files. Returns the score along with the file index of the save containing it.
+--- Useful for leaderboard-style comparisons and overall progress tracking function save_file_get_max_coin_score(courseIndex) -- ... end @@ -10035,7 +10324,8 @@ end --- @param fileIndex integer --- @param courseIndex integer --- @return integer ---- Calculates the total number of stars collected in a specific course for a given save file. Useful for determining completion status of individual levels +--- Calculates the total number of stars collected in a specific course for a given save file.
+--- Useful for determining completion status of individual levels function save_file_get_course_star_count(fileIndex, courseIndex) -- ... end @@ -10044,25 +10334,29 @@ end --- @param minCourse integer --- @param maxCourse integer --- @return integer ---- Calculates the total number of stars collected across multiple courses within a specified range. Useful for determining the overall progress toward game completion +--- Calculates the total number of stars collected across multiple courses within a specified range.
+--- Useful for determining the overall progress toward game completion function save_file_get_total_star_count(fileIndex, minCourse, maxCourse) -- ... end --- @param flags integer ---- Adds new flags to the save file's flag bitmask. Useful for updating progress or triggering new gameplay features +--- Adds new flags to the save file's flag bitmask.
+--- Useful for updating progress or triggering new gameplay features function save_file_set_flags(flags) -- ... end --- @param flags integer ---- Clears specific flags in the current save file. The flags are specified as a bitmask in the `flags` parameter. Ensures that the save file remains valid after clearing. Useful for removing specific game states, such as collected items or completed objectives, without resetting the entire save +--- Clears specific flags in the current save file. The flags are specified as a bitmask in the `flags` parameter. Ensures that the save file remains valid after clearing.
+--- Useful for removing specific game states, such as collected items or completed objectives, without resetting the entire save function save_file_clear_flags(flags) -- ... end --- @return integer ---- Retrieves the bitmask of flags representing the current state of the save file. Flags indicate collected items, completed objectives, and other game states. Useful for checking specific game progress details +--- Retrieves the bitmask of flags representing the current state of the save file. Flags indicate collected items, completed objectives, and other game states.
+--- Useful for checking specific game progress details function save_file_get_flags() -- ... end @@ -10070,7 +10364,8 @@ end --- @param fileIndex integer --- @param courseIndex integer --- @return integer ---- Retrieves the bitmask of stars collected in a specific course or castle secret stars (-1). Useful for evaluating level progress and completion +--- Retrieves the bitmask of stars collected in a specific course or castle secret stars (-1).
+--- Useful for evaluating level progress and completion function save_file_get_star_flags(fileIndex, courseIndex) -- ... end @@ -10078,7 +10373,8 @@ end --- @param fileIndex integer --- @param courseIndex integer --- @param starFlags integer ---- Adds specific star flags to the save file, indicating collected stars for a course or castle secret stars. Updates the save file flags as necessary. Useful for recording progress after star collection +--- Adds specific star flags to the save file, indicating collected stars for a course or castle secret stars. Updates the save file flags as necessary.
+--- Useful for recording progress after star collection function save_file_set_star_flags(fileIndex, courseIndex, starFlags) -- ... end @@ -10086,7 +10382,8 @@ end --- @param fileIndex integer --- @param courseIndex integer --- @param starFlagsToRemove integer ---- Removes specific star flags from the save file. This modifies the bitmask representing collected stars for a course or castle secret stars. Useful for undoing progress or debugging collected stars +--- Removes specific star flags from the save file. This modifies the bitmask representing collected stars for a course or castle secret stars.
+--- Useful for undoing progress or debugging collected stars function save_file_remove_star_flags(fileIndex, courseIndex, starFlagsToRemove) -- ... end @@ -10094,7 +10391,8 @@ end --- @param fileIndex integer --- @param courseIndex integer --- @return integer ---- Returns the highest coin score for a specified course in the save file. Performs checks to ensure the coin score is valid. Useful for tracking player achievements and high scores +--- Returns the highest coin score for a specified course in the save file. Performs checks to ensure the coin score is valid.
+--- Useful for tracking player achievements and high scores function save_file_get_course_coin_score(fileIndex, courseIndex) -- ... end @@ -10102,7 +10400,8 @@ end --- @param fileIndex integer --- @param courseIndex integer --- @param coinScore integer ---- Updates the coin score for a specific course in the save file. The new score is provided in the `coinScore` parameter. Useful for manually setting achievements such as high coin counts in individual levels +--- Updates the coin score for a specific course in the save file. The new score is provided in the `coinScore` parameter.
+--- Useful for manually setting achievements such as high coin counts in individual levels function save_file_set_course_coin_score(fileIndex, courseIndex, coinScore) -- ... end @@ -10110,7 +10409,8 @@ end --- @param fileIndex integer --- @param courseIndex integer --- @return integer ---- Checks whether the cannon in the specified course is unlocked. Returns true if the cannon is unlocked, otherwise false. Useful for tracking course-specific progress and enabling shortcuts +--- Checks whether the cannon in the specified course is unlocked. Returns true if the cannon is unlocked, otherwise false.
+--- Useful for tracking course-specific progress and enabling shortcuts function save_file_is_cannon_unlocked(fileIndex, courseIndex) -- ... end @@ -10122,13 +10422,15 @@ end --- @param capPos Vec3s --- @return integer ---- Retrieves the current position of Mario's cap, if it is on the ground in the current level and area. The position is stored in the provided `capPos` parameter. Useful for tracking the cap's location after it has been dropped or lost +--- Retrieves the current position of Mario's cap, if it is on the ground in the current level and area. The position is stored in the provided `capPos` parameter.
+--- Useful for tracking the cap's location after it has been dropped or lost function save_file_get_cap_pos(capPos) -- ... end --- @return integer ---- Returns the current sound mode (e.g., stereo, mono) stored in the save file. Useful for checking the audio output preferences when loading a save +--- Returns the current sound mode (e.g., stereo, mono) stored in the save file.
+--- Useful for checking the audio output preferences when loading a save function save_file_get_sound_mode() -- ... end @@ -10427,7 +10729,8 @@ function camera_romhack_allow_dpad_usage(allow) end --- @param enable integer ---- Toggles collision settings for the ROM hack camera. This enables or disables specific collision behaviors in modded levels +--- Toggles collision settings for the ROM hack camera.
+--- This enables or disables specific collision behaviors in modded levels function camera_romhack_set_collisions(enable) -- ... end @@ -10749,7 +11052,9 @@ end --- @param vertex2 Vec3s --- @param vertex3 Vec3s --- @return Surface ---- Allocates a new collision surface with the given vertices, computes the surface normal and other fields, and inserts it into the spatial partition. Returns the new surface, or `nil` if the triangle is degenerate (zero area). Set `dynamic` to `true` for surfaces that are cleared each frame, or `false` for persistent static surfaces +--- Allocates a new collision surface with the given vertices, computes the surface normal and other fields, and inserts it into the spatial partition.
+--- Returns the new surface, or `nil` if the triangle is degenerate (zero area).
+--- Set `dynamic` to `true` for surfaces that are cleared each frame, or `false` for persistent static surfaces function smlua_collision_add_surface(dynamic, surfaceType, vertex1, vertex2, vertex3) -- ... end @@ -10758,7 +11063,9 @@ end --- @param vertex1 Vec3s --- @param vertex2 Vec3s --- @param vertex3 Vec3s ---- Moves an existing collision surface to new vertex positions. Recalculates the surface normal, origin offset, and Y bounds, removes the surface from its old spatial partition cells, and re-adds it to the correct cells. The previous vertices are preserved for interpolation +--- Moves an existing collision surface to new vertex positions.
+--- Recalculates the surface normal, origin offset, and Y bounds, removes the surface from its old spatial partition cells, and re-adds it to the correct cells.
+--- The previous vertices are preserved for interpolation function smlua_collision_move_surface(surface, vertex1, vertex2, vertex3) -- ... end @@ -11006,7 +11313,8 @@ end --- @param name string --- @return Pointer_Gfx --- @return integer length ---- Gets a display list of the current mod from its name. Returns a pointer to the display list and its length +--- Gets a display list of the current mod from its name.
+--- Returns a pointer to the display list and its length function gfx_get_from_name(name) -- ... end @@ -11077,7 +11385,8 @@ end --- @param name string --- @return Pointer_Vtx --- @return integer count ---- Gets a vertex buffer of the current mod from its name. Returns a pointer to the vertex buffer and its vertex count +--- Gets a vertex buffer of the current mod from its name.
+--- Returns a pointer to the vertex buffer and its vertex count function vtx_get_from_name(name) -- ... end @@ -11531,7 +11840,8 @@ end --- @param m MarioState --- @param index integer --- @return number ---- Gets the X coordinate of Mario's hand (0-1) or foot (2-3) but it is important to note that the positions are not updated off-screen +--- Gets the X coordinate of Mario's hand (0-1) or foot (2-3)
+--- but it is important to note that the positions are not updated off-screen function get_hand_foot_pos_x(m, index) -- ... end @@ -11539,7 +11849,8 @@ end --- @param m MarioState --- @param index integer --- @return number ---- Gets the Y coordinate of Mario's hand (0-1) or foot (2-3) but It is important to note that the positions are not updated off-screen +--- Gets the Y coordinate of Mario's hand (0-1) or foot (2-3)
+--- but It is important to note that the positions are not updated off-screen function get_hand_foot_pos_y(m, index) -- ... end @@ -11547,7 +11858,8 @@ end --- @param m MarioState --- @param index integer --- @return number ---- Gets the Z coordinate of Mario's hand (0-1) or foot (2-3) but it is important to note that the positions are not updated off-screen +--- Gets the Z coordinate of Mario's hand (0-1) or foot (2-3)
+--- but it is important to note that the positions are not updated off-screen function get_hand_foot_pos_z(m, index) -- ... end @@ -11851,7 +12163,8 @@ end --- @param z number --- @param objSetupFunction function --- @return Object ---- Spawns a synchronized object at `x`, `y`, and `z` as a child object of the local Mario with his rotation. You can change the fields of the object in `objSetupFunction` +--- Spawns a synchronized object at `x`, `y`, and `z` as a child object of the local Mario with his rotation.
+--- You can change the fields of the object in `objSetupFunction` function spawn_sync_object(behaviorId, modelId, x, y, z, objSetupFunction) -- ... end @@ -11863,7 +12176,8 @@ end --- @param z number --- @param objSetupFunction function --- @return Object ---- Spawns a non-synchronized object at `x`, `y`, and `z` as a child object of the local Mario with his rotation. You can change the fields of the object in `objSetupFunction` +--- Spawns a non-synchronized object at `x`, `y`, and `z` as a child object of the local Mario with his rotation.
+--- You can change the fields of the object in `objSetupFunction` function spawn_non_sync_object(behaviorId, modelId, x, y, z, objSetupFunction) -- ... end @@ -11965,7 +12279,8 @@ end --- @param fieldIndex integer --- @param value integer --- @return Object ---- Gets the first object loaded with `behaviorId` and object signed 32-bit integer field (look in `object_fields.h` to get the index of a field) +--- Gets the first object loaded with `behaviorId` and object signed 32-bit integer field
+--- (look in `object_fields.h` to get the index of a field) function obj_get_first_with_behavior_id_and_field_s32(behaviorId, fieldIndex, value) -- ... end @@ -11974,7 +12289,8 @@ end --- @param fieldIndex integer --- @param value number --- @return Object ---- Gets the first object loaded with `behaviorId` and object float field (look in `object_fields.h` to get the index of a field) +--- Gets the first object loaded with `behaviorId` and object float field
+--- (look in `object_fields.h` to get the index of a field) function obj_get_first_with_behavior_id_and_field_f32(behaviorId, fieldIndex, value) -- ... end @@ -11997,7 +12313,8 @@ end --- @param fieldIndex integer --- @param value integer --- @return Object ---- Gets the next object loaded with the same behavior ID and object signed 32-bit integer field (look in `object_fields.h` to get the index of a field) +--- Gets the next object loaded with the same behavior ID and object signed 32-bit integer field
+--- (look in `object_fields.h` to get the index of a field) function obj_get_next_with_same_behavior_id_and_field_s32(o, fieldIndex, value) -- ... end @@ -12006,7 +12323,8 @@ end --- @param fieldIndex integer --- @param value number --- @return Object ---- Gets the next object loaded with the same behavior ID and object float field (look in `object_fields.h` to get the index of a field) +--- Gets the next object loaded with the same behavior ID and object float field
+--- (look in `object_fields.h` to get the index of a field) function obj_get_next_with_same_behavior_id_and_field_f32(o, fieldIndex, value) -- ... end @@ -12530,28 +12848,34 @@ function cur_obj_play_sound_2(soundMagic) end --- @param soundMagic integer ---- Create a sound spawner for objects that need a sound play once. (Breakable walls, King Bobomb exploding, etc) +--- Create a sound spawner for objects that need a sound play once.
+--- (Breakable walls, King Bobomb exploding, etc) function create_sound_spawner(soundMagic) -- ... end --- @param distance number --- @return integer ---- Unused vanilla function, calculates a volume based on `distance`. If `distance` is less than 500 then 127, if `distance` is greater than 1500 then 0, if `distance` is between 500 and 1500 then it ranges linearly from 60 to 124. What an even more strange and confusing function +--- Unused vanilla function, calculates a volume based on `distance`.
+--- If `distance` is less than 500 then 127, if `distance` is greater than 1500 then 0, if `distance` is between 500 and 1500 then it ranges linearly from 60 to 124.
+--- What an even more strange and confusing function function calc_dist_to_volume_range_1(distance) -- ... end --- @param distance number --- @return integer ---- Unused vanilla function, calculates a volume based on `distance`. If `distance` is less than 1300 then 127, if `distance` is greater than 2300 then 0, if `distance` is between 1300 and 2300 then it ranges linearly from 60 to 127. What a strange and confusing function +--- Unused vanilla function, calculates a volume based on `distance`.
+--- If `distance` is less than 1300 then 127, if `distance` is greater than 2300 then 0, if `distance` is between 1300 and 2300 then it ranges linearly from 60 to 127.
+--- What a strange and confusing function function calc_dist_to_volume_range_2(distance) -- ... end --- @param colData WallCollisionData --- @return integer ---- Detects wall collisions at a given position and adjusts the position based on the walls found. Returns the number of wall collisions detected +--- Detects wall collisions at a given position and adjusts the position based on the walls found.
+--- Returns the number of wall collisions detected function find_wall_collisions(colData) -- ... end @@ -12561,7 +12885,8 @@ end --- @param posZ number --- @return number --- @return Surface pceil ---- Finds the height of the highest ceiling above a given position (x, y, z) and return the corresponding ceil surface. If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default) +--- Finds the height of the highest ceiling above a given position (x, y, z) and return the corresponding ceil surface.
+--- If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default) function find_ceil(posX, posY, posZ) -- ... end @@ -12570,7 +12895,8 @@ end --- @param y number --- @param z number --- @return number ---- Finds the height of the highest ceiling above a given position (x, y, z). If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default) +--- Finds the height of the highest ceiling above a given position (x, y, z).
+--- If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default) function find_ceil_height(x, y, z) -- ... end @@ -12579,7 +12905,8 @@ end --- @param y number --- @param z number --- @return number ---- Finds the height of the highest floor below a given position (x, y, z). If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default) +--- Finds the height of the highest floor below a given position (x, y, z).
+--- If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default) function find_floor_height(x, y, z) -- ... end @@ -12589,7 +12916,8 @@ end --- @param zPos number --- @return number --- @return Surface pfloor ---- Finds the height of the highest floor below a given position (x, y, z) and return the corresponding floor surface. If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default) +--- Finds the height of the highest floor below a given position (x, y, z) and return the corresponding floor surface.
+--- If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default) function find_floor(xPos, yPos, zPos) -- ... end @@ -12597,7 +12925,8 @@ end --- @param x number --- @param z number --- @return number ---- Finds the height of water at a given position (x, z), if the position is within a water region. If no water is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default) +--- Finds the height of water at a given position (x, z), if the position is within a water region.
+--- If no water is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default) function find_water_level(x, z) -- ... end @@ -12605,7 +12934,8 @@ end --- @param x number --- @param z number --- @return number ---- Finds the height of the poison gas at a given position (x, z), if the position is within a gas region. If no gas is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default) +--- Finds the height of the poison gas at a given position (x, z), if the position is within a gas region.
+--- If no gas is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default) function find_poison_gas_level(x, z) -- ... end @@ -12626,13 +12956,15 @@ function closest_point_to_triangle(surf, src, out) -- ... end ---- Loads the object's collision data into dynamic collision. You must run this every frame in your object's behavior loop for it to have collision +--- Loads the object's collision data into dynamic collision.
+--- You must run this every frame in your object's behavior loop for it to have collision function load_object_collision_model() -- ... end --- @return StaticObjectCollision ---- Loads the object's collision data into static collision. You may run this only once to capture the object's collision at that frame. +--- Loads the object's collision data into static collision.
+--- You may run this only once to capture the object's collision at that frame. function load_static_object_collision() -- ... end diff --git a/docs/lua/functions-2.md b/docs/lua/functions-2.md index 0fe24495c..9cad9f1e8 100644 --- a/docs/lua/functions-2.md +++ b/docs/lua/functions-2.md @@ -4197,7 +4197,8 @@ Behavior loop function for Tox Box ## [mario_moving_fast_enough_to_make_piranha_plant_bite](#mario_moving_fast_enough_to_make_piranha_plant_bite) ### Description -Checks if Mario is moving fast enough to make Piranha Plant bite. This one is a mouthful +Checks if Mario is moving fast enough to make Piranha Plant bite. +This one is a mouthful ### Lua Example `local integerValue = mario_moving_fast_enough_to_make_piranha_plant_bite()` diff --git a/docs/lua/functions-3.md b/docs/lua/functions-3.md index 9dd4ee27c..2aab0ab14 100644 --- a/docs/lua/functions-3.md +++ b/docs/lua/functions-3.md @@ -290,7 +290,8 @@ Gets a behavior ID from a behavior name ## [skip_camera_interpolation](#skip_camera_interpolation) ### Description -Skips camera interpolation for a frame, locking the camera instantly to the target position. Useful for immediate changes in camera state or position without smooth transitions +Skips camera interpolation for a frame, locking the camera instantly to the target position. +Useful for immediate changes in camera state or position without smooth transitions ### Lua Example `skip_camera_interpolation()` @@ -311,7 +312,8 @@ Skips camera interpolation for a frame, locking the camera instantly to the targ ## [set_camera_shake_from_hit](#set_camera_shake_from_hit) ### Description -Applies a shake effect to the camera based on a hit type. Different shake types simulate various impacts, such as attacks, falls, or shocks +Applies a shake effect to the camera based on a hit type. +Different shake types simulate various impacts, such as attacks, falls, or shocks ### Lua Example `set_camera_shake_from_hit(shake)` @@ -334,7 +336,8 @@ Applies a shake effect to the camera based on a hit type. Different shake types ## [set_environmental_camera_shake](#set_environmental_camera_shake) ### Description -Applies an environmental shake effect to the camera. Handles predefined shake types triggered by environmental events like explosions or platform movements +Applies an environmental shake effect to the camera. +Handles predefined shake types triggered by environmental events like explosions or platform movements ### Lua Example `set_environmental_camera_shake(shake)` @@ -357,7 +360,8 @@ Applies an environmental shake effect to the camera. Handles predefined shake ty ## [set_camera_shake_from_point](#set_camera_shake_from_point) ### Description -Applies a shake effect to the camera, scaled by its proximity to a specified point. The intensity decreases with distance from the point +Applies a shake effect to the camera, scaled by its proximity to a specified point. +The intensity decreases with distance from the point ### Lua Example `set_camera_shake_from_point(shake, posX, posY, posZ)` @@ -383,7 +387,8 @@ Applies a shake effect to the camera, scaled by its proximity to a specified poi ## [move_mario_head_c_up](#move_mario_head_c_up) ### Description -Moves Mario's head slightly upward when the C-Up button is pressed. This function aligns the camera to match the head movement for consistency +Moves Mario's head slightly upward when the C-Up button is pressed. +This function aligns the camera to match the head movement for consistency ### Lua Example `move_mario_head_c_up(c)` @@ -406,7 +411,8 @@ Moves Mario's head slightly upward when the C-Up button is pressed. This functio ## [transition_next_state](#transition_next_state) ### Description -Transitions the camera to the next state over a specified number of frames. This is typically used for cutscenes or scripted sequences +Transitions the camera to the next state over a specified number of frames. +This is typically used for cutscenes or scripted sequences ### Lua Example `transition_next_state(c, frames)` @@ -430,7 +436,8 @@ Transitions the camera to the next state over a specified number of frames. This ## [set_camera_mode](#set_camera_mode) ### Description -Changes the camera to a new mode, optionally interpolating over a specified number of frames. Useful for transitioning between different camera behaviors dynamically +Changes the camera to a new mode, optionally interpolating over a specified number of frames. +Useful for transitioning between different camera behaviors dynamically ### Lua Example `set_camera_mode(c, mode, frames)` @@ -455,7 +462,8 @@ Changes the camera to a new mode, optionally interpolating over a specified numb ## [soft_reset_camera](#soft_reset_camera) ### Description -Resets the camera's state while retaining some settings, such as position or mode. This is often used when soft-resetting gameplay without reinitialization +Resets the camera's state while retaining some settings, such as position or mode. +This is often used when soft-resetting gameplay without reinitialization ### Lua Example `soft_reset_camera(c)` @@ -478,7 +486,8 @@ Resets the camera's state while retaining some settings, such as position or mod ## [reset_camera](#reset_camera) ### Description -Fully resets the camera to its default state and reinitializes all settings. This is typically used when restarting gameplay or loading a new area +Fully resets the camera to its default state and reinitializes all settings. +This is typically used when restarting gameplay or loading a new area ### Lua Example `reset_camera(c)` @@ -501,7 +510,8 @@ Fully resets the camera to its default state and reinitializes all settings. Thi ## [select_mario_cam_mode](#select_mario_cam_mode) ### Description -Selects the appropriate camera mode for Mario based on the current gameplay context. Adapts camera behavior dynamically to match Mario's environment or state +Selects the appropriate camera mode for Mario based on the current gameplay context. +Adapts camera behavior dynamically to match Mario's environment or state ### Lua Example `select_mario_cam_mode()` @@ -522,7 +532,8 @@ Selects the appropriate camera mode for Mario based on the current gameplay cont ## [object_pos_to_vec3f](#object_pos_to_vec3f) ### Description -Converts an object's position to a `Vec3f` format. Useful for aligning object behaviors or interactions with the camera system +Converts an object's position to a `Vec3f` format. +Useful for aligning object behaviors or interactions with the camera system ### Lua Example `object_pos_to_vec3f(dst, o)` @@ -546,7 +557,8 @@ Converts an object's position to a `Vec3f` format. Useful for aligning object be ## [vec3f_to_object_pos](#vec3f_to_object_pos) ### Description -Converts a `Vec3f` position to an object's internal format. Useful for syncing 3D positions between objects and the game world +Converts a `Vec3f` position to an object's internal format. +Useful for syncing 3D positions between objects and the game world ### Lua Example `vec3f_to_object_pos(o, src)` @@ -666,7 +678,8 @@ Converts a `Vec3s` angle to an object's move angle internal format ## [cam_select_alt_mode](#cam_select_alt_mode) ### Description -Selects an alternate camera mode based on the given angle. Used to toggle between predefined camera modes dynamically +Selects an alternate camera mode based on the given angle. +Used to toggle between predefined camera modes dynamically ### Lua Example `local integerValue = cam_select_alt_mode(angle)` @@ -689,7 +702,8 @@ Selects an alternate camera mode based on the given angle. Used to toggle betwee ## [set_cam_angle](#set_cam_angle) ### Description -Sets the camera's angle based on the specified mode. Handles rotation and focus adjustments for predefined camera behaviors +Sets the camera's angle based on the specified mode. +Handles rotation and focus adjustments for predefined camera behaviors ### Lua Example `local integerValue = set_cam_angle(mode)` @@ -712,7 +726,8 @@ Sets the camera's angle based on the specified mode. Handles rotation and focus ## [set_handheld_shake](#set_handheld_shake) ### Description -Applies a handheld camera shake effect with configurable parameters. Can be used to simulate dynamic, realistic camera movement +Applies a handheld camera shake effect with configurable parameters. +Can be used to simulate dynamic, realistic camera movement ### Lua Example `set_handheld_shake(mode)` @@ -735,7 +750,8 @@ Applies a handheld camera shake effect with configurable parameters. Can be used ## [shake_camera_handheld](#shake_camera_handheld) ### Description -Activates a handheld camera shake effect. Calculates positional and focus adjustments to simulate manual movement +Activates a handheld camera shake effect. +Calculates positional and focus adjustments to simulate manual movement ### Lua Example `shake_camera_handheld(pos, focus)` @@ -759,7 +775,8 @@ Activates a handheld camera shake effect. Calculates positional and focus adjust ## [find_c_buttons_pressed](#find_c_buttons_pressed) ### Description -Determines which C-buttons are currently pressed by the player. Returns a bitmask indicating the active buttons for camera control +Determines which C-buttons are currently pressed by the player. +Returns a bitmask indicating the active buttons for camera control ### Lua Example `local integerValue = find_c_buttons_pressed(currentState, buttonsPressed, buttonsDown)` @@ -784,7 +801,8 @@ Determines which C-buttons are currently pressed by the player. Returns a bitmas ## [collide_with_walls](#collide_with_walls) ### Description -Checks for collisions between the camera and level geometry. Adjusts the camera's position to avoid clipping into walls or obstacles +Checks for collisions between the camera and level geometry. +Adjusts the camera's position to avoid clipping into walls or obstacles ### Lua Example `local integerValue = collide_with_walls(pos, offsetY, radius)` @@ -809,7 +827,8 @@ Checks for collisions between the camera and level geometry. Adjusts the camera' ## [clamp_pitch](#clamp_pitch) ### Description -Clamps the camera's pitch angle between a maximum and minimum value. Prevents over-rotation and maintains a consistent viewing angle +Clamps the camera's pitch angle between a maximum and minimum value. +Prevents over-rotation and maintains a consistent viewing angle ### Lua Example `local integerValue = clamp_pitch(from, to, maxPitch, minPitch)` @@ -835,7 +854,8 @@ Clamps the camera's pitch angle between a maximum and minimum value. Prevents ov ## [is_within_100_units_of_mario](#is_within_100_units_of_mario) ### Description -Checks if a position is within 100 units of Mario's current position. Returns true if the position is within the specified radius and false otherwise +Checks if a position is within 100 units of Mario's current position. +Returns true if the position is within the specified radius and false otherwise ### Lua Example `local integerValue = is_within_100_units_of_mario(posX, posY, posZ)` @@ -860,7 +880,9 @@ Checks if a position is within 100 units of Mario's current position. Returns tr ## [set_or_approach_f32_asymptotic](#set_or_approach_f32_asymptotic) ### Description -Smoothly transitions or directly sets a floating-point value (`dst`) to approach a target (`goal`). Uses asymptotic scaling for gradual adjustments or direct assignment. Returns FALSE if `dst` reaches `goal` +Smoothly transitions or directly sets a floating-point value (`dst`) to approach a target (`goal`). +Uses asymptotic scaling for gradual adjustments or direct assignment. +Returns FALSE if `dst` reaches `goal` ### Lua Example `local integerValue, dst = set_or_approach_f32_asymptotic(dst, goal, scale)` @@ -886,7 +908,8 @@ Smoothly transitions or directly sets a floating-point value (`dst`) to approach ## [approach_f32_asymptotic_bool](#approach_f32_asymptotic_bool) ### Description -Gradually adjusts a floating-point value (`current`) towards a target (`target`) using asymptotic smoothing. Returns FALSE if `current` reaches the `target` +Gradually adjusts a floating-point value (`current`) towards a target (`target`) using asymptotic smoothing. +Returns FALSE if `current` reaches the `target` ### Lua Example `local integerValue, current = approach_f32_asymptotic_bool(current, target, multiplier)` @@ -912,7 +935,9 @@ Gradually adjusts a floating-point value (`current`) towards a target (`target`) ## [approach_f32_asymptotic](#approach_f32_asymptotic) ### Description -Gradually approaches a floating-point value (`target`) using asymptotic smoothing. The rate of approach is controlled by the `multiplier`. Useful for smoothly adjusting camera parameters like field-of-view or position +Gradually approaches a floating-point value (`target`) using asymptotic smoothing. +The rate of approach is controlled by the `multiplier`. +Useful for smoothly adjusting camera parameters like field-of-view or position ### Lua Example `local numberValue = approach_f32_asymptotic(current, target, multiplier)` @@ -937,7 +962,8 @@ Gradually approaches a floating-point value (`target`) using asymptotic smoothin ## [approach_s16_asymptotic_bool](#approach_s16_asymptotic_bool) ### Description -Gradually adjusts a signed 16-bit integer (`current`) towards a target (`target`) using asymptotic smoothing. Returns FALSE if `current` reaches `target` +Gradually adjusts a signed 16-bit integer (`current`) towards a target (`target`) using asymptotic smoothing. +Returns FALSE if `current` reaches `target` ### Lua Example `local integerValue, current = approach_s16_asymptotic_bool(current, target, divisor)` @@ -963,7 +989,9 @@ Gradually adjusts a signed 16-bit integer (`current`) towards a target (`target` ## [approach_s16_asymptotic](#approach_s16_asymptotic) ### Description -Gradually approaches a signed 16-bit integer (`target`) using asymptotic smoothing. The divisor controls the rate of the adjustment. Useful for adjusting angles or positions smoothly +Gradually approaches a signed 16-bit integer (`target`) using asymptotic smoothing. +The divisor controls the rate of the adjustment. +Useful for adjusting angles or positions smoothly ### Lua Example `local integerValue = approach_s16_asymptotic(current, target, divisor)` @@ -988,7 +1016,8 @@ Gradually approaches a signed 16-bit integer (`target`) using asymptotic smoothi ## [approach_vec3f_asymptotic](#approach_vec3f_asymptotic) ### Description -Smoothly transitions a 3D vector (`current`) towards a target vector (`target`) using asymptotic scaling. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component +Smoothly transitions a 3D vector (`current`) towards a target vector (`target`) using asymptotic scaling. +Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component ### Lua Example `approach_vec3f_asymptotic(current, target, xMul, yMul, zMul)` @@ -1015,7 +1044,8 @@ Smoothly transitions a 3D vector (`current`) towards a target vector (`target`) ## [set_or_approach_vec3f_asymptotic](#set_or_approach_vec3f_asymptotic) ### Description -Smoothly transitions a 3D vector (`current`) toward a target vector (`goal`) using asymptotic scaling. Allows gradual or instantaneous alignment of 3D positions. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component +Smoothly transitions a 3D vector (`current`) toward a target vector (`goal`) using asymptotic scaling. +Allows gradual or instantaneous alignment of 3D positions. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component ### Lua Example `set_or_approach_vec3f_asymptotic(dst, goal, xMul, yMul, zMul)` @@ -1042,7 +1072,8 @@ Smoothly transitions a 3D vector (`current`) toward a target vector (`goal`) usi ## [camera_approach_s16_symmetric_bool](#camera_approach_s16_symmetric_bool) ### Description -Adjusts a signed 16-bit integer (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). Returns FALSE if `current` reaches the `target` +Adjusts a signed 16-bit integer (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). +Returns FALSE if `current` reaches the `target` ### Lua Example `local integerValue, current = camera_approach_s16_symmetric_bool(current, target, increment)` @@ -1068,7 +1099,9 @@ Adjusts a signed 16-bit integer (`current`) towards a target (`target`) symmetri ## [set_or_approach_s16_symmetric](#set_or_approach_s16_symmetric) ### Description -Smoothly transitions or directly sets a signed 16-bit value (`current`) to approach a target (`target`). Uses symmetric scaling for gradual or immediate adjustments. Returns FALSE if `current` reaches the `target` +Smoothly transitions or directly sets a signed 16-bit value (`current`) to approach a target (`target`). +Uses symmetric scaling for gradual or immediate adjustments. +Returns FALSE if `current` reaches the `target` ### Lua Example `local integerValue, current = set_or_approach_s16_symmetric(current, target, increment)` @@ -1094,7 +1127,8 @@ Smoothly transitions or directly sets a signed 16-bit value (`current`) to appro ## [camera_approach_f32_symmetric_bool](#camera_approach_f32_symmetric_bool) ### Description -Adjusts a floating-point value (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). Returns FALSE if `current` reaches the `target` +Adjusts a floating-point value (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). +Returns FALSE if `current` reaches the `target` ### Lua Example `local integerValue, current = camera_approach_f32_symmetric_bool(current, target, increment)` @@ -1120,7 +1154,8 @@ Adjusts a floating-point value (`current`) towards a target (`target`) symmetric ## [camera_approach_f32_symmetric](#camera_approach_f32_symmetric) ### Description -Symmetrically approaches a floating-point value (`target`) with a fixed increment (`increment`) per frame. Limits the rate of change to ensure gradual transitions +Symmetrically approaches a floating-point value (`target`) with a fixed increment (`increment`) per frame. +Limits the rate of change to ensure gradual transitions ### Lua Example `local numberValue = camera_approach_f32_symmetric(value, target, increment)` @@ -1145,7 +1180,8 @@ Symmetrically approaches a floating-point value (`target`) with a fixed incremen ## [random_vec3s](#random_vec3s) ### Description -Generates a random 3D vector with short integer components. Useful for randomized offsets or environmental effects +Generates a random 3D vector with short integer components. +Useful for randomized offsets or environmental effects ### Lua Example `random_vec3s(dst, xRange, yRange, zRange)` @@ -1171,7 +1207,8 @@ Generates a random 3D vector with short integer components. Useful for randomize ## [clamp_positions_and_find_yaw](#clamp_positions_and_find_yaw) ### Description -Clamps a position within specified X and Z bounds and calculates the yaw angle from the origin. Prevents the camera from moving outside of the designated area +Clamps a position within specified X and Z bounds and calculates the yaw angle from the origin. +Prevents the camera from moving outside of the designated area ### Lua Example `local integerValue = clamp_positions_and_find_yaw(pos, origin, xMax, xMin, zMax, zMin)` @@ -1199,7 +1236,8 @@ Clamps a position within specified X and Z bounds and calculates the yaw angle f ## [is_range_behind_surface](#is_range_behind_surface) ### Description -Determines if a range is obstructed by a surface relative to the camera. Returns true if the range is behind the specified surface +Determines if a range is obstructed by a surface relative to the camera. +Returns true if the range is behind the specified surface ### Lua Example `local integerValue = is_range_behind_surface(from, to, surf, range, surfType)` @@ -1226,7 +1264,9 @@ Determines if a range is obstructed by a surface relative to the camera. Returns ## [scale_along_line](#scale_along_line) ### Description -Scales a point along a line between two 3D points (`from` and `to`). The scaling factor determines how far along the line the resulting point will be. The result is stored in the destination vector (`dest`) +Scales a point along a line between two 3D points (`from` and `to`). +The scaling factor determines how far along the line the resulting point will be. +The result is stored in the destination vector (`dest`) ### Lua Example `scale_along_line(dest, from, to, scale)` @@ -1252,7 +1292,8 @@ Scales a point along a line between two 3D points (`from` and `to`). The scaling ## [calculate_pitch](#calculate_pitch) ### Description -Calculates the pitch angle (rotation around the X-axis) from one 3D point (`from`) to another (`to`). Returns the pitch as a signed 16-bit integer +Calculates the pitch angle (rotation around the X-axis) from one 3D point (`from`) to another (`to`). +Returns the pitch as a signed 16-bit integer ### Lua Example `local integerValue = calculate_pitch(from, to)` @@ -1276,7 +1317,8 @@ Calculates the pitch angle (rotation around the X-axis) from one 3D point (`from ## [calculate_yaw](#calculate_yaw) ### Description -Determines the yaw angle (rotation around the Y-axis) from one 3D position (`from`) to another (`to`). Returns the yaw as a signed 16-bit integer +Determines the yaw angle (rotation around the Y-axis) from one 3D position (`from`) to another (`to`). +Returns the yaw as a signed 16-bit integer ### Lua Example `local integerValue = calculate_yaw(from, to)` @@ -1325,7 +1367,9 @@ Calculates and returns the pitch and yaw angles from one 3D position (`from`) to ## [calc_abs_dist](#calc_abs_dist) ### Description -Calculates the absolute distance between two 3D points (`a` and `b`). Returns the distance as a floating-point value. Useful for determining proximity between objects in 3D space +Calculates the absolute distance between two 3D points (`a` and `b`). +Returns the distance as a floating-point value. +Useful for determining proximity between objects in 3D space ### Lua Example `local numberValue = calc_abs_dist(a, b)` @@ -1349,7 +1393,9 @@ Calculates the absolute distance between two 3D points (`a` and `b`). Returns th ## [calc_hor_dist](#calc_hor_dist) ### Description -Calculates the horizontal (XZ-plane) distance between two 3D points (`a` and `b`). Returns the distance as a floating-point value. Useful for terrain navigation or collision detection +Calculates the horizontal (XZ-plane) distance between two 3D points (`a` and `b`). +Returns the distance as a floating-point value. +Useful for terrain navigation or collision detection ### Lua Example `local numberValue = calc_hor_dist(a, b)` @@ -1373,7 +1419,9 @@ Calculates the horizontal (XZ-plane) distance between two 3D points (`a` and `b` ## [rotate_in_xz](#rotate_in_xz) ### Description -Rotates a vector around the XZ-plane by a specified yaw angle. The result is stored in the destination vector (`dst`). Useful for rotating camera positions or object coordinates horizontally +Rotates a vector around the XZ-plane by a specified yaw angle. +The result is stored in the destination vector (`dst`). +Useful for rotating camera positions or object coordinates horizontally ### Lua Example `rotate_in_xz(dst, src, yaw)` @@ -1398,7 +1446,9 @@ Rotates a vector around the XZ-plane by a specified yaw angle. The result is sto ## [rotate_in_yz](#rotate_in_yz) ### Description -Rotates a vector around the YZ-plane by a specified pitch angle. The result is stored in the destination vector (`dst`). Useful for vertical camera rotations or object transformations +Rotates a vector around the YZ-plane by a specified pitch angle. +The result is stored in the destination vector (`dst`). +Useful for vertical camera rotations or object transformations ### Lua Example `rotate_in_yz(dst, src, pitch)` @@ -1423,7 +1473,9 @@ Rotates a vector around the YZ-plane by a specified pitch angle. The result is s ## [set_camera_pitch_shake](#set_camera_pitch_shake) ### Description -Applies a pitch-based shake effect to the camera. The shake's magnitude, decay, and increment are configurable. Simulates vertical disturbances like impacts or explosions +Applies a pitch-based shake effect to the camera. +The shake's magnitude, decay, and increment are configurable. +Simulates vertical disturbances like impacts or explosions ### Lua Example `set_camera_pitch_shake(mag, decay, inc)` @@ -1448,7 +1500,8 @@ Applies a pitch-based shake effect to the camera. The shake's magnitude, decay, ## [set_camera_yaw_shake](#set_camera_yaw_shake) ### Description -Applies a yaw-based shake effect to the camera. Simulates horizontal vibrations or rotational impacts +Applies a yaw-based shake effect to the camera. +Simulates horizontal vibrations or rotational impacts ### Lua Example `set_camera_yaw_shake(mag, decay, inc)` @@ -1473,7 +1526,8 @@ Applies a yaw-based shake effect to the camera. Simulates horizontal vibrations ## [set_camera_roll_shake](#set_camera_roll_shake) ### Description -Applies a roll-based shake effect to the camera. Simulates rotational disturbances for dynamic camera effects +Applies a roll-based shake effect to the camera. +Simulates rotational disturbances for dynamic camera effects ### Lua Example `set_camera_roll_shake(mag, decay, inc)` @@ -1498,7 +1552,8 @@ Applies a roll-based shake effect to the camera. Simulates rotational disturbanc ## [set_pitch_shake_from_point](#set_pitch_shake_from_point) ### Description -Applies a pitch shake effect to the camera, scaled by proximity to a specified point. Simulates vibrations with intensity decreasing further from the point +Applies a pitch shake effect to the camera, scaled by proximity to a specified point. +Simulates vibrations with intensity decreasing further from the point ### Lua Example `set_pitch_shake_from_point(mag, decay, inc, maxDist, posX, posY, posZ)` @@ -1527,7 +1582,8 @@ Applies a pitch shake effect to the camera, scaled by proximity to a specified p ## [shake_camera_pitch](#shake_camera_pitch) ### Description -Activates a pitch-based shake effect. Adds vertical vibrational movement to the camera's behavior +Activates a pitch-based shake effect. +Adds vertical vibrational movement to the camera's behavior ### Lua Example `shake_camera_pitch(pos, focus)` @@ -1551,7 +1607,8 @@ Activates a pitch-based shake effect. Adds vertical vibrational movement to the ## [shake_camera_yaw](#shake_camera_yaw) ### Description -Activates a yaw-based shake effect. Adds horizontal vibrational movement to the camera's behavior +Activates a yaw-based shake effect. +Adds horizontal vibrational movement to the camera's behavior ### Lua Example `shake_camera_yaw(pos, focus)` @@ -1575,7 +1632,8 @@ Activates a yaw-based shake effect. Adds horizontal vibrational movement to the ## [shake_camera_roll](#shake_camera_roll) ### Description -Applies a roll-based shake effect to the camera. Simulates rotational disturbances caused by impacts or other events +Applies a roll-based shake effect to the camera. +Simulates rotational disturbances caused by impacts or other events ### Lua Example `local roll = shake_camera_roll(roll)` @@ -1598,7 +1656,8 @@ Applies a roll-based shake effect to the camera. Simulates rotational disturbanc ## [offset_yaw_outward_radial](#offset_yaw_outward_radial) ### Description -Calculates an outward radial offset based on the camera's yaw angle. Returns the offset yaw, used for positioning or alignment +Calculates an outward radial offset based on the camera's yaw angle. +Returns the offset yaw, used for positioning or alignment ### Lua Example `local integerValue = offset_yaw_outward_radial(c, areaYaw)` @@ -1622,7 +1681,8 @@ Calculates an outward radial offset based on the camera's yaw angle. Returns the ## [play_camera_buzz_if_cdown](#play_camera_buzz_if_cdown) ### Description -Plays a buzzing sound effect when the camera attempts to move downward but is restricted. Provides feedback for invalid C-Down input actions +Plays a buzzing sound effect when the camera attempts to move downward but is restricted. +Provides feedback for invalid C-Down input actions ### Lua Example `play_camera_buzz_if_cdown()` @@ -1643,7 +1703,8 @@ Plays a buzzing sound effect when the camera attempts to move downward but is re ## [play_camera_buzz_if_cbutton](#play_camera_buzz_if_cbutton) ### Description -Plays a buzzing sound effect when a blocked C-button action is attempted. Used to signal invalid input or restricted camera movement +Plays a buzzing sound effect when a blocked C-button action is attempted. +Used to signal invalid input or restricted camera movement ### Lua Example `play_camera_buzz_if_cbutton()` @@ -1664,7 +1725,8 @@ Plays a buzzing sound effect when a blocked C-button action is attempted. Used t ## [play_camera_buzz_if_c_sideways](#play_camera_buzz_if_c_sideways) ### Description -Plays a buzzing sound effect when the camera's position is misaligned with the player's perspective. Used as audio feedback for incorrect camera behavior +Plays a buzzing sound effect when the camera's position is misaligned with the player's perspective. +Used as audio feedback for incorrect camera behavior ### Lua Example `play_camera_buzz_if_c_sideways()` @@ -1685,7 +1747,8 @@ Plays a buzzing sound effect when the camera's position is misaligned with the p ## [play_sound_cbutton_up](#play_sound_cbutton_up) ### Description -Plays a sound effect when the C-Up button is pressed for camera movement. Provides feedback for vertical camera adjustments +Plays a sound effect when the C-Up button is pressed for camera movement. +Provides feedback for vertical camera adjustments ### Lua Example `play_sound_cbutton_up()` @@ -1706,7 +1769,8 @@ Plays a sound effect when the C-Up button is pressed for camera movement. Provid ## [play_sound_cbutton_down](#play_sound_cbutton_down) ### Description -Plays a sound effect when the C-Down button is pressed for camera movement. Provides auditory feedback for valid camera input +Plays a sound effect when the C-Down button is pressed for camera movement. +Provides auditory feedback for valid camera input ### Lua Example `play_sound_cbutton_down()` @@ -1727,7 +1791,8 @@ Plays a sound effect when the C-Down button is pressed for camera movement. Prov ## [play_sound_cbutton_side](#play_sound_cbutton_side) ### Description -Plays a sound effect when the C-Side button (left or right) is pressed for camera movement. Used as audio feedback for horizontal adjustments to the camera +Plays a sound effect when the C-Side button (left or right) is pressed for camera movement. +Used as audio feedback for horizontal adjustments to the camera ### Lua Example `play_sound_cbutton_side()` @@ -1748,7 +1813,8 @@ Plays a sound effect when the C-Side button (left or right) is pressed for camer ## [play_sound_button_change_blocked](#play_sound_button_change_blocked) ### Description -Plays a sound effect when a blocked action changes the camera mode. This provides feedback for invalid attempts to switch the camera state +Plays a sound effect when a blocked action changes the camera mode. +This provides feedback for invalid attempts to switch the camera state ### Lua Example `play_sound_button_change_blocked()` @@ -1769,7 +1835,8 @@ Plays a sound effect when a blocked action changes the camera mode. This provide ## [play_sound_rbutton_changed](#play_sound_rbutton_changed) ### Description -Plays a sound effect when the R-Button camera mode is changed. Provides feedback for toggling camera behaviors +Plays a sound effect when the R-Button camera mode is changed. +Provides feedback for toggling camera behaviors ### Lua Example `play_sound_rbutton_changed()` @@ -1790,7 +1857,8 @@ Plays a sound effect when the R-Button camera mode is changed. Provides feedback ## [play_sound_if_cam_switched_to_lakitu_or_mario](#play_sound_if_cam_switched_to_lakitu_or_mario) ### Description -Plays a sound effect when the camera switches between Lakitu and Mario perspectives. Signals a successful change in camera mode +Plays a sound effect when the camera switches between Lakitu and Mario perspectives. +Signals a successful change in camera mode ### Lua Example `play_sound_if_cam_switched_to_lakitu_or_mario()` @@ -1811,7 +1879,8 @@ Plays a sound effect when the camera switches between Lakitu and Mario perspecti ## [radial_camera_input](#radial_camera_input) ### Description -Handles radial camera movement based on player input. Updates the camera's position or orientation accordingly +Handles radial camera movement based on player input. +Updates the camera's position or orientation accordingly ### Lua Example `local integerValue = radial_camera_input(c, unused)` @@ -1835,7 +1904,8 @@ Handles radial camera movement based on player input. Updates the camera's posit ## [trigger_cutscene_dialog](#trigger_cutscene_dialog) ### Description -Triggers a dialog sequence during a cutscene. The dialog is synchronized with the camera's position and movement +Triggers a dialog sequence during a cutscene. +The dialog is synchronized with the camera's position and movement ### Lua Example `local integerValue = trigger_cutscene_dialog(trigger)` @@ -1858,7 +1928,8 @@ Triggers a dialog sequence during a cutscene. The dialog is synchronized with th ## [handle_c_button_movement](#handle_c_button_movement) ### Description -Handles camera movement based on input from the C-buttons. Updates the camera's position or angle to match directional player input +Handles camera movement based on input from the C-buttons. +Updates the camera's position or angle to match directional player input ### Lua Example `handle_c_button_movement(c)` @@ -1881,7 +1952,8 @@ Handles camera movement based on input from the C-buttons. Updates the camera's ## [start_cutscene](#start_cutscene) ### Description -Starts a cutscene based on the provided ID. The camera transitions to predefined behaviors for the duration of the cutscene +Starts a cutscene based on the provided ID. +The camera transitions to predefined behaviors for the duration of the cutscene ### Lua Example `start_cutscene(c, cutscene)` @@ -1905,7 +1977,8 @@ Starts a cutscene based on the provided ID. The camera transitions to predefined ## [get_cutscene_from_mario_status](#get_cutscene_from_mario_status) ### Description -Gets the appropriate cutscene to play based on Mario's current gameplay state. This function helps determine transitions for cinematic or scripted sequences +Gets the appropriate cutscene to play based on Mario's current gameplay state. +This function helps determine transitions for cinematic or scripted sequences ### Lua Example `local integerValue = get_cutscene_from_mario_status(c)` @@ -1928,7 +2001,8 @@ Gets the appropriate cutscene to play based on Mario's current gameplay state. T ## [warp_camera](#warp_camera) ### Description -Moves the camera to a specified warp destination. This function handles transitions between levels or areas seamlessly +Moves the camera to a specified warp destination. +This function handles transitions between levels or areas seamlessly ### Lua Example `warp_camera(displacementX, displacementY, displacementZ)` @@ -1953,7 +2027,8 @@ Moves the camera to a specified warp destination. This function handles transiti ## [approach_camera_height](#approach_camera_height) ### Description -Adjusts the camera's height toward a target value (`goalHeight`) while respecting terrain and obstructions. This is really wonky and probably shouldn't be used, prefer `gLakituStates` +Adjusts the camera's height toward a target value (`goalHeight`) while respecting terrain and obstructions. +This is really wonky and probably shouldn't be used, prefer `gLakituStates` ### Lua Example `approach_camera_height(c, goal, inc)` @@ -1978,7 +2053,8 @@ Adjusts the camera's height toward a target value (`goalHeight`) while respectin ## [offset_rotated](#offset_rotated) ### Description -Offsets a vector by rotating it in 3D space relative to a reference position. This is useful for creating radial effects or dynamic transformations +Offsets a vector by rotating it in 3D space relative to a reference position. +This is useful for creating radial effects or dynamic transformations ### Lua Example `offset_rotated(dst, from, to, rotation)` @@ -2004,7 +2080,8 @@ Offsets a vector by rotating it in 3D space relative to a reference position. Th ## [next_lakitu_state](#next_lakitu_state) ### Description -Transitions the camera to the next Lakitu state, updating position and focus. This function handles smooth transitions between different gameplay scenarios +Transitions the camera to the next Lakitu state, updating position and focus. +This function handles smooth transitions between different gameplay scenarios ### Lua Example `local integerValue = next_lakitu_state(newPos, newFoc, curPos, curFoc, oldPos, oldFoc, yaw)` @@ -2056,7 +2133,8 @@ Set the fixed camera base pos depending on the current level area ## [camera_course_processing](#camera_course_processing) ### Description -Processes course-specific camera settings, such as predefined positions or modes. Adjusts the camera to match the design and gameplay requirements of the current course +Processes course-specific camera settings, such as predefined positions or modes. +Adjusts the camera to match the design and gameplay requirements of the current course ### Lua Example `local integerValue = camera_course_processing(c)` @@ -2079,7 +2157,8 @@ Processes course-specific camera settings, such as predefined positions or modes ## [resolve_geometry_collisions](#resolve_geometry_collisions) ### Description -Resolves collisions between the camera and level geometry. Adjusts the camera's position to prevent clipping or intersecting with objects +Resolves collisions between the camera and level geometry. +Adjusts the camera's position to prevent clipping or intersecting with objects ### Lua Example `resolve_geometry_collisions(pos, lastGood)` @@ -2103,7 +2182,8 @@ Resolves collisions between the camera and level geometry. Adjusts the camera's ## [rotate_camera_around_walls](#rotate_camera_around_walls) ### Description -Rotates the camera to avoid walls or other obstructions. Ensures clear visibility of the player or target objects +Rotates the camera to avoid walls or other obstructions. +Ensures clear visibility of the player or target objects ### Lua Example `local integerValue, avoidYaw = rotate_camera_around_walls(c, cPos, avoidYaw, yawRange)` @@ -2130,7 +2210,8 @@ Rotates the camera to avoid walls or other obstructions. Ensures clear visibilit ## [start_object_cutscene_without_focus](#start_object_cutscene_without_focus) ### Description -Starts a cutscene focused on an object without requiring focus to remain locked. This is useful for dynamic events where the camera adjusts freely +Starts a cutscene focused on an object without requiring focus to remain locked. +This is useful for dynamic events where the camera adjusts freely ### Lua Example `local integerValue = start_object_cutscene_without_focus(cutscene)` @@ -2153,7 +2234,8 @@ Starts a cutscene focused on an object without requiring focus to remain locked. ## [cutscene_object_with_dialog](#cutscene_object_with_dialog) ### Description -Starts a cutscene involving an object and displays dialog during the sequence. The camera focuses on the object while synchronizing dialog with the scene +Starts a cutscene involving an object and displays dialog during the sequence. +The camera focuses on the object while synchronizing dialog with the scene ### Lua Example `local integerValue = cutscene_object_with_dialog(cutscene, o, dialogID)` @@ -2178,7 +2260,8 @@ Starts a cutscene involving an object and displays dialog during the sequence. T ## [cutscene_object_without_dialog](#cutscene_object_without_dialog) ### Description -Starts a cutscene involving an object without dialog. The camera transitions smoothly to focus on the object +Starts a cutscene involving an object without dialog. +The camera transitions smoothly to focus on the object ### Lua Example `local integerValue = cutscene_object_without_dialog(cutscene, o)` @@ -2202,7 +2285,8 @@ Starts a cutscene involving an object without dialog. The camera transitions smo ## [cutscene_object](#cutscene_object) ### Description -Initiates a cutscene focusing on a specific object in the game world. The camera transitions smoothly to the object, adapting its position as needed +Initiates a cutscene focusing on a specific object in the game world. +The camera transitions smoothly to the object, adapting its position as needed ### Lua Example `local integerValue = cutscene_object(cutscene, o)` @@ -2226,7 +2310,8 @@ Initiates a cutscene focusing on a specific object in the game world. The camera ## [play_cutscene](#play_cutscene) ### Description -Starts the execution of a predefined cutscene. The camera transitions dynamically to follow the scripted sequence +Starts the execution of a predefined cutscene. +The camera transitions dynamically to follow the scripted sequence ### Lua Example `play_cutscene(c)` @@ -2249,7 +2334,8 @@ Starts the execution of a predefined cutscene. The camera transitions dynamicall ## [cutscene_spawn_obj](#cutscene_spawn_obj) ### Description -Spawns an object as part of a cutscene, such as props or interactive elements. Returns the spawned object's reference for further manipulation +Spawns an object as part of a cutscene, such as props or interactive elements. +Returns the spawned object's reference for further manipulation ### Lua Example `local integerValue = cutscene_spawn_obj(obj, frame)` @@ -2273,7 +2359,8 @@ Spawns an object as part of a cutscene, such as props or interactive elements. R ## [set_fov_shake](#set_fov_shake) ### Description -Applies a field-of-view shake effect to simulate zoom or focus disruptions. Shake parameters, such as amplitude and decay, control the intensity +Applies a field-of-view shake effect to simulate zoom or focus disruptions. +Shake parameters, such as amplitude and decay, control the intensity ### Lua Example `set_fov_shake(amplitude, decay, shakeSpeed)` @@ -2298,7 +2385,8 @@ Applies a field-of-view shake effect to simulate zoom or focus disruptions. Shak ## [set_fov_function](#set_fov_function) ### Description -Assigns a custom function for dynamic field-of-view adjustments. This allows precise control over the camera's zoom behavior during gameplay +Assigns a custom function for dynamic field-of-view adjustments. +This allows precise control over the camera's zoom behavior during gameplay ### Lua Example `set_fov_function(func)` @@ -2321,7 +2409,8 @@ Assigns a custom function for dynamic field-of-view adjustments. This allows pre ## [cutscene_set_fov_shake_preset](#cutscene_set_fov_shake_preset) ### Description -Applies a preset field-of-view shake effect during a cutscene. This creates dynamic visual effects, such as zoom or focus disruptions +Applies a preset field-of-view shake effect during a cutscene. +This creates dynamic visual effects, such as zoom or focus disruptions ### Lua Example `cutscene_set_fov_shake_preset(preset)` @@ -2344,7 +2433,8 @@ Applies a preset field-of-view shake effect during a cutscene. This creates dyna ## [set_fov_shake_from_point_preset](#set_fov_shake_from_point_preset) ### Description -Applies a preset field-of-view shake effect relative to a specific point. The intensity diminishes as the distance from the point increases +Applies a preset field-of-view shake effect relative to a specific point. +The intensity diminishes as the distance from the point increases ### Lua Example `set_fov_shake_from_point_preset(preset, posX, posY, posZ)` @@ -2370,7 +2460,8 @@ Applies a preset field-of-view shake effect relative to a specific point. The in ## [obj_rotate_towards_point](#obj_rotate_towards_point) ### Description -Rotates an object toward a specific point in 3D space. Gradually updates the object's pitch and yaw angles to face the target +Rotates an object toward a specific point in 3D space. +Gradually updates the object's pitch and yaw angles to face the target ### Lua Example `obj_rotate_towards_point(o, point, pitchOff, yawOff, pitchDiv, yawDiv)` @@ -2398,7 +2489,8 @@ Rotates an object toward a specific point in 3D space. Gradually updates the obj ## [set_camera_mode_fixed](#set_camera_mode_fixed) ### Description -Activates a fixed camera mode and aligns the camera to specific X, Y, Z coordinates. This is useful for predefined static views in specific areas +Activates a fixed camera mode and aligns the camera to specific X, Y, Z coordinates. +This is useful for predefined static views in specific areas ### Lua Example `local integerValue = set_camera_mode_fixed(c, x, y, z)` @@ -2424,7 +2516,8 @@ Activates a fixed camera mode and aligns the camera to specific X, Y, Z coordina ## [snap_to_45_degrees](#snap_to_45_degrees) ### Description -Takes in an SM64 angle unit and returns the nearest 45 degree angle, also in SM64 angle units. Useful when needing to align angles (camera, yaw, etc.) +Takes in an SM64 angle unit and returns the nearest 45 degree angle, also in SM64 angle units. +Useful when needing to align angles (camera, yaw, etc.) ### Lua Example `local integerValue = snap_to_45_degrees(angle)` @@ -2447,7 +2540,8 @@ Takes in an SM64 angle unit and returns the nearest 45 degree angle, also in SM6 ## [camera_set_use_course_specific_settings](#camera_set_use_course_specific_settings) ### Description -Toggles whether the camera uses course-specific settings. This is useful for enabling or disabling custom behaviors in specific courses or areas +Toggles whether the camera uses course-specific settings. +This is useful for enabling or disabling custom behaviors in specific courses or areas ### Lua Example `camera_set_use_course_specific_settings(enable)` @@ -2470,7 +2564,8 @@ Toggles whether the camera uses course-specific settings. This is useful for ena ## [center_rom_hack_camera](#center_rom_hack_camera) ### Description -Centers the ROM hack camera. This function is designed for non-standard level layouts and modded game environments +Centers the ROM hack camera. +This function is designed for non-standard level layouts and modded game environments ### Lua Example `center_rom_hack_camera()` @@ -2520,7 +2615,8 @@ Gets a Character struct from `m` ## [play_character_sound](#play_character_sound) ### Description -Plays a character-specific sound based on the given `characterSound` value. The sound is tied to Mario's current state (`m`). Useful for triggering sound effects for actions like jumping or interacting with the environment +Plays a character-specific sound based on the given `characterSound` value. The sound is tied to Mario's current state (`m`). +Useful for triggering sound effects for actions like jumping or interacting with the environment ### Lua Example `play_character_sound(m, characterSound)` @@ -2544,7 +2640,8 @@ Plays a character-specific sound based on the given `characterSound` value. The ## [play_character_sound_offset](#play_character_sound_offset) ### Description -Plays a character-specific sound with an additional `offset`, allowing variations or delays in the sound effect. Uses Mario's current state (`m`). Useful for adding dynamic sound effects or syncing sounds to specific animations or events +Plays a character-specific sound with an additional `offset`, allowing variations or delays in the sound effect. Uses Mario's current state (`m`). +Useful for adding dynamic sound effects or syncing sounds to specific animations or events ### Lua Example `play_character_sound_offset(m, characterSound, offset)` @@ -2569,7 +2666,8 @@ Plays a character-specific sound with an additional `offset`, allowing variation ## [play_character_sound_if_no_flag](#play_character_sound_if_no_flag) ### Description -Plays a character-specific sound only if certain flags are not set. This ensures that sounds are not repeated unnecessarily. The sound is based on `characterSound`, and the flags are checked using `flags`. Useful for avoiding duplicate sound effects in rapid succession or conditional actions +Plays a character-specific sound only if certain flags are not set. This ensures that sounds are not repeated unnecessarily. The sound is based on `characterSound`, and the flags are checked using `flags`. +Useful for avoiding duplicate sound effects in rapid succession or conditional actions ### Lua Example `play_character_sound_if_no_flag(m, characterSound, flags)` @@ -2594,7 +2692,8 @@ Plays a character-specific sound only if certain flags are not set. This ensures ## [get_character_anim_offset](#get_character_anim_offset) ### Description -Calculates the animation offset for Mario's current animation. The offset is determined by the type of animation being played (e.g., hand, feet, or torso movement). Useful for smoothly syncing Mario's model height or positional adjustments during animations +Calculates the animation offset for Mario's current animation. The offset is determined by the type of animation being played (e.g., hand, feet, or torso movement). +Useful for smoothly syncing Mario's model height or positional adjustments during animations ### Lua Example `local numberValue = get_character_anim_offset(m)` @@ -2617,7 +2716,8 @@ Calculates the animation offset for Mario's current animation. The offset is det ## [get_character_anim](#get_character_anim) ### Description -Gets the animation ID to use for a specific character and animation combination. The ID is based on `characterAnim` and the character currently controlled by Mario (`m`). Useful for determining which animation to play for actions like walking, jumping, or idle states +Gets the animation ID to use for a specific character and animation combination. The ID is based on `characterAnim` and the character currently controlled by Mario (`m`). +Useful for determining which animation to play for actions like walking, jumping, or idle states ### Lua Example `local integerValue = get_character_anim(m, characterAnim)` @@ -2641,7 +2741,8 @@ Gets the animation ID to use for a specific character and animation combination. ## [update_character_anim_offset](#update_character_anim_offset) ### Description -Updates Mario's current animation offset. This adjusts Mario's position based on the calculated offset to ensure animations appear smooth and natural. Useful for keeping Mario's animations visually aligned, particularly when transitioning between animations +Updates Mario's current animation offset. This adjusts Mario's position based on the calculated offset to ensure animations appear smooth and natural. +Useful for keeping Mario's animations visually aligned, particularly when transitioning between animations ### Lua Example `update_character_anim_offset(m)` @@ -5199,7 +5300,8 @@ Sets the state for a dialog box (`DIALOG_STATE_*`) ## [interact_coin](#interact_coin) ### Description -Handles Mario's interaction with coins. Collecting a coin increases Mario's coin count and heals him slightly. Useful for score, and coin management +Handles Mario's interaction with coins. Collecting a coin increases Mario's coin count and heals him slightly. +Useful for score, and coin management ### Lua Example `local integerValue = interact_coin(m, interactType, o)` @@ -5224,7 +5326,8 @@ Handles Mario's interaction with coins. Collecting a coin increases Mario's coin ## [interact_water_ring](#interact_water_ring) ### Description -Handles interactions with water rings that heal Mario. Passing through water rings increases his health counter. Useful for underwater stages +Handles interactions with water rings that heal Mario. Passing through water rings increases his health counter. +Useful for underwater stages ### Lua Example `local integerValue = interact_water_ring(m, interactType, o)` @@ -5249,7 +5352,8 @@ Handles interactions with water rings that heal Mario. Passing through water rin ## [interact_star_or_key](#interact_star_or_key) ### Description -Handles interaction with Stars or Keys. If Mario collects a star or key, it triggers a specific star grab cutscene and progression is updated. Also handles no-exit variants (like the wing cap stage star). Useful for the main progression system of collecting Stars and unlocking new areas +Handles interaction with Stars or Keys. If Mario collects a star or key, it triggers a specific star grab cutscene and progression is updated. Also handles no-exit variants (like the wing cap stage star). +Useful for the main progression system of collecting Stars and unlocking new areas ### Lua Example `local integerValue = interact_star_or_key(m, interactType, o)` @@ -5299,7 +5403,8 @@ Handles Mario's interaction with the Boo's Big Haunt (BBH) entrance object. When ## [interact_warp](#interact_warp) ### Description -Handles interaction with warps, including warp pipes and hole warps. If Mario steps onto a warp, he either transitions into another area or level. Useful for connecting different parts of the game world and controlling transitions between levels as well as custom warp areas +Handles interaction with warps, including warp pipes and hole warps. If Mario steps onto a warp, he either transitions into another area or level. +Useful for connecting different parts of the game world and controlling transitions between levels as well as custom warp areas ### Lua Example `local integerValue = interact_warp(m, interactType, o)` @@ -5324,7 +5429,8 @@ Handles interaction with warps, including warp pipes and hole warps. If Mario st ## [interact_warp_door](#interact_warp_door) ### Description -Handles interaction with warp doors that lead to other areas or require keys. If Mario can open the door (has enough stars or a key), he proceeds. Otherwise, it may show a dialog. Useful for restricting access to certain areas based on progression +Handles interaction with warp doors that lead to other areas or require keys. If Mario can open the door (has enough stars or a key), he proceeds. Otherwise, it may show a dialog. +Useful for restricting access to certain areas based on progression ### Lua Example `local integerValue = interact_warp_door(m, interactType, o)` @@ -5349,7 +5455,8 @@ Handles interaction with warp doors that lead to other areas or require keys. If ## [interact_door](#interact_door) ### Description -Handles interaction when Mario touches a door. If Mario meets the star requirement or has the key, he can unlock/open the door. Otherwise, it may display dialog indicating the requirement. Useful for controlling access to locked areas and providing progression gating in the game +Handles interaction when Mario touches a door. If Mario meets the star requirement or has the key, he can unlock/open the door. Otherwise, it may display dialog indicating the requirement. +Useful for controlling access to locked areas and providing progression gating in the game ### Lua Example `local integerValue = interact_door(m, interactType, o)` @@ -5374,7 +5481,8 @@ Handles interaction when Mario touches a door. If Mario meets the star requireme ## [interact_cannon_base](#interact_cannon_base) ### Description -Handles interaction when Mario touches a cannon base. If the cannon is ready, Mario enters the cannon, triggering a special action and camera behavior. Useful for transitioning to cannon-aiming mode and enabling cannon travel within levels +Handles interaction when Mario touches a cannon base. If the cannon is ready, Mario enters the cannon, triggering a special action and camera behavior. +Useful for transitioning to cannon-aiming mode and enabling cannon travel within levels ### Lua Example `local integerValue = interact_cannon_base(m, interactType, o)` @@ -5399,7 +5507,9 @@ Handles interaction when Mario touches a cannon base. If the cannon is ready, Ma ## [interact_player](#interact_player) ### Description -Handles interaction with another player (in multiplayer scenarios). Checks if Mario and another player collide and resolves any special behavior like bouncing on top. Useful for multiplayer interactions, such as PvP or cooperative gameplay mechanics +Handles interaction with another player (in multiplayer scenarios). +Checks if Mario and another player collide and resolves any special behavior like bouncing on top. +Useful for multiplayer interactions, such as PvP or cooperative gameplay mechanics ### Lua Example `local integerValue = interact_player(m, interactType, o)` @@ -5424,7 +5534,8 @@ Handles interaction with another player (in multiplayer scenarios). Checks if Ma ## [interact_igloo_barrier](#interact_igloo_barrier) ### Description -Handles interaction with the igloo barrier found in Snowman's Land. If Mario runs into the barrier, this function pushes him away and prevents passage without the vanish cap. Useful for enforcing require-caps to access certain areas +Handles interaction with the igloo barrier found in Snowman's Land. If Mario runs into the barrier, this function pushes him away and prevents passage without the vanish cap. +Useful for enforcing require-caps to access certain areas ### Lua Example `local integerValue = interact_igloo_barrier(m, interactType, o)` @@ -5449,7 +5560,8 @@ Handles interaction with the igloo barrier found in Snowman's Land. If Mario run ## [interact_tornado](#interact_tornado) ### Description -Handles interaction with tornados. If Mario touches a tornado, he enters a spinning twirl action, losing control temporarily. Useful for desert levels or areas where environmental hazards lift Mario into the air +Handles interaction with tornados. If Mario touches a tornado, he enters a spinning twirl action, losing control temporarily. +Useful for desert levels or areas where environmental hazards lift Mario into the air ### Lua Example `local integerValue = interact_tornado(m, interactType, o)` @@ -5474,7 +5586,8 @@ Handles interaction with tornados. If Mario touches a tornado, he enters a spinn ## [interact_whirlpool](#interact_whirlpool) ### Description -Handles interaction with whirlpools. If Mario gets caught in a whirlpool, he's pulled toward it, resulting in a unique "caught" action. Useful for hazards that trap Mario like whirlpools +Handles interaction with whirlpools. If Mario gets caught in a whirlpool, he's pulled toward it, resulting in a unique "caught" action. +Useful for hazards that trap Mario like whirlpools ### Lua Example `local integerValue = interact_whirlpool(m, interactType, o)` @@ -5499,7 +5612,8 @@ Handles interaction with whirlpools. If Mario gets caught in a whirlpool, he's p ## [interact_strong_wind](#interact_strong_wind) ### Description -Handles interaction with strong wind gusts. These gusts push Mario back, often knocking him off platforms or sending him flying backwards. Useful for environmental wind hazards +Handles interaction with strong wind gusts. These gusts push Mario back, often knocking him off platforms or sending him flying backwards. +Useful for environmental wind hazards ### Lua Example `local integerValue = interact_strong_wind(m, interactType, o)` @@ -5524,7 +5638,8 @@ Handles interaction with strong wind gusts. These gusts push Mario back, often k ## [interact_flame](#interact_flame) ### Description -Handles interaction with flame objects. If Mario touches a flame and is not invulnerable or protected by certain caps, he takes damage and may be set on fire, causing a burning jump. Useful for simulating fire damage and hazards in levels +Handles interaction with flame objects. If Mario touches a flame and is not invulnerable or protected by certain caps, he takes damage and may be set on fire, causing a burning jump. +Useful for simulating fire damage and hazards in levels ### Lua Example `local integerValue = interact_flame(m, interactType, o)` @@ -5574,7 +5689,8 @@ Handles interaction with Snufit bullets (projectiles fired by certain enemies). ## [interact_clam_or_bubba](#interact_clam_or_bubba) ### Description -Handles interactions with objects like Clams or Bubbas, which can damage Mario or, in Bubba's case, eat Mario. If Bubba eats Mario, it triggers a unique "caught" action. Otherwise, it deals damage and knockback if hit by a Clam +Handles interactions with objects like Clams or Bubbas, which can damage Mario or, in Bubba's case, eat Mario. +If Bubba eats Mario, it triggers a unique "caught" action. Otherwise, it deals damage and knockback if hit by a Clam ### Lua Example `local integerValue = interact_clam_or_bubba(m, interactType, o)` @@ -5599,7 +5715,8 @@ Handles interactions with objects like Clams or Bubbas, which can damage Mario o ## [interact_bully](#interact_bully) ### Description -Handles interaction with Bully enemies. Determines if Mario attacks the Bully or gets knocked back. Updates Mario's velocity and state accordingly, and can defeat the Bully if attacked successfully. Useful for enemy encounters that involve pushing and shoving mechanics rather than just stomping like the bullies +Handles interaction with Bully enemies. Determines if Mario attacks the Bully or gets knocked back. Updates Mario's velocity and state accordingly, and can defeat the Bully if attacked successfully. +Useful for enemy encounters that involve pushing and shoving mechanics rather than just stomping like the bullies ### Lua Example `local integerValue = interact_bully(m, interactType, o)` @@ -5624,7 +5741,8 @@ Handles interaction with Bully enemies. Determines if Mario attacks the Bully or ## [interact_shock](#interact_shock) ### Description -Handles interaction with shocking objects. If Mario touches an electrified enemy or hazard, he takes damage and may be stunned or shocked. Useful for electric-themed enemies and obstacles +Handles interaction with shocking objects. If Mario touches an electrified enemy or hazard, he takes damage and may be stunned or shocked. +Useful for electric-themed enemies and obstacles ### Lua Example `local integerValue = interact_shock(m, interactType, o)` @@ -5649,7 +5767,8 @@ Handles interaction with shocking objects. If Mario touches an electrified enemy ## [interact_mr_blizzard](#interact_mr_blizzard) ### Description -Handles interaction with Mr. Blizzard (the snowman enemy) or similar objects. If Mario is attacked or collides with Mr. Blizzard, it applies damage and knockback if not protected or attacking +Handles interaction with Mr. Blizzard (the snowman enemy) or similar objects. +If Mario is attacked or collides with Mr. Blizzard, it applies damage and knockback if not protected or attacking ### Lua Example `local integerValue = interact_mr_blizzard(m, interactType, o)` @@ -5674,7 +5793,8 @@ Handles interaction with Mr. Blizzard (the snowman enemy) or similar objects. If ## [interact_hit_from_below](#interact_hit_from_below) ### Description -Handles interactions where Mario hits an object from below (e.g., hitting a block from underneath). Determines if Mario damages/destroys the object, or if it damages Mario. Useful for handling upward attacks, hitting coin blocks, or interacting with certain NPCs from below +Handles interactions where Mario hits an object from below (e.g., hitting a block from underneath). Determines if Mario damages/destroys the object, or if it damages Mario. +Useful for handling upward attacks, hitting coin blocks, or interacting with certain NPCs from below ### Lua Example `local integerValue = interact_hit_from_below(m, interactType, o)` @@ -5699,7 +5819,9 @@ Handles interactions where Mario hits an object from below (e.g., hitting a bloc ## [interact_bounce_top](#interact_bounce_top) ### Description -Handles interactions where Mario bounces off the top of an object (e.g., Goombas, Koopas). Checks if Mario attacks the object from above and applies the appropriate knockback, sound effects, and object state changes. Useful for enemy defeat mechanics and platform bouncing +Handles interactions where Mario bounces off the top of an object (e.g., Goombas, Koopas). +Checks if Mario attacks the object from above and applies the appropriate knockback, sound effects, and object state changes. +Useful for enemy defeat mechanics and platform bouncing ### Lua Example `local integerValue = interact_bounce_top(m, interactType, o)` @@ -5724,7 +5846,8 @@ Handles interactions where Mario bounces off the top of an object (e.g., Goombas ## [interact_spiny_walking](#interact_spiny_walking) ### Description -Handles interaction with Spiny-walking enemies. If Mario attacks it (e.g., by punching), the enemy is hurt. If he fails to attack properly (say bouncing on top), Mario takes damage and knockback. Useful for enemies that cannot be stomped from above and require direct attacks +Handles interaction with Spiny-walking enemies. If Mario attacks it (e.g., by punching), the enemy is hurt. If he fails to attack properly (say bouncing on top), Mario takes damage and knockback. +Useful for enemies that cannot be stomped from above and require direct attacks ### Lua Example `local integerValue = interact_spiny_walking(m, interactType, o)` @@ -5749,7 +5872,8 @@ Handles interaction with Spiny-walking enemies. If Mario attacks it (e.g., by pu ## [interact_damage](#interact_damage) ### Description -Handles damaging interactions from various objects (e.g., enemies, hazards). If Mario takes damage, it applies knockback and reduces health. Useful for enemy attacks, environmental hazards, and managing damage related behaviors +Handles damaging interactions from various objects (e.g., enemies, hazards). If Mario takes damage, it applies knockback and reduces health. +Useful for enemy attacks, environmental hazards, and managing damage related behaviors ### Lua Example `local integerValue = interact_damage(m, interactType, o)` @@ -5774,7 +5898,8 @@ Handles damaging interactions from various objects (e.g., enemies, hazards). If ## [interact_breakable](#interact_breakable) ### Description -Handles interactions with breakable objects (e.g., breakable boxes or bob-ombs). If Mario hits the object with a valid attack (like a punch or kick), the object is destroyed or changes state. Useful for managing collectible items hidden in breakable objects and level progression through destructible blocks or walls +Handles interactions with breakable objects (e.g., breakable boxes or bob-ombs). If Mario hits the object with a valid attack (like a punch or kick), the object is destroyed or changes state. +Useful for managing collectible items hidden in breakable objects and level progression through destructible blocks or walls ### Lua Example `local integerValue = interact_breakable(m, interactType, o)` @@ -5799,7 +5924,8 @@ Handles interactions with breakable objects (e.g., breakable boxes or bob-ombs). ## [interact_koopa_shell](#interact_koopa_shell) ### Description -Handles interaction when Mario touches a Koopa Shell. If conditions are met, Mario can hop onto the shell and start riding it, changing his movement mechanics. Useful for implementing Koopa Shell behavior +Handles interaction when Mario touches a Koopa Shell. If conditions are met, Mario can hop onto the shell and start riding it, changing his movement mechanics. +Useful for implementing Koopa Shell behavior ### Lua Example `local integerValue = interact_koopa_shell(m, interactType, o)` @@ -5824,7 +5950,8 @@ Handles interaction when Mario touches a Koopa Shell. If conditions are met, Mar ## [interact_pole](#interact_pole) ### Description -Handles interaction with poles (e.g., climbing poles). If Mario runs into a vertical pole, he can grab it and start climbing. Useful for platforming mechanics +Handles interaction with poles (e.g., climbing poles). If Mario runs into a vertical pole, he can grab it and start climbing. +Useful for platforming mechanics ### Lua Example `local integerValue = interact_pole(m, interactType, o)` @@ -5849,7 +5976,8 @@ Handles interaction with poles (e.g., climbing poles). If Mario runs into a vert ## [interact_hoot](#interact_hoot) ### Description -Handles interaction with Hoot, the owl. If Mario can grab onto Hoot, this sets Mario onto a riding action, allowing him to fly around the level. Useful for special traversal mechanics and shortcuts within a course +Handles interaction with Hoot, the owl. If Mario can grab onto Hoot, this sets Mario onto a riding action, allowing him to fly around the level. +Useful for special traversal mechanics and shortcuts within a course ### Lua Example `local integerValue = interact_hoot(m, interactType, o)` @@ -5874,7 +6002,9 @@ Handles interaction with Hoot, the owl. If Mario can grab onto Hoot, this sets M ## [interact_cap](#interact_cap) ### Description -Handles interaction when Mario picks up a cap object. This includes normal caps, wing caps, vanish caps, and metal caps. Updates Mario's state (e.g., cap timers, sound effects) and may initiate putting on the cap animation. Useful for managing cap statuses +Handles interaction when Mario picks up a cap object. This includes normal caps, wing caps, vanish caps, and metal caps. +Updates Mario's state (e.g., cap timers, sound effects) and may initiate putting on the cap animation. +Useful for managing cap statuses ### Lua Example `local integerValue = interact_cap(m, interactType, o)` @@ -5899,7 +6029,8 @@ Handles interaction when Mario picks up a cap object. This includes normal caps, ## [interact_grabbable](#interact_grabbable) ### Description -Handles interaction with grabbable objects (e.g., crates, small enemies, or Bowser). Checks if Mario can pick up the object and initiates the grab action if possible. Useful for course mechanics, throwing items, and Bowser +Handles interaction with grabbable objects (e.g., crates, small enemies, or Bowser). Checks if Mario can pick up the object and initiates the grab action if possible. +Useful for course mechanics, throwing items, and Bowser ### Lua Example `local integerValue = interact_grabbable(m, interactType, o)` @@ -5924,7 +6055,8 @@ Handles interaction with grabbable objects (e.g., crates, small enemies, or Bows ## [interact_text](#interact_text) ### Description -Handles interaction with signs, NPCs, and other text-bearing objects. If Mario presses the interact button facing them, he enters a dialog reading state. Useful for managing hints, story elements, or gameplay instructions through in-game dialogue +Handles interaction with signs, NPCs, and other text-bearing objects. If Mario presses the interact button facing them, he enters a dialog reading state. +Useful for managing hints, story elements, or gameplay instructions through in-game dialogue ### Lua Example `local integerValue = interact_text(m, interactType, o)` @@ -5949,7 +6081,8 @@ Handles interaction with signs, NPCs, and other text-bearing objects. If Mario p ## [mario_obj_angle_to_object](#mario_obj_angle_to_object) ### Description -Calculates the angle between Mario and a specified object. Used for determining Mario's orientation relative to the object. Useful for deciding directions between Mario and NPCs +Calculates the angle between Mario and a specified object. Used for determining Mario's orientation relative to the object. +Useful for deciding directions between Mario and NPCs ### Lua Example `local integerValue = mario_obj_angle_to_object(m, o)` @@ -5973,7 +6106,8 @@ Calculates the angle between Mario and a specified object. Used for determining ## [mario_stop_riding_object](#mario_stop_riding_object) ### Description -Stops Mario from riding any currently ridden object (e.g., a Koopa shell or Hoot), updating the object's interaction status and Mario's state. Useful for cleanly dismounting ridden objects +Stops Mario from riding any currently ridden object (e.g., a Koopa shell or Hoot), updating the object's interaction status and Mario's state. +Useful for cleanly dismounting ridden objects ### Lua Example `mario_stop_riding_object(m)` @@ -5996,7 +6130,9 @@ Stops Mario from riding any currently ridden object (e.g., a Koopa shell or Hoot ## [mario_grab_used_object](#mario_grab_used_object) ### Description -Grabs the object currently referenced by Mario's `usedObj` if it's not already being held. Changes the object's state to indicate it is now held by Mario. Useful for handling the moment Mario successfully picks up an object +Grabs the object currently referenced by Mario's `usedObj` if it's not already being held. +Changes the object's state to indicate it is now held by Mario. +Useful for handling the moment Mario successfully picks up an object ### Lua Example `mario_grab_used_object(m)` @@ -6019,7 +6155,8 @@ Grabs the object currently referenced by Mario's `usedObj` if it's not already b ## [mario_drop_held_object](#mario_drop_held_object) ### Description -Causes Mario to drop the object he is currently holding. Sets the held object's state accordingly and places it in front of Mario. Useful for releasing carried objects, such as throwing Bob-ombs or setting down crates +Causes Mario to drop the object he is currently holding. Sets the held object's state accordingly and places it in front of Mario. +Useful for releasing carried objects, such as throwing Bob-ombs or setting down crates ### Lua Example `mario_drop_held_object(m)` @@ -6042,7 +6179,8 @@ Causes Mario to drop the object he is currently holding. Sets the held object's ## [mario_throw_held_object](#mario_throw_held_object) ### Description -Throws the object Mario is currently holding. The object is placed in front of Mario and given a forward velocity. Useful for attacking enemies with thrown objects, solving puzzles by throwing crates, or interacting with environment items +Throws the object Mario is currently holding. The object is placed in front of Mario and given a forward velocity. +Useful for attacking enemies with thrown objects, solving puzzles by throwing crates, or interacting with environment items ### Lua Example `mario_throw_held_object(m)` @@ -6065,7 +6203,9 @@ Throws the object Mario is currently holding. The object is placed in front of M ## [mario_stop_riding_and_holding](#mario_stop_riding_and_holding) ### Description -Causes Mario to stop riding any object (like a shell or Hoot) and also drop any held object. Resets related states to ensure Mario is no longer attached to or holding anything. Useful when changing Mario's state after certain actions, transitions, or to prevent exploits +Causes Mario to stop riding any object (like a shell or Hoot) and also drop any held object. +Resets related states to ensure Mario is no longer attached to or holding anything. +Useful when changing Mario's state after certain actions, transitions, or to prevent exploits ### Lua Example `mario_stop_riding_and_holding(m)` @@ -6088,7 +6228,9 @@ Causes Mario to stop riding any object (like a shell or Hoot) and also drop any ## [does_mario_have_normal_cap_on_head](#does_mario_have_normal_cap_on_head) ### Description -Checks if Mario is currently wearing his normal cap on his head. Returns true if Mario's flag state matches that of having the normal cap equipped on his head, otherwise false. Useful for determining Mario's cap status +Checks if Mario is currently wearing his normal cap on his head. +Returns true if Mario's flag state matches that of having the normal cap equipped on his head, otherwise false. +Useful for determining Mario's cap status ### Lua Example `local integerValue = does_mario_have_normal_cap_on_head(m)` @@ -6111,7 +6253,9 @@ Checks if Mario is currently wearing his normal cap on his head. Returns true if ## [does_mario_have_blown_cap](#does_mario_have_blown_cap) ### Description -Checks if Mario has already had a cap blown off of his head in the current level, Returns true if a blown cap can be found for Mario, false if not. Useful to check if a blown cap exists in the level currently. +Checks if Mario has already had a cap blown off of his head in the current level, +Returns true if a blown cap can be found for Mario, false if not. +Useful to check if a blown cap exists in the level currently. ### Lua Example `local booleanValue = does_mario_have_blown_cap(m)` @@ -6134,7 +6278,9 @@ Checks if Mario has already had a cap blown off of his head in the current level ## [mario_blow_off_cap](#mario_blow_off_cap) ### Description -Makes Mario blow off his normal cap at a given speed. Removes the normal cap from Mario's head and spawns it as a collectible object in the game world. Useful for simulating events where Mario loses his cap due to enemy attacks or environmental forces +Makes Mario blow off his normal cap at a given speed. +Removes the normal cap from Mario's head and spawns it as a collectible object in the game world. +Useful for simulating events where Mario loses his cap due to enemy attacks or environmental forces ### Lua Example `mario_blow_off_cap(m, capSpeed)` @@ -6158,7 +6304,9 @@ Makes Mario blow off his normal cap at a given speed. Removes the normal cap fro ## [mario_lose_cap_to_enemy](#mario_lose_cap_to_enemy) ### Description -Makes Mario lose his normal cap to an enemy, such as Klepto or Ukiki. Updates flags so that the cap is no longer on Mario's head. Returns true if Mario was wearing his normal cap, otherwise false. Useful for scenarios where enemies steal Mario's cap +Makes Mario lose his normal cap to an enemy, such as Klepto or Ukiki. Updates flags so that the cap is no longer on Mario's head. +Returns true if Mario was wearing his normal cap, otherwise false. +Useful for scenarios where enemies steal Mario's cap ### Lua Example `local integerValue = mario_lose_cap_to_enemy(m, arg)` @@ -6182,7 +6330,9 @@ Makes Mario lose his normal cap to an enemy, such as Klepto or Ukiki. Updates fl ## [mario_retrieve_cap](#mario_retrieve_cap) ### Description -Retrieves Mario's normal cap if it was previously lost. Removes the cap from Mario's hand state and places it on his head. Useful when Mario recovers his normal cap from enemies, finds it in a level, or if it were to disappear +Retrieves Mario's normal cap if it was previously lost. +Removes the cap from Mario's hand state and places it on his head. +Useful when Mario recovers his normal cap from enemies, finds it in a level, or if it were to disappear ### Lua Example `mario_retrieve_cap(m)` @@ -6205,7 +6355,8 @@ Retrieves Mario's normal cap if it was previously lost. Removes the cap from Mar ## [mario_get_collided_object](#mario_get_collided_object) ### Description -Returns a collided object that matches a given interaction type from Mario's current collision data. Useful for determining which object Mario has come into contact with +Returns a collided object that matches a given interaction type from Mario's current collision data. +Useful for determining which object Mario has come into contact with ### Lua Example `local objectValue = mario_get_collided_object(m, interactType)` @@ -6229,7 +6380,8 @@ Returns a collided object that matches a given interaction type from Mario's cur ## [mario_check_object_grab](#mario_check_object_grab) ### Description -Checks if Mario can grab the currently encountered object (usually triggered when Mario punches or dives). If conditions are met, initiates the grabbing process. Useful for picking up objects, throwing enemies, or grabbing special items +Checks if Mario can grab the currently encountered object (usually triggered when Mario punches or dives). If conditions are met, initiates the grabbing process. +Useful for picking up objects, throwing enemies, or grabbing special items ### Lua Example `local integerValue = mario_check_object_grab(m)` @@ -6252,7 +6404,8 @@ Checks if Mario can grab the currently encountered object (usually triggered whe ## [get_door_save_file_flag](#get_door_save_file_flag) ### Description -Retrieves the save file flag associated with a door, based on the number of stars required to open it. Used to check if the player has unlocked certain star doors or progressed far enough to access new areas +Retrieves the save file flag associated with a door, based on the number of stars required to open it. +Used to check if the player has unlocked certain star doors or progressed far enough to access new areas ### Lua Example `local integerValue = get_door_save_file_flag(door)` @@ -6275,7 +6428,9 @@ Retrieves the save file flag associated with a door, based on the number of star ## [passes_pvp_interaction_checks](#passes_pvp_interaction_checks) ### Description -Checks if the necessary conditions are met for one player to successfully attack another player in a PvP scenario. Considers factors like invincibility, action states, and whether the attack is valid. Useful for multiplayer where players can harm each other +Checks if the necessary conditions are met for one player to successfully attack another player in a PvP scenario. +Considers factors like invincibility, action states, and whether the attack is valid. +Useful for multiplayer where players can harm each other ### Lua Example `local integerValue = passes_pvp_interaction_checks(attacker, victim)` @@ -6299,7 +6454,8 @@ Checks if the necessary conditions are met for one player to successfully attack ## [should_push_or_pull_door](#should_push_or_pull_door) ### Description -Determines whether Mario should push or pull a door when he interacts with it, based on his orientation and position. Useful for animating door interactions realistically, depending on which side Mario approaches from +Determines whether Mario should push or pull a door when he interacts with it, based on his orientation and position. +Useful for animating door interactions realistically, depending on which side Mario approaches from ### Lua Example `local integerValue = should_push_or_pull_door(m, o)` @@ -6323,7 +6479,9 @@ Determines whether Mario should push or pull a door when he interacts with it, b ## [take_damage_and_knock_back](#take_damage_and_knock_back) ### Description -Handles the logic of Mario taking damage and being knocked back by a damaging object. Decreases Mario's health, sets his knockback state, and triggers appropriate sound and camera effects. Useful for implementing enemy attacks, hazards, and ensuring Mario receives proper feedback upon taking damage +Handles the logic of Mario taking damage and being knocked back by a damaging object. +Decreases Mario's health, sets his knockback state, and triggers appropriate sound and camera effects. +Useful for implementing enemy attacks, hazards, and ensuring Mario receives proper feedback upon taking damage ### Lua Example `local integerValue = take_damage_and_knock_back(m, o)` @@ -6347,7 +6505,8 @@ Handles the logic of Mario taking damage and being knocked back by a damaging ob ## [get_mario_cap_flag](#get_mario_cap_flag) ### Description -Determines the type of cap an object represents. Depending on the object's behavior, it returns a cap type (normal, metal, wing, vanish). Useful for handling the logic of picking up, wearing, or losing different kinds of caps +Determines the type of cap an object represents. Depending on the object's behavior, it returns a cap type (normal, metal, wing, vanish). +Useful for handling the logic of picking up, wearing, or losing different kinds of caps ### Lua Example `local integerValue = get_mario_cap_flag(capObject)` @@ -6370,7 +6529,9 @@ Determines the type of cap an object represents. Depending on the object's behav ## [determine_interaction](#determine_interaction) ### Description -Determines how Mario interacts with a given object based on his current action, position, and other state variables. Calculates the appropriate interaction type (e.g., punch, kick, ground pound) that should result from Mario's contact with the specified object (`o`). Useful for handling different types of player-object collisions, attacks, and object behaviors +Determines how Mario interacts with a given object based on his current action, position, and other state variables. +Calculates the appropriate interaction type (e.g., punch, kick, ground pound) that should result from Mario's contact with the specified object (`o`). +Useful for handling different types of player-object collisions, attacks, and object behaviors ### Lua Example `local integerValue = determine_interaction(m, o)` @@ -6492,7 +6653,8 @@ Gets the local Mario's state index ## [get_level_name_ascii](#get_level_name_ascii) ### Description -Returns the name of the level corresponding to `courseNum`, `levelNum` and `areaIndex` as an ASCII (human readable) string. Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string +Returns the name of the level corresponding to `courseNum`, `levelNum` and `areaIndex` as an ASCII (human readable) string. +Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string ### Lua Example `local stringValue = get_level_name_ascii(courseNum, levelNum, areaIndex, charCase)` @@ -6518,7 +6680,9 @@ Returns the name of the level corresponding to `courseNum`, `levelNum` and `area ## [get_level_name_sm64](#get_level_name_sm64) ### Description -Returns the name of the level corresponding to `courseNum`, `levelNum` and `areaIndex` as an SM64 encoded string. This function should not be used in Lua mods. Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string +Returns the name of the level corresponding to `courseNum`, `levelNum` and `areaIndex` as an SM64 encoded string. +This function should not be used in Lua mods. +Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string ### Lua Example `local pointerValue = get_level_name_sm64(courseNum, levelNum, areaIndex, charCase)` @@ -6569,7 +6733,8 @@ Returns the name of the level corresponding to `courseNum`, `levelNum` and `area ## [get_star_name_ascii](#get_star_name_ascii) ### Description -Returns the name of the star corresponding to `courseNum` and `starNum` as an ASCII (human readable) string. Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string +Returns the name of the star corresponding to `courseNum` and `starNum` as an ASCII (human readable) string. +Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string ### Lua Example `local stringValue = get_star_name_ascii(courseNum, starNum, charCase)` @@ -6594,7 +6759,9 @@ Returns the name of the star corresponding to `courseNum` and `starNum` as an AS ## [get_star_name_sm64](#get_star_name_sm64) ### Description -Returns the name of the star corresponding to `courseNum` and `starNum` as an SM64 encoded string. This function should not be used in Lua mods. Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string +Returns the name of the star corresponding to `courseNum` and `starNum` as an SM64 encoded string. +This function should not be used in Lua mods. +Set `charCase` to 1 to capitalize or -1 to decapitalize the returned string ### Lua Example `local pointerValue = get_star_name_sm64(courseNum, starNum, charCase)` @@ -6649,7 +6816,9 @@ Returns the name of the star corresponding to `courseNum` and `starNum` as a dec ## [area_create_warp_node](#area_create_warp_node) ### Description -Creates a warp node in the current level and area with id `id` that goes to the warp node `destNode` in level `destLevel` and area `destArea`, and attach it to the object `o`. To work properly, object `o` must be able to trigger a warp (for example, with interact type set to `INTERACT_WARP`.) `checkpoint` should be set only to WARP_NO_CHECKPOINT (0x00) or WARP_CHECKPOINT (0x80.) If `checkpoint` is set to `0x80`, Mario will warp directly to this node if he enters the level again (after a death for example) +Creates a warp node in the current level and area with id `id` that goes to the warp node `destNode` in level `destLevel` and area `destArea`, and attach it to the object `o`. +To work properly, object `o` must be able to trigger a warp (for example, with interact type set to `INTERACT_WARP`.) +`checkpoint` should be set only to WARP_NO_CHECKPOINT (0x00) or WARP_CHECKPOINT (0x80.) If `checkpoint` is set to `0x80`, Mario will warp directly to this node if he enters the level again (after a death for example) ### Lua Example `local objectWarpNodeValue = area_create_warp_node(id, destLevel, destArea, destNode, checkpoint, o)` diff --git a/docs/lua/functions-4.md b/docs/lua/functions-4.md index 79aa91bb8..a33c0bcaa 100644 --- a/docs/lua/functions-4.md +++ b/docs/lua/functions-4.md @@ -644,7 +644,8 @@ Overrides the soundbank, set to -1 to reset ## [is_anim_at_end](#is_anim_at_end) ### Description -Checks if Mario's current animation has reached its final frame (i.e., the last valid frame in the animation). Useful for deciding when to transition out of an animation-driven action +Checks if Mario's current animation has reached its final frame (i.e., the last valid frame in the animation). +Useful for deciding when to transition out of an animation-driven action ### Lua Example `local integerValue = is_anim_at_end(m)` @@ -667,7 +668,8 @@ Checks if Mario's current animation has reached its final frame (i.e., the last ## [is_anim_past_end](#is_anim_past_end) ### Description -Checks if Mario's current animation has passed the second-to-last valid frame (i.e., effectively at or beyond its final frames). Useful for advanced checks where slightly early transitions or timing are needed before the final frame +Checks if Mario's current animation has passed the second-to-last valid frame (i.e., effectively at or beyond its final frames). +Useful for advanced checks where slightly early transitions or timing are needed before the final frame ### Lua Example `local integerValue = is_anim_past_end(m)` @@ -714,7 +716,8 @@ Sets Mario's current animation to `targetAnimID` at a default acceleration (no s ## [set_mario_anim_with_accel](#set_mario_anim_with_accel) ### Description -Sets Mario's current animation to `targetAnimID` with a custom `accel` value to speed up or slow down the animation. Useful for controlling animation timing, e.g., slow-motion or fast-forward effects +Sets Mario's current animation to `targetAnimID` with a custom `accel` value to speed up or slow down the animation. +Useful for controlling animation timing, e.g., slow-motion or fast-forward effects ### Lua Example `local integerValue = set_mario_anim_with_accel(m, targetAnimID, accel)` @@ -763,7 +766,8 @@ Sets the character-specific animation at its default rate (no acceleration) ## [set_character_anim_with_accel](#set_character_anim_with_accel) ### Description -Sets a character-specific animation where the animation speed is adjusted by `accel`. Useful for varying animation speeds based on context or dynamic conditions (e.g., slow-motion) +Sets a character-specific animation where the animation speed is adjusted by `accel`. +Useful for varying animation speeds based on context or dynamic conditions (e.g., slow-motion) ### Lua Example `local integerValue = set_character_anim_with_accel(m, targetAnimID, accel)` @@ -812,7 +816,8 @@ Sets the current animation frame to a specific `animFrame` ## [is_anim_past_frame](#is_anim_past_frame) ### Description -Checks if Mario's current animation is past a specified `animFrame`. Useful for conditional logic where an action can branch after reaching a specific point in the animation +Checks if Mario's current animation is past a specified `animFrame`. +Useful for conditional logic where an action can branch after reaching a specific point in the animation ### Lua Example `local integerValue = is_anim_past_frame(m, animFrame)` @@ -836,7 +841,8 @@ Checks if Mario's current animation is past a specified `animFrame`. Useful for ## [find_mario_anim_flags_and_translation](#find_mario_anim_flags_and_translation) ### Description -Retrieves the current animation flags and calculates the translation for Mario's animation, rotating it into the global coordinate system based on `yaw`. Useful for determining positional offsets from animations (e.g., stepping forward in a walk animation) and applying them to Mario's position +Retrieves the current animation flags and calculates the translation for Mario's animation, rotating it into the global coordinate system based on `yaw`. +Useful for determining positional offsets from animations (e.g., stepping forward in a walk animation) and applying them to Mario's position ### Lua Example `local integerValue = find_mario_anim_flags_and_translation(o, yaw, translation)` @@ -884,7 +890,8 @@ Applies the translation from Mario's current animation to his world position. Co ## [return_mario_anim_y_translation](#return_mario_anim_y_translation) ### Description -Determines the vertical translation from Mario's animation (how much the animation moves Mario up or down). Returns the y-component of the animation's translation. Useful for adjusting Mario's vertical position based on an ongoing animation (e.g., a bounce or jump) +Determines the vertical translation from Mario's animation (how much the animation moves Mario up or down). Returns the y-component of the animation's translation. +Useful for adjusting Mario's vertical position based on an ongoing animation (e.g., a bounce or jump) ### Lua Example `local integerValue = return_mario_anim_y_translation(m)` @@ -955,7 +962,8 @@ Plays Mario's jump sound if it hasn't been played yet since the last action chan ## [adjust_sound_for_speed](#adjust_sound_for_speed) ### Description -Adjusts the pitch/volume of Mario's movement-based sounds according to his forward velocity (`m.forwardVel`). Useful for adding dynamic audio feedback based on Mario's running or walking speed +Adjusts the pitch/volume of Mario's movement-based sounds according to his forward velocity (`m.forwardVel`). +Useful for adding dynamic audio feedback based on Mario's running or walking speed ### Lua Example `adjust_sound_for_speed(m)` @@ -1076,7 +1084,8 @@ A variant of `play_mario_landing_sound` that ensures the sound is only played on ## [play_mario_heavy_landing_sound](#play_mario_heavy_landing_sound) ### Description -Plays a heavier, more forceful landing sound, possibly for ground pounds or large impacts. Takes into account whether Mario has a metal cap equipped. Useful for making big impact landings stand out aurally +Plays a heavier, more forceful landing sound, possibly for ground pounds or large impacts. Takes into account whether Mario has a metal cap equipped. +Useful for making big impact landings stand out aurally ### Lua Example `play_mario_heavy_landing_sound(m, soundBits)` @@ -1100,7 +1109,8 @@ Plays a heavier, more forceful landing sound, possibly for ground pounds or larg ## [play_mario_heavy_landing_sound_once](#play_mario_heavy_landing_sound_once) ### Description -A variant of `play_mario_heavy_landing_sound` that ensures the sound is only played once per action (using `play_mario_action_sound` internally). Useful for consistent heavy landing effects without repetition +A variant of `play_mario_heavy_landing_sound` that ensures the sound is only played once per action (using `play_mario_action_sound` internally). +Useful for consistent heavy landing effects without repetition ### Lua Example `play_mario_heavy_landing_sound_once(m, soundBits)` @@ -1241,7 +1251,8 @@ Transitions Mario into a bubbled state (if available in multiplayer), decrementi ## [mario_set_forward_vel](#mario_set_forward_vel) ### Description -Sets Mario's forward velocity (`m.forwardVel`) and updates `slideVelX/Z` and `m.vel` accordingly, based on `m.faceAngle.y`. Useful for controlling Mario's speed and direction in various actions (jumping, walking, sliding, etc.) +Sets Mario's forward velocity (`m.forwardVel`) and updates `slideVelX/Z` and `m.vel` accordingly, based on `m.faceAngle.y`. +Useful for controlling Mario's speed and direction in various actions (jumping, walking, sliding, etc.) ### Lua Example `mario_set_forward_vel(m, speed)` @@ -1265,7 +1276,8 @@ Sets Mario's forward velocity (`m.forwardVel`) and updates `slideVelX/Z` and `m. ## [mario_get_floor_class](#mario_get_floor_class) ### Description -Retrieves the slipperiness class of Mario's current floor, ranging from not slippery to very slippery. Considers terrain types and special surfaces. Useful for controlling friction, movement speed adjustments, and whether Mario slips or walks +Retrieves the slipperiness class of Mario's current floor, ranging from not slippery to very slippery. Considers terrain types and special surfaces. +Useful for controlling friction, movement speed adjustments, and whether Mario slips or walks ### Lua Example `local integerValue = mario_get_floor_class(m)` @@ -1288,7 +1300,8 @@ Retrieves the slipperiness class of Mario's current floor, ranging from not slip ## [mario_get_terrain_sound_addend](#mario_get_terrain_sound_addend) ### Description -Computes a value added to terrain sounds, depending on the floor's type (sand, snow, water, etc.) and slipperiness. This returns a sound 'addend' used with sound effects. Useful for playing context-specific footstep or movement sounds +Computes a value added to terrain sounds, depending on the floor's type (sand, snow, water, etc.) and slipperiness. This returns a sound 'addend' used with sound effects. +Useful for playing context-specific footstep or movement sounds ### Lua Example `local integerValue = mario_get_terrain_sound_addend(m)` @@ -1311,7 +1324,8 @@ Computes a value added to terrain sounds, depending on the floor's type (sand, s ## [resolve_and_return_wall_collisions](#resolve_and_return_wall_collisions) ### Description -Checks for and resolves wall collisions at a given position `pos`, returning the last wall encountered. Primarily used to prevent Mario from going through walls. Useful for collision detection when updating Mario's movement or adjusting his position +Checks for and resolves wall collisions at a given position `pos`, returning the last wall encountered. Primarily used to prevent Mario from going through walls. +Useful for collision detection when updating Mario's movement or adjusting his position ### Lua Example `local surfaceValue = resolve_and_return_wall_collisions(pos, offset, radius)` @@ -1362,7 +1376,8 @@ Similar to `resolve_and_return_wall_collisions` but also returns detailed collis ## [vec3f_find_ceil](#vec3f_find_ceil) ### Description -Finds the ceiling from a vec3f horizontally and a height (with 80 vertical buffer). Returns the ceiling height and surface +Finds the ceiling from a vec3f horizontally and a height (with 80 vertical buffer). +Returns the ceiling height and surface ### Lua Example `local numberValue, ceil = vec3f_find_ceil(pos, height)` @@ -1387,7 +1402,9 @@ Finds the ceiling from a vec3f horizontally and a height (with 80 vertical buffe ## [vec3f_mario_ceil](#vec3f_mario_ceil) ### Description -Finds the ceiling from a vec3f horizontally and a height (with 80 vertical buffer). Prevents exposed ceiling bug. Returns the ceiling height and surface +Finds the ceiling from a vec3f horizontally and a height (with 80 vertical buffer). +Prevents exposed ceiling bug. +Returns the ceiling height and surface ### Lua Example `local numberValue, ceil = vec3f_mario_ceil(pos, height)` @@ -1412,7 +1429,8 @@ Finds the ceiling from a vec3f horizontally and a height (with 80 vertical buffe ## [mario_facing_downhill](#mario_facing_downhill) ### Description -Determines if Mario is facing downhill relative to his floor angle, optionally accounting for forward velocity direction. Returns true if he is oriented down the slope. Useful for deciding if Mario will walk or slide on sloped floors +Determines if Mario is facing downhill relative to his floor angle, optionally accounting for forward velocity direction. Returns true if he is oriented down the slope. +Useful for deciding if Mario will walk or slide on sloped floors ### Lua Example `local integerValue = mario_facing_downhill(m, turnYaw)` @@ -1436,7 +1454,8 @@ Determines if Mario is facing downhill relative to his floor angle, optionally a ## [mario_floor_is_slippery](#mario_floor_is_slippery) ### Description -Checks whether Mario's current floor is slippery based on both the floor's surface class and Mario's environment (e.g., special slides). Useful for deciding if Mario should transition to sliding or maintain normal traction +Checks whether Mario's current floor is slippery based on both the floor's surface class and Mario's environment (e.g., special slides). +Useful for deciding if Mario should transition to sliding or maintain normal traction ### Lua Example `local integerValue = mario_floor_is_slippery(m)` @@ -1482,7 +1501,8 @@ Checks whether Mario's floor is a slope, i.e., not flat but not necessarily stee ## [mario_floor_is_steep](#mario_floor_is_steep) ### Description -Checks whether Mario's floor is steep enough to cause special behavior, such as forcing slides or preventing certain actions. Returns true if the slope is too steep. Useful for restricting normal movement on surfaces with extreme angles +Checks whether Mario's floor is steep enough to cause special behavior, such as forcing slides or preventing certain actions. Returns true if the slope is too steep. +Useful for restricting normal movement on surfaces with extreme angles ### Lua Example `local integerValue = mario_floor_is_steep(m)` @@ -1505,7 +1525,8 @@ Checks whether Mario's floor is steep enough to cause special behavior, such as ## [find_floor_height_relative_polar](#find_floor_height_relative_polar) ### Description -Finds the floor height relative to Mario's current position given a polar displacement (`angleFromMario`, `distFromMario`). Useful for determining height differentials ahead or behind Mario, e.g. for slope checks or collision logic +Finds the floor height relative to Mario's current position given a polar displacement (`angleFromMario`, `distFromMario`). +Useful for determining height differentials ahead or behind Mario, e.g. for slope checks or collision logic ### Lua Example `local numberValue = find_floor_height_relative_polar(m, angleFromMario, distFromMario)` @@ -1530,7 +1551,8 @@ Finds the floor height relative to Mario's current position given a polar displa ## [find_floor_slope](#find_floor_slope) ### Description -Returns a slope angle based on comparing the floor heights slightly in front and behind Mario. It essentially calculates how steep the ground is in a specific yaw direction. Useful for slope-based calculations such as setting walking or sliding behaviors +Returns a slope angle based on comparing the floor heights slightly in front and behind Mario. It essentially calculates how steep the ground is in a specific yaw direction. +Useful for slope-based calculations such as setting walking or sliding behaviors ### Lua Example `local integerValue = find_floor_slope(m, yawOffset)` @@ -1554,7 +1576,8 @@ Returns a slope angle based on comparing the floor heights slightly in front and ## [update_mario_sound_and_camera](#update_mario_sound_and_camera) ### Description -Updates the background noise and camera modes based on Mario's action. Especially relevant for actions like first-person view or sleeping. Useful for synchronizing camera behavior and ambient sounds with Mario's state changes +Updates the background noise and camera modes based on Mario's action. Especially relevant for actions like first-person view or sleeping. +Useful for synchronizing camera behavior and ambient sounds with Mario's state changes ### Lua Example `update_mario_sound_and_camera(m)` @@ -1577,7 +1600,8 @@ Updates the background noise and camera modes based on Mario's action. Especiall ## [set_steep_jump_action](#set_steep_jump_action) ### Description -Transitions Mario into ACT_STEEP_JUMP if the floor is too steep, adjusting his forward velocity and orientation accordingly. Useful for forcing special jump states on surfaces exceeding normal slope limits +Transitions Mario into ACT_STEEP_JUMP if the floor is too steep, adjusting his forward velocity and orientation accordingly. +Useful for forcing special jump states on surfaces exceeding normal slope limits ### Lua Example `set_steep_jump_action(m)` @@ -1749,7 +1773,8 @@ Increments Mario's `hurtCounter` and immediately sets a new action. Often used w ## [check_common_action_exits](#check_common_action_exits) ### Description -Checks for inputs that cause common action transitions (jump, freefall, walking, sliding). Useful for quickly exiting certain stationary actions when Mario begins moving or leaves the floor +Checks for inputs that cause common action transitions (jump, freefall, walking, sliding). +Useful for quickly exiting certain stationary actions when Mario begins moving or leaves the floor ### Lua Example `local integerValue = check_common_action_exits(m)` @@ -1795,7 +1820,8 @@ Checks for inputs that cause common hold-action transitions (hold jump, hold fre ## [transition_submerged_to_walking](#transition_submerged_to_walking) ### Description -Transitions Mario from being underwater to a walking state. Resets camera to the default mode and can handle object-holding states. Useful for restoring standard ground movement when emerging from water +Transitions Mario from being underwater to a walking state. Resets camera to the default mode and can handle object-holding states. +Useful for restoring standard ground movement when emerging from water ### Lua Example `local integerValue = transition_submerged_to_walking(m)` @@ -1864,7 +1890,8 @@ Main driver for Mario's behavior. Executes the current action group (stationary, ## [force_idle_state](#force_idle_state) ### Description -Forces Mario into an idle state, either `ACT_IDLE` or `ACT_WATER_IDLE` depending on whether he is submerged. Useful for quickly resetting Mario's state to an idle pose under special conditions (e.g., cutscene triggers) +Forces Mario into an idle state, either `ACT_IDLE` or `ACT_WATER_IDLE` depending on whether he is submerged. +Useful for quickly resetting Mario's state to an idle pose under special conditions (e.g., cutscene triggers) ### Lua Example `local integerValue = force_idle_state(m)` @@ -1988,7 +2015,8 @@ Gets the MarioState corresponding to the provided object if the object is a Mari ## [play_flip_sounds](#play_flip_sounds) ### Description -Plays a spinning sound at specific animation frames for flips (usually side flips or certain jump flips). If the current animation frame matches any of the specified frames, it triggers `SOUND_ACTION_SPIN` +Plays a spinning sound at specific animation frames for flips (usually side flips or certain jump flips). +If the current animation frame matches any of the specified frames, it triggers `SOUND_ACTION_SPIN` ### Lua Example `play_flip_sounds(m, frame1, frame2, frame3)` @@ -2014,7 +2042,8 @@ Plays a spinning sound at specific animation frames for flips (usually side flip ## [play_far_fall_sound](#play_far_fall_sound) ### Description -Plays a unique sound when Mario has fallen a significant distance without being invulnerable, twirling, or flying. If the fall exceeds a threshold, triggers a "long fall" exclamation. Also sets a flag to prevent repeated triggering +Plays a unique sound when Mario has fallen a significant distance without being invulnerable, twirling, or flying. +If the fall exceeds a threshold, triggers a "long fall" exclamation. Also sets a flag to prevent repeated triggering ### Lua Example `play_far_fall_sound(m)` @@ -2037,7 +2066,8 @@ Plays a unique sound when Mario has fallen a significant distance without being ## [play_knockback_sound](#play_knockback_sound) ### Description -Plays a knockback sound effect if Mario is hit or knocked back with significant velocity. The specific sound differs depending on whether Mario's forward velocity is high enough to be considered a strong knockback +Plays a knockback sound effect if Mario is hit or knocked back with significant velocity. The specific sound differs +depending on whether Mario's forward velocity is high enough to be considered a strong knockback ### Lua Example `play_knockback_sound(m)` @@ -2060,7 +2090,9 @@ Plays a knockback sound effect if Mario is hit or knocked back with significant ## [lava_boost_on_wall](#lava_boost_on_wall) ### Description -Allows Mario to 'lava boost' off a lava wall, reorienting him to face away from the wall and adjusting forward velocity. Increases Mario's hurt counter if he's not metal, plays a burning sound, and transitions his action to `ACT_LAVA_BOOST`. Useful for handling collisions with lava walls, giving Mario a strong upward/forward boost at the cost of health +Allows Mario to 'lava boost' off a lava wall, reorienting him to face away from the wall and adjusting forward velocity. +Increases Mario's hurt counter if he's not metal, plays a burning sound, and transitions his action to `ACT_LAVA_BOOST`. +Useful for handling collisions with lava walls, giving Mario a strong upward/forward boost at the cost of health ### Lua Example `local integerValue = lava_boost_on_wall(m)` @@ -2083,7 +2115,10 @@ Allows Mario to 'lava boost' off a lava wall, reorienting him to face away from ## [check_fall_damage](#check_fall_damage) ### Description -Evaluates whether Mario should take fall damage based on the height difference between his peak and current position. If the fall is large enough and does not occur over burning surfaces or while twirling, Mario may get hurt or enter a hard fall action. If the fall is significant but not extreme, minimal damage and a squish effect may be applied. Useful for determining if Mario's fall warrants a health penalty or a special landing action +Evaluates whether Mario should take fall damage based on the height difference between his peak and current position. +If the fall is large enough and does not occur over burning surfaces or while twirling, Mario may get hurt or enter +a hard fall action. If the fall is significant but not extreme, minimal damage and a squish effect may be applied. +Useful for determining if Mario's fall warrants a health penalty or a special landing action ### Lua Example `local integerValue = check_fall_damage(m, hardFallAction)` @@ -2107,7 +2142,8 @@ Evaluates whether Mario should take fall damage based on the height difference b ## [check_kick_or_dive_in_air](#check_kick_or_dive_in_air) ### Description -Checks if Mario should perform a kick or a dive while in mid-air, depending on his current forward velocity. Pressing the B button in the air can trigger a jump kick (at lower speeds) or a dive (at higher speeds) +Checks if Mario should perform a kick or a dive while in mid-air, depending on his current forward velocity. +Pressing the B button in the air can trigger a jump kick (at lower speeds) or a dive (at higher speeds) ### Lua Example `local integerValue = check_kick_or_dive_in_air(m)` @@ -2130,7 +2166,9 @@ Checks if Mario should perform a kick or a dive while in mid-air, depending on h ## [should_get_stuck_in_ground](#should_get_stuck_in_ground) ### Description -Determines whether Mario should become stuck in the ground after landing, specifically for soft terrain such as snow or sand, provided certain conditions are met (height of the fall, normal of the floor, etc.). Returns true if Mario should be stuck, false otherwise +Determines whether Mario should become stuck in the ground after landing, specifically for soft terrain such as snow +or sand, provided certain conditions are met (height of the fall, normal of the floor, etc.). +Returns true if Mario should be stuck, false otherwise ### Lua Example `local integerValue = should_get_stuck_in_ground(m)` @@ -2153,7 +2191,9 @@ Determines whether Mario should become stuck in the ground after landing, specif ## [check_fall_damage_or_get_stuck](#check_fall_damage_or_get_stuck) ### Description -Checks if Mario should get stuck in the ground after a large fall onto soft terrain (like snow or sand) or if he should just proceed with regular fall damage calculations. If the terrain and height conditions are met, Mario's action changes to being stuck in the ground. Otherwise, normal fall damage logic applies +Checks if Mario should get stuck in the ground after a large fall onto soft terrain (like snow or sand) or if he +should just proceed with regular fall damage calculations. If the terrain and height conditions are met, Mario's +action changes to being stuck in the ground. Otherwise, normal fall damage logic applies ### Lua Example `local integerValue = check_fall_damage_or_get_stuck(m, hardFallAction)` @@ -2177,7 +2217,8 @@ Checks if Mario should get stuck in the ground after a large fall onto soft terr ## [check_horizontal_wind](#check_horizontal_wind) ### Description -Checks for the presence of a horizontal wind surface under Mario. If found, applies a push force to Mario's horizontal velocity. Caps speed at certain thresholds, updates Mario's forward velocity and yaw for sliding/wind movement +Checks for the presence of a horizontal wind surface under Mario. If found, applies a push force to Mario's horizontal +velocity. Caps speed at certain thresholds, updates Mario's forward velocity and yaw for sliding/wind movement ### Lua Example `local integerValue = check_horizontal_wind(m)` @@ -2200,7 +2241,8 @@ Checks for the presence of a horizontal wind surface under Mario. If found, appl ## [update_air_with_turn](#update_air_with_turn) ### Description -Updates Mario's air movement while allowing him to turn. Checks horizontal wind and applies a moderate amount of drag, approaches the forward velocity toward zero if no input is pressed, and modifies forward velocity/angle based on stick input +Updates Mario's air movement while allowing him to turn. Checks horizontal wind and applies a moderate amount of drag, +approaches the forward velocity toward zero if no input is pressed, and modifies forward velocity/angle based on stick input ### Lua Example `update_air_with_turn(m)` @@ -2223,7 +2265,8 @@ Updates Mario's air movement while allowing him to turn. Checks horizontal wind ## [update_air_without_turn](#update_air_without_turn) ### Description -Updates Mario's air movement without directly turning his facing angle to match his intended yaw. Instead, Mario can move sideways relative to his current facing direction. Also checks horizontal wind and applies drag +Updates Mario's air movement without directly turning his facing angle to match his intended yaw. Instead, Mario can +move sideways relative to his current facing direction. Also checks horizontal wind and applies drag ### Lua Example `update_air_without_turn(m)` @@ -2246,7 +2289,8 @@ Updates Mario's air movement without directly turning his facing angle to match ## [update_lava_boost_or_twirling](#update_lava_boost_or_twirling) ### Description -Updates Mario's movement when in actions like lava boost or twirling in mid-air. Applies player input to adjust forward velocity and facing angle, but in a more restricted manner compared to standard jump movement. Used by `ACT_LAVA_BOOST` and `ACT_TWIRLING` +Updates Mario's movement when in actions like lava boost or twirling in mid-air. Applies player input to adjust forward velocity +and facing angle, but in a more restricted manner compared to standard jump movement. Used by `ACT_LAVA_BOOST` and `ACT_TWIRLING` ### Lua Example `update_lava_boost_or_twirling(m)` @@ -2269,7 +2313,8 @@ Updates Mario's movement when in actions like lava boost or twirling in mid-air. ## [update_flying_yaw](#update_flying_yaw) ### Description -Calculates and applies a change in Mario's yaw while flying, based on horizontal stick input. Approaches a target yaw velocity and sets Mario's roll angle to simulate banking turns. This results in a more natural, curved flight path +Calculates and applies a change in Mario's yaw while flying, based on horizontal stick input. Approaches a target yaw velocity +and sets Mario's roll angle to simulate banking turns. This results in a more natural, curved flight path ### Lua Example `update_flying_yaw(m)` @@ -2292,7 +2337,8 @@ Calculates and applies a change in Mario's yaw while flying, based on horizontal ## [update_flying_pitch](#update_flying_pitch) ### Description -Calculates and applies a change in Mario's pitch while flying, based on vertical stick input. Approaches a target pitch velocity and clamps the final pitch angle to a certain range, simulating a smooth flight control +Calculates and applies a change in Mario's pitch while flying, based on vertical stick input. Approaches a target pitch velocity +and clamps the final pitch angle to a certain range, simulating a smooth flight control ### Lua Example `update_flying_pitch(m)` @@ -2315,7 +2361,8 @@ Calculates and applies a change in Mario's pitch while flying, based on vertical ## [update_flying](#update_flying) ### Description -Handles the complete flying logic for Mario (usually with the wing cap). Continuously updates pitch and yaw based on controller input, applies drag, and adjusts forward velocity. Also updates Mario's model angles for flight animations +Handles the complete flying logic for Mario (usually with the wing cap). Continuously updates pitch and yaw based on controller input, +applies drag, and adjusts forward velocity. Also updates Mario's model angles for flight animations ### Lua Example `update_flying(m)` @@ -2338,7 +2385,9 @@ Handles the complete flying logic for Mario (usually with the wing cap). Continu ## [common_air_action_step](#common_air_action_step) ### Description -Performs a standard step update for air actions without knockback, typically used for jumps or freefalls. Updates Mario's velocity (and possibly checks horizontal wind), then calls `perform_air_step` with given `stepArg`. Handles how Mario lands, hits walls, grabs ledges, or grabs ceilings. Optionally sets an animation +Performs a standard step update for air actions without knockback, typically used for jumps or freefalls. +Updates Mario's velocity (and possibly checks horizontal wind), then calls `perform_air_step` with given `stepArg`. +Handles how Mario lands, hits walls, grabs ledges, or grabs ceilings. Optionally sets an animation ### Lua Example `local integerValue = common_air_action_step(m, landAction, animation, stepArg)` @@ -2364,7 +2413,8 @@ Performs a standard step update for air actions without knockback, typically use ## [common_air_knockback_step](#common_air_knockback_step) ### Description -A shared step update used for airborne knockback states (both forward and backward). Updates velocity, calls `perform_air_step`, and handles wall collisions or landing transitions to appropriate ground knockback actions. Also sets animation and speed +A shared step update used for airborne knockback states (both forward and backward). Updates velocity, calls `perform_air_step`, +and handles wall collisions or landing transitions to appropriate ground knockback actions. Also sets animation and speed ### Lua Example `local integerValue = common_air_knockback_step(m, landAction, hardFallAction, animation, speed)` @@ -2391,7 +2441,8 @@ A shared step update used for airborne knockback states (both forward and backwa ## [check_wall_kick](#check_wall_kick) ### Description -Checks if Mario should wall kick after performing an air hit against a wall. If the input conditions (e.g., pressing A) and the `wallKickTimer` allow, Mario transitions to `ACT_WALL_KICK_AIR` +Checks if Mario should wall kick after performing an air hit against a wall. If the input conditions (e.g., pressing A) +and the `wallKickTimer` allow, Mario transitions to `ACT_WALL_KICK_AIR` ### Lua Example `local integerValue = check_wall_kick(m)` @@ -2414,7 +2465,9 @@ Checks if Mario should wall kick after performing an air hit against a wall. If ## [check_common_airborne_cancels](#check_common_airborne_cancels) ### Description -Checks for and handles common conditions that would cancel Mario's current air action. This includes transitioning to a water plunge if below the water level, becoming squished if appropriate, or switching to vertical wind action if on certain wind surfaces. Also resets `m.quicksandDepth` +Checks for and handles common conditions that would cancel Mario's current air action. This includes transitioning +to a water plunge if below the water level, becoming squished if appropriate, or switching to vertical wind action +if on certain wind surfaces. Also resets `m.quicksandDepth` ### Lua Example `local integerValue = check_common_airborne_cancels(m)` @@ -2437,7 +2490,8 @@ Checks for and handles common conditions that would cancel Mario's current air a ## [mario_execute_airborne_action](#mario_execute_airborne_action) ### Description -Executes Mario's current airborne action by first checking common airborne cancels, then playing a far-fall sound if needed. Dispatches to the appropriate action function, such as jump, double jump, freefall, etc +Executes Mario's current airborne action by first checking common airborne cancels, then playing a far-fall sound if needed. +Dispatches to the appropriate action function, such as jump, double jump, freefall, etc ### Lua Example `local integerValue = mario_execute_airborne_action(m)` @@ -2466,7 +2520,8 @@ Executes Mario's current airborne action by first checking common airborne cance ## [add_tree_leaf_particles](#add_tree_leaf_particles) ### Description -Spawns leaf particles when Mario climbs a tree, if he is sufficiently high above the floor. In Shifting Sand Land, the leaf effect spawns higher due to the taller palm trees +Spawns leaf particles when Mario climbs a tree, if he is sufficiently high above the floor. +In Shifting Sand Land, the leaf effect spawns higher due to the taller palm trees ### Lua Example `add_tree_leaf_particles(m)` @@ -2513,7 +2568,8 @@ Plays the appropriate climbing sound effect depending on whether Mario is on a t ## [set_pole_position](#set_pole_position) ### Description -Sets Mario's position and alignment while he is on a climbable pole or tree. This function checks collisions with floors and ceilings, and updates Mario's action if he leaves the pole or touches the floor. Useful for ensuring Mario's correct placement and transitions when climbing poles or trees +Sets Mario's position and alignment while he is on a climbable pole or tree. This function checks collisions with floors and ceilings, and updates Mario's action if he leaves the pole or touches the floor. +Useful for ensuring Mario's correct placement and transitions when climbing poles or trees ### Lua Example `local integerValue = set_pole_position(m, offsetY)` @@ -2747,7 +2803,8 @@ Checks if Mario should cancel his current automatic action, primarily by detecti ## [mario_execute_automatic_action](#mario_execute_automatic_action) ### Description -Executes Mario's current automatic action (e.g., climbing a pole, hanging, ledge-grabbing) by calling the corresponding function. It also checks for common cancellations, like falling into water. Returns true if the action was canceled and a new action was set, or false otherwise +Executes Mario's current automatic action (e.g., climbing a pole, hanging, ledge-grabbing) by calling the corresponding function. It also checks for common cancellations, like falling into water. +Returns true if the action was canceled and a new action was set, or false otherwise ### Lua Example `local integerValue = mario_execute_automatic_action(m)` @@ -3138,7 +3195,8 @@ Executes Mario's current cutscene action based on his `action` field. Includes v ## [tilt_body_running](#tilt_body_running) ### Description -Tilts Mario's body according to his running speed and slope angle. Calculates a pitch offset used while running to simulate leaning forward at higher speeds or on slopes +Tilts Mario's body according to his running speed and slope angle. +Calculates a pitch offset used while running to simulate leaning forward at higher speeds or on slopes ### Lua Example `local integerValue = tilt_body_running(m)` @@ -3161,7 +3219,8 @@ Tilts Mario's body according to his running speed and slope angle. Calculates a ## [play_step_sound](#play_step_sound) ### Description -Checks the current animation frame against two specified frames to trigger footstep sounds. Also chooses specific sounds if Mario is wearing Metal Cap or is in quicksand +Checks the current animation frame against two specified frames to trigger footstep sounds. +Also chooses specific sounds if Mario is wearing Metal Cap or is in quicksand ### Lua Example `play_step_sound(m, frame1, frame2)` @@ -3235,7 +3294,8 @@ Sets Mario's facing yaw to his intended yaw, applies a specified forward velocit ## [check_ledge_climb_down](#check_ledge_climb_down) ### Description -Checks if Mario is near an edge while moving slowly and the floor below that edge is significantly lower. If the conditions are met, transitions Mario into a ledge-climb-down action and positions him accordingly on the edge +Checks if Mario is near an edge while moving slowly and the floor below that edge is significantly lower. +If the conditions are met, transitions Mario into a ledge-climb-down action and positions him accordingly on the edge ### Lua Example `check_ledge_climb_down(m)` @@ -3308,7 +3368,9 @@ Determines the proper triple jump action based on Mario's forward velocity and t ## [update_sliding_angle](#update_sliding_angle) ### Description -Adjusts Mario's slide velocity and facing angle when on a slope. Calculates slope direction and steepness, then modifies velocity accordingly (speed up downhill, slow uphill). Handles facing-direction changes and maximum speed limits +Adjusts Mario's slide velocity and facing angle when on a slope. +Calculates slope direction and steepness, then modifies velocity accordingly (speed up downhill, slow uphill). +Handles facing-direction changes and maximum speed limits ### Lua Example `update_sliding_angle(m, accel, lossFactor)` @@ -3333,7 +3395,9 @@ Adjusts Mario's slide velocity and facing angle when on a slope. Calculates slop ## [update_sliding](#update_sliding) ### Description -Updates Mario's sliding state each frame, applying additional friction or acceleration based on the surface's slipperiness. Also checks if speed has slowed below a threshold to end the slide. Returns `true` if sliding has stopped +Updates Mario's sliding state each frame, applying additional friction or acceleration based on the surface's slipperiness. +Also checks if speed has slowed below a threshold to end the slide. +Returns `true` if sliding has stopped ### Lua Example `local integerValue = update_sliding(m, stopSpeed)` @@ -3357,7 +3421,8 @@ Updates Mario's sliding state each frame, applying additional friction or accele ## [apply_slope_accel](#apply_slope_accel) ### Description -Applies acceleration or deceleration based on the slope of the floor. On downward slopes, Mario gains speed, while on upward slopes, Mario loses speed +Applies acceleration or deceleration based on the slope of the floor. +On downward slopes, Mario gains speed, while on upward slopes, Mario loses speed ### Lua Example `apply_slope_accel(m)` @@ -3380,7 +3445,8 @@ Applies acceleration or deceleration based on the slope of the floor. On downwar ## [apply_landing_accel](#apply_landing_accel) ### Description -Applies friction-like deceleration if the floor is flat, or slope-based acceleration if the floor is sloped. Capped in such a way that Mario eventually stops or stabilizes on flatter ground +Applies friction-like deceleration if the floor is flat, or slope-based acceleration if the floor is sloped. +Capped in such a way that Mario eventually stops or stabilizes on flatter ground ### Lua Example `local integerValue = apply_landing_accel(m, frictionFactor)` @@ -3427,7 +3493,8 @@ Controls Mario's speed when riding a Koopa Shell on the ground. ## [apply_slope_decel](#apply_slope_decel) ### Description -Approaches Mario's forward velocity toward zero at a rate dependent on the floor's slipperiness. This function can completely stop Mario if the slope is gentle enough or if friction is high +Approaches Mario's forward velocity toward zero at a rate dependent on the floor's slipperiness. +This function can completely stop Mario if the slope is gentle enough or if friction is high ### Lua Example `local integerValue = apply_slope_decel(m, decelCoef)` @@ -3451,7 +3518,8 @@ Approaches Mario's forward velocity toward zero at a rate dependent on the floor ## [update_decelerating_speed](#update_decelerating_speed) ### Description -Gradually reduces Mario's forward speed to zero over time on level ground, unless otherwise influenced by slope or friction. Returns true if Mario's speed reaches zero, meaning he has stopped +Gradually reduces Mario's forward speed to zero over time on level ground, unless otherwise influenced by slope or friction. +Returns true if Mario's speed reaches zero, meaning he has stopped ### Lua Example `local integerValue = update_decelerating_speed(m)` @@ -3474,7 +3542,8 @@ Gradually reduces Mario's forward speed to zero over time on level ground, unles ## [update_walking_speed](#update_walking_speed) ### Description -Updates Mario's walking speed based on player input and floor conditions (e.g., a slow floor or quicksand). Caps speed at a certain value and may reduce it slightly on steep slopes +Updates Mario's walking speed based on player input and floor conditions (e.g., a slow floor or quicksand). +Caps speed at a certain value and may reduce it slightly on steep slopes ### Lua Example `update_walking_speed(m)` @@ -3497,7 +3566,8 @@ Updates Mario's walking speed based on player input and floor conditions (e.g., ## [should_begin_sliding](#should_begin_sliding) ### Description -Checks if Mario should begin sliding, based on player input (facing downhill, pressing the analog stick backward, or on a slide terrain), and current floor steepness. Returns true if conditions to slide are met. +Checks if Mario should begin sliding, based on player input (facing downhill, pressing the analog stick backward, or on a slide terrain), and current floor steepness. +Returns true if conditions to slide are met. ### Lua Example `local integerValue = should_begin_sliding(m)` @@ -3520,7 +3590,8 @@ Checks if Mario should begin sliding, based on player input (facing downhill, pr ## [analog_stick_held_back](#analog_stick_held_back) ### Description -Checks if the analog stick is held significantly behind Mario's current facing angle. Returns true if the stick is far enough in the opposite direction, indicating Mario wants to move backward +Checks if the analog stick is held significantly behind Mario's current facing angle. +Returns true if the stick is far enough in the opposite direction, indicating Mario wants to move backward ### Lua Example `local integerValue = analog_stick_held_back(m)` @@ -3543,7 +3614,8 @@ Checks if the analog stick is held significantly behind Mario's current facing a ## [check_ground_dive_or_punch](#check_ground_dive_or_punch) ### Description -Checks if the B button was pressed to either initiate a dive (if moving fast enough) or a punch (if moving slowly). Returns `true` if the action was changed to either a dive or a punching attack +Checks if the B button was pressed to either initiate a dive (if moving fast enough) or a punch (if moving slowly). +Returns `true` if the action was changed to either a dive or a punching attack ### Lua Example `local integerValue = check_ground_dive_or_punch(m)` @@ -3566,7 +3638,8 @@ Checks if the B button was pressed to either initiate a dive (if moving fast eno ## [begin_braking_action](#begin_braking_action) ### Description -Begins a braking action if Mario's forward velocity is high enough or transitions to a decelerating action otherwise. Also handles the scenario where Mario is up against a wall, transitioning to a standing state +Begins a braking action if Mario's forward velocity is high enough or transitions to a decelerating action otherwise. +Also handles the scenario where Mario is up against a wall, transitioning to a standing state ### Lua Example `local integerValue = begin_braking_action(m)` @@ -3589,7 +3662,8 @@ Begins a braking action if Mario's forward velocity is high enough or transition ## [anim_and_audio_for_walk](#anim_and_audio_for_walk) ### Description -Handles the animation and audio (footstep sounds) for normal walking or running. The specific animation used (tiptoe, walk, or run) depends on Mario's current speed +Handles the animation and audio (footstep sounds) for normal walking or running. +The specific animation used (tiptoe, walk, or run) depends on Mario's current speed ### Lua Example `anim_and_audio_for_walk(m)` @@ -3612,7 +3686,8 @@ Handles the animation and audio (footstep sounds) for normal walking or running. ## [anim_and_audio_for_hold_walk](#anim_and_audio_for_hold_walk) ### Description -Plays the appropriate animation and footstep sounds for walking while carrying a lighter object (like a small box). Adjusts the animation speed dynamically based on Mario's velocity +Plays the appropriate animation and footstep sounds for walking while carrying a lighter object (like a small box). +Adjusts the animation speed dynamically based on Mario's velocity ### Lua Example `anim_and_audio_for_hold_walk(m)` @@ -3635,7 +3710,8 @@ Plays the appropriate animation and footstep sounds for walking while carrying a ## [anim_and_audio_for_heavy_walk](#anim_and_audio_for_heavy_walk) ### Description -Plays the appropriate animation and footstep sounds for walking while carrying a heavy object. Sets the character animation speed based on Mario's intended movement speed +Plays the appropriate animation and footstep sounds for walking while carrying a heavy object. +Sets the character animation speed based on Mario's intended movement speed ### Lua Example `anim_and_audio_for_heavy_walk(m)` @@ -3682,7 +3758,8 @@ When Mario hits a wall during movement, decides whether he's pushing against the ## [tilt_body_walking](#tilt_body_walking) ### Description -Applies a left/right tilt to Mario's torso (and some pitch if running fast) while walking or running. The tilt is based on his change in yaw and current speed, giving a leaning appearance when turning +Applies a left/right tilt to Mario's torso (and some pitch if running fast) while walking or running. +The tilt is based on his change in yaw and current speed, giving a leaning appearance when turning ### Lua Example `tilt_body_walking(m, startYaw)` @@ -3706,7 +3783,8 @@ Applies a left/right tilt to Mario's torso (and some pitch if running fast) whil ## [tilt_body_ground_shell](#tilt_body_ground_shell) ### Description -Tilts Mario's torso and head while riding a shell on the ground to reflect turning. Similar to other tilt functions but tuned for shell-riding speeds and angles +Tilts Mario's torso and head while riding a shell on the ground to reflect turning. +Similar to other tilt functions but tuned for shell-riding speeds and angles ### Lua Example `tilt_body_ground_shell(m, startYaw)` @@ -3730,7 +3808,8 @@ Tilts Mario's torso and head while riding a shell on the ground to reflect turni ## [tilt_body_butt_slide](#tilt_body_butt_slide) ### Description -Tilts Mario's torso while butt sliding based on analog input direction and magnitude. Gives the appearance that Mario is balancing or leaning into a turn +Tilts Mario's torso while butt sliding based on analog input direction and magnitude. +Gives the appearance that Mario is balancing or leaning into a turn ### Lua Example `tilt_body_butt_slide(m)` @@ -3779,7 +3858,8 @@ Applies shared logic for sliding-related actions while playing sliding sounds, m ## [common_slide_action_with_jump](#common_slide_action_with_jump) ### Description -Builds on `common_slide_action` by also allowing Mario to jump out of a slide if A is pressed after a short delay. If the sliding slows enough, Mario transitions to a specified stopping action +Builds on `common_slide_action` by also allowing Mario to jump out of a slide if A is pressed after a short delay. +If the sliding slows enough, Mario transitions to a specified stopping action ### Lua Example `local integerValue = common_slide_action_with_jump(m, stopAction, jumpAction, airAction, animation)` @@ -3806,7 +3886,8 @@ Builds on `common_slide_action` by also allowing Mario to jump out of a slide if ## [stomach_slide_action](#stomach_slide_action) ### Description -Updates Mario's sliding state where he is on his stomach. Similar to other slide actions but has a chance to roll out if A or B is pressed. Uses `common_slide_action` for the core movement logic +Updates Mario's sliding state where he is on his stomach. Similar to other slide actions but has a chance to roll out if A or B is pressed. +Uses `common_slide_action` for the core movement logic ### Lua Example `local integerValue = stomach_slide_action(m, stopAction, airAction, animation)` @@ -3884,7 +3965,8 @@ Applies movement upon landing from a jump or fall. Adjusts velocity based on slo ## [quicksand_jump_land_action](#quicksand_jump_land_action) ### Description -Handles a special landing in quicksand after a jump. Over several frames, Mario emerges from the quicksand. First part of the animation reduces his quicksand depth. Ends with a normal landing action or transitions back to air if he leaves the ground +Handles a special landing in quicksand after a jump. Over several frames, Mario emerges from the quicksand. +First part of the animation reduces his quicksand depth. Ends with a normal landing action or transitions back to air if he leaves the ground ### Lua Example `local integerValue = quicksand_jump_land_action(m, animation1, animation2, endAction, airAction)` @@ -4011,7 +4093,9 @@ Updates Mario's punching state ## [check_common_object_cancels](#check_common_object_cancels) ### Description -Checks for and handles common conditions that would cancel Mario's current object action. This includes transitioning to a water plunge if below the water level, becoming squished if appropriate, or switching to standing death action if Mario is dead +Checks for and handles common conditions that would cancel Mario's current object action. This includes transitioning +to a water plunge if below the water level, becoming squished if appropriate, or switching to standing death action +if Mario is dead ### Lua Example `local integerValue = check_common_object_cancels(m)` @@ -4034,7 +4118,8 @@ Checks for and handles common conditions that would cancel Mario's current objec ## [mario_execute_object_action](#mario_execute_object_action) ### Description -Executes Mario's current object action by first checking common object cancels, then updating quicksand state. Dispatches to the appropriate action function, such as punching, throwing, picking up Bowser, etc +Executes Mario's current object action by first checking common object cancels, then updating quicksand state. +Dispatches to the appropriate action function, such as punching, throwing, picking up Bowser, etc ### Lua Example `local integerValue = mario_execute_object_action(m)` @@ -4253,7 +4338,8 @@ Checks for and handles common conditions that would cancel Mario's current stati ## [mario_execute_stationary_action](#mario_execute_stationary_action) ### Description -Executes Mario's current object action by first checking common stationary cancels, then updating quicksand state. Dispatches to the appropriate action function, such as idle, sleeping, crouching, ect +Executes Mario's current object action by first checking common stationary cancels, then updating quicksand state. +Dispatches to the appropriate action function, such as idle, sleeping, crouching, ect ### Lua Example `local integerValue = mario_execute_stationary_action(m)` @@ -4400,7 +4486,8 @@ Controls the bobbing that happens when you swim near the water surface ## [mario_execute_submerged_action](#mario_execute_submerged_action) ### Description -Executes Mario's current submerged action by first checking common submerged cancels, then setting quicksand depth and head angles to 0. Dispatches to the appropriate action function, such as breaststroke, flutterkick, water punch, ect +Executes Mario's current submerged action by first checking common submerged cancels, then setting quicksand depth and head angles to 0. +Dispatches to the appropriate action function, such as breaststroke, flutterkick, water punch, ect ### Lua Example `local integerValue = mario_execute_submerged_action(m)` @@ -5678,7 +5765,8 @@ Converts an angle from degrees to SM64 format ## [mtxf_zero](#mtxf_zero) ### Description -Sets the 4x4 floating-point matrix `mtx` to all zeros. Unless you really need this-It's reccomended to use mtxf_identity instead. +Sets the 4x4 floating-point matrix `mtx` to all zeros. +Unless you really need this-It's reccomended to use mtxf_identity instead. ### Lua Example `mtxf_zero(mtx)` diff --git a/docs/lua/functions-5.md b/docs/lua/functions-5.md index e8822093a..a2a5a7598 100644 --- a/docs/lua/functions-5.md +++ b/docs/lua/functions-5.md @@ -1952,7 +1952,11 @@ Writes a line to a text modfs `file`. Returns true on success ## [mod_fs_file_seek](#mod_fs_file_seek) ### Description -Sets the current position of a modfs `file`. If `origin` is `FILE_SEEK_SET`, file position is set to `offset`. If `origin` is `FILE_SEEK_CUR`, `offset` is added to file current position. If `origin` is `FILE_SEEK_END`, file position is set to `end of file + offset`. Returns true on success +Sets the current position of a modfs `file`. +If `origin` is `FILE_SEEK_SET`, file position is set to `offset`. +If `origin` is `FILE_SEEK_CUR`, `offset` is added to file current position. +If `origin` is `FILE_SEEK_END`, file position is set to `end of file + offset`. +Returns true on success ### Lua Example `local booleanValue = mod_fs_file_seek(file, offset, origin)` @@ -1977,7 +1981,8 @@ Sets the current position of a modfs `file`. If `origin` is `FILE_SEEK_SET`, fil ## [mod_fs_file_rewind](#mod_fs_file_rewind) ### Description -Sets the current position of a modfs `file` to its beginning. Returns true on success +Sets the current position of a modfs `file` to its beginning. +Returns true on success ### Lua Example `local booleanValue = mod_fs_file_rewind(file)` @@ -3126,7 +3131,8 @@ Generates splashes if at surface of water, entering water, or bubbles if underwa ## [object_step](#object_step) ### Description -Generic object move function. Handles walls, water, floors, and gravity. Returns flags for certain interactions +Generic object move function. Handles walls, water, floors, and gravity. +Returns flags for certain interactions ### Lua Example `local integerValue = object_step()` @@ -3147,7 +3153,8 @@ Generic object move function. Handles walls, water, floors, and gravity. Returns ## [object_step_without_floor_orient](#object_step_without_floor_orient) ### Description -Takes an object step but does not orient with the object's floor. Used for boulders, falling pillars, and the rolling snowman body +Takes an object step but does not orient with the object's floor. +Used for boulders, falling pillars, and the rolling snowman body ### Lua Example `local integerValue = object_step_without_floor_orient()` @@ -3168,7 +3175,8 @@ Takes an object step but does not orient with the object's floor. Used for bould ## [obj_move_xyz_using_fvel_and_yaw](#obj_move_xyz_using_fvel_and_yaw) ### Description -Don't use this function outside of of a context where the current object and `obj` are the same. Moves `obj` based on a seemingly random mix of using either the current obj or `obj`'s fields +Don't use this function outside of of a context where the current object and `obj` are the same. +Moves `obj` based on a seemingly random mix of using either the current obj or `obj`'s fields ### Lua Example `obj_move_xyz_using_fvel_and_yaw(obj)` @@ -3578,7 +3586,8 @@ Randomly displaces an objects home if RNG says to, and turns the object towards ## [obj_check_if_facing_toward_angle](#obj_check_if_facing_toward_angle) ### Description -A series of checks using sin and cos to see if a given angle is facing in the same direction of a given angle, within a certain range +A series of checks using sin and cos to see if a given angle is facing in the same direction +of a given angle, within a certain range ### Lua Example `local integerValue = obj_check_if_facing_toward_angle(base, goal, range)` @@ -3701,7 +3710,8 @@ Checks if a given room is Mario's current room, even if on an object ## [obj_check_floor_death](#obj_check_floor_death) ### Description -Checks if `floor`'s type is burning or death plane and if so change the current object's action accordingly +Checks if `floor`'s type is burning or death plane and if so change the +current object's action accordingly ### Lua Example `obj_check_floor_death(collisionFlags, floor)` @@ -3725,7 +3735,8 @@ Checks if `floor`'s type is burning or death plane and if so change the current ## [obj_lava_death](#obj_lava_death) ### Description -Controls an object dying in lava by creating smoke, sinking the object, playing audio, and eventually despawning it. Returns TRUE when the obj is dead +Controls an object dying in lava by creating smoke, sinking the object, playing +audio, and eventually despawning it. Returns TRUE when the obj is dead ### Lua Example `local integerValue = obj_lava_death()` @@ -4426,7 +4437,10 @@ Rotates the current object's move angle yaw using `delta` in either a randomly d ## [obj_grow_then_shrink](#obj_grow_then_shrink) ### Description -Begin by increasing the current object's scale by `scaleVel`, and slowly decreasing `scaleVel`. Once the object starts to shrink, wait a bit, and then begin to scale the object toward `endScale`. The first time it reaches below `shootFireScale` during this time, return 1. Return -1 once it's reached endScale +Begin by increasing the current object's scale by `scaleVel`, and slowly decreasing `scaleVel`. +Once the object starts to shrink, wait a bit, and then begin to scale the object toward `endScale`. +The first time it reaches below `shootFireScale` during this time, return 1. +Return -1 once it's reached endScale ### Lua Example `local integerValue, scaleVel = obj_grow_then_shrink(scaleVel, shootFireScale, endScale)` diff --git a/docs/lua/functions-6.md b/docs/lua/functions-6.md index 7a2ee4482..05dda50b4 100644 --- a/docs/lua/functions-6.md +++ b/docs/lua/functions-6.md @@ -777,7 +777,12 @@ Overrides the current room Mario is in. Set to -1 to reset override ## [linear_mtxf_mul_vec3f](#linear_mtxf_mul_vec3f) ### Description -Multiplies a vector by a matrix of the form: `| ? ? ? 0 |` `| ? ? ? 0 |` `| ? ? ? 0 |` `| 0 0 0 1 |` i.e. a matrix representing a linear transformation over 3 space +Multiplies a vector by a matrix of the form: +`| ? ? ? 0 |` +`| ? ? ? 0 |` +`| ? ? ? 0 |` +`| 0 0 0 1 |` +i.e. a matrix representing a linear transformation over 3 space ### Lua Example `linear_mtxf_mul_vec3f(m, dst, v)` @@ -802,7 +807,12 @@ Multiplies a vector by a matrix of the form: `| ? ? ? 0 |` `| ? ? ? 0 |` `| ? ? ## [linear_mtxf_transpose_mul_vec3f](#linear_mtxf_transpose_mul_vec3f) ### Description -Multiplies a vector by the transpose of a matrix of the form: `| ? ? ? 0 |` `| ? ? ? 0 |` `| ? ? ? 0 |` `| 0 0 0 1 |` i.e. a matrix representing a linear transformation over 3 space +Multiplies a vector by the transpose of a matrix of the form: +`| ? ? ? 0 |` +`| ? ? ? 0 |` +`| ? ? ? 0 |` +`| 0 0 0 1 |` +i.e. a matrix representing a linear transformation over 3 space ### Lua Example `linear_mtxf_transpose_mul_vec3f(m, dst, v)` @@ -4788,7 +4798,8 @@ Gets the level number's corresponding course number ## [touch_coin_score_age](#touch_coin_score_age) ### Description -Marks the coin score for a specific course as the newest among all save files. Adjusts the age of other scores to reflect the update. Useful for leaderboard tracking or displaying recent progress +Marks the coin score for a specific course as the newest among all save files. Adjusts the age of other scores to reflect the update. +Useful for leaderboard tracking or displaying recent progress ### Lua Example `touch_coin_score_age(fileIndex, courseIndex)` @@ -4812,7 +4823,8 @@ Marks the coin score for a specific course as the newest among all save files. A ## [save_file_do_save](#save_file_do_save) ### Description -Saves the current state of the game into a specified save file. Includes data verification and backup management. Useful for maintaining game progress during play or when saving manually +Saves the current state of the game into a specified save file. Includes data verification and backup management. +Useful for maintaining game progress during play or when saving manually ### Lua Example `save_file_do_save(fileIndex, forceSave)` @@ -4836,7 +4848,8 @@ Saves the current state of the game into a specified save file. Includes data ve ## [save_file_erase](#save_file_erase) ### Description -Erases all data in a specified save file, including backup slots. Marks the save file as modified and performs a save to apply the changes. Useful for resetting a save file to its default state +Erases all data in a specified save file, including backup slots. Marks the save file as modified and performs a save to apply the changes. +Useful for resetting a save file to its default state ### Lua Example `save_file_erase(fileIndex)` @@ -4880,7 +4893,8 @@ Erases the backup data for the current save file without affecting the primary s ## [save_file_reload](#save_file_reload) ### Description -Reloads the save file data into memory, optionally resetting all save files. Marks the save file as modified. Useful for reloading state after data corruption or during development debugging +Reloads the save file data into memory, optionally resetting all save files. Marks the save file as modified. +Useful for reloading state after data corruption or during development debugging ### Lua Example `save_file_reload(load_all)` @@ -4903,7 +4917,8 @@ Reloads the save file data into memory, optionally resetting all save files. Mar ## [save_file_get_max_coin_score](#save_file_get_max_coin_score) ### Description -Determines the maximum coin score for a course across all save files. Returns the score along with the file index of the save containing it. Useful for leaderboard-style comparisons and overall progress tracking +Determines the maximum coin score for a course across all save files. Returns the score along with the file index of the save containing it. +Useful for leaderboard-style comparisons and overall progress tracking ### Lua Example `local integerValue = save_file_get_max_coin_score(courseIndex)` @@ -4926,7 +4941,8 @@ Determines the maximum coin score for a course across all save files. Returns th ## [save_file_get_course_star_count](#save_file_get_course_star_count) ### Description -Calculates the total number of stars collected in a specific course for a given save file. Useful for determining completion status of individual levels +Calculates the total number of stars collected in a specific course for a given save file. +Useful for determining completion status of individual levels ### Lua Example `local integerValue = save_file_get_course_star_count(fileIndex, courseIndex)` @@ -4950,7 +4966,8 @@ Calculates the total number of stars collected in a specific course for a given ## [save_file_get_total_star_count](#save_file_get_total_star_count) ### Description -Calculates the total number of stars collected across multiple courses within a specified range. Useful for determining the overall progress toward game completion +Calculates the total number of stars collected across multiple courses within a specified range. +Useful for determining the overall progress toward game completion ### Lua Example `local integerValue = save_file_get_total_star_count(fileIndex, minCourse, maxCourse)` @@ -4975,7 +4992,8 @@ Calculates the total number of stars collected across multiple courses within a ## [save_file_set_flags](#save_file_set_flags) ### Description -Adds new flags to the save file's flag bitmask. Useful for updating progress or triggering new gameplay features +Adds new flags to the save file's flag bitmask. +Useful for updating progress or triggering new gameplay features ### Lua Example `save_file_set_flags(flags)` @@ -4998,7 +5016,8 @@ Adds new flags to the save file's flag bitmask. Useful for updating progress or ## [save_file_clear_flags](#save_file_clear_flags) ### Description -Clears specific flags in the current save file. The flags are specified as a bitmask in the `flags` parameter. Ensures that the save file remains valid after clearing. Useful for removing specific game states, such as collected items or completed objectives, without resetting the entire save +Clears specific flags in the current save file. The flags are specified as a bitmask in the `flags` parameter. Ensures that the save file remains valid after clearing. +Useful for removing specific game states, such as collected items or completed objectives, without resetting the entire save ### Lua Example `save_file_clear_flags(flags)` @@ -5021,7 +5040,8 @@ Clears specific flags in the current save file. The flags are specified as a bit ## [save_file_get_flags](#save_file_get_flags) ### Description -Retrieves the bitmask of flags representing the current state of the save file. Flags indicate collected items, completed objectives, and other game states. Useful for checking specific game progress details +Retrieves the bitmask of flags representing the current state of the save file. Flags indicate collected items, completed objectives, and other game states. +Useful for checking specific game progress details ### Lua Example `local integerValue = save_file_get_flags()` @@ -5042,7 +5062,8 @@ Retrieves the bitmask of flags representing the current state of the save file. ## [save_file_get_star_flags](#save_file_get_star_flags) ### Description -Retrieves the bitmask of stars collected in a specific course or castle secret stars (-1). Useful for evaluating level progress and completion +Retrieves the bitmask of stars collected in a specific course or castle secret stars (-1). +Useful for evaluating level progress and completion ### Lua Example `local integerValue = save_file_get_star_flags(fileIndex, courseIndex)` @@ -5066,7 +5087,8 @@ Retrieves the bitmask of stars collected in a specific course or castle secret s ## [save_file_set_star_flags](#save_file_set_star_flags) ### Description -Adds specific star flags to the save file, indicating collected stars for a course or castle secret stars. Updates the save file flags as necessary. Useful for recording progress after star collection +Adds specific star flags to the save file, indicating collected stars for a course or castle secret stars. Updates the save file flags as necessary. +Useful for recording progress after star collection ### Lua Example `save_file_set_star_flags(fileIndex, courseIndex, starFlags)` @@ -5091,7 +5113,8 @@ Adds specific star flags to the save file, indicating collected stars for a cour ## [save_file_remove_star_flags](#save_file_remove_star_flags) ### Description -Removes specific star flags from the save file. This modifies the bitmask representing collected stars for a course or castle secret stars. Useful for undoing progress or debugging collected stars +Removes specific star flags from the save file. This modifies the bitmask representing collected stars for a course or castle secret stars. +Useful for undoing progress or debugging collected stars ### Lua Example `save_file_remove_star_flags(fileIndex, courseIndex, starFlagsToRemove)` @@ -5116,7 +5139,8 @@ Removes specific star flags from the save file. This modifies the bitmask repres ## [save_file_get_course_coin_score](#save_file_get_course_coin_score) ### Description -Returns the highest coin score for a specified course in the save file. Performs checks to ensure the coin score is valid. Useful for tracking player achievements and high scores +Returns the highest coin score for a specified course in the save file. Performs checks to ensure the coin score is valid. +Useful for tracking player achievements and high scores ### Lua Example `local integerValue = save_file_get_course_coin_score(fileIndex, courseIndex)` @@ -5140,7 +5164,8 @@ Returns the highest coin score for a specified course in the save file. Performs ## [save_file_set_course_coin_score](#save_file_set_course_coin_score) ### Description -Updates the coin score for a specific course in the save file. The new score is provided in the `coinScore` parameter. Useful for manually setting achievements such as high coin counts in individual levels +Updates the coin score for a specific course in the save file. The new score is provided in the `coinScore` parameter. +Useful for manually setting achievements such as high coin counts in individual levels ### Lua Example `save_file_set_course_coin_score(fileIndex, courseIndex, coinScore)` @@ -5165,7 +5190,8 @@ Updates the coin score for a specific course in the save file. The new score is ## [save_file_is_cannon_unlocked](#save_file_is_cannon_unlocked) ### Description -Checks whether the cannon in the specified course is unlocked. Returns true if the cannon is unlocked, otherwise false. Useful for tracking course-specific progress and enabling shortcuts +Checks whether the cannon in the specified course is unlocked. Returns true if the cannon is unlocked, otherwise false. +Useful for tracking course-specific progress and enabling shortcuts ### Lua Example `local integerValue = save_file_is_cannon_unlocked(fileIndex, courseIndex)` @@ -5210,7 +5236,8 @@ Unlocks the cannon in the current course ## [save_file_get_cap_pos](#save_file_get_cap_pos) ### Description -Retrieves the current position of Mario's cap, if it is on the ground in the current level and area. The position is stored in the provided `capPos` parameter. Useful for tracking the cap's location after it has been dropped or lost +Retrieves the current position of Mario's cap, if it is on the ground in the current level and area. The position is stored in the provided `capPos` parameter. +Useful for tracking the cap's location after it has been dropped or lost ### Lua Example `local integerValue = save_file_get_cap_pos(capPos)` @@ -5233,7 +5260,8 @@ Retrieves the current position of Mario's cap, if it is on the ground in the cur ## [save_file_get_sound_mode](#save_file_get_sound_mode) ### Description -Returns the current sound mode (e.g., stereo, mono) stored in the save file. Useful for checking the audio output preferences when loading a save +Returns the current sound mode (e.g., stereo, mono) stored in the save file. +Useful for checking the audio output preferences when loading a save ### Lua Example `local integerValue = save_file_get_sound_mode()` @@ -6296,7 +6324,8 @@ Sets if the romhack camera should allow D-Pad movement ## [camera_romhack_set_collisions](#camera_romhack_set_collisions) ### Description -Toggles collision settings for the ROM hack camera. This enables or disables specific collision behaviors in modded levels +Toggles collision settings for the ROM hack camera. +This enables or disables specific collision behaviors in modded levels ### Lua Example `camera_romhack_set_collisions(enable)` @@ -7429,7 +7458,9 @@ Gets a table of the surface types from `data` ## [smlua_collision_add_surface](#smlua_collision_add_surface) ### Description -Allocates a new collision surface with the given vertices, computes the surface normal and other fields, and inserts it into the spatial partition. Returns the new surface, or `nil` if the triangle is degenerate (zero area). Set `dynamic` to `true` for surfaces that are cleared each frame, or `false` for persistent static surfaces +Allocates a new collision surface with the given vertices, computes the surface normal and other fields, and inserts it into the spatial partition. +Returns the new surface, or `nil` if the triangle is degenerate (zero area). +Set `dynamic` to `true` for surfaces that are cleared each frame, or `false` for persistent static surfaces ### Lua Example `local surfaceValue = smlua_collision_add_surface(dynamic, surfaceType, vertex1, vertex2, vertex3)` @@ -7456,7 +7487,9 @@ Allocates a new collision surface with the given vertices, computes the surface ## [smlua_collision_move_surface](#smlua_collision_move_surface) ### Description -Moves an existing collision surface to new vertex positions. Recalculates the surface normal, origin offset, and Y bounds, removes the surface from its old spatial partition cells, and re-adds it to the correct cells. The previous vertices are preserved for interpolation +Moves an existing collision surface to new vertex positions. +Recalculates the surface normal, origin offset, and Y bounds, removes the surface from its old spatial partition cells, and re-adds it to the correct cells. +The previous vertices are preserved for interpolation ### Lua Example `smlua_collision_move_surface(surface, vertex1, vertex2, vertex3)` diff --git a/docs/lua/functions-7.md b/docs/lua/functions-7.md index 23c515329..6779d5890 100644 --- a/docs/lua/functions-7.md +++ b/docs/lua/functions-7.md @@ -751,7 +751,8 @@ Gets the texture from a display list command if it has an image related op ## [gfx_get_from_name](#gfx_get_from_name) ### Description -Gets a display list of the current mod from its name. Returns a pointer to the display list and its length +Gets a display list of the current mod from its name. +Returns a pointer to the display list and its length ### Lua Example `local pointerValue, length = gfx_get_from_name(name)` @@ -985,7 +986,8 @@ Deletes all display lists created by `gfx_create` ## [vtx_get_from_name](#vtx_get_from_name) ### Description -Gets a vertex buffer of the current mod from its name. Returns a pointer to the vertex buffer and its vertex count +Gets a vertex buffer of the current mod from its name. +Returns a pointer to the vertex buffer and its vertex count ### Lua Example `local pointerValue, count = vtx_get_from_name(name)` @@ -2533,7 +2535,8 @@ Allocates an action ID with bitwise flags ## [get_hand_foot_pos_x](#get_hand_foot_pos_x) ### Description -Gets the X coordinate of Mario's hand (0-1) or foot (2-3) but it is important to note that the positions are not updated off-screen +Gets the X coordinate of Mario's hand (0-1) or foot (2-3) +but it is important to note that the positions are not updated off-screen ### Lua Example `local numberValue = get_hand_foot_pos_x(m, index)` @@ -2557,7 +2560,8 @@ Gets the X coordinate of Mario's hand (0-1) or foot (2-3) but it is important to ## [get_hand_foot_pos_y](#get_hand_foot_pos_y) ### Description -Gets the Y coordinate of Mario's hand (0-1) or foot (2-3) but It is important to note that the positions are not updated off-screen +Gets the Y coordinate of Mario's hand (0-1) or foot (2-3) +but It is important to note that the positions are not updated off-screen ### Lua Example `local numberValue = get_hand_foot_pos_y(m, index)` @@ -2581,7 +2585,8 @@ Gets the Y coordinate of Mario's hand (0-1) or foot (2-3) but It is important to ## [get_hand_foot_pos_z](#get_hand_foot_pos_z) ### Description -Gets the Z coordinate of Mario's hand (0-1) or foot (2-3) but it is important to note that the positions are not updated off-screen +Gets the Z coordinate of Mario's hand (0-1) or foot (2-3) +but it is important to note that the positions are not updated off-screen ### Lua Example `local numberValue = get_hand_foot_pos_z(m, index)` @@ -3620,7 +3625,8 @@ Gets the extended model ID for the `name` of a `GeoLayout` ## [spawn_sync_object](#spawn_sync_object) ### Description -Spawns a synchronized object at `x`, `y`, and `z` as a child object of the local Mario with his rotation. You can change the fields of the object in `objSetupFunction` +Spawns a synchronized object at `x`, `y`, and `z` as a child object of the local Mario with his rotation. +You can change the fields of the object in `objSetupFunction` ### Lua Example `local objectValue = spawn_sync_object(behaviorId, modelId, x, y, z, objSetupFunction)` @@ -3648,7 +3654,8 @@ Spawns a synchronized object at `x`, `y`, and `z` as a child object of the local ## [spawn_non_sync_object](#spawn_non_sync_object) ### Description -Spawns a non-synchronized object at `x`, `y`, and `z` as a child object of the local Mario with his rotation. You can change the fields of the object in `objSetupFunction` +Spawns a non-synchronized object at `x`, `y`, and `z` as a child object of the local Mario with his rotation. +You can change the fields of the object in `objSetupFunction` ### Lua Example `local objectValue = spawn_non_sync_object(behaviorId, modelId, x, y, z, objSetupFunction)` @@ -3991,7 +3998,8 @@ Gets the first object loaded with `behaviorId` ## [obj_get_first_with_behavior_id_and_field_s32](#obj_get_first_with_behavior_id_and_field_s32) ### Description -Gets the first object loaded with `behaviorId` and object signed 32-bit integer field (look in `object_fields.h` to get the index of a field) +Gets the first object loaded with `behaviorId` and object signed 32-bit integer field +(look in `object_fields.h` to get the index of a field) ### Lua Example `local objectValue = obj_get_first_with_behavior_id_and_field_s32(behaviorId, fieldIndex, value)` @@ -4016,7 +4024,8 @@ Gets the first object loaded with `behaviorId` and object signed 32-bit integer ## [obj_get_first_with_behavior_id_and_field_f32](#obj_get_first_with_behavior_id_and_field_f32) ### Description -Gets the first object loaded with `behaviorId` and object float field (look in `object_fields.h` to get the index of a field) +Gets the first object loaded with `behaviorId` and object float field +(look in `object_fields.h` to get the index of a field) ### Lua Example `local objectValue = obj_get_first_with_behavior_id_and_field_f32(behaviorId, fieldIndex, value)` @@ -4087,7 +4096,8 @@ Gets the next object loaded with the same behavior ID ## [obj_get_next_with_same_behavior_id_and_field_s32](#obj_get_next_with_same_behavior_id_and_field_s32) ### Description -Gets the next object loaded with the same behavior ID and object signed 32-bit integer field (look in `object_fields.h` to get the index of a field) +Gets the next object loaded with the same behavior ID and object signed 32-bit integer field +(look in `object_fields.h` to get the index of a field) ### Lua Example `local objectValue = obj_get_next_with_same_behavior_id_and_field_s32(o, fieldIndex, value)` @@ -4112,7 +4122,8 @@ Gets the next object loaded with the same behavior ID and object signed 32-bit i ## [obj_get_next_with_same_behavior_id_and_field_f32](#obj_get_next_with_same_behavior_id_and_field_f32) ### Description -Gets the next object loaded with the same behavior ID and object float field (look in `object_fields.h` to get the index of a field) +Gets the next object loaded with the same behavior ID and object float field +(look in `object_fields.h` to get the index of a field) ### Lua Example `local objectValue = obj_get_next_with_same_behavior_id_and_field_f32(o, fieldIndex, value)` @@ -5882,7 +5893,8 @@ Plays a sound if the current object is visible and queues rumble for specific so ## [create_sound_spawner](#create_sound_spawner) ### Description -Create a sound spawner for objects that need a sound play once. (Breakable walls, King Bobomb exploding, etc) +Create a sound spawner for objects that need a sound play once. +(Breakable walls, King Bobomb exploding, etc) ### Lua Example `create_sound_spawner(soundMagic)` @@ -5905,7 +5917,9 @@ Create a sound spawner for objects that need a sound play once. (Breakable walls ## [calc_dist_to_volume_range_1](#calc_dist_to_volume_range_1) ### Description -Unused vanilla function, calculates a volume based on `distance`. If `distance` is less than 500 then 127, if `distance` is greater than 1500 then 0, if `distance` is between 500 and 1500 then it ranges linearly from 60 to 124. What an even more strange and confusing function +Unused vanilla function, calculates a volume based on `distance`. +If `distance` is less than 500 then 127, if `distance` is greater than 1500 then 0, if `distance` is between 500 and 1500 then it ranges linearly from 60 to 124. +What an even more strange and confusing function ### Lua Example `local integerValue = calc_dist_to_volume_range_1(distance)` @@ -5928,7 +5942,9 @@ Unused vanilla function, calculates a volume based on `distance`. If `distance` ## [calc_dist_to_volume_range_2](#calc_dist_to_volume_range_2) ### Description -Unused vanilla function, calculates a volume based on `distance`. If `distance` is less than 1300 then 127, if `distance` is greater than 2300 then 0, if `distance` is between 1300 and 2300 then it ranges linearly from 60 to 127. What a strange and confusing function +Unused vanilla function, calculates a volume based on `distance`. +If `distance` is less than 1300 then 127, if `distance` is greater than 2300 then 0, if `distance` is between 1300 and 2300 then it ranges linearly from 60 to 127. +What a strange and confusing function ### Lua Example `local integerValue = calc_dist_to_volume_range_2(distance)` @@ -5957,7 +5973,8 @@ Unused vanilla function, calculates a volume based on `distance`. If `distance` ## [find_wall_collisions](#find_wall_collisions) ### Description -Detects wall collisions at a given position and adjusts the position based on the walls found. Returns the number of wall collisions detected +Detects wall collisions at a given position and adjusts the position based on the walls found. +Returns the number of wall collisions detected ### Lua Example `local integerValue = find_wall_collisions(colData)` @@ -5980,7 +5997,8 @@ Detects wall collisions at a given position and adjusts the position based on th ## [find_ceil](#find_ceil) ### Description -Finds the height of the highest ceiling above a given position (x, y, z) and return the corresponding ceil surface. If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default) +Finds the height of the highest ceiling above a given position (x, y, z) and return the corresponding ceil surface. +If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default) ### Lua Example `local numberValue, pceil = find_ceil(posX, posY, posZ)` @@ -6006,7 +6024,8 @@ Finds the height of the highest ceiling above a given position (x, y, z) and ret ## [find_ceil_height](#find_ceil_height) ### Description -Finds the height of the highest ceiling above a given position (x, y, z). If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default) +Finds the height of the highest ceiling above a given position (x, y, z). +If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default) ### Lua Example `local numberValue = find_ceil_height(x, y, z)` @@ -6031,7 +6050,8 @@ Finds the height of the highest ceiling above a given position (x, y, z). If no ## [find_floor_height](#find_floor_height) ### Description -Finds the height of the highest floor below a given position (x, y, z). If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default) +Finds the height of the highest floor below a given position (x, y, z). +If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default) ### Lua Example `local numberValue = find_floor_height(x, y, z)` @@ -6056,7 +6076,8 @@ Finds the height of the highest floor below a given position (x, y, z). If no fl ## [find_floor](#find_floor) ### Description -Finds the height of the highest floor below a given position (x, y, z) and return the corresponding floor surface. If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default) +Finds the height of the highest floor below a given position (x, y, z) and return the corresponding floor surface. +If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default) ### Lua Example `local numberValue, pfloor = find_floor(xPos, yPos, zPos)` @@ -6082,7 +6103,8 @@ Finds the height of the highest floor below a given position (x, y, z) and retur ## [find_water_level](#find_water_level) ### Description -Finds the height of water at a given position (x, z), if the position is within a water region. If no water is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default) +Finds the height of water at a given position (x, z), if the position is within a water region. +If no water is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default) ### Lua Example `local numberValue = find_water_level(x, z)` @@ -6106,7 +6128,8 @@ Finds the height of water at a given position (x, z), if the position is within ## [find_poison_gas_level](#find_poison_gas_level) ### Description -Finds the height of the poison gas at a given position (x, z), if the position is within a gas region. If no gas is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default) +Finds the height of the poison gas at a given position (x, z), if the position is within a gas region. +If no gas is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default) ### Lua Example `local numberValue = find_poison_gas_level(x, z)` @@ -6186,7 +6209,8 @@ Gets the closest point of the triangle to `src` and returns it in `out`. ## [load_object_collision_model](#load_object_collision_model) ### Description -Loads the object's collision data into dynamic collision. You must run this every frame in your object's behavior loop for it to have collision +Loads the object's collision data into dynamic collision. +You must run this every frame in your object's behavior loop for it to have collision ### Lua Example `load_object_collision_model()` @@ -6207,7 +6231,8 @@ Loads the object's collision data into dynamic collision. You must run this ever ## [load_static_object_collision](#load_static_object_collision) ### Description -Loads the object's collision data into static collision. You may run this only once to capture the object's collision at that frame. +Loads the object's collision data into static collision. +You may run this only once to capture the object's collision at that frame. ### Lua Example `local staticObjectCollisionValue = load_static_object_collision()` diff --git a/docs/lua/functions.md b/docs/lua/functions.md index a286da56d..bb2cd05d3 100644 --- a/docs/lua/functions.md +++ b/docs/lua/functions.md @@ -2836,7 +2836,8 @@ Derives a `MARIO_SPAWN_*` constant from `o` ## [area_get_warp_node](#area_get_warp_node) ### Description -Finds a warp node in the current area by its ID. The warp node must exist in the list of warp nodes for the current area. Useful for locating a specific warp point in the level, such as teleportation zones or connections to other areas +Finds a warp node in the current area by its ID. The warp node must exist in the list of warp nodes for the current area. +Useful for locating a specific warp point in the level, such as teleportation zones or connections to other areas ### Lua Example `local objectWarpNodeValue = area_get_warp_node(id)` @@ -2880,7 +2881,8 @@ Gets the first warp node found in the area, otherwise returns nil ## [area_get_warp_node_from_params](#area_get_warp_node_from_params) ### Description -Finds a warp node in the current area using parameters from the provided object. The object's behavior parameters are used to determine the warp node ID. Useful for associating an object (like a door or warp pipe) with its corresponding warp node in the area +Finds a warp node in the current area using parameters from the provided object. The object's behavior parameters are used to determine the warp node ID. +Useful for associating an object (like a door or warp pipe) with its corresponding warp node in the area ### Lua Example `local objectWarpNodeValue = area_get_warp_node_from_params(o)`