diff --git a/autogen/lua_definitions/functions.lua b/autogen/lua_definitions/functions.lua index 81063c5bb..ffe5fef42 100644 --- a/autogen/lua_definitions/functions.lua +++ b/autogen/lua_definitions/functions.lua @@ -2995,6 +2995,7 @@ end --- @param c Camera --- @param goal number --- @param inc number +--- Adjusts the camera's height toward a target value (`goalHeight`) while respecting terrain and obstructions. This is really wonky and probably shouldn't be used, prefer `gLakituStates` function approach_camera_height(c, goal, inc) -- ... end @@ -3003,6 +3004,7 @@ end --- @param target number --- @param multiplier number --- @return number +--- Gradually approaches a floating-point value (`target`) using asymptotic smoothing. The rate of approach is controlled by the `multiplier`. Useful for smoothly adjusting camera parameters like field-of-view or position function approach_f32_asymptotic(current, target, multiplier) -- ... end @@ -3011,6 +3013,7 @@ end --- @param target number --- @param multiplier number --- @return integer +--- Gradually adjusts a floating-point value (`current`) towards a target (`target`) using asymptotic smoothing. Returns true if `current` reaches the `target` and false otherwise function approach_f32_asymptotic_bool(current, target, multiplier) -- ... end @@ -3019,6 +3022,7 @@ end --- @param target integer --- @param divisor integer --- @return integer +--- Gradually approaches a signed 16-bit integer (`target`) using asymptotic smoothing. The divisor controls the rate of the adjustment. Useful for adjusting angles or positions smoothly function approach_s16_asymptotic(current, target, divisor) -- ... end @@ -3027,6 +3031,7 @@ end --- @param target integer --- @param divisor integer --- @return integer +--- Gradually adjusts a signed 16-bit integer (`current`) towards a target (`target`) using asymptotic smoothing. Returns true if `current` reaches `target` and false otherwise function approach_s16_asymptotic_bool(current, target, divisor) -- ... end @@ -3036,6 +3041,7 @@ end --- @param xMul number --- @param yMul number --- @param zMul number +--- Smoothly transitions a 3D vector (`current`) towards a target vector (`target`) using asymptotic scaling. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component function approach_vec3f_asymptotic(current, target, xMul, yMul, zMul) -- ... end @@ -3043,6 +3049,7 @@ end --- @param a Vec3f --- @param b Vec3f --- @return number +--- Calculates the absolute distance between two 3D points (`a` and `b`). Returns the distance as a floating-point value. Useful for determining proximity between objects in 3D space function calc_abs_dist(a, b) -- ... end @@ -3050,6 +3057,7 @@ end --- @param a Vec3f --- @param b Vec3f --- @return number +--- Calculates the horizontal (XZ-plane) distance between two 3D points (`a` and `b`). Returns the distance as a floating-point value. Useful for terrain navigation or collision detection function calc_hor_dist(a, b) -- ... end @@ -3058,6 +3066,7 @@ end --- @param to Vec3f --- @param pitch Pointer_integer --- @param yaw Pointer_integer +--- Calculates the pitch and yaw angles from one 3D position (`from`) to another (`to`). Updates the provided pointers with the computed pitch and yaw values function calculate_angles(from, to, pitch, yaw) -- ... end @@ -3065,6 +3074,7 @@ end --- @param from Vec3f --- @param to Vec3f --- @return integer +--- Calculates the pitch angle (rotation around the X-axis) from one 3D point (`from`) to another (`to`). Returns the pitch as a signed 16-bit integer function calculate_pitch(from, to) -- ... end @@ -3072,12 +3082,14 @@ end --- @param from Vec3f --- @param to Vec3f --- @return integer +--- Determines the yaw angle (rotation around the Y-axis) from one 3D position (`from`) to another (`to`). Returns the yaw as a signed 16-bit integer function calculate_yaw(from, to) -- ... end --- @param angle integer --- @return integer +--- Selects an alternate camera mode based on the given angle. Used to toggle between predefined camera modes dynamically function cam_select_alt_mode(angle) -- ... end @@ -3086,6 +3098,7 @@ end --- @param target number --- @param increment number --- @return number +--- Symmetrically approaches a floating-point value (`target`) with a fixed increment (`increment`) per frame. Limits the rate of change to ensure gradual transitions function camera_approach_f32_symmetric(value, target, increment) -- ... end @@ -3094,6 +3107,7 @@ end --- @param target number --- @param increment number --- @return integer +--- Adjusts a floating-point value (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). Returns true if the value reaches the target and false otherwise function camera_approach_f32_symmetric_bool(current, target, increment) -- ... end @@ -3102,21 +3116,25 @@ end --- @param target integer --- @param increment integer --- @return integer +--- Adjusts a signed 16-bit integer (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). Returns true if the value reaches the target and false otherwise function camera_approach_s16_symmetric_bool(current, target, increment) -- ... end --- @param c Camera --- @return integer +--- Processes course-specific camera settings, such as predefined positions or modes. Adjusts the camera to match the design and gameplay requirements of the current course function camera_course_processing(c) -- ... end --- @param enable integer +--- Toggles whether the camera uses course-specific settings. This is useful for enabling or disabling custom behaviors in specific courses or areas function camera_set_use_course_specific_settings(enable) -- ... end +--- Centers the ROM hack camera. This function is designed for non-standard level layouts and modded game environments function center_rom_hack_camera() -- ... end @@ -3126,6 +3144,7 @@ end --- @param maxPitch integer --- @param minPitch integer --- @return integer +--- Clamps the camera's pitch angle between a maximum and minimum value. Prevents over-rotation and maintains a consistent viewing angle function clamp_pitch(from, to, maxPitch, minPitch) -- ... end @@ -3137,6 +3156,7 @@ end --- @param zMax number --- @param zMin number --- @return integer +--- Clamps a position within specified X and Z bounds and calculates the yaw angle from the origin. Prevents the camera from moving outside of the designated area function clamp_positions_and_find_yaw(pos, origin, xMax, xMin, zMax, zMin) -- ... end @@ -3145,6 +3165,7 @@ end --- @param offsetY number --- @param radius number --- @return integer +--- Checks for collisions between the camera and level geometry. Adjusts the camera's position to avoid clipping into walls or obstacles function collide_with_walls(pos, offsetY, radius) -- ... end @@ -3152,6 +3173,7 @@ end --- @param cutscene integer --- @param o Object --- @return integer +--- Initiates a cutscene focusing on a specific object in the game world. The camera transitions smoothly to the object, adapting its position as needed function cutscene_object(cutscene, o) -- ... end @@ -3160,6 +3182,7 @@ end --- @param o Object --- @param dialogID integer --- @return integer +--- Starts a cutscene involving an object and displays dialog during the sequence. The camera focuses on the object while synchronizing dialog with the scene function cutscene_object_with_dialog(cutscene, o, dialogID) -- ... end @@ -3167,11 +3190,13 @@ end --- @param cutscene integer --- @param o Object --- @return integer +--- Starts a cutscene involving an object without dialog. The camera transitions smoothly to focus on the object function cutscene_object_without_dialog(cutscene, o) -- ... end --- @param preset integer +--- Applies a preset field-of-view shake effect during a cutscene. This creates dynamic visual effects, such as zoom or focus disruptions function cutscene_set_fov_shake_preset(preset) -- ... end @@ -3179,6 +3204,7 @@ end --- @param obj integer --- @param frame integer --- @return integer +--- Spawns an object as part of a cutscene, such as props or interactive elements. Returns the spawned object's reference for further manipulation function cutscene_spawn_obj(obj, frame) -- ... end @@ -3187,22 +3213,26 @@ end --- @param buttonsPressed integer --- @param buttonsDown integer --- @return integer +--- Determines which C-buttons are currently pressed by the player. Returns a bitmask indicating the active buttons for camera control function find_c_buttons_pressed(currentState, buttonsPressed, buttonsDown) -- ... end --- @param pg PlayerGeometry +--- Finds the floor and ceiling directly above and below Mario's position. Updates Mario's geometry information for camera calculations function find_mario_floor_and_ceil(pg) -- ... end --- @param c Camera --- @return integer +--- Gets the appropriate cutscene to play based on Mario's current gameplay state. This function helps determine transitions for cinematic or scripted sequences function get_cutscene_from_mario_status(c) -- ... end --- @param c Camera +--- Handles camera movement based on input from the C-buttons. Updates the camera's position or angle to match directional player input function handle_c_button_movement(c) -- ... end @@ -3213,6 +3243,7 @@ end --- @param range integer --- @param surfType integer --- @return integer +--- Determines if a range is obstructed by a surface relative to the camera. Returns true if the range is behind the specified surface function is_range_behind_surface(from, to, surf, range, surfType) -- ... end @@ -3221,11 +3252,13 @@ end --- @param posY number --- @param posZ number --- @return integer +--- Checks if a position is within 100 units of Mario's current position. Returns true if the position is within the specified radius and false otherwise function is_within_100_units_of_mario(posX, posY, posZ) -- ... end --- @param c Camera +--- Moves Mario's head slightly upward when the C-Up button is pressed. This function aligns the camera to match the head movement for consistency function move_mario_head_c_up(c) -- ... end @@ -3238,6 +3271,7 @@ end --- @param oldFoc Vec3f --- @param yaw integer --- @return integer +--- Transitions the camera to the next Lakitu state, updating position and focus. This function handles smooth transitions between different gameplay scenarios function next_lakitu_state(newPos, newFoc, curPos, curFoc, oldPos, oldFoc, yaw) -- ... end @@ -3248,12 +3282,14 @@ end --- @param yawOff integer --- @param pitchDiv integer --- @param yawDiv integer +--- Rotates an object toward a specific point in 3D space. Gradually updates the object's pitch and yaw angles to face the target function obj_rotate_towards_point(o, point, pitchOff, yawOff, pitchDiv, yawDiv) -- ... end --- @param dst Vec3f --- @param o Object +--- Converts an object's position to a `Vec3f` format. Useful for aligning object behaviors or interactions with the camera system function object_pos_to_vec3f(dst, o) -- ... end @@ -3262,6 +3298,7 @@ end --- @param from Vec3f --- @param to Vec3f --- @param rotation Vec3s +--- Offsets a vector by rotating it in 3D space relative to a reference position. This is useful for creating radial effects or dynamic transformations function offset_rotated(dst, from, to, rotation) -- ... end @@ -3269,47 +3306,58 @@ end --- @param c Camera --- @param areaYaw integer --- @return integer +--- Calculates an outward radial offset based on the camera's yaw angle. Returns the offset yaw, used for positioning or alignment function offset_yaw_outward_radial(c, areaYaw) -- ... end +--- Plays a buzzing sound effect when the camera's position is misaligned with the player's perspective. Used as audio feedback for incorrect camera behavior function play_camera_buzz_if_c_sideways() -- ... end +--- Plays a buzzing sound effect when a blocked C-button action is attempted. Used to signal invalid input or restricted camera movement function play_camera_buzz_if_cbutton() -- ... end +--- Plays a buzzing sound effect when the camera attempts to move downward but is restricted. Provides feedback for invalid C-Down input actions function play_camera_buzz_if_cdown() -- ... end --- @param c Camera +--- Starts the execution of a predefined cutscene. The camera transitions dynamically to follow the scripted sequence function play_cutscene(c) -- ... end +--- Plays a sound effect when a blocked action changes the camera mode. This provides feedback for invalid attempts to switch the camera state function play_sound_button_change_blocked() -- ... end +--- Plays a sound effect when the C-Down button is pressed for camera movement. Provides auditory feedback for valid camera input function play_sound_cbutton_down() -- ... end +--- Plays a sound effect when the C-Side button (left or right) is pressed for camera movement. Used as audio feedback for horizontal adjustments to the camera function play_sound_cbutton_side() -- ... end +--- Plays a sound effect when the C-Up button is pressed for camera movement. Provides feedback for vertical camera adjustments function play_sound_cbutton_up() -- ... end +--- Plays a sound effect when the camera switches between Lakitu and Mario perspectives. Signals a successful change in camera mode function play_sound_if_cam_switched_to_lakitu_or_mario() -- ... end +--- Plays a sound effect when the R-Button camera mode is changed. Provides feedback for toggling camera behaviors function play_sound_rbutton_changed() -- ... end @@ -3317,6 +3365,7 @@ end --- @param c Camera --- @param unused number --- @return integer +--- Handles radial camera movement based on player input. Updates the camera's position or orientation accordingly function radial_camera_input(c, unused) -- ... end @@ -3325,22 +3374,26 @@ end --- @param xRange integer --- @param yRange integer --- @param zRange integer +--- Generates a random 3D vector with short integer components. Useful for randomized offsets or environmental effects function random_vec3s(dst, xRange, yRange, zRange) -- ... end --- @param c Camera +--- Fully resets the camera to its default state and reinitializes all settings. This is typically used when restarting gameplay or loading a new area function reset_camera(c) -- ... end --- @param pos Vec3f --- @param lastGood Vec3f +--- Resolves collisions between the camera and level geometry. Adjusts the camera's position to prevent clipping or intersecting with objects function resolve_geometry_collisions(pos, lastGood) -- ... end --- @param enable integer +--- Toggles collision settings for the ROM hack camera. This enables or disables specific collision behaviors in modded levels function rom_hack_cam_set_collisions(enable) -- ... end @@ -3350,6 +3403,7 @@ end --- @param avoidYaw Pointer_integer --- @param yawRange integer --- @return integer +--- Rotates the camera to avoid walls or other obstructions. Ensures clear visibility of the player or target objects function rotate_camera_around_walls(c, cPos, avoidYaw, yawRange) -- ... end @@ -3357,6 +3411,7 @@ end --- @param dst Vec3f --- @param src Vec3f --- @param yaw integer +--- Rotates a vector around the XZ-plane by a specified yaw angle. The result is stored in the destination vector (`dst`). Useful for rotating camera positions or object coordinates horizontally function rotate_in_xz(dst, src, yaw) -- ... end @@ -3364,6 +3419,7 @@ end --- @param dst Vec3f --- @param src Vec3f --- @param pitch integer +--- Rotates a vector around the YZ-plane by a specified pitch angle. The result is stored in the destination vector (`dst`). Useful for vertical camera rotations or object transformations function rotate_in_yz(dst, src, pitch) -- ... end @@ -3372,16 +3428,19 @@ end --- @param from Vec3f --- @param to Vec3f --- @param scale number +--- Scales a point along a line between two 3D points (`from` and `to`). The scaling factor determines how far along the line the resulting point will be. The result is stored in the destination vector (`dest`) function scale_along_line(dest, from, to, scale) -- ... end +--- Selects the appropriate camera mode for Mario based on the current gameplay context. Adapts camera behavior dynamically to match Mario's environment or state function select_mario_cam_mode() -- ... end --- @param mode integer --- @return integer +--- Sets the camera's angle based on the specified mode. Handles rotation and focus adjustments for predefined camera behaviors function set_cam_angle(mode) -- ... end @@ -3389,6 +3448,7 @@ end --- @param c Camera --- @param mode integer --- @param frames integer +--- Changes the camera to a new mode, optionally interpolating over a specified number of frames. Useful for transitioning between different camera behaviors dynamically function set_camera_mode(c, mode, frames) -- ... end @@ -3398,6 +3458,7 @@ end --- @param y integer --- @param z integer --- @return integer +--- Activates a fixed camera mode and aligns the camera to specific X, Y, Z coordinates. This is useful for predefined static views in specific areas function set_camera_mode_fixed(c, x, y, z) -- ... end @@ -3405,6 +3466,7 @@ end --- @param mag integer --- @param decay integer --- @param inc integer +--- Applies a pitch-based shake effect to the camera. The shake's magnitude, decay, and increment are configurable. Simulates vertical disturbances like impacts or explosions function set_camera_pitch_shake(mag, decay, inc) -- ... end @@ -3412,11 +3474,13 @@ end --- @param mag integer --- @param decay integer --- @param inc integer +--- Applies a roll-based shake effect to the camera. Simulates rotational disturbances for dynamic camera effects function set_camera_roll_shake(mag, decay, inc) -- ... end --- @param shake integer +--- Applies a shake effect to the camera based on a hit type. Different shake types simulate various impacts, such as attacks, falls, or shocks function set_camera_shake_from_hit(shake) -- ... end @@ -3425,6 +3489,7 @@ end --- @param posX number --- @param posY number --- @param posZ number +--- Applies a shake effect to the camera, scaled by its proximity to a specified point. The intensity decreases with distance from the point function set_camera_shake_from_point(shake, posX, posY, posZ) -- ... end @@ -3432,21 +3497,25 @@ end --- @param mag integer --- @param decay integer --- @param inc integer +--- Applies a yaw-based shake effect to the camera. Simulates horizontal vibrations or rotational impacts function set_camera_yaw_shake(mag, decay, inc) -- ... end --- @param shake integer +--- Applies an environmental shake effect to the camera. Handles predefined shake types triggered by environmental events like explosions or platform movements 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 --- @param func integer +--- Assigns a custom function for dynamic field-of-view adjustments. This allows precise control over the camera's zoom behavior during gameplay function set_fov_function(func) -- ... end @@ -3454,6 +3523,7 @@ end --- @param amplitude integer --- @param decay integer --- @param shakeSpeed integer +--- Applies a field-of-view shake effect to simulate zoom or focus disruptions. Shake parameters, such as amplitude and decay, control the intensity function set_fov_shake(amplitude, decay, shakeSpeed) -- ... end @@ -3462,11 +3532,13 @@ end --- @param posX number --- @param posY number --- @param posZ number +--- Applies a preset field-of-view shake effect relative to a specific point. The intensity diminishes as the distance from the point increases function set_fov_shake_from_point_preset(preset, posX, posY, posZ) -- ... end --- @param mode integer +--- Applies a handheld camera shake effect with configurable parameters. Can be used to simulate dynamic, realistic camera movement function set_handheld_shake(mode) -- ... end @@ -3475,6 +3547,7 @@ end --- @param goal number --- @param scale number --- @return integer +--- Smoothly transitions or directly sets a floating-point value (`dst`) to approach a target (`goal`). Uses asymptotic scaling for gradual adjustments or direct assignment function set_or_approach_f32_asymptotic(dst, goal, scale) -- ... end @@ -3483,6 +3556,7 @@ end --- @param target integer --- @param increment integer --- @return integer +--- Smoothly transitions or directly sets a signed 16-bit value (`current`) to approach a target (`target`). Uses symmetric scaling for gradual or immediate adjustments function set_or_approach_s16_symmetric(current, target, increment) -- ... end @@ -3492,6 +3566,7 @@ end --- @param xMul number --- @param yMul number --- @param zMul number +--- Smoothly transitions a 3D vector (`current`) toward a target vector (`goal`) using asymptotic scaling. Allows gradual or instantaneous alignment of 3D positions. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component function set_or_approach_vec3f_asymptotic(dst, goal, xMul, yMul, zMul) -- ... end @@ -3503,74 +3578,87 @@ end --- @param posX number --- @param posY number --- @param posZ number +--- Applies a pitch shake effect to the camera, scaled by proximity to a specified point. Simulates vibrations with intensity decreasing further from the point function set_pitch_shake_from_point(mag, decay, inc, maxDist, posX, posY, posZ) -- ... end --- @param pos Vec3f --- @param focus Vec3f +--- Activates a handheld camera shake effect. Calculates positional and focus adjustments to simulate manual movement function shake_camera_handheld(pos, focus) -- ... end --- @param pos Vec3f --- @param focus Vec3f +--- Activates a pitch-based shake effect. Adds vertical vibrational movement to the camera's behavior function shake_camera_pitch(pos, focus) -- ... end --- @param roll Pointer_integer +--- Applies a roll-based shake effect to the camera. Simulates rotational disturbances caused by impacts or other events function shake_camera_roll(roll) -- ... end --- @param pos Vec3f --- @param focus Vec3f +--- Activates a yaw-based shake effect. Adds horizontal vibrational movement to the camera's behavior function shake_camera_yaw(pos, focus) -- ... end +--- Skips camera interpolation for a frame, locking the camera instantly to the target position. Useful for immediate changes in camera state or position without smooth transitions function skip_camera_interpolation() -- ... end --- @param c Camera +--- Resets the camera's state while retaining some settings, such as position or mode. This is often used when soft-resetting gameplay without reinitialization function soft_reset_camera(c) -- ... end --- @param c Camera --- @param cutscene integer +--- Starts a cutscene based on the provided ID. The camera transitions to predefined behaviors for the duration of the cutscene function start_cutscene(c, cutscene) -- ... end --- @param cutscene integer --- @return integer +--- Starts a cutscene focused on an object without requiring focus to remain locked. This is useful for dynamic events where the camera adjusts freely function start_object_cutscene_without_focus(cutscene) -- ... end --- @param c Camera --- @param frames integer +--- Transitions the camera to the next state over a specified number of frames. This is typically used for cutscenes or scripted sequences function transition_next_state(c, frames) -- ... end --- @param trigger integer --- @return integer +--- Triggers a dialog sequence during a cutscene. The dialog is synchronized with the camera's position and movement function trigger_cutscene_dialog(trigger) -- ... end --- @param dst Vec3f --- @param src Vec3f +--- Subtracts one 3D vector (`src`) from another (`dst`). Stores the result in the destination vector function vec3f_sub(dst, src) -- ... end --- @param o Object --- @param src Vec3f +--- Converts a `Vec3f` position to an object's internal format. Useful for syncing 3D positions between objects and the game world function vec3f_to_object_pos(o, src) -- ... end @@ -3578,6 +3666,7 @@ end --- @param displacementX number --- @param displacementY number --- @param displacementZ number +--- Moves the camera to a specified warp destination. This function handles transitions between levels or areas seamlessly function warp_camera(displacementX, displacementY, displacementZ) -- ... end diff --git a/docs/lua/functions-3.md b/docs/lua/functions-3.md index fac85ce91..8e71c536b 100644 --- a/docs/lua/functions-3.md +++ b/docs/lua/functions-3.md @@ -289,6 +289,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [approach_camera_height](#approach_camera_height) +### Description +Adjusts the camera's height toward a target value (`goalHeight`) while respecting terrain and obstructions. This is really wonky and probably shouldn't be used, prefer `gLakituStates` + ### Lua Example `approach_camera_height(c, goal, inc)` @@ -311,6 +314,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [approach_f32_asymptotic](#approach_f32_asymptotic) +### Description +Gradually approaches a floating-point value (`target`) using asymptotic smoothing. The rate of approach is controlled by the `multiplier`. Useful for smoothly adjusting camera parameters like field-of-view or position + ### Lua Example `local numberValue = approach_f32_asymptotic(current, target, multiplier)` @@ -333,6 +339,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [approach_f32_asymptotic_bool](#approach_f32_asymptotic_bool) +### Description +Gradually adjusts a floating-point value (`current`) towards a target (`target`) using asymptotic smoothing. Returns true if `current` reaches the `target` and false otherwise + ### Lua Example `local integerValue = approach_f32_asymptotic_bool(current, target, multiplier)` @@ -355,6 +364,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [approach_s16_asymptotic](#approach_s16_asymptotic) +### Description +Gradually approaches a signed 16-bit integer (`target`) using asymptotic smoothing. The divisor controls the rate of the adjustment. Useful for adjusting angles or positions smoothly + ### Lua Example `local integerValue = approach_s16_asymptotic(current, target, divisor)` @@ -377,6 +389,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [approach_s16_asymptotic_bool](#approach_s16_asymptotic_bool) +### Description +Gradually adjusts a signed 16-bit integer (`current`) towards a target (`target`) using asymptotic smoothing. Returns true if `current` reaches `target` and false otherwise + ### Lua Example `local integerValue = approach_s16_asymptotic_bool(current, target, divisor)` @@ -399,6 +414,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [approach_vec3f_asymptotic](#approach_vec3f_asymptotic) +### Description +Smoothly transitions a 3D vector (`current`) towards a target vector (`target`) using asymptotic scaling. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component + ### Lua Example `approach_vec3f_asymptotic(current, target, xMul, yMul, zMul)` @@ -423,6 +441,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [calc_abs_dist](#calc_abs_dist) +### Description +Calculates the absolute distance between two 3D points (`a` and `b`). Returns the distance as a floating-point value. Useful for determining proximity between objects in 3D space + ### Lua Example `local numberValue = calc_abs_dist(a, b)` @@ -444,6 +465,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [calc_hor_dist](#calc_hor_dist) +### Description +Calculates the horizontal (XZ-plane) distance between two 3D points (`a` and `b`). Returns the distance as a floating-point value. Useful for terrain navigation or collision detection + ### Lua Example `local numberValue = calc_hor_dist(a, b)` @@ -465,6 +489,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [calculate_angles](#calculate_angles) +### Description +Calculates the pitch and yaw angles from one 3D position (`from`) to another (`to`). Updates the provided pointers with the computed pitch and yaw values + ### Lua Example `calculate_angles(from, to, pitch, yaw)` @@ -488,6 +515,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [calculate_pitch](#calculate_pitch) +### Description +Calculates the pitch angle (rotation around the X-axis) from one 3D point (`from`) to another (`to`). Returns the pitch as a signed 16-bit integer + ### Lua Example `local integerValue = calculate_pitch(from, to)` @@ -509,6 +539,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [calculate_yaw](#calculate_yaw) +### Description +Determines the yaw angle (rotation around the Y-axis) from one 3D position (`from`) to another (`to`). Returns the yaw as a signed 16-bit integer + ### Lua Example `local integerValue = calculate_yaw(from, to)` @@ -530,6 +563,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [cam_select_alt_mode](#cam_select_alt_mode) +### Description +Selects an alternate camera mode based on the given angle. Used to toggle between predefined camera modes dynamically + ### Lua Example `local integerValue = cam_select_alt_mode(angle)` @@ -550,6 +586,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [camera_approach_f32_symmetric](#camera_approach_f32_symmetric) +### Description +Symmetrically approaches a floating-point value (`target`) with a fixed increment (`increment`) per frame. Limits the rate of change to ensure gradual transitions + ### Lua Example `local numberValue = camera_approach_f32_symmetric(value, target, increment)` @@ -572,6 +611,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [camera_approach_f32_symmetric_bool](#camera_approach_f32_symmetric_bool) +### Description +Adjusts a floating-point value (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). Returns true if the value reaches the target and false otherwise + ### Lua Example `local integerValue = camera_approach_f32_symmetric_bool(current, target, increment)` @@ -594,6 +636,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [camera_approach_s16_symmetric_bool](#camera_approach_s16_symmetric_bool) +### Description +Adjusts a signed 16-bit integer (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). Returns true if the value reaches the target and false otherwise + ### Lua Example `local integerValue = camera_approach_s16_symmetric_bool(current, target, increment)` @@ -616,6 +661,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [camera_course_processing](#camera_course_processing) +### Description +Processes course-specific camera settings, such as predefined positions or modes. Adjusts the camera to match the design and gameplay requirements of the current course + ### Lua Example `local integerValue = camera_course_processing(c)` @@ -636,6 +684,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [camera_set_use_course_specific_settings](#camera_set_use_course_specific_settings) +### Description +Toggles whether the camera uses course-specific settings. This is useful for enabling or disabling custom behaviors in specific courses or areas + ### Lua Example `camera_set_use_course_specific_settings(enable)` @@ -656,6 +707,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [center_rom_hack_camera](#center_rom_hack_camera) +### Description +Centers the ROM hack camera. This function is designed for non-standard level layouts and modded game environments + ### Lua Example `center_rom_hack_camera()` @@ -674,6 +728,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [clamp_pitch](#clamp_pitch) +### Description +Clamps the camera's pitch angle between a maximum and minimum value. Prevents over-rotation and maintains a consistent viewing angle + ### Lua Example `local integerValue = clamp_pitch(from, to, maxPitch, minPitch)` @@ -697,6 +754,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [clamp_positions_and_find_yaw](#clamp_positions_and_find_yaw) +### Description +Clamps a position within specified X and Z bounds and calculates the yaw angle from the origin. Prevents the camera from moving outside of the designated area + ### Lua Example `local integerValue = clamp_positions_and_find_yaw(pos, origin, xMax, xMin, zMax, zMin)` @@ -722,6 +782,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [collide_with_walls](#collide_with_walls) +### Description +Checks for collisions between the camera and level geometry. Adjusts the camera's position to avoid clipping into walls or obstacles + ### Lua Example `local integerValue = collide_with_walls(pos, offsetY, radius)` @@ -744,6 +807,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [cutscene_object](#cutscene_object) +### Description +Initiates a cutscene focusing on a specific object in the game world. The camera transitions smoothly to the object, adapting its position as needed + ### Lua Example `local integerValue = cutscene_object(cutscene, o)` @@ -765,6 +831,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [cutscene_object_with_dialog](#cutscene_object_with_dialog) +### Description +Starts a cutscene involving an object and displays dialog during the sequence. The camera focuses on the object while synchronizing dialog with the scene + ### Lua Example `local integerValue = cutscene_object_with_dialog(cutscene, o, dialogID)` @@ -787,6 +856,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [cutscene_object_without_dialog](#cutscene_object_without_dialog) +### Description +Starts a cutscene involving an object without dialog. The camera transitions smoothly to focus on the object + ### Lua Example `local integerValue = cutscene_object_without_dialog(cutscene, o)` @@ -808,6 +880,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [cutscene_set_fov_shake_preset](#cutscene_set_fov_shake_preset) +### Description +Applies a preset field-of-view shake effect during a cutscene. This creates dynamic visual effects, such as zoom or focus disruptions + ### Lua Example `cutscene_set_fov_shake_preset(preset)` @@ -828,6 +903,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [cutscene_spawn_obj](#cutscene_spawn_obj) +### Description +Spawns an object as part of a cutscene, such as props or interactive elements. Returns the spawned object's reference for further manipulation + ### Lua Example `local integerValue = cutscene_spawn_obj(obj, frame)` @@ -849,6 +927,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [find_c_buttons_pressed](#find_c_buttons_pressed) +### Description +Determines which C-buttons are currently pressed by the player. Returns a bitmask indicating the active buttons for camera control + ### Lua Example `local integerValue = find_c_buttons_pressed(currentState, buttonsPressed, buttonsDown)` @@ -871,6 +952,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [find_mario_floor_and_ceil](#find_mario_floor_and_ceil) +### Description +Finds the floor and ceiling directly above and below Mario's position. Updates Mario's geometry information for camera calculations + ### Lua Example `find_mario_floor_and_ceil(pg)` @@ -891,6 +975,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [get_cutscene_from_mario_status](#get_cutscene_from_mario_status) +### Description +Gets the appropriate cutscene to play based on Mario's current gameplay state. This function helps determine transitions for cinematic or scripted sequences + ### Lua Example `local integerValue = get_cutscene_from_mario_status(c)` @@ -911,6 +998,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [handle_c_button_movement](#handle_c_button_movement) +### Description +Handles camera movement based on input from the C-buttons. Updates the camera's position or angle to match directional player input + ### Lua Example `handle_c_button_movement(c)` @@ -931,6 +1021,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [is_range_behind_surface](#is_range_behind_surface) +### Description +Determines if a range is obstructed by a surface relative to the camera. Returns true if the range is behind the specified surface + ### Lua Example `local integerValue = is_range_behind_surface(from, to, surf, range, surfType)` @@ -955,6 +1048,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [is_within_100_units_of_mario](#is_within_100_units_of_mario) +### Description +Checks if a position is within 100 units of Mario's current position. Returns true if the position is within the specified radius and false otherwise + ### Lua Example `local integerValue = is_within_100_units_of_mario(posX, posY, posZ)` @@ -977,6 +1073,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [move_mario_head_c_up](#move_mario_head_c_up) +### Description +Moves Mario's head slightly upward when the C-Up button is pressed. This function aligns the camera to match the head movement for consistency + ### Lua Example `move_mario_head_c_up(c)` @@ -997,6 +1096,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [next_lakitu_state](#next_lakitu_state) +### Description +Transitions the camera to the next Lakitu state, updating position and focus. This function handles smooth transitions between different gameplay scenarios + ### Lua Example `local integerValue = next_lakitu_state(newPos, newFoc, curPos, curFoc, oldPos, oldFoc, yaw)` @@ -1023,6 +1125,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [obj_rotate_towards_point](#obj_rotate_towards_point) +### Description +Rotates an object toward a specific point in 3D space. Gradually updates the object's pitch and yaw angles to face the target + ### Lua Example `obj_rotate_towards_point(o, point, pitchOff, yawOff, pitchDiv, yawDiv)` @@ -1048,6 +1153,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [object_pos_to_vec3f](#object_pos_to_vec3f) +### Description +Converts an object's position to a `Vec3f` format. Useful for aligning object behaviors or interactions with the camera system + ### Lua Example `object_pos_to_vec3f(dst, o)` @@ -1069,6 +1177,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [offset_rotated](#offset_rotated) +### Description +Offsets a vector by rotating it in 3D space relative to a reference position. This is useful for creating radial effects or dynamic transformations + ### Lua Example `offset_rotated(dst, from, to, rotation)` @@ -1092,6 +1203,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [offset_yaw_outward_radial](#offset_yaw_outward_radial) +### Description +Calculates an outward radial offset based on the camera's yaw angle. Returns the offset yaw, used for positioning or alignment + ### Lua Example `local integerValue = offset_yaw_outward_radial(c, areaYaw)` @@ -1113,6 +1227,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [play_camera_buzz_if_c_sideways](#play_camera_buzz_if_c_sideways) +### Description +Plays a buzzing sound effect when the camera's position is misaligned with the player's perspective. Used as audio feedback for incorrect camera behavior + ### Lua Example `play_camera_buzz_if_c_sideways()` @@ -1131,6 +1248,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [play_camera_buzz_if_cbutton](#play_camera_buzz_if_cbutton) +### Description +Plays a buzzing sound effect when a blocked C-button action is attempted. Used to signal invalid input or restricted camera movement + ### Lua Example `play_camera_buzz_if_cbutton()` @@ -1149,6 +1269,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [play_camera_buzz_if_cdown](#play_camera_buzz_if_cdown) +### Description +Plays a buzzing sound effect when the camera attempts to move downward but is restricted. Provides feedback for invalid C-Down input actions + ### Lua Example `play_camera_buzz_if_cdown()` @@ -1167,6 +1290,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [play_cutscene](#play_cutscene) +### Description +Starts the execution of a predefined cutscene. The camera transitions dynamically to follow the scripted sequence + ### Lua Example `play_cutscene(c)` @@ -1187,6 +1313,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [play_sound_button_change_blocked](#play_sound_button_change_blocked) +### Description +Plays a sound effect when a blocked action changes the camera mode. This provides feedback for invalid attempts to switch the camera state + ### Lua Example `play_sound_button_change_blocked()` @@ -1205,6 +1334,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [play_sound_cbutton_down](#play_sound_cbutton_down) +### Description +Plays a sound effect when the C-Down button is pressed for camera movement. Provides auditory feedback for valid camera input + ### Lua Example `play_sound_cbutton_down()` @@ -1223,6 +1355,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [play_sound_cbutton_side](#play_sound_cbutton_side) +### Description +Plays a sound effect when the C-Side button (left or right) is pressed for camera movement. Used as audio feedback for horizontal adjustments to the camera + ### Lua Example `play_sound_cbutton_side()` @@ -1241,6 +1376,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [play_sound_cbutton_up](#play_sound_cbutton_up) +### Description +Plays a sound effect when the C-Up button is pressed for camera movement. Provides feedback for vertical camera adjustments + ### Lua Example `play_sound_cbutton_up()` @@ -1259,6 +1397,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [play_sound_if_cam_switched_to_lakitu_or_mario](#play_sound_if_cam_switched_to_lakitu_or_mario) +### Description +Plays a sound effect when the camera switches between Lakitu and Mario perspectives. Signals a successful change in camera mode + ### Lua Example `play_sound_if_cam_switched_to_lakitu_or_mario()` @@ -1277,6 +1418,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [play_sound_rbutton_changed](#play_sound_rbutton_changed) +### Description +Plays a sound effect when the R-Button camera mode is changed. Provides feedback for toggling camera behaviors + ### Lua Example `play_sound_rbutton_changed()` @@ -1295,6 +1439,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [radial_camera_input](#radial_camera_input) +### Description +Handles radial camera movement based on player input. Updates the camera's position or orientation accordingly + ### Lua Example `local integerValue = radial_camera_input(c, unused)` @@ -1316,6 +1463,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [random_vec3s](#random_vec3s) +### Description +Generates a random 3D vector with short integer components. Useful for randomized offsets or environmental effects + ### Lua Example `random_vec3s(dst, xRange, yRange, zRange)` @@ -1339,6 +1489,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [reset_camera](#reset_camera) +### Description +Fully resets the camera to its default state and reinitializes all settings. This is typically used when restarting gameplay or loading a new area + ### Lua Example `reset_camera(c)` @@ -1359,6 +1512,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [resolve_geometry_collisions](#resolve_geometry_collisions) +### Description +Resolves collisions between the camera and level geometry. Adjusts the camera's position to prevent clipping or intersecting with objects + ### Lua Example `resolve_geometry_collisions(pos, lastGood)` @@ -1380,6 +1536,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [rom_hack_cam_set_collisions](#rom_hack_cam_set_collisions) +### Description +Toggles collision settings for the ROM hack camera. This enables or disables specific collision behaviors in modded levels + ### Lua Example `rom_hack_cam_set_collisions(enable)` @@ -1400,6 +1559,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [rotate_camera_around_walls](#rotate_camera_around_walls) +### Description +Rotates the camera to avoid walls or other obstructions. Ensures clear visibility of the player or target objects + ### Lua Example `local integerValue = rotate_camera_around_walls(c, cPos, avoidYaw, yawRange)` @@ -1423,6 +1585,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [rotate_in_xz](#rotate_in_xz) +### Description +Rotates a vector around the XZ-plane by a specified yaw angle. The result is stored in the destination vector (`dst`). Useful for rotating camera positions or object coordinates horizontally + ### Lua Example `rotate_in_xz(dst, src, yaw)` @@ -1445,6 +1610,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [rotate_in_yz](#rotate_in_yz) +### Description +Rotates a vector around the YZ-plane by a specified pitch angle. The result is stored in the destination vector (`dst`). Useful for vertical camera rotations or object transformations + ### Lua Example `rotate_in_yz(dst, src, pitch)` @@ -1467,6 +1635,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [scale_along_line](#scale_along_line) +### Description +Scales a point along a line between two 3D points (`from` and `to`). The scaling factor determines how far along the line the resulting point will be. The result is stored in the destination vector (`dest`) + ### Lua Example `scale_along_line(dest, from, to, scale)` @@ -1490,6 +1661,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [select_mario_cam_mode](#select_mario_cam_mode) +### Description +Selects the appropriate camera mode for Mario based on the current gameplay context. Adapts camera behavior dynamically to match Mario's environment or state + ### Lua Example `select_mario_cam_mode()` @@ -1508,6 +1682,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_cam_angle](#set_cam_angle) +### Description +Sets the camera's angle based on the specified mode. Handles rotation and focus adjustments for predefined camera behaviors + ### Lua Example `local integerValue = set_cam_angle(mode)` @@ -1528,6 +1705,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_camera_mode](#set_camera_mode) +### Description +Changes the camera to a new mode, optionally interpolating over a specified number of frames. Useful for transitioning between different camera behaviors dynamically + ### Lua Example `set_camera_mode(c, mode, frames)` @@ -1550,6 +1730,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_camera_mode_fixed](#set_camera_mode_fixed) +### Description +Activates a fixed camera mode and aligns the camera to specific X, Y, Z coordinates. This is useful for predefined static views in specific areas + ### Lua Example `local integerValue = set_camera_mode_fixed(c, x, y, z)` @@ -1573,6 +1756,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_camera_pitch_shake](#set_camera_pitch_shake) +### Description +Applies a pitch-based shake effect to the camera. The shake's magnitude, decay, and increment are configurable. Simulates vertical disturbances like impacts or explosions + ### Lua Example `set_camera_pitch_shake(mag, decay, inc)` @@ -1595,6 +1781,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_camera_roll_shake](#set_camera_roll_shake) +### Description +Applies a roll-based shake effect to the camera. Simulates rotational disturbances for dynamic camera effects + ### Lua Example `set_camera_roll_shake(mag, decay, inc)` @@ -1617,6 +1806,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_camera_shake_from_hit](#set_camera_shake_from_hit) +### Description +Applies a shake effect to the camera based on a hit type. Different shake types simulate various impacts, such as attacks, falls, or shocks + ### Lua Example `set_camera_shake_from_hit(shake)` @@ -1637,6 +1829,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_camera_shake_from_point](#set_camera_shake_from_point) +### Description +Applies a shake effect to the camera, scaled by its proximity to a specified point. The intensity decreases with distance from the point + ### Lua Example `set_camera_shake_from_point(shake, posX, posY, posZ)` @@ -1660,6 +1855,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_camera_yaw_shake](#set_camera_yaw_shake) +### Description +Applies a yaw-based shake effect to the camera. Simulates horizontal vibrations or rotational impacts + ### Lua Example `set_camera_yaw_shake(mag, decay, inc)` @@ -1682,6 +1880,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_environmental_camera_shake](#set_environmental_camera_shake) +### Description +Applies an environmental shake effect to the camera. Handles predefined shake types triggered by environmental events like explosions or platform movements + ### Lua Example `set_environmental_camera_shake(shake)` @@ -1702,6 +1903,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_fixed_cam_axis_sa_lobby](#set_fixed_cam_axis_sa_lobby) +### Description +Transitions the camera to the next Lakitu state, updating position and focus. This function handles smooth transitions between different gameplay scenarios + ### Lua Example `set_fixed_cam_axis_sa_lobby(preset)` @@ -1722,6 +1926,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_fov_function](#set_fov_function) +### Description +Assigns a custom function for dynamic field-of-view adjustments. This allows precise control over the camera's zoom behavior during gameplay + ### Lua Example `set_fov_function(func)` @@ -1742,6 +1949,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_fov_shake](#set_fov_shake) +### Description +Applies a field-of-view shake effect to simulate zoom or focus disruptions. Shake parameters, such as amplitude and decay, control the intensity + ### Lua Example `set_fov_shake(amplitude, decay, shakeSpeed)` @@ -1764,6 +1974,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_fov_shake_from_point_preset](#set_fov_shake_from_point_preset) +### Description +Applies a preset field-of-view shake effect relative to a specific point. The intensity diminishes as the distance from the point increases + ### Lua Example `set_fov_shake_from_point_preset(preset, posX, posY, posZ)` @@ -1787,6 +2000,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_handheld_shake](#set_handheld_shake) +### Description +Applies a handheld camera shake effect with configurable parameters. Can be used to simulate dynamic, realistic camera movement + ### Lua Example `set_handheld_shake(mode)` @@ -1807,6 +2023,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_or_approach_f32_asymptotic](#set_or_approach_f32_asymptotic) +### Description +Smoothly transitions or directly sets a floating-point value (`dst`) to approach a target (`goal`). Uses asymptotic scaling for gradual adjustments or direct assignment + ### Lua Example `local integerValue = set_or_approach_f32_asymptotic(dst, goal, scale)` @@ -1829,6 +2048,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_or_approach_s16_symmetric](#set_or_approach_s16_symmetric) +### Description +Smoothly transitions or directly sets a signed 16-bit value (`current`) to approach a target (`target`). Uses symmetric scaling for gradual or immediate adjustments + ### Lua Example `local integerValue = set_or_approach_s16_symmetric(current, target, increment)` @@ -1851,6 +2073,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_or_approach_vec3f_asymptotic](#set_or_approach_vec3f_asymptotic) +### Description +Smoothly transitions a 3D vector (`current`) toward a target vector (`goal`) using asymptotic scaling. Allows gradual or instantaneous alignment of 3D positions. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component + ### Lua Example `set_or_approach_vec3f_asymptotic(dst, goal, xMul, yMul, zMul)` @@ -1875,6 +2100,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [set_pitch_shake_from_point](#set_pitch_shake_from_point) +### Description +Applies a pitch shake effect to the camera, scaled by proximity to a specified point. Simulates vibrations with intensity decreasing further from the point + ### Lua Example `set_pitch_shake_from_point(mag, decay, inc, maxDist, posX, posY, posZ)` @@ -1901,6 +2129,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [shake_camera_handheld](#shake_camera_handheld) +### Description +Activates a handheld camera shake effect. Calculates positional and focus adjustments to simulate manual movement + ### Lua Example `shake_camera_handheld(pos, focus)` @@ -1922,6 +2153,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [shake_camera_pitch](#shake_camera_pitch) +### Description +Activates a pitch-based shake effect. Adds vertical vibrational movement to the camera's behavior + ### Lua Example `shake_camera_pitch(pos, focus)` @@ -1943,6 +2177,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [shake_camera_roll](#shake_camera_roll) +### Description +Applies a roll-based shake effect to the camera. Simulates rotational disturbances caused by impacts or other events + ### Lua Example `shake_camera_roll(roll)` @@ -1963,6 +2200,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [shake_camera_yaw](#shake_camera_yaw) +### Description +Activates a yaw-based shake effect. Adds horizontal vibrational movement to the camera's behavior + ### Lua Example `shake_camera_yaw(pos, focus)` @@ -1984,6 +2224,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [skip_camera_interpolation](#skip_camera_interpolation) +### Description +Skips camera interpolation for a frame, locking the camera instantly to the target position. Useful for immediate changes in camera state or position without smooth transitions + ### Lua Example `skip_camera_interpolation()` @@ -2002,6 +2245,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [soft_reset_camera](#soft_reset_camera) +### Description +Resets the camera's state while retaining some settings, such as position or mode. This is often used when soft-resetting gameplay without reinitialization + ### Lua Example `soft_reset_camera(c)` @@ -2022,6 +2268,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [start_cutscene](#start_cutscene) +### Description +Starts a cutscene based on the provided ID. The camera transitions to predefined behaviors for the duration of the cutscene + ### Lua Example `start_cutscene(c, cutscene)` @@ -2043,6 +2292,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [start_object_cutscene_without_focus](#start_object_cutscene_without_focus) +### Description +Starts a cutscene focused on an object without requiring focus to remain locked. This is useful for dynamic events where the camera adjusts freely + ### Lua Example `local integerValue = start_object_cutscene_without_focus(cutscene)` @@ -2063,6 +2315,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [transition_next_state](#transition_next_state) +### Description +Transitions the camera to the next state over a specified number of frames. This is typically used for cutscenes or scripted sequences + ### Lua Example `transition_next_state(c, frames)` @@ -2084,6 +2339,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [trigger_cutscene_dialog](#trigger_cutscene_dialog) +### Description +Triggers a dialog sequence during a cutscene. The dialog is synchronized with the camera's position and movement + ### Lua Example `local integerValue = trigger_cutscene_dialog(trigger)` @@ -2104,6 +2362,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [vec3f_sub](#vec3f_sub) +### Description +Subtracts one 3D vector (`src`) from another (`dst`). Stores the result in the destination vector + ### Lua Example `vec3f_sub(dst, src)` @@ -2125,6 +2386,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [vec3f_to_object_pos](#vec3f_to_object_pos) +### Description +Converts a `Vec3f` position to an object's internal format. Useful for syncing 3D positions between objects and the game world + ### Lua Example `vec3f_to_object_pos(o, src)` @@ -2146,6 +2410,9 @@ Gets a behavior ID from only vanilla behavior scripts ## [warp_camera](#warp_camera) +### Description +Moves the camera to a specified warp destination. This function handles transitions between levels or areas seamlessly + ### Lua Example `warp_camera(displacementX, displacementY, displacementZ)` @@ -7616,817 +7883,6 @@ Creates a warp node in the current level and area with id `id` that goes to the [:arrow_up_small:](#) -
- ---- -# functions from mario_actions_moving.c - -
- - -## [align_with_floor](#align_with_floor) - -### Lua Example -`align_with_floor(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- None - -### C Prototype -`void align_with_floor(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [analog_stick_held_back](#analog_stick_held_back) - -### Lua Example -`local integerValue = analog_stick_held_back(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s32 analog_stick_held_back(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [anim_and_audio_for_heavy_walk](#anim_and_audio_for_heavy_walk) - -### Lua Example -`anim_and_audio_for_heavy_walk(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- None - -### C Prototype -`void anim_and_audio_for_heavy_walk(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [anim_and_audio_for_hold_walk](#anim_and_audio_for_hold_walk) - -### Lua Example -`anim_and_audio_for_hold_walk(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- None - -### C Prototype -`void anim_and_audio_for_hold_walk(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [anim_and_audio_for_walk](#anim_and_audio_for_walk) - -### Lua Example -`anim_and_audio_for_walk(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- None - -### C Prototype -`void anim_and_audio_for_walk(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [apply_landing_accel](#apply_landing_accel) - -### Lua Example -`local integerValue = apply_landing_accel(m, frictionFactor)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| frictionFactor | `number` | - -### Returns -- `integer` - -### C Prototype -`s32 apply_landing_accel(struct MarioState *m, f32 frictionFactor);` - -[:arrow_up_small:](#) - -
- -## [apply_slope_accel](#apply_slope_accel) - -### Lua Example -`apply_slope_accel(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- None - -### C Prototype -`void apply_slope_accel(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [apply_slope_decel](#apply_slope_decel) - -### Lua Example -`local integerValue = apply_slope_decel(m, decelCoef)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| decelCoef | `number` | - -### Returns -- `integer` - -### C Prototype -`s32 apply_slope_decel(struct MarioState *m, f32 decelCoef);` - -[:arrow_up_small:](#) - -
- -## [begin_braking_action](#begin_braking_action) - -### Lua Example -`local integerValue = begin_braking_action(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s32 begin_braking_action(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [begin_walking_action](#begin_walking_action) - -### Lua Example -`local integerValue = begin_walking_action(m, forwardVel, action, actionArg)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| forwardVel | `number` | -| action | `integer` | -| actionArg | `integer` | - -### Returns -- `integer` - -### C Prototype -`s32 begin_walking_action(struct MarioState *m, f32 forwardVel, u32 action, u32 actionArg);` - -[:arrow_up_small:](#) - -
- -## [check_common_moving_cancels](#check_common_moving_cancels) - -### Lua Example -`local integerValue = check_common_moving_cancels(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s32 check_common_moving_cancels(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [check_ground_dive_or_punch](#check_ground_dive_or_punch) - -### Lua Example -`local integerValue = check_ground_dive_or_punch(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s32 check_ground_dive_or_punch(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [check_ledge_climb_down](#check_ledge_climb_down) - -### Lua Example -`check_ledge_climb_down(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- None - -### C Prototype -`void check_ledge_climb_down(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [common_ground_knockback_action](#common_ground_knockback_action) - -### Lua Example -`local integerValue = common_ground_knockback_action(m, animation, arg2, arg3, arg4)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| animation | `integer` | -| arg2 | `integer` | -| arg3 | `integer` | -| arg4 | `integer` | - -### Returns -- `integer` - -### C Prototype -`s32 common_ground_knockback_action(struct MarioState *m, s32 animation, s32 arg2, s32 arg3, s32 arg4);` - -[:arrow_up_small:](#) - -
- -## [common_landing_action](#common_landing_action) - -### Lua Example -`local integerValue = common_landing_action(m, animation, airAction)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| animation | `integer` | -| airAction | `integer` | - -### Returns -- `integer` - -### C Prototype -`u32 common_landing_action(struct MarioState *m, s16 animation, u32 airAction);` - -[:arrow_up_small:](#) - -
- -## [common_slide_action](#common_slide_action) - -### Lua Example -`common_slide_action(m, endAction, airAction, animation)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| endAction | `integer` | -| airAction | `integer` | -| animation | `integer` | - -### Returns -- None - -### C Prototype -`void common_slide_action(struct MarioState *m, u32 endAction, u32 airAction, s32 animation);` - -[:arrow_up_small:](#) - -
- -## [common_slide_action_with_jump](#common_slide_action_with_jump) - -### Lua Example -`local integerValue = common_slide_action_with_jump(m, stopAction, jumpAction, airAction, animation)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| stopAction | `integer` | -| jumpAction | `integer` | -| airAction | `integer` | -| animation | `integer` | - -### Returns -- `integer` - -### C Prototype -`s32 common_slide_action_with_jump(struct MarioState *m, u32 stopAction, u32 jumpAction, u32 airAction, s32 animation);` - -[:arrow_up_small:](#) - -
- -## [mario_execute_moving_action](#mario_execute_moving_action) - -### Lua Example -`local integerValue = mario_execute_moving_action(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s32 mario_execute_moving_action(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [play_step_sound](#play_step_sound) - -### Lua Example -`play_step_sound(m, frame1, frame2)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| frame1 | `integer` | -| frame2 | `integer` | - -### Returns -- None - -### C Prototype -`void play_step_sound(struct MarioState *m, s16 frame1, s16 frame2);` - -[:arrow_up_small:](#) - -
- -## [push_or_sidle_wall](#push_or_sidle_wall) - -### Lua Example -`push_or_sidle_wall(m, startPos)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| startPos | [Vec3f](structs.md#Vec3f) | - -### Returns -- None - -### C Prototype -`void push_or_sidle_wall(struct MarioState *m, Vec3f startPos);` - -[:arrow_up_small:](#) - -
- -## [quicksand_jump_land_action](#quicksand_jump_land_action) - -### Lua Example -`local integerValue = quicksand_jump_land_action(m, animation1, animation2, endAction, airAction)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| animation1 | `integer` | -| animation2 | `integer` | -| endAction | `integer` | -| airAction | `integer` | - -### Returns -- `integer` - -### C Prototype -`s32 quicksand_jump_land_action(struct MarioState *m, s32 animation1, s32 animation2, u32 endAction, u32 airAction);` - -[:arrow_up_small:](#) - -
- -## [set_triple_jump_action](#set_triple_jump_action) - -### Lua Example -`local integerValue = set_triple_jump_action(m, action, actionArg)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| action | `integer` | -| actionArg | `integer` | - -### Returns -- `integer` - -### C Prototype -`s32 set_triple_jump_action(struct MarioState *m, UNUSED u32 action, UNUSED u32 actionArg);` - -[:arrow_up_small:](#) - -
- -## [should_begin_sliding](#should_begin_sliding) - -### Lua Example -`local integerValue = should_begin_sliding(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s32 should_begin_sliding(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [slide_bonk](#slide_bonk) - -### Lua Example -`slide_bonk(m, fastAction, slowAction)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| fastAction | `integer` | -| slowAction | `integer` | - -### Returns -- None - -### C Prototype -`void slide_bonk(struct MarioState *m, u32 fastAction, u32 slowAction);` - -[:arrow_up_small:](#) - -
- -## [stomach_slide_action](#stomach_slide_action) - -### Lua Example -`local integerValue = stomach_slide_action(m, stopAction, airAction, animation)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| stopAction | `integer` | -| airAction | `integer` | -| animation | `integer` | - -### Returns -- `integer` - -### C Prototype -`s32 stomach_slide_action(struct MarioState *m, u32 stopAction, u32 airAction, s32 animation);` - -[:arrow_up_small:](#) - -
- -## [tilt_body_butt_slide](#tilt_body_butt_slide) - -### Lua Example -`tilt_body_butt_slide(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- None - -### C Prototype -`void tilt_body_butt_slide(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [tilt_body_ground_shell](#tilt_body_ground_shell) - -### Lua Example -`tilt_body_ground_shell(m, startYaw)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| startYaw | `integer` | - -### Returns -- None - -### C Prototype -`void tilt_body_ground_shell(struct MarioState *m, s16 startYaw);` - -[:arrow_up_small:](#) - -
- -## [tilt_body_running](#tilt_body_running) - -### Lua Example -`local integerValue = tilt_body_running(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s16 tilt_body_running(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [tilt_body_walking](#tilt_body_walking) - -### Lua Example -`tilt_body_walking(m, startYaw)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| startYaw | `integer` | - -### Returns -- None - -### C Prototype -`void tilt_body_walking(struct MarioState *m, s16 startYaw);` - -[:arrow_up_small:](#) - -
- -## [update_decelerating_speed](#update_decelerating_speed) - -### Lua Example -`local integerValue = update_decelerating_speed(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s32 update_decelerating_speed(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [update_shell_speed](#update_shell_speed) - -### Lua Example -`update_shell_speed(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- None - -### C Prototype -`void update_shell_speed(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [update_sliding](#update_sliding) - -### Lua Example -`local integerValue = update_sliding(m, stopSpeed)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| stopSpeed | `number` | - -### Returns -- `integer` - -### C Prototype -`s32 update_sliding(struct MarioState *m, f32 stopSpeed);` - -[:arrow_up_small:](#) - -
- -## [update_sliding_angle](#update_sliding_angle) - -### Lua Example -`update_sliding_angle(m, accel, lossFactor)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| accel | `number` | -| lossFactor | `number` | - -### Returns -- None - -### C Prototype -`void update_sliding_angle(struct MarioState *m, f32 accel, f32 lossFactor);` - -[:arrow_up_small:](#) - -
- -## [update_walking_speed](#update_walking_speed) - -### Lua Example -`update_walking_speed(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- None - -### C Prototype -`void update_walking_speed(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- ---- -# functions from mario_actions_object.c - -
- - -## [animated_stationary_ground_step](#animated_stationary_ground_step) - -### Lua Example -`animated_stationary_ground_step(m, animation, endAction)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | -| animation | `integer` | -| endAction | `integer` | - -### Returns -- None - -### C Prototype -`void animated_stationary_ground_step(struct MarioState *m, s32 animation, u32 endAction);` - -[:arrow_up_small:](#) - -
- -## [check_common_object_cancels](#check_common_object_cancels) - -### Lua Example -`local integerValue = check_common_object_cancels(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s32 check_common_object_cancels(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [mario_execute_object_action](#mario_execute_object_action) - -### Lua Example -`local integerValue = mario_execute_object_action(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s32 mario_execute_object_action(struct MarioState *m);` - -[:arrow_up_small:](#) - -
- -## [mario_update_punch_sequence](#mario_update_punch_sequence) - -### Lua Example -`local integerValue = mario_update_punch_sequence(m)` - -### Parameters -| Field | Type | -| ----- | ---- | -| m | [MarioState](structs.md#MarioState) | - -### Returns -- `integer` - -### C Prototype -`s32 mario_update_punch_sequence(struct MarioState *m);` - -[:arrow_up_small:](#) -
--- diff --git a/docs/lua/functions-4.md b/docs/lua/functions-4.md index 05932fc20..67b12ad6f 100644 --- a/docs/lua/functions-4.md +++ b/docs/lua/functions-4.md @@ -5,6 +5,817 @@ [< prev](functions-3.md) | [1](functions.md) | [2](functions-2.md) | [3](functions-3.md) | 4 | [5](functions-5.md) | [6](functions-6.md) | [next >](functions-5.md)] +--- +# functions from mario_actions_moving.c + +
+ + +## [align_with_floor](#align_with_floor) + +### Lua Example +`align_with_floor(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- None + +### C Prototype +`void align_with_floor(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [analog_stick_held_back](#analog_stick_held_back) + +### Lua Example +`local integerValue = analog_stick_held_back(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s32 analog_stick_held_back(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [anim_and_audio_for_heavy_walk](#anim_and_audio_for_heavy_walk) + +### Lua Example +`anim_and_audio_for_heavy_walk(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- None + +### C Prototype +`void anim_and_audio_for_heavy_walk(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [anim_and_audio_for_hold_walk](#anim_and_audio_for_hold_walk) + +### Lua Example +`anim_and_audio_for_hold_walk(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- None + +### C Prototype +`void anim_and_audio_for_hold_walk(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [anim_and_audio_for_walk](#anim_and_audio_for_walk) + +### Lua Example +`anim_and_audio_for_walk(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- None + +### C Prototype +`void anim_and_audio_for_walk(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [apply_landing_accel](#apply_landing_accel) + +### Lua Example +`local integerValue = apply_landing_accel(m, frictionFactor)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| frictionFactor | `number` | + +### Returns +- `integer` + +### C Prototype +`s32 apply_landing_accel(struct MarioState *m, f32 frictionFactor);` + +[:arrow_up_small:](#) + +
+ +## [apply_slope_accel](#apply_slope_accel) + +### Lua Example +`apply_slope_accel(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- None + +### C Prototype +`void apply_slope_accel(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [apply_slope_decel](#apply_slope_decel) + +### Lua Example +`local integerValue = apply_slope_decel(m, decelCoef)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| decelCoef | `number` | + +### Returns +- `integer` + +### C Prototype +`s32 apply_slope_decel(struct MarioState *m, f32 decelCoef);` + +[:arrow_up_small:](#) + +
+ +## [begin_braking_action](#begin_braking_action) + +### Lua Example +`local integerValue = begin_braking_action(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s32 begin_braking_action(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [begin_walking_action](#begin_walking_action) + +### Lua Example +`local integerValue = begin_walking_action(m, forwardVel, action, actionArg)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| forwardVel | `number` | +| action | `integer` | +| actionArg | `integer` | + +### Returns +- `integer` + +### C Prototype +`s32 begin_walking_action(struct MarioState *m, f32 forwardVel, u32 action, u32 actionArg);` + +[:arrow_up_small:](#) + +
+ +## [check_common_moving_cancels](#check_common_moving_cancels) + +### Lua Example +`local integerValue = check_common_moving_cancels(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s32 check_common_moving_cancels(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [check_ground_dive_or_punch](#check_ground_dive_or_punch) + +### Lua Example +`local integerValue = check_ground_dive_or_punch(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s32 check_ground_dive_or_punch(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [check_ledge_climb_down](#check_ledge_climb_down) + +### Lua Example +`check_ledge_climb_down(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- None + +### C Prototype +`void check_ledge_climb_down(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [common_ground_knockback_action](#common_ground_knockback_action) + +### Lua Example +`local integerValue = common_ground_knockback_action(m, animation, arg2, arg3, arg4)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| animation | `integer` | +| arg2 | `integer` | +| arg3 | `integer` | +| arg4 | `integer` | + +### Returns +- `integer` + +### C Prototype +`s32 common_ground_knockback_action(struct MarioState *m, s32 animation, s32 arg2, s32 arg3, s32 arg4);` + +[:arrow_up_small:](#) + +
+ +## [common_landing_action](#common_landing_action) + +### Lua Example +`local integerValue = common_landing_action(m, animation, airAction)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| animation | `integer` | +| airAction | `integer` | + +### Returns +- `integer` + +### C Prototype +`u32 common_landing_action(struct MarioState *m, s16 animation, u32 airAction);` + +[:arrow_up_small:](#) + +
+ +## [common_slide_action](#common_slide_action) + +### Lua Example +`common_slide_action(m, endAction, airAction, animation)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| endAction | `integer` | +| airAction | `integer` | +| animation | `integer` | + +### Returns +- None + +### C Prototype +`void common_slide_action(struct MarioState *m, u32 endAction, u32 airAction, s32 animation);` + +[:arrow_up_small:](#) + +
+ +## [common_slide_action_with_jump](#common_slide_action_with_jump) + +### Lua Example +`local integerValue = common_slide_action_with_jump(m, stopAction, jumpAction, airAction, animation)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| stopAction | `integer` | +| jumpAction | `integer` | +| airAction | `integer` | +| animation | `integer` | + +### Returns +- `integer` + +### C Prototype +`s32 common_slide_action_with_jump(struct MarioState *m, u32 stopAction, u32 jumpAction, u32 airAction, s32 animation);` + +[:arrow_up_small:](#) + +
+ +## [mario_execute_moving_action](#mario_execute_moving_action) + +### Lua Example +`local integerValue = mario_execute_moving_action(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s32 mario_execute_moving_action(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [play_step_sound](#play_step_sound) + +### Lua Example +`play_step_sound(m, frame1, frame2)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| frame1 | `integer` | +| frame2 | `integer` | + +### Returns +- None + +### C Prototype +`void play_step_sound(struct MarioState *m, s16 frame1, s16 frame2);` + +[:arrow_up_small:](#) + +
+ +## [push_or_sidle_wall](#push_or_sidle_wall) + +### Lua Example +`push_or_sidle_wall(m, startPos)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| startPos | [Vec3f](structs.md#Vec3f) | + +### Returns +- None + +### C Prototype +`void push_or_sidle_wall(struct MarioState *m, Vec3f startPos);` + +[:arrow_up_small:](#) + +
+ +## [quicksand_jump_land_action](#quicksand_jump_land_action) + +### Lua Example +`local integerValue = quicksand_jump_land_action(m, animation1, animation2, endAction, airAction)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| animation1 | `integer` | +| animation2 | `integer` | +| endAction | `integer` | +| airAction | `integer` | + +### Returns +- `integer` + +### C Prototype +`s32 quicksand_jump_land_action(struct MarioState *m, s32 animation1, s32 animation2, u32 endAction, u32 airAction);` + +[:arrow_up_small:](#) + +
+ +## [set_triple_jump_action](#set_triple_jump_action) + +### Lua Example +`local integerValue = set_triple_jump_action(m, action, actionArg)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| action | `integer` | +| actionArg | `integer` | + +### Returns +- `integer` + +### C Prototype +`s32 set_triple_jump_action(struct MarioState *m, UNUSED u32 action, UNUSED u32 actionArg);` + +[:arrow_up_small:](#) + +
+ +## [should_begin_sliding](#should_begin_sliding) + +### Lua Example +`local integerValue = should_begin_sliding(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s32 should_begin_sliding(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [slide_bonk](#slide_bonk) + +### Lua Example +`slide_bonk(m, fastAction, slowAction)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| fastAction | `integer` | +| slowAction | `integer` | + +### Returns +- None + +### C Prototype +`void slide_bonk(struct MarioState *m, u32 fastAction, u32 slowAction);` + +[:arrow_up_small:](#) + +
+ +## [stomach_slide_action](#stomach_slide_action) + +### Lua Example +`local integerValue = stomach_slide_action(m, stopAction, airAction, animation)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| stopAction | `integer` | +| airAction | `integer` | +| animation | `integer` | + +### Returns +- `integer` + +### C Prototype +`s32 stomach_slide_action(struct MarioState *m, u32 stopAction, u32 airAction, s32 animation);` + +[:arrow_up_small:](#) + +
+ +## [tilt_body_butt_slide](#tilt_body_butt_slide) + +### Lua Example +`tilt_body_butt_slide(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- None + +### C Prototype +`void tilt_body_butt_slide(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [tilt_body_ground_shell](#tilt_body_ground_shell) + +### Lua Example +`tilt_body_ground_shell(m, startYaw)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| startYaw | `integer` | + +### Returns +- None + +### C Prototype +`void tilt_body_ground_shell(struct MarioState *m, s16 startYaw);` + +[:arrow_up_small:](#) + +
+ +## [tilt_body_running](#tilt_body_running) + +### Lua Example +`local integerValue = tilt_body_running(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s16 tilt_body_running(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [tilt_body_walking](#tilt_body_walking) + +### Lua Example +`tilt_body_walking(m, startYaw)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| startYaw | `integer` | + +### Returns +- None + +### C Prototype +`void tilt_body_walking(struct MarioState *m, s16 startYaw);` + +[:arrow_up_small:](#) + +
+ +## [update_decelerating_speed](#update_decelerating_speed) + +### Lua Example +`local integerValue = update_decelerating_speed(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s32 update_decelerating_speed(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [update_shell_speed](#update_shell_speed) + +### Lua Example +`update_shell_speed(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- None + +### C Prototype +`void update_shell_speed(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [update_sliding](#update_sliding) + +### Lua Example +`local integerValue = update_sliding(m, stopSpeed)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| stopSpeed | `number` | + +### Returns +- `integer` + +### C Prototype +`s32 update_sliding(struct MarioState *m, f32 stopSpeed);` + +[:arrow_up_small:](#) + +
+ +## [update_sliding_angle](#update_sliding_angle) + +### Lua Example +`update_sliding_angle(m, accel, lossFactor)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| accel | `number` | +| lossFactor | `number` | + +### Returns +- None + +### C Prototype +`void update_sliding_angle(struct MarioState *m, f32 accel, f32 lossFactor);` + +[:arrow_up_small:](#) + +
+ +## [update_walking_speed](#update_walking_speed) + +### Lua Example +`update_walking_speed(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- None + +### C Prototype +`void update_walking_speed(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +--- +# functions from mario_actions_object.c + +
+ + +## [animated_stationary_ground_step](#animated_stationary_ground_step) + +### Lua Example +`animated_stationary_ground_step(m, animation, endAction)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | +| animation | `integer` | +| endAction | `integer` | + +### Returns +- None + +### C Prototype +`void animated_stationary_ground_step(struct MarioState *m, s32 animation, u32 endAction);` + +[:arrow_up_small:](#) + +
+ +## [check_common_object_cancels](#check_common_object_cancels) + +### Lua Example +`local integerValue = check_common_object_cancels(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s32 check_common_object_cancels(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [mario_execute_object_action](#mario_execute_object_action) + +### Lua Example +`local integerValue = mario_execute_object_action(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s32 mario_execute_object_action(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ +## [mario_update_punch_sequence](#mario_update_punch_sequence) + +### Lua Example +`local integerValue = mario_update_punch_sequence(m)` + +### Parameters +| Field | Type | +| ----- | ---- | +| m | [MarioState](structs.md#MarioState) | + +### Returns +- `integer` + +### C Prototype +`s32 mario_update_punch_sequence(struct MarioState *m);` + +[:arrow_up_small:](#) + +
+ --- # functions from mario_actions_stationary.c diff --git a/docs/lua/functions.md b/docs/lua/functions.md index fd6e9f6f8..0d3951f35 100644 --- a/docs/lua/functions.md +++ b/docs/lua/functions.md @@ -1047,48 +1047,48 @@
- mario_actions_moving.c - - [align_with_floor](functions-3.md#align_with_floor) - - [analog_stick_held_back](functions-3.md#analog_stick_held_back) - - [anim_and_audio_for_heavy_walk](functions-3.md#anim_and_audio_for_heavy_walk) - - [anim_and_audio_for_hold_walk](functions-3.md#anim_and_audio_for_hold_walk) - - [anim_and_audio_for_walk](functions-3.md#anim_and_audio_for_walk) - - [apply_landing_accel](functions-3.md#apply_landing_accel) - - [apply_slope_accel](functions-3.md#apply_slope_accel) - - [apply_slope_decel](functions-3.md#apply_slope_decel) - - [begin_braking_action](functions-3.md#begin_braking_action) - - [begin_walking_action](functions-3.md#begin_walking_action) - - [check_common_moving_cancels](functions-3.md#check_common_moving_cancels) - - [check_ground_dive_or_punch](functions-3.md#check_ground_dive_or_punch) - - [check_ledge_climb_down](functions-3.md#check_ledge_climb_down) - - [common_ground_knockback_action](functions-3.md#common_ground_knockback_action) - - [common_landing_action](functions-3.md#common_landing_action) - - [common_slide_action](functions-3.md#common_slide_action) - - [common_slide_action_with_jump](functions-3.md#common_slide_action_with_jump) - - [mario_execute_moving_action](functions-3.md#mario_execute_moving_action) - - [play_step_sound](functions-3.md#play_step_sound) - - [push_or_sidle_wall](functions-3.md#push_or_sidle_wall) - - [quicksand_jump_land_action](functions-3.md#quicksand_jump_land_action) - - [set_triple_jump_action](functions-3.md#set_triple_jump_action) - - [should_begin_sliding](functions-3.md#should_begin_sliding) - - [slide_bonk](functions-3.md#slide_bonk) - - [stomach_slide_action](functions-3.md#stomach_slide_action) - - [tilt_body_butt_slide](functions-3.md#tilt_body_butt_slide) - - [tilt_body_ground_shell](functions-3.md#tilt_body_ground_shell) - - [tilt_body_running](functions-3.md#tilt_body_running) - - [tilt_body_walking](functions-3.md#tilt_body_walking) - - [update_decelerating_speed](functions-3.md#update_decelerating_speed) - - [update_shell_speed](functions-3.md#update_shell_speed) - - [update_sliding](functions-3.md#update_sliding) - - [update_sliding_angle](functions-3.md#update_sliding_angle) - - [update_walking_speed](functions-3.md#update_walking_speed) + - [align_with_floor](functions-4.md#align_with_floor) + - [analog_stick_held_back](functions-4.md#analog_stick_held_back) + - [anim_and_audio_for_heavy_walk](functions-4.md#anim_and_audio_for_heavy_walk) + - [anim_and_audio_for_hold_walk](functions-4.md#anim_and_audio_for_hold_walk) + - [anim_and_audio_for_walk](functions-4.md#anim_and_audio_for_walk) + - [apply_landing_accel](functions-4.md#apply_landing_accel) + - [apply_slope_accel](functions-4.md#apply_slope_accel) + - [apply_slope_decel](functions-4.md#apply_slope_decel) + - [begin_braking_action](functions-4.md#begin_braking_action) + - [begin_walking_action](functions-4.md#begin_walking_action) + - [check_common_moving_cancels](functions-4.md#check_common_moving_cancels) + - [check_ground_dive_or_punch](functions-4.md#check_ground_dive_or_punch) + - [check_ledge_climb_down](functions-4.md#check_ledge_climb_down) + - [common_ground_knockback_action](functions-4.md#common_ground_knockback_action) + - [common_landing_action](functions-4.md#common_landing_action) + - [common_slide_action](functions-4.md#common_slide_action) + - [common_slide_action_with_jump](functions-4.md#common_slide_action_with_jump) + - [mario_execute_moving_action](functions-4.md#mario_execute_moving_action) + - [play_step_sound](functions-4.md#play_step_sound) + - [push_or_sidle_wall](functions-4.md#push_or_sidle_wall) + - [quicksand_jump_land_action](functions-4.md#quicksand_jump_land_action) + - [set_triple_jump_action](functions-4.md#set_triple_jump_action) + - [should_begin_sliding](functions-4.md#should_begin_sliding) + - [slide_bonk](functions-4.md#slide_bonk) + - [stomach_slide_action](functions-4.md#stomach_slide_action) + - [tilt_body_butt_slide](functions-4.md#tilt_body_butt_slide) + - [tilt_body_ground_shell](functions-4.md#tilt_body_ground_shell) + - [tilt_body_running](functions-4.md#tilt_body_running) + - [tilt_body_walking](functions-4.md#tilt_body_walking) + - [update_decelerating_speed](functions-4.md#update_decelerating_speed) + - [update_shell_speed](functions-4.md#update_shell_speed) + - [update_sliding](functions-4.md#update_sliding) + - [update_sliding_angle](functions-4.md#update_sliding_angle) + - [update_walking_speed](functions-4.md#update_walking_speed)
- mario_actions_object.c - - [animated_stationary_ground_step](functions-3.md#animated_stationary_ground_step) - - [check_common_object_cancels](functions-3.md#check_common_object_cancels) - - [mario_execute_object_action](functions-3.md#mario_execute_object_action) - - [mario_update_punch_sequence](functions-3.md#mario_update_punch_sequence) + - [animated_stationary_ground_step](functions-4.md#animated_stationary_ground_step) + - [check_common_object_cancels](functions-4.md#check_common_object_cancels) + - [mario_execute_object_action](functions-4.md#mario_execute_object_action) + - [mario_update_punch_sequence](functions-4.md#mario_update_punch_sequence)
diff --git a/src/game/camera.h b/src/game/camera.h index e69636762..8918aa091 100644 --- a/src/game/camera.h +++ b/src/game/camera.h @@ -694,107 +694,562 @@ extern struct Object *gCutsceneFocus; extern struct Object *gSecondCameraFocus; extern u8 gRecentCutscene; +/* |description| +Skips camera interpolation for a frame, locking the camera instantly to the target position. +Useful for immediate changes in camera state or position without smooth transitions +|descriptionEnd| */ void skip_camera_interpolation(void); + +/* |description| +Applies a shake effect to the camera based on a hit type. +Different shake types simulate various impacts, such as attacks, falls, or shocks +|descriptionEnd| */ void set_camera_shake_from_hit(s16 shake); + +/* |description| +Applies an environmental shake effect to the camera. +Handles predefined shake types triggered by environmental events like explosions or platform movements +|descriptionEnd| */ void set_environmental_camera_shake(s16 shake); + +/* |description| +Applies a shake effect to the camera, scaled by its proximity to a specified point. +The intensity decreases with distance from the point +|descriptionEnd| */ void set_camera_shake_from_point(s16 shake, f32 posX, f32 posY, f32 posZ); + +/* |description| +Moves Mario's head slightly upward when the C-Up button is pressed. +This function aligns the camera to match the head movement for consistency +|descriptionEnd| */ void move_mario_head_c_up(UNUSED struct Camera *c); + +/* |description| +Transitions the camera to the next state over a specified number of frames. +This is typically used for cutscenes or scripted sequences +|descriptionEnd| */ void transition_next_state(UNUSED struct Camera *c, s16 frames); + +/* |description| +Changes the camera to a new mode, optionally interpolating over a specified number of frames. +Useful for transitioning between different camera behaviors dynamically +|descriptionEnd| */ void set_camera_mode(struct Camera *c, s16 mode, s16 frames); + void update_camera(struct Camera *c); + +/* |description| +Resets the camera's state while retaining some settings, such as position or mode. +This is often used when soft-resetting gameplay without reinitialization +|descriptionEnd| */ void soft_reset_camera(struct Camera* c); + +/* |description| +Fully resets the camera to its default state and reinitializes all settings. +This is typically used when restarting gameplay or loading a new area +|descriptionEnd| */ void reset_camera(struct Camera *c); + void init_camera(struct Camera *c); + +/* |description| +Selects the appropriate camera mode for Mario based on the current gameplay context. +Adapts camera behavior dynamically to match Mario's environment or state +|descriptionEnd| */ void select_mario_cam_mode(void); + Gfx *geo_camera_main(s32 callContext, struct GraphNode *g, void *context); + void stub_camera_2(UNUSED struct Camera *c); + void stub_camera_3(UNUSED struct Camera *c); + +/* |description| +Subtracts one 3D vector (`src`) from another (`dst`). +Stores the result in the destination vector +|descriptionEnd| */ void vec3f_sub(Vec3f dst, Vec3f src); + +/* |description| +Converts an object's position to a `Vec3f` format. +Useful for aligning object behaviors or interactions with the camera system +|descriptionEnd| */ void object_pos_to_vec3f(Vec3f dst, struct Object *o); + +/* |description| +Converts a `Vec3f` position to an object's internal format. +Useful for syncing 3D positions between objects and the game world +|descriptionEnd| */ void vec3f_to_object_pos(struct Object *o, Vec3f src); + s32 move_point_along_spline(Vec3f p, struct CutsceneSplinePoint spline[], s16 *splineSegment, f32 *progress); + +/* |description| +Selects an alternate camera mode based on the given angle. +Used to toggle between predefined camera modes dynamically +|descriptionEnd| */ s32 cam_select_alt_mode(s32 angle); + +/* |description| +Sets the camera's angle based on the specified mode. +Handles rotation and focus adjustments for predefined camera behaviors +|descriptionEnd| */ s32 set_cam_angle(s32 mode); + +/* |description| +Applies a handheld camera shake effect with configurable parameters. +Can be used to simulate dynamic, realistic camera movement +|descriptionEnd| */ void set_handheld_shake(u8 mode); + +/* |description| +Activates a handheld camera shake effect. +Calculates positional and focus adjustments to simulate manual movement +|descriptionEnd| */ void shake_camera_handheld(Vec3f pos, Vec3f focus); + +/* |description| +Determines which C-buttons are currently pressed by the player. +Returns a bitmask indicating the active buttons for camera control +|descriptionEnd| */ s32 find_c_buttons_pressed(u16 currentState, u16 buttonsPressed, u16 buttonsDown); + s32 update_camera_hud_status(struct Camera *c); + +/* |description| +Checks for collisions between the camera and level geometry. +Adjusts the camera's position to avoid clipping into walls or obstacles +|descriptionEnd| */ s32 collide_with_walls(Vec3f pos, f32 offsetY, f32 radius); + +/* |description| +Clamps the camera's pitch angle between a maximum and minimum value. +Prevents over-rotation and maintains a consistent viewing angle +|descriptionEnd| */ s32 clamp_pitch(Vec3f from, Vec3f to, s16 maxPitch, s16 minPitch); + +/* |description| +Checks if a position is within 100 units of Mario's current position. +Returns true if the position is within the specified radius and false otherwise +|descriptionEnd| */ s32 is_within_100_units_of_mario(f32 posX, f32 posY, f32 posZ); + + +/* |description| +Smoothly transitions or directly sets a floating-point value (`dst`) to approach a target (`goal`). +Uses asymptotic scaling for gradual adjustments or direct assignment +|descriptionEnd| */ s32 set_or_approach_f32_asymptotic(f32 *dst, f32 goal, f32 scale); + + +/* |description| +Gradually adjusts a floating-point value (`current`) towards a target (`target`) using asymptotic smoothing. +Returns true if `current` reaches the `target` and false otherwise +|descriptionEnd| */ s32 approach_f32_asymptotic_bool(f32 *current, f32 target, f32 multiplier); + +/* |description| +Gradually approaches a floating-point value (`target`) using asymptotic smoothing. +The rate of approach is controlled by the `multiplier`. +Useful for smoothly adjusting camera parameters like field-of-view or position +|descriptionEnd| */ f32 approach_f32_asymptotic(f32 current, f32 target, f32 multiplier); + +/* |description| +Gradually adjusts a signed 16-bit integer (`current`) towards a target (`target`) using asymptotic smoothing. +Returns true if `current` reaches `target` and false otherwise +|descriptionEnd| */ s32 approach_s16_asymptotic_bool(s16 *current, s16 target, s16 divisor); + +/* |description| +Gradually approaches a signed 16-bit integer (`target`) using asymptotic smoothing. +The divisor controls the rate of the adjustment. +Useful for adjusting angles or positions smoothly +|descriptionEnd| */ s32 approach_s16_asymptotic(s16 current, s16 target, s16 divisor); + +/* |description| +Smoothly transitions a 3D vector (`current`) towards a target vector (`target`) using asymptotic scaling. +Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component +|descriptionEnd| */ void approach_vec3f_asymptotic(Vec3f current, Vec3f target, f32 xMul, f32 yMul, f32 zMul); + +/* |description| +Smoothly transitions a 3D vector (`current`) toward a target vector (`goal`) using asymptotic scaling. +Allows gradual or instantaneous alignment of 3D positions. Scaling values (the `Mul` variables) for x, y, and z axes determine the speed of adjustment for each component +|descriptionEnd| */ void set_or_approach_vec3f_asymptotic(Vec3f dst, Vec3f goal, f32 xMul, f32 yMul, f32 zMul); + +/* |description| +Adjusts a signed 16-bit integer (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). +Returns true if the value reaches the target and false otherwise +|descriptionEnd| */ s32 camera_approach_s16_symmetric_bool(s16 *current, s16 target, s16 increment); + +/* |description| +Smoothly transitions or directly sets a signed 16-bit value (`current`) to approach a target (`target`). +Uses symmetric scaling for gradual or immediate adjustments +|descriptionEnd| */ s32 set_or_approach_s16_symmetric(s16 *current, s16 target, s16 increment); + +/* |description| +Adjusts a floating-point value (`current`) towards a target (`target`) symmetrically with a fixed increment (`increment`). +Returns true if the value reaches the target and false otherwise +|descriptionEnd| */ s32 camera_approach_f32_symmetric_bool(f32 *current, f32 target, f32 increment); + +/* |description| +Symmetrically approaches a floating-point value (`target`) with a fixed increment (`increment`) per frame. +Limits the rate of change to ensure gradual transitions +|descriptionEnd| */ f32 camera_approach_f32_symmetric(f32 value, f32 target, f32 increment); + +/* |description| +Generates a random 3D vector with short integer components. +Useful for randomized offsets or environmental effects +|descriptionEnd| */ void random_vec3s(Vec3s dst, s16 xRange, s16 yRange, s16 zRange); + +/* |description| +Clamps a position within specified X and Z bounds and calculates the yaw angle from the origin. +Prevents the camera from moving outside of the designated area +|descriptionEnd| */ s32 clamp_positions_and_find_yaw(Vec3f pos, Vec3f origin, f32 xMax, f32 xMin, f32 zMax, f32 zMin); + +/* |description| +Determines if a range is obstructed by a surface relative to the camera. +Returns true if the range is behind the specified surface +|descriptionEnd| */ s32 is_range_behind_surface(Vec3f from, Vec3f to, struct Surface *surf, s16 range, s16 surfType); + +/* |description| +Scales a point along a line between two 3D points (`from` and `to`). +The scaling factor determines how far along the line the resulting point will be. +The result is stored in the destination vector (`dest`) +|descriptionEnd| */ void scale_along_line(Vec3f dest, Vec3f from, Vec3f to, f32 scale); + +/* |description| +Calculates the pitch angle (rotation around the X-axis) from one 3D point (`from`) to another (`to`). +Returns the pitch as a signed 16-bit integer +|descriptionEnd| */ s16 calculate_pitch(Vec3f from, Vec3f to); + +/* |description| +Determines the yaw angle (rotation around the Y-axis) from one 3D position (`from`) to another (`to`). +Returns the yaw as a signed 16-bit integer +|descriptionEnd| */ s16 calculate_yaw(Vec3f from, Vec3f to); + +/* |description| +Calculates the pitch and yaw angles from one 3D position (`from`) to another (`to`). +Updates the provided pointers with the computed pitch and yaw values +|descriptionEnd| */ void calculate_angles(Vec3f from, Vec3f to, s16 *pitch, s16 *yaw); + +/* |description| +Calculates the absolute distance between two 3D points (`a` and `b`). +Returns the distance as a floating-point value. +Useful for determining proximity between objects in 3D space +|descriptionEnd| */ f32 calc_abs_dist(Vec3f a, Vec3f b); + +/* |description| +Calculates the horizontal (XZ-plane) distance between two 3D points (`a` and `b`). +Returns the distance as a floating-point value. +Useful for terrain navigation or collision detection +|descriptionEnd| */ f32 calc_hor_dist(Vec3f a, Vec3f b); + +/* |description| +Rotates a vector around the XZ-plane by a specified yaw angle. +The result is stored in the destination vector (`dst`). +Useful for rotating camera positions or object coordinates horizontally +|descriptionEnd| */ void rotate_in_xz(Vec3f dst, Vec3f src, s16 yaw); + +/* |description| +Rotates a vector around the YZ-plane by a specified pitch angle. +The result is stored in the destination vector (`dst`). +Useful for vertical camera rotations or object transformations +|descriptionEnd| */ void rotate_in_yz(Vec3f dst, Vec3f src, s16 pitch); + +/* |description| +Applies a pitch-based shake effect to the camera. +The shake's magnitude, decay, and increment are configurable. +Simulates vertical disturbances like impacts or explosions +|descriptionEnd| */ void set_camera_pitch_shake(s16 mag, s16 decay, s16 inc); + +/* |description| +Applies a yaw-based shake effect to the camera. +Simulates horizontal vibrations or rotational impacts +|descriptionEnd| */ void set_camera_yaw_shake(s16 mag, s16 decay, s16 inc); + +/* |description| +Applies a roll-based shake effect to the camera. +Simulates rotational disturbances for dynamic camera effects +|descriptionEnd| */ void set_camera_roll_shake(s16 mag, s16 decay, s16 inc); + +/* |description| +Applies a pitch shake effect to the camera, scaled by proximity to a specified point. +Simulates vibrations with intensity decreasing further from the point +|descriptionEnd| */ void set_pitch_shake_from_point(s16 mag, s16 decay, s16 inc, f32 maxDist, f32 posX, f32 posY, f32 posZ); + +/* |description| +Activates a pitch-based shake effect. +Adds vertical vibrational movement to the camera's behavior +|descriptionEnd| */ void shake_camera_pitch(Vec3f pos, Vec3f focus); + +/* |description| +Activates a yaw-based shake effect. +Adds horizontal vibrational movement to the camera's behavior +|descriptionEnd| */ void shake_camera_yaw(Vec3f pos, Vec3f focus); + +/* |description| +Applies a roll-based shake effect to the camera. +Simulates rotational disturbances caused by impacts or other events +|descriptionEnd| */ void shake_camera_roll(s16 *roll); + +/* |description| +Calculates an outward radial offset based on the camera's yaw angle. +Returns the offset yaw, used for positioning or alignment +|descriptionEnd| */ s32 offset_yaw_outward_radial(struct Camera *c, s16 areaYaw); + +/* |description| +Plays a buzzing sound effect when the camera attempts to move downward but is restricted. +Provides feedback for invalid C-Down input actions +|descriptionEnd| */ void play_camera_buzz_if_cdown(void); + +/* |description| +Plays a buzzing sound effect when a blocked C-button action is attempted. +Used to signal invalid input or restricted camera movement +|descriptionEnd| */ void play_camera_buzz_if_cbutton(void); + +/* |description| +Plays a buzzing sound effect when the camera's position is misaligned with the player's perspective. +Used as audio feedback for incorrect camera behavior +|descriptionEnd| */ void play_camera_buzz_if_c_sideways(void); + +/* |description| +Plays a sound effect when the C-Up button is pressed for camera movement. +Provides feedback for vertical camera adjustments +|descriptionEnd| */ void play_sound_cbutton_up(void); + +/* |description| +Plays a sound effect when the C-Down button is pressed for camera movement. +Provides auditory feedback for valid camera input +|descriptionEnd| */ void play_sound_cbutton_down(void); + +/* |description| +Plays a sound effect when the C-Side button (left or right) is pressed for camera movement. +Used as audio feedback for horizontal adjustments to the camera +|descriptionEnd| */ void play_sound_cbutton_side(void); + +/* |description| +Plays a sound effect when a blocked action changes the camera mode. +This provides feedback for invalid attempts to switch the camera state +|descriptionEnd| */ void play_sound_button_change_blocked(void); + +/* |description| +Plays a sound effect when the R-Button camera mode is changed. +Provides feedback for toggling camera behaviors +|descriptionEnd| */ void play_sound_rbutton_changed(void); + +/* |description| +Plays a sound effect when the camera switches between Lakitu and Mario perspectives. +Signals a successful change in camera mode +|descriptionEnd| */ void play_sound_if_cam_switched_to_lakitu_or_mario(void); + +/* |description| +Handles radial camera movement based on player input. +Updates the camera's position or orientation accordingly +|descriptionEnd| */ s32 radial_camera_input(struct Camera *c, UNUSED f32 unused); + +/* |description| +Triggers a dialog sequence during a cutscene. +The dialog is synchronized with the camera's position and movement +|descriptionEnd| */ s32 trigger_cutscene_dialog(s32 trigger); + +/* |description| +Handles camera movement based on input from the C-buttons. +Updates the camera's position or angle to match directional player input +|descriptionEnd| */ void handle_c_button_movement(struct Camera *c); + +/* |description| +Starts a cutscene based on the provided ID. +The camera transitions to predefined behaviors for the duration of the cutscene +|descriptionEnd| */ void start_cutscene(struct Camera *c, u8 cutscene); + +/* |description| +Gets the appropriate cutscene to play based on Mario's current gameplay state. +This function helps determine transitions for cinematic or scripted sequences +|descriptionEnd| */ u8 get_cutscene_from_mario_status(struct Camera *c); + +/* |description| +Moves the camera to a specified warp destination. +This function handles transitions between levels or areas seamlessly +|descriptionEnd| */ void warp_camera(f32 displacementX, f32 displacementY, f32 displacementZ); + +/* |description| +Adjusts the camera's height toward a target value (`goalHeight`) while respecting terrain and obstructions. +This is really wonky and probably shouldn't be used, prefer `gLakituStates` +|descriptionEnd| */ void approach_camera_height(struct Camera *c, f32 goal, f32 inc); + +/* |description| +Offsets a vector by rotating it in 3D space relative to a reference position. +This is useful for creating radial effects or dynamic transformations +|descriptionEnd| */ void offset_rotated(Vec3f dst, Vec3f from, Vec3f to, Vec3s rotation); + +/* |description| +Transitions the camera to the next Lakitu state, updating position and focus. +This function handles smooth transitions between different gameplay scenarios +|descriptionEnd| */ s16 next_lakitu_state(Vec3f newPos, Vec3f newFoc, Vec3f curPos, Vec3f curFoc, Vec3f oldPos, Vec3f oldFoc, s16 yaw); + void set_fixed_cam_axis_sa_lobby(UNUSED s16 preset); +/* |description| +Processes course-specific camera settings, such as predefined positions or modes. +Adjusts the camera to match the design and gameplay requirements of the current course +|descriptionEnd| */ s16 camera_course_processing(struct Camera *c); + +/* |description| +Resolves collisions between the camera and level geometry. +Adjusts the camera's position to prevent clipping or intersecting with objects +|descriptionEnd| */ void resolve_geometry_collisions(Vec3f pos, UNUSED Vec3f lastGood); + +/* |description| +Rotates the camera to avoid walls or other obstructions. +Ensures clear visibility of the player or target objects +|descriptionEnd| */ s32 rotate_camera_around_walls(struct Camera *c, Vec3f cPos, s16 *avoidYaw, s16 yawRange); + + +/* |description| +Finds the floor and ceiling directly above and below Mario's position. +Updates Mario's geometry information for camera calculations +|descriptionEnd| */ void find_mario_floor_and_ceil(struct PlayerGeometry *pg); + +/* |description| +Starts a cutscene focused on an object without requiring focus to remain locked. +This is useful for dynamic events where the camera adjusts freely +|descriptionEnd| */ u8 start_object_cutscene_without_focus(u8 cutscene); + +/* |description| +Starts a cutscene involving an object and displays dialog during the sequence. +The camera focuses on the object while synchronizing dialog with the scene +|descriptionEnd| */ s16 cutscene_object_with_dialog(u8 cutscene, struct Object *o, s16 dialogID); + +/* |description| +Starts a cutscene involving an object without dialog. +The camera transitions smoothly to focus on the object +|descriptionEnd| */ s16 cutscene_object_without_dialog(u8 cutscene, struct Object *o); + +/* |description| +Initiates a cutscene focusing on a specific object in the game world. +The camera transitions smoothly to the object, adapting its position as needed +|descriptionEnd| */ s16 cutscene_object(u8 cutscene, struct Object *o); + +/* |description| +Starts the execution of a predefined cutscene. +The camera transitions dynamically to follow the scripted sequence +|descriptionEnd| */ void play_cutscene(struct Camera *c); + s32 cutscene_event(CameraEvent event, struct Camera * c, s16 start, s16 end); + +/* |description| +Spawns an object as part of a cutscene, such as props or interactive elements. +Returns the spawned object's reference for further manipulation +|descriptionEnd| */ s32 cutscene_spawn_obj(u32 obj, s16 frame); + +/* |description| +Applies a field-of-view shake effect to simulate zoom or focus disruptions. +Shake parameters, such as amplitude and decay, control the intensity +|descriptionEnd| */ void set_fov_shake(s16 amplitude, s16 decay, s16 shakeSpeed); +/* |description| +Assigns a custom function for dynamic field-of-view adjustments. +This allows precise control over the camera's zoom behavior during gameplay +|descriptionEnd| */ void set_fov_function(u8 func); + +/* |description| +Applies a preset field-of-view shake effect during a cutscene. +This creates dynamic visual effects, such as zoom or focus disruptions +|descriptionEnd| */ void cutscene_set_fov_shake_preset(u8 preset); + +/* |description| +Applies a preset field-of-view shake effect relative to a specific point. +The intensity diminishes as the distance from the point increases +|descriptionEnd| */ void set_fov_shake_from_point_preset(u8 preset, f32 posX, f32 posY, f32 posZ); + +/* |description| +Rotates an object toward a specific point in 3D space. +Gradually updates the object's pitch and yaw angles to face the target +|descriptionEnd| */ void obj_rotate_towards_point(struct Object *o, Vec3f point, s16 pitchOff, s16 yawOff, s16 pitchDiv, s16 yawDiv); Gfx *geo_camera_fov(s32 callContext, struct GraphNode *g, UNUSED void *context); +/* |description| +Activates a fixed camera mode and aligns the camera to specific X, Y, Z coordinates. +This is useful for predefined static views in specific areas +|descriptionEnd| */ s32 set_camera_mode_fixed(struct Camera* c, s16 x, s16 y, s16 z); +/* |description| +Toggles whether the camera uses course-specific settings. +This is useful for enabling or disabling custom behaviors in specific courses or areas +|descriptionEnd| */ void camera_set_use_course_specific_settings(u8 enable); + +/* |description| +Toggles collision settings for the ROM hack camera. +This enables or disables specific collision behaviors in modded levels +|descriptionEnd| */ void rom_hack_cam_set_collisions(u8 enable); + +/* |description| +Centers the ROM hack camera. +This function is designed for non-standard level layouts and modded game environments +|descriptionEnd| */ void center_rom_hack_camera(void); #endif // CAMERA_H