redscript-mc 2.5.0 → 2.6.0

package/docs/LANGUAGE_REFERENCE.md

@@ -1,6 +1,8 @@
 # RedScript Language Reference
 
-This document describes the syntax RedScript accepts today.
+This document describes the syntax and semantics RedScript accepts today.
+
+---
 
 ## Program Structure
 
@@ -16,40 +18,90 @@ fn main() {}
 
 If no namespace is provided, the CLI derives one from the filename or uses the compile option you pass.
 
+### Library modules
+
+Mark a file as a library (not a standalone datapack entry point) with `module library;`:
+
+```rs
+module library;
+
+fn helper(x: int) -> int {
+    return x * 2;
+}
+```
+
+---
+
+## Module System
+
+```rs
+module library;   // marks this file as a library (not a standalone datapack)
+
+import math;      // import a stdlib module by name
+import "path/to/file";  // import by relative file path
+```
+
+Imported names are available globally within the file. Circular imports are not supported.
+
+---
+
 ## Types
 
-RedScript currently supports these primitive types:
+### Primitive types
 
-| Type | Notes |
-|:--|:--|
-| `int` | Scoreboard-backed integer values |
-| `bool` | Lowered as `0` or `1` |
-| `float` | Fixed-point values scaled by `1000` |
-| `string` | Used primarily in builtin calls |
-| `void` | Function return type when no value is produced |
+| Type | Backend | Notes |
+|:--|:--|:--|
+| `int` | Scoreboard — signed 32-bit | Primary numeric type |
+| `bool` | Scoreboard — lowered as `0` / `1` | `true` = 1, `false` = 0 |
+| `fixed` | Scoreboard — ×10000 fixed-point | `1.5` is stored as `15000` |
+| `double` | NBT IEEE 754 double (`rs:d` storage) | Not backed by scoreboard; no arithmetic with scoreboard types without explicit cast |
+| `string` | Compiler/builtin | Primarily used as builtin arguments |
+| `void` | — | Function return type when no value is produced |
+| `float` | **Deprecated** — MC NBT float | Boundary type; no arithmetic supported; triggers `[FloatArithmetic]` lint warning |
 
-Composite types:
+### Composite types
 
 | Type form | Example |
 |:--|:--|
 | Struct | `TurretState` |
 | Array | `int[]`, `string[]` |
 
+### Type casting
+
+There are **no implicit conversions**. Use the `as` keyword for explicit casts:
+
+```rs
+let x: double = 3.14d;
+let x_fixed: fixed = x as fixed;    // double → fixed
+let x_int: int = x_fixed as int;    // fixed → int
+let d: double = x_fixed as double;  // fixed → double
+```
+
+### Literal suffixes
+
+- `double` literals use the `d` suffix: `3.14d`, `0.0d`, `1.0d`
+- `fixed` literals are regular numbers declared as `fixed` type (no suffix needed)
+- `int` literals are plain integers: `42`, `-7`
+- `bool` literals: `true`, `false`
+
 ### Variables
 
 ```rs
 let hp: int = 20;
 let enabled: bool = true;
-let speed: float = 1.5;
+let speed: fixed = 1.5;
+let x: double = 3.14d;
 let name: string = "turret";
 let numbers: int[] = [1, 2, 3];
 ```
 
-Type annotations are supported on `let` bindings and function parameters. Function return types use `->`.
+Type annotations are supported on `let` bindings and function parameters.
+
+---
 
 ## Functions
 
-Functions use C-style syntax and may return values.
+Functions use C-style syntax and may return values. Return types follow `->`.
 
 ```rs
 fn add(a: int, b: int) -> int {
@@ -68,6 +120,17 @@ Rules:
 - `return;` is valid in `void` functions.
 - Function calls are synchronous and compile to `function <namespace>:<name>`.
 
+### Generic functions
+
+Some stdlib functions use a type parameter `<T>`:
+
+```rs
+fn abs<T>(x: T) -> T { ... }
+fn min<T>(a: T, b: T) -> T { ... }
+```
+
+---
+
 ## Control Flow
 
 ### `if` / `else`
@@ -107,11 +170,11 @@ fn repeat() {
 }
 ```
 
-The initializer is optional, and compound assignment is supported in the step clause.
+The initializer is optional. Compound assignment is supported in the step clause.
 
 ### `foreach`
 
-`foreach` iterates over a selector by extracting the body into a helper function and running it with `execute as ... run function ...`.
+`foreach` iterates over a selector. The body is extracted into a helper function and run with `execute as ... run function ...`.
 
 ```rs
 fn notify_players() {
@@ -121,11 +184,13 @@ fn notify_players() {
 }
 ```
 
-Inside the loop body, the bound variable refers to the current entity context.
+Inside the loop body, the bound variable refers to the current entity context (`@s`).
+
+---
 
 ## Structs
 
-Structs group fields and are stored in Minecraft storage.
+Structs group fields and are stored in Minecraft NBT storage.
 
 ```rs
 struct TurretState {
@@ -137,6 +202,7 @@ fn create() {
     let state: TurretState = { health: 40, level: 1 };
     state.health = 50;
     let hp = state.health;
+    state.health += 5;
 }
 ```
 
@@ -144,13 +210,14 @@ Supported operations:
 
 - Struct declaration
 - Struct literals
-- Field read
-- Field assignment
-- Compound assignment on fields such as `state.health += 5`
+- Field read / field assignment
+- Compound assignment on fields (`state.health += 5`)
+
+---
 
 ## Arrays
 
-Arrays are currently backed by Minecraft storage.
+Arrays are backed by Minecraft NBT storage.
 
 ```rs
 fn sample() {
@@ -160,20 +227,22 @@ fn sample() {
 }
 ```
 
-Current support includes:
+Supported operations:
 
 - Empty arrays: `[]`
 - Array literals with initial values
 - `push(...)`
-- Index reads such as `arr[0]`
+- Index reads (`arr[0]`)
+
+---
 
 ## Decorators
 
-Decorators attach runtime behavior to functions.
+Decorators attach runtime behaviour to functions.
 
 ### `@tick`
 
-Runs every game tick through the generated `__tick.mcfunction`.
+Runs every game tick via the generated `__tick.mcfunction`.
 
 ```rs
 @tick
@@ -210,29 +279,90 @@ The compiler creates:
 - a dispatch function
 - trigger checks inside `__tick.mcfunction`
 
-## Execute Context
+### `@schedule(N)`
 
-RedScript supports both shorthand context blocks and explicit `execute ... run { ... }`.
+Runs the function once after `N` ticks (one-shot scheduled call).
+
+```rs
+@schedule(100)
+fn delayed_explosion() {
+    summon("tnt", "~", "~", "~");
+}
+```
 
-### `as`
+### `@coroutine`
+
+Marks a function as a tick-splitting state machine. Loop back-edges become automatic yield points: the loop body runs up to `batch` iterations per tick, then returns — resuming next tick where it left off.
 
 ```rs
-as @a {
-    say("Hello from each player");
+@coroutine(batch=10, onDone="on_scan_done")
+fn scan_region() {
+    let x: int = 0;
+    while (x < 1000) {
+        process(x);
+        x += 1;
+    }
+    // after the loop: calls on_scan_done()
 }
 ```
 
-### `at`
+**Parameters:**
+- `batch` — maximum loop iterations per tick (default: 1). Total ticks = actual iterations / batch.
+- `onDone` — optional function name to call when the coroutine finishes.
+
+**How it works:**
+
+The compiler performs control-flow analysis (dominator tree + back-edge detection) to find all loop headers. Each loop is split into a *continuation function* that runs up to `batch` iterations before returning. A generated `@tick` dispatcher checks a scoreboard `pc` counter and calls the right continuation each tick.
+
+```
+call scan_region()           → sets pc = 1, initializes live vars
+@tick → dispatcher           → pc == 1 → call _coro_scan_region_cont_1
+cont_1 runs 10 iterations    → returns (yield)
+next tick: cont_1 runs again → ... until loop exits
+loop done                    → calls onDone, sets pc = -1 (stopped)
+```
+
+Variables that are live across yield points are automatically promoted to persistent scoreboard slots.
+
+**Constraints:**
+- Functions containing macro calls cannot use `@coroutine` (continuations are invoked via `function`, which does not substitute macro variables).
+- Nested loops: the transform handles each loop independently. For nested loops, extract the inner loop into a separate function.
+- Multiple sequential loops compile to multiple continuations dispatched in order.
+- Calling one coroutine from another: use `onDone` chaining — the first coroutine's `onDone` callback initializes the second.
 
 ```rs
-at @s {
-    summon("zombie", "~", "~", "~");
+@coroutine(batch=5, onDone="start_phase2")
+fn phase1() { /* long work */ }
+
+fn start_phase2() {
+    phase2();  // initializes phase2's pc, starts it
 }
+
+@coroutine(batch=5)
+fn phase2() { /* runs after phase1 completes */ }
 ```
 
-### Combined `as` and `at`
+**Performance note:** `@coroutine` is designed to stay within MC's per-tick command budget (`maxCommandChainLength`, default 65536). Without it, 1000 iterations × 20 commands = 20000 commands/tick — fine. But 10000 iterations × 20 = 200000 — exceeds the limit and causes silent truncation. The `batch` parameter is your throttle valve.
+
+No blocking occurs — other `@tick` functions and game logic continue to run while the coroutine is spread across ticks.
+
+---
+
+## Execute Context
+
+RedScript supports both shorthand context blocks and explicit `execute ... run { ... }`.
+
+### Shorthand `as` / `at`
 
 ```rs
+as @a {
+    say("Hello from each player");
+}
+
+at @s {
+    summon("zombie", "~", "~", "~");
+}
+
 as @a at @s {
     particle("flame", "~", "~", "~");
 }
@@ -240,7 +370,7 @@ as @a at @s {
 
 ### `execute ... run { ... }`
 
-Supported subcommands today:
+Supported subcommands:
 
 - `as <selector>`
 - `at <selector>`
@@ -248,8 +378,6 @@ Supported subcommands today:
 - `unless entity <selector>`
 - `in <dimension>`
 
-Examples:
-
 ```rs
 execute as @a run {
     say("Hello");
@@ -272,11 +400,13 @@ execute as @a at @s if entity @s[tag=vip] in overworld run {
 }
 ```
 
+---
+
 ## Selectors
 
 Entity selectors are first-class expressions and can be passed directly to builtins.
 
-### Supported selector heads
+### Selector heads
 
 | Selector | Meaning |
 |:--|:--|
@@ -293,18 +423,22 @@ Entity selectors are first-class expressions and can be passed directly to built
 @e[type=armor_stand, tag=turret]
 @a[scores={kills=10..}]
 @p[distance=..5]
+@a[x_rotation=-90..-45]
 ```
 
-Supported filter categories in the current parser:
+Supported filter categories:
 
 - `type`
-- `distance` with ranges such as `..5`, `1..`, `1..10`
+- `distance` with ranges (`..5`, `1..`, `1..10`)
 - `tag`
 - score filters
 - `limit`
 - `sort`
 - `nbt`
 - `gamemode`
+- `x_rotation` / `y_rotation`
+
+---
 
 ## Coordinates
 
@@ -341,37 +475,80 @@ Each component can be:
 - a relative coordinate like `~` or `~-2`
 - a local coordinate like `^` or `^3`
 
+---
+
 ## Builtins
 
-The compiler recognizes these builtins and lowers them directly to Minecraft commands or runtime helpers.
+The compiler recognises these builtins and lowers them to Minecraft commands or runtime helpers.
+
+### General builtins
 
 | Builtin | Returns | Notes |
 |:--|:--|:--|
 | `say(msg)` | `void` | Emits `say` |
-| `tell(sel, msg)` | `void` | Emits `tellraw` with a plain text JSON component |
+| `tell(sel, msg)` | `void` | Emits `tellraw` with plain text JSON |
 | `title(sel, msg)` | `void` | Emits `title <sel> title` |
 | `give(sel, item, count?)` | `void` | Default count is `1` |
 | `effect(sel, effect, duration?, amplifier?)` | `void` | Defaults: duration `30`, amplifier `0` |
+| `effect_clear(sel, effect?)` | `void` | Clears specific or all effects |
 | `summon(type, x?, y?, z?, nbt?)` | `void` | Defaults position to `~ ~ ~` |
 | `particle(name, x?, y?, z?)` | `void` | Defaults position to `~ ~ ~` |
 | `tp(sel, x?, y?, z?)` | `void` | Also accepts `tp(sel, pos)` with `BlockPos` |
 | `setblock(x, y, z, block)` | `void` | Also accepts `setblock(pos, block)` with `BlockPos` |
 | `fill(x1, y1, z1, x2, y2, z2, block)` | `void` | Also accepts `fill(from, to, block)` with `BlockPos` |
-| `clone(x1, y1, z1, x2, y2, z2, dx, dy, dz)` | `void` | Also accepts `clone(from, to, dest)` with `BlockPos` |
+| `clone(x1, y1, z1, x2, y2, z2, dx, dy, dz)` | `void` | Also accepts `clone(from, to, dest)` |
 | `kill(sel?)` | `void` | Defaults to `@s` |
+| `clear(sel, item?)` | `void` | Clears all or specific item |
+| `time_set(ticks)` | `void` | Sets world time |
+| `weather(type)` | `void` | `"clear"`, `"rain"`, `"thunder"` |
+| `gamerule(rule, value)` | `void` | Sets a gamerule |
+| `difficulty(level)` | `void` | `"peaceful"`, `"easy"`, `"normal"`, `"hard"` |
+
+### Scoreboard builtins
+
+| Builtin | Returns | Notes |
+|:--|:--|:--|
 | `scoreboard_get(target, objective)` | `int` | Reads a scoreboard score |
 | `score(target, objective)` | `int` | Alias of `scoreboard_get` |
 | `scoreboard_set(target, objective, value)` | `void` | Writes a scoreboard score |
+| `scoreboard_add_objective(name, criterion)` | `void` | Creates a new objective |
+
+### Data / NBT builtins
+
+| Builtin | Returns | Notes |
+|:--|:--|:--|
 | `data_get(kind, target, path, scale?)` | `int` | Reads NBT with `data get` |
-| `random(min, max)` | `int` | Uses `scoreboard players random` for pre-1.20.3 compatibility |
-| `random_native(min, max)` | `int` | Uses `/random value <min> <max>` (MC 1.20.3+) |
-| `random_sequence(sequence, seed?)` | `void` | Uses `/random reset <sequence> <seed>`; default seed is `0` (MC 1.20.3+) |
-| `spawn_object(x, y, z)` | world object handle | Spawns an invisible armor stand with generated tags |
-| `raw(cmd)` | `void` | Emits a literal Minecraft command |
+| `storage_get_int(storage, path, index)` | `int` | Reads an array element from NBT storage |
+| `storage_set_array(storage, path, json)` | `void` | Writes an array literal to NBT storage |
+
+### Random builtins
+
+| Builtin | Returns | Notes |
+|:--|:--|:--|
+| `random(min, max)` | `int` | Uses `scoreboard players random` (pre-1.20.3) |
+| `random_native(min, max)` | `int` | Uses `/random value` (MC 1.20.3+) |
+| `random_sequence(sequence, seed?)` | `void` | Uses `/random reset` (MC 1.20.3+); default seed `0` |
+
+### Team builtins
+
+| Builtin | Returns | Notes |
+|:--|:--|:--|
+| `team_add(name)` | `void` | Creates a team |
+| `team_remove(name)` | `void` | Removes a team |
+| `team_join(sel, name)` | `void` | Adds entities to team |
+| `team_leave(sel)` | `void` | Removes entities from teams |
+| `team_option(name, key, value)` | `void` | Sets a team option |
+
+### Tag builtins
+
+| Builtin | Returns | Notes |
+|:--|:--|:--|
+| `tag_add(sel, name)` | `void` | Adds an entity tag |
+| `tag_remove(sel, name)` | `void` | Removes an entity tag |
 
 ### Entity helper methods
 
-These are written as member calls on selectors or spawned object handles:
+These are written as member calls on selectors or object handles:
 
 | Method | Returns | Example |
 |:--|:--|:--|
@@ -379,27 +556,23 @@ These are written as member calls on selectors or spawned object handles:
 | `entity.untag(name)` | `void` | `@s.untag("boss");` |
 | `entity.has_tag(name)` | `bool` | `let boss: bool = @s.has_tag("boss");` |
 
-## Operators
+### World object
 
-Arithmetic and comparison operators:
+| Builtin | Returns | Notes |
+|:--|:--|:--|
+| `spawn_object(x, y, z)` | world object handle | Spawns invisible armor stand with generated tags |
 
-- `+`, `-`, `*`, `/`, `%`
-- `==`, `!=`, `<`, `<=`, `>`, `>=`
-- `&&`, `||`
-- unary `-`, `!`
+### Escape hatch
 
-Assignment operators:
+| Builtin | Returns | Notes |
+|:--|:--|:--|
+| `raw(cmd)` | `void` | Emits a literal Minecraft command |
 
-- `=`
-- `+=`
-- `-=`
-- `*=`
-- `/=`
-- `%=`
+---
 
 ## Raw Commands
 
-Use `raw(...)` when you need an escape hatch for a command RedScript does not model directly.
+Use `raw(...)` as an escape hatch for commands RedScript does not model directly.
 
 ```rs
 fn admin() {
@@ -407,9 +580,71 @@ fn admin() {
 }
 ```
 
-## Notes on Numeric Semantics
+### `__NS__` and `__OBJ__` substitutions
+
+Inside `raw(...)`, two compile-time tokens are replaced automatically:
+
+- `__NS__` — replaced with the current namespace (e.g. `my_pack`)
+- `__OBJ__` — replaced with the current scoreboard objective (`__<namespace>`)
+
+```rs
+fn example() {
+    raw("scoreboard players set #flag __OBJ__ 1");
+    raw("function __NS__:helper");
+}
+```
+
+---
+
+## Operators
+
+### Arithmetic
+
+| Operator | Description |
+|:--|:--|
+| `+` | Addition |
+| `-` | Subtraction / unary negate |
+| `*` | Multiplication |
+| `/` | Integer division |
+| `%` | Modulo |
+
+### Comparison
+
+| Operator | Description |
+|:--|:--|
+| `==` | Equal |
+| `!=` | Not equal |
+| `<` | Less than |
+| `<=` | Less than or equal |
+| `>` | Greater than |
+| `>=` | Greater than or equal |
+
+### Logical
+
+| Operator | Description |
+|:--|:--|
+| `&&` | Logical AND |
+| `\|\|` | Logical OR |
+| `!` | Logical NOT |
+
+### Assignment
+
+| Operator | Description |
+|:--|:--|
+| `=` | Assign |
+| `+=` | Add-assign |
+| `-=` | Subtract-assign |
+| `*=` | Multiply-assign |
+| `/=` | Divide-assign |
+| `%=` | Modulo-assign |
+
+---
+
+## Numeric Semantics
 
-- `int` values map directly to scoreboard integers.
+- `int` values map directly to MC scoreboard integers (signed 32-bit).
 - `bool` is lowered as integer `0` or `1`.
-- `float` is stored as fixed-point `value * 1000`.
-- String values are currently most useful as builtin arguments rather than general-purpose data values.
+- `fixed` is a signed 32-bit scoreboard integer scaled by **×10000** (e.g. `1.5` → `15000`). Previously incorrectly documented as ×1000.
+- `double` is an IEEE 754 64-bit float stored in `rs:d` NBT storage — not accessible through scoreboard arithmetic without explicit casting.
+- `float` is deprecated. It represents an MC NBT float boundary type with no arithmetic support; using it triggers a `[FloatArithmetic]` lint warning.
+- `string` values are currently most useful as builtin arguments rather than general-purpose data.

package/docs/stdlib/README.md

@@ -0,0 +1,54 @@
+# Standard Library
+
+RedScript ships with 35 stdlib modules. Import any module with `import <name>;`.
+
+## Categories
+
+### Mathematics
+- [math](math.md) — basic math (`abs`, `clamp`, `lerp`, `sin_fixed`, `sqrt_fx`, `ln`, `exp_fx`, `smoothstep`, ...)
+- [math_hp](math_hp.md) — high-precision (`sin_hp`, `cos_hp`, `ln_hp`, `double_sqrt`, `pow_real`, ...)
+- [bits](bits.md) — bitwise operations (`bit_and`, `bit_or`, `bit_xor`, `bit_shl`, `popcount`, ...)
+- [bigint](bigint.md) — multi-word integers (base-10000 bigint add/sub/mul/div, arbitrary length)
+- [calculus](calculus.md) — numerical integration/differentiation (trapezoid, Simpson, Welford statistics)
+
+### Data Structures
+- [list](list.md) — array aggregates (`sum`, `avg`, `min`, `max`, `sort3`–`sort5`, `shuffle`, ...)
+- [sets](sets.md) — set operations (`set_new`, `set_add`, `set_contains`, `set_remove`)
+- [matrix](matrix.md) — matrix math for Display Entities (2D/3D rotation, scale, quaternion helpers)
+- [vec](vec.md) — 2D/3D vectors (`dot2d`, `cross3d`, `length2d_fixed`, `atan2_fixed`, `normalize2d_x`, ...)
+- [quaternion](quaternion.md) — 3D rotations (`quat_mul`, `quat_slerp`, `quat_euler`, axis-angle constructors)
+
+### Randomness & Statistics
+- [random](random.md) — LCG/PCG RNG, binomial and hypergeometric sampling
+- [noise](noise.md) — procedural noise (value noise 1D/2D, fractal Brownian motion, terrain height)
+
+### Signal Processing
+- [signal](signal.md) — DFT (up to 8 samples), Gaussian/exponential/Poisson/geometric distributions
+- [expr](expr.md) — RPN expression evaluator (dynamic formula evaluation at runtime)
+
+### Geometry & Graphics
+- [geometry](geometry.md) — selection zones (AABB, sphere, cylinder, cone, sector)
+- [advanced](advanced.md) — Bézier curves (quadratic–N-order), Mandelbrot/Julia, modular exponentiation
+- [parabola](parabola.md) — projectile trajectories (ballistic aiming, drag physics)
+- [easing](easing.md) — easing functions (quad, cubic, quartic, sine, expo, back, bounce, smoothstep)
+- [particles](particles.md) — particle helpers (hearts, flame, smoke; draw line, circle, helix)
+- [color](color.md) — RGB/HSL/hex color utilities (pack/unpack, lerp, RGB↔HSL conversion)
+
+### Physics
+- [physics](physics.md) — velocity, gravity, collision (projectile motion, drag, spring, friction)
+- [strings](strings.md) — string utilities (`str_len`)
+
+### Minecraft Game Mechanics
+- [player](player.md) — player utilities (`heal`, `damage`, `is_op`)
+- [mobs](mobs.md) — mob type string constants (all vanilla entity IDs)
+- [combat](combat.md) — damage and health (`weapon_damage`, `apply_damage`)
+- [effects](effects.md) — potion effects (`speed`, `jump`, `regen`, `buff_all`, ...)
+- [spawn](spawn.md) — entity spawning and teleportation (`teleport_to`, `goto_lobby`, `goto_arena`)
+- [interactions](interactions.md) — interaction entities (right-click, sneak, look-direction detection)
+- [inventory](inventory.md) — inventory management (`clear_inventory`, `give_kit_warrior`, ...)
+- [bossbar](bossbar.md) — boss bar UI (`create_timer_bar`, `create_health_bar`, `update_bar_color`)
+- [cooldown](cooldown.md) — ability cooldowns (`cooldown_start`, `cooldown_ready`, `cooldown_tick`)
+- [timer](timer.md) — countdown timers (`Timer` struct with `start`, `done`, `remaining`)
+- [tags](tags.md) — Minecraft block/entity/item/damage type tag string constants
+- [teams](teams.md) — team management (`setup_two_teams`, `setup_four_teams`, `add_to_team`)
+- [world](world.md) — world queries (`set_day`, `weather_clear`, `sun_altitude`, `glass_box`, ...)