redscript-mc 2.5.0 → 2.6.2

package/docs/stdlib/mobs.md

@@ -0,0 +1,131 @@
+# `mobs` — Mob type constants
+
+Import: `import mobs;`
+
+Vanilla Minecraft Java Edition entity type string constants. Import and use these instead of raw string literals to avoid typos. Covers hostile mobs, passive mobs, neutral mobs, bosses, and special/misc entities.
+
+## Constants
+
+### Hostile mobs
+
+| Constant | Value |
+|:--|:--|
+| `ZOMBIE` | `"minecraft:zombie"` |
+| `SKELETON` | `"minecraft:skeleton"` |
+| `CREEPER` | `"minecraft:creeper"` |
+| `SPIDER` | `"minecraft:spider"` |
+| `CAVE_SPIDER` | `"minecraft:cave_spider"` |
+| `ENDERMAN` | `"minecraft:enderman"` |
+| `WITCH` | `"minecraft:witch"` |
+| `PHANTOM` | `"minecraft:phantom"` |
+| `DROWNED` | `"minecraft:drowned"` |
+| `HUSK` | `"minecraft:husk"` |
+| `STRAY` | `"minecraft:stray"` |
+| `WARDEN` | `"minecraft:warden"` |
+| `PILLAGER` | `"minecraft:pillager"` |
+| `RAVAGER` | `"minecraft:ravager"` |
+| `VINDICATOR` | `"minecraft:vindicator"` |
+| `EVOKER` | `"minecraft:evoker"` |
+| `VEXE` | `"minecraft:vex"` |
+| `ZOMBIE_VILLAGER` | `"minecraft:zombie_villager"` |
+| `BLAZE` | `"minecraft:blaze"` |
+| `GHAST` | `"minecraft:ghast"` |
+| `MAGMA_CUBE` | `"minecraft:magma_cube"` |
+| `SLIME` | `"minecraft:slime"` |
+| `PIGLIN_BRUTE` | `"minecraft:piglin_brute"` |
+| `HOGLIN` | `"minecraft:hoglin"` |
+| `ZOGLIN` | `"minecraft:zoglin"` |
+| `ENDERMITE` | `"minecraft:endermite"` |
+| `SILVERFISH` | `"minecraft:silverfish"` |
+| `SHULKER` | `"minecraft:shulker"` |
+| `GUARDIAN` | `"minecraft:guardian"` |
+| `ELDER_GUARDIAN` | `"minecraft:elder_guardian"` |
+| `BOGGED` | `"minecraft:bogged"` |
+| `BREEZE` | `"minecraft:breeze"` |
+
+### Passive mobs
+
+| Constant | Value |
+|:--|:--|
+| `PIG` | `"minecraft:pig"` |
+| `COW` | `"minecraft:cow"` |
+| `SHEEP` | `"minecraft:sheep"` |
+| `CHICKEN` | `"minecraft:chicken"` |
+| `HORSE` | `"minecraft:horse"` |
+| `DONKEY` | `"minecraft:donkey"` |
+| `MULE` | `"minecraft:mule"` |
+| `RABBIT` | `"minecraft:rabbit"` |
+| `COD` | `"minecraft:cod"` |
+| `SALMON` | `"minecraft:salmon"` |
+| `TROPICAL_FISH` | `"minecraft:tropical_fish"` |
+| `PUFFERFISH` | `"minecraft:pufferfish"` |
+| `SQUID` | `"minecraft:squid"` |
+| `GLOW_SQUID` | `"minecraft:glow_squid"` |
+| `BAT` | `"minecraft:bat"` |
+| `VILLAGER` | `"minecraft:villager"` |
+| `WANDERING_TRADER` | `"minecraft:wandering_trader"` |
+| `SNOW_GOLEM` | `"minecraft:snow_golem"` |
+| `STRIDER` | `"minecraft:strider"` |
+| `AXOLOTL` | `"minecraft:axolotl"` |
+| `FROG` | `"minecraft:frog"` |
+| `TADPOLE` | `"minecraft:tadpole"` |
+| `ALLAY` | `"minecraft:allay"` |
+| `SNIFFER` | `"minecraft:sniffer"` |
+| `ARMADILLO` | `"minecraft:armadillo"` |
+| `TURTLE` | `"minecraft:turtle"` |
+
+### Neutral mobs
+
+| Constant | Value |
+|:--|:--|
+| `WOLF` | `"minecraft:wolf"` |
+| `BEE` | `"minecraft:bee"` |
+| `POLAR_BEAR` | `"minecraft:polar_bear"` |
+| `DOLPHIN` | `"minecraft:dolphin"` |
+| `IRON_GOLEM` | `"minecraft:iron_golem"` |
+| `PIGLIN` | `"minecraft:piglin"` |
+| `ZOMBIFIED_PIGLIN` | `"minecraft:zombified_piglin"` |
+| `PANDA` | `"minecraft:panda"` |
+| `LLAMA` | `"minecraft:llama"` |
+| `TRADER_LLAMA` | `"minecraft:trader_llama"` |
+| `CAT` | `"minecraft:cat"` |
+| `OCELOT` | `"minecraft:ocelot"` |
+| `FOX` | `"minecraft:fox"` |
+| `GOAT` | `"minecraft:goat"` |
+| `CAMEL` | `"minecraft:camel"` |
+
+### Bosses
+
+| Constant | Value |
+|:--|:--|
+| `ENDER_DRAGON` | `"minecraft:ender_dragon"` |
+| `WITHER` | `"minecraft:wither"` |
+
+### Special / misc
+
+| Constant | Value |
+|:--|:--|
+| `ARMOR_STAND` | `"minecraft:armor_stand"` |
+| `ITEM_FRAME` | `"minecraft:item_frame"` |
+| `GLOW_ITEM_FRAME` | `"minecraft:glow_item_frame"` |
+| `PAINTING` | `"minecraft:painting"` |
+| `BOAT` | `"minecraft:boat"` |
+| `MINECART` | `"minecraft:minecart"` |
+| `TNT` | `"minecraft:tnt"` |
+| `FALLING_BLOCK` | `"minecraft:falling_block"` |
+| `ITEM` | `"minecraft:item"` |
+| `XP_ORB` | `"minecraft:experience_orb"` |
+| `FIREBALL` | `"minecraft:fireball"` |
+| `PLAYER` | `"minecraft:player"` |
+
+## Example
+
+```rs
+import mobs;
+
+fn spawn_wave() {
+    summon(ZOMBIE, "~", "~", "~");
+    summon(SKELETON, "~5", "~", "~");
+    summon(CREEPER, "~-5", "~", "~");
+}
+```

package/docs/stdlib/noise.md

@@ -0,0 +1,103 @@
+# `noise` — Procedural noise
+
+Import: `import noise;`
+
+Procedural noise functions using fixed-point arithmetic (×10000 scale) with no external dependencies. Provides 1D and 2D integer hash functions, smooth value noise (bilinear interpolation with smoothstep), fractal Brownian motion (octave stacking), and a terrain height convenience function. Requires `math` for `lerp`, `abs`, `clamp`.
+
+## Functions
+
+### `hash_1d(x: int): int`
+
+Pseudo-random integer from a 1D coordinate. Returns any int (use `%` to restrict range).
+
+**Example:**
+```rs
+import noise;
+let h: int = hash_1d(42);
+```
+
+---
+
+### `hash_2d(x: int, z: int): int`
+
+Pseudo-random integer from 2D coordinates.
+
+---
+
+### `hash_1d_pos(x: int): int`
+
+Hash in `[0, 10000]` from 1D coordinate.
+
+---
+
+### `hash_2d_pos(x: int, z: int): int`
+
+Hash in `[0, 10000]` from 2D coordinates.
+
+---
+
+### `value_noise_1d(x_fx: int): int`
+
+> **Cost:** O(1) — 2 hash lookups + smoothstep interpolation
+
+Smooth 1D value noise at position `x_fx` (fixed-point ×10000). Returns value in `[0, 10000]`. Uses linear interpolation with smoothstep for C1 continuity.
+
+**Example:**
+```rs
+import noise;
+let n: int = value_noise_1d(15000);  // position 1.5 → smooth value in [0, 10000]
+```
+
+---
+
+### `value_noise_2d(x_fx: int, z_fx: int): int`
+
+> **Cost:** O(1) — 4 hash lookups + bilinear interpolation
+
+Smooth 2D value noise. Returns value in `[0, 10000]`. Bilinear interpolation of 4 corner hash values with smoothstep weights.
+
+**Example:**
+```rs
+import noise;
+let n: int = value_noise_2d(10000, 20000);  // at (1.0, 2.0)
+```
+
+---
+
+### `fbm_1d(x_fx: int, octaves: int, persistence_fx: int): int`
+
+> **Cost:** O(octaves) — one value_noise_1d call per octave
+
+Fractal Brownian Motion in 1D. Stacks `octaves` noise layers with amplitude decaying by `persistence_fx ×10000` per octave (typical: 5000 = 0.5). Returns normalised value in `[0, 10000]`.
+
+**Example:**
+```rs
+import noise;
+let n: int = fbm_1d(10000, 4, 5000);  // 4 octaves, 0.5 persistence
+```
+
+---
+
+### `fbm_2d(x_fx: int, z_fx: int, octaves: int, persistence_fx: int): int`
+
+> **Cost:** O(octaves)
+
+Fractal Brownian Motion in 2D. Returns normalised value in `[0, 10000]`.
+
+**Example:**
+```rs
+import noise;
+let n: int = fbm_2d(10000, 30000, 3, 5000);
+```
+
+---
+
+### `terrain_height(x: int, z: int, base_y: int, amplitude: int): int`
+
+Generate terrain height at block coordinate `(x, z)` using 3-octave 2D fbm with persistence 0.5. Returns `base_y + noise × amplitude` in blocks.
+
+**Example:**
+```rs
+import noise;
+let h: int = terrain_height(100, 200, 64, 20);  // height near y=64±20
+```

package/docs/stdlib/parabola.md

@@ -0,0 +1,119 @@
+# `parabola` — Projectile trajectories
+
+Import: `import parabola;`
+
+Projectile motion helpers using Minecraft's native physics model. All positions/velocities ×10000 (blocks × 10000), time in ticks, gravity ≈ 0.08 blocks/tick² (800 in ×10000). Provides ballistic aiming (compute initial velocity to hit a target in N ticks), position at time t, flight time estimation, and per-tick drag physics. Requires `math` for `mulfix`, `isqrt`.
+
+## Functions
+
+### `parabola_gravity(): int`
+
+MC gravity constant per tick ×10000: returns 800 (= 0.08 × 10000).
+
+---
+
+### `parabola_gravity_half(): int`
+
+Half-gravity constant: returns 400.
+
+---
+
+### `parabola_vx(dx: int, ticks: int): int`
+
+Initial X velocity ×10000 to reach horizontal offset `dx` blocks in `ticks` ticks (no drag).
+
+**Example:**
+```rs
+import parabola;
+let vx: int = parabola_vx(10, 20);  // 5000 (0.5 blocks/tick)
+```
+
+---
+
+### `parabola_vy(dy: int, ticks: int): int`
+
+Initial Y velocity ×10000 to reach vertical offset `dy` blocks in `ticks` ticks (compensates for gravity).
+
+**Example:**
+```rs
+import parabola;
+let vy: int = parabola_vy(5, 20);  // upward velocity to reach +5 blocks in 20 ticks
+```
+
+---
+
+### `parabola_vz(dz: int, ticks: int): int`
+
+Initial Z velocity ×10000 to reach `dz` blocks in `ticks` ticks.
+
+---
+
+### `parabola_speed_xz(dx: int, dz: int, ticks: int): int`
+
+Horizontal speed ×10000: `√(vx² + vz²)`. Uses `isqrt`.
+
+---
+
+### `parabola_x(vx0: int, t: int): int`
+
+X position at tick `t` in blocks given initial velocity `vx0 ×10000`.
+
+---
+
+### `parabola_y(vy0: int, t: int): int`
+
+Y position at tick `t` in blocks given initial velocity `vy0 ×10000`. Applies gravity: `vy0×t/10000 - 400×t²/10000`.
+
+---
+
+### `parabola_z(vz0: int, t: int): int`
+
+Z position at tick `t` in blocks given initial velocity `vz0 ×10000`.
+
+---
+
+### `parabola_flight_time(vy0: int): int`
+
+Ticks until the projectile returns to launch height (y=0): `2 × vy0 / 800`. Returns 0 if `vy0 ≤ 0`.
+
+**Example:**
+```rs
+import parabola;
+let t: int = parabola_flight_time(8000);  // 20 ticks
+```
+
+---
+
+### `parabola_max_height(vy0: int): int`
+
+Maximum height above launch point in blocks at the apex.
+
+---
+
+### `parabola_step_vx(vx: int, drag: int): int`
+
+Apply drag to X velocity for one tick: `mulfix(vx, drag)`. `drag` ×10000 (e.g. 9900 for arrows).
+
+---
+
+### `parabola_step_vy(vy: int, drag: int): int`
+
+Apply gravity then drag to Y velocity for one tick: `mulfix(vy - gravity, drag)`.
+
+---
+
+### `parabola_step_vz(vz: int, drag: int): int`
+
+Apply drag to Z velocity for one tick.
+
+---
+
+### `parabola_ticks_for_range(range: int): int`
+
+Estimate ticks to reach a horizontal range. Uses average-speed heuristic: `t ≈ range × 10000 / 8000` (assumes ~0.8 blocks/tick horizontal for arrows). For precise aiming, use `parabola_vx/vy/vz` with desired ticks instead.
+
+---
+
+### `parabola_in_range(dx: int, dz: int, max_range: int): int`
+
+Returns 1 if target is within horizontal range (squared distance check, no sqrt).

package/docs/stdlib/particles.md

@@ -0,0 +1,123 @@
+# `particles` — Particle effect helpers
+
+Import: `import particles;`
+
+Named wrappers for common particle effects at specific positions, plus helpers for drawing 2D/3D particle shapes: lines, circles, and helices. Coordinates in block integers unless noted.
+
+## Functions
+
+### `hearts_at(x: int, y: int, z: int)`
+
+Spawn `heart` particles at block position.
+
+**Example:**
+```rs
+import particles;
+hearts_at(0, 65, 0);
+```
+
+---
+
+### `flames(x: int, y: int, z: int)`
+
+Spawn `flame` particles at position.
+
+---
+
+### `smoke(x: int, y: int, z: int)`
+
+Spawn `large_smoke` particles at position.
+
+---
+
+### `explosion_effect(x: int, y: int, z: int)`
+
+Spawn `explosion` particles at position.
+
+---
+
+### `sparkles_at(x: int, y: int, z: int)`
+
+Spawn `enchant` magic sparkle particles at position.
+
+---
+
+### `angry_at(x: int, y: int, z: int)`
+
+Spawn `angry_villager` particles at position.
+
+---
+
+### `happy_at(x: int, y: int, z: int)`
+
+Spawn `happy_villager` particles at position.
+
+---
+
+### `portal_effect(x: int, y: int, z: int)`
+
+Spawn `portal` particles at position.
+
+---
+
+### `totem_at(x: int, y: int, z: int)`
+
+Spawn `totem_of_undying` particles at position.
+
+---
+
+### `end_sparkles_at(x: int, y: int, z: int)`
+
+Spawn `end_rod` sparkle particles at position.
+
+---
+
+### `particle_at_fx(x_fx: int, y_fx: int, z_fx: int, particle: string)`
+
+Spawn a particle at a fixed-point position (coordinates ×100; 1 block = 100 units). Converts to decimal block coordinates before emitting.
+
+**Example:**
+```rs
+import particles;
+particle_at_fx(150, 6400, 250, "minecraft:flame");  // 1.5, 64.0, 2.5
+```
+
+---
+
+### `draw_line_2d(x0: int, y0: int, x1: int, y1: int, steps: int, z: int, particle: string)`
+
+Draw a straight line from `(x0, y0)` to `(x1, y1)` with `steps` particle samples. All coords ×100.
+
+**Example:**
+```rs
+import particles;
+draw_line_2d(0, 6400, 1000, 6400, 20, 0, "minecraft:flame");  // horizontal line
+```
+
+---
+
+### `draw_circle(cx: int, cy: int, cz: int, r: int, steps: int, particle: string)`
+
+Draw a circle in the XZ plane centred at `(cx, cy, cz)`. `cx`, `cy`, `cz` in blocks; `r` in ×100 units; `steps` particles.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded (uses `sin_fixed`/`cos_fixed`)
+
+**Example:**
+```rs
+import particles;
+draw_circle(0, 65, 0, 500, 36, "minecraft:enchant");  // 5-block radius circle
+```
+
+---
+
+### `draw_helix(cx: int, cy_start: int, cz: int, r: int, height: int, rotations: int, steps: int, particle: string)`
+
+Draw a helix spiral. `r` in ×100 units; `height` in blocks.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+---
+
+### `particle_dot(x: int, y: int, z: int, particle: string)`
+
+Spawn a single particle at integer block coordinates using `raw()`.

package/docs/stdlib/physics.md

@@ -0,0 +1,148 @@
+# `physics` — Velocity, gravity, and collision
+
+Import: `import physics;`
+
+Simple physics simulation for Minecraft datapacks. Fixed-point convention: positions/velocities ×100 (1 block = 100 units), time in ticks (1/20 second), gravity = 8 units/tick² (= 0.08 blocks/tick²). Provides projectile motion, drag, spring physics, circular motion, friction, and impact velocity helpers.
+
+## Functions
+
+### `gravity_fx(): int`
+
+Returns the gravity constant: 8 (= 0.08 blocks/tick² × 100).
+
+---
+
+### `air_drag_fx(): int`
+
+Returns air drag factor: 9800 (= 0.98 × 10000 per tick).
+
+---
+
+### `water_drag_fx(): int`
+
+Returns water drag factor: 8000 (= 0.80 × 10000 per tick).
+
+---
+
+### `projectile_y(p0: int, v0: int, t: int): int`
+
+Y position after `t` ticks. No drag, constant gravity. `p0`, `v0` ×100, `t` in ticks.
+
+**Example:**
+```rs
+import physics;
+let y: int = projectile_y(6400, 100, 10);  // y after 10 ticks
+```
+
+---
+
+### `projectile_x(p0: int, v0: int, t: int): int`
+
+Horizontal position after `t` ticks (no gravity, no drag).
+
+---
+
+### `projectile_vy(v0: int, t: int): int`
+
+Y velocity after `t` ticks of gravity: `v0 - gravity × t`.
+
+---
+
+### `projectile_land_t(v0y: int): int`
+
+Approximate tick when Y returns to 0: `2 × v0y / gravity_fx()`.
+
+---
+
+### `projectile_max_height(v0y: int): int`
+
+Maximum height ×100 reached: `v0y² / (2 × gravity)`.
+
+---
+
+### `apply_drag(v_fx: int, drag_fx: int): int`
+
+Apply drag to a velocity: `v × drag / 10000`.
+
+---
+
+### `apply_gravity(vy_fx: int): int`
+
+Subtract one tick of gravity from Y velocity: `vy - gravity_fx()`.
+
+---
+
+### `update_pos(p_fx: int, v_fx: int): int`
+
+Advance position by one tick: `p + v`.
+
+---
+
+### `bounce_v(v_fx: int, restitution_fx: int): int`
+
+Reflect velocity with energy loss. `restitution_fx ×10000`: 10000 = elastic, 5000 = half energy, 0 = inelastic.
+
+**Example:**
+```rs
+import physics;
+let new_vy: int = bounce_v(-50, 8000);  // 80% energy retained
+```
+
+---
+
+### `clamp_velocity(v_fx: int, max_fx: int): int`
+
+Clamp speed to `[-max_fx, max_fx]`.
+
+---
+
+### `spring_force(pos_fx: int, target_fx: int, k_fx: int): int`
+
+Hooke's law: `F = -k × (pos - target)`. `k_fx ×10000`.
+
+---
+
+### `spring_update_v(v_fx: int, pos_fx: int, target_fx: int, k_fx: int, damping_fx: int): int`
+
+Update velocity with spring force and damping: `v × damping + spring_force`. Both `k_fx` and `damping_fx` ×10000.
+
+**Example:**
+```rs
+import physics;
+// Spring toward target=0, damping=0.8
+let v: int = spring_update_v(50, 200, 0, 5000, 8000);
+```
+
+---
+
+### `circular_x(cx: int, r: int, angle_deg: int): int`
+
+X position on a circle. `cx` ×100, `r` ×100, `angle_deg` in degrees (integer, not ×10000).
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+---
+
+### `circular_z(cz: int, r: int, angle_deg: int): int`
+
+Z position on a circle.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+---
+
+### `friction_decel(v_fx: int, friction_fx: int): int`
+
+Reduce velocity toward zero by `friction_fx ×100` per tick, never overshooting zero.
+
+---
+
+### `is_grounded(y_fx: int, ground_y_fx: int): int`
+
+Returns 1 if `y_fx ≤ ground_y_fx`.
+
+---
+
+### `impact_velocity(h_fx: int): int`
+
+Velocity after falling from height `h_fx ×100`: approximates `√(2 × g × h)`.

package/docs/stdlib/player.md

@@ -0,0 +1,43 @@
+# `player` — Player utilities
+
+Import: `import player;`
+
+Player utility helpers built on scoreboard and tag patterns. All functions operate on the nearest player (`@p`).
+
+## Functions
+
+### `heal(amount: int)`
+
+Add `amount` to the nearest player's `#health` scoreboard value.
+
+**Example:**
+```rs
+import player;
+heal(20);  // restore 20 health
+```
+
+---
+
+### `damage(amount: int)`
+
+Subtract `amount` from the nearest player's `#health` scoreboard value, clamping at 0.
+
+**Example:**
+```rs
+import player;
+damage(10);
+```
+
+---
+
+### `is_op(): int`
+
+Returns 1 if the nearest player has the tag `op`, 0 otherwise.
+
+**Example:**
+```rs
+import player;
+if (is_op() == 1) {
+    give(@p, "minecraft:command_block", 1);
+}
+```