redscript-mc 2.4.1 → 2.6.0

package/docs/stdlib/quaternion.md

@@ -0,0 +1,159 @@
+# `quaternion` — 3D rotations for Display Entities
+
+Import: `import quaternion;`
+
+Quaternion math for MC Display Entity rotations. Quaternions are stored as `[x, y, z, w]` with all components ×10000 (e.g. `qw=10000` = 1.0). A unit quaternion satisfies `qx²+qy²+qz²+qw² = 100,000,000` (= 10000²). Provides constructors from axis-angle, quaternion multiplication, conjugate, magnitude, dot, SLERP (via LERP+normalize for MC game quality), and Euler angles to quaternion conversion (YXZ order). Requires `math` for `sin_fixed`, `cos_fixed`, `mulfix`, `abs`, `isqrt`.
+
+## Functions
+
+### `quat_identity_w(): int`
+
+Returns W component of identity quaternion: 10000.
+
+### `quat_identity_x(): int` / `quat_identity_y(): int` / `quat_identity_z(): int`
+
+Returns 0 (X, Y, Z components of identity).
+
+---
+
+### `quat_axis_x_x(angle_deg: int): int`
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+X component of quaternion for rotation `angle_deg°` around X axis. Uses `sin(angle/2) × 10`.
+
+### `quat_axis_x_y(angle_deg: int): int` / `quat_axis_x_z(angle_deg: int): int`
+
+Return 0 (for X-axis rotation, Y and Z components are 0).
+
+### `quat_axis_x_w(angle_deg: int): int`
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+W component: `cos(angle/2) × 10`.
+
+---
+
+### `quat_axis_y_x(angle_deg: int): int` / `quat_axis_y_z(angle_deg: int): int`
+
+Return 0 (for Y-axis rotation).
+
+### `quat_axis_y_y(angle_deg: int): int`
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+Y component for rotation around Y axis: `sin(angle/2) × 10`.
+
+### `quat_axis_y_w(angle_deg: int): int`
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+W component: `cos(angle/2) × 10`.
+
+---
+
+### `quat_axis_z_x(angle_deg: int): int` / `quat_axis_z_y(angle_deg: int): int`
+
+Return 0 (for Z-axis rotation).
+
+### `quat_axis_z_z(angle_deg: int): int`
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+Z component for rotation around Z axis: `sin(angle/2) × 10`.
+
+### `quat_axis_z_w(angle_deg: int): int`
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+W component: `cos(angle/2) × 10`.
+
+---
+
+### `quat_mul_x(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int`
+
+X component of quaternion product `a × b`. Uses `mulfix` for fixed-point arithmetic.
+
+**Example:**
+```rs
+import quaternion;
+// Compose two 90° Y-axis rotations
+let ax: int = quat_axis_y_x(90); let ay: int = quat_axis_y_y(90);
+let az: int = quat_axis_y_z(90); let aw: int = quat_axis_y_w(90);
+let rx: int = quat_mul_x(ax, ay, az, aw, ax, ay, az, aw);  // 180° rotation
+```
+
+### `quat_mul_y(...)`, `quat_mul_z(...)`, `quat_mul_w(...)`
+
+Y, Z, W components of quaternion product.
+
+---
+
+### `quat_conj_x(qx: int, qy: int, qz: int, qw: int): int`
+
+X component of conjugate (= inverse for unit quaternion): `-qx`.
+
+### `quat_conj_y(...)`, `quat_conj_z(...)`, `quat_conj_w(...)`
+
+Y, Z components: negated. W component: unchanged.
+
+---
+
+### `quat_mag_sq(qx: int, qy: int, qz: int, qw: int): int`
+
+Magnitude squared ×10000 using `mulfix`. For unit quaternion this should equal 10000.
+
+---
+
+### `quat_dot(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int`
+
+Dot product of two quaternions ×10000.
+
+---
+
+### `quat_slerp_x(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int`
+
+X component of SLERP interpolation. `t ∈ [0, 1000]`. Uses LERP + normalize approximation (cheaper than true SLERP; sufficient for MC game use).
+
+### `quat_slerp_y(...)`, `quat_slerp_z(...)`, `quat_slerp_w(...)`
+
+Y, Z, W components of SLERP interpolation.
+
+**Example:**
+```rs
+import quaternion;
+// Interpolate halfway between identity and 90° Y rotation
+let bx: int = quat_axis_y_x(90); let by_: int = quat_axis_y_y(90);
+let bz: int = quat_axis_y_z(90); let bw: int = quat_axis_y_w(90);
+let rx: int = quat_slerp_x(0, 0, 0, 10000, bx, by_, bz, bw, 500);  // 45° at t=500
+```
+
+---
+
+### `quat_euler_x(yaw: int, pitch: int, roll: int): int`
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+X component of quaternion from Euler angles (YXZ order, MC convention). `yaw`, `pitch`, `roll` in degrees (plain integers).
+
+### `quat_euler_y(yaw: int, pitch: int, roll: int): int`
+
+Y component from Euler angles.
+
+### `quat_euler_z(yaw: int, pitch: int, roll: int): int`
+
+Z component from Euler angles.
+
+### `quat_euler_w(yaw: int, pitch: int, roll: int): int`
+
+W component from Euler angles.
+
+**Example:**
+```rs
+import quaternion;
+// Build quaternion from player yaw=45°, pitch=30°, roll=0°
+let qx: int = quat_euler_x(45, 30, 0);
+let qy: int = quat_euler_y(45, 30, 0);
+let qz: int = quat_euler_z(45, 30, 0);
+let qw: int = quat_euler_w(45, 30, 0);
+```

package/docs/stdlib/random.md

@@ -0,0 +1,86 @@
+# `random` — LCG/PCG RNG and distributions
+
+Import: `import random;`
+
+Pseudo-random number generators and statistical sampling. LCG (Linear Congruential Generator) with parameters from Numerical Recipes (a=1664525, c=1013904223, modulus 2³² via int32 overflow). Also provides a simplified PCG32-variant, binomial sampling, and hypergeometric sampling.
+
+## Functions
+
+### `next_lcg(seed: int): int`
+
+Advance LCG state: `seed × 1664525 + 1013904223`. The returned value is the new seed AND the random output. Fast, suitable for most game use.
+
+**Example:**
+```rs
+import random;
+let seed: int = 12345;
+seed = next_lcg(seed);
+```
+
+---
+
+### `random_range(seed: int, lo: int, hi: int): int`
+
+Integer in `[lo, hi)`. `seed` should be the output of `next_lcg`. Uses absolute value + modulo.
+
+**Example:**
+```rs
+import random;
+let seed: int = next_lcg(42);
+let roll: int = random_range(seed, 1, 7);  // d6: 1–6
+```
+
+---
+
+### `random_bool(seed: int): int`
+
+Returns 0 or 1 with equal probability.
+
+---
+
+### `pcg_next_lo(state_lo: int): int`
+
+Advance PCG state low word. Use with `pcg_next_hi` to maintain the two-word state.
+
+---
+
+### `pcg_next_hi(state_hi: int, state_lo: int): int`
+
+Advance PCG state high word.
+
+---
+
+### `pcg_output(state_lo: int): int`
+
+Extract output from PCG low word using XSH-RR permutation (simplified XOR-shift).
+
+> **Note:** Statistical quality is better than plain LCG but this is a simplified PCG32 variant, not the full reference implementation.
+
+---
+
+### `binomial_sample(n: int, p_x10000: int, seed: int): int`
+
+> **Cost:** O(n) — n LCG advances
+
+Count successes in `n` Bernoulli trials. `p_x10000`: probability ×10000 (5000 = 50%). Returns count ∈ `[0, n]`.
+
+**Example:**
+```rs
+import random;
+let hits: int = binomial_sample(10, 3000, 99999);  // 10 trials at 30% each
+```
+
+---
+
+### `hypergeometric_sample(pop_size: int, success_states: int, draws: int, seed: int): int`
+
+> **Cost:** O(draws)
+
+Draw `draws` items without replacement from a population of `pop_size` items, of which `success_states` are successes. Returns successes drawn ∈ `[0, min(draws, success_states)]`.
+
+**Example:**
+```rs
+import random;
+// Draw 5 cards from 52-card deck with 4 aces
+let aces: int = hypergeometric_sample(52, 4, 5, 12345);
+```

package/docs/stdlib/sets.md

@@ -0,0 +1,68 @@
+# `sets` — Set operations
+
+Import: `import sets;`
+
+Runtime set implementation using NBT storage arrays with uniqueness enforced on add. The actual implementation is handled by the compiler; this module documents the interface.
+
+## Functions
+
+### `set_new(): string`
+
+Create a new empty set. Returns a unique set ID string.
+
+**Example:**
+```rs
+import sets;
+let my_set: string = set_new();
+```
+
+---
+
+### `set_add(set: string, value: string)`
+
+Add `value` to the set if not already present (enforces uniqueness).
+
+**Example:**
+```rs
+import sets;
+let s: string = set_new();
+set_add(s, "player_alice");
+set_add(s, "player_bob");
+set_add(s, "player_alice");  // no-op, already in set
+```
+
+---
+
+### `set_contains(set: string, value: string): int`
+
+Returns 1 if `value` exists in the set, 0 otherwise.
+
+**Example:**
+```rs
+import sets;
+let has_alice: int = set_contains(my_set, "player_alice");  // 1
+```
+
+---
+
+### `set_remove(set: string, value: string)`
+
+Remove `value` from the set.
+
+**Example:**
+```rs
+import sets;
+set_remove(my_set, "player_bob");
+```
+
+---
+
+### `set_clear(set: string)`
+
+Remove all values from the set.
+
+**Example:**
+```rs
+import sets;
+set_clear(my_set);
+```

package/docs/stdlib/signal.md

@@ -0,0 +1,141 @@
+# `signal` — Statistical distributions, DFT, and signal processing
+
+Import: `import signal;`
+
+Statistical distributions (uniform, Gaussian approximation, exponential, Bernoulli, weighted choice, gamma, Poisson, geometric, negative binomial) and Discrete Fourier Transform helpers for up to 8 samples. All probability and distribution values use ×10000 scale. Requires `math` for `ln`, `exp_fx`, `sqrt_fx`; requires `random` for `next_lcg`.
+
+## Functions
+
+### `uniform_int(seed: int, lo: int, hi: int): int`
+
+Uniform integer in `[lo, hi]` inclusive using inline LCG.
+
+**Example:**
+```rs
+import signal;
+let roll: int = uniform_int(42, 1, 6);  // d6
+```
+
+---
+
+### `uniform_frac(seed: int): int`
+
+Uniform fraction in `[0, 10000]` (×10000 scale).
+
+---
+
+### `normal_approx12(seed: int): int`
+
+> **Cost:** 12 LCG advances per call
+
+Approximate N(0, 1) × 10000 using the sum-of-12-uniforms method. Output range ≈ `[-60000, 60000]`. Mean = 0, σ ≈ 10000. Good enough for game use.
+
+**Example:**
+```rs
+import signal;
+let noise: int = normal_approx12(seed);  // ≈ N(0,1) × 10000
+```
+
+---
+
+### `exp_dist_approx(seed: int, lambda_fx: int): int`
+
+> **Requires:** `math` for `ln`
+
+Exponential distribution variate ×10000. `lambda_fx ×10000` (e.g. 10000 = rate 1.0). Output capped at 100000 (10.0) for MC sanity.
+
+---
+
+### `bernoulli(seed: int, p_fx: int): int`
+
+Bernoulli trial: 1 with probability `p_fx / 10000`, 0 otherwise.
+
+**Example:**
+```rs
+import signal;
+let hit: int = bernoulli(seed, 3000);  // 30% chance of 1
+```
+
+---
+
+### `weighted2(seed: int, w0: int, w1: int): int`
+
+Choose 0 or 1 with integer weights `w0`, `w1`.
+
+---
+
+### `weighted3(seed: int, w0: int, w1: int, w2: int): int`
+
+Choose 0, 1, or 2 with integer weights.
+
+---
+
+### `gamma_sample(shape_k: int, scale_theta: int, seed: int): int`
+
+> **Cost:** O(shape_k / 10000) — up to 5 exponential samples  
+> **Requires:** `math` for `ln`
+
+Gamma(k, θ) variate ×10000. `shape_k ×10000` (e.g. 20000 = k=2), `scale_theta ×10000`. Handles k = 1..5.
+
+---
+
+### `poisson_sample(lambda: int, seed: int): int`
+
+> **Cost:** O(lambda / 10000) expected — Knuth algorithm  
+> **Requires:** `math` for `exp_fx`
+
+Poisson(λ) count. `lambda ×10000`. Works well for λ ≤ 20 (200000 in ×10000). Hard cap at 100 iterations.
+
+**Example:**
+```rs
+import signal;
+let spawns: int = poisson_sample(30000, seed);  // Poisson(3) spawn count
+```
+
+---
+
+### `geometric_sample(p_success: int, seed: int): int`
+
+> **Requires:** `math` for `ln`
+
+Geometric(p) — count of failures before first success. `p_success ×10000`. Returns non-negative integer.
+
+---
+
+### `negative_binomial_sample(r: int, p_success: int, seed: int): int`
+
+> **Cost:** O(r) — sums r geometric samples  
+> **Requires:** `geometric_sample`
+
+Negative Binomial(r, p) — failures before `r` successes. `p_success ×10000`.
+
+---
+
+### `dft_real(s0: int, s1: int, s2: int, s3: int, s4: int, s5: int, s6: int, s7: int, n: int, k: int): int`
+
+> **Cost:** O(n) — n multiply-add operations using 45°-step trig lookup
+
+Real part of DFT bin `k` for `n` samples (`n ≤ 8`). All sample values ×10000. Returns `(1/n) × Σ samples[j] × cos(2π k j / n)` × 10000. Uses `_cos45`/`_sin45` which handle 45°-step angles without NBT.
+
+**Example:**
+```rs
+import signal;
+// Compute DC component (k=0) of a 4-sample signal
+let dc: int = dft_real(10000, 5000, 0, -5000, 0, 0, 0, 0, 4, 0);
+```
+
+---
+
+### `dft_imag(s0: int, s1: int, s2: int, s3: int, s4: int, s5: int, s6: int, s7: int, n: int, k: int): int`
+
+> **Cost:** O(n)
+
+Imaginary part of DFT bin `k` (negative sine convention). Returns `-(1/n) × Σ samples[j] × sin(2π k j / n)` × 10000.
+
+---
+
+### `dft_magnitude(s0: int, s1: int, s2: int, s3: int, s4: int, s5: int, s6: int, s7: int, n: int, k: int): int`
+
+> **Cost:** O(n) + sqrt
+
+Magnitude of DFT bin `k`: `√(real² + imag²)`.

package/docs/stdlib/spawn.md

@@ -0,0 +1,65 @@
+# `spawn` — Entity spawning and teleportation
+
+Import: `import spawn;`
+
+Teleportation and spawn point helpers for players and entities.
+
+## Functions
+
+### `teleport_to(target: selector, x: int, y: int, z: int)`
+
+Teleport `target` to absolute coordinates.
+
+**Example:**
+```rs
+import spawn;
+teleport_to(@s, 100, 64, 100);
+```
+
+---
+
+### `teleport_to_entity(target: selector, dest: selector)`
+
+Teleport `target` to another entity's location.
+
+**Example:**
+```rs
+import spawn;
+teleport_to_entity(@a, @e[type=armor_stand, tag=spawn_point, limit=1]);
+```
+
+---
+
+### `spread_players(x: int, z: int, radius: int)`
+
+Spread players randomly within `radius` of `(x, z)`. Currently emits a placeholder message; implement with `raw("spreadplayers ...")` for full functionality.
+
+---
+
+### `gather_all(x: int, y: int, z: int)`
+
+Teleport all players to one location.
+
+**Example:**
+```rs
+import spawn;
+gather_all(0, 64, 0);
+```
+
+---
+
+### `launch_up(target: selector, height: int)`
+
+Teleport target upward by `height` blocks using relative coordinates.
+
+---
+
+### `goto_lobby(target: selector)`
+
+Teleport target to the lobby (default: 0, 64, 0) and show "Welcome to Lobby!" title.
+
+---
+
+### `goto_arena(target: selector)`
+
+Teleport target to the arena (default: 100, 64, 100) and show "Fight!" title.

package/docs/stdlib/strings.md

@@ -0,0 +1,17 @@
+# `strings` — String utilities
+
+Import: `import strings;`
+
+String helper utilities. Runtime string manipulation is currently limited in RedScript; `str_len` is compiler-assisted and lowers to `data get storage rs:strings ...` for literal-backed strings.
+
+## Functions
+
+### `str_len(s: string): int`
+
+Return the length of a string. Currently returns 0 as a stub; full implementation is compiler-assisted for literal-backed strings.
+
+**Example:**
+```rs
+import strings;
+let len: int = str_len("hello");  // 5 (compiler-assisted)
+```

package/docs/stdlib/tags.md

@@ -0,0 +1,117 @@
+# `tags` — Minecraft tag constants
+
+Import: `import tags;`
+
+String constants for vanilla Minecraft Java Edition block, entity type, item, fluid, and damage type tags. Use these instead of raw string literals to avoid typos. All values are `#minecraft:...` tag identifiers.
+
+## Block Tags
+
+| Constant | Tag |
+|:--|:--|
+| `BLOCK_MINEABLE_AXE` | `#minecraft:mineable/axe` |
+| `BLOCK_MINEABLE_HOE` | `#minecraft:mineable/hoe` |
+| `BLOCK_MINEABLE_PICKAXE` | `#minecraft:mineable/pickaxe` |
+| `BLOCK_MINEABLE_SHOVEL` | `#minecraft:mineable/shovel` |
+| `BLOCK_LOGS` | `#minecraft:logs` |
+| `BLOCK_LOGS_THAT_BURN` | `#minecraft:logs_that_burn` |
+| `BLOCK_LEAVES` | `#minecraft:leaves` |
+| `BLOCK_PLANKS` | `#minecraft:planks` |
+| `BLOCK_SLABS` | `#minecraft:slabs` |
+| `BLOCK_STAIRS` | `#minecraft:stairs` |
+| `BLOCK_DOORS` | `#minecraft:doors` |
+| `BLOCK_TRAPDOORS` | `#minecraft:trapdoors` |
+| `BLOCK_FENCES` | `#minecraft:fences` |
+| `BLOCK_FENCE_GATES` | `#minecraft:fence_gates` |
+| `BLOCK_WALLS` | `#minecraft:walls` |
+| `BLOCK_BUTTONS` | `#minecraft:buttons` |
+| `BLOCK_PRESSURE_PLATES` | `#minecraft:pressure_plates` |
+| `BLOCK_RAILS` | `#minecraft:rails` |
+| `BLOCK_BEDS` | `#minecraft:beds` |
+| `BLOCK_SIGNS` | `#minecraft:signs` |
+| `BLOCK_CROPS` | `#minecraft:crops` |
+| `BLOCK_SAPLINGS` | `#minecraft:saplings` |
+| `BLOCK_FLOWERS` | `#minecraft:flowers` |
+| `BLOCK_FIRE` | `#minecraft:fire` |
+| `BLOCK_ICE` | `#minecraft:ice` |
+| `BLOCK_SNOW` | `#minecraft:snow` |
+| `BLOCK_SAND` | `#minecraft:sand` |
+| `BLOCK_DIRT` | `#minecraft:dirt` |
+| `BLOCK_WOOL` | `#minecraft:wool` |
+| `BLOCK_WOOL_CARPETS` | `#minecraft:wool_carpets` |
+| `BLOCK_CANDLES` | `#minecraft:candles` |
+| `BLOCK_CAMPFIRES` | `#minecraft:campfires` |
+| `BLOCK_CAULDRONS` | `#minecraft:cauldrons` |
+| `BLOCK_SHULKER_BOXES` | `#minecraft:shulker_boxes` |
+| `BLOCK_DRAGON_IMMUNE` | `#minecraft:dragon_immune` |
+| `BLOCK_WITHER_IMMUNE` | `#minecraft:wither_immune` |
+
+See source file for the full list of ~100+ block tag constants.
+
+## Entity Type Tags
+
+| Constant | Tag |
+|:--|:--|
+| `ENTITY_ARROWS` | `#minecraft:arrows` |
+| `ENTITY_RAIDERS` | `#minecraft:raiders` |
+| `ENTITY_SKELETONS` | `#minecraft:skeletons` |
+| `ENTITY_FALL_DAMAGE_IMMUNE` | `#minecraft:fall_damage_immune` |
+| `ENTITY_IMPACT_PROJECTILES` | `#minecraft:impact_projectiles` |
+
+## Item Tags
+
+| Constant | Tag |
+|:--|:--|
+| `ITEM_SWORDS` | `#minecraft:swords` |
+| `ITEM_AXES` | `#minecraft:axes` |
+| `ITEM_PICKAXES` | `#minecraft:pickaxes` |
+| `ITEM_SHOVELS` | `#minecraft:shovels` |
+| `ITEM_HOES` | `#minecraft:hoes` |
+| `ITEM_TOOLS` | `#minecraft:tools` |
+| `ITEM_ARROWS` | `#minecraft:arrows` |
+| `ITEM_BEDS` | `#minecraft:beds` |
+| `ITEM_BOATS` | `#minecraft:boats` |
+| `ITEM_LOGS` | `#minecraft:logs` |
+| `ITEM_PLANKS` | `#minecraft:planks` |
+| `ITEM_WOOL` | `#minecraft:wool` |
+| `ITEM_MUSIC_DISCS` | `#minecraft:music_discs` |
+| `ITEM_COALS` | `#minecraft:coals` |
+| `ITEM_COMPASSES` | `#minecraft:compasses` |
+| `ITEM_PIGLIN_LOVED` | `#minecraft:piglin_loved` |
+| `ITEM_TRIM_MATERIALS` | `#minecraft:trim_materials` |
+| `ITEM_TRIMMABLE_ARMOR` | `#minecraft:trimmable_armor` |
+
+See source file for the full list of 70+ item tag constants.
+
+## Fluid Tags
+
+| Constant | Tag |
+|:--|:--|
+| `FLUID_LAVA` | `#minecraft:lava` |
+| `FLUID_WATER` | `#minecraft:water` |
+
+## Damage Type Tags
+
+| Constant | Tag |
+|:--|:--|
+| `DAMAGE_BYPASSES_ARMOR` | `#minecraft:bypasses_armor` |
+| `DAMAGE_BYPASSES_INVULNERABILITY` | `#minecraft:bypasses_invulnerability` |
+| `DAMAGE_IS_FIRE` | `#minecraft:is_fire` |
+| `DAMAGE_IS_FALL` | `#minecraft:is_fall` |
+| `DAMAGE_IS_EXPLOSION` | `#minecraft:is_explosion` |
+| `DAMAGE_IS_PROJECTILE` | `#minecraft:is_projectile` |
+| `DAMAGE_IS_DROWNING` | `#minecraft:is_drowning` |
+| `DAMAGE_IS_LIGHTNING` | `#minecraft:is_lightning` |
+| `DAMAGE_NO_KNOCKBACK` | `#minecraft:no_knockback` |
+
+See source file for the full list of 25+ damage type constants.
+
+## Example
+
+```rs
+import tags;
+
+fn setup() {
+    // Check if block is mineable with a pickaxe
+    raw("execute if block ~ ~ ~ " + BLOCK_MINEABLE_PICKAXE + " run ...");
+}
+```