redscript-mc 2.6.2 → 3.0.0

package/src/stdlib/color.mcrs

@@ -9,30 +9,58 @@ module library;
 
 // ─── Pack / Unpack ────────────────────────────────────────────────────────────
 
-// rgb_pack(r, g, b): pack RGB into a single int (0xRRGGBB)
+/// Pack RGB components into a single integer (0xRRGGBB format).
+/// @since 1.0.0
+/// @param r  Red channel, range [0, 255]
+/// @param g  Green channel, range [0, 255]
+/// @param b  Blue channel, range [0, 255]
+/// @returns  r*65536 + g*256 + b
+/// @example
+/// let red: int = rgb_pack(255, 0, 0)  // result: 16711680 (0xFF0000)
 fn rgb_pack(r: int, g: int, b: int): int {
     return r * 65536 + g * 256 + b;
 }
 
-// rgb_r(packed): extract red component
+/// Extract the red component from a packed RGB integer.
+/// @since 1.0.0
+/// @param packed  Packed color integer (0xRRGGBB)
+/// @returns  Red channel value in [0, 255]
+/// @example
+/// let r: int = rgb_r(16711680)  // result: 255
 fn rgb_r(packed: int): int {
     return packed / 65536 % 256;
 }
 
-// rgb_g(packed): extract green component
+/// Extract the green component from a packed RGB integer.
+/// @since 1.0.0
+/// @param packed  Packed color integer (0xRRGGBB)
+/// @returns  Green channel value in [0, 255]
+/// @example
+/// let g: int = rgb_g(65280)  // result: 255 (0x00FF00)
 fn rgb_g(packed: int): int {
     return packed / 256 % 256;
 }
 
-// rgb_b(packed): extract blue component
+/// Extract the blue component from a packed RGB integer.
+/// @since 1.0.0
+/// @param packed  Packed color integer (0xRRGGBB)
+/// @returns  Blue channel value in [0, 255]
+/// @example
+/// let b: int = rgb_b(255)  // result: 255 (0x0000FF)
 fn rgb_b(packed: int): int {
     return packed % 256;
 }
 
 // ─── Blending ─────────────────────────────────────────────────────────────────
 
-// rgb_lerp(a, b, t): linear blend between two packed colors, t ∈ [0, 1000]
-// t=0 → a, t=1000 → b
+/// Linear interpolation between two packed RGB colors.
+/// @since 1.0.0
+/// @param a  Start color (packed 0xRRGGBB)
+/// @param b  End color (packed 0xRRGGBB)
+/// @param t  Blend factor in [0, 1000] (0 = a, 1000 = b)
+/// @returns  Packed RGB interpolated between a and b
+/// @example
+/// let mid: int = rgb_lerp(0xFF0000, 0x0000FF, 500)  // halfway between red and blue
 fn rgb_lerp(a: int, b: int, t: int): int {
     let ra: int = a / 65536 % 256;
     let ga: int = a / 256 % 256;
@@ -53,7 +81,14 @@ fn rgb_lerp(a: int, b: int, t: int): int {
 //   H ∈ [0, 3600000]        (360° × 10000)
 //   S, L ∈ [0, 10000]       (1.0 × 10000)
 
-// rgb_to_l(r, g, b): lightness ×10000, range [0, 10000]
+/// Compute the HSL lightness from RGB components (×10000 scale).
+/// @since 1.0.0
+/// @param r  Red ×10000, range [0, 2550000]
+/// @param g  Green ×10000, range [0, 2550000]
+/// @param b  Blue ×10000, range [0, 2550000]
+/// @returns  Lightness in [0, 10000] (0 = black, 10000 = white)
+/// @example
+/// let l: int = rgb_to_l(2550000, 2550000, 2550000)  // result: 10000 (white)
 fn rgb_to_l(r: int, g: int, b: int): int {
     let mx: int = r;
     if (g > mx) { mx = g; }
@@ -64,7 +99,14 @@ fn rgb_to_l(r: int, g: int, b: int): int {
     return (mx + mn) / 510;
 }
 
-// rgb_to_s(r, g, b): saturation ×10000, range [0, 10000]
+/// Compute the HSL saturation from RGB components (×10000 scale).
+/// @since 1.0.0
+/// @param r  Red ×10000, range [0, 2550000]
+/// @param g  Green ×10000, range [0, 2550000]
+/// @param b  Blue ×10000, range [0, 2550000]
+/// @returns  Saturation in [0, 10000] (0 = grey, 10000 = fully saturated)
+/// @example
+/// let s: int = rgb_to_s(2550000, 0, 0)  // result: 10000 (pure red is fully saturated)
 fn rgb_to_s(r: int, g: int, b: int): int {
     let mx: int = r;
     if (g > mx) { mx = g; }
@@ -81,7 +123,14 @@ fn rgb_to_s(r: int, g: int, b: int): int {
     return d * 10000 / (255 * denom);
 }
 
-// rgb_to_h(r, g, b): hue ×10000, range [0, 3600000]
+/// Compute the HSL hue from RGB components (×10000 scale).
+/// @since 1.0.0
+/// @param r  Red ×10000, range [0, 2550000]
+/// @param g  Green ×10000, range [0, 2550000]
+/// @param b  Blue ×10000, range [0, 2550000]
+/// @returns  Hue in [0, 3600000] (degrees × 10000; 0=red, 1200000=green, 2400000=blue)
+/// @example
+/// let h: int = rgb_to_h(0, 2550000, 0)  // result: 1200000 (120°, pure green)
 fn rgb_to_h(r: int, g: int, b: int): int {
     let mx: int = r;
     if (g > mx) { mx = g; }
@@ -120,7 +169,14 @@ fn _hsl10k_chroma(s: int, l: int): int {
     return (10000 - abs2l1) * s / 10000;
 }
 
-// hsl_to_r(h, s, l): H×10000, S×10000, L×10000 → R ∈ [0, 2550000]
+/// Convert HSL to the red channel of RGB (×10000 scale).
+/// @since 1.0.0
+/// @param h  Hue ×10000, range [0, 3600000]
+/// @param s  Saturation ×10000, range [0, 10000]
+/// @param l  Lightness ×10000, range [0, 10000]
+/// @returns  Red channel ×10000, range [0, 2550000]; divide by 10000 for 0-255
+/// @example
+/// let r: int = hsl_to_r(0, 10000, 5000)  // pure red → 2550000
 fn hsl_to_r(h: int, s: int, l: int): int {
     let c: int = _hsl10k_chroma(s, l);
     let x: int = _hsl10k_chroma_x(h, c);
@@ -134,7 +190,14 @@ fn hsl_to_r(h: int, s: int, l: int): int {
     return (r1 + m) * 255;
 }
 
-// hsl_to_g(h, s, l): H×10000, S×10000, L×10000 → G ∈ [0, 2550000]
+/// Convert HSL to the green channel of RGB (×10000 scale).
+/// @since 1.0.0
+/// @param h  Hue ×10000, range [0, 3600000]
+/// @param s  Saturation ×10000, range [0, 10000]
+/// @param l  Lightness ×10000, range [0, 10000]
+/// @returns  Green channel ×10000, range [0, 2550000]
+/// @example
+/// let g: int = hsl_to_g(1200000, 10000, 5000)  // pure green → 2550000
 fn hsl_to_g(h: int, s: int, l: int): int {
     let c: int = _hsl10k_chroma(s, l);
     let x: int = _hsl10k_chroma_x(h, c);
@@ -148,7 +211,14 @@ fn hsl_to_g(h: int, s: int, l: int): int {
     return (g1 + m) * 255;
 }
 
-// hsl_to_b(h, s, l): H×10000, S×10000, L×10000 → B ∈ [0, 2550000]
+/// Convert HSL to the blue channel of RGB (×10000 scale).
+/// @since 1.0.0
+/// @param h  Hue ×10000, range [0, 3600000]
+/// @param s  Saturation ×10000, range [0, 10000]
+/// @param l  Lightness ×10000, range [0, 10000]
+/// @returns  Blue channel ×10000, range [0, 2550000]
+/// @example
+/// let b: int = hsl_to_b(2400000, 10000, 5000)  // pure blue → 2550000
 fn hsl_to_b(h: int, s: int, l: int): int {
     let c: int = _hsl10k_chroma(s, l);
     let x: int = _hsl10k_chroma_x(h, c);
@@ -162,7 +232,14 @@ fn hsl_to_b(h: int, s: int, l: int): int {
     return (b1 + m) * 255;
 }
 
-// hsl_to_packed(h, s, l): HSL (×10000 scale) → packed RGB int (0xRRGGBB)
+/// Convert HSL (×10000 scale) to a packed RGB integer (0xRRGGBB).
+/// @since 1.0.0
+/// @param h  Hue ×10000, range [0, 3600000]
+/// @param s  Saturation ×10000, range [0, 10000]
+/// @param l  Lightness ×10000, range [0, 10000]
+/// @returns  Packed RGB integer (0xRRGGBB), each channel 0-255
+/// @example
+/// let col: int = hsl_to_packed(0, 10000, 5000)  // pure red → 0xFF0000
 fn hsl_to_packed(h: int, s: int, l: int): int {
     let r: int = hsl_to_r(h, s, l) / 10000;
     let g: int = hsl_to_g(h, s, l) / 10000;
@@ -172,9 +249,14 @@ fn hsl_to_packed(h: int, s: int, l: int): int {
 
 // ─── rgb_to_hex ───────────────────────────────────────────────────────────────
 
-// rgb_to_hex(r, g, b): pack RGB into 0xRRGGBB integer
-// Equivalent to rgb_pack; provided as an explicit named alias.
-// r, g, b ∈ [0, 255]; no fixed-point — simple integer arithmetic.
+/// Pack RGB into a 0xRRGGBB integer (alias for rgb_pack with explicit naming).
+/// @since 1.0.0
+/// @param r  Red channel, range [0, 255]
+/// @param g  Green channel, range [0, 255]
+/// @param b  Blue channel, range [0, 255]
+/// @returns  r*65536 + g*256 + b (same as rgb_pack)
+/// @example
+/// let hex: int = rgb_to_hex(0, 128, 255)  // result: 32895 (0x0080FF)
 fn rgb_to_hex(r: int, g: int, b: int): int {
     return r * 65536 + g * 256 + b;
 }

package/src/stdlib/combat.mcrs

@@ -1,14 +1,25 @@
 // module library
 // Combat helpers for simple RPG-style datapacks.
 
-// Returns base + bonus damage.
+/// Calculate total weapon damage from a base value plus a bonus.
+/// @since 1.0.0
+/// @param base   Base weapon damage value
+/// @param bonus  Additional damage modifier (e.g. from enchantments or buffs)
+/// @returns  base + bonus
+/// @example
+/// let dmg: int = weapon_damage(10, 5)  // result: 15
 fn weapon_damage(base: int, bonus: int): int {
     return base + bonus
 }
 
-// Applies damage to a health value, clamping to 0.
-// Usage: let new_hp: int = take_damage(current_hp, amount)
-// Then: scoreboard_set(player, objective, new_hp)
+/// Apply damage to a health value, clamping the result to a minimum of 0.
+/// @since 1.0.0
+/// @param health  Current health value (e.g. from scoreboard)
+/// @param amount  Damage amount to subtract
+/// @returns  health - amount, clamped to 0; use scoreboard_set after calling
+/// @example
+/// let new_hp: int = take_damage(current_hp, 8)
+/// scoreboard_set(@p, #health, new_hp)
 fn take_damage(health: int, amount: int): int {
     let next: int = health - amount
     if (next < 0) {
@@ -17,7 +28,14 @@ fn take_damage(health: int, amount: int): int {
     return next
 }
 
-// Returns 1 if health <= 0 (dead), else 0.
+/// Check whether an entity is dead (health at or below zero).
+/// @since 1.0.0
+/// @param health  Current health value to test
+/// @returns  1 if health <= 0 (dead), 0 otherwise (alive)
+/// @example
+/// if (is_dead(current_hp) == 1) {
+///     // trigger death logic
+/// }
 fn is_dead(health: int): int {
     if (health <= 0) {
         return 1

package/src/stdlib/cooldown.mcrs

@@ -4,11 +4,24 @@
 // that can route string literals through user-defined calls. Today this file
 // manages one cooldown slot on the `rs` objective.
 
+/// Start (or restart) a cooldown for the given slot.
+/// The cooldown expires after `ticks` game ticks.
+/// @since 1.2.0
+/// @param name Cooldown slot identifier (reserved for future multi-slot support)
+/// @param ticks Duration in game ticks (20 ticks = 1 second)
+/// @example
+/// cooldown_start("sword", 40); // 2-second cooldown
 fn cooldown_start(name: string, ticks: int) {
     scoreboard_set("cooldown_ticks", #rs, ticks);
     scoreboard_set("cooldown_active", #rs, 1);
 }
 
+/// Check whether the cooldown has expired (i.e. is ready to fire again).
+/// @since 1.2.0
+/// @param name Cooldown slot identifier (reserved for future multi-slot support)
+/// @returns 1 if the cooldown is ready (inactive or ticks remaining ≤ 0), 0 otherwise
+/// @example
+/// if (cooldown_ready("sword") == 1) { attack(); cooldown_start("sword", 40); }
 fn cooldown_ready(name: string) -> int {
     let active: int = scoreboard_get("cooldown_active", #rs);
     let ticks_left: int = scoreboard_get("cooldown_ticks", #rs);
@@ -24,6 +37,12 @@ fn cooldown_ready(name: string) -> int {
     return 0;
 }
 
+/// Advance the cooldown by one tick. Call this every tick from a `@tick` function.
+/// Automatically marks the cooldown inactive when the remaining ticks reach zero.
+/// @since 1.2.0
+/// @param name Cooldown slot identifier (reserved for future multi-slot support)
+/// @example
+/// @tick fn game_tick() { cooldown_tick("sword"); }
 fn cooldown_tick(name: string) {
     let active: int = scoreboard_get("cooldown_active", #rs);
     let ticks_left: int = scoreboard_get("cooldown_ticks", #rs);

package/src/stdlib/dialog.mcrs

@@ -6,18 +6,38 @@
 
 module library
 
-/// Send a plain white message to a player.
+/// Sends a plain white chat message to a player or selector.
+///
+/// @since 1.0.0
+/// @param p    Recipient selector
+/// @param msg  Plain text message content
+/// @example
+/// dialog_say(@p, "Quest updated")
 fn dialog_say(p: selector, msg: string) {
     raw("tellraw {p} {\"text\":\"{msg}\"}");
 }
 
-/// Broadcast a plain white message to all players.
+/// Broadcasts a plain white chat message to all players.
+///
+/// @since 1.0.0
+/// @param msg  Plain text message content
+/// @example
+/// dialog_broadcast("Server restart in 60 seconds")
 fn dialog_broadcast(msg: string) {
     raw("tellraw @a {\"text\":\"{msg}\"}");
 }
 
-/// Send a colored message to a player.
-/// color: 0=white, 1=red, 2=green, 3=gold, 4=aqua
+/// Sends a colored chat message to a player or selector.
+///
+/// Color mapping: `0=white`, `1=red`, `2=green`, `3=gold`, `4=aqua`.
+/// Any other value falls back to white.
+///
+/// @since 1.0.0
+/// @param p      Recipient selector
+/// @param msg    Plain text message content
+/// @param color  Color selector integer (0=white, 1=red, 2=green, 3=gold, 4=aqua)
+/// @example
+/// dialog_say_color(@s, "You died!", 1)
 fn dialog_say_color(p: selector, msg: string, color: int) {
     if (color == 1) {
         raw("tellraw {p} {\"text\":\"{msg}\",\"color\":\"red\"}");
@@ -38,18 +58,36 @@ fn dialog_say_color(p: selector, msg: string, color: int) {
     }
 }
 
-/// Display a large title and subtitle on a player's screen.
+/// Displays a title and subtitle on a player's screen.
+///
+/// @since 1.0.0
+/// @param p         Recipient selector
+/// @param title     Large title text
+/// @param subtitle  Subtitle text shown below the title
+/// @example
+/// dialog_title(@s, "Stage 2", "Defeat the boss")
 fn dialog_title(p: selector, title: string, subtitle: string) {
     raw("title {p} title {\"text\":\"{title}\"}");
     raw("title {p} subtitle {\"text\":\"{subtitle}\"}");
 }
 
-/// Clear the title from a player's screen.
+/// Clears any currently displayed title for the target selector.
+///
+/// @since 1.0.0
+/// @param p  Recipient selector
+/// @example
+/// dialog_title_clear(@s)
 fn dialog_title_clear(p: selector) {
     raw("title {p} clear");
 }
 
-/// Display a message on the player's actionbar (above hotbar).
+/// Displays a short message in the player's actionbar.
+///
+/// @since 1.0.0
+/// @param p    Recipient selector
+/// @param msg  Plain text message content
+/// @example
+/// dialog_actionbar(@s, "Mana: 80/100")
 fn dialog_actionbar(p: selector, msg: string) {
     raw("title {p} actionbar {\"text\":\"{msg}\"}");
 }

package/src/stdlib/easing.mcrs

@@ -11,22 +11,43 @@ module library;
 
 // ─── Linear ──────────────────────────────────────────────────────────────────
 
+/// Linear easing — no acceleration or deceleration.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  t (identity function)
+/// @example
+/// let v: int = ease_linear(5000)  // result: 5000 (50%)
 fn ease_linear(t: int): int { return t; }
 
 // ─── Quadratic ───────────────────────────────────────────────────────────────
 
-// ease_in_quad: slow start, fast end
+/// Quadratic ease-in — slow start, fast end.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  t² / 10000
+/// @example
+/// let v: int = ease_in_quad(5000)  // result: 2500 (25%)
 fn ease_in_quad(t: int): int {
     return t * t / 10000;
 }
 
-// ease_out_quad: fast start, slow end
+/// Quadratic ease-out — fast start, slow end.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  1 - (1-t)²
+/// @example
+/// let v: int = ease_out_quad(5000)  // result: 7500 (75%)
 fn ease_out_quad(t: int): int {
     let inv: int = 10000 - t;
     return 10000 - inv * inv / 10000;
 }
 
-// ease_in_out_quad: slow start and end, fast middle
+/// Quadratic ease-in-out — slow start and end, fast middle.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  2t² for t < 0.5, else 1 - 2*(1-t)²
+/// @example
+/// let v: int = ease_in_out_quad(2500)  // result: 1250 (12.5%)
 fn ease_in_out_quad(t: int): int {
     if (t < 5000) {
         return 2 * t * t / 10000;
@@ -37,15 +58,33 @@ fn ease_in_out_quad(t: int): int {
 
 // ─── Cubic ───────────────────────────────────────────────────────────────────
 
+/// Cubic ease-in — slow start, accelerates to fast end (stronger than quadratic).
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  t³
+/// @example
+/// let v: int = ease_in_cubic(5000)  // result: 1250 (12.5%)
 fn ease_in_cubic(t: int): int {
     return t * t / 10000 * t / 10000;
 }
 
+/// Cubic ease-out — fast start, decelerates to slow end.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  1 - (1-t)³
+/// @example
+/// let v: int = ease_out_cubic(5000)  // result: 8750 (87.5%)
 fn ease_out_cubic(t: int): int {
     let inv: int = 10000 - t;
     return 10000 - inv * inv / 10000 * inv / 10000;
 }
 
+/// Cubic ease-in-out — slow start and end, fast middle (stronger than quadratic).
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  4t³ for t < 0.5, else 1 - 4*(1-t)³
+/// @example
+/// let v: int = ease_in_out_cubic(5000)  // result: 5000 (50%)
 fn ease_in_out_cubic(t: int): int {
     if (t < 5000) {
         return 4 * t * t / 10000 * t / 10000;
@@ -56,11 +95,23 @@ fn ease_in_out_cubic(t: int): int {
 
 // ─── Quartic ──────────────────────────────────────────────────────────────────
 
+/// Quartic ease-in — very slow start, very fast end (t⁴).
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  t⁴
+/// @example
+/// let v: int = ease_in_quart(5000)  // result: 625 (6.25%)
 fn ease_in_quart(t: int): int {
     let t2: int = t * t / 10000;
     return t2 * t2 / 10000;
 }
 
+/// Quartic ease-out — very fast start, very slow end (1 - (1-t)⁴).
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  1 - (1-t)⁴
+/// @example
+/// let v: int = ease_out_quart(5000)  // result: 9375 (93.75%)
 fn ease_out_quart(t: int): int {
     let inv: int = 10000 - t;
     let inv2: int = inv * inv / 10000;
@@ -70,7 +121,12 @@ fn ease_out_quart(t: int): int {
 // ─── Sine approximation ───────────────────────────────────────────────────────
 // Approximated using polynomial — no actual trig needed for easing
 
-// ease_in_sine: t ∈ [0,10000] → starts slow, accelerates
+/// Sinusoidal ease-in — starts slow, accelerates (approximated with polynomial).
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  Approximate 1 - cos(t*π/2)
+/// @example
+/// let v: int = ease_in_sine(5000)  // ≈ 2929 (sin curve at 50%)
 fn ease_in_sine(t: int): int {
     // ≈ 1 - cos(t*π/2) using polynomial: 1 - (1 - t²/2 + t⁴/24)
     let t2: int = t * t / 10000;
@@ -79,10 +135,22 @@ fn ease_in_sine(t: int): int {
     return 10000 - cos_approx;
 }
 
+/// Sinusoidal ease-out — fast start, decelerates gently (approximated).
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  Approximate sin(t*π/2)
+/// @example
+/// let v: int = ease_out_sine(5000)  // ≈ 7071
 fn ease_out_sine(t: int): int {
     return 10000 - ease_in_sine(10000 - t);
 }
 
+/// Sinusoidal ease-in-out — smooth start and end via sine wave.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  Approximate -(cos(π*t) - 1) / 2
+/// @example
+/// let v: int = ease_in_out_sine(5000)  // result: 5000 (symmetrical)
 fn ease_in_out_sine(t: int): int {
     if (t < 5000) {
         return ease_in_sine(t * 2) / 2;
@@ -92,7 +160,12 @@ fn ease_in_out_sine(t: int): int {
 
 // ─── Exponential ─────────────────────────────────────────────────────────────
 
-// ease_in_expo: very slow start, explosive end
+/// Exponential ease-in — nearly zero at start, explosive at end.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  Approximate 2^(10t-10) (uses cubic proxy)
+/// @example
+/// let v: int = ease_in_expo(8000)  // very small until close to the end
 fn ease_in_expo(t: int): int {
     if (t <= 0) { return 0; }
     // Approximate 2^(10t-10) ≈ exp_fx((10*t-100000)*693/10000)
@@ -101,6 +174,12 @@ fn ease_in_expo(t: int): int {
     return t3;
 }
 
+/// Exponential ease-out — explosive start, slows to near-zero at end.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  1 - ease_in_expo(1 - t)
+/// @example
+/// let v: int = ease_out_expo(2000)  // large value even early
 fn ease_out_expo(t: int): int {
     if (t >= 10000) { return 10000; }
     return 10000 - ease_in_expo(10000 - t);
@@ -108,8 +187,12 @@ fn ease_out_expo(t: int): int {
 
 // ─── Back (overshoot) ─────────────────────────────────────────────────────────
 
-// ease_in_back: slight pullback before moving forward
-// c1 = 1.70158 × 10000 = 17015
+/// Back ease-in — slight pullback before accelerating forward (overshoot anticipation).
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  t³*(c3) - t²*(c1) where c1 ≈ 1.70158 (may briefly go below 0)
+/// @example
+/// let v: int = ease_in_back(2000)  // negative briefly, then rises
 fn ease_in_back(t: int): int {
     let c1: int = 17015;   // 1.70158
     let c3: int = c1 + 10000;  // c1 + 1
@@ -119,10 +202,22 @@ fn ease_in_back(t: int): int {
     return t3 * c3 / 10000 - t2 * c1 / 10000;
 }
 
+/// Back ease-out — overshoots target then settles back.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  Mirrored ease_in_back (may briefly exceed 10000)
+/// @example
+/// let v: int = ease_out_back(8000)  // overshoots near the end
 fn ease_out_back(t: int): int {
     return 10000 - ease_in_back(10000 - t);
 }
 
+/// Back ease-in-out — pullback on entry, overshoot on exit.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  Combined back ease, symmetric around t=5000
+/// @example
+/// let v: int = ease_in_out_back(5000)  // result: 5000 (midpoint)
 fn ease_in_out_back(t: int): int {
     if (t < 5000) {
         return ease_in_back(t * 2) / 2;
@@ -132,7 +227,12 @@ fn ease_in_out_back(t: int): int {
 
 // ─── Bounce ───────────────────────────────────────────────────────────────────
 
-// ease_out_bounce: bounces at the end (ball dropping)
+/// Bounce ease-out — simulates a ball dropping and bouncing at the end.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  Piecewise bounce curve, always in [0, 10000]
+/// @example
+/// let v: int = ease_out_bounce(8000)  // bouncing near the end
 fn ease_out_bounce(t: int): int {
     let n1: int = 75625;  // 7.5625 × 10000
     let d1: int = 27500;  // 2.75 × 10000
@@ -152,10 +252,22 @@ fn ease_out_bounce(t: int): int {
     return n1 * t2 / 10000 * t2 / 10000 + 9844;
 }
 
+/// Bounce ease-in — bounces at the start before settling into forward motion.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  Mirrored ease_out_bounce
+/// @example
+/// let v: int = ease_in_bounce(2000)  // bouncing at the start
 fn ease_in_bounce(t: int): int {
     return 10000 - ease_out_bounce(10000 - t);
 }
 
+/// Bounce ease-in-out — bounce on both entry and exit.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  Symmetric bounce easing
+/// @example
+/// let v: int = ease_in_out_bounce(5000)  // result: 5000 (midpoint)
 fn ease_in_out_bounce(t: int): int {
     if (t < 5000) {
         return ease_in_bounce(t * 2) / 2;
@@ -165,14 +277,22 @@ fn ease_in_out_bounce(t: int): int {
 
 // ─── Smoothstep family ────────────────────────────────────────────────────────
 
-// smoothstep already in math.mcrs — re-exported here for convenience
-// smoothstep(t) = 3t² - 2t³
+/// Smoothstep easing — cubic Hermite curve (3t² - 2t³), smooth start and end.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  3t² - 2t³ (Ken Perlin's smooth interpolation)
+/// @example
+/// let v: int = ease_smooth(5000)  // result: 5000 (symmetric)
 fn ease_smooth(t: int): int {
     return 3 * t * t / 10000 - 2 * t * t / 10000 * t / 10000;
 }
 
-// smootherstep: even smoother (Ken Perlin)
-// 6t⁵ - 15t⁴ + 10t³
+/// Smootherstep easing — quintic curve (6t⁵ - 15t⁴ + 10t³), zero first and second derivatives at endpoints.
+/// @since 1.0.0
+/// @param t  Progress ×10000, range [0, 10000]
+/// @returns  6t⁵ - 15t⁴ + 10t³ (Ken Perlin's improved noise smoothstep)
+/// @example
+/// let v: int = ease_smoother(5000)  // result: 5000 (symmetric)
 fn ease_smoother(t: int): int {
     let t2: int = t * t / 10000;
     let t3: int = t2 * t / 10000;