Documentation of mario.h, mario_actions_airborne.c, mario_actions_automatic.c, mario_actions_cutscene.c, and mario_actions_moving.c (#601)

* WIP mario.h - mario_actions_moving.c

* Fix improper list formatting

bulleted lists are broken due to whitespace stripping, i may fix this later.

* Fix some issues in formatting and missing descriptions

* Accidental struct syntax fix

* Fix repeating descriptions

* Fix repeating descriptions final

autogen/extract_functions.py

@@ -13,7 +13,6 @@ replacements = {
     'BAD_RETURN(u64)': 'void',
     'BAD_RETURN(f32)': 'void',
     'BAD_RETURN(f64)': 'void',
-
 }
 
 def extract_functions(filename):
@@ -83,11 +82,9 @@ def extract_functions(filename):
     for character in tmp:
         if inside == 0:
             txt += character
-
         if character == '{':
             txt += '\n'
             inside += 1
-
         if character == '}':
             inside -= 1
 
@@ -112,6 +109,11 @@ def extract_functions(filename):
         function_without_semicolon = line.rstrip(';')
         for i, raw_line in enumerate(raw_lines):
             if function_without_semicolon in raw_line:
+                if i - 1 >= 0:
+                    prev_line = raw_lines[i - 1].rstrip()
+                    if not prev_line.endswith('*/'):
+                        break
+
                 # found the function in raw_lines, now look above for |descriptionEnd|
                 # We'll scan upwards until we find |descriptionEnd| and then keep going until |description| is found.
                 description_end_line_index = None
@@ -144,8 +146,7 @@ def extract_functions(filename):
                         combined_description = re.sub(r'\|\s*descriptionEnd\s*\|.*', '', combined_description).strip()
                         # Normalize whitespace
                         combined_description = re.sub(r'\s+', ' ', combined_description).strip()
-                        descriptions[line] = combined_description
+                        descriptions[re.sub(r'\)\s*\{', ');', line)] = combined_description
-
                 break
 
     # normalize function ending
@@ -159,4 +160,3 @@ if __name__ == "__main__":
     for func, desc in descriptions.items():
         print(f"Function: {func}")
         print(f"    Description: {desc}\n")
-

autogen/lua_definitions/functions.lua

@@ -3509,7 +3509,6 @@ function set_environmental_camera_shake(shake)
 end
 
 --- @param preset integer
---- Transitions the camera to the next Lakitu state, updating position and focus. This function handles smooth transitions between different gameplay scenarios
 function set_fixed_cam_axis_sa_lobby(preset)
     -- ...
 end
@@ -4817,18 +4816,21 @@ function warp_special(arg)
 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
 function adjust_sound_for_speed(m)
     -- ...
 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
 function check_common_action_exits(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- Checks for inputs that cause common hold-action transitions (hold jump, hold freefall, hold walking, hold sliding)
 function check_common_hold_action_exits(m)
     -- ...
 end
@@ -4837,12 +4839,14 @@ end
 --- @param action integer
 --- @param actionArg integer
 --- @return integer
+--- Drops any currently held object and sets Mario to a new action. This function is typically used when Mario transitions to states where he cannot hold objects
 function drop_and_set_mario_action(m, action, actionArg)
     -- ...
 end
 
 --- @param o Object
 --- @return integer
+--- Main driver for Mario's behavior. Executes the current action group (stationary, moving, airborne, etc.) in a loop until no further action changes are necessary
 function execute_mario_action(o)
     -- ...
 end
@@ -4851,6 +4855,7 @@ 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
 function find_floor_height_relative_polar(m, angleFromMario, distFromMario)
     -- ...
 end
@@ -4858,6 +4863,7 @@ 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
 function find_floor_slope(m, yawOffset)
     -- ...
 end
@@ -4866,12 +4872,14 @@ 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
 function find_mario_anim_flags_and_translation(o, yaw, translation)
     -- ...
 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)
 function force_idle_state(m)
     -- ...
 end
@@ -4881,23 +4889,27 @@ end
 --- @param actionArg integer
 --- @param hurtCounter integer
 --- @return integer
+--- Increments Mario's `hurtCounter` and immediately sets a new action. Often used when Mario takes damage and transitions into a knockback or stunned action.
 function hurt_and_set_mario_action(m, action, actionArg, hurtCounter)
     -- ...
 end
 
 --- @param m MarioState
+--- Initializes the fields of a single `MarioState` structure when the player spawns or respawns. Sets starting position, velocity, action, and various internal flags
 function init_single_mario(m)
     -- ...
 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
 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
 function is_anim_past_end(m)
     -- ...
 end
@@ -4905,12 +4917,14 @@ 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
 function is_anim_past_frame(m, animFrame)
     -- ...
 end
 
 --- @param m MarioState
 --- @return boolean
+--- Checks whether Mario can become bubbled under certain game conditions (multiplayer bubble mechanic). Returns false if already bubbled or if not allowed by settings
 function mario_can_bubble(m)
     -- ...
 end
@@ -4918,59 +4932,69 @@ 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
 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
 function mario_floor_is_slippery(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- Checks whether Mario's floor is a slope, i.e., not flat but not necessarily steep. This depends on the floor's surface class and angle
 function mario_floor_is_slope(m)
     -- ...
 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
 function mario_floor_is_steep(m)
     -- ...
 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
 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
 function mario_get_terrain_sound_addend(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @return boolean
+--- Returns true if Mario is in any of the crouching or crawling states, checking his current action
 function mario_is_crouching(m)
     -- ...
 end
 
 --- @param m MarioState
+--- Transitions Mario into a bubbled state (if available in multiplayer), decrementing lives and preventing normal movement
 function mario_set_bubbled(m)
     -- ...
 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.)
 function mario_set_forward_vel(m, speed)
     -- ...
 end
 
 --- @param m MarioState
 --- @param wcd WallCollisionData
+--- Updates Mario's wall information based on wall collisions (`WallCollisionData`). Chooses the most relevant wall depending on the level’s collision fix settings
 function mario_update_wall(m, wcd)
     -- ...
 end
@@ -4978,35 +5002,41 @@ end
 --- @param m MarioState
 --- @param soundBits integer
 --- @param waveParticleType integer
+--- Plays an action sound once per action, optionally spawning wave or dust particles depending on the surface. This sets the `MARIO_ACTION_SOUND_PLAYED` flag to prevent repeats
 function play_mario_action_sound(m, soundBits, waveParticleType)
     -- ...
 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
 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
 function play_mario_heavy_landing_sound_once(m, soundBits)
     -- ...
 end
 
 --- @param m MarioState
+--- Plays Mario’s jump sound if it hasn't been played yet since the last action change. This helps avoid overlapping jump voice lines on repeated jumps
 function play_mario_jump_sound(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @param soundBits integer
+--- Plays a normal landing sound (or metal landing sound if Mario is metal) and spawns appropriate particle effects (water splash, dust, etc.)
 function play_mario_landing_sound(m, soundBits)
     -- ...
 end
 
 --- @param m MarioState
 --- @param soundBits integer
+--- A variant of `play_mario_landing_sound` that ensures the sound is only played once per action. Uses `play_mario_action_sound` internally
 function play_mario_landing_sound_once(m, soundBits)
     -- ...
 end
@@ -5014,6 +5044,7 @@ end
 --- @param m MarioState
 --- @param primarySoundBits integer
 --- @param scondarySoundBits integer
+--- Plays a given action sound (like a jump or landing) and also a Mario voice line if certain conditions are met. It manages flags to avoid repeated sounds
 function play_mario_sound(m, primarySoundBits, scondarySoundBits)
     -- ...
 end
@@ -5021,6 +5052,7 @@ end
 --- @param m MarioState
 --- @param soundBits integer
 --- @param waveParticleType integer
+--- Plays the specified sound effect and spawns surface-appropriate particles (e.g., water splash, snow, sand). Checks if Mario is metal to adjust audio accordingly
 function play_sound_and_spawn_particles(m, soundBits, waveParticleType)
     -- ...
 end
@@ -5028,6 +5060,7 @@ end
 --- @param m MarioState
 --- @param soundBits integer
 --- @param flags integer
+--- Plays a sound if Mario does not currently have a specific flag set. Once played, the flag is set to prevent immediate repeats
 function play_sound_if_no_flag(m, soundBits, flags)
     -- ...
 end
@@ -5036,6 +5069,7 @@ 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
 function resolve_and_return_wall_collisions(pos, offset, radius)
     -- ...
 end
@@ -5044,18 +5078,21 @@ end
 --- @param offset number
 --- @param radius number
 --- @param collisionData WallCollisionData
+--- Similar to `resolve_and_return_wall_collisions` but also returns detailed collision data (`WallCollisionData`). This can handle multiple walls and store them for further checks
 function resolve_and_return_wall_collisions_data(pos, offset, radius, collisionData)
     -- ...
 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)
 function return_mario_anim_y_translation(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @param animFrame integer
+--- Sets the current animation frame to a specific `animFrame`
 function set_anim_to_frame(m, animFrame)
     -- ...
 end
@@ -5064,6 +5101,7 @@ end
 --- @param targetAnimID integer
 --- @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)
 function set_character_anim_with_accel(m, targetAnimID, accel)
     -- ...
 end
@@ -5071,12 +5109,14 @@ end
 --- @param m MarioState
 --- @param targetAnimID integer
 --- @return integer
+--- Sets the character-specific animation at its default rate (no acceleration)
 function set_character_animation(m, targetAnimID)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- When Mario lands on the ground, decides whether to jump again (single, double, triple) or enter a steep jump if the floor is very steep. Handles quicksand logic as well
 function set_jump_from_landing(m)
     -- ...
 end
@@ -5085,6 +5125,7 @@ end
 --- @param action integer
 --- @param actionArg integer
 --- @return integer
+--- Sets Mario to a jumping action (regular, double, triple, or steep jump) if conditions allow it. If the floor is too steep or if in quicksand, it changes the action accordingly
 function set_jumping_action(m, action, actionArg)
     -- ...
 end
@@ -5093,6 +5134,7 @@ end
 --- @param action integer
 --- @param actionArg integer
 --- @return integer
+--- Sets Mario's action to the specified `action` and `actionArg`, routing through group-specific transition functions (e.g., airborne actions). Resets sound flags and updates internal timers
 function set_mario_action(m, action, actionArg)
     -- ...
 end
@@ -5101,6 +5143,7 @@ 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
 function set_mario_anim_with_accel(m, targetAnimID, accel)
     -- ...
 end
@@ -5108,6 +5151,7 @@ end
 --- @param m MarioState
 --- @param targetAnimID integer
 --- @return integer
+--- Sets Mario's current animation to `targetAnimID` at a default acceleration (no speed change)
 function set_mario_animation(m, targetAnimID)
     -- ...
 end
@@ -5115,6 +5159,7 @@ end
 --- @param m MarioState
 --- @param flags integer
 --- @param clear integer
+--- Sets Mario's particle flags to spawn various visual effects (dust, water splashes, etc.), with an option to clear or set new flags
 function set_mario_particle_flags(m, flags, clear)
     -- ...
 end
@@ -5122,39 +5167,46 @@ end
 --- @param m MarioState
 --- @param initialVelY number
 --- @param multiplier number
+--- Adjusts Mario's vertical velocity (`m.vel.y`) based on his forward speed. This function also accounts for conditions like quicksand to halve velocity
 function set_mario_y_vel_based_on_fspeed(m, initialVelY, multiplier)
     -- ...
 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
 function set_steep_jump_action(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- Transitions Mario into a "water plunge" action, used when he enters water from above. Adjusts position, velocity, and camera mode
 function set_water_plunge_action(m)
     -- ...
 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
 function transition_submerged_to_walking(m)
     -- ...
 end
 
 --- @param m MarioState
+--- Applies the translation from Mario's current animation to his world position. Considers animation flags (horizontal/vertical translation)
 function update_mario_pos_for_anim(m)
     -- ...
 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
 function update_mario_sound_and_camera(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`
 function check_common_airborne_cancels(m)
     -- ...
 end
@@ -5162,6 +5214,7 @@ 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
 function check_fall_damage(m, hardFallAction)
     -- ...
 end
@@ -5169,24 +5222,28 @@ 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
 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
 function check_horizontal_wind(m)
     -- ...
 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)
 function check_kick_or_dive_in_air(m)
     -- ...
 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`
 function check_wall_kick(m)
     -- ...
 end
@@ -5196,6 +5253,7 @@ 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
 function common_air_action_step(m, landAction, animation, stepArg)
     -- ...
 end
@@ -5206,23 +5264,27 @@ 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
 function common_air_knockback_step(m, landAction, hardFallAction, animation, speed)
     -- ...
 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
 function lava_boost_on_wall(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
 function mario_execute_airborne_action(m)
     -- ...
 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
 function play_far_fall_sound(m)
     -- ...
 end
@@ -5231,75 +5293,89 @@ 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`
 function play_flip_sounds(m, frame1, frame2, frame3)
     -- ...
 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
 function play_knockback_sound(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
 function should_get_stuck_in_ground(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
 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
 function update_air_without_turn(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
 function update_flying(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
 function update_flying_pitch(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
 function update_flying_yaw(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`
 function update_lava_boost_or_twirling(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
 function add_tree_leaf_particles(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- Checks if Mario should cancel his current automatic action, primarily by detecting if he falls into deep water. If so, transitions him to the water-plunge state
 function check_common_automatic_cancels(m)
     -- ...
 end
 
 --- @param m MarioState
+--- Moves Mario onto the top of a ledge once he finishes climbing it. This shifts Mario forward slightly on the ledge and updates his animation accordingly
 function climb_up_ledge(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- Handles Mario letting go of a ledge by adjusting his position and setting his velocity to make him fall away from the ledge. The action then transitions to a 'soft bonk' state
 function let_go_of_ledge(m)
     -- ...
 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
 function mario_execute_automatic_action(m)
     -- ...
 end
@@ -5307,12 +5383,14 @@ end
 --- @param m MarioState
 --- @param nextPos Vec3f
 --- @return integer
+--- Performs a single step of movement while Mario is hanging from a ceiling. It handles wall collisions and checks the floor and ceiling to determine if Mario remains hanging, leaves the ceiling, or hits it
 function perform_hanging_step(m, nextPos)
     -- ...
 end
 
 --- @param m MarioState
 --- @param b integer
+--- Plays the appropriate climbing sound effect depending on whether Mario is on a tree or a pole. If `b == 1`, it plays the "climbing up" sound; otherwise, it plays the "sliding down" sound
 function play_climbing_sounds(m, b)
     -- ...
 end
@@ -5320,17 +5398,20 @@ 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
 function set_pole_position(m, offsetY)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- Updates Mario's velocity and position while he is moving across a hangable ceiling. It calls `perform_hanging_step()` to handle collisions and movement logic, returning a status code indicating if Mario is still hanging or if he left the ceiling
 function update_hang_moving(m)
     -- ...
 end
 
 --- @param m MarioState
+--- Keeps Mario stationary while he is hanging from a ceiling. This function zeroes out his velocity and ensures he remains aligned with the ceiling
 function update_hang_stationary(m)
     -- ...
 end
@@ -5338,19 +5419,23 @@ end
 --- @param m MarioState
 --- @param animation integer
 --- @param endAction integer
+--- Updates Mario's climb onto a ledge by setting the chosen climbing animation and transitioning to the specified end action (e.g., standing idle) once the animation finishes. If the end action is `ACT_IDLE`, Mario is placed on top of the ledge
 function update_ledge_climb(m, animation, endAction)
     -- ...
 end
 
 --- @param m MarioState
+--- Gradually adjusts the camera position to track Mario as he climbs a ledge. This creates a smoother view transition from the ledge-grab camera angle to Mario's new location on top of the ledge
 function update_ledge_climb_camera(m)
     -- ...
 end
 
+--- Handles Peach's final cutscene animation. Cycles through frames based on the global `sEndPeachAnimation` value
 function bhv_end_peach_loop()
     -- ...
 end
 
+--- Handles Toad's final cutscene animation. Chooses which animation index to use based on Toad's x-position, then progresses through the animation frames as it nears completion
 function bhv_end_toad_loop()
     -- ...
 end
@@ -5359,22 +5444,26 @@ end
 --- @param animation integer
 --- @param frameToDeathWarp integer
 --- @return integer
+--- Handles shared logic for Mario's various death states. Plays the specified death animation (`animation`), checks for a specific frame (`frameToDeathWarp`) to trigger a warp or bubble state if allowed, and sets Mario's eye state to 'dead'
 function common_death_handler(m, animation, frameToDeathWarp)
     -- ...
 end
 
 --- @param m MarioState
+--- Transitions Mario's state from having the cap in his hand to wearing it on his head. Clears the `MARIO_CAP_IN_HAND` flag, sets the `MARIO_CAP_ON_HEAD` flag, and plays the 'put cap on' sound
 function cutscene_put_cap_on(m)
     -- ...
 end
 
 --- @param m MarioState
+--- Transitions Mario's state from wearing the cap on his head to holding it in his hand. Clears the `MARIO_CAP_ON_HEAD` flag, sets the `MARIO_CAP_IN_HAND` flag, and plays the 'take cap off' sound
 function cutscene_take_cap_off(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @param isInWater integer
+--- Manages the star collection dance sequence for Mario, both on land and in water. Plays music, spawns the celebration star, increments the star count, and triggers level exits or dialogs at the correct times
 function general_star_dance_handler(m, isInWater)
     -- ...
 end
@@ -5383,23 +5472,27 @@ end
 --- @param y integer
 --- @param z integer
 --- @param radius number
+--- Spawns yellow sparkles in a circular pattern around a specified point (`x`, `y`, `z`) within a given `radius`. Frequently seen during end cutscenes when objects like stars or Peach appear
 function generate_yellow_sparkles(x, y, z, radius)
     -- ...
 end
 
 --- @param str Pointer_integer
 --- @return integer
+--- Calculates the pixel width of a given credits string. Each space is counted as 4 pixels, and any other character as 7 pixels. Stops counting at the null terminator
 function get_credits_str_width(str)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- Determines which (if any) dialog to show when Mario collects a star. Checks milestone star counts against `prevNumStarsForDialog`, and returns a dialog ID if a milestone is reached. Otherwise, returns 0
 function get_star_collection_dialog(m)
     -- ...
 end
 
 --- @param m MarioState
+--- Handles interactions with the save menu after collecting a star/key. Checks the user's selection (e.g., Save and Continue) and performs the corresponding action, such as saving the file or returning Mario to idle
 function handle_save_menu(m)
     -- ...
 end
@@ -5409,18 +5502,21 @@ end
 --- @param animation integer
 --- @param forwardVel number
 --- @return integer
+--- Launches Mario forward with a given velocity (`forwardVel`) and sets his animation. Continues moving him through the air until he lands, then changes Mario's action to `endAction`
 function launch_mario_until_land(m, endAction, animation, forwardVel)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- Executes Mario's current cutscene action based on his `action` field. Includes various story-related sequences like entering doors, collecting stars, and final boss cutscenes. Delegates to the appropriate function for each cutscene action
 function mario_execute_cutscene_action(m)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- Checks if Mario's current action allows him to speak. For Mario to be ready, his action must be in a 'stationary' or 'moving' group (or waiting for dialog), and he must not be riding a shell, invulnerable, or in first-person mode
 function mario_ready_to_speak(m)
     -- ...
 end
@@ -5428,6 +5524,7 @@ end
 --- @param m MarioState
 --- @param object Object
 --- @return integer
+--- Checks if the dialog from a specified `object` should start or continue for this particular Mario. Ensures Mario is visible to enemies (i.e., not in certain invulnerable states) and, for remote players, validates the correct dialog object
 function should_start_or_continue_dialog(m, object)
     -- ...
 end
@@ -5443,27 +5540,32 @@ function stuck_in_ground_handler(m, animation, unstuckFrame, target2, target3, e
 end
 
 --- @param m MarioState
+--- Aligns Mario's position and model transformation matrix to match the floor's angle. Specifically: Sets Mario's vertical position to be at `m.floorHeight` plus any active character animation offset and adjusts Mario's `throwMatrix` so that his body appears flush with the floor
 function align_with_floor(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
 function analog_stick_held_back(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
 function anim_and_audio_for_heavy_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
 function anim_and_audio_for_hold_walk(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
 function anim_and_audio_for_walk(m)
     -- ...
 end
@@ -5471,11 +5573,13 @@ 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
 function apply_landing_accel(m, frictionFactor)
     -- ...
 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
 function apply_slope_accel(m)
     -- ...
 end
@@ -5483,12 +5587,14 @@ 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
 function apply_slope_decel(m, decelCoef)
     -- ...
 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
 function begin_braking_action(m)
     -- ...
 end
@@ -5498,23 +5604,27 @@ end
 --- @param action integer
 --- @param actionArg integer
 --- @return integer
+--- Sets Mario's facing yaw to his intended yaw, applies a specified forward velocity, and transitions to the given action (e.g., `ACT_WALKING`).
 function begin_walking_action(m, forwardVel, action, actionArg)
     -- ...
 end
 
 --- @param m MarioState
 --- @return integer
+--- Performs common checks when Mario is in a moving state, transitions to water plunge if underwater, handles squished or shockwave bounce scenarios, and checks for death conditions
 function check_common_moving_cancels(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
 function check_ground_dive_or_punch(m)
     -- ...
 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
 function check_ledge_climb_down(m)
     -- ...
 end
@@ -5525,6 +5635,7 @@ end
 --- @param arg3 integer
 --- @param arg4 integer
 --- @return integer
+--- Handles knockback on the ground (getting hit while on the ground) with shared logic for multiple knockback states. Applies deceleration or minimal momentum, chooses appropriate landing action if Mario leaves the ground, and handles death transitions if Mario's health is depleted
 function common_ground_knockback_action(m, animation, arg2, arg3, arg4)
     -- ...
 end
@@ -5533,6 +5644,7 @@ end
 --- @param animation integer
 --- @param airAction integer
 --- @return integer
+--- Applies movement upon landing from a jump or fall. Adjusts velocity based on slope or friction, checks for transitions like sliding or hitting a wall, handles small dust particles if moving fast
 function common_landing_action(m, animation, airAction)
     -- ...
 end
@@ -5541,6 +5653,7 @@ end
 --- @param endAction integer
 --- @param airAction integer
 --- @param animation integer
+--- Applies shared logic for sliding-related actions while playing sliding sounds, managing ground steps (falling off edges, hitting walls), updates animation
 function common_slide_action(m, endAction, airAction, animation)
     -- ...
 end
@@ -5557,6 +5670,7 @@ end
 
 --- @param m MarioState
 --- @return integer
+--- Executes Mario's current moving actions by: checking common cancellations (e.g., water plunge, squish, death), handling quicksand updates, and switching to the correct sub-action handler based on `m.action`
 function mario_execute_moving_action(m)
     -- ...
 end
@@ -5564,12 +5678,14 @@ 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
 function play_step_sound(m, frame1, frame2)
     -- ...
 end
 
 --- @param m MarioState
 --- @param startPos Vec3f
+--- When Mario hits a wall during movement, decides whether he's pushing against the wall or sidling along it. Plays pushing animations and sounds if he's head-on, sidles along the wall if he's more angled
 function push_or_sidle_wall(m, startPos)
     -- ...
 end
@@ -5588,12 +5704,14 @@ end
 --- @param action integer
 --- @param actionArg integer
 --- @return integer
+--- Determines the proper triple jump action based on Mario's forward velocity and the Wing Cap flag: Normal triple jump, flying triple jump, or just a single jump if not enough speed
 function set_triple_jump_action(m, action, actionArg)
     -- ...
 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.
 function should_begin_sliding(m)
     -- ...
 end
@@ -5601,6 +5719,7 @@ end
 --- @param m MarioState
 --- @param fastAction integer
 --- @param slowAction integer
+--- Handles the scenario where Mario slides into a wall. If Mario is moving fast, reflects his velocity and transitions to a fast knockback, Otherwise, stops his forward velocity and sets a slower knockback
 function slide_bonk(m, fastAction, slowAction)
     -- ...
 end
@@ -5610,40 +5729,47 @@ 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
 function stomach_slide_action(m, stopAction, airAction, animation)
     -- ...
 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
 function tilt_body_butt_slide(m)
     -- ...
 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
 function tilt_body_ground_shell(m, startYaw)
     -- ...
 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
 function tilt_body_running(m)
     -- ...
 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
 function tilt_body_walking(m, startYaw)
     -- ...
 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
 function update_decelerating_speed(m)
     -- ...
 end
 
 --- @param m MarioState
+--- Controls Mario's speed when riding a Koopa Shell on the ground.
 function update_shell_speed(m)
     -- ...
 end
@@ -5651,6 +5777,7 @@ 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
 function update_sliding(m, stopSpeed)
     -- ...
 end
@@ -5658,11 +5785,13 @@ 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
 function update_sliding_angle(m, accel, lossFactor)
     -- ...
 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
 function update_walking_speed(m)
     -- ...
 end
@@ -8951,7 +9080,6 @@ function get_surface_from_wcd_index(wcd, index)
 end
 
 --- @return Surface
---- Finds a potential ceiling at the given `x`, `y`, and `z` values
 function get_water_surface_pseudo_floor()
     -- ...
 end

docs/lua/functions-6.md

@@ -5,6 +5,320 @@
 [< prev](functions-5.md) | [1](functions.md) | [2](functions-2.md) | [3](functions-3.md) | [4](functions-4.md) | [5](functions-5.md) | 6]
 
 
+---
+# functions from smlua_math_utils.h
+
+<br />
+
+
+## [clamp](#clamp)
+
+### Description
+Clamps a signed 32-bit integer `a` between bounds `b` (minimum) and `c` (maximum)
+
+### Lua Example
+`local integerValue = clamp(a, b, c)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| a | `integer` |
+| b | `integer` |
+| c | `integer` |
+
+### Returns
+- `integer`
+
+### C Prototype
+`s32 clamp(s32 a, s32 b, s32 c);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [clampf](#clampf)
+
+### Description
+Clamps a floating-point number `a` between bounds `b` (minimum) and `c` (maximum)
+
+### Lua Example
+`local numberValue = clampf(a, b, c)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| a | `number` |
+| b | `number` |
+| c | `number` |
+
+### Returns
+- `number`
+
+### C Prototype
+`f32 clampf(f32 a, f32 b, f32 c);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [degrees_to_sm64](#degrees_to_sm64)
+
+### Description
+Converts an angle from degrees to SM64 format
+
+### Lua Example
+`local integerValue = degrees_to_sm64(degreesAngle)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| degreesAngle | `number` |
+
+### Returns
+- `integer`
+
+### C Prototype
+`s16 degrees_to_sm64(f32 degreesAngle);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [hypotf](#hypotf)
+
+### Description
+Computes the hypotenuse of a right triangle given sides `a` and `b` using the Pythagorean theorem
+
+### Lua Example
+`local numberValue = hypotf(a, b)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| a | `number` |
+| b | `number` |
+
+### Returns
+- `number`
+
+### C Prototype
+`f32 hypotf(f32 a, f32 b);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [max](#max)
+
+### Description
+Finds the maximum of two signed 32-bit integers
+
+### Lua Example
+`local integerValue = max(a, b)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| a | `integer` |
+| b | `integer` |
+
+### Returns
+- `integer`
+
+### C Prototype
+`s32 max(s32 a, s32 b);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [maxf](#maxf)
+
+### Description
+Finds the maximum of two floating-point numbers
+
+### Lua Example
+`local numberValue = maxf(a, b)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| a | `number` |
+| b | `number` |
+
+### Returns
+- `number`
+
+### C Prototype
+`f32 maxf(f32 a, f32 b);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [min](#min)
+
+### Description
+Finds the minimum of two signed 32-bit integers
+
+### Lua Example
+`local integerValue = min(a, b)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| a | `integer` |
+| b | `integer` |
+
+### Returns
+- `integer`
+
+### C Prototype
+`s32 min(s32 a, s32 b);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [minf](#minf)
+
+### Description
+Finds the minimum of two floating-point numbers
+
+### Lua Example
+`local numberValue = minf(a, b)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| a | `number` |
+| b | `number` |
+
+### Returns
+- `number`
+
+### C Prototype
+`f32 minf(f32 a, f32 b);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [radians_to_sm64](#radians_to_sm64)
+
+### Description
+Converts an angle from radians to SM64 format
+
+### Lua Example
+`local integerValue = radians_to_sm64(radiansAngle)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| radiansAngle | `number` |
+
+### Returns
+- `integer`
+
+### C Prototype
+`s16 radians_to_sm64(f32 radiansAngle);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [sm64_to_degrees](#sm64_to_degrees)
+
+### Description
+Converts an angle from SM64 format to degrees
+
+### Lua Example
+`local numberValue = sm64_to_degrees(sm64Angle)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| sm64Angle | `integer` |
+
+### Returns
+- `number`
+
+### C Prototype
+`f32 sm64_to_degrees(s16 sm64Angle);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [sm64_to_radians](#sm64_to_radians)
+
+### Description
+Converts an angle from SM64 format to radians
+
+### Lua Example
+`local numberValue = sm64_to_radians(sm64Angle)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| sm64Angle | `integer` |
+
+### Returns
+- `number`
+
+### C Prototype
+`f32 sm64_to_radians(s16 sm64Angle);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [sqr](#sqr)
+
+### Description
+Computes the square of a signed 32-bit integer
+
+### Lua Example
+`local integerValue = sqr(x)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| x | `integer` |
+
+### Returns
+- `integer`
+
+### C Prototype
+`s32 sqr(s32 x);`
+
+[:arrow_up_small:](#)
+
+<br />
+
+## [sqrf](#sqrf)
+
+### Description
+Computes the square of a floating-point number
+
+### Lua Example
+`local numberValue = sqrf(x)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| x | `number` |
+
+### Returns
+- `number`
+
+### C Prototype
+`f32 sqrf(f32 x);`
+
+[:arrow_up_small:](#)
+
+<br />
+
 ---
 # functions from smlua_misc_utils.h
 

docs/lua/functions.md

@@ -944,58 +944,58 @@
 <br />
 
 - mario.h
-   - [adjust_sound_for_speed](functions-3.md#adjust_sound_for_speed)
+   - [adjust_sound_for_speed](functions-4.md#adjust_sound_for_speed)
-   - [check_common_action_exits](functions-3.md#check_common_action_exits)
+   - [check_common_action_exits](functions-4.md#check_common_action_exits)
-   - [check_common_hold_action_exits](functions-3.md#check_common_hold_action_exits)
+   - [check_common_hold_action_exits](functions-4.md#check_common_hold_action_exits)
-   - [drop_and_set_mario_action](functions-3.md#drop_and_set_mario_action)
+   - [drop_and_set_mario_action](functions-4.md#drop_and_set_mario_action)
-   - [execute_mario_action](functions-3.md#execute_mario_action)
+   - [execute_mario_action](functions-4.md#execute_mario_action)
-   - [find_floor_height_relative_polar](functions-3.md#find_floor_height_relative_polar)
+   - [find_floor_height_relative_polar](functions-4.md#find_floor_height_relative_polar)
-   - [find_floor_slope](functions-3.md#find_floor_slope)
+   - [find_floor_slope](functions-4.md#find_floor_slope)
-   - [find_mario_anim_flags_and_translation](functions-3.md#find_mario_anim_flags_and_translation)
+   - [find_mario_anim_flags_and_translation](functions-4.md#find_mario_anim_flags_and_translation)
-   - [force_idle_state](functions-3.md#force_idle_state)
+   - [force_idle_state](functions-4.md#force_idle_state)
-   - [hurt_and_set_mario_action](functions-3.md#hurt_and_set_mario_action)
+   - [hurt_and_set_mario_action](functions-4.md#hurt_and_set_mario_action)
-   - [init_single_mario](functions-3.md#init_single_mario)
+   - [init_single_mario](functions-4.md#init_single_mario)
-   - [is_anim_at_end](functions-3.md#is_anim_at_end)
+   - [is_anim_at_end](functions-4.md#is_anim_at_end)
-   - [is_anim_past_end](functions-3.md#is_anim_past_end)
+   - [is_anim_past_end](functions-4.md#is_anim_past_end)
-   - [is_anim_past_frame](functions-3.md#is_anim_past_frame)
+   - [is_anim_past_frame](functions-4.md#is_anim_past_frame)
-   - [mario_can_bubble](functions-3.md#mario_can_bubble)
+   - [mario_can_bubble](functions-4.md#mario_can_bubble)
-   - [mario_facing_downhill](functions-3.md#mario_facing_downhill)
+   - [mario_facing_downhill](functions-4.md#mario_facing_downhill)
-   - [mario_floor_is_slippery](functions-3.md#mario_floor_is_slippery)
+   - [mario_floor_is_slippery](functions-4.md#mario_floor_is_slippery)
-   - [mario_floor_is_slope](functions-3.md#mario_floor_is_slope)
+   - [mario_floor_is_slope](functions-4.md#mario_floor_is_slope)
-   - [mario_floor_is_steep](functions-3.md#mario_floor_is_steep)
+   - [mario_floor_is_steep](functions-4.md#mario_floor_is_steep)
-   - [mario_get_floor_class](functions-3.md#mario_get_floor_class)
+   - [mario_get_floor_class](functions-4.md#mario_get_floor_class)
-   - [mario_get_terrain_sound_addend](functions-3.md#mario_get_terrain_sound_addend)
+   - [mario_get_terrain_sound_addend](functions-4.md#mario_get_terrain_sound_addend)
-   - [mario_is_crouching](functions-3.md#mario_is_crouching)
+   - [mario_is_crouching](functions-4.md#mario_is_crouching)
-   - [mario_set_bubbled](functions-3.md#mario_set_bubbled)
+   - [mario_set_bubbled](functions-4.md#mario_set_bubbled)
-   - [mario_set_forward_vel](functions-3.md#mario_set_forward_vel)
+   - [mario_set_forward_vel](functions-4.md#mario_set_forward_vel)
-   - [mario_update_wall](functions-3.md#mario_update_wall)
+   - [mario_update_wall](functions-4.md#mario_update_wall)
-   - [play_mario_action_sound](functions-3.md#play_mario_action_sound)
+   - [play_mario_action_sound](functions-4.md#play_mario_action_sound)
-   - [play_mario_heavy_landing_sound](functions-3.md#play_mario_heavy_landing_sound)
+   - [play_mario_heavy_landing_sound](functions-4.md#play_mario_heavy_landing_sound)
-   - [play_mario_heavy_landing_sound_once](functions-3.md#play_mario_heavy_landing_sound_once)
+   - [play_mario_heavy_landing_sound_once](functions-4.md#play_mario_heavy_landing_sound_once)
-   - [play_mario_jump_sound](functions-3.md#play_mario_jump_sound)
+   - [play_mario_jump_sound](functions-4.md#play_mario_jump_sound)
-   - [play_mario_landing_sound](functions-3.md#play_mario_landing_sound)
+   - [play_mario_landing_sound](functions-4.md#play_mario_landing_sound)
-   - [play_mario_landing_sound_once](functions-3.md#play_mario_landing_sound_once)
+   - [play_mario_landing_sound_once](functions-4.md#play_mario_landing_sound_once)
-   - [play_mario_sound](functions-3.md#play_mario_sound)
+   - [play_mario_sound](functions-4.md#play_mario_sound)
-   - [play_sound_and_spawn_particles](functions-3.md#play_sound_and_spawn_particles)
+   - [play_sound_and_spawn_particles](functions-4.md#play_sound_and_spawn_particles)
-   - [play_sound_if_no_flag](functions-3.md#play_sound_if_no_flag)
+   - [play_sound_if_no_flag](functions-4.md#play_sound_if_no_flag)
-   - [resolve_and_return_wall_collisions](functions-3.md#resolve_and_return_wall_collisions)
+   - [resolve_and_return_wall_collisions](functions-4.md#resolve_and_return_wall_collisions)
-   - [resolve_and_return_wall_collisions_data](functions-3.md#resolve_and_return_wall_collisions_data)
+   - [resolve_and_return_wall_collisions_data](functions-4.md#resolve_and_return_wall_collisions_data)
-   - [return_mario_anim_y_translation](functions-3.md#return_mario_anim_y_translation)
+   - [return_mario_anim_y_translation](functions-4.md#return_mario_anim_y_translation)
-   - [set_anim_to_frame](functions-3.md#set_anim_to_frame)
+   - [set_anim_to_frame](functions-4.md#set_anim_to_frame)
-   - [set_character_anim_with_accel](functions-3.md#set_character_anim_with_accel)
+   - [set_character_anim_with_accel](functions-4.md#set_character_anim_with_accel)
-   - [set_character_animation](functions-3.md#set_character_animation)
+   - [set_character_animation](functions-4.md#set_character_animation)
-   - [set_jump_from_landing](functions-3.md#set_jump_from_landing)
+   - [set_jump_from_landing](functions-4.md#set_jump_from_landing)
-   - [set_jumping_action](functions-3.md#set_jumping_action)
+   - [set_jumping_action](functions-4.md#set_jumping_action)
-   - [set_mario_action](functions-3.md#set_mario_action)
+   - [set_mario_action](functions-4.md#set_mario_action)
-   - [set_mario_anim_with_accel](functions-3.md#set_mario_anim_with_accel)
+   - [set_mario_anim_with_accel](functions-4.md#set_mario_anim_with_accel)
-   - [set_mario_animation](functions-3.md#set_mario_animation)
+   - [set_mario_animation](functions-4.md#set_mario_animation)
-   - [set_mario_particle_flags](functions-3.md#set_mario_particle_flags)
+   - [set_mario_particle_flags](functions-4.md#set_mario_particle_flags)
-   - [set_mario_y_vel_based_on_fspeed](functions-3.md#set_mario_y_vel_based_on_fspeed)
+   - [set_mario_y_vel_based_on_fspeed](functions-4.md#set_mario_y_vel_based_on_fspeed)
-   - [set_steep_jump_action](functions-3.md#set_steep_jump_action)
+   - [set_steep_jump_action](functions-4.md#set_steep_jump_action)
-   - [set_water_plunge_action](functions-3.md#set_water_plunge_action)
+   - [set_water_plunge_action](functions-4.md#set_water_plunge_action)
-   - [transition_submerged_to_walking](functions-3.md#transition_submerged_to_walking)
+   - [transition_submerged_to_walking](functions-4.md#transition_submerged_to_walking)
-   - [update_mario_pos_for_anim](functions-3.md#update_mario_pos_for_anim)
+   - [update_mario_pos_for_anim](functions-4.md#update_mario_pos_for_anim)
-   - [update_mario_sound_and_camera](functions-3.md#update_mario_sound_and_camera)
+   - [update_mario_sound_and_camera](functions-4.md#update_mario_sound_and_camera)
 
 <br />
 
@@ -1289,52 +1289,52 @@
 <br />
 
 - obj_behaviors_2.c
-   - [approach_f32_ptr](functions-4.md#approach_f32_ptr)
+   - [approach_f32_ptr](functions-5.md#approach_f32_ptr)
-   - [cur_obj_init_anim_and_check_if_end](functions-4.md#cur_obj_init_anim_and_check_if_end)
+   - [cur_obj_init_anim_and_check_if_end](functions-5.md#cur_obj_init_anim_and_check_if_end)
-   - [cur_obj_init_anim_check_frame](functions-4.md#cur_obj_init_anim_check_frame)
+   - [cur_obj_init_anim_check_frame](functions-5.md#cur_obj_init_anim_check_frame)
-   - [cur_obj_init_anim_extend](functions-4.md#cur_obj_init_anim_extend)
+   - [cur_obj_init_anim_extend](functions-5.md#cur_obj_init_anim_extend)
-   - [cur_obj_play_sound_at_anim_range](functions-4.md#cur_obj_play_sound_at_anim_range)
+   - [cur_obj_play_sound_at_anim_range](functions-5.md#cur_obj_play_sound_at_anim_range)
-   - [cur_obj_set_anim_if_at_end](functions-4.md#cur_obj_set_anim_if_at_end)
+   - [cur_obj_set_anim_if_at_end](functions-5.md#cur_obj_set_anim_if_at_end)
-   - [cur_obj_spin_all_dimensions](functions-4.md#cur_obj_spin_all_dimensions)
+   - [cur_obj_spin_all_dimensions](functions-5.md#cur_obj_spin_all_dimensions)
-   - [obj_act_knockback](functions-4.md#obj_act_knockback)
+   - [obj_act_knockback](functions-5.md#obj_act_knockback)
-   - [obj_act_squished](functions-4.md#obj_act_squished)
+   - [obj_act_squished](functions-5.md#obj_act_squished)
-   - [obj_bounce_off_walls_edges_objects](functions-4.md#obj_bounce_off_walls_edges_objects)
+   - [obj_bounce_off_walls_edges_objects](functions-5.md#obj_bounce_off_walls_edges_objects)
-   - [obj_check_attacks](functions-4.md#obj_check_attacks)
+   - [obj_check_attacks](functions-5.md#obj_check_attacks)
-   - [obj_compute_vel_from_move_pitch](functions-4.md#obj_compute_vel_from_move_pitch)
+   - [obj_compute_vel_from_move_pitch](functions-5.md#obj_compute_vel_from_move_pitch)
-   - [obj_die_if_above_lava_and_health_non_positive](functions-4.md#obj_die_if_above_lava_and_health_non_positive)
+   - [obj_die_if_above_lava_and_health_non_positive](functions-5.md#obj_die_if_above_lava_and_health_non_positive)
-   - [obj_die_if_health_non_positive](functions-4.md#obj_die_if_health_non_positive)
+   - [obj_die_if_health_non_positive](functions-5.md#obj_die_if_health_non_positive)
-   - [obj_face_pitch_approach](functions-4.md#obj_face_pitch_approach)
+   - [obj_face_pitch_approach](functions-5.md#obj_face_pitch_approach)
-   - [obj_face_roll_approach](functions-4.md#obj_face_roll_approach)
+   - [obj_face_roll_approach](functions-5.md#obj_face_roll_approach)
-   - [obj_face_yaw_approach](functions-4.md#obj_face_yaw_approach)
+   - [obj_face_yaw_approach](functions-5.md#obj_face_yaw_approach)
-   - [obj_forward_vel_approach](functions-4.md#obj_forward_vel_approach)
+   - [obj_forward_vel_approach](functions-5.md#obj_forward_vel_approach)
-   - [obj_get_pitch_from_vel](functions-4.md#obj_get_pitch_from_vel)
+   - [obj_get_pitch_from_vel](functions-5.md#obj_get_pitch_from_vel)
-   - [obj_get_pitch_to_home](functions-4.md#obj_get_pitch_to_home)
+   - [obj_get_pitch_to_home](functions-5.md#obj_get_pitch_to_home)
-   - [obj_grow_then_shrink](functions-4.md#obj_grow_then_shrink)
+   - [obj_grow_then_shrink](functions-5.md#obj_grow_then_shrink)
-   - [obj_handle_attacks](functions-4.md#obj_handle_attacks)
+   - [obj_handle_attacks](functions-5.md#obj_handle_attacks)
-   - [obj_is_near_to_and_facing_mario](functions-4.md#obj_is_near_to_and_facing_mario)
+   - [obj_is_near_to_and_facing_mario](functions-5.md#obj_is_near_to_and_facing_mario)
-   - [obj_is_rendering_enabled](functions-4.md#obj_is_rendering_enabled)
+   - [obj_is_rendering_enabled](functions-5.md#obj_is_rendering_enabled)
-   - [obj_move_for_one_second](functions-4.md#obj_move_for_one_second)
+   - [obj_move_for_one_second](functions-5.md#obj_move_for_one_second)
-   - [obj_move_pitch_approach](functions-4.md#obj_move_pitch_approach)
+   - [obj_move_pitch_approach](functions-5.md#obj_move_pitch_approach)
-   - [obj_random_fixed_turn](functions-4.md#obj_random_fixed_turn)
+   - [obj_random_fixed_turn](functions-5.md#obj_random_fixed_turn)
-   - [obj_resolve_collisions_and_turn](functions-4.md#obj_resolve_collisions_and_turn)
+   - [obj_resolve_collisions_and_turn](functions-5.md#obj_resolve_collisions_and_turn)
-   - [obj_resolve_object_collisions](functions-4.md#obj_resolve_object_collisions)
+   - [obj_resolve_object_collisions](functions-5.md#obj_resolve_object_collisions)
-   - [obj_roll_to_match_yaw_turn](functions-4.md#obj_roll_to_match_yaw_turn)
+   - [obj_roll_to_match_yaw_turn](functions-5.md#obj_roll_to_match_yaw_turn)
-   - [obj_rotate_yaw_and_bounce_off_walls](functions-4.md#obj_rotate_yaw_and_bounce_off_walls)
+   - [obj_rotate_yaw_and_bounce_off_walls](functions-5.md#obj_rotate_yaw_and_bounce_off_walls)
-   - [obj_set_dist_from_home](functions-4.md#obj_set_dist_from_home)
+   - [obj_set_dist_from_home](functions-5.md#obj_set_dist_from_home)
-   - [obj_set_knockback_action](functions-4.md#obj_set_knockback_action)
+   - [obj_set_knockback_action](functions-5.md#obj_set_knockback_action)
-   - [obj_set_squished_action](functions-4.md#obj_set_squished_action)
+   - [obj_set_squished_action](functions-5.md#obj_set_squished_action)
-   - [obj_smooth_turn](functions-4.md#obj_smooth_turn)
+   - [obj_smooth_turn](functions-5.md#obj_smooth_turn)
-   - [obj_spit_fire](functions-4.md#obj_spit_fire)
+   - [obj_spit_fire](functions-5.md#obj_spit_fire)
-   - [obj_turn_pitch_toward_mario](functions-4.md#obj_turn_pitch_toward_mario)
+   - [obj_turn_pitch_toward_mario](functions-5.md#obj_turn_pitch_toward_mario)
-   - [obj_unused_die](functions-4.md#obj_unused_die)
+   - [obj_unused_die](functions-5.md#obj_unused_die)
-   - [obj_update_blinking](functions-4.md#obj_update_blinking)
+   - [obj_update_blinking](functions-5.md#obj_update_blinking)
-   - [obj_update_standard_actions](functions-4.md#obj_update_standard_actions)
+   - [obj_update_standard_actions](functions-5.md#obj_update_standard_actions)
-   - [obj_y_vel_approach](functions-4.md#obj_y_vel_approach)
+   - [obj_y_vel_approach](functions-5.md#obj_y_vel_approach)
-   - [oscillate_toward](functions-4.md#oscillate_toward)
+   - [oscillate_toward](functions-5.md#oscillate_toward)
-   - [platform_on_track_update_pos_or_spawn_ball](functions-4.md#platform_on_track_update_pos_or_spawn_ball)
+   - [platform_on_track_update_pos_or_spawn_ball](functions-5.md#platform_on_track_update_pos_or_spawn_ball)
-   - [random_linear_offset](functions-4.md#random_linear_offset)
+   - [random_linear_offset](functions-5.md#random_linear_offset)
-   - [random_mod_offset](functions-4.md#random_mod_offset)
+   - [random_mod_offset](functions-5.md#random_mod_offset)
-   - [treat_far_home_as_mario](functions-4.md#treat_far_home_as_mario)
+   - [treat_far_home_as_mario](functions-5.md#treat_far_home_as_mario)
 
 <br />
 
@@ -1736,19 +1736,19 @@
 <br />
 
 - smlua_math_utils.h
-   - [clamp](functions-5.md#clamp)
+   - [clamp](functions-6.md#clamp)
-   - [clampf](functions-5.md#clampf)
+   - [clampf](functions-6.md#clampf)
-   - [degrees_to_sm64](functions-5.md#degrees_to_sm64)
+   - [degrees_to_sm64](functions-6.md#degrees_to_sm64)
-   - [hypotf](functions-5.md#hypotf)
+   - [hypotf](functions-6.md#hypotf)
-   - [max](functions-5.md#max)
+   - [max](functions-6.md#max)
-   - [maxf](functions-5.md#maxf)
+   - [maxf](functions-6.md#maxf)
-   - [min](functions-5.md#min)
+   - [min](functions-6.md#min)
-   - [minf](functions-5.md#minf)
+   - [minf](functions-6.md#minf)
-   - [radians_to_sm64](functions-5.md#radians_to_sm64)
+   - [radians_to_sm64](functions-6.md#radians_to_sm64)
-   - [sm64_to_degrees](functions-5.md#sm64_to_degrees)
+   - [sm64_to_degrees](functions-6.md#sm64_to_degrees)
-   - [sm64_to_radians](functions-5.md#sm64_to_radians)
+   - [sm64_to_radians](functions-6.md#sm64_to_radians)
-   - [sqr](functions-5.md#sqr)
+   - [sqr](functions-6.md#sqr)
-   - [sqrf](functions-5.md#sqrf)
+   - [sqrf](functions-6.md#sqrf)
 
 <br />
 

src/game/mario.h

@@ -9,64 +9,295 @@
 extern u16 gLocalBubbleCounter;
 struct WallCollisionData;
 
+/* |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
+|descriptionEnd| */
 s32 is_anim_at_end(struct MarioState *m);
+
+/* |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
+|descriptionEnd| */
 s32 is_anim_past_end(struct MarioState *m);
+
+/* |description|
+Sets Mario's current animation to `targetAnimID` at a default acceleration (no speed change)
+|descriptionEnd| */
 s16 set_mario_animation(struct MarioState *m, s32 targetAnimID);
+
+/* |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
+|descriptionEnd| */
 s16 set_mario_anim_with_accel(struct MarioState *m, s32 targetAnimID, s32 accel);
 
+/* |description|
+Sets the character-specific animation at its default rate (no acceleration)
+|descriptionEnd| */
 s16 set_character_animation(struct MarioState *m, s32 targetAnimID);
+
+/* |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)
+|descriptionEnd| */
 s16 set_character_anim_with_accel(struct MarioState *m, s32 targetAnimID, s32 accel);
 
+/* |description|
+Sets the current animation frame to a specific `animFrame`
+|descriptionEnd| */
 void set_anim_to_frame(struct MarioState *m, s16 animFrame);
+
+/* |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
+|descriptionEnd| */
 s32 is_anim_past_frame(struct MarioState *m, s16 animFrame);
+
+/* |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
+|descriptionEnd| */
 s16 find_mario_anim_flags_and_translation(struct Object *o, s32 yaw, Vec3s translation);
+
+/* |description|
+Applies the translation from Mario's current animation to his world position. Considers animation flags (horizontal/vertical translation)
+|descriptionEnd| */
 void update_mario_pos_for_anim(struct MarioState *m);
+
+/* |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)
+|descriptionEnd| */
 s16 return_mario_anim_y_translation(struct MarioState *m);
+
+/* |description|
+Plays a sound if Mario does not currently have a specific flag set. Once played, the flag is set to prevent immediate repeats
+|descriptionEnd| */
 void play_sound_if_no_flag(struct MarioState *m, u32 soundBits, u32 flags);
+
+/* |description|
+Plays Mario’s jump sound if it hasn't been played yet since the last action change. This helps avoid overlapping jump voice lines on repeated jumps
+|descriptionEnd| */
 void play_mario_jump_sound(struct MarioState *m);
+
+/* |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
+|descriptionEnd| */
 void adjust_sound_for_speed(struct MarioState *m);
+
+/* |description|
+Plays the specified sound effect and spawns surface-appropriate particles (e.g., water splash, snow, sand). Checks if Mario is metal to adjust audio accordingly
+|descriptionEnd| */
 void play_sound_and_spawn_particles(struct MarioState *m, u32 soundBits, u32 waveParticleType);
+
+/* |description|
+Plays an action sound once per action, optionally spawning wave or dust particles depending on the surface. This sets the `MARIO_ACTION_SOUND_PLAYED` flag to prevent repeats
+|descriptionEnd| */
 void play_mario_action_sound(struct MarioState *m, u32 soundBits, u32 waveParticleType);
+
+/* |description|
+Plays a normal landing sound (or metal landing sound if Mario is metal) and spawns appropriate particle effects (water splash, dust, etc.)
+|descriptionEnd| */
 void play_mario_landing_sound(struct MarioState *m, u32 soundBits);
+
+/* |description|
+A variant of `play_mario_landing_sound` that ensures the sound is only played once per action. Uses `play_mario_action_sound` internally
+|descriptionEnd| */
 void play_mario_landing_sound_once(struct MarioState *m, u32 soundBits);
+
+/* |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
+|descriptionEnd| */
 void play_mario_heavy_landing_sound(struct MarioState *m, u32 soundBits);
+
+/* |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
+|descriptionEnd| */
 void play_mario_heavy_landing_sound_once(struct MarioState *m, u32 soundBits);
+
+/* |description|
+Plays a given action sound (like a jump or landing) and also a Mario voice line if certain conditions are met. It manages flags to avoid repeated sounds
+|descriptionEnd| */
 void play_mario_sound(struct MarioState *m, s32 primarySoundBits, s32 scondarySoundBits);
+
+/* |description|
+Returns true if Mario is in any of the crouching or crawling states, checking his current action
+|descriptionEnd| */
 bool mario_is_crouching(struct MarioState *m);
+
+/* |description|
+Checks whether Mario can become bubbled under certain game conditions (multiplayer bubble mechanic). Returns false if already bubbled or if not allowed by settings
+|descriptionEnd| */
 bool mario_can_bubble(struct MarioState* m);
+
+/* |description|
+Transitions Mario into a bubbled state (if available in multiplayer), decrementing lives and preventing normal movement
+|descriptionEnd| */
 void mario_set_bubbled(struct MarioState* m);
+
+/* |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.)
+|descriptionEnd| */
 void mario_set_forward_vel(struct MarioState *m, f32 speed);
+
+/* |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
+|descriptionEnd| */
 s32 mario_get_floor_class(struct MarioState *m);
+
+/* |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
+|descriptionEnd| */
 u32 mario_get_terrain_sound_addend(struct MarioState *m);
+
+/* |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
+|descriptionEnd| */
 struct Surface *resolve_and_return_wall_collisions(Vec3f pos, f32 offset, f32 radius);
+
+/* |description|
+Similar to `resolve_and_return_wall_collisions` but also returns detailed collision data (`WallCollisionData`). This can handle multiple walls and store them for further checks
+|descriptionEnd| */
 void resolve_and_return_wall_collisions_data(Vec3f pos, f32 offset, f32 radius, struct WallCollisionData* collisionData);
+
 f32 vec3f_find_ceil(Vec3f pos, f32 height, struct Surface **ceil);
 f32 vec3f_mario_ceil(Vec3f pos, f32 height, struct Surface **ceil);
+
+/* |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
+|descriptionEnd| */
 s32 mario_facing_downhill(struct MarioState *m, s32 turnYaw);
+
+/* |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
+|descriptionEnd| */
 u32 mario_floor_is_slippery(struct MarioState *m);
+
+/* |description|
+Checks whether Mario's floor is a slope, i.e., not flat but not necessarily steep. This depends on the floor's surface class and angle
+|descriptionEnd| */
 s32 mario_floor_is_slope(struct MarioState *m);
+
+/* |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
+|descriptionEnd| */
 s32 mario_floor_is_steep(struct MarioState *m);
+
+/* |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
+|descriptionEnd| */
 f32 find_floor_height_relative_polar(struct MarioState *m, s16 angleFromMario, f32 distFromMario);
+
+/* |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
+|descriptionEnd| */
 s16 find_floor_slope(struct MarioState *m, s16 yawOffset);
+
+/* |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
+|descriptionEnd| */
 void update_mario_sound_and_camera(struct MarioState *m);
+
+/* |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
+|descriptionEnd| */
 void set_steep_jump_action(struct MarioState *m);
+
+/* |description|
+Adjusts Mario's vertical velocity (`m.vel.y`) based on his forward speed. This function also accounts for conditions like quicksand to halve velocity
+|descriptionEnd| */
 void set_mario_y_vel_based_on_fspeed(struct MarioState *m, f32 initialVelY, f32 multiplier);
+
+/* |description|
+Sets Mario's action to the specified `action` and `actionArg`, routing through group-specific transition functions (e.g., airborne actions). Resets sound flags and updates internal timers
+|descriptionEnd| */
 u32 set_mario_action(struct MarioState *m, u32 action, u32 actionArg);
+
+/* |description|
+When Mario lands on the ground, decides whether to jump again (single, double, triple) or enter a steep jump if the floor is very steep. Handles quicksand logic as well
+|descriptionEnd| */
 s32 set_jump_from_landing(struct MarioState *m);
+
+/* |description|
+Sets Mario to a jumping action (regular, double, triple, or steep jump) if conditions allow it. If the floor is too steep or if in quicksand, it changes the action accordingly
+|descriptionEnd| */
 s32 set_jumping_action(struct MarioState *m, u32 action, u32 actionArg);
+
+/* |description|
+Drops any currently held object and sets Mario to a new action. This function is typically used when Mario transitions to states where he cannot hold objects
+|descriptionEnd| */
 s32 drop_and_set_mario_action(struct MarioState *m, u32 action, u32 actionArg);
+
+/* |description|
+Increments Mario's `hurtCounter` and immediately sets a new action. Often used when Mario takes damage and transitions into a knockback or stunned action.
+|descriptionEnd| */
 s32 hurt_and_set_mario_action(struct MarioState *m, u32 action, u32 actionArg, s16 hurtCounter);
+
+/* |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
+|descriptionEnd| */
 s32 check_common_action_exits(struct MarioState *m);
+
+/* |description|
+Checks for inputs that cause common hold-action transitions (hold jump, hold freefall, hold walking, hold sliding)
+|descriptionEnd| */
 s32 check_common_hold_action_exits(struct MarioState *m);
+
+/* |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
+|descriptionEnd| */
 s32 transition_submerged_to_walking(struct MarioState *m);
+
+/* |description|
+Transitions Mario into a "water plunge" action, used when he enters water from above. Adjusts position, velocity, and camera mode
+|descriptionEnd| */
 s32 set_water_plunge_action(struct MarioState *m);
+
+/* |description|
+Main driver for Mario's behavior. Executes the current action group (stationary, moving, airborne, etc.) in a loop until no further action changes are necessary
+|descriptionEnd| */
 s32 execute_mario_action(UNUSED struct Object *o);
+
+/* |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)
+|descriptionEnd| */
 s32 force_idle_state(struct MarioState* m);
+
+/* |description|
+Initializes the fields of a single `MarioState` structure when the player spawns or respawns. Sets starting position, velocity, action, and various internal flags
+|descriptionEnd| */
 void init_single_mario(struct MarioState* m);
+
 void init_mario(void);
 void init_mario_single_from_save_file(struct MarioState* m, u16 index);
 void init_mario_from_save_file(void);
+
+/* |description|
+Sets Mario's particle flags to spawn various visual effects (dust, water splashes, etc.), with an option to clear or set new flags
+|descriptionEnd| */
 void set_mario_particle_flags(struct MarioState* m, u32 flags, u8 clear);
+
+/* |description|
+Updates Mario's wall information based on wall collisions (`WallCollisionData`). Chooses the most relevant wall depending on the level’s collision fix settings
+|descriptionEnd| */
 void mario_update_wall(struct MarioState* m, struct WallCollisionData* wcd);
 
 #endif // MARIO_H

src/game/mario_actions_airborne.c

@@ -22,6 +22,10 @@
 #include "pc/lua/smlua.h"
 #include "hardcoded.h"
 
+/* |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`
+|descriptionEnd| */
 void play_flip_sounds(struct MarioState *m, s16 frame1, s16 frame2, s16 frame3) {
     if (!m) { return; }
     s32 animFrame = m->marioObj->header.gfx.animInfo.animFrame;
@@ -30,6 +34,10 @@ void play_flip_sounds(struct MarioState *m, s16 frame1, s16 frame2, s16 frame3)
     }
 }
 
+/* |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
+|descriptionEnd| */
 void play_far_fall_sound(struct MarioState *m) {
     if (!m) { return; }
     u32 action = m->action;
@@ -43,6 +51,10 @@ void play_far_fall_sound(struct MarioState *m) {
 }
 
 #ifndef VERSION_JP
+/* |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
+|descriptionEnd| */
 void play_knockback_sound(struct MarioState *m) {
     if (!m) { return; }
     if (m->actionArg == 0 && (m->forwardVel <= -28.0f || m->forwardVel >= 28.0f)) {
@@ -53,6 +65,11 @@ void play_knockback_sound(struct MarioState *m) {
 }
 #endif
 
+/* |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
+|descriptionEnd| */
 s32 lava_boost_on_wall(struct MarioState *m) {
     if (!m) { return 0; }
     bool allow = true;
@@ -73,6 +90,12 @@ s32 lava_boost_on_wall(struct MarioState *m) {
     return drop_and_set_mario_action(m, ACT_LAVA_BOOST, 1);
 }
 
+/* |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
+|descriptionEnd| */
 s32 check_fall_damage(struct MarioState *m, u32 hardFallAction) {
     if (!m) { return 0; }
     
@@ -115,6 +138,10 @@ s32 check_fall_damage(struct MarioState *m, u32 hardFallAction) {
     return FALSE;
 }
 
+/* |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)
+|descriptionEnd| */
 s32 check_kick_or_dive_in_air(struct MarioState *m) {
     if (!m) { return 0; }
     if (m->input & INPUT_B_PRESSED) {
@@ -123,6 +150,11 @@ s32 check_kick_or_dive_in_air(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 s32 should_get_stuck_in_ground(struct MarioState *m) {
     if (!m) { return 0; }
     if (m->floor == NULL) { return FALSE; }
@@ -142,6 +174,11 @@ s32 should_get_stuck_in_ground(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 s32 check_fall_damage_or_get_stuck(struct MarioState *m, u32 hardFallAction) {
     if (!m) { return 0; }
     if (should_get_stuck_in_ground(m)) {
@@ -160,6 +197,10 @@ s32 check_fall_damage_or_get_stuck(struct MarioState *m, u32 hardFallAction) {
     return check_fall_damage(m, hardFallAction);
 }
 
+/* |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
+|descriptionEnd| */
 s32 check_horizontal_wind(struct MarioState *m) {
     if (!m) { return 0; }
     struct Surface *floor;
@@ -198,6 +239,10 @@ s32 check_horizontal_wind(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 void update_air_with_turn(struct MarioState *m) {
     if (!m) { return; }
     f32 dragThreshold;
@@ -229,6 +274,10 @@ void update_air_with_turn(struct MarioState *m) {
     }
 }
 
+/* |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
+|descriptionEnd| */
 void update_air_without_turn(struct MarioState *m) {
     if (!m) { return; }
     f32 sidewaysSpeed = 0.0f;
@@ -267,6 +316,11 @@ void update_air_without_turn(struct MarioState *m) {
     }
 }
 
+
+/* |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`
+|descriptionEnd| */
 void update_lava_boost_or_twirling(struct MarioState *m) {
     if (!m) { return; }
     s16 intendedDYaw;
@@ -293,6 +347,10 @@ void update_lava_boost_or_twirling(struct MarioState *m) {
     m->vel[2] = m->slideVelZ = m->forwardVel * coss(m->faceAngle[1]);
 }
 
+/* |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
+|descriptionEnd| */
 void update_flying_yaw(struct MarioState *m) {
     if (!m) { return; }
     s16 targetYawVel = -(s16)(m->controller->stickX * (m->forwardVel / 4.0f));
@@ -323,6 +381,10 @@ void update_flying_yaw(struct MarioState *m) {
     m->faceAngle[2] = 20 * -m->angleVel[1];
 }
 
+/* |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
+|descriptionEnd| */
 void update_flying_pitch(struct MarioState *m) {
     if (!m) { return; }
     s16 targetPitchVel = -(s16)(m->controller->stickY * (m->forwardVel / 5.0f));
@@ -350,6 +412,10 @@ void update_flying_pitch(struct MarioState *m) {
     }
 }
 
+/* |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
+|descriptionEnd| */
 void update_flying(struct MarioState *m) {
     if (!m) { return; }
     UNUSED u32 unused;
@@ -389,6 +455,11 @@ void update_flying(struct MarioState *m) {
     m->slideVelZ = m->vel[2];
 }
 
+/* |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
+|descriptionEnd| */
 u32 common_air_action_step(struct MarioState *m, u32 landAction, s32 animation, u32 stepArg) {
     if (!m) { return 0; }
     u32 stepResult;
@@ -1151,8 +1222,11 @@ s32 act_crazy_box_bounce(struct MarioState *m) {
     return FALSE;
 }
 
-u32 common_air_knockback_step(struct MarioState *m, u32 landAction, u32 hardFallAction, s32 animation,
+/* |description|
-                              f32 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
+|descriptionEnd| */
+u32 common_air_knockback_step(struct MarioState *m, u32 landAction, u32 hardFallAction, s32 animation, f32 speed) {
     if (!m) { return 0; }
     u32 stepResult;
 
@@ -1210,6 +1284,10 @@ u32 common_air_knockback_step(struct MarioState *m, u32 landAction, u32 hardFall
     return stepResult;
 }
 
+/* |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`
+|descriptionEnd| */
 s32 check_wall_kick(struct MarioState *m) {
     if (!m) { return 0; }
     if ((m->input & INPUT_A_PRESSED) && m->wallKickTimer != 0 && m->prevAction == ACT_AIR_HIT_WALL) {
@@ -2206,6 +2284,11 @@ s32 act_special_triple_jump(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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`
+|descriptionEnd| */
 s32 check_common_airborne_cancels(struct MarioState *m) {
     if (!m) { return 0; }
     if (m->pos[1] < m->waterLevel - 100) {
@@ -2224,6 +2307,10 @@ s32 check_common_airborne_cancels(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 s32 mario_execute_airborne_action(struct MarioState *m) {
     if (!m) { return FALSE; }
     u32 cancel;

src/game/mario_actions_automatic.c

@@ -33,6 +33,10 @@
 #define HANG_HIT_CEIL_OR_OOB 1
 #define HANG_LEFT_CEIL       2
 
+/* |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
+|descriptionEnd| */
 void add_tree_leaf_particles(struct MarioState *m) {
     if (!m) { return; }
     f32 leafHeight;
@@ -50,6 +54,9 @@ void add_tree_leaf_particles(struct MarioState *m) {
     }
 }
 
+/* |description|
+Plays the appropriate climbing sound effect depending on whether Mario is on a tree or a pole. If `b == 1`, it plays the "climbing up" sound; otherwise, it plays the "sliding down" sound
+|descriptionEnd| */
 void play_climbing_sounds(struct MarioState *m, s32 b) {
     if (!m) { return; }
     s32 isOnTree = (m->usedObj != NULL && m->usedObj->behavior == segmented_to_virtual(smlua_override_behavior(bhvTree)));
@@ -65,6 +72,10 @@ void play_climbing_sounds(struct MarioState *m, s32 b) {
     }
 }
 
+/* |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
+|descriptionEnd| */
 s32 set_pole_position(struct MarioState *m, f32 offsetY) {
     if (!m) { return 0; }
     if (m->usedObj == NULL) { m->usedObj = cur_obj_find_nearest_pole(); }
@@ -330,6 +341,9 @@ s32 act_top_of_pole(struct MarioState *m) {
     return FALSE;
 }
 
+/* |description|
+Performs a single step of movement while Mario is hanging from a ceiling. It handles wall collisions and checks the floor and ceiling to determine if Mario remains hanging, leaves the ceiling, or hits it
+|descriptionEnd| */
 s32 perform_hanging_step(struct MarioState *m, Vec3f nextPos) {
     if (!m) { return 0; }
     UNUSED s32 unused;
@@ -383,6 +397,9 @@ s32 perform_hanging_step(struct MarioState *m, Vec3f nextPos) {
     return HANG_NONE;
 }
 
+/* |description|
+Updates Mario's velocity and position while he is moving across a hangable ceiling. It calls `perform_hanging_step()` to handle collisions and movement logic, returning a status code indicating if Mario is still hanging or if he left the ceiling
+|descriptionEnd| */
 s32 update_hang_moving(struct MarioState *m) {
     if (!m) { return 0; }
     s32 stepResult;
@@ -418,6 +435,9 @@ s32 update_hang_moving(struct MarioState *m) {
     return stepResult;
 }
 
+/* |description|
+Keeps Mario stationary while he is hanging from a ceiling. This function zeroes out his velocity and ensures he remains aligned with the ceiling
+|descriptionEnd| */
 void update_hang_stationary(struct MarioState *m) {
     if (!m) { return; }
     m->forwardVel = 0.0f;
@@ -530,6 +550,9 @@ s32 act_hang_moving(struct MarioState *m) {
     return FALSE;
 }
 
+/* |description|
+Handles Mario letting go of a ledge by adjusting his position and setting his velocity to make him fall away from the ledge. The action then transitions to a 'soft bonk' state
+|descriptionEnd| */
 s32 let_go_of_ledge(struct MarioState *m) {
     if (!m) { return 0; }
     f32 floorHeight;
@@ -550,6 +573,9 @@ s32 let_go_of_ledge(struct MarioState *m) {
     return set_mario_action(m, ACT_SOFT_BONK, 0);
 }
 
+/* |description|
+Moves Mario onto the top of a ledge once he finishes climbing it. This shifts Mario forward slightly on the ledge and updates his animation accordingly
+|descriptionEnd| */
 void climb_up_ledge(struct MarioState *m) {
     if (!m) { return; }
     set_character_animation(m, CHAR_ANIM_IDLE_HEAD_LEFT);
@@ -558,6 +584,9 @@ void climb_up_ledge(struct MarioState *m) {
     vec3f_copy(m->marioObj->header.gfx.pos, m->pos);
 }
 
+/* |description|
+Gradually adjusts the camera position to track Mario as he climbs a ledge. This creates a smoother view transition from the ledge-grab camera angle to Mario's new location on top of the ledge
+|descriptionEnd| */
 void update_ledge_climb_camera(struct MarioState *m) {
     if (!m) { return; }
     f32 sp4;
@@ -574,6 +603,9 @@ void update_ledge_climb_camera(struct MarioState *m) {
     m->flags |= MARIO_UNKNOWN_25;
 }
 
+/* |description|
+Updates Mario's climb onto a ledge by setting the chosen climbing animation and transitioning to the specified end action (e.g., standing idle) once the animation finishes. If the end action is `ACT_IDLE`, Mario is placed on top of the ledge
+|descriptionEnd| */
 void update_ledge_climb(struct MarioState *m, s32 animation, u32 endAction) {
     stop_and_set_height_to_floor(m);
 
@@ -1123,6 +1155,9 @@ s32 act_bubbled(struct MarioState* m) {
     return FALSE;
 }
 
+/* |description|
+Checks if Mario should cancel his current automatic action, primarily by detecting if he falls into deep water. If so, transitions him to the water-plunge state
+|descriptionEnd| */
 s32 check_common_automatic_cancels(struct MarioState *m) {
     if (!m) { return 0; }
     if (m->pos[1] < m->waterLevel - 100) {
@@ -1132,6 +1167,10 @@ s32 check_common_automatic_cancels(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 s32 mario_execute_automatic_action(struct MarioState *m) {
     if (!m) { return 0; }
     if (!m) { return FALSE; }

src/game/mario_actions_cutscene.c

@@ -90,6 +90,9 @@ static Vec4s sJumboStarKeyframes[27] = {
  * character is a null character (equal to 0), stop counting the length since
  * that's the end of the string.
  */
+/* |description|
+Calculates the pixel width of a given credits string. Each space is counted as 4 pixels, and any other character as 7 pixels. Stops counting at the null terminator
+|descriptionEnd| */
 s32 get_credits_str_width(char *str) {
     if (!str) { return 0; }
     u32 c;
@@ -184,6 +187,9 @@ void print_displaying_credits_entry(void) {
     }
 }
 
+/* |description|
+Handles Peach's final cutscene animation. Cycles through frames based on the global `sEndPeachAnimation` value
+|descriptionEnd| */
 void bhv_end_peach_loop(void) {
     cur_obj_init_animation_with_sound(sEndPeachAnimation);
     if (cur_obj_check_if_near_animation_end()) {
@@ -194,6 +200,9 @@ void bhv_end_peach_loop(void) {
     }
 }
 
+/* |description|
+Handles Toad's final cutscene animation. Chooses which animation index to use based on Toad's x-position, then progresses through the animation frames as it nears completion
+|descriptionEnd| */
 void bhv_end_toad_loop(void) {
     if (!gCurrentObject) { return; }
     s32 toadAnimIndex = (gCurrentObject->oPosX >= 0.0f);
@@ -241,6 +250,9 @@ static void stub_is_textbox_active(u16 *a0) {
  * if so, return the dialog ID. Otherwise, return 0. A dialog is returned if
  * numStars has reached a milestone and prevNumStarsForDialog has not reached it.
  */
+/* |description|
+Determines which (if any) dialog to show when Mario collects a star. Checks milestone star counts against `prevNumStarsForDialog`, and returns a dialog ID if a milestone is reached. Otherwise, returns 0
+|descriptionEnd| */
 s32 get_star_collection_dialog(struct MarioState *m) {
     if (!m) { return 0; }
     s32 dialogID = 0;
@@ -274,6 +286,9 @@ s32 get_star_collection_dialog(struct MarioState *m) {
 }
 
 // save menu handler
+/* |description|
+Handles interactions with the save menu after collecting a star/key. Checks the user's selection (e.g., Save and Continue) and performs the corresponding action, such as saving the file or returning Mario to idle
+|descriptionEnd| */
 void handle_save_menu(struct MarioState *m) {
     if (!m) { return; }
 
@@ -332,6 +347,9 @@ struct Object *spawn_obj_at_mario_rel_yaw(struct MarioState *m, s32 model, const
  * Clears "cap on head" flag, sets "cap in hand" flag, plays sound
  * SOUND_ACTION_UNKNOWN43D.
  */
+/* |description|
+Transitions Mario's state from wearing the cap on his head to holding it in his hand. Clears the `MARIO_CAP_ON_HEAD` flag, sets the `MARIO_CAP_IN_HAND` flag, and plays the 'take cap off' sound
+|descriptionEnd| */
 void cutscene_take_cap_off(struct MarioState *m) {
     if (!m) { return; }
     m->flags &= ~MARIO_CAP_ON_HEAD;
@@ -344,6 +362,9 @@ void cutscene_take_cap_off(struct MarioState *m) {
  * Clears "cap in hand" flag, sets "cap on head" flag, plays sound
  * SOUND_ACTION_UNKNOWN43E.
  */
+/* |description|
+Transitions Mario's state from having the cap in his hand to wearing it on his head. Clears the `MARIO_CAP_IN_HAND` flag, sets the `MARIO_CAP_ON_HEAD` flag, and plays the 'put cap on' sound
+|descriptionEnd| */
 void cutscene_put_cap_on(struct MarioState *m) {
     if (!m) { return; }
     m->flags &= ~MARIO_CAP_IN_HAND;
@@ -361,6 +382,9 @@ void cutscene_put_cap_on(struct MarioState *m) {
  * 2: Mario mat not be riding a shell or be invulnerable.
  * 3: Mario must not be in first person mode.
  */
+/* |description|
+Checks if Mario's current action allows him to speak. For Mario to be ready, his action must be in a 'stationary' or 'moving' group (or waiting for dialog), and he must not be riding a shell, invulnerable, or in first-person mode
+|descriptionEnd| */
 s32 mario_ready_to_speak(struct MarioState* m) {
     if (!m) { return FALSE; }
     u32 actionGroup = m->action & ACT_GROUP_MASK;
@@ -376,6 +400,9 @@ s32 mario_ready_to_speak(struct MarioState* m) {
     return isReadyToSpeak;
 }
 
+/* |description|
+Checks if the dialog from a specified `object` should start or continue for this particular Mario. Ensures Mario is visible to enemies (i.e., not in certain invulnerable states) and, for remote players, validates the correct dialog object
+|descriptionEnd| */
 u8 should_start_or_continue_dialog(struct MarioState* m, struct Object* object) {
     if (!m) { return FALSE; }
     if (!m->visibleToEnemies) { return FALSE; }
@@ -688,6 +715,9 @@ s32 act_debug_free_move(struct MarioState *m) {
     return FALSE;
 }
 
+/* |description|
+Manages the star collection dance sequence for Mario, both on land and in water. Plays music, spawns the celebration star, increments the star count, and triggers level exits or dialogs at the correct times
+|descriptionEnd| */
 void general_star_dance_handler(struct MarioState *m, s32 isInWater) {
     if (m == NULL) { return; }
 
@@ -808,6 +838,9 @@ s32 act_fall_after_star_grab(struct MarioState *m) {
     return FALSE;
 }
 
+/* |description|
+Handles shared logic for Mario's various death states. Plays the specified death animation (`animation`), checks for a specific frame (`frameToDeathWarp`) to trigger a warp or bubble state if allowed, and sets Mario's eye state to 'dead'
+|descriptionEnd| */
 s32 common_death_handler(struct MarioState *m, s32 animation, s32 frameToDeathWarp) {
     if (!m) { return 0; }
     s32 animFrame = set_character_animation(m, animation);
@@ -933,6 +966,9 @@ s32 act_eaten_by_bubba(struct MarioState *m) {
 
 // set animation and forwardVel; when perform_air_step returns AIR_STEP_LANDED,
 // set the new action
+/* |description|
+Launches Mario forward with a given velocity (`forwardVel`) and sets his animation. Continues moving him through the air until he lands, then changes Mario's action to `endAction`
+|descriptionEnd| */
 s32 launch_mario_until_land(struct MarioState *m, s32 endAction, s32 animation, f32 forwardVel) {
     s32 airStepLanded;
     mario_set_forward_vel(m, forwardVel);
@@ -1905,6 +1941,9 @@ s32 act_taking_off_cap(struct MarioState *m) {
     return FALSE;
 }
 
+/* |description|
+Handles the cutscene and animation sequence for when Mario is stuck in the ground (head, butt, or feet). Plays a designated `animation`, checks specific frames (`unstuckFrame`, `target2`, `target3`) for sound effects or transitions, and frees Mario to the `endAction` once the animation completes
+|descriptionEnd| */
 void stuck_in_ground_handler(struct MarioState *m, s32 animation, s32 unstuckFrame, s32 target2,
                              s32 target3, s32 endAction) {
     if (!m) { return; }
@@ -2324,6 +2363,9 @@ static s32 act_jumbo_star_cutscene(struct MarioState *m) {
     return FALSE;
 }
 
+/* |description|
+Spawns yellow sparkles in a circular pattern around a specified point (`x`, `y`, `z`) within a given `radius`. Frequently seen during end cutscenes when objects like stars or Peach appear
+|descriptionEnd| */
 void generate_yellow_sparkles(s16 x, s16 y, s16 z, f32 radius) {
     static s32 sSparkleGenTheta = 0;
     static s32 sSparkleGenPhi = 0;
@@ -3102,6 +3144,9 @@ static s32 check_for_instant_quicksand(struct MarioState *m) {
     return FALSE;
 }
 
+/* |description|
+Executes Mario's current cutscene action based on his `action` field. Includes various story-related sequences like entering doors, collecting stars, and final boss cutscenes. Delegates to the appropriate function for each cutscene action
+|descriptionEnd| */
 s32 mario_execute_cutscene_action(struct MarioState *m) {
     if (!m) { return FALSE; }
 

src/game/mario_actions_moving.c

@@ -65,6 +65,10 @@ struct LandingAction sBackflipLandAction = {
 
 Mat4 sFloorAlignMatrix[MAX_PLAYERS];
 
+/* |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
+|descriptionEnd| */
 s16 tilt_body_running(struct MarioState *m) {
     if (!m) { return 0; }
     s16 pitch = find_floor_slope(m, 0);
@@ -72,6 +76,10 @@ s16 tilt_body_running(struct MarioState *m) {
     return -pitch;
 }
 
+/* |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
+|descriptionEnd| */
 void play_step_sound(struct MarioState *m, s16 frame1, s16 frame2) {
     if (!m) { return; }
     if (is_anim_past_frame(m, frame1) || is_anim_past_frame(m, frame2)) {
@@ -91,6 +99,9 @@ void play_step_sound(struct MarioState *m, s16 frame1, s16 frame2) {
     }
 }
 
+/* |description|
+Aligns Mario's position and model transformation matrix to match the floor's angle. Specifically: Sets Mario's vertical position to be at `m.floorHeight` plus any active character animation offset and adjusts Mario's `throwMatrix` so that his body appears flush with the floor
+|descriptionEnd| */
 void align_with_floor(struct MarioState *m) {
     if (!m) { return; }
     m->pos[1] = m->floorHeight + get_character_anim_offset(m);
@@ -98,6 +109,9 @@ void align_with_floor(struct MarioState *m) {
     m->marioObj->header.gfx.throwMatrix = &sFloorAlignMatrix[m->playerIndex];
 }
 
+/* |description|
+Sets Mario's facing yaw to his intended yaw, applies a specified forward velocity, and transitions to the given action (e.g., `ACT_WALKING`).
+|descriptionEnd| */
 s32 begin_walking_action(struct MarioState *m, f32 forwardVel, u32 action, u32 actionArg) {
     if (!m) { return 0; }
     m->faceAngle[1] = m->intendedYaw;
@@ -105,6 +119,10 @@ s32 begin_walking_action(struct MarioState *m, f32 forwardVel, u32 action, u32 a
     return set_mario_action(m, action, actionArg);
 }
 
+/* |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
+|descriptionEnd| */
 void check_ledge_climb_down(struct MarioState *m) {
     if (!m) { return; }
     struct WallCollisionData wallCols;
@@ -143,6 +161,9 @@ void check_ledge_climb_down(struct MarioState *m) {
     }
 }
 
+/* |description|
+Handles the scenario where Mario slides into a wall. If Mario is moving fast, reflects his velocity and transitions to a fast knockback, Otherwise, stops his forward velocity and sets a slower knockback
+|descriptionEnd| */
 void slide_bonk(struct MarioState *m, u32 fastAction, u32 slowAction) {
     if (!m) { return; }
     if (m->forwardVel > 16.0f) {
@@ -154,6 +175,9 @@ void slide_bonk(struct MarioState *m, u32 fastAction, u32 slowAction) {
     }
 }
 
+/* |description|
+Determines the proper triple jump action based on Mario's forward velocity and the Wing Cap flag: Normal triple jump, flying triple jump, or just a single jump if not enough speed
+|descriptionEnd| */
 s32 set_triple_jump_action(struct MarioState *m, UNUSED u32 action, UNUSED u32 actionArg) {
     if (!m) { return FALSE; }
 
@@ -168,6 +192,11 @@ s32 set_triple_jump_action(struct MarioState *m, UNUSED u32 action, UNUSED u32 a
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 void update_sliding_angle(struct MarioState *m, f32 accel, f32 lossFactor) {
     if (!m) { return; }
     s32 newFacingDYaw;
@@ -231,6 +260,11 @@ void update_sliding_angle(struct MarioState *m, f32 accel, f32 lossFactor) {
     }
 }
 
+/* |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
+|descriptionEnd| */
 s32 update_sliding(struct MarioState *m, f32 stopSpeed) {
     if (!m) { return FALSE; }
     f32 lossFactor;
@@ -296,6 +330,10 @@ s32 update_sliding(struct MarioState *m, f32 stopSpeed) {
     return stopped;
 }
 
+/* |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
+|descriptionEnd| */
 void apply_slope_accel(struct MarioState *m) {
     if (!m) { return; }
     f32 slopeAccel;
@@ -349,6 +387,10 @@ void apply_slope_accel(struct MarioState *m) {
     mario_update_windy_ground(m);
 }
 
+/* |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
+|descriptionEnd| */
 s32 apply_landing_accel(struct MarioState *m, f32 frictionFactor) {
     if (!m) { return FALSE; }
     s32 stopped = FALSE;
@@ -366,6 +408,9 @@ s32 apply_landing_accel(struct MarioState *m, f32 frictionFactor) {
     return stopped;
 }
 
+/* |description|
+Controls Mario's speed when riding a Koopa Shell on the ground.
+|descriptionEnd| */
 void update_shell_speed(struct MarioState *m) {
     if (!m || !m->floor) { return; }
     f32 maxTargetSpeed;
@@ -410,6 +455,10 @@ void update_shell_speed(struct MarioState *m) {
     apply_slope_accel(m);
 }
 
+/* |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
+|descriptionEnd| */
 s32 apply_slope_decel(struct MarioState *m, f32 decelCoef) {
     if (!m) { return 0; }
     f32 decel;
@@ -438,6 +487,10 @@ s32 apply_slope_decel(struct MarioState *m, f32 decelCoef) {
     return stopped;
 }
 
+/* |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
+|descriptionEnd| */
 s32 update_decelerating_speed(struct MarioState *m) {
     if (!m) { return 0; }
     s32 stopped = FALSE;
@@ -453,6 +506,11 @@ s32 update_decelerating_speed(struct MarioState *m) {
     return stopped;
 }
 
+
+/* |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
+|descriptionEnd| */
 void update_walking_speed(struct MarioState *m) {
     if (!m) { return; }
     f32 maxTargetSpeed;
@@ -486,6 +544,10 @@ void update_walking_speed(struct MarioState *m) {
     apply_slope_accel(m);
 }
 
+/* |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.
+|descriptionEnd| */
 s32 should_begin_sliding(struct MarioState *m) {
     if (!m) { return FALSE; }
     if (m->input & INPUT_ABOVE_SLIDE) {
@@ -500,12 +562,20 @@ s32 should_begin_sliding(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 s32 analog_stick_held_back(struct MarioState *m) {
     if (!m) { return FALSE; }
     s16 intendedDYaw = m->intendedYaw - m->faceAngle[1];
     return intendedDYaw < -0x471C || intendedDYaw > 0x471C;
 }
 
+/* |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
+|descriptionEnd| */
 s32 check_ground_dive_or_punch(struct MarioState *m) {
     if (!m) { return FALSE; }
     UNUSED s32 unused;
@@ -523,6 +593,10 @@ s32 check_ground_dive_or_punch(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 s32 begin_braking_action(struct MarioState *m) {
     if (!m) { return FALSE; }
     mario_drop_held_object(m);
@@ -539,6 +613,10 @@ s32 begin_braking_action(struct MarioState *m) {
     return set_mario_action(m, ACT_DECELERATING, 0);
 }
 
+/* |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
+|descriptionEnd| */
 void anim_and_audio_for_walk(struct MarioState *m) {
     if (!m) { return; }
     s32 val14;
@@ -634,6 +712,10 @@ void anim_and_audio_for_walk(struct MarioState *m) {
     marioObj->header.gfx.angle[0] = marioObj->oMarioWalkingPitch;
 }
 
+/* |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
+|descriptionEnd| */
 void anim_and_audio_for_hold_walk(struct MarioState *m) {
     if (!m) { return; }
     s32 val0C;
@@ -696,6 +778,10 @@ void anim_and_audio_for_hold_walk(struct MarioState *m) {
     }
 }
 
+/* |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
+|descriptionEnd| */
 void anim_and_audio_for_heavy_walk(struct MarioState *m) {
     if (!m) { return; }
     s32 val04 = (s32)(m->intendedMag * 0x10000);
@@ -703,6 +789,9 @@ void anim_and_audio_for_heavy_walk(struct MarioState *m) {
     play_step_sound(m, 26, 79);
 }
 
+/* |description|
+When Mario hits a wall during movement, decides whether he's pushing against the wall or sidling along it. Plays pushing animations and sounds if he's head-on, sidles along the wall if he's more angled
+|descriptionEnd| */
 void push_or_sidle_wall(struct MarioState *m, Vec3f startPos) {
     if (!m) { return; }
     s16 wallAngle = 0;
@@ -745,6 +834,10 @@ void push_or_sidle_wall(struct MarioState *m, Vec3f startPos) {
     }
 }
 
+/* |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
+|descriptionEnd| */
 void tilt_body_walking(struct MarioState *m, s16 startYaw) {
     if (!m) { return; }
     struct MarioBodyState *val0C = m->marioBodyState;
@@ -780,6 +873,10 @@ void tilt_body_walking(struct MarioState *m, s16 startYaw) {
     }
 }
 
+/* |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
+|descriptionEnd| */
 void tilt_body_ground_shell(struct MarioState *m, s16 startYaw) {
     if (!m) { return; }
     struct MarioBodyState *val0C = m->marioBodyState;
@@ -1403,6 +1500,10 @@ s32 act_burning_ground(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 void tilt_body_butt_slide(struct MarioState *m) {
     if (!m) { return; }
     s16 intendedDYaw = m->intendedYaw - m->faceAngle[1];
@@ -1410,6 +1511,9 @@ void tilt_body_butt_slide(struct MarioState *m) {
     m->marioBodyState->torsoAngle[2] = (s32)(-(5461.3335f * m->intendedMag / 32.0f * sins(intendedDYaw)));
 }
 
+/* |description|
+Applies shared logic for sliding-related actions while playing sliding sounds, managing ground steps (falling off edges, hitting walls), updates animation
+|descriptionEnd| */
 void common_slide_action(struct MarioState *m, u32 endAction, u32 airAction, s32 animation) {
     if (!m) { return; }
     Vec3f pos;
@@ -1466,6 +1570,10 @@ void common_slide_action(struct MarioState *m, u32 endAction, u32 airAction, s32
     }
 }
 
+/* |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
+|descriptionEnd| */
 s32 common_slide_action_with_jump(struct MarioState *m, u32 stopAction, u32 jumpAction, u32 airAction,
                                   s32 animation) {
     if (!m) { return FALSE; }
@@ -1578,6 +1686,10 @@ s32 act_slide_kick_slide(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 s32 stomach_slide_action(struct MarioState *m, u32 stopAction, u32 airAction, s32 animation) {
     if (!m) { return FALSE; }
     if (m->actionTimer == 5) {
@@ -1651,6 +1763,9 @@ s32 act_dive_slide(struct MarioState *m) {
     return FALSE;
 }
 
+/* |description|
+Handles knockback on the ground (getting hit while on the ground) with shared logic for multiple knockback states. Applies deceleration or minimal momentum, chooses appropriate landing action if Mario leaves the ground, and handles death transitions if Mario's health is depleted
+|descriptionEnd| */
 s32 common_ground_knockback_action(struct MarioState *m, s32 animation, s32 arg2, s32 arg3, s32 arg4) {
     if (!m) { return 0; }
     s32 animFrame;
@@ -1802,6 +1917,9 @@ s32 act_death_exit_land(struct MarioState *m) {
     return FALSE;
 }
 
+/* |description|
+Applies movement upon landing from a jump or fall. Adjusts velocity based on slope or friction, checks for transitions like sliding or hitting a wall, handles small dust particles if moving fast
+|descriptionEnd| */
 u32 common_landing_action(struct MarioState *m, s16 animation, u32 airAction) {
     if (!m) { return 0; }
     u32 stepResult;
@@ -2005,6 +2123,9 @@ s32 act_backflip_land(struct MarioState *m) {
     return FALSE;
 }
 
+/* |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
+|descriptionEnd| */
 s32 quicksand_jump_land_action(struct MarioState *m, s32 animation1, s32 animation2, u32 endAction,
                                u32 airAction) {
     if (!m) { return FALSE; }
@@ -2047,6 +2168,10 @@ s32 act_hold_quicksand_jump_land(struct MarioState *m) {
     return cancel;
 }
 
+
+/* |description|
+Performs common checks when Mario is in a moving state, transitions to water plunge if underwater, handles squished or shockwave bounce scenarios, and checks for death conditions
+|descriptionEnd| */
 s32 check_common_moving_cancels(struct MarioState *m) {
     if (!m) { return FALSE; }
     if (m->pos[1] < m->waterLevel - 100) {
@@ -2070,6 +2195,9 @@ s32 check_common_moving_cancels(struct MarioState *m) {
     return FALSE;
 }
 
+/* |description|
+Executes Mario's current moving actions by: checking common cancellations (e.g., water plunge, squish, death), handling quicksand updates, and switching to the correct sub-action handler based on `m.action`
+|descriptionEnd| */
 s32 mario_execute_moving_action(struct MarioState *m) {
     if (!m) { return FALSE; }
     s32 cancel;

src/pc/lua/utils/smlua_collision_utils.h

@@ -117,6 +117,7 @@ extern struct GlobalObjectCollisionData gGlobalObjectCollisionData;
 struct RayIntersectionInfo* collision_find_surface_on_ray(f32 startX, f32 startY, f32 startZ, f32 dirX, f32 dirY, f32 dirZ, f32 precision);
 /* |description|Finds a potential floor at the given `x`, `y`, and `z` values|descriptionEnd| */
 struct Surface* collision_find_floor(f32 x, f32 y, f32 z);
+
 /* |description|Finds a potential ceiling at the given `x`, `y`, and `z` values|descriptionEnd| */
 struct Surface* collision_find_ceil(f32 x, f32 y, f32 z);