redscript-mc 2.5.0 → 2.6.0

package/docs/stdlib/expr.md

@@ -0,0 +1,38 @@
+# `expr` — RPN expression evaluator
+
+Import: `import expr;`
+
+A stack-based Reverse Polish Notation (RPN) expression evaluator for dynamic formula evaluation at runtime. All values use ×10000 fixed-point scale. The evaluator supports a variable `x`, arithmetic operators, and common math functions. Useful for configurable easing, game formulas, and computed attributes. Requires `math` for `sin_fixed`, `cos_fixed`, `sqrt_fx`, `abs`.
+
+## Token encoding
+
+| Token value | Meaning |
+|:--|:--|
+| Positive integer | Literal value (×10000) |
+| `-10000` | Variable `x` |
+| `-1` | ADD: pop b, a; push a + b |
+| `-2` | SUB: pop b, a; push a - b |
+| `-3` | MUL: pop b, a; push a × b / 10000 (fixed-point) |
+| `-4` | DIV: pop b, a; push a × 10000 / b (fixed-point) |
+| `-5` | SIN: pop a (degrees ×10000); push sin ×10000 |
+| `-6` | COS: pop a (degrees ×10000); push cos ×10000 |
+| `-7` | SQRT: pop a; push sqrt_fx(a) |
+| `-8` | ABS: pop a; push \|a\| |
+
+The internal stack is 16 elements.
+
+## Functions
+
+### `expr_eval(tokens: int[], n: int, x: int): int`
+
+> **Cost:** O(n) — one pass over n tokens, constant per token
+
+Evaluate `n` RPN tokens, substituting `x` for any `-10000` token. Returns the top-of-stack value (×10000 scale). Behaviour is undefined for malformed token streams (stack underflow/overflow).
+
+**Example:**
+```rs
+import expr;
+// Encode: 2*x + 1  →  [20000, -10000, -3, 10000, -1]
+let tokens: int[] = [20000, -10000, -3, 10000, -1];
+let result: int = expr_eval(tokens, 5, 15000);  // x=1.5 → 40000 (4.0)
+```

package/docs/stdlib/geometry.md

@@ -0,0 +1,130 @@
+# `geometry` — 3D geometry and selection zones
+
+Import: `import geometry;`
+
+3D geometry helpers for Minecraft datapacks: bounding box and sphere containment tests, vertical cylinder and cone checks, 2D fan (sector) selection, parabola helpers, grid/tile math, angle utilities, and sun angle conversion. Fixed-point convention: coordinates ×100 (1 block = 100 units); angles in degrees ×10000. Requires `math` for `sqrt_fx`, `sin_fixed`, `cos_fixed`, `abs`.
+
+## Functions
+
+### `midpoint(a: int, b: int): int`
+
+Integer midpoint of two coordinates: `(a + b) / 2`.
+
+---
+
+### `aabb_contains(px: int, py: int, pz: int, minx: int, miny: int, minz: int, maxx: int, maxy: int, maxz: int): int`
+
+Returns 1 if point `(px, py, pz)` is inside the axis-aligned bounding box, 0 otherwise.
+
+**Example:**
+```rs
+import geometry;
+let inside: int = aabb_contains(50, 64, 50, 0, 60, 0, 100, 80, 100);  // 1
+```
+
+---
+
+### `sphere_contains(px: int, py: int, pz: int, cx: int, cy: int, cz: int, r: int): int`
+
+Returns 1 if point is inside a sphere. Avoids sqrt by comparing squared distances.
+
+**Example:**
+```rs
+import geometry;
+let inside: int = sphere_contains(5, 0, 0, 0, 0, 0, 10);  // 1 (dist=5 < r=10)
+```
+
+---
+
+### `cylinder_contains(px: int, pz: int, cx: int, cz: int, r: int): int`
+
+Returns 1 if `(px, pz)` is inside a vertical cylinder (ignores Y axis). 2D circle check.
+
+**Example:**
+```rs
+import geometry;
+let inside: int = cylinder_contains(3, 4, 0, 0, 10);  // 1
+```
+
+---
+
+### `parabola_y(y0: int, vy0: int, t: int): int`
+
+Y position at tick `t` for a parabolic arc. `y0`: initial Y ×100, `vy0`: initial Y velocity ×100. Gravity: 5 units/tick² (= 0.05 blocks/tick²).
+
+---
+
+### `parabola_x(x0: int, vx0: int, t: int): int`
+
+Horizontal X position at tick `t` (no drag, constant velocity).
+
+---
+
+### `parabola_land_t(vy0: int): int`
+
+Approximate tick when projectile returns to Y=0: `t ≈ 2 × vy0 / 5`.
+
+---
+
+### `tile_of(coord: int, tile_size: int): int`
+
+Which tile a coordinate belongs to (floor division, handles negative coordinates correctly).
+
+---
+
+### `tile_center(tile: int, tile_size: int): int`
+
+Center coordinate of a tile.
+
+---
+
+### `angle_normalize(deg: int): int`
+
+Normalize angle to `[0, 3600000)` (degrees ×10000).
+
+---
+
+### `angle_diff(a: int, b: int): int`
+
+Signed shortest angular difference between two angles (degrees ×10000). Result in `(-1800000, 1800000]`.
+
+---
+
+### `mc_day_angle(daytime: int): int`
+
+Convert MC `/time query daytime` (0–24000) to sun angle ×10000. Tick 0 = dawn (90°), tick 6000 = noon (180°).
+
+---
+
+### `in_cylinder(px: int, py: int, pz: int, cx: int, cz: int, radius: int, y_lo: int, y_hi: int): int`
+
+Returns 1 if `(px, py, pz)` is inside a vertical cylinder centred at `(cx, *, cz)` with the given height bounds. All coordinates ×10000 (1 block = 10000 units).
+
+> **Note:** Radius up to ~46340 (≈4.6 blocks at ×10000 scale) to avoid overflow. For larger radii, divide all coords by 10 first.
+
+**Example:**
+```rs
+import geometry;
+let inside: int = in_cylinder(50000, 64000, 50000, 50000, 50000, 30000, 60000, 70000);
+```
+
+---
+
+### `in_cone(px: int, py: int, pz: int, apex_x: int, apex_y: int, apex_z: int, dir_y: int, half_angle_tan: int, height: int): int`
+
+Returns 1 if point is inside an upright cone (axis along ±Y from apex). `half_angle_tan = tan(half-angle) × 10000` (e.g. 45° → 10000, 30° → 5773). `dir_y > 0` for upward cone, `dir_y < 0` for downward.
+
+---
+
+### `in_sector_2d(px: int, pz: int, cx: int, cz: int, dir_angle: int, half_angle: int, radius: int): int`
+
+Returns 1 if `(px, pz)` is inside a 2D fan (sector) in the XZ plane. `dir_angle` and `half_angle` are ×10000 radians (full circle = 628318). Requires `atan2_fixed` from `vec`.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded (via `@require_on_load(_atan_init)`)
+
+**Example:**
+```rs
+import geometry;
+// Is point in a 90° cone facing east (+X)?
+let inside: int = in_sector_2d(10, 0, 0, 0, 0, 157080, 20);
+```

package/docs/stdlib/interactions.md

@@ -0,0 +1,111 @@
+# `interactions` — Player interaction detection
+
+Import: `import interactions;`
+
+Common patterns for detecting player input: right-click (carrot-on-a-stick), sneak/crouch detection, look direction checks, and combined input combos. Uses scoreboard objectives for tracking. Call `interactions_init()` once in your `@load` function.
+
+## Functions
+
+### `interactions_init()`
+
+Initialize interaction scoreboards. Call once from your `@load` function.
+
+- `rs.click` — `minecraft.used:minecraft.carrot_on_a_stick`
+- `rs.sneak` — `minecraft.custom:minecraft.sneak_time`
+- `rs.attack` — `minecraft.custom:minecraft.damage_dealt`
+
+**Example:**
+```rs
+import interactions;
+
+@load
+fn setup() {
+    interactions_init();
+}
+```
+
+---
+
+### `on_right_click(callback_fn: string)`
+
+Check for right-click (carrot on a stick). Tags players who clicked with `rs.clicked` and resets their click counter. Call from a `@tick` function.
+
+**Example:**
+```rs
+import interactions;
+
+@tick
+fn check_input() {
+    on_right_click("my_action");
+}
+```
+
+---
+
+### `example_right_click()`
+
+Example right-click handler: detects clicks, resets counter, and emits a `say`.
+
+---
+
+### `is_sneaking(target: selector): int`
+
+Returns 1 if the target is currently sneaking (sneak_time > 0), 0 otherwise.
+
+**Example:**
+```rs
+import interactions;
+let sneaking: int = is_sneaking(@s);
+```
+
+---
+
+### `on_sneak_start()`
+
+Detect the first tick of sneaking for all players. Tags players with `rs.sneak_start` when `sneak_time == 1`, removes the tag otherwise. Call from `@tick`.
+
+---
+
+### `check_look_up()`
+
+Tag players looking up (pitch < -45°) with `rs.look_up`. Call from `@tick`.
+
+---
+
+### `check_look_down()`
+
+Tag players looking down (pitch > 45°) with `rs.look_down`. Call from `@tick`.
+
+---
+
+### `check_look_straight()`
+
+Tag players looking straight (pitch between -45° and 45°) with `rs.look_straight`. Call from `@tick`.
+
+---
+
+### `check_holding_item(item_id: string)`
+
+Check if player is holding a specific item. Currently emits a `say` reminder to use predicate files for NBT checks.
+
+---
+
+### `on_sneak_click()`
+
+Detect sneak + right-click combo. Tags players with `rs.sneak_click` for the combo, `rs.clicked` for normal click. Call from `@tick`.
+
+**Example:**
+```rs
+import interactions;
+
+@tick
+fn check_combos() {
+    on_sneak_click();
+}
+```
+
+---
+
+### `on_double_sneak()`
+
+Detect double-tap sneak within a 10-tick window. Tags players with `rs.double_sneak`. Call from `@tick`.

package/docs/stdlib/inventory.md

@@ -0,0 +1,53 @@
+# `inventory` — Inventory management
+
+Import: `import inventory;`
+
+Inventory management helpers for clearing inventories and giving pre-defined item kits to players.
+
+## Functions
+
+### `clear_inventory(target: selector)`
+
+Clear all items from a player's inventory.
+
+**Example:**
+```rs
+import inventory;
+clear_inventory(@a);
+```
+
+---
+
+### `give_kit_warrior(target: selector)`
+
+Give the warrior kit: iron sword, iron chestplate, iron leggings, iron boots, shield, 16× cooked beef.
+
+**Example:**
+```rs
+import inventory;
+give_kit_warrior(@s);
+```
+
+---
+
+### `give_kit_archer(target: selector)`
+
+Give the archer kit: bow, 64× arrows, leather chestplate, leather leggings, leather boots, 16× cooked beef.
+
+---
+
+### `give_kit_mage(target: selector)`
+
+Give the mage kit: wooden sword, 8× golden apple, 16× ender pearl, 8× splash harming potion, 16× cooked beef.
+
+---
+
+### `remove_item(target: selector, item: string)`
+
+Remove a specific item from the player's inventory using `clear`.
+
+**Example:**
+```rs
+import inventory;
+remove_item(@s, "minecraft:poisonous_potato");
+```

package/docs/stdlib/list.md

@@ -0,0 +1,189 @@
+# `list` — Array aggregates and sorting
+
+Import: `import list;`
+
+Array utilities including static min/max/avg/sum helpers for up to 5 values, optimal sorting networks for 2–5 values, weighted random choice, dynamic sorting (bubble sort, ascending/descending) and aggregates (sum, avg, min, max, contains, index_of, shuffle, dedup count) for arbitrary-length arrays.
+
+> **Note:** Dynamic array functions (those taking `arr: int[]`) require RedScript ≥ 2.4.0 (array parameter by reference).
+
+## Functions
+
+### `sort2_min(a: int, b: int): int`
+
+Minimum of two values.
+
+### `sort2_max(a: int, b: int): int`
+
+Maximum of two values.
+
+### `list_min3(a: int, b: int, c: int): int`
+
+Minimum of three values.
+
+### `list_max3(a: int, b: int, c: int): int`
+
+Maximum of three values.
+
+### `list_min5(a: int, b: int, c: int, d: int, e: int): int`
+
+Minimum of five values.
+
+### `list_max5(a: int, b: int, c: int, d: int, e: int): int`
+
+Maximum of five values.
+
+### `list_sum3(a: int, b: int, c: int): int`
+
+Sum of three values.
+
+### `list_sum4(a: int, b: int, c: int, d: int): int`
+
+Sum of four values.
+
+### `list_sum5(a: int, b: int, c: int, d: int, e: int): int`
+
+Sum of five values.
+
+### `avg3(a: int, b: int, c: int): int`
+
+Integer average of three values.
+
+### `avg5(a: int, b: int, c: int, d: int, e: int): int`
+
+Integer average of five values.
+
+---
+
+### `sort3(a: int, b: int, c: int, pos: int): int`
+
+Sort three values, returning the value at sorted position `pos` (0=min, 1=mid, 2=max). Uses a 3-comparison sorting network.
+
+**Example:**
+```rs
+import list;
+let median: int = sort3(30, 10, 20, 1);  // 20
+```
+
+---
+
+### `sort4(a: int, b: int, c: int, d: int, pos: int): int`
+
+Sort four values, returning the value at sorted position `pos` (0=min, 3=max). Uses a 5-comparison optimal sorting network.
+
+---
+
+### `sort5(a: int, b: int, c: int, d: int, e: int, pos: int): int`
+
+Sort five values, returning the value at sorted position `pos`. Uses a 9-comparison sorting network (Batcher odd-even merge).
+
+---
+
+### `weighted2(seed: int, w0: int, w1: int): int`
+
+Choose 0 or 1 with weights `w0`, `w1`. Returns the index selected. Uses LCG from `seed`.
+
+**Example:**
+```rs
+import list;
+let choice: int = weighted2(12345, 70, 30);  // 70% chance of 0, 30% chance of 1
+```
+
+---
+
+### `weighted3(seed: int, w0: int, w1: int, w2: int): int`
+
+Choose 0, 1, or 2 with given weights. Returns the index selected.
+
+---
+
+### `list_sort_asc(arr: int[], len: int)`
+
+> **Cost:** O(n²) — bubble sort
+
+In-place ascending bubble sort of `len` elements.
+
+**Example:**
+```rs
+import list;
+let nums: int[] = [30, 10, 20];
+list_sort_asc(nums, 3);  // [10, 20, 30]
+```
+
+---
+
+### `list_sort_desc(arr: int[], len: int)`
+
+> **Cost:** O(n²) — bubble sort
+
+In-place descending bubble sort of `len` elements.
+
+---
+
+### `list_sum(arr: int[], len: int): int`
+
+> **Cost:** O(n)
+
+Sum of all `len` elements in `arr`.
+
+---
+
+### `list_avg(arr: int[], len: int): int`
+
+> **Cost:** O(n)
+
+Arithmetic mean ×10000 (fixed-point). Returns `(sum × 10000) / len`. Returns 0 for empty array.
+
+---
+
+### `list_min(arr: int[], len: int): int`
+
+> **Cost:** O(n)
+
+Minimum element in `arr`.
+
+---
+
+### `list_max(arr: int[], len: int): int`
+
+> **Cost:** O(n)
+
+Maximum element in `arr`.
+
+---
+
+### `list_contains(arr: int[], len: int, val: int): int`
+
+> **Cost:** O(n)
+
+Returns 1 if `val` is in `arr`, 0 otherwise.
+
+---
+
+### `list_index_of(arr: int[], len: int, val: int): int`
+
+> **Cost:** O(n)
+
+First index of `val` in `arr`, or -1 if not found.
+
+---
+
+### `list_shuffle(arr: int[], len: int, seed: int): int[]`
+
+> **Cost:** O(n)
+
+Fisher-Yates shuffle in-place using LCG RNG. Returns `arr`. Uses `next_lcg` from `random`.
+
+**Example:**
+```rs
+import list;
+let deck: int[] = [1, 2, 3, 4, 5];
+list_shuffle(deck, 5, 99999);
+```
+
+---
+
+### `list_dedup_count(arr: int[], len: int): int`
+
+> **Cost:** O(n²) — suitable for small arrays
+
+Count of unique values in `arr`.