redscript-mc 2.4.1 → 2.5.0

package/src/stdlib/easing.mcrs

@@ -0,0 +1,182 @@
+// easing.mcrs — Easing functions for animations and transitions.
+//
+// All functions take t ∈ [0, 10000] (fixed-point ×10000)
+// and return a value in [0, 10000] (or slightly outside for elastic/bounce).
+//
+// Common use: smooth particle movement, UI transitions, projectile arcs
+//
+// Requires: import "stdlib/math" (for abs, clamp, mul_fixed)
+
+module library;
+
+// ─── Linear ──────────────────────────────────────────────────────────────────
+
+fn ease_linear(t: int): int { return t; }
+
+// ─── Quadratic ───────────────────────────────────────────────────────────────
+
+// ease_in_quad: slow start, fast end
+fn ease_in_quad(t: int): int {
+    return t * t / 10000;
+}
+
+// ease_out_quad: fast start, slow end
+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
+fn ease_in_out_quad(t: int): int {
+    if (t < 5000) {
+        return 2 * t * t / 10000;
+    }
+    let inv: int = 10000 - t;
+    return 10000 - 2 * inv * inv / 10000;
+}
+
+// ─── Cubic ───────────────────────────────────────────────────────────────────
+
+fn ease_in_cubic(t: int): int {
+    return t * t / 10000 * t / 10000;
+}
+
+fn ease_out_cubic(t: int): int {
+    let inv: int = 10000 - t;
+    return 10000 - inv * inv / 10000 * inv / 10000;
+}
+
+fn ease_in_out_cubic(t: int): int {
+    if (t < 5000) {
+        return 4 * t * t / 10000 * t / 10000;
+    }
+    let inv: int = 10000 - t;
+    return 10000 - 4 * inv * inv / 10000 * inv / 10000;
+}
+
+// ─── Quartic ──────────────────────────────────────────────────────────────────
+
+fn ease_in_quart(t: int): int {
+    let t2: int = t * t / 10000;
+    return t2 * t2 / 10000;
+}
+
+fn ease_out_quart(t: int): int {
+    let inv: int = 10000 - t;
+    let inv2: int = inv * inv / 10000;
+    return 10000 - inv2 * inv2 / 10000;
+}
+
+// ─── Sine approximation ───────────────────────────────────────────────────────
+// Approximated using polynomial — no actual trig needed for easing
+
+// ease_in_sine: t ∈ [0,10000] → starts slow, accelerates
+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;
+    let t4: int = t2 * t2 / 10000;
+    let cos_approx: int = 10000 - t2 * 4934 / 10000 + t4 * 405 / 10000;
+    return 10000 - cos_approx;
+}
+
+fn ease_out_sine(t: int): int {
+    return 10000 - ease_in_sine(10000 - t);
+}
+
+fn ease_in_out_sine(t: int): int {
+    if (t < 5000) {
+        return ease_in_sine(t * 2) / 2;
+    }
+    return 5000 + ease_out_sine((t - 5000) * 2) / 2;
+}
+
+// ─── Exponential ─────────────────────────────────────────────────────────────
+
+// ease_in_expo: very slow start, explosive end
+fn ease_in_expo(t: int): int {
+    if (t <= 0) { return 0; }
+    // Approximate 2^(10t-10) ≈ exp_fx((10*t-100000)*693/10000)
+    // Simplified: use cubic as proxy for games
+    let t3: int = t * t / 10000 * t / 10000;
+    return t3;
+}
+
+fn ease_out_expo(t: int): int {
+    if (t >= 10000) { return 10000; }
+    return 10000 - ease_in_expo(10000 - t);
+}
+
+// ─── Back (overshoot) ─────────────────────────────────────────────────────────
+
+// ease_in_back: slight pullback before moving forward
+// c1 = 1.70158 × 10000 = 17015
+fn ease_in_back(t: int): int {
+    let c1: int = 17015;   // 1.70158
+    let c3: int = c1 + 10000;  // c1 + 1
+    // t³ * c3 - t² * c1
+    let t2: int = t * t / 10000;
+    let t3: int = t2 * t / 10000;
+    return t3 * c3 / 10000 - t2 * c1 / 10000;
+}
+
+fn ease_out_back(t: int): int {
+    return 10000 - ease_in_back(10000 - t);
+}
+
+fn ease_in_out_back(t: int): int {
+    if (t < 5000) {
+        return ease_in_back(t * 2) / 2;
+    }
+    return 5000 + ease_out_back((t - 5000) * 2) / 2;
+}
+
+// ─── Bounce ───────────────────────────────────────────────────────────────────
+
+// ease_out_bounce: bounces at the end (ball dropping)
+fn ease_out_bounce(t: int): int {
+    let n1: int = 75625;  // 7.5625 × 10000
+    let d1: int = 27500;  // 2.75 × 10000
+    // Piecewise: 4 bounce segments
+    if (t < 3636) {  // t < 1/2.75
+        return n1 * t / 10000 * t / 10000;
+    }
+    if (t < 7272) {  // t < 2/2.75
+        let t2: int = t - 5454;  // t - 1.5/2.75
+        return n1 * t2 / 10000 * t2 / 10000 + 7500;
+    }
+    if (t < 9090) {  // t < 2.5/2.75
+        let t2: int = t - 8181;  // t - 2.25/2.75
+        return n1 * t2 / 10000 * t2 / 10000 + 9375;
+    }
+    let t2: int = t - 9545;  // t - 2.625/2.75
+    return n1 * t2 / 10000 * t2 / 10000 + 9844;
+}
+
+fn ease_in_bounce(t: int): int {
+    return 10000 - ease_out_bounce(10000 - t);
+}
+
+fn ease_in_out_bounce(t: int): int {
+    if (t < 5000) {
+        return ease_in_bounce(t * 2) / 2;
+    }
+    return 5000 + ease_out_bounce((t - 5000) * 2) / 2;
+}
+
+// ─── Smoothstep family ────────────────────────────────────────────────────────
+
+// smoothstep already in math.mcrs — re-exported here for convenience
+// smoothstep(t) = 3t² - 2t³
+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³
+fn ease_smoother(t: int): int {
+    let t2: int = t * t / 10000;
+    let t3: int = t2 * t / 10000;
+    let t4: int = t3 * t / 10000;
+    let t5: int = t4 * t / 10000;
+    return 6 * t5 / 10000 - 15 * t4 / 10000 + 10 * t3 / 10000;
+}

package/src/stdlib/matrix.mcrs

@@ -0,0 +1,108 @@
+// matrix.mcrs — 2D/3D transformation matrices for Display Entities.
+//
+// MC Display Entities use a 4×4 transformation matrix (left_rotation × scale × right_rotation).
+// This module provides helpers for common transforms.
+//
+// Fixed-point: all values ×10000 unless noted.
+// Angle: degrees ×10000 (e.g. 450000 = 45°)
+//
+// Note: Actual matrix application to entities requires raw() commands.
+// These functions compute the values; use raw() to apply them.
+//
+// Requires: import "stdlib/math" (for sin_fixed, cos_fixed, abs)
+
+module library;
+
+// ─── 2D transform helpers ────────────────────────────────────────────────────
+
+// rotate2d_x: x component after 2D rotation by angle_deg×10000
+// rotate2d_x(x, y, 450000) ≈ x*cos45 - y*sin45
+fn rotate2d_x(x: int, y: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return x * c / 1000 - y * s / 1000;
+}
+
+fn rotate2d_y(x: int, y: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return x * s / 1000 + y * c / 1000;
+}
+
+// ─── Scale helpers ────────────────────────────────────────────────────────────
+
+// scale_x(x, sx_fx): scale x by sx_fx (sx_fx ×10000, e.g. 20000 = 2×)
+fn scale_x(x: int, sx_fx: int): int { return x * sx_fx / 10000; }
+fn scale_y(y: int, sy_fx: int): int { return y * sy_fx / 10000; }
+fn scale_z(z: int, sz_fx: int): int { return z * sz_fx / 10000; }
+
+// uniform_scale(v, s_fx): apply uniform scale
+fn uniform_scale(v: int, s_fx: int): int { return v * s_fx / 10000; }
+
+// ─── 3D rotation (Euler angles, Y-up) ────────────────────────────────────────
+
+// rotate_y_x: X component after rotation around Y axis
+fn rotate_y_x(x: int, z: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return x * c / 1000 + z * s / 1000;
+}
+
+fn rotate_y_z(x: int, z: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return 0 - x * s / 1000 + z * c / 1000;
+}
+
+// rotate_x_y: Y component after rotation around X axis
+fn rotate_x_y(y: int, z: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return y * c / 1000 - z * s / 1000;
+}
+
+fn rotate_x_z(y: int, z: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return y * s / 1000 + z * c / 1000;
+}
+
+// ─── Display Entity transformation ───────────────────────────────────────────
+// MC Display Entity transformation format:
+//   transformation: {left_rotation:[0f,0f,0f,1f], scale:[1f,1f,1f],
+//                    right_rotation:[0f,0f,0f,1f], translation:[0f,0f,0f]}
+//
+// Quaternion for Y-axis rotation by angle θ:
+//   [0, sin(θ/2), 0, cos(θ/2)]
+//
+// These helpers compute quaternion components (×10000)
+
+// quat_sin_half(angle_deg_fx): sin(angle/2) ×1000
+// angle_deg_fx: degrees ×10000
+fn quat_sin_half(angle_deg_fx: int): int {
+    return sin_fixed(angle_deg_fx / 20000);  // angle/2 in degrees, then /10000 for sin_fixed
+}
+
+fn quat_cos_half(angle_deg_fx: int): int {
+    return cos_fixed(angle_deg_fx / 20000);
+}
+
+// ─── Billboard helpers ────────────────────────────────────────────────────────
+
+// billboard_rotation_y(player_yaw_fx): get Y rotation for a billboard facing player
+// player_yaw_fx: player yaw ×10000 (from entity NBT Rotation[0])
+fn billboard_y(player_yaw_fx: int): int {
+    // Billboard should face opposite direction
+    return (player_yaw_fx + 1800000) % 3600000;
+}
+
+// ─── Interpolation for smooth animation ──────────────────────────────────────
+
+// lerp_angle(a_fx, b_fx, t): lerp between two angles ×10000, taking shortest path
+fn lerp_angle(a_fx: int, b_fx: int, t: int): int {
+    let diff: int = b_fx - a_fx;
+    // Normalize to [-1800000, 1800000]
+    while (diff > 1800000) { diff = diff - 3600000; }
+    while (diff < -1800000) { diff = diff + 3600000; }
+    return a_fx + diff * t / 10000;
+}

package/src/stdlib/noise.mcrs

@@ -0,0 +1,153 @@
+// noise.mcrs — Procedural noise functions for Minecraft datapacks.
+//
+// Uses fixed-point arithmetic (×10000 scale).
+// No floating point, no external dependencies.
+//
+// Functions:
+//   hash_1d, hash_2d — integer hash (pseudo-random per coordinate)
+//   value_noise_1d   — smooth 1D value noise [0, 10000]
+//   value_noise_2d   — smooth 2D value noise [0, 10000]
+//   fbm_1d           — fractal Brownian motion (octave stacking)
+//
+// Requires: import "stdlib/math" (for lerp, abs, clamp)
+
+module library;
+
+// ─── Hash functions ───────────────────────────────────────────────────────────
+
+// hash_1d(x): pseudo-random int from a 1D coordinate
+// Returns any int (use % to restrict range)
+fn hash_1d(x: int): int {
+    let h: int = x * 374761393;
+    h = h + 1013904223;
+    h = h * 1664525;
+    h = h + (h / 65536);
+    return h;
+}
+
+// hash_2d(x, z): pseudo-random int from 2D coordinates
+fn hash_2d(x: int, z: int): int {
+    return hash_1d(x + hash_1d(z));
+}
+
+// hash_1d_pos(x): hash in [0, 10000]
+fn hash_1d_pos(x: int): int {
+    let h: int = hash_1d(x);
+    if (h < 0) { h = 0 - h; }
+    return h % 10001;
+}
+
+// hash_2d_pos(x, z): hash in [0, 10000]
+fn hash_2d_pos(x: int, z: int): int {
+    let h: int = hash_2d(x, z);
+    if (h < 0) { h = 0 - h; }
+    return h % 10001;
+}
+
+// ─── Value noise ─────────────────────────────────────────────────────────────
+
+// value_noise_1d(x_fx): smooth 1D noise at position x_fx (fixed-point ×10000)
+// Returns value in [0, 10000]
+// Uses linear interpolation between random values at integer coords
+fn value_noise_1d(x_fx: int): int {
+    let xi: int = x_fx / 10000;   // integer part
+    let xf: int = x_fx % 10000;   // fractional part [0, 9999]
+    if (xf < 0) { xf = xf + 10000; xi = xi - 1; }
+
+    let v0: int = hash_1d_pos(xi);
+    let v1: int = hash_1d_pos(xi + 1);
+
+    // Smooth interpolation using smoothstep on xf
+    let t: int = 3 * xf * xf / 10000 - 2 * xf * xf / 10000 * xf / 10000;
+    return v0 + (v1 - v0) * t / 10000;
+}
+
+// value_noise_2d(x_fx, z_fx): smooth 2D noise
+// Returns value in [0, 10000]
+fn value_noise_2d(x_fx: int, z_fx: int): int {
+    let xi: int = x_fx / 10000;
+    let xf: int = x_fx % 10000;
+    if (xf < 0) { xf = xf + 10000; xi = xi - 1; }
+
+    let zi: int = z_fx / 10000;
+    let zf: int = z_fx % 10000;
+    if (zf < 0) { zf = zf + 10000; zi = zi - 1; }
+
+    // Bilinear interpolation of 4 corner values
+    let v00: int = hash_2d_pos(xi, zi);
+    let v10: int = hash_2d_pos(xi + 1, zi);
+    let v01: int = hash_2d_pos(xi, zi + 1);
+    let v11: int = hash_2d_pos(xi + 1, zi + 1);
+
+    // Smooth t values
+    let tx: int = 3 * xf * xf / 10000 - 2 * xf * xf / 10000 * xf / 10000;
+    let tz: int = 3 * zf * zf / 10000 - 2 * zf * zf / 10000 * zf / 10000;
+
+    // Bilinear interpolation
+    let vz0: int = v00 + (v10 - v00) * tx / 10000;
+    let vz1: int = v01 + (v11 - v01) * tx / 10000;
+    return vz0 + (vz1 - vz0) * tz / 10000;
+}
+
+// ─── Fractal Brownian Motion ──────────────────────────────────────────────────
+
+// fbm_1d(x_fx, octaves, persistence_fx):
+//   x_fx: position ×10000
+//   octaves: number of noise layers (1-6, more = more detail)
+//   persistence_fx: amplitude decay per octave ×10000 (typical: 5000 = 0.5)
+// Returns value in approximately [0, 10000]
+fn fbm_1d(x_fx: int, octaves: int, persistence_fx: int): int {
+    let value: int = 0;
+    let amplitude: int = 10000;
+    let frequency: int = 10000;  // ×10000 multiplier (starts at 1.0)
+    let max_val: int = 0;         // for normalization
+
+    let oct: int = 0;
+    while (oct < octaves) {
+        let sample_x: int = x_fx * frequency / 10000;
+        value = value + value_noise_1d(sample_x) * amplitude / 10000;
+        max_val = max_val + amplitude;
+        amplitude = amplitude * persistence_fx / 10000;
+        frequency = frequency * 2;
+        oct = oct + 1;
+    }
+
+    // Normalize to [0, 10000]
+    if (max_val <= 0) { return 0; }
+    return value * 10000 / max_val;
+}
+
+// fbm_2d(x_fx, z_fx, octaves, persistence_fx): 2D fractal Brownian motion
+fn fbm_2d(x_fx: int, z_fx: int, octaves: int, persistence_fx: int): int {
+    let value: int = 0;
+    let amplitude: int = 10000;
+    let frequency: int = 10000;
+    let max_val: int = 0;
+
+    let oct: int = 0;
+    while (oct < octaves) {
+        let sx: int = x_fx * frequency / 10000;
+        let sz: int = z_fx * frequency / 10000;
+        value = value + value_noise_2d(sx, sz) * amplitude / 10000;
+        max_val = max_val + amplitude;
+        amplitude = amplitude * persistence_fx / 10000;
+        frequency = frequency * 2;
+        oct = oct + 1;
+    }
+
+    if (max_val <= 0) { return 0; }
+    return value * 10000 / max_val;
+}
+
+// ─── Convenience: terrain height ─────────────────────────────────────────────
+
+// terrain_height(x, z, base_y, amplitude):
+//   Generates a terrain height using 3-octave fbm.
+//   x, z: block coordinates (integers, NOT fixed-point)
+//   base_y: baseline height in blocks
+//   amplitude: max height variation in blocks
+fn terrain_height(x: int, z: int, base_y: int, amplitude: int): int {
+    // Scale x,z by ×10000 for fixed-point, divide by 4 for wider features
+    let noise: int = fbm_2d(x * 2500, z * 2500, 3, 5000);
+    return base_y + noise * amplitude / 10000;
+}

package/src/stdlib/physics.mcrs

@@ -0,0 +1,134 @@
+// physics.mcrs — Simple physics simulation for Minecraft datapacks.
+//
+// Fixed-point convention: positions/velocities ×100 (1 block = 100 units)
+// Time unit: 1 tick = 1/20 second
+// Gravity: MC default ≈ 0.08 blocks/tick² = 8 units/tick²
+//
+// All functions operate on components separately (x, y, z).
+// No vector types — returns each axis independently for MC compatibility.
+
+module library;
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+fn gravity_fx(): int { return 8; }      // 0.08 blocks/tick² × 100
+fn air_drag_fx(): int { return 9800; }  // 0.98 drag factor × 10000 (per tick)
+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
+fn projectile_y(p0: int, v0: int, t: int): int {
+    return p0 + v0 * t - gravity_fx() * t * t / 2;
+}
+
+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)
+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
+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)
+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
+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
+fn apply_gravity(vy_fx: int): int {
+    return vy_fx - gravity_fx();
+}
+
+// update_pos(p_fx, v_fx): update position by one 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
+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
+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; }
+    return v_fx;
+}
+
+// ─── Spring physics ───────────────────────────────────────────────────────────
+
+// spring_force(pos_fx, target_fx, k_fx): Hooke's law F = -k(x - target)
+// k_fx: spring constant ×10000
+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
+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;
+    return damped + force;
+}
+
+// ─── Circular motion ─────────────────────────────────────────────────────────
+
+// circular_x(cx, r, angle_deg): X position on circle
+// cx: center X ×100, r: radius ×100, angle_deg: degrees (NOT ×10000)
+fn circular_x(cx: int, r: int, angle_deg: int): int {
+    return cx + r * cos_fixed(angle_deg) / 1000;
+}
+
+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)
+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; }
+    return 0;
+}
+
+// ─── Impact detection ────────────────────────────────────────────────────────
+
+// is_grounded(y_fx, ground_y_fx): returns 1 if at or below ground
+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
+fn impact_velocity(h_fx: int): int {
+    if (h_fx <= 0) { return 0; }
+    return isqrt(2 * gravity_fx() * h_fx / 100) * 10;
+}