redscript-mc 2.5.0 → 2.6.2

package/src/examples/tutorial_01_hello.mcrs

@@ -0,0 +1,63 @@
+// ============================================
+// Tutorial 01: Hello Datapack
+// ============================================
+// A "hello world" datapack that announces server startup,
+// welcomes players who trigger the welcome kit, and gives
+// them starter items on demand.
+// ============================================
+
+// Declare a namespace for this datapack
+namespace tutorial01
+
+// ─── Scoreboard setup ───────────────────────────────────────────────────────
+
+@load
+fn setup() {
+    // Create a scoreboard objective so we can track anything we want later
+    scoreboard_add_objective("tut01_data", "dummy")
+
+    // This runs once when the world loads
+    say("Hello! Tutorial 01 datapack loaded.")
+    say("Type /trigger welcome_kit to get started!")
+}
+
+// ─── Tick function ───────────────────────────────────────────────────────────
+
+@tick
+fn every_tick() {
+    // This runs every game tick (20 times per second)
+    // Keep it lightweight — just checking a counter here
+    let active: int = scoreboard_get("#active", "tut01_data")
+    if (active == 1) {
+        // The datapack is running — nothing fancy yet
+    }
+}
+
+// ─── Welcome kit trigger ─────────────────────────────────────────────────────
+
+// Players run:  /trigger welcome_kit
+// This fires once per activation per player
+@on_trigger("welcome_kit")
+fn give_welcome_kit() {
+    // tell() sends a private message only to the triggering player (@s)
+    tell(@s, "Welcome to Tutorial 01!")
+    tell(@s, "Here is your starter kit:")
+
+    // give() hands items directly to the triggering player
+    give(@s, "minecraft:bread", 16)
+    give(@s, "minecraft:wooden_sword", 1)
+    give(@s, "minecraft:torch", 8)
+
+    // Announce to everyone that someone got the kit
+    announce("A player claimed the welcome kit!")
+}
+
+// ─── Bonus: greeting trigger ─────────────────────────────────────────────────
+
+// Players run:  /trigger greet
+@on_trigger("greet")
+fn greet_player() {
+    tell(@s, "Hello there, adventurer!")
+    title(@s, "Welcome!")
+    subtitle(@s, "Enjoy the server")
+}

package/src/examples/tutorial_02_variables.mcrs

@@ -0,0 +1,157 @@
+// ============================================
+// Tutorial 02: Variables & Control Flow
+// ============================================
+// A vote counter that lets players vote yes or no,
+// tracks results, and announces the winner.
+// ============================================
+
+namespace tutorial02
+
+// ─── Scoreboard setup ───────────────────────────────────────────────────────
+
+@load
+fn setup() {
+    scoreboard_add_objective("votes_yes", "dummy")
+    scoreboard_add_objective("votes_no", "dummy")
+    scoreboard_add_objective("vote_cast", "dummy")
+    say("Vote system ready! /trigger vote_yes  or  /trigger vote_no")
+}
+
+// ─── Variable types demo ─────────────────────────────────────────────────────
+
+fn demo_types() {
+    // int: whole numbers (stored in scoreboard)
+    let count: int = 42
+    let negative: int = -7
+
+    // bool: true or false
+    let is_active: bool = true
+    let has_voted: bool = false
+
+    // fixed: decimal numbers × 10000 (1.5 is stored as 15000)
+    // Useful for percentages, fractions, sub-block positions
+    let percentage: fixed = 7500 as fixed   // represents 0.75 (75%)
+    let half: fixed = 5000 as fixed         // represents 0.5
+
+    // string: text labels
+    let winner: string = "yes"
+
+    // Use the values so the compiler doesn't complain
+    if (is_active) {
+        tell(@a, "Demo types loaded")
+    }
+}
+
+// ─── Vote yes ───────────────────────────────────────────────────────────────
+
+@on_trigger("vote_yes")
+fn cast_yes() {
+    // Check if player already voted
+    let already_voted: int = scoreboard_get(@s, "vote_cast")
+    if (already_voted == 1) {
+        tell(@s, "You already voted!")
+        return
+    }
+
+    // Record vote
+    scoreboard_set(@s, "vote_cast", 1)
+    let yes_count: int = scoreboard_get("#total", "votes_yes")
+    yes_count = yes_count + 1
+    scoreboard_set("#total", "votes_yes", yes_count)
+
+    tell(@s, "You voted YES!")
+    announce("A player voted YES")
+}
+
+// ─── Vote no ────────────────────────────────────────────────────────────────
+
+@on_trigger("vote_no")
+fn cast_no() {
+    let already_voted: int = scoreboard_get(@s, "vote_cast")
+    if (already_voted == 1) {
+        tell(@s, "You already voted!")
+        return
+    }
+
+    scoreboard_set(@s, "vote_cast", 1)
+    let no_count: int = scoreboard_get("#total", "votes_no")
+    no_count = no_count + 1
+    scoreboard_set("#total", "votes_no", no_count)
+
+    tell(@s, "You voted NO!")
+    announce("A player voted NO")
+}
+
+// ─── Tally results ──────────────────────────────────────────────────────────
+
+@on_trigger("tally_votes")
+fn tally() {
+    let yes_count: int = scoreboard_get("#total", "votes_yes")
+    let no_count: int = scoreboard_get("#total", "votes_no")
+    let total: int = yes_count + no_count
+
+    say("=== Vote Results ===")
+    announce(f"YES: {yes_count}")
+    announce(f"NO:  {no_count}")
+
+    if (total == 0) {
+        say("No votes cast yet!")
+        return
+    }
+
+    // Determine winner using if/else
+    if (yes_count > no_count) {
+        title(@a, "YES wins!")
+        say("The YES vote wins!")
+    } else {
+        if (no_count > yes_count) {
+            title(@a, "NO wins!")
+            say("The NO vote wins!")
+        } else {
+            title(@a, "It's a tie!")
+            say("It's a perfect tie!")
+        }
+    }
+
+    // Show percentage with fixed-point arithmetic
+    // Multiply by 10000 first to keep precision, then divide by total
+    let yes_pct: fixed = (yes_count * 10000 / total) as fixed
+    announce(f"YES percentage (x10000): {yes_pct}")
+}
+
+// ─── While loop example ──────────────────────────────────────────────────────
+
+@on_trigger("count_down")
+fn count_down() {
+    let i: int = 5
+    while (i > 0) {
+        tell(@s, f"Countdown: {i}")
+        i = i - 1
+    }
+    tell(@s, "Done!")
+}
+
+// ─── For loop example ────────────────────────────────────────────────────────
+
+@on_trigger("for_demo")
+fn for_demo() {
+    // for loop: start, end (exclusive), step defaults to 1
+    let i: int = 0
+    while (i < 5) {
+        tell(@s, f"Step {i}")
+        i = i + 1
+    }
+}
+
+// ─── Reset votes ────────────────────────────────────────────────────────────
+
+@on_trigger("reset_votes")
+fn reset_votes() {
+    scoreboard_set("#total", "votes_yes", 0)
+    scoreboard_set("#total", "votes_no", 0)
+    // Reset all players' vote_cast flags
+    foreach (p in @a) {
+        scoreboard_set(p, "vote_cast", 0)
+    }
+    say("Votes reset! Everyone can vote again.")
+}

package/src/examples/tutorial_03_functions_structs.mcrs

@@ -0,0 +1,162 @@
+// ============================================
+// Tutorial 03: Functions & Structs
+// ============================================
+// A boss health tracking system.
+// Demonstrates functions with parameters/return values
+// and structs for organizing related data.
+// ============================================
+
+namespace tutorial03
+
+// ─── Struct definition ───────────────────────────────────────────────────────
+
+// A struct groups related data into one named type
+struct BossState {
+    max_hp: int,
+    current_hp: int,
+    phase: int,        // 1=normal, 2=enraged (below 50%), 3=dying (below 20%)
+    alive: int         // 0=dead, 1=alive
+}
+
+// Global boss instance
+let boss: BossState = {
+    max_hp: 200,
+    current_hp: 200,
+    phase: 1,
+    alive: 0
+}
+
+// ─── Setup ──────────────────────────────────────────────────────────────────
+
+@load
+fn setup() {
+    scoreboard_add_objective("boss_hp", "dummy")
+    scoreboard_add_objective("boss_phase", "dummy")
+    say("Boss system loaded! /trigger spawn_boss to begin")
+}
+
+// ─── Functions ──────────────────────────────────────────────────────────────
+
+// A pure function that computes a value and returns it
+fn hp_percentage(current: int, max: int) -> int {
+    if (max <= 0) {
+        return 0
+    }
+    return current * 100 / max
+}
+
+// A function that checks and updates boss phase
+// Takes the boss state by value (RedScript structs are value types)
+fn get_phase(current_hp: int, max_hp: int) -> int {
+    let pct: int = hp_percentage(current_hp, max_hp)
+    if (pct <= 20) {
+        return 3
+    }
+    if (pct <= 50) {
+        return 2
+    }
+    return 1
+}
+
+fn describe_phase(phase: int) -> string {
+    if (phase == 1) {
+        return "Normal"
+    }
+    if (phase == 2) {
+        return "Enraged"
+    }
+    return "Dying"
+}
+
+// ─── Spawn boss ─────────────────────────────────────────────────────────────
+
+@on_trigger("spawn_boss")
+fn spawn_boss() {
+    boss.max_hp = 200
+    boss.current_hp = 200
+    boss.phase = 1
+    boss.alive = 1
+
+    scoreboard_set("#boss", "boss_hp", boss.current_hp)
+    scoreboard_set("#boss", "boss_phase", boss.phase)
+
+    summon("minecraft:wither_skeleton", 0, 64, 0)
+    say("The Boss has appeared! HP: 200")
+    title(@a, "BOSS FIGHT")
+    subtitle(@a, "Phase 1: Normal")
+}
+
+// ─── Damage boss ────────────────────────────────────────────────────────────
+
+@on_trigger("damage_boss")
+fn damage_boss() {
+    if (boss.alive == 0) {
+        tell(@s, "No boss is active!")
+        return
+    }
+
+    // Deal 15 damage
+    let damage: int = 15
+    boss.current_hp = boss.current_hp - damage
+
+    // Clamp to zero
+    if (boss.current_hp < 0) {
+        boss.current_hp = 0
+    }
+
+    // Update scoreboard
+    scoreboard_set("#boss", "boss_hp", boss.current_hp)
+
+    // Check for phase transition
+    let new_phase: int = get_phase(boss.current_hp, boss.max_hp)
+    if (new_phase != boss.phase) {
+        boss.phase = new_phase
+        scoreboard_set("#boss", "boss_phase", boss.phase)
+        let phase_name: string = describe_phase(boss.phase)
+        announce(f"Boss entered phase {boss.phase}: {phase_name}!")
+        title(@a, f"Phase {boss.phase}")
+    }
+
+    let pct: int = hp_percentage(boss.current_hp, boss.max_hp)
+    announce(f"Boss HP: {boss.current_hp}/{boss.max_hp} ({pct}%)")
+
+    // Check for death
+    if (boss.current_hp <= 0) {
+        kill_boss()
+    }
+}
+
+// ─── Kill boss ───────────────────────────────────────────────────────────────
+
+fn kill_boss() {
+    boss.alive = 0
+    boss.phase = 0
+
+    kill(@e[type=minecraft:wither_skeleton])
+    title(@a, "Boss Defeated!")
+    subtitle(@a, "Well done, heroes!")
+    say("The Boss has been slain!")
+
+    // Give reward to all players
+    foreach (p in @a) {
+        give(p, "minecraft:diamond", 3)
+        tell(p, "You earned 3 diamonds for defeating the boss!")
+    }
+}
+
+// ─── Status check ────────────────────────────────────────────────────────────
+
+@on_trigger("boss_status")
+fn check_status() {
+    if (boss.alive == 0) {
+        tell(@s, "No boss is currently active.")
+        return
+    }
+
+    let pct: int = hp_percentage(boss.current_hp, boss.max_hp)
+    let phase_name: string = describe_phase(boss.phase)
+    tell(@s, "=== Boss Status ===")
+    tell(@s, f"HP: {boss.current_hp}/{boss.max_hp}")
+    tell(@s, f"Health: {pct}%")
+    tell(@s, f"Phase: {phase_name}")
+}

package/src/examples/tutorial_04_selectors.mcrs

@@ -0,0 +1,139 @@
+// ============================================
+// Tutorial 04: Selectors & Execute Context
+// ============================================
+// A proximity detector that finds players near a
+// zone, grants them glowing + speed, and alerts them.
+// ============================================
+
+namespace tutorial04
+
+import effects::*
+
+// ─── Setup ──────────────────────────────────────────────────────────────────
+
+@load
+fn setup() {
+    scoreboard_add_objective("in_zone", "dummy")
+    say("Proximity detector loaded! Zone is around 0,64,0 radius 10.")
+}
+
+// ─── Zone check runs every second (rate=20 ticks) ───────────────────────────
+
+@tick(rate=20)
+fn check_zone() {
+    // @a[distance=..10] selects all players within 10 blocks of the executor
+    // The executor position is the world origin (0,0,0) here
+    // In a real setup you'd use execute at (x,y,z) run { ... }
+
+    // Mark players currently in zone
+    foreach (p in @a[distance=..10]) {
+        let was_in_zone: int = scoreboard_get(p, "in_zone")
+        if (was_in_zone == 0) {
+            // Player just entered the zone
+            scoreboard_set(p, "in_zone", 1)
+            on_player_enter(p)
+        }
+        // Refresh effects while in zone
+        refresh_zone_effects(p)
+    }
+
+    // Mark players who left the zone
+    foreach (p in @a[distance=10..]) {
+        let was_in_zone: int = scoreboard_get(p, "in_zone")
+        if (was_in_zone == 1) {
+            scoreboard_set(p, "in_zone", 0)
+            on_player_leave(p)
+        }
+    }
+}
+
+// ─── Zone entry handler ──────────────────────────────────────────────────────
+
+fn on_player_enter(p: selector) {
+    tell(p, "You entered the magic zone!")
+    title(p, "Zone Entered")
+    subtitle(p, "You have the blessing")
+}
+
+fn on_player_leave(p: selector) {
+    tell(p, "You left the magic zone.")
+    // Remove effects when leaving
+    effect_clear(p)
+}
+
+fn refresh_zone_effects(p: selector) {
+    // Give short-duration effects (refreshed every second)
+    speed(p, 2, 1)         // speed II for 2 seconds
+    glow(p, 2)             // glowing for 2 seconds
+}
+
+// ─── Selector filter demos ───────────────────────────────────────────────────
+
+@on_trigger("demo_selectors")
+fn demo_selectors() {
+    // @s  — the entity running this function (the trigger activator)
+    tell(@s, "You are @s")
+
+    // @p  — nearest player to the executor
+    // tell(@p, "Hello, nearest player!")
+
+    // @a  — all players
+    // tell(@a, "Hello everyone!")
+
+    // @e  — all entities
+    // @e[type=minecraft:zombie]  — only zombies
+    // @e[tag=boss]               — only entities with the "boss" tag
+
+    // Count players in zone using selector
+    let in_zone_count: int = 0
+    foreach (p in @a[distance=..10]) {
+        in_zone_count = in_zone_count + 1
+    }
+    tell(@s, f"Players in zone: {in_zone_count}")
+}
+
+// ─── Tag-based selection ─────────────────────────────────────────────────────
+
+@on_trigger("mark_vip")
+fn mark_vip() {
+    // Add a tag to the triggering player
+    tag_add(@s, "vip")
+    tell(@s, "You are now VIP!")
+
+    // Now we can select only VIPs
+    foreach (vip in @a[tag=vip]) {
+        tell(vip, "VIP check: you have VIP status!")
+    }
+}
+
+@on_trigger("give_vip_buff")
+fn give_vip_buff() {
+    // Give buff only to tagged VIP players
+    foreach (vip in @a[tag=vip]) {
+        regen(vip, 30, 1)
+        tell(vip, "VIP buff granted!")
+    }
+    // Non-VIPs get a message too
+    foreach (p in @a) {
+        let is_vip: int = 0
+        // Check tag using selector filter
+        foreach (check in @a[tag=vip]) {
+            // If we're checking the same player
+        }
+    }
+}
+
+// ─── foreach with as/at context ──────────────────────────────────────────────
+
+@on_trigger("sweep_entities")
+fn sweep_entities() {
+    // foreach runs the body "as" each selected entity
+    // meaning @s inside the body refers to each entity
+    foreach (zombie in @e[type=minecraft:zombie, distance=..20]) {
+        // @s here is each zombie
+        tell(@s, "Found a zombie!")
+        // Tag it for later use
+        tag_add(zombie, "detected")
+    }
+    announce("Entity sweep complete!")
+}

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, f"Countdown: {sec}")
+    // Color changes as time runs out
+    if (sec <= 3) {
+        subtitle(@a, "Hurry!")
+        actionbar(@a, f"⏱ {sec} seconds!")
+    } else {
+        subtitle(@a, "Get ready...")
+        actionbar(@a, f"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!")
+}