redscript-mc 2.6.0 → 3.0.0

package/src/stdlib/calculus.mcrs

@@ -12,24 +12,35 @@ module library;
 
 // ─── Differentiation ─────────────────────────────────────────────────────────
 
-// deriv_forward(f1, f0, h_fx): forward difference derivative
-// f1 = f(x+h), f0 = f(x), h_fx = step size ×10000
-// Returns df/dx ×10000
+/// Forward-difference derivative: (f(x+h) − f(x)) / h.
+/// @since 1.3.0
+/// @param f1 f(x + h) × 10000
+/// @param f0 f(x) × 10000
+/// @param h_fx Step size × 10000 (must not be zero)
+/// @returns df/dx × 10000; returns 0 if h_fx == 0
 fn deriv_forward(f1: int, f0: int, h_fx: int): int {
     if (h_fx == 0) { return 0; }
     return (f1 - f0) * 10000 / h_fx;
 }
 
-// deriv_central(f_plus, f_minus, h_fx): central difference (more accurate)
-// f_plus = f(x+h), f_minus = f(x-h)
-// Returns df/dx ×10000
+/// Central-difference derivative: (f(x+h) − f(x−h)) / (2h). More accurate than forward difference.
+/// @since 1.3.0
+/// @param f_plus f(x + h) × 10000
+/// @param f_minus f(x − h) × 10000
+/// @param h_fx Step size × 10000 (must not be zero)
+/// @returns df/dx × 10000; returns 0 if h_fx == 0
 fn deriv_central(f_plus: int, f_minus: int, h_fx: int): int {
     if (h_fx == 0) { return 0; }
     return (f_plus - f_minus) * 10000 / (2 * h_fx);
 }
 
-// second_deriv(f_plus, f0, f_minus, h_fx): second derivative
-// Returns d²f/dx² ×10000
+/// Second derivative via the central finite-difference formula: (f(x+h) − 2f(x) + f(x−h)) / h².
+/// @since 1.3.0
+/// @param f_plus f(x + h) × 10000
+/// @param f0 f(x) × 10000
+/// @param f_minus f(x − h) × 10000
+/// @param h_fx Step size × 10000 (must not be zero)
+/// @returns d²f/dx² × 10000; returns 0 if h_fx == 0
 fn second_deriv(f_plus: int, f0: int, f_minus: int, h_fx: int): int {
     if (h_fx == 0) { return 0; }
     return (f_plus - 2 * f0 + f_minus) * 100000000 / h_fx / h_fx;
@@ -40,10 +51,15 @@ fn second_deriv(f_plus: int, f0: int, f_minus: int, h_fx: int): int {
 // For integration, the user provides an array of function values at equally
 // spaced points, and the step size.
 
-// integrate_trapezoid(vals, n, h_fx): trapezoidal rule integration
-// vals: array of n function values ×10000, equally spaced by h_fx
-// h_fx: step width ×10000
-// Returns integral ×10000 (area under curve)
+/// Numerical integration using the trapezoidal rule.
+/// @since 1.3.0
+/// @param vals Array of n function values × 10000 at equally spaced points
+/// @param n Number of sample points (must be ≥ 2)
+/// @param h_fx Step width between samples × 10000
+/// @returns Approximate integral × 10000 (area under the curve)
+/// @example
+/// let ys: int[] = [0, 5000, 10000]; // f(0)=0, f(0.5)=0.5, f(1)=1  (linear)
+/// let area: int = integrate_trapezoid(ys, 3, 5000); // ≈ 5000  (∫₀¹ x dx = 0.5)
 fn integrate_trapezoid(vals: int[], n: int, h_fx: int): int {
     if (n < 2) { return 0; }
     // Sum = (vals[0] + vals[n-1]) / 2 + vals[1] + vals[2] + ... + vals[n-2]
@@ -56,8 +72,13 @@ fn integrate_trapezoid(vals: int[], n: int, h_fx: int): int {
     return sum * h_fx / 10000;
 }
 
-// integrate_simpson(vals, n, h_fx): Simpson's 1/3 rule (n must be odd, n ≥ 3)
-// More accurate than trapezoid for smooth functions
+/// Numerical integration using Simpson's 1/3 rule (more accurate than trapezoid for smooth functions).
+/// Uses n−1 intervals if n is even. Requires n ≥ 3.
+/// @since 1.3.0
+/// @param vals Array of n function values × 10000 at equally spaced points
+/// @param n Number of sample points (should be odd and ≥ 3)
+/// @param h_fx Step width × 10000
+/// @returns Approximate integral × 10000
 fn integrate_simpson(vals: int[], n: int, h_fx: int): int {
     if (n < 3) { return integrate_trapezoid(vals, n, h_fx); }
     // Ensure n is odd by using n-1 if even
@@ -80,7 +101,12 @@ fn integrate_simpson(vals: int[], n: int, h_fx: int): int {
 
 // ─── Riemann sums ─────────────────────────────────────────────────────────────
 
-// riemann_left(vals, n, h_fx): left Riemann sum
+/// Left Riemann sum: sum of f(x_i) × h for i = 0 … n−2.
+/// @since 1.3.0
+/// @param vals Array of n function values × 10000
+/// @param n Number of sample points
+/// @param h_fx Step width × 10000
+/// @returns Approximate integral × 10000
 fn riemann_left(vals: int[], n: int, h_fx: int): int {
     let sum: int = 0;
     let i: int = 0;
@@ -88,7 +114,12 @@ fn riemann_left(vals: int[], n: int, h_fx: int): int {
     return sum * h_fx / 10000;
 }
 
-// riemann_right(vals, n, h_fx): right Riemann sum
+/// Right Riemann sum: sum of f(x_i) × h for i = 1 … n−1.
+/// @since 1.3.0
+/// @param vals Array of n function values × 10000
+/// @param n Number of sample points
+/// @param h_fx Step width × 10000
+/// @returns Approximate integral × 10000
 fn riemann_right(vals: int[], n: int, h_fx: int): int {
     let sum: int = 0;
     let i: int = 1;
@@ -96,8 +127,12 @@ fn riemann_right(vals: int[], n: int, h_fx: int): int {
     return sum * h_fx / 10000;
 }
 
-// riemann_mid(vals, n, h_fx): midpoint Riemann sum
-// vals: midpoint values (n-1 midpoints for n-1 intervals)
+/// Midpoint Riemann sum using precomputed midpoint values.
+/// @since 1.3.0
+/// @param vals Array of n midpoint values × 10000 (one per interval)
+/// @param n Number of intervals (i.e. length of vals)
+/// @param h_fx Step width × 10000
+/// @returns Approximate integral × 10000
 fn riemann_mid(vals: int[], n: int, h_fx: int): int {
     let sum: int = 0;
     let i: int = 0;
@@ -107,8 +142,12 @@ fn riemann_mid(vals: int[], n: int, h_fx: int): int {
 
 // ─── Curve length ────────────────────────────────────────────────────────────
 
-// curve_length_2d(xs, ys, n): approximate arc length of a 2D polyline
-// xs, ys: x and y coordinates ×10000 of n points
+/// Approximate arc length of a 2-D polyline through n points using the Euclidean distance between consecutive points.
+/// @since 1.3.0
+/// @param xs X coordinates × 10000 of the n points
+/// @param ys Y coordinates × 10000 of the n points
+/// @param n Number of points (must be ≥ 2)
+/// @returns Approximate arc length × 10000
 fn curve_length_2d(xs: int[], ys: int[], n: int): int {
     let total: int = 0;
     let i: int = 0;
@@ -124,26 +163,43 @@ fn curve_length_2d(xs: int[], ys: int[], n: int): int {
 
 // ─── Running statistics ───────────────────────────────────────────────────────
 
-// running_mean(prev_mean, new_val, n): Welford's online mean update
-// prev_mean ×10000, new_val ×10000, n: count after adding new_val (n ≥ 1)
+/// Welford's online algorithm: update a running mean with a new sample.
+/// @since 1.3.0
+/// @param prev_mean Previous mean × 10000
+/// @param new_val New sample value × 10000
+/// @param n Total count after adding the new sample (n ≥ 1)
+/// @returns Updated mean × 10000
 fn running_mean(prev_mean: int, new_val: int, n: int): int {
     if (n <= 1) { return new_val; }
     return prev_mean + (new_val - prev_mean) * 10000 / (n * 10000);
 }
 
-// running_m2(prev_m2, prev_mean, new_mean, new_val): Welford's M2 update
-// Used to compute variance: variance = m2 / (n-1)
+/// Welford's online algorithm: update the M2 accumulator used to compute variance.
+/// Variance = running_m2 / (n − 1) after n samples.
+/// @since 1.3.0
+/// @param prev_m2 Previous M2 accumulator × 10000
+/// @param prev_mean Mean before adding the new sample × 10000
+/// @param new_mean Mean after adding the new sample × 10000
+/// @param new_val New sample value × 10000
+/// @returns Updated M2 accumulator × 10000
 fn running_m2(prev_m2: int, prev_mean: int, new_mean: int, new_val: int): int {
     return prev_m2 + (new_val - prev_mean) * (new_val - new_mean) / 10000;
 }
 
-// variance_from_m2(m2, n): get variance from Welford's M2, n = number of samples
+/// Compute sample variance from a Welford M2 accumulator and sample count.
+/// @since 1.3.0
+/// @param m2 M2 accumulator from `running_m2` × 10000
+/// @param n Number of samples collected
+/// @returns Sample variance × 10000; returns 0 for n ≤ 1
 fn variance_from_m2(m2: int, n: int): int {
     if (n <= 1) { return 0; }
     return m2 / (n - 1);
 }
 
-// std_dev_approx(variance_fx): approximate std dev = √variance
+/// Approximate standard deviation as the integer square root of the variance.
+/// @since 1.3.0
+/// @param variance_fx Variance × 10000 (e.g. from `variance_from_m2`)
+/// @returns √variance × 10000; returns 0 for non-positive input
 fn std_dev_approx(variance_fx: int): int {
     if (variance_fx <= 0) { return 0; }
     return isqrt(variance_fx * 100) * 100 / 10000;

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,20 +1,44 @@
+// module library
 // Combat helpers for simple RPG-style datapacks.
 
-fn weapon_damage(base: int, bonus: int) -> int {
-    return base + bonus;
+/// 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
 }
 
-fn enemy_health(name: string) -> int {
-    return scoreboard_get(name, #health);
+/// 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) {
+        next = 0
+    }
+    return next
 }
 
-fn apply_damage(name: string, amount: int) {
-    let health: int = enemy_health(name);
-    let next: int = health - amount;
-
-    if (next < 0) {
-        scoreboard_set(name, #health, 0);
-    } else {
-        scoreboard_set(name, #health, next);
+/// 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
     }
+    return 0
 }

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

@@ -0,0 +1,93 @@
+// MC tellraw dialog system — high-level wrapper for player messaging.
+// Usage: import "stdlib/dialog.mcrs"
+//
+// Provides tellraw-based chat messages, title/subtitle display, and
+// actionbar notifications. All text is sent as raw JSON chat components.
+
+module library
+
+/// 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}\"}");
+}
+
+/// 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}\"}");
+}
+
+/// 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\"}");
+    } else {
+        if (color == 2) {
+            raw("tellraw {p} {\"text\":\"{msg}\",\"color\":\"green\"}");
+        } else {
+            if (color == 3) {
+                raw("tellraw {p} {\"text\":\"{msg}\",\"color\":\"gold\"}");
+            } else {
+                if (color == 4) {
+                    raw("tellraw {p} {\"text\":\"{msg}\",\"color\":\"aqua\"}");
+                } else {
+                    raw("tellraw {p} {\"text\":\"{msg}\",\"color\":\"white\"}");
+                }
+            }
+        }
+    }
+}
+
+/// 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}\"}");
+}
+
+/// 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");
+}
+
+/// 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}\"}");
+}