redscript-mc 2.5.0 → 2.6.2

package/src/examples/tutorial_06_math_particles.mcrs

@@ -0,0 +1,123 @@
+// ============================================
+// Tutorial 06: Standard Library — Math & Particles
+// ============================================
+// Demonstrates math functions and particle drawing.
+// Draws a circle and a helix using trig + particle helpers.
+// ============================================
+
+namespace tutorial06
+
+import math::*
+import particles::*
+
+// ─── Setup ──────────────────────────────────────────────────────────────────
+
+@load
+fn setup() {
+    say("Math & Particles tutorial loaded!")
+    say("Triggers: /trigger draw_circle  /trigger draw_helix  /trigger demo_math")
+}
+
+// ─── Demo: core math functions ───────────────────────────────────────────────
+
+@on_trigger("demo_math")
+fn demo_math() {
+    // abs — absolute value
+    let neg: int = abs(-42)             // 42
+    tell(@s, f"abs(-42) = {neg}")
+
+    // min / max
+    let lo: int = min(10, 20)           // 10
+    let hi: int = max(10, 20)           // 20
+    tell(@s, f"min(10,20) = {lo}  max(10,20) = {hi}")
+
+    // clamp — restrict a value to a range
+    let clamped: int = clamp(150, 0, 100)   // 100
+    tell(@s, f"clamp(150, 0, 100) = {clamped}")
+
+    // isqrt — integer square root
+    let root: int = isqrt(144)          // 12
+    tell(@s, f"isqrt(144) = {root}")
+
+    // sqrt_fixed — fixed-point sqrt (scale = 1000)
+    let sq2: int = sqrt_fixed(2000)     // ~1414 = sqrt(2) * 1000
+    tell(@s, f"sqrt_fixed(2000) = {sq2}  (sqrt(2) * 1000 = 1414)")
+
+    // sqrt_fx — fixed-point sqrt (scale = 10000)
+    let sq2_hp: int = sqrt_fx(20000)    // ~14142 = sqrt(2) * 10000
+    tell(@s, f"sqrt_fx(20000) = {sq2_hp}")
+
+    // sin_fixed / cos_fixed — trig in degrees, result * 1000
+    let sin30: int = sin_fixed(30)      // 500 = 0.5 * 1000
+    let cos60: int = cos_fixed(60)      // 500
+    tell(@s, f"sin_fixed(30) = {sin30}  cos_fixed(60) = {cos60}")
+
+    // lerp — linear interpolation  lerp(a, b, t) with t in [0,1000]
+    let midpoint: int = lerp(100, 200, 500)   // 150
+    tell(@s, f"lerp(100, 200, 500) = {midpoint}")
+
+    // mulfix — multiply two fixed-point values (scale=1000)
+    // mulfix(a,b) = a*b/1000
+    let product: int = mulfix(sin30, cos60)   // 500*500/1000 = 250
+    tell(@s, f"mulfix(500, 500) = {product}  (0.5 * 0.5 = 0.25 * 1000 = 250)")
+}
+
+// ─── Draw a circle of particles ──────────────────────────────────────────────
+
+// Uses draw_circle() from particles stdlib
+// Draws a circle in the XZ plane at Y=65, radius=5 blocks
+@on_trigger("draw_circle")
+fn do_draw_circle() {
+    // draw_circle(cx, cy, cz, radius*100, steps, particle)
+    // radius * 100 because coords are in units of 0.01 blocks
+    draw_circle(0, 65, 0, 500, 36, "minecraft:flame")
+    tell(@s, "Drew a circle of 36 flame particles!")
+}
+
+// ─── Draw a helix of particles ───────────────────────────────────────────────
+
+// Uses draw_helix() from particles stdlib
+@on_trigger("draw_helix")
+fn do_draw_helix() {
+    // draw_helix(cx, cy_start, cz, radius*100, height_blocks, rotations, steps, particle)
+    draw_helix(0, 64, 0, 300, 10, 3, 60, "minecraft:enchant")
+    tell(@s, "Drew a helix of 60 enchant particles!")
+}
+
+// ─── Manual sine wave using sin_fixed ────────────────────────────────────────
+
+// Draws a sine wave as particles at Y = 65 + sin(i*10°) * 3 blocks
+@on_trigger("draw_sine")
+fn draw_sine_wave() {
+    let i: int = 0
+    while (i < 36) {
+        let angle: int = i * 10          // 0, 10, 20, ... 350 degrees
+        let sin_val: int = sin_fixed(angle)  // -1000 .. +1000
+
+        // Convert to block coords:
+        //   x = i (1 block per step, 0..35)
+        //   y = 65 + sin_val * 3 / 1000  (±3 blocks amplitude)
+        //   z = 0
+        let y_offset: int = sin_val * 3 / 1000
+        let y_pos: int = 65 + y_offset
+
+        // particle_dot places a single particle at integer block coords
+        particle_dot(i, y_pos, 0, "minecraft:end_rod")
+
+        i = i + 1
+    }
+    tell(@s, "Drew a sine wave!")
+}
+
+// ─── Particle effects helpers demo ──────────────────────────────────────────
+
+@on_trigger("particle_demo")
+fn particle_demo() {
+    // Convenience functions from particles stdlib
+    flames(0, 66, 0)
+    sparkles_at(1, 66, 0)
+    hearts_at(2, 66, 0)
+    smoke(3, 66, 0)
+    explosion_effect(4, 66, 0)
+    tell(@s, "Spawned particle effects!")
+}

package/src/examples/tutorial_07_random.mcrs

@@ -0,0 +1,142 @@
+// ============================================
+// Tutorial 07: Standard Library — Random & Noise
+// ============================================
+// A treasure chest generator that uses:
+// 1. random_range to pick loot items
+// 2. value_noise_1d for a natural reward multiplier
+// 3. binomial_sample to determine bonus chest count
+// ============================================
+
+namespace tutorial07
+
+import random::*
+import noise::*
+
+// ─── State ──────────────────────────────────────────────────────────────────
+
+@load
+fn setup() {
+    scoreboard_add_objective("rng_seed", "dummy")
+    // Seed from a large prime for variety
+    scoreboard_set("#seed", "rng_seed", 987654321)
+    say("Treasure system loaded! /trigger open_chest  /trigger terrain_demo")
+}
+
+// ─── Get and advance the global seed ─────────────────────────────────────────
+
+fn advance_seed() -> int {
+    let seed: int = scoreboard_get("#seed", "rng_seed")
+    seed = next_lcg(seed)
+    scoreboard_set("#seed", "rng_seed", seed)
+    return seed
+}
+
+// ─── Loot table using random_range ───────────────────────────────────────────
+
+fn pick_loot_item(seed: int) -> string {
+    // random_range returns a value in [lo, hi)
+    let roll: int = random_range(seed, 0, 10)  // 0..9
+
+    if (roll < 2) {
+        return "minecraft:diamond"        // 20%
+    }
+    if (roll < 5) {
+        return "minecraft:gold_ingot"     // 30%
+    }
+    if (roll < 8) {
+        return "minecraft:iron_ingot"     // 30%
+    }
+    return "minecraft:bread"              // 20%
+}
+
+fn item_name(item: string) -> string {
+    if (item == "minecraft:diamond") { return "Diamond" }
+    if (item == "minecraft:gold_ingot") { return "Gold Ingot" }
+    if (item == "minecraft:iron_ingot") { return "Iron Ingot" }
+    return "Bread"
+}
+
+// ─── Open a treasure chest ───────────────────────────────────────────────────
+
+@on_trigger("open_chest")
+fn open_chest() {
+    tell(@s, "=== Treasure Chest ===")
+
+    // 1. Pick loot item
+    let seed1: int = advance_seed()
+    let item: string = pick_loot_item(seed1)
+    let name: string = item_name(item)
+
+    // 2. Reward multiplier from value_noise_1d
+    // value_noise_1d returns [0, 10000]  → scale to [1, 3] count
+    let seed2: int = advance_seed()
+    let noise_val: int = value_noise_1d(seed2)   // [0, 10000]
+    // Map [0, 10000] to [1, 3]  using linear mapping
+    let count: int = 1 + noise_val * 2 / 10000   // 1 or 2 or 3
+
+    // 3. Bonus chest count from binomial_sample
+    // binomial_sample(n, p*10000, seed) = successes in n trials with prob p
+    let seed3: int = advance_seed()
+    let bonus: int = binomial_sample(3, 2500, seed3)   // 3 trials, 25% each → 0..3
+
+    tell(@s, f"Found: {count}x {name}")
+    give(@s, item, count)
+
+    if (bonus > 0) {
+        tell(@s, f"BONUS! +{bonus} extra chests!")
+        let b: int = 0
+        while (b < bonus) {
+            let bseed: int = advance_seed()
+            let bitem: string = pick_loot_item(bseed)
+            give(@s, bitem, 1)
+            b = b + 1
+        }
+    } else {
+        tell(@s, "No bonus chests this time.")
+    }
+
+    announce("A player opened a treasure chest!")
+}
+
+// ─── Terrain height demo using value noise ───────────────────────────────────
+
+@on_trigger("terrain_demo")
+fn terrain_demo() {
+    tell(@s, "=== Terrain Noise Demo ===")
+    // terrain_height(x, z, base_y, amplitude)
+    // uses 3-octave fbm under the hood
+    let i: int = 0
+    while (i < 5) {
+        let h: int = terrain_height(i, 0, 64, 20)
+        tell(@s, f"x={i} → height={h}")
+        i = i + 1
+    }
+}
+
+// ─── fbm (fractal Brownian motion) demo ─────────────────────────────────────
+
+@on_trigger("fbm_demo")
+fn fbm_demo() {
+    tell(@s, "=== FBM Noise (4 octaves) ===")
+    let i: int = 0
+    while (i < 8) {
+        // x_fx in ×10000 fixed-point: i * 5000 = 0.0, 0.5, 1.0, ...
+        let x_fx: int = i * 5000
+        let n: int = fbm_1d(x_fx, 4, 5000)   // 4 octaves, persistence=0.5
+        tell(@s, f"fbm({i}/2) = {n}")
+        i = i + 1
+    }
+}
+
+// ─── Random bool demo ────────────────────────────────────────────────────────
+
+@on_trigger("coin_flip")
+fn coin_flip() {
+    let seed: int = advance_seed()
+    let result: int = random_bool(seed)
+    if (result == 1) {
+        tell(@s, "Coin flip: HEADS!")
+    } else {
+        tell(@s, "Coin flip: TAILS!")
+    }
+}

package/src/examples/tutorial_08_coroutine.mcrs

@@ -0,0 +1,163 @@
+// ============================================
+// Tutorial 08: Coroutines — Spread Heavy Work
+// ============================================
+// Phase 1: Scan a 100×100 region using @coroutine(batch=50)
+//          Yields at loop back-edges → 50 iterations per tick
+//          → 10000/50 = 200 ticks total (10 seconds)
+// Phase 2: After scan completes (onDone), announce results
+// ============================================
+
+namespace tutorial08
+
+// ─── State ──────────────────────────────────────────────────────────────────
+
+struct ScanState {
+    blocks_checked: int,
+    special_found: int,
+    scan_running: int
+}
+
+let scan: ScanState = {
+    blocks_checked: 0,
+    special_found: 0,
+    scan_running: 0
+}
+
+// ─── Setup ──────────────────────────────────────────────────────────────────
+
+@load
+fn setup() {
+    scoreboard_add_objective("scan_data", "dummy")
+    say("Coroutine tutorial loaded! /trigger start_scan")
+    say("The scan will process 50 blocks per tick over 200 ticks.")
+}
+
+// ─── Trigger the scan ───────────────────────────────────────────────────────
+
+@on_trigger("start_scan")
+fn start_scan() {
+    if (scan.scan_running == 1) {
+        tell(@s, "Scan already in progress!")
+        return
+    }
+
+    scan.blocks_checked = 0
+    scan.special_found = 0
+    scan.scan_running = 1
+
+    announce("Starting 100x100 region scan... (will take ~10 seconds)")
+    run_scan()
+}
+
+// ─── The coroutine: scan 100×100 = 10000 positions ─────────────────────────
+//
+// @coroutine(batch=50) means:
+//   - The while loop yields at its back-edge every 50 iterations
+//   - So 10000 iterations / 50 = 200 ticks = 10 seconds
+//   - Without @coroutine this would run all 10000 iterations in ONE tick
+//     → crash with "maxCommandChainLength exceeded" (default limit is 65536)
+//
+// Yield point: the BACK-EDGE of a loop (end of loop body, before condition check)
+// There is NO explicit yield keyword — it happens automatically.
+//
+// onDone: specifies a function to call when the coroutine finishes.
+
+@coroutine(batch=50)
+fn run_scan() {
+    let i: int = 0
+    // 10000 iterations total, 50 per tick
+    while (i < 10000) {
+        // Simulate scanning a block: x = i%100, z = i/100
+        let x: int = i % 100
+        let z: int = i / 100
+
+        // Pretend every 200th block is "special" (5% of region)
+        if (i % 200 == 0) {
+            scan.special_found = scan.special_found + 1
+        }
+
+        scan.blocks_checked = scan.blocks_checked + 1
+
+        // Progress update every 1000 blocks (every 20 ticks)
+        if (scan.blocks_checked % 1000 == 0) {
+            let pct: int = scan.blocks_checked * 100 / 10000
+            actionbar(@a, f"Scanning: {pct}% ({scan.blocks_checked}/10000)")
+        }
+
+        i = i + 1
+        // <- Back-edge: coroutine yields here every 50 iterations
+    }
+    // When the while loop finishes, onDone fires:
+    scan_complete()
+}
+
+// ─── Called automatically when run_scan() finishes ──────────────────────────
+
+fn scan_complete() {
+    scan.scan_running = 0
+
+    say("=== Scan Complete! ===")
+    say(f"Blocks checked: {scan.blocks_checked}")
+    say(f"Special blocks found: {scan.special_found}")
+
+    title(@a, "Scan Done!")
+    let found: int = scan.special_found
+    subtitle(@a, f"Special blocks found: {found}")
+
+    // Give a report item to all players
+    foreach (p in @a) {
+        give(p, "minecraft:paper", 1)
+        tell(p, f"Your scan report: {scan.special_found} special blocks in 100x100 region")
+    }
+}
+
+// ─── Status check ────────────────────────────────────────────────────────────
+
+@on_trigger("scan_status")
+fn scan_status() {
+    if (scan.scan_running == 0) {
+        tell(@s, f"No scan running. Last result: {scan.special_found} special blocks")
+        return
+    }
+
+    let pct: int = scan.blocks_checked * 100 / 10000
+    tell(@s, f"Scan in progress: {pct}% ({scan.blocks_checked}/10000)")
+}
+
+// ─── Chained coroutine example ───────────────────────────────────────────────
+//
+// You can chain coroutines: when one finishes, start another.
+// Here we do a 3-phase pipeline: collect → process → report
+
+@on_trigger("chained_scan")
+fn start_chained() {
+    announce("Starting chained coroutine pipeline...")
+    phase1_collect()
+}
+
+@coroutine(batch=100)
+fn phase1_collect() {
+    let i: int = 0
+    while (i < 500) {
+        // Simulate data collection
+        i = i + 1
+    }
+    announce("Phase 1 (collect) done — starting phase 2")
+    phase2_process()
+}
+
+@coroutine(batch=25)
+fn phase2_process() {
+    let i: int = 0
+    while (i < 200) {
+        // Simulate heavy processing
+        i = i + 1
+    }
+    announce("Phase 2 (process) done — starting phase 3")
+    phase3_report()
+}
+
+fn phase3_report() {
+    say("Pipeline complete! All 3 phases finished.")
+    title(@a, "Pipeline Done")
+}

package/src/examples/tutorial_09_precision.mcrs

@@ -0,0 +1,154 @@
+// ============================================
+// Tutorial 09: Precision Arithmetic — fixed & double
+// ============================================
+// Demonstrates:
+// 1. fixed-point (×10000) for 4-decimal precision
+// 2. double type (NBT-backed IEEE 754) for 8+ decimal precision
+// 3. Compound interest: A = P * (1.05)^t
+// 4. Casting between types
+// ============================================
+
+namespace tutorial09
+
+import math::*
+import math_hp::*
+
+// ─── Setup ──────────────────────────────────────────────────────────────────
+
+@load
+fn on_load() {
+    scoreboard_add_objective("precision_data", "dummy")
+    scoreboard_add_objective("result_display", "dummy")
+    scoreboard_display("sidebar", "result_display")
+    say("Precision arithmetic tutorial! /trigger compound_interest  /trigger fixed_demo")
+}
+
+// ─── Fixed-point demo ────────────────────────────────────────────────────────
+
+@on_trigger("fixed_demo")
+fn fixed_demo() {
+    tell(@s, "=== Fixed-Point Arithmetic (×10000 scale) ===")
+
+    // fixed stores values as integer × 10000
+    // 1.5 → 15000,  3.14 → 31400,  0.001 → 10
+    let a: fixed = 15000 as fixed   // 1.5
+    let b: fixed = 25000 as fixed   // 2.5
+
+    // Arithmetic on fixed values works like int arithmetic
+    // BUT remember: adding two fixed values is fine (15000+25000=40000 = 4.0)
+    // Multiplying needs manual rescaling: a*b/10000
+
+    let sum: int = (a as int) + (b as int)   // 40000 = 4.0
+    tell(@s, f"1.5 + 2.5 = {sum} (×10000, real value = 4.0)")
+
+    // Multiply: must divide by 10000 to stay in scale
+    let product: int = mulfix(a as int, b as int)   // 15000*25000/1000 ≈ 375000? No!
+    // mulfix uses scale=1000, but our fixed uses scale=10000
+    // For ×10000 scale: use (a * b) / 10000
+    let product_fx: int = (a as int) * (b as int) / 10000
+    tell(@s, f"1.5 * 2.5 = {product_fx} (×10000, real value = 3.75)")
+
+    // Percentage calculation
+    let score: int = 750    // raw score
+    let max_score: int = 1000
+    let pct_fx: fixed = (score * 10000 / max_score) as fixed  // 7500 = 75.00%
+    tell(@s, f"Score {score}/{max_score} = {(pct_fx as int)} (×10000 = 75.00%)")
+
+    // sqrt_fx: fixed-point square root (×10000 scale)
+    // sqrt_fx(20000) ≈ 14142 means sqrt(2.0) ≈ 1.4142
+    let sqrt2: int = sqrt_fx(20000)
+    tell(@s, f"sqrt(2.0) ≈ {sqrt2} (×10000)")
+
+    // sin_fixed: degrees, result ×1000 (note: math lib uses scale=1000 not 10000)
+    let sin45: int = sin_fixed(45)   // ≈ 707
+    tell(@s, f"sin(45°) ≈ {sin45} (×1000 = 0.707)")
+}
+
+// ─── Compound interest with fixed-point ─────────────────────────────────────
+// A = P * (1 + r)^t
+// Using fixed-point: rate = 500 (0.05 = 5%)
+
+@on_trigger("compound_interest")
+fn compound_interest() {
+    tell(@s, "=== Compound Interest Demo ===")
+    tell(@s, "P = 1000, rate = 5%, t = 10 years")
+
+    // Fixed-point approach
+    let principal: int = 1000
+    let rate_fx: int = 500   // 0.05 * 10000 = 500
+    let base_fx: int = 10000 + rate_fx   // 1.05 × 10000 = 10500
+
+    let amount: int = principal
+    let t: int = 0
+    while (t < 10) {
+        // A = A * 1.05  in fixed-point: A = A * base_fx / 10000
+        amount = amount * base_fx / 10000
+        t = t + 1
+    }
+
+    tell(@s, f"Fixed-point result: {amount} (expected ~1629)")
+    scoreboard_set("#result_fx", "result_display", amount)
+    scoreboard_set("#result_fx", "precision_data", amount)
+
+    // Show step-by-step for first 3 years
+    let a: int = principal
+    tell(@s, "Year-by-year (fixed):")
+    let yr: int = 1
+    while (yr <= 5) {
+        a = a * base_fx / 10000
+        tell(@s, f"Year {yr}: {a}")
+        yr = yr + 1
+    }
+}
+
+// ─── Double precision compound interest ─────────────────────────────────────
+// Uses NBT-backed IEEE 754 doubles for higher precision
+
+@on_trigger("compound_double")
+fn compound_double() {
+    tell(@s, "=== Compound Interest (double precision) ===")
+    tell(@s, "P = 1000.0, rate = 5%, t = 10 years")
+
+    // pow_real(base, exp) computes base^exp using ln/exp
+    // base = 1.05d, exp = 10.0d
+    let base: double = 1.05d
+    let exp_val: double = 10.0d
+
+    let result: double = pow_real(base, exp_val) as double
+
+    // Convert result to int (×10000) to display
+    let result_int: int = result as int
+    scoreboard_set("#result_dbl", "result_display", result_int)
+    tell(@s, f"Double result (×10000): {result_int} (expected ~16289 = 1.6289)")
+
+    // Compare precision
+    // Fixed:  1000 * 10500^10 / 10000^10  (integer truncation each step)
+    // Double: exact IEEE 754 floating point computation
+    tell(@s, "Fixed gave: check sidebar 'result_fx' vs 'result_dbl'")
+}
+
+// ─── Casting between types ───────────────────────────────────────────────────
+
+@on_trigger("cast_demo")
+fn cast_demo() {
+    tell(@s, "=== Type Casting Demo ===")
+
+    let i: int = 42
+    let f: fixed = i as fixed       // int → fixed: just stores as-is (42 as fixed)
+    tell(@s, f"int 42 as fixed = {(f as int)} (note: fixed stores the raw int)")
+
+    // To represent 4.2 as fixed: store 42000 (4.2 × 10000)
+    let four_two: fixed = 42000 as fixed
+    tell(@s, f"4.2 as fixed = {(four_two as int)} (×10000)")
+
+    // fixed → int: drops the scale factor, use / 10000 for real value
+    let raw: int = four_two as int
+    let real: int = raw / 10000   // integer part
+    let decimal: int = raw % 10000   // decimal part (×10000)
+    tell(@s, f"4.2 in fixed: integer={real} decimal={decimal}")
+
+    // double → int: reads the double as a ×10000 fixed integer
+    let d: double = 3.14d
+    let d_int: int = d as int
+    tell(@s, f"3.14d as int = {d_int} (×10000 = 31400)")
+}