redscript-mc 2.6.2 → 3.0.0

package/src/stdlib/physics.mcrs

@@ -11,69 +11,134 @@ module library;
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
+/// Minecraft gravity constant in fixed-point units (0.08 blocks/tick² × 100 = 8).
+/// @since 1.0.0
+/// @returns  8 (gravity acceleration per tick in ×100 units)
 fn gravity_fx(): int { return 8; }      // 0.08 blocks/tick² × 100
+
+/// Air drag factor in ×10000 scale (0.98 per tick).
+/// @since 1.0.0
+/// @returns  9800 (multiply velocity by this / 10000 each tick)
 fn air_drag_fx(): int { return 9800; }  // 0.98 drag factor × 10000 (per tick)
+
+/// Water drag factor in ×10000 scale (0.80 per tick, stronger than air).
+/// @since 1.0.0
+/// @returns  8000 (multiply velocity by this / 10000 each tick while in water)
 fn water_drag_fx(): int { return 8000; } // 0.80 drag (in water)
 
 // ─── Projectile motion ────────────────────────────────────────────────────────
 
-// projectile_pos(p0, v0, t): position after t ticks with initial velocity v0
-// p0, v0: ×100 (blocks × 100), t: ticks
-// No drag, constant gravity
+/// Compute Y position of a projectile after t ticks (no drag, constant gravity).
+/// @since 1.0.0
+/// @param p0  Initial Y position ×100 (blocks × 100)
+/// @param v0  Initial Y velocity ×100 (blocks/tick × 100)
+/// @param t   Time in ticks
+/// @returns  Y position at tick t: p0 + v0*t - gravity*t²/2
+/// @example
+/// let y: int = projectile_y(0, 200, 5)  // height after 5 ticks, launched at 2 blocks/tick
 fn projectile_y(p0: int, v0: int, t: int): int {
     return p0 + v0 * t - gravity_fx() * t * t / 2;
 }
 
+/// Compute horizontal X position of a projectile after t ticks (constant velocity, no drag).
+/// @since 1.0.0
+/// @param p0  Initial X position ×100
+/// @param v0  Horizontal X velocity ×100
+/// @param t   Time in ticks
+/// @returns  X position at tick t: p0 + v0*t
+/// @example
+/// let x: int = projectile_x(0, 100, 10)  // 10 blocks/tick for 10 ticks = 1000 units
 fn projectile_x(p0: int, v0: int, t: int): int {
     return p0 + v0 * t;
 }
 
-// projectile_vy(v0, t): Y velocity after t ticks (with gravity)
+/// Compute Y velocity of a projectile after t ticks (accounting for gravity).
+/// @since 1.0.0
+/// @param v0  Initial Y velocity ×100
+/// @param t   Time in ticks
+/// @returns  v0 - gravity*t
+/// @example
+/// let vy: int = projectile_vy(200, 5)  // velocity after 5 ticks
 fn projectile_vy(v0: int, t: int): int {
     return v0 - gravity_fx() * t;
 }
 
-// projectile_land_t(v0y): approximate tick when Y returns to 0
-// t = 2*v0y / gravity
+/// Estimate the tick at which a projectile launched upward returns to Y=0.
+/// @since 1.0.0
+/// @param v0y  Initial upward Y velocity ×100 (must be positive)
+/// @returns  2*v0y / gravity; returns 0 if v0y <= 0
+/// @example
+/// let land_t: int = projectile_land_t(160)  // ticks until landing
 fn projectile_land_t(v0y: int): int {
     if (v0y <= 0) { return 0; }
     return 2 * v0y / gravity_fx();
 }
 
-// projectile_max_height(v0y): maximum height reached ×100
-// h = v0y² / (2*gravity)
+/// Compute the maximum height reached by a projectile launched upward.
+/// @since 1.0.0
+/// @param v0y  Initial upward Y velocity ×100
+/// @returns  v0y² / (2*gravity) in ×100 units
+/// @example
+/// let max_h: int = projectile_max_height(160)  // peak height in units×100
 fn projectile_max_height(v0y: int): int {
     return v0y * v0y / (2 * gravity_fx());
 }
 
 // ─── Velocity with drag ───────────────────────────────────────────────────────
 
-// apply_drag(v_fx, drag_fx): apply drag to velocity
-// v_fx: velocity ×100, drag_fx: drag factor ×10000
+/// Apply a drag factor to a velocity (one tick of drag).
+/// @since 1.0.0
+/// @param v_fx     Velocity ×100
+/// @param drag_fx  Drag factor ×10000 (9800 for air, 8000 for water)
+/// @returns  v_fx * drag_fx / 10000
+/// @example
+/// let v: int = apply_drag(500, air_drag_fx())  // 500 * 0.98 = 490
 fn apply_drag(v_fx: int, drag_fx: int): int {
     return v_fx * drag_fx / 10000;
 }
 
-// apply_gravity(vy_fx): apply one tick of gravity to Y velocity
+/// Apply one tick of gravity to a Y velocity component.
+/// @since 1.0.0
+/// @param vy_fx  Current Y velocity ×100
+/// @returns  vy_fx - gravity_fx()
+/// @example
+/// vy = apply_gravity(vy)  // call each tick in your physics loop
 fn apply_gravity(vy_fx: int): int {
     return vy_fx - gravity_fx();
 }
 
-// update_pos(p_fx, v_fx): update position by one tick
+/// Update a position component by one tick of velocity.
+/// @since 1.0.0
+/// @param p_fx  Current position ×100
+/// @param v_fx  Velocity ×100
+/// @returns  p_fx + v_fx
+/// @example
+/// px = update_pos(px, vx)  // advance X each tick
 fn update_pos(p_fx: int, v_fx: int): int {
     return p_fx + v_fx;
 }
 
 // ─── Collision / bounce ───────────────────────────────────────────────────────
 
-// bounce_v(v_fx, restitution_fx): reflect velocity with energy loss
-// restitution_fx ×10000: 10000=elastic, 5000=half energy, 0=inelastic
+/// Reflect a velocity component with energy loss (bounce).
+/// @since 1.0.0
+/// @param v_fx            Velocity ×100 to reflect
+/// @param restitution_fx  Energy retention ×10000 (10000=elastic, 5000=half, 0=inelastic)
+/// @returns  Negated and scaled velocity: -v_fx * restitution / 10000
+/// @example
+/// vy = bounce_v(vy, 7000)  // 70% energy retained on bounce
 fn bounce_v(v_fx: int, restitution_fx: int): int {
     let neg: int = 0 - v_fx;
     return neg * restitution_fx / 10000;
 }
 
-// clamp_velocity(v_fx, max_fx): clamp speed to max
+/// Clamp a velocity component to a maximum absolute speed.
+/// @since 1.0.0
+/// @param v_fx    Velocity ×100 to clamp
+/// @param max_fx  Maximum absolute velocity ×100 (terminal velocity)
+/// @returns  v_fx clamped to [-max_fx, max_fx]
+/// @example
+/// vx = clamp_velocity(vx, 500)  // cap horizontal speed at 5 blocks/tick
 fn clamp_velocity(v_fx: int, max_fx: int): int {
     if (v_fx > max_fx) { return max_fx; }
     if (v_fx < 0 - max_fx) { return 0 - max_fx; }
@@ -82,14 +147,28 @@ fn clamp_velocity(v_fx: int, max_fx: int): int {
 
 // ─── Spring physics ───────────────────────────────────────────────────────────
 
-// spring_force(pos_fx, target_fx, k_fx): Hooke's law F = -k(x - target)
-// k_fx: spring constant ×10000
+/// Compute spring force toward a target position (Hooke's law: F = -k*(x - target)).
+/// @since 1.0.0
+/// @param pos_fx     Current position ×100
+/// @param target_fx  Rest/target position ×100
+/// @param k_fx       Spring constant ×10000 (higher = stiffer spring)
+/// @returns  (target - pos) * k / 10000
+/// @example
+/// let f: int = spring_force(pos, 500, 2000)  // spring toward position 500 with k=0.2
 fn spring_force(pos_fx: int, target_fx: int, k_fx: int): int {
     return (target_fx - pos_fx) * k_fx / 10000;
 }
 
-// spring_update_v(v_fx, pos_fx, target_fx, k_fx, damping_fx):
-// update velocity with spring force and damping
+/// Update velocity with spring force and damping (one tick).
+/// @since 1.0.0
+/// @param v_fx       Current velocity ×100
+/// @param pos_fx     Current position ×100
+/// @param target_fx  Spring rest position ×100
+/// @param k_fx       Spring constant ×10000
+/// @param damping_fx Damping factor ×10000 (10000=no damping, 8000=some damping)
+/// @returns  New velocity after applying spring force and damping
+/// @example
+/// vx = spring_update_v(vx, px, target_px, 1000, 9000)
 fn spring_update_v(v_fx: int, pos_fx: int, target_fx: int, k_fx: int, damping_fx: int): int {
     let force: int = spring_force(pos_fx, target_fx, k_fx);
     let damped: int = v_fx * damping_fx / 10000;
@@ -98,20 +177,39 @@ fn spring_update_v(v_fx: int, pos_fx: int, target_fx: int, k_fx: int, damping_fx
 
 // ─── Circular motion ─────────────────────────────────────────────────────────
 
-// circular_x(cx, r, angle_deg): X position on circle
-// cx: center X ×100, r: radius ×100, angle_deg: degrees (NOT ×10000)
+/// Compute X position on a circle given center, radius, and angle.
+/// @since 1.0.0
+/// @param cx        Circle center X ×100
+/// @param r         Radius ×100
+/// @param angle_deg Angle in whole degrees (NOT ×10000)
+/// @returns  cx + r * cos(angle_deg) / 1000
+/// @example
+/// let x: int = circular_x(500, 200, 45)  // point at 45° on radius-2 circle
 fn circular_x(cx: int, r: int, angle_deg: int): int {
     return cx + r * cos_fixed(angle_deg) / 1000;
 }
 
+/// Compute Z position on a circle given center, radius, and angle.
+/// @since 1.0.0
+/// @param cz        Circle center Z ×100
+/// @param r         Radius ×100
+/// @param angle_deg Angle in whole degrees (NOT ×10000)
+/// @returns  cz + r * sin(angle_deg) / 1000
+/// @example
+/// let z: int = circular_z(500, 200, 45)
 fn circular_z(cz: int, r: int, angle_deg: int): int {
     return cz + r * sin_fixed(angle_deg) / 1000;
 }
 
 // ─── Friction ────────────────────────────────────────────────────────────────
 
-// friction_decel(v_fx, friction_fx): reduce velocity toward zero by friction
-// friction_fx ×100: amount subtracted per tick (absolute)
+/// Apply friction to reduce a velocity component toward zero.
+/// @since 1.0.0
+/// @param v_fx        Current velocity ×100
+/// @param friction_fx Friction deceleration per tick ×100 (absolute amount subtracted)
+/// @returns  Velocity reduced toward 0 by friction; stops at 0 rather than reversing
+/// @example
+/// vx = friction_decel(vx, 10)  // slow down by 0.1 blocks/tick per tick
 fn friction_decel(v_fx: int, friction_fx: int): int {
     if (v_fx > friction_fx) { return v_fx - friction_fx; }
     if (v_fx < 0 - friction_fx) { return v_fx + friction_fx; }
@@ -120,14 +218,24 @@ fn friction_decel(v_fx: int, friction_fx: int): int {
 
 // ─── Impact detection ────────────────────────────────────────────────────────
 
-// is_grounded(y_fx, ground_y_fx): returns 1 if at or below ground
+/// Check whether a position has reached or fallen below the ground level.
+/// @since 1.0.0
+/// @param y_fx       Current Y position ×100
+/// @param ground_y_fx Ground Y level ×100
+/// @returns  1 if y_fx <= ground_y_fx (grounded), 0 otherwise
+/// @example
+/// if (is_grounded(py, 0) == 1) { py = 0; vy = bounce_v(vy, 7000); }
 fn is_grounded(y_fx: int, ground_y_fx: int): int {
     if (y_fx <= ground_y_fx) { return 1; }
     return 0;
 }
 
-// impact_velocity(h_fx): velocity after falling from height h (blocks ×100)
-// v = sqrt(2*g*h), approximated
+/// Estimate the impact velocity after falling from a given height.
+/// @since 1.0.0
+/// @param h_fx  Fall height ×100 (blocks × 100, must be positive)
+/// @returns  Approximate impact speed ×100 via integer square root of 2*g*h
+/// @example
+/// let impact_v: int = impact_velocity(400)  // falling from 4 blocks
 fn impact_velocity(h_fx: int): int {
     if (h_fx <= 0) { return 0; }
     return isqrt(2 * gravity_fx() * h_fx / 100) * 10;

package/src/stdlib/player.mcrs

@@ -1,12 +1,24 @@
 // Player helpers built on scoreboard/tag patterns.
 // These helpers target the nearest player via @p.
 
+/// Heal the nearest player by adding `amount` to their #health scoreboard.
+/// @since 1.0.0
+/// @param amount  Number of health points to restore (positive integer)
+/// @returns  void — modifies the #health scoreboard objective of @p
+/// @example
+/// heal(10)  // restore 10 HP to nearest player
 fn heal(amount: int) {
     let health: int = scoreboard_get(@p, #health);
     let next: int = health + amount;
     scoreboard_set(@p, #health, next);
 }
 
+/// Deal damage to the nearest player, clamping health to a minimum of 0.
+/// @since 1.0.0
+/// @param amount  Number of damage points to apply (positive integer)
+/// @returns  void — modifies the #health scoreboard objective of @p; will not go below 0
+/// @example
+/// damage(5)  // deal 5 damage to nearest player
 fn damage(amount: int) {
     let health: int = scoreboard_get(@p, #health);
     let next: int = health - amount;
@@ -18,6 +30,12 @@ fn damage(amount: int) {
     }
 }
 
+/// Check whether the nearest player has the `op` tag (operator status).
+/// @since 1.0.0
+/// @returns  1 if @p has the `op` entity tag, 0 otherwise
+/// @example
+/// let admin: int = is_op()
+/// // if (admin == 1) { ... }
 fn is_op() -> int {
     let result: int = 0;
 

package/src/stdlib/quaternion.mcrs

@@ -14,69 +14,211 @@ module library;
 
 // ─── Constructors ─────────────────────────────────────────────────────────────
 
-// quat_identity: returns W component of identity quaternion (x=y=z=0, w=1)
+/// W component of the identity quaternion `(0, 0, 0, 1)`.
+///
+/// @since 2.0.0
+/// @returns  `10000`
 fn quat_identity_w(): int { return 10000; }
+
+/// X component of the identity quaternion.
+///
+/// @since 2.0.0
+/// @returns  `0`
 fn quat_identity_x(): int { return 0; }
+
+/// Y component of the identity quaternion.
+///
+/// @since 2.0.0
+/// @returns  `0`
 fn quat_identity_y(): int { return 0; }
+
+/// Z component of the identity quaternion.
+///
+/// @since 2.0.0
+/// @returns  `0`
 fn quat_identity_z(): int { return 0; }
 
-// quat_from_axis_x: rotation around X axis by angle degrees
-// sin_fixed/cos_fixed return ×1000; we scale to ×10000 by multiplying by 10
-// angle_deg: degrees (integer)
+/// X component of a quaternion representing rotation by `angle_deg` around the X axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees (integer)
+/// @returns          `sin(angle/2)` ×10000
 fn quat_axis_x_x(angle_deg: int): int { return sin_fixed(angle_deg / 2) * 10; }
+
+/// Y component of a quaternion representing rotation by `angle_deg` around the X axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `0`
 fn quat_axis_x_y(angle_deg: int): int { return 0; }
+
+/// Z component of a quaternion representing rotation by `angle_deg` around the X axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `0`
 fn quat_axis_x_z(angle_deg: int): int { return 0; }
+
+/// W component of a quaternion representing rotation by `angle_deg` around the X axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `cos(angle/2)` ×10000
 fn quat_axis_x_w(angle_deg: int): int { return cos_fixed(angle_deg / 2) * 10; }
 
-// quat_from_axis_y: rotation around Y axis
+/// X component of a quaternion representing rotation by `angle_deg` around the Y axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `0`
 fn quat_axis_y_x(angle_deg: int): int { return 0; }
+
+/// Y component of a quaternion representing rotation by `angle_deg` around the Y axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `sin(angle/2)` ×10000
 fn quat_axis_y_y(angle_deg: int): int { return sin_fixed(angle_deg / 2) * 10; }
+
+/// Z component of a quaternion representing rotation by `angle_deg` around the Y axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `0`
 fn quat_axis_y_z(angle_deg: int): int { return 0; }
+
+/// W component of a quaternion representing rotation by `angle_deg` around the Y axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `cos(angle/2)` ×10000
 fn quat_axis_y_w(angle_deg: int): int { return cos_fixed(angle_deg / 2) * 10; }
 
-// quat_from_axis_z: rotation around Z axis
+/// X component of a quaternion representing rotation by `angle_deg` around the Z axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `0`
 fn quat_axis_z_x(angle_deg: int): int { return 0; }
+
+/// Y component of a quaternion representing rotation by `angle_deg` around the Z axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `0`
 fn quat_axis_z_y(angle_deg: int): int { return 0; }
+
+/// Z component of a quaternion representing rotation by `angle_deg` around the Z axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `sin(angle/2)` ×10000
 fn quat_axis_z_z(angle_deg: int): int { return sin_fixed(angle_deg / 2) * 10; }
+
+/// W component of a quaternion representing rotation by `angle_deg` around the Z axis.
+///
+/// @since 2.0.0
+/// @param angle_deg  Rotation angle in degrees
+/// @returns          `cos(angle/2)` ×10000
 fn quat_axis_z_w(angle_deg: int): int { return cos_fixed(angle_deg / 2) * 10; }
 
 // ─── Quaternion multiplication ────────────────────────────────────────────────
 // q = (ax,ay,az,aw) * (bx,by,bz,bw)
 // All components ×10000, result ×10000
 
+/// X component of quaternion product `a × b`.
+///
+/// @since 2.0.0
+/// @param ax  @param ay  @param az  @param aw  Quaternion a components ×10000
+/// @param bx  @param by  @param bz  @param bw  Quaternion b components ×10000
+/// @returns   X component of `a × b` ×10000
+/// @example
+/// let rx: int = quat_mul_x(ax, ay, az, aw, bx, by, bz, bw)
 fn quat_mul_x(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int {
     // x = aw*bx + ax*bw + ay*bz - az*by
     return mulfix(aw, bx) + mulfix(ax, bw) + mulfix(ay, bz) - mulfix(az, by);
 }
 
+/// Y component of quaternion product `a × b`.
+///
+/// @since 2.0.0
+/// @param ax  @param ay  @param az  @param aw  Quaternion a components ×10000
+/// @param bx  @param by  @param bz  @param bw  Quaternion b components ×10000
+/// @returns   Y component of `a × b` ×10000
 fn quat_mul_y(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int {
     // y = aw*by - ax*bz + ay*bw + az*bx
     return mulfix(aw, by) - mulfix(ax, bz) + mulfix(ay, bw) + mulfix(az, bx);
 }
 
+/// Z component of quaternion product `a × b`.
+///
+/// @since 2.0.0
+/// @param ax  @param ay  @param az  @param aw  Quaternion a components ×10000
+/// @param bx  @param by  @param bz  @param bw  Quaternion b components ×10000
+/// @returns   Z component of `a × b` ×10000
 fn quat_mul_z(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int {
     // z = aw*bz + ax*by - ay*bx + az*bw
     return mulfix(aw, bz) + mulfix(ax, by) - mulfix(ay, bx) + mulfix(az, bw);
 }
 
+/// W component of quaternion product `a × b`.
+///
+/// @since 2.0.0
+/// @param ax  @param ay  @param az  @param aw  Quaternion a components ×10000
+/// @param bx  @param by  @param bz  @param bw  Quaternion b components ×10000
+/// @returns   W component of `a × b` ×10000
 fn quat_mul_w(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int {
     // w = aw*bw - ax*bx - ay*by - az*bz
     return mulfix(aw, bw) - mulfix(ax, bx) - mulfix(ay, by) - mulfix(az, bz);
 }
 
 // ─── Quaternion conjugate (= inverse for unit quaternion) ────────────────────
+
+/// X component of the conjugate of quaternion `(qx, qy, qz, qw)`.
+///
+/// @since 2.0.0
+/// @param qx  @param qy  @param qz  @param qw  Input quaternion ×10000
+/// @returns   `-qx`
 fn quat_conj_x(qx: int, qy: int, qz: int, qw: int): int { return 0 - qx; }
+
+/// Y component of the conjugate of quaternion `(qx, qy, qz, qw)`.
+///
+/// @since 2.0.0
+/// @param qx  @param qy  @param qz  @param qw  Input quaternion ×10000
+/// @returns   `-qy`
 fn quat_conj_y(qx: int, qy: int, qz: int, qw: int): int { return 0 - qy; }
+
+/// Z component of the conjugate of quaternion `(qx, qy, qz, qw)`.
+///
+/// @since 2.0.0
+/// @param qx  @param qy  @param qz  @param qw  Input quaternion ×10000
+/// @returns   `-qz`
 fn quat_conj_z(qx: int, qy: int, qz: int, qw: int): int { return 0 - qz; }
+
+/// W component of the conjugate of quaternion `(qx, qy, qz, qw)`.
+///
+/// @since 2.0.0
+/// @param qx  @param qy  @param qz  @param qw  Input quaternion ×10000
+/// @returns   `qw` (unchanged)
 fn quat_conj_w(qx: int, qy: int, qz: int, qw: int): int { return qw; }
 
-// ─── Magnitude squared ×10000 ─────────────────────────────────────────────────
-// For unit quaternion: should equal 10000 (= 1.0 in ×10000 scale)
+/// Magnitude squared of a quaternion in ×10000 scale.
+///
+/// For a unit quaternion this should equal `10000`.
+///
+/// @since 2.0.0
+/// @param qx  @param qy  @param qz  @param qw  Quaternion components ×10000
+/// @returns   `qx²/10000 + qy²/10000 + qz²/10000 + qw²/10000` (×10000)
 fn quat_mag_sq(qx: int, qy: int, qz: int, qw: int): int {
     return mulfix(qx, qx) + mulfix(qy, qy) + mulfix(qz, qz) + mulfix(qw, qw);
 }
 
-// ─── Dot product ×10000 ──────────────────────────────────────────────────────
+/// Dot product of two quaternions in ×10000 scale.
+///
+/// @since 2.0.0
+/// @param ax  @param ay  @param az  @param aw  Quaternion a ×10000
+/// @param bx  @param by  @param bz  @param bw  Quaternion b ×10000
+/// @returns   `ax*bx/10000 + ay*by/10000 + az*bz/10000 + aw*bw/10000`
 fn quat_dot(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int {
     return mulfix(ax, bx) + mulfix(ay, by) + mulfix(az, bz) + mulfix(aw, bw);
 }
@@ -99,6 +241,17 @@ fn _quat_slerp_mag(rx: int, ry: int, rz: int, rw: int): int {
     return isqrt(ss);  // returns ≈ 1000 for unit quaternion
 }
 
+/// X component of the SLERP interpolation between quaternions `a` and `b` at `t/1000`.
+///
+/// Uses LERP + normalise (good approximation for small angles).
+///
+/// @since 2.0.0
+/// @param ax  @param ay  @param az  @param aw  Start quaternion ×10000
+/// @param bx  @param by  @param bz  @param bw  End quaternion ×10000
+/// @param t   Interpolation factor ×1000 (0 = a, 1000 = b)
+/// @returns   X component of interpolated quaternion ×10000
+/// @example
+/// let rx: int = quat_slerp_x(ax, ay, az, aw, bx, by, bz, bw, 500)
 fn quat_slerp_x(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int {
     let inv_t: int = 1000 - t;
     let rx: int = ax * inv_t / 1000 + bx * t / 1000;
@@ -110,6 +263,13 @@ fn quat_slerp_x(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, b
     return rx * 1000 / mag;
 }
 
+/// Y component of the SLERP interpolation between quaternions `a` and `b` at `t/1000`.
+///
+/// @since 2.0.0
+/// @param ax  @param ay  @param az  @param aw  Start quaternion ×10000
+/// @param bx  @param by  @param bz  @param bw  End quaternion ×10000
+/// @param t   Interpolation factor ×1000
+/// @returns   Y component of interpolated quaternion ×10000
 fn quat_slerp_y(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int {
     let inv_t: int = 1000 - t;
     let rx: int = ax * inv_t / 1000 + bx * t / 1000;
@@ -121,6 +281,13 @@ fn quat_slerp_y(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, b
     return ry * 1000 / mag;
 }
 
+/// Z component of the SLERP interpolation between quaternions `a` and `b` at `t/1000`.
+///
+/// @since 2.0.0
+/// @param ax  @param ay  @param az  @param aw  Start quaternion ×10000
+/// @param bx  @param by  @param bz  @param bw  End quaternion ×10000
+/// @param t   Interpolation factor ×1000
+/// @returns   Z component of interpolated quaternion ×10000
 fn quat_slerp_z(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int {
     let inv_t: int = 1000 - t;
     let rx: int = ax * inv_t / 1000 + bx * t / 1000;
@@ -132,6 +299,13 @@ fn quat_slerp_z(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, b
     return rz * 1000 / mag;
 }
 
+/// W component of the SLERP interpolation between quaternions `a` and `b` at `t/1000`.
+///
+/// @since 2.0.0
+/// @param ax  @param ay  @param az  @param aw  Start quaternion ×10000
+/// @param bx  @param by  @param bz  @param bw  End quaternion ×10000
+/// @param t   Interpolation factor ×1000
+/// @returns   W component of interpolated quaternion ×10000
 fn quat_slerp_w(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int {
     let inv_t: int = 1000 - t;
     let rx: int = ax * inv_t / 1000 + bx * t / 1000;
@@ -147,6 +321,15 @@ fn quat_slerp_w(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, b
 // yaw: Y-axis rotation (°), pitch: X-axis rotation (°), roll: Z-axis rotation (°)
 // YXZ order: first yaw, then pitch, then roll
 
+/// X component of the quaternion from Euler angles (YXZ order, MC convention).
+///
+/// @since 2.0.0
+/// @param yaw    Y-axis rotation in degrees
+/// @param pitch  X-axis rotation in degrees
+/// @param roll   Z-axis rotation in degrees
+/// @returns      X component ×10000
+/// @example
+/// let qx: int = quat_euler_x(90, 0, 0)
 fn quat_euler_x(yaw: int, pitch: int, roll: int): int {
     let cy: int = cos_fixed(yaw / 2) * 10;
     let sy: int = sin_fixed(yaw / 2) * 10;
@@ -158,6 +341,13 @@ fn quat_euler_x(yaw: int, pitch: int, roll: int): int {
     return mulfix(mulfix(cy, sp), cr) + mulfix(mulfix(sy, cp), sr);
 }
 
+/// Y component of the quaternion from Euler angles (YXZ order, MC convention).
+///
+/// @since 2.0.0
+/// @param yaw    Y-axis rotation in degrees
+/// @param pitch  X-axis rotation in degrees
+/// @param roll   Z-axis rotation in degrees
+/// @returns      Y component ×10000
 fn quat_euler_y(yaw: int, pitch: int, roll: int): int {
     let cy: int = cos_fixed(yaw / 2) * 10;
     let sy: int = sin_fixed(yaw / 2) * 10;
@@ -169,6 +359,13 @@ fn quat_euler_y(yaw: int, pitch: int, roll: int): int {
     return mulfix(mulfix(sy, cp), cr) - mulfix(mulfix(cy, sp), sr);
 }
 
+/// Z component of the quaternion from Euler angles (YXZ order, MC convention).
+///
+/// @since 2.0.0
+/// @param yaw    Y-axis rotation in degrees
+/// @param pitch  X-axis rotation in degrees
+/// @param roll   Z-axis rotation in degrees
+/// @returns      Z component ×10000
 fn quat_euler_z(yaw: int, pitch: int, roll: int): int {
     let cy: int = cos_fixed(yaw / 2) * 10;
     let sy: int = sin_fixed(yaw / 2) * 10;
@@ -180,6 +377,13 @@ fn quat_euler_z(yaw: int, pitch: int, roll: int): int {
     return mulfix(mulfix(cy, cp), sr) - mulfix(mulfix(sy, sp), cr);
 }
 
+/// W component of the quaternion from Euler angles (YXZ order, MC convention).
+///
+/// @since 2.0.0
+/// @param yaw    Y-axis rotation in degrees
+/// @param pitch  X-axis rotation in degrees
+/// @param roll   Z-axis rotation in degrees
+/// @returns      W component ×10000
 fn quat_euler_w(yaw: int, pitch: int, roll: int): int {
     let cy: int = cos_fixed(yaw / 2) * 10;
     let sy: int = sin_fixed(yaw / 2) * 10;