redscript-mc 2.5.0 → 2.6.0

package/src/examples/tutorial_05_decorators.mcrs

@@ -0,0 +1,131 @@
+// ============================================
+// Tutorial 05: Decorators & Scheduling
+// ============================================
+// A countdown timer system:
+// - /trigger start_countdown  begins a 10-second countdown
+// - Titles update every second
+// - Firework launches at the end
+// ============================================
+
+namespace tutorial05
+
+// ─── State ──────────────────────────────────────────────────────────────────
+
+struct TimerState {
+    running: int,
+    seconds_left: int
+}
+
+let timer: TimerState = {
+    running: 0,
+    seconds_left: 0
+}
+
+// ─── @load: runs once when the world loads ───────────────────────────────────
+
+@load
+fn on_load() {
+    scoreboard_add_objective("tut05_data", "dummy")
+    say("Countdown system ready! /trigger start_countdown")
+}
+
+// ─── @tick: runs every single game tick (20/sec) ────────────────────────────
+
+// This runs every tick but only does work if something is active.
+// Keep @tick functions lightweight — they run 20 times a second!
+@tick
+fn heartbeat() {
+    // We use a scoreboard flag to debounce: only tick once per 20 ticks
+    // (the @tick(rate=20) decorator below handles this more cleanly)
+}
+
+// ─── @tick(rate=20): runs every 20 ticks = once per second ──────────────────
+
+@tick(rate=20)
+fn every_second() {
+    if (timer.running == 0) {
+        return
+    }
+
+    timer.seconds_left = timer.seconds_left - 1
+
+    if (timer.seconds_left > 0) {
+        show_countdown(timer.seconds_left)
+    } else {
+        fire_at_zero()
+    }
+}
+
+fn show_countdown(sec: int) {
+    tell(@a, "Countdown: " + sec)
+    // Color changes as time runs out
+    if (sec <= 3) {
+        subtitle(@a, "Hurry!")
+        actionbar(@a, "⏱ " + sec + " seconds!")
+    } else {
+        subtitle(@a, "Get ready...")
+        actionbar(@a, "Countdown: " + sec)
+    }
+}
+
+fn fire_at_zero() {
+    timer.running = 0
+    timer.seconds_left = 0
+
+    title(@a, "GO!")
+    subtitle(@a, "Time is up!")
+    say("Countdown complete!")
+
+    // Summon firework
+    summon("minecraft:firework_rocket", 0, 65, 0)
+}
+
+// ─── @on_trigger: fires when a player uses /trigger ─────────────────────────
+
+// Players type:  /trigger start_countdown
+@on_trigger("start_countdown")
+fn start_countdown() {
+    if (timer.running == 1) {
+        tell(@s, "A countdown is already running!")
+        return
+    }
+
+    timer.running = 1
+    timer.seconds_left = 10
+
+    announce("Countdown started by a player!")
+    title(@a, "10")
+    subtitle(@a, "Countdown begins!")
+    title_times(@a, 5, 15, 5)
+}
+
+// Players type:  /trigger stop_countdown
+@on_trigger("stop_countdown")
+fn stop_countdown() {
+    if (timer.running == 0) {
+        tell(@s, "No countdown running.")
+        return
+    }
+
+    timer.running = 0
+    timer.seconds_left = 0
+    title(@a, "Stopped")
+    say("Countdown cancelled.")
+}
+
+// ─── @schedule: runs once after a delay ─────────────────────────────────────
+
+// Players type:  /trigger delayed_message
+// The message appears 5 seconds (100 ticks) later
+@on_trigger("delayed_message")
+fn queue_delayed() {
+    tell(@s, "Message will appear in 5 seconds...")
+    // Schedule the delivery 100 ticks (5 seconds) from now
+    delayed_deliver()
+}
+
+@schedule(100)
+fn delayed_deliver() {
+    say("This message was delayed by 5 seconds!")
+    title(@a, "Delayed!")
+}

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, "abs(-42) = " + neg)
+
+    // min / max
+    let lo: int = min(10, 20)           // 10
+    let hi: int = max(10, 20)           // 20
+    tell(@s, "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, "clamp(150, 0, 100) = " + clamped)
+
+    // isqrt — integer square root
+    let root: int = isqrt(144)          // 12
+    tell(@s, "isqrt(144) = " + root)
+
+    // sqrt_fixed — fixed-point sqrt (scale = 1000)
+    let sq2: int = sqrt_fixed(2000)     // ~1414 = sqrt(2) * 1000
+    tell(@s, "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, "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, "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, "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, "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, "Found: " + count + "x " + name)
+    give(@s, item, count)
+
+    if (bonus > 0) {
+        tell(@s, "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, "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, "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, "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("Blocks checked: " + scan.blocks_checked)
+    say("Special blocks found: " + scan.special_found)
+
+    title(@a, "Scan Done!")
+    let found: int = scan.special_found
+    subtitle(@a, "Special blocks found: " + found)
+
+    // Give a report item to all players
+    foreach (p in @a) {
+        give(p, "minecraft:paper", 1)
+        tell(p, "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, "No scan running. Last result: " + scan.special_found + " special blocks")
+        return
+    }
+
+    let pct: int = scan.blocks_checked * 100 / 10000
+    tell(@s, "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")
+}