redscript-mc 1.0.0 → 1.2.0

package/src/stdlib/README.md

@@ -1,156 +1,194 @@
-# RedScript Stdlib
+# RedScript Standard Library
 
-This folder contains source-only utility modules for RedScript projects. There is
-no import system yet, so stdlib usage is intentionally simple:
+Ready-to-use utility functions for common Minecraft operations.
 
-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.
+## Usage
 
-## 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:
+```mcrs
+import "stdlib/effects.mcrs"
+import "stdlib/world.mcrs"
 
-- `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);
+fn start() {
+    set_day();
+    buff_all(@a, 600);  // 30 second buff
 }
 ```
 
-### `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:
+## Modules
 
-```rs
-if (cooldown_ready("dash") == 1) {
-    cooldown_start("dash", 40);
-}
-cooldown_tick("dash");
+### math.mcrs
+Basic math utilities.
+- `abs(x)` — Absolute value
+- `min(a, b)` — Minimum of two values
+- `max(a, b)` — Maximum of two values
+- `clamp(x, min, max)` — Clamp value to range
+- `sign(x)` — Sign of number (-1, 0, 1)
+
+### effects.mcrs
+Effect shortcuts.
+- `speed(target, duration, level)`
+- `jump(target, duration, level)`
+- `regen(target, duration, level)`
+- `resistance(target, duration, level)`
+- `strength(target, duration, level)`
+- `invisible(target, duration)`
+- `night_vision(target, duration)`
+- `slow_fall(target, duration)`
+- `glow(target, duration)`
+- `clear_effects(target)`
+- `buff_all(target, duration)` — Speed + strength + regen + resistance
+
+### world.mcrs
+World and game rule helpers.
+- `set_day()`, `set_night()`, `set_noon()`, `set_midnight()`
+- `weather_clear()`, `weather_rain()`, `weather_thunder()`
+- `enable_keep_inventory()`, `disable_keep_inventory()`
+- `disable_mob_griefing()`, `disable_fire_spread()`
+- `set_peaceful()`, `set_easy()`, `set_normal()`, `set_hard()`
+- `barrier_wall(x1,y1,z1,x2,y2,z2)`
+- `clear_area(x1,y1,z1,x2,y2,z2)`
+- `glass_box(x1,y1,z1,x2,y2,z2)`
+
+### inventory.mcrs
+Inventory management.
+- `clear_inventory(target)`
+- `give_kit_warrior(target)`
+- `give_kit_archer(target)`
+- `give_kit_mage(target)`
+- `remove_item(target, item)`
+
+### player.mcrs
+Player state management.
+- `heal(amount)`
+- `damage(amount)`
+- `is_op()` — Check if player has op tag
+
+### cooldown.mcrs
+Cooldown system using scoreboards.
+- `cooldown_start(target, ticks)`
+- `cooldown_tick()`
+- `is_on_cooldown(target)` → int
+
+### timer.mcrs
+Timer utilities with an OOP API.
+- `Timer::new(ticks)` → `Timer`
+- `timer.start()`, `timer.pause()`, `timer.reset()`
+- `timer.done()` → bool
+- `timer.elapsed()` → int
+- `timer.remaining()` → int
+- `timer.tick()` — manual tick update; current runtime uses one shared timer slot
+
+### combat.mcrs
+Combat helpers.
+- `apply_damage(target, amount)`
+- `knockback(target, strength)`
+
+### mobs.mcrs
+Mob spawning utilities.
+- `spawn_zombie(x, y, z)`
+- `spawn_skeleton(x, y, z)`
+- `spawn_creeper(x, y, z)`
+
+### sets.mcrs
+Runtime set operations (NBT-based).
+- `make_set()` → string
+- `add_to_set(set, value)`
+- `in_set(set, value)` → int
+- `remove_from_set(set, value)`
+
+### strings.mcrs
+String formatting helpers.
+- `broadcast(msg)` — Announce to all players
+- `whisper(target, msg)` — Private message
+
+### particles.mcrs
+Particle effect shortcuts.
+- `hearts(target)` — Heart particles above target
+- `flames(x, y, z)` — Fire particles
+- `smoke(x, y, z)` — Smoke effect
+- `explosion_effect(x, y, z)` — Explosion particles
+- `sparkles(target)` — Enchantment sparkles
+- `angry(target)` — Angry villager particles
+- `happy(target)` — Happy villager particles
+- `portal_effect(x, y, z)` — Portal particles
+- `totem_effect(target)` — Totem of undying particles
+- `end_sparkles(target)` — End rod particles
+
+### spawn.mcrs
+Teleport and spawn utilities.
+- `teleport_to(target, x, y, z)` — TP to coordinates
+- `teleport_to_entity(target, dest)` — TP to entity
+- `gather_all(x, y, z)` — TP all players
+- `launch_up(target, height)` — Launch player upward
+- `goto_lobby(target)` — TP to lobby
+- `goto_arena(target)` — TP to arena
+
+### teams.mcrs
+Team management.
+- `create_team(name, color)` — Create colored team
+- `create_red_team()`, `create_blue_team()` — Quick team setup
+- `create_green_team()`, `create_yellow_team()`
+- `add_to_team(target, team)` — Add player to team
+- `remove_from_teams(target)` — Remove from all teams
+- `setup_two_teams()` — Quick 2-team setup
+- `setup_four_teams()` — Quick 4-team setup
+- `cleanup_teams()` — Remove all teams
+
+### bossbar.mcrs
+Bossbar for timers and progress.
+- `create_timer_bar(id, name, seconds)` — Timer bossbar
+- `create_health_bar(id, name, max)` — Red health bar
+- `create_progress_bar(id, name, max)` — Blue progress bar
+- `update_bar(id, value)` — Update value
+- `hide_bar(id)`, `show_bar(id)` — Visibility
+- `remove_bar(id)` — Delete bossbar
+- `update_bar_color(id, percent)` — Color by percentage
+
+### interactions.mcrs
+Player input detection (right click, sneak, look direction).
+- `interactions_init()` — Setup scoreboards (call on @load)
+- `on_right_click()` — Detect carrot-on-stick right click
+- `is_sneaking(target)` — Check if sneaking
+- `on_sneak_start()` — Detect sneak start (first tick)
+- `check_look_up()` — Tag players looking up
+- `check_look_down()` — Tag players looking down
+- `on_sneak_click()` — Detect sneak + right click combo
+- `on_double_sneak()` — Detect double-tap sneak
+
+**New selector filters:**
+```mcrs
+// Rotation (pitch/yaw)
+@a[x_rotation=-90..-45]  // Looking up
+@a[x_rotation=45..90]    // Looking down
+@a[y_rotation=0..90]     // Facing east
+
+// Position ranges
+@a[x=-5..5, y=62..68, z=-5..5]  // In specific area
 ```
 
-## Incorporation Patterns
+### tags.mcrs
+Minecraft Java Edition tag constants generated from the Minecraft Fandom tag list.
 
-### Copy into your project
+#### Coverage
+- 171 `BLOCK_*` constants for Java block tags
+- 14 `ENTITY_*` constants for Java entity type tags
+- 99 `ITEM_*` constants for Java item tags
+- 2 `FLUID_*` constants for Java fluid tags
+- 27 `DAMAGE_*` constants for Java damage type tags
 
-This is the simplest path today. Paste the helper functions above your gameplay
-functions and compile one `.rs` file.
+#### Naming
+- Constants use `SCREAMING_SNAKE_CASE`
+- Each constant is prefixed by category: `BLOCK_`, `ENTITY_`, `ITEM_`, `FLUID_`, `DAMAGE_`
+- Each value is the full tag selector string, for example `#minecraft:mineable/axe`
 
-### Compile separately
+#### Usage
+```mcrs
+import "stdlib/tags.mcrs"
 
-You can inspect or ship a stdlib datapack directly:
+// Select skeleton variants
+kill(@e[type=ENTITY_SKELETONS]);
 
-```bash
-npx ts-node src/cli.ts compile src/stdlib/math.rs -o dist/stdlib-math
+// Use block and item tags in your own helpers
+const LOGS: string = BLOCK_LOGS;
+const SWORDS: string = ITEM_SWORDS;
 ```
-
-### 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/bossbar.mcrs

@@ -0,0 +1,68 @@
+// Bossbar helpers for progress bars and timers
+// Usage: import "stdlib/bossbar.mcrs"
+
+/// Create and show a timer bossbar
+fn create_timer_bar(id: string, name: string, max_seconds: int) {
+    bossbar_add(id, name);
+    bossbar_set_max(id, max_seconds * 20);
+    bossbar_set_value(id, max_seconds * 20);
+    bossbar_set_color(id, "green");
+    bossbar_set_style(id, "progress");
+    bossbar_set_players(id, @a);
+    bossbar_set_visible(id, 1);
+}
+
+/// Create a health-style bossbar (red)
+fn create_health_bar(id: string, name: string, max_val: int) {
+    bossbar_add(id, name);
+    bossbar_set_max(id, max_val);
+    bossbar_set_value(id, max_val);
+    bossbar_set_color(id, "red");
+    bossbar_set_style(id, "progress");
+    bossbar_set_players(id, @a);
+    bossbar_set_visible(id, 1);
+}
+
+/// Create a progress bossbar (blue)
+fn create_progress_bar(id: string, name: string, max_val: int) {
+    bossbar_add(id, name);
+    bossbar_set_max(id, max_val);
+    bossbar_set_value(id, 0);
+    bossbar_set_color(id, "blue");
+    bossbar_set_style(id, "progress");
+    bossbar_set_players(id, @a);
+    bossbar_set_visible(id, 1);
+}
+
+/// Update bossbar value
+fn update_bar(id: string, value: int) {
+    bossbar_set_value(id, value);
+}
+
+/// Hide bossbar
+fn hide_bar(id: string) {
+    bossbar_set_visible(id, 0);
+}
+
+/// Show bossbar
+fn show_bar(id: string) {
+    bossbar_set_visible(id, 1);
+}
+
+/// Remove bossbar
+fn remove_bar(id: string) {
+    bossbar_remove(id);
+}
+
+/// Set bossbar color based on percentage
+fn update_bar_color(id: string, percent: int) {
+    if (percent > 66) {
+        bossbar_set_color(id, "green");
+    } else {
+        if (percent > 33) {
+            bossbar_set_color(id, "yellow");
+        } else {
+            bossbar_set_color(id, "red");
+        }
+    }
+}

package/src/stdlib/{cooldown.rs → cooldown.mcrs}

@@ -1,6 +1,6 @@
 // Cooldown helpers.
 //
-// Like timer.rs, the `name` parameter is reserved for a future compiler/runtime
+// Like timer.mcrs, 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.
 

package/src/stdlib/effects.mcrs

@@ -0,0 +1,64 @@
+// Effect helper functions
+
+/// Give speed boost
+fn speed(target: selector, duration: int, level: int) {
+    effect(target, "minecraft:speed", duration, level);
+}
+
+/// Give jump boost
+fn jump(target: selector, duration: int, level: int) {
+    effect(target, "minecraft:jump_boost", duration, level);
+}
+
+/// Give regeneration
+fn regen(target: selector, duration: int, level: int) {
+    effect(target, "minecraft:regeneration", duration, level);
+}
+
+/// Give resistance
+fn resistance(target: selector, duration: int, level: int) {
+    effect(target, "minecraft:resistance", duration, level);
+}
+
+/// Give strength
+fn strength(target: selector, duration: int, level: int) {
+    effect(target, "minecraft:strength", duration, level);
+}
+
+/// Give invisibility
+fn invisible(target: selector, duration: int) {
+    effect(target, "minecraft:invisibility", duration, 0);
+}
+
+/// Give night vision
+fn night_vision(target: selector, duration: int) {
+    effect(target, "minecraft:night_vision", duration, 0);
+}
+
+/// Give slow falling
+fn slow_fall(target: selector, duration: int) {
+    effect(target, "minecraft:slow_falling", duration, 0);
+}
+
+/// Give glowing effect
+fn glow(target: selector, duration: int) {
+    effect(target, "minecraft:glowing", duration, 0);
+}
+
+/// Clear all effects from target
+fn clear_effects(target: selector) {
+    effect_clear(target);
+}
+
+/// Clear specific effect from target
+fn clear_effect(target: selector, eff: string) {
+    effect_clear(target, eff);
+}
+
+/// Full buff package (speed, strength, regen)
+fn buff_all(target: selector, duration: int) {
+    speed(target, duration, 1);
+    strength(target, duration, 1);
+    regen(target, duration, 1);
+    resistance(target, duration, 0);
+}

package/src/stdlib/interactions.mcrs

@@ -0,0 +1,195 @@
+// Player interaction detection helpers
+// Usage: import "stdlib/interactions.mcrs"
+//
+// Common patterns for detecting player input:
+// - Right click (carrot on stick)
+// - Sneak/crouch
+// - Look direction
+// - Item in hand
+
+// =============================================
+// SETUP - Call once on @load
+// =============================================
+
+/// Initialize interaction scoreboards
+fn interactions_init() {
+    // Right click detection (carrot on a stick)
+    scoreboard_add_objective("rs.click", "minecraft.used:minecraft.carrot_on_a_stick");
+    
+    // Sneak time tracking
+    scoreboard_add_objective("rs.sneak", "minecraft.custom:minecraft.sneak_time");
+    
+    // Attack detection (left click on entity)
+    scoreboard_add_objective("rs.attack", "minecraft.custom:minecraft.damage_dealt");
+}
+
+// =============================================
+// RIGHT CLICK DETECTION
+// =============================================
+// Uses Carrot on a Stick item
+// Give players: /give @p carrot_on_a_stick{CustomModelData:1234}
+
+/// Check if player right-clicked (carrot on stick)
+/// Call this in @tick, resets after detection
+fn on_right_click(callback_fn: string) {
+    // Players with click score > 0 have clicked
+    foreach (p in @a) {
+        let clicks: int = scoreboard_get(p, "rs.click");
+        if (clicks > 0) {
+            // Reset counter
+            scoreboard_set(p, "rs.click", 0);
+            // Trigger callback by tag
+            tag_add(p, "rs.clicked");
+        }
+    }
+}
+
+/// Example: detect right click and do something
+fn example_right_click() {
+    foreach (p in @a) {
+        let clicks: int = scoreboard_get(p, "rs.click");
+        if (clicks > 0) {
+            scoreboard_set(p, "rs.click", 0);
+            // Do your action here
+            say("Player right clicked!");
+        }
+    }
+}
+
+// =============================================
+// SNEAK DETECTION  
+// =============================================
+
+/// Check if player just started sneaking
+/// Returns 1 if sneaking, 0 otherwise
+fn is_sneaking(target: selector) -> int {
+    let sneak_time: int = scoreboard_get(target, "rs.sneak");
+    if (sneak_time > 0) {
+        return 1;
+    }
+    return 0;
+}
+
+/// Detect sneak start (first tick of sneaking)
+fn on_sneak_start() {
+    foreach (p in @a) {
+        let sneak_time: int = scoreboard_get(p, "rs.sneak");
+        // Sneak time == 1 means just started
+        if (sneak_time == 1) {
+            tag_add(p, "rs.sneak_start");
+        } else {
+            tag_remove(p, "rs.sneak_start");
+        }
+    }
+}
+
+// =============================================
+// LOOK DIRECTION
+// =============================================
+// Uses execute with rotation checks
+
+/// Check if player is looking up (pitch < -45)
+fn check_look_up() {
+    // Now supports p[filters] syntax sugar!
+    foreach (p in @a) {
+        execute if entity p[x_rotation=-90..-45] run {
+            tag_add(@s, "rs.look_up");
+        }
+        execute unless entity p[x_rotation=-90..-45] run {
+            tag_remove(@s, "rs.look_up");
+        }
+    }
+}
+
+/// Check if player is looking down (pitch > 45)
+fn check_look_down() {
+    foreach (p in @a) {
+        execute if entity p[x_rotation=45..90] run {
+            tag_add(@s, "rs.look_down");
+        }
+        execute unless entity p[x_rotation=45..90] run {
+            tag_remove(@s, "rs.look_down");
+        }
+    }
+}
+
+/// Check if player is looking straight (pitch -45 to 45)
+fn check_look_straight() {
+    foreach (p in @a) {
+        execute if entity p[x_rotation=-45..45] run {
+            tag_add(@s, "rs.look_straight");
+        }
+        execute unless entity p[x_rotation=-45..45] run {
+            tag_remove(@s, "rs.look_straight");
+        }
+    }
+}
+
+// =============================================
+// ITEM IN HAND
+// =============================================
+// Use execute if data or predicates
+
+/// Check if holding specific item (by tag)
+/// Usage: check_holding_tag("my_wand") checks for tag rs.holding.my_wand
+fn check_holding_item(item_id: string) {
+    // This requires predicate files in datapack
+    // Example predicate: data/ns/predicates/holding_diamond_sword.json
+    // { "condition": "minecraft:entity_properties", 
+    //   "entity": "this",
+    //   "predicate": { "equipment": { "mainhand": { "items": ["minecraft:diamond_sword"] }}}}
+    
+    // For now, use NBT check via execute
+    say("Use execute if data for item checks");
+}
+
+// =============================================
+// COMBINED: SNEAK + RIGHT CLICK
+// =============================================
+// Common pattern: Sneak + Use for special ability
+
+/// Detect sneak + right click combo
+fn on_sneak_click() {
+    foreach (p in @a) {
+        let clicks: int = scoreboard_get(p, "rs.click");
+        let sneak: int = scoreboard_get(p, "rs.sneak");
+        
+        if (clicks > 0) {
+            if (sneak > 0) {
+                // Sneak + Click!
+                scoreboard_set(p, "rs.click", 0);
+                tag_add(p, "rs.sneak_click");
+            } else {
+                // Normal click
+                scoreboard_set(p, "rs.click", 0);
+                tag_add(p, "rs.clicked");
+            }
+        }
+    }
+}
+
+// =============================================
+// DOUBLE TAP SNEAK
+// =============================================
+// Detect double-tap sneak (toggle fly, etc)
+
+let last_sneak_tick: int = 0;
+const DOUBLE_TAP_WINDOW: int = 10;  // 0.5 second
+
+fn on_double_sneak() {
+    foreach (p in @a) {
+        let sneak: int = scoreboard_get(p, "rs.sneak");
+        let last: int = scoreboard_get(p, "rs.last_sneak");
+        let now: int = scoreboard_get(p, "rs.tick");
+        
+        // Just started sneaking
+        if (sneak == 1) {
+            let diff: int = now - last;
+            if (diff < DOUBLE_TAP_WINDOW) {
+                // Double sneak detected!
+                tag_add(p, "rs.double_sneak");
+            }
+            scoreboard_set(p, "rs.last_sneak", now);
+        }
+    }
+}