redscript-mc 1.0.0

package/src/stdlib/README.md

@@ -0,0 +1,156 @@
+# RedScript Stdlib
+
+This folder contains source-only utility modules for RedScript projects. There is
+no import system yet, so stdlib usage is intentionally simple:
+
+1. Copy the functions you need into your project file.
+2. Compile a stdlib file on its own to inspect the generated `.mcfunction` output.
+3. Recreate the same pattern with `raw("function namespace:name")` if you prefer
+   to wire precompiled datapack functions manually.
+
+## Modules
+
+### `math.rs`
+
+Integer helpers:
+
+- `abs(x: int) -> int`
+- `min(a: int, b: int) -> int`
+- `max(a: int, b: int) -> int`
+- `clamp(x: int, lo: int, hi: int) -> int`
+- `sign(x: int) -> int`
+
+Example:
+
+```rs
+let offset: int = abs(delta);
+let limited: int = clamp(offset, 0, 20);
+```
+
+### `player.rs`
+
+Nearest-player helpers:
+
+- `heal(amount: int)` adds to the nearest player's `health` scoreboard value
+- `damage(amount: int)` subtracts from the nearest player's `health` scoreboard
+- `is_op() -> int` returns `1` when the nearest player has the `op` tag
+
+Example:
+
+```rs
+if (is_op() == 1) {
+    heal(4);
+} else {
+    damage(2);
+}
+```
+
+### `strings.rs`
+
+String helpers:
+
+- `str_len(s: string) -> int`
+
+Important limitation:
+
+RedScript still does not support general runtime string manipulation. Today the
+compiler only lowers `str_len(...)` cleanly when the input is a string literal,
+a `const` string, or a string variable initialized from a literal-backed value.
+That path works by storing the string in `storage rs:strings` and reading its
+character count with `data get storage`.
+
+Example:
+
+```rs
+let name: string = "Player";
+let n: int = str_len(name);
+tell(@s, "${n}");
+```
+
+### `mobs.rs`
+
+Vanilla Java Edition entity type constants for selectors, summon helpers, and
+command wrappers. The file groups hostile, passive, neutral, boss, and misc
+entity IDs so you can copy stable names instead of repeating raw strings.
+
+Example:
+
+```rs
+summon(ALLAY, "~", "~", "~");
+summon(ZOMBIE, "~", "~", "~");
+```
+```
+
+### `timer.rs`
+
+Countdown helpers plus a `Timer` struct shape:
+
+- `struct Timer { ticks: int, active: int }`
+- `timer_start(name: string, duration: int)`
+- `timer_tick(name: string) -> int`
+- `timer_done(name: string) -> int`
+
+Important limitation:
+
+Current RedScript lowering does not preserve string arguments when they are passed
+into user-defined functions. Because of that, `timer.rs` is implemented as a
+single-slot template backed by `timer_ticks` and `timer_active` fake players on
+the `rs` objective. Keep one copy per named timer, or replace those fake-player
+names with your own concrete identifiers.
+
+Example:
+
+```rs
+timer_start("wave", 200);
+let remaining: int = timer_tick("wave");
+if (timer_done("wave") == 1) {
+    say("Next wave.");
+}
+```
+
+### `cooldown.rs`
+
+Cooldown helpers:
+
+- `cooldown_start(name: string, ticks: int)`
+- `cooldown_ready(name: string) -> int`
+- `cooldown_tick(name: string)`
+
+This file has the same single-slot limitation as `timer.rs`. Copy it and rename
+the scoreboard fake players if you need multiple independent cooldowns.
+
+Example:
+
+```rs
+if (cooldown_ready("dash") == 1) {
+    cooldown_start("dash", 40);
+}
+cooldown_tick("dash");
+```
+
+## Incorporation Patterns
+
+### Copy into your project
+
+This is the simplest path today. Paste the helper functions above your gameplay
+functions and compile one `.rs` file.
+
+### Compile separately
+
+You can inspect or ship a stdlib datapack directly:
+
+```bash
+npx ts-node src/cli.ts compile src/stdlib/math.rs -o dist/stdlib-math
+```
+
+### Call precompiled helpers with `raw()`
+
+If you compile helper files into their own namespace, you can call them from raw
+Minecraft commands:
+
+```rs
+raw("function stdlib_math:abs");
+```
+
+That pattern is most useful for command wrappers or tick/load entrypoints where
+the datapack interface is already fixed.

package/src/stdlib/combat.rs

@@ -0,0 +1,20 @@
+// Combat helpers for simple RPG-style datapacks.
+
+fn weapon_damage(base: int, bonus: int) -> int {
+    return base + bonus;
+}
+
+fn enemy_health(name: string) -> int {
+    return scoreboard_get(name, #health);
+}
+
+fn apply_damage(name: string, amount: int) {
+    let health: int = enemy_health(name);
+    let next: int = health - amount;
+
+    if (next < 0) {
+        scoreboard_set(name, #health, 0);
+    } else {
+        scoreboard_set(name, #health, next);
+    }
+}

package/src/stdlib/cooldown.rs

@@ -0,0 +1,45 @@
+// Cooldown helpers.
+//
+// Like timer.rs, the `name` parameter is reserved for a future compiler/runtime
+// that can route string literals through user-defined calls. Today this file
+// manages one cooldown slot on the `rs` objective.
+
+fn cooldown_start(name: string, ticks: int) {
+    scoreboard_set("cooldown_ticks", #rs, ticks);
+    scoreboard_set("cooldown_active", #rs, 1);
+}
+
+fn cooldown_ready(name: string) -> int {
+    let active: int = scoreboard_get("cooldown_active", #rs);
+    let ticks_left: int = scoreboard_get("cooldown_ticks", #rs);
+
+    if (active == 0) {
+        return 1;
+    }
+
+    if (ticks_left <= 0) {
+        return 1;
+    }
+
+    return 0;
+}
+
+fn cooldown_tick(name: string) {
+    let active: int = scoreboard_get("cooldown_active", #rs);
+    let ticks_left: int = scoreboard_get("cooldown_ticks", #rs);
+
+    if (active == 0) {
+        return;
+    }
+
+    if (ticks_left > 0) {
+        let next: int = ticks_left - 1;
+        scoreboard_set("cooldown_ticks", #rs, next);
+
+        if (next == 0) {
+            scoreboard_set("cooldown_active", #rs, 0);
+        }
+    } else {
+        scoreboard_set("cooldown_active", #rs, 0);
+    }
+}

package/src/stdlib/math.rs

@@ -0,0 +1,49 @@
+// Integer math helpers for RedScript datapacks.
+
+fn abs(x: int) -> int {
+    if (x < 0) {
+        return -x;
+    } else {
+        return x;
+    }
+}
+
+fn min(a: int, b: int) -> int {
+    if (a < b) {
+        return a;
+    } else {
+        return b;
+    }
+}
+
+fn max(a: int, b: int) -> int {
+    if (a > b) {
+        return a;
+    } else {
+        return b;
+    }
+}
+
+fn clamp(x: int, lo: int, hi: int) -> int {
+    if (x < lo) {
+        return lo;
+    } else {
+        if (x > hi) {
+            return hi;
+        } else {
+            return x;
+        }
+    }
+}
+
+fn sign(x: int) -> int {
+    if (x > 0) {
+        return 1;
+    } else {
+        if (x < 0) {
+            return -1;
+        } else {
+            return 0;
+        }
+    }
+}

package/src/stdlib/mobs.rs

@@ -0,0 +1,99 @@
+// Vanilla Minecraft Java Edition entity type constants.
+// Copy the names you need into your own project until RedScript gets imports.
+
+// Hostile mobs
+const ZOMBIE: string = "minecraft:zombie"
+const SKELETON: string = "minecraft:skeleton"
+const CREEPER: string = "minecraft:creeper"
+const SPIDER: string = "minecraft:spider"
+const CAVE_SPIDER: string = "minecraft:cave_spider"
+const ENDERMAN: string = "minecraft:enderman"
+const WITCH: string = "minecraft:witch"
+const PHANTOM: string = "minecraft:phantom"
+const DROWNED: string = "minecraft:drowned"
+const HUSK: string = "minecraft:husk"
+const STRAY: string = "minecraft:stray"
+const WARDEN: string = "minecraft:warden"
+const PILLAGER: string = "minecraft:pillager"
+const RAVAGER: string = "minecraft:ravager"
+const VINDICATOR: string = "minecraft:vindicator"
+const EVOKER: string = "minecraft:evoker"
+const VEXE: string = "minecraft:vex"
+const ZOMBIE_VILLAGER: string = "minecraft:zombie_villager"
+const BLAZE: string = "minecraft:blaze"
+const GHAST: string = "minecraft:ghast"
+const MAGMA_CUBE: string = "minecraft:magma_cube"
+const SLIME: string = "minecraft:slime"
+const PIGLIN_BRUTE: string = "minecraft:piglin_brute"
+const HOGLIN: string = "minecraft:hoglin"
+const ZOGLIN: string = "minecraft:zoglin"
+const ENDERMITE: string = "minecraft:endermite"
+const SILVERFISH: string = "minecraft:silverfish"
+const SHULKER: string = "minecraft:shulker"
+const GUARDIAN: string = "minecraft:guardian"
+const ELDER_GUARDIAN: string = "minecraft:elder_guardian"
+const BOGGED: string = "minecraft:bogged"
+const BREEZE: string = "minecraft:breeze"
+
+// Passive mobs
+const PIG: string = "minecraft:pig"
+const COW: string = "minecraft:cow"
+const SHEEP: string = "minecraft:sheep"
+const CHICKEN: string = "minecraft:chicken"
+const HORSE: string = "minecraft:horse"
+const DONKEY: string = "minecraft:donkey"
+const MULE: string = "minecraft:mule"
+const RABBIT: string = "minecraft:rabbit"
+const COD: string = "minecraft:cod"
+const SALMON: string = "minecraft:salmon"
+const TROPICAL_FISH: string = "minecraft:tropical_fish"
+const PUFFERFISH: string = "minecraft:pufferfish"
+const SQUID: string = "minecraft:squid"
+const GLOW_SQUID: string = "minecraft:glow_squid"
+const BAT: string = "minecraft:bat"
+const VILLAGER: string = "minecraft:villager"
+const WANDERING_TRADER: string = "minecraft:wandering_trader"
+const SNOW_GOLEM: string = "minecraft:snow_golem"
+const STRIDER: string = "minecraft:strider"
+const AXOLOTL: string = "minecraft:axolotl"
+const FROG: string = "minecraft:frog"
+const TADPOLE: string = "minecraft:tadpole"
+const ALLAY: string = "minecraft:allay"
+const SNIFFER: string = "minecraft:sniffer"
+const ARMADILLO: string = "minecraft:armadillo"
+const TURTLE: string = "minecraft:turtle"
+
+// Neutral mobs
+const WOLF: string = "minecraft:wolf"
+const BEE: string = "minecraft:bee"
+const POLAR_BEAR: string = "minecraft:polar_bear"
+const DOLPHIN: string = "minecraft:dolphin"
+const IRON_GOLEM: string = "minecraft:iron_golem"
+const PIGLIN: string = "minecraft:piglin"
+const ZOMBIFIED_PIGLIN: string = "minecraft:zombified_piglin"
+const PANDA: string = "minecraft:panda"
+const LLAMA: string = "minecraft:llama"
+const TRADER_LLAMA: string = "minecraft:trader_llama"
+const CAT: string = "minecraft:cat"
+const OCELOT: string = "minecraft:ocelot"
+const FOX: string = "minecraft:fox"
+const GOAT: string = "minecraft:goat"
+const CAMEL: string = "minecraft:camel"
+
+// Bosses
+const ENDER_DRAGON: string = "minecraft:ender_dragon"
+const WITHER: string = "minecraft:wither"
+
+// Special / misc
+const ARMOR_STAND: string = "minecraft:armor_stand"
+const ITEM_FRAME: string = "minecraft:item_frame"
+const GLOW_ITEM_FRAME: string = "minecraft:glow_item_frame"
+const PAINTING: string = "minecraft:painting"
+const BOAT: string = "minecraft:boat"
+const MINECART: string = "minecraft:minecart"
+const TNT: string = "minecraft:tnt"
+const FALLING_BLOCK: string = "minecraft:falling_block"
+const ITEM: string = "minecraft:item"
+const XP_ORB: string = "minecraft:experience_orb"
+const FIREBALL: string = "minecraft:fireball"
+const PLAYER: string = "minecraft:player"

package/src/stdlib/player.rs

@@ -0,0 +1,29 @@
+// Player helpers built on scoreboard/tag patterns.
+// These helpers target the nearest player via @p.
+
+fn heal(amount: int) {
+    let health: int = scoreboard_get(@p, #health);
+    let next: int = health + amount;
+    scoreboard_set(@p, #health, next);
+}
+
+fn damage(amount: int) {
+    let health: int = scoreboard_get(@p, #health);
+    let next: int = health - amount;
+
+    if (next < 0) {
+        scoreboard_set(@p, #health, 0);
+    } else {
+        scoreboard_set(@p, #health, next);
+    }
+}
+
+fn is_op() -> int {
+    let result: int = 0;
+
+    execute if entity @p[tag=op] run {
+        result = 1;
+    }
+
+    return result;
+}

package/src/stdlib/strings.rs

@@ -0,0 +1,7 @@
+// String helpers for RedScript datapacks.
+// Runtime string manipulation is still limited; `str_len` is compiler-assisted
+// and lowers to `data get storage rs:strings ...` for literal-backed strings.
+
+fn str_len(s: string) -> int {
+    return 0;
+}

package/src/stdlib/timer.rs

@@ -0,0 +1,51 @@
+// Countdown timer helpers.
+//
+// The current compiler does not propagate string literals through user-defined
+// function calls yet, so the `name` parameter is a forward-compatible placeholder.
+// This module manages one timer slot backed by fake players on the `rs` objective.
+
+struct Timer {
+    ticks: int,
+    active: int
+}
+
+fn timer_start(name: string, duration: int) {
+    scoreboard_set("timer_ticks", #rs, duration);
+    scoreboard_set("timer_active", #rs, 1);
+}
+
+fn timer_tick(name: string) -> int {
+    let active: int = scoreboard_get("timer_active", #rs);
+    let ticks: int = scoreboard_get("timer_ticks", #rs);
+
+    if (active == 0) {
+        return 0;
+    }
+
+    if (ticks > 0) {
+        let next: int = ticks - 1;
+        scoreboard_set("timer_ticks", #rs, next);
+
+        if (next == 0) {
+            scoreboard_set("timer_active", #rs, 0);
+        }
+
+        return next;
+    }
+
+    scoreboard_set("timer_active", #rs, 0);
+    return 0;
+}
+
+fn timer_done(name: string) -> int {
+    let active: int = scoreboard_get("timer_active", #rs);
+    let ticks: int = scoreboard_get("timer_ticks", #rs);
+
+    if (active == 0) {
+        if (ticks <= 0) {
+            return 1;
+        }
+    }
+
+    return 0;
+}

package/src/templates/README.md

@@ -0,0 +1,126 @@
+# Templates
+
+This folder contains production-oriented RedScript templates you can copy into datapack projects and adapt to your own scoreboard/objective naming.
+
+## Included templates
+
+### `mini-game-framework.rs`
+
+A reusable round controller with four phases:
+
+- `0`: waiting
+- `1`: starting
+- `2`: playing
+- `3`: ending
+
+It provides `/trigger game_join`, `/trigger game_start`, and a `@tick(rate=20)` loop that advances the countdown and announces state changes with `title`, `subtitle`, and `actionbar`.
+
+### `economy.rs`
+
+A scoreboard-backed coin system with:
+
+- `earn(player, amount)`
+- `spend(player, amount) -> int`
+- `balance(player) -> int`
+- `shop_buy(player, item, price)`
+
+Use it as the base layer for shops, quest rewards, or class unlocks.
+
+### `combat.rs`
+
+A combat state module built around `CombatEntity`:
+
+- health
+- max health
+- defense
+- cooldown
+
+It includes direct damage/heal helpers, alive checks, cooldown ticking, and combat tags such as `in_combat`, `combat_ready`, and `defeated`.
+
+### `quest.rs`
+
+A mission system using a `Quest` struct and scoreboard-backed progress:
+
+- start a quest
+- add progress
+- complete the quest
+- hook into `/trigger kill_zombie`
+
+This works well for survival servers, RPG loops, and PvE encounters.
+
+## Combining templates
+
+### Economy + Combat = RPG foundation
+
+Use `combat.rs` to handle health, armor, and cooldown windows. Reward victories or enemy kills through `economy.rs`, then let players spend coins on better gear or consumables.
+
+### Quest + Economy = reward loop
+
+Run `quest_complete()` and then call `earn()` to pay players for finishing objectives. This gives you a clean mission-reward pipeline with minimal scoreboard plumbing.
+
+### Mini-game framework + Combat = arena match
+
+Use `mini-game-framework.rs` for phase control and player flow, then activate combat logic only during phase `2` so the lobby and ending states remain safe.
+
+## RedScript reference card
+
+### Core syntax
+
+```rs
+struct Stats { hp: int, armor: int }
+
+fn add(a: int, b: int) -> int {
+    return a + b;
+}
+
+if (score > 10) {
+    title(@s, "Ready");
+} else {
+    actionbar(@s, "Keep going");
+}
+
+foreach (player in @a) {
+    tell(player, "Round live");
+}
+```
+
+### Decorators
+
+```rs
+@tick
+fn every_tick() {}
+
+@tick(rate=20)
+fn once_per_second() {}
+
+@on_trigger("shop_buy")
+fn handle_trigger() {}
+```
+
+### Common builtins
+
+```rs
+title(@a, "Fight!");
+actionbar(@a, "Capture the point");
+give(@s, "minecraft:bread", 1);
+scoreboard_set("@s", "coins", 10);
+let coins: int = scoreboard_get("@s", "coins");
+tag_add(@s, "boss");
+tag_remove(@s, "boss");
+```
+
+### Execution context
+
+```rs
+as @a {
+    say("Hello");
+}
+
+at @s {
+    summon("zombie", "~", "~", "~");
+}
+
+execute as @a if entity @s[tag=vip] run {
+    title(@s, "VIP");
+}
+```

package/src/templates/combat.rs

@@ -0,0 +1,96 @@
+// Combat helper library with scoreboard-backed health and cooldown state.
+
+struct CombatEntity { health: int, maxHealth: int, defense: int, cooldown: int }
+
+fn entity_state(target: string) -> CombatEntity {
+    let health: int = scoreboard_get(target, #health);
+    let maxHealth: int = scoreboard_get(target, #max_health);
+    let defense: int = scoreboard_get(target, #defense);
+    let cooldown: int = scoreboard_get(target, #cooldown);
+    let entity: CombatEntity = {
+        health: health,
+        maxHealth: maxHealth,
+        defense: defense,
+        cooldown: cooldown
+    };
+    return entity;
+}
+
+fn deal_damage(attacker: string, target: string, damage: int) {
+    let entity: CombatEntity = entity_state(target);
+    let finalDamage: int = damage - entity.defense;
+
+    if (entity.cooldown > 0) {
+        actionbar(attacker, "Attack on cooldown");
+        return;
+    }
+
+    if (finalDamage < 1) {
+        finalDamage = 1;
+    }
+
+    if (entity.health > finalDamage) {
+        entity.health = entity.health - finalDamage;
+        scoreboard_set(target, #health, entity.health);
+        scoreboard_set(attacker, #cooldown, 10);
+        tag_add(attacker, #in_combat);
+        tag_add(target, #in_combat);
+        tag_add(attacker, #combat_ready);
+        tag_remove(attacker, #combat_ready);
+        actionbar(attacker, "Hit confirmed");
+        actionbar(target, "You took damage");
+    } else {
+        scoreboard_set(target, #health, 0);
+        scoreboard_set(attacker, #cooldown, 10);
+        tag_add(attacker, #in_combat);
+        tag_add(target, #in_combat);
+        tag_add(target, #defeated);
+        tag_remove(target, #combat_ready);
+        title(target, "Defeated");
+        subtitle(target, "Wait for a heal or respawn");
+    }
+}
+
+fn heal_entity(target: string, amount: int) {
+    let entity: CombatEntity = entity_state(target);
+
+    if (entity.health <= 0) {
+        tag_remove(target, #defeated);
+    }
+
+    entity.health = entity.health + amount;
+    if (entity.health > entity.maxHealth) {
+        entity.health = entity.maxHealth;
+    }
+
+    scoreboard_set(target, #health, entity.health);
+    actionbar(target, "Health restored");
+}
+
+fn is_alive(target: string) -> int {
+    let health: int = scoreboard_get(target, #health);
+    if (health > 0) {
+        return 1;
+    }
+    return 0;
+}
+
+@tick(rate=1)
+fn combat_tick() {
+    foreach (entity in @e[tag=in_combat]) {
+        let cooldown: int = scoreboard_get(@s, #cooldown);
+
+        if (cooldown > 0) {
+            let next: int = cooldown - 1;
+            scoreboard_set(@s, #cooldown, next);
+
+            if (next == 0) {
+                tag_add(@s, #combat_ready);
+                tag_remove(@s, #in_combat);
+            }
+        } else {
+            tag_add(@s, #combat_ready);
+            tag_remove(@s, #in_combat);
+        }
+    }
+}