redscript-mc 1.0.0

package/src/examples/README.md

@@ -0,0 +1,77 @@
+# Examples
+
+This folder contains small RedScript example programs that demonstrate common datapack patterns and the current language feature set.
+
+## `counter.rs`
+
+A minimal tick counter.
+
+Demonstrates:
+- `@tick`
+- `scoreboard_get()` and `scoreboard_set()`
+- integer math and `%`
+- `if`
+- `say()`
+
+## `shop.rs`
+
+A simple shop entry point that runs from `@on_trigger("shop_buy")` and reads a companion `shop_choice` scoreboard to decide what to give the player.
+
+Demonstrates:
+- `@on_trigger`
+- helper functions
+- nested `if` / `else`
+- `give()`
+- `tell()`
+- scoreboard-driven branching
+
+Note: the current trigger system fires when a trigger objective is set, but it does not pass the numeric trigger amount into the handler. This example uses `shop_choice` for the item selection value.
+
+## `arena.rs`
+
+A PvP arena tracker that checks the `kills` objective every 200 ticks, finds the highest score, and notifies the leader or tied leaders.
+
+Demonstrates:
+- periodic logic with `@tick`
+- `foreach (player in @a)`
+- per-player scoreboard reads
+- aggregation with local variables
+- `announce()`, `actionbar()`, `subtitle()`, and `title_times()`
+- `tell()` and `title()`
+
+## `world_manager.rs`
+
+A small world administration example that resets a lobby platform and locks in predictable world settings from a trigger handler.
+
+Demonstrates:
+- `BlockPos` tuple literals with `setblock()` and `fill()`
+- `weather()` and `time_set()`
+- `gamerule()`
+- `announce()` and `actionbar()`
+- `@on_trigger`
+
+## `turret.rs`
+
+An automated turret deployment example. A trigger spawns an invisible armor stand, tags it as a turret, stores a health value, and a tick loop kills nearby zombies around every deployed turret.
+
+Demonstrates:
+- `spawn_object()`
+- world object field assignment
+- entity tagging
+- `struct` literals and field reads
+- `@tick(rate=20)`
+- nested `foreach`
+- `at` blocks
+
+## `quiz.rs`
+
+A trigger-based quiz game. Players start with `quiz_start`, answer with `quiz_a`, `quiz_b`, or `quiz_c`, and keep score in scoreboards while receiving `tellraw`-style messages through `tell()`.
+
+Demonstrates:
+- multiple `@on_trigger` handlers
+- regular functions with parameters
+- scoreboard-backed state machines
+- branching by current question and answer choice
+- `title()` and `tell()`
+
+Note: `tell()` lowers to Minecraft `tellraw`, so these messages are rendered as JSON text components in the datapack output.

package/src/examples/SHOWCASE_GAME.md

@@ -0,0 +1,43 @@
+# Crystal Rush
+
+`showcase_game.rs` is a complete RedScript mini-game showcase built around a simple loop:
+
+1. Players join with `/trigger crystal_join`
+2. Anyone in the lobby can start a countdown with `/trigger crystal_start`
+3. During the round, players use `/trigger crystal_claim` near one of four crystal lanes
+4. `/trigger crystal_dash` spends the shared stdlib cooldown to lunge forward
+5. Zombies spawn in waves and touching them applies scoreboard-based damage
+6. First player to `15` score wins, then the arena resets
+
+## Mechanics
+
+- Four crystal pads exist at north, south, east, and west.
+- A player claims the crystal in the lane they are currently closest to.
+- Claiming a crystal removes the block, awards score, and starts its recharge cycle.
+- Every second the game respawns missing crystals and periodically spawns zombie pressure.
+- If a player's tracked health reaches `0`, they are teleported back to spawn and lose `1` score.
+
+## Feature Coverage
+
+- `const` declarations: scoring, timers, cooldown, and damage are all constant-driven.
+- `enum` types: `Phase` and `Lane` drive game flow and crystal logic.
+- Arrays: lane lists and respawn loops use `int[]`.
+- Structs: `GameState` and `PlayerState` snapshot scoreboard-backed state.
+- String interpolation: titles, actionbars, and announcements use `${...}`.
+- `match`: used for phase dispatch, lane lookup, lane labels, and lane crystal state.
+- Default parameters: `crystal_reward(base, streak = 0)`.
+- `foreach` over selectors: player counting and per-player round updates.
+- BlockPos with `~` and `^`: arena pad marking uses `(~0, 64, ~0)`, dash uses `(^0, ^0, ^3)`.
+- `@tick(rate=20)`: once-per-second game logic runs in `crystal_rush_second`.
+- Trigger decorator: this repo currently supports `@on_trigger("...")`, not `@on_advancement` / `@on_death`, so Crystal Rush uses trigger handlers for join/start/claim/dash.
+- Stdlib imports: `math.rs`, `player.rs`, and `cooldown.rs` are imported and exercised.
+- `execute/as/at` blocks: used for zombie contact damage and spawn-pad marking.
+- Scoreboard operations: all game state is stored in objectives like `score`, `crystals`, `health`, and `crystal`.
+- `fill` / `setblock`: arena build and crystal respawn both use block-editing builtins.
+- `title` / `subtitle` / `actionbar`: all phases and major player events surface feedback through UI.
+- Multiple functions calling each other: the game loop is split into snapshots, dispatch, arena setup, scoring, respawn, and reset helpers.
+
+## Notes
+
+- The imported stdlib cooldown helper is currently a single global slot on objective `rs`, so dash acts as a shared cooldown showcase rather than a per-player system.
+- The compiler surface today does not implement `@on_advancement` or `@on_death`; this example intentionally stays within the supported decorator set in the current codebase.

package/src/examples/arena.rs

@@ -0,0 +1,44 @@
+// PvP arena scoreboard tracker.
+// Reads the vanilla kills objective, announces the top score every 200 ticks,
+// and tells the current leader(s) directly.
+
+@tick
+fn arena_tick() {
+    let ticks: int = scoreboard_get("arena", #ticks);
+    ticks = ticks + 1;
+    scoreboard_set("arena", #ticks, ticks);
+
+    if (ticks % 200 == 0) {
+        announce_leaders();
+    }
+}
+
+fn announce_leaders() {
+    let top_kills: int = 0;
+
+    foreach (player in @a) {
+        let kills: int = scoreboard_get(player, #kills);
+        if (kills > top_kills) {
+            top_kills = kills;
+        }
+    }
+
+    if (top_kills > 0) {
+        announce("Arena update: leader check complete.");
+        title_times(@a, 10, 40, 10);
+        actionbar(@a, "Top kills updated");
+
+        foreach (player in @a) {
+            let kills: int = scoreboard_get(player, #kills);
+            if (kills == top_kills) {
+                tell(player, "You are leading the arena right now.");
+                title(player, "Arena Leader");
+                subtitle(player, "Hold the top score");
+                actionbar(player, "Stay alive to keep the lead");
+            }
+        }
+    } else {
+        announce("Arena update: no PvP kills yet.");
+        actionbar(@a, "No arena leader yet");
+    }
+}

package/src/examples/counter.rs

@@ -0,0 +1,12 @@
+// Tick counter that announces every 100 ticks.
+
+@tick
+fn counter_tick() {
+    let ticks: int = scoreboard_get("counter", #ticks);
+    ticks = ticks + 1;
+    scoreboard_set("counter", #ticks, ticks);
+
+    if (ticks % 100 == 0) {
+        say("Counter reached another 100 ticks");
+    }
+}

package/src/examples/pvp_arena.rs

@@ -0,0 +1,131 @@
+struct FighterState {
+    health: int,
+    eliminations: int,
+    alive: int
+}
+
+fn snapshot_fighter() -> FighterState {
+    let health: int = scoreboard_get(@s, #arena_health);
+    let eliminations: int = scoreboard_get(@s, #arena_elims);
+    let alive: int = scoreboard_get(@s, #arena_alive);
+    let state: FighterState = { health: health, eliminations: eliminations, alive: alive };
+    return state;
+}
+
+fn save_fighter(state: FighterState) {
+    scoreboard_set(@s, #arena_health, state.health);
+    scoreboard_set(@s, #arena_elims, state.eliminations);
+    scoreboard_set(@s, #arena_alive, state.alive);
+}
+
+fn count_team(tagName: string) -> int {
+    let total: int = 0;
+
+    if (tagName == "red") {
+        foreach (player in @a[tag=arena_red, tag=arena_alive]) {
+            total += 1;
+        }
+    } else {
+        foreach (player in @a[tag=arena_blue, tag=arena_alive]) {
+            total += 1;
+        }
+    }
+
+    return total;
+}
+
+fn check_winner() {
+    let red_alive: int = count_team("red");
+    let blue_alive: int = count_team("blue");
+
+    if (red_alive == 0) {
+        title(@a, "Blue Team Wins");
+        subtitle(@a, "Red squad has been eliminated");
+    } else {
+        if (blue_alive == 0) {
+            title(@a, "Red Team Wins");
+            subtitle(@a, "Blue squad has been eliminated");
+        }
+    }
+}
+
+fn knock_out_current_player() {
+    let state: FighterState = snapshot_fighter();
+    state.health = 0;
+    state.alive = 0;
+    save_fighter(state);
+    @s.tag("arena_out");
+    @s.untag("arena_alive");
+    title(@s, "Eliminated");
+    actionbar(@s, "Wait for the next arena reset");
+}
+
+fn award_elimination() {
+    let killer: FighterState = snapshot_fighter();
+    killer.eliminations = killer.eliminations + 1;
+    save_fighter(killer);
+    title(@s, "Elimination");
+    actionbar(@s, "Your elimination total is now ${killer.eliminations}");
+}
+
+fn check_milestones() {
+    let milestones: int[] = [1, 3, 5];
+    let kills: int = scoreboard_get(@s, #arena_elims);
+
+    foreach (milestone in milestones) {
+        if (kills == milestone) {
+            actionbar(@s, "Milestone reached: ${milestone} eliminations");
+        }
+    }
+}
+
+@tick
+fn arena_status_tick() {
+    let red_alive: int = count_team("red");
+    let blue_alive: int = count_team("blue");
+    actionbar(@a, "Arena status: Red ${red_alive} alive | Blue ${blue_alive} alive");
+    check_winner();
+}
+
+@on_trigger("arena_assign_red")
+fn arena_assign_red() {
+    @s.tag("arena_red");
+    @s.tag("arena_alive");
+    @s.untag("arena_blue");
+    @s.untag("arena_out");
+    scoreboard_set(@s, #arena_health, 20);
+    scoreboard_set(@s, #arena_elims, 0);
+    scoreboard_set(@s, #arena_alive, 1);
+    title(@s, "Red Team");
+}
+
+@on_trigger("arena_assign_blue")
+fn arena_assign_blue() {
+    @s.tag("arena_blue");
+    @s.tag("arena_alive");
+    @s.untag("arena_red");
+    @s.untag("arena_out");
+    scoreboard_set(@s, #arena_health, 20);
+    scoreboard_set(@s, #arena_elims, 0);
+    scoreboard_set(@s, #arena_alive, 1);
+    title(@s, "Blue Team");
+}
+
+@on_trigger("arena_hit")
+fn arena_hit() {
+    let state: FighterState = snapshot_fighter();
+    state.health = state.health - 5;
+    save_fighter(state);
+
+    if (state.health <= 0) {
+        knock_out_current_player();
+    } else {
+        subtitle(@s, "Health now ${state.health}");
+    }
+}
+
+@on_trigger("arena_elim")
+fn arena_elim() {
+    award_elimination();
+    check_milestones();
+}

package/src/examples/quiz.rs

@@ -0,0 +1,90 @@
+// Quiz game with trigger-based answers.
+// Use /trigger quiz_start to begin, then /trigger quiz_a, /trigger quiz_b, or /trigger quiz_c.
+
+@on_trigger("quiz_start")
+fn start_quiz() {
+    scoreboard_set(@s, #quiz_score, 0);
+    scoreboard_set(@s, #quiz_question, 1);
+    ask_question();
+}
+
+fn ask_question() {
+    let question: int = scoreboard_get(@s, #quiz_question);
+
+    if (question == 1) {
+        tell(@s, "Question 1: Which block drops diamonds?");
+        tell(@s, "A) Diamond ore  B) Stone  C) Oak log");
+    } else {
+        if (question == 2) {
+            tell(@s, "Question 2: Which food restores more hunger?");
+            tell(@s, "A) Bread  B) Steak  C) Beetroot");
+        } else {
+            if (question == 3) {
+                tell(@s, "Question 3: Which mob explodes?");
+                tell(@s, "A) Cow  B) Creeper  C) Villager");
+            } else {
+                finish_quiz();
+            }
+        }
+    }
+}
+
+fn handle_answer(choice: int) {
+    let question: int = scoreboard_get(@s, #quiz_question);
+    let score: int = scoreboard_get(@s, #quiz_score);
+
+    if (question == 1) {
+        if (choice == 1) {
+            score = score + 1;
+            tell(@s, "Correct.");
+        } else {
+            tell(@s, "Wrong. The answer was A.");
+        }
+    } else {
+        if (question == 2) {
+            if (choice == 2) {
+                score = score + 1;
+                tell(@s, "Correct.");
+            } else {
+                tell(@s, "Wrong. The answer was B.");
+            }
+        } else {
+            if (question == 3) {
+                if (choice == 2) {
+                    score = score + 1;
+                    tell(@s, "Correct.");
+                } else {
+                    tell(@s, "Wrong. The answer was B.");
+                }
+            }
+        }
+    }
+
+    scoreboard_set(@s, #quiz_score, score);
+    question = question + 1;
+    scoreboard_set(@s, #quiz_question, question);
+    ask_question();
+}
+
+fn finish_quiz() {
+    let score: int = scoreboard_get(@s, #quiz_score);
+    title(@s, "Quiz Complete");
+    tell(@s, "Your final quiz score is recorded in quiz_score.");
+    scoreboard_set(@s, #quiz_question, 0);
+    scoreboard_set(@s, #quiz_score, score);
+}
+
+@on_trigger("quiz_a")
+fn answer_a() {
+    handle_answer(1);
+}
+
+@on_trigger("quiz_b")
+fn answer_b() {
+    handle_answer(2);
+}
+
+@on_trigger("quiz_c")
+fn answer_c() {
+    handle_answer(3);
+}

package/src/examples/rpg.rs

@@ -0,0 +1,13 @@
+import "../stdlib/math.rs"
+import "../stdlib/combat.rs"
+
+fn attack(enemy: string, base: int, bonus: int) {
+    let raw_damage: int = weapon_damage(base, bonus);
+    let damage: int = clamp(raw_damage, 1, 20);
+    apply_damage(enemy, damage);
+}
+
+@tick
+fn battle_tick() {
+    attack("goblin", 4, 2);
+}

package/src/examples/shop.rs

@@ -0,0 +1,30 @@
+// Trigger-driven shop.
+// Players set shop_choice, then run /trigger shop_buy.
+
+fn complete_purchase() {
+    let choice: int = scoreboard_get(@s, #shop_choice);
+
+    if (choice == 1) {
+        give(@s, "minecraft:bread", 1);
+        tell(@s, "You bought bread.");
+    } else {
+        if (choice == 2) {
+            give(@s, "minecraft:steak", 1);
+            tell(@s, "You bought steak.");
+        } else {
+            if (choice == 3) {
+                give(@s, "minecraft:diamond", 1);
+                tell(@s, "You bought a diamond.");
+            } else {
+                tell(@s, "Invalid shop_choice. Use 1, 2, or 3.");
+            }
+        }
+    }
+
+    scoreboard_set(@s, #shop_choice, 0);
+}
+
+@on_trigger("shop_buy")
+fn handle_shop_trigger() {
+    complete_purchase();
+}