redscript-mc 2.6.2 → 3.0.0

package/src/stdlib/mobs.mcrs

@@ -2,98 +2,185 @@
 // Copy the names you need into your own project until RedScript gets imports.
 
 // Hostile mobs
+/// Entity type ID for zombie.
 const ZOMBIE ="minecraft:zombie"
+/// Entity type ID for skeleton.
 const SKELETON ="minecraft:skeleton"
+/// Entity type ID for creeper.
 const CREEPER ="minecraft:creeper"
+/// Entity type ID for spider.
 const SPIDER ="minecraft:spider"
+/// Entity type ID for cave spider.
 const CAVE_SPIDER ="minecraft:cave_spider"
+/// Entity type ID for enderman.
 const ENDERMAN ="minecraft:enderman"
+/// Entity type ID for witch.
 const WITCH ="minecraft:witch"
+/// Entity type ID for phantom.
 const PHANTOM ="minecraft:phantom"
+/// Entity type ID for drowned.
 const DROWNED ="minecraft:drowned"
+/// Entity type ID for husk.
 const HUSK ="minecraft:husk"
+/// Entity type ID for stray.
 const STRAY ="minecraft:stray"
+/// Entity type ID for warden.
 const WARDEN ="minecraft:warden"
+/// Entity type ID for pillager.
 const PILLAGER ="minecraft:pillager"
+/// Entity type ID for ravager.
 const RAVAGER ="minecraft:ravager"
+/// Entity type ID for vindicator.
 const VINDICATOR ="minecraft:vindicator"
+/// Entity type ID for evoker.
 const EVOKER ="minecraft:evoker"
+/// Entity type ID for vex.
 const VEXE ="minecraft:vex"
+/// Entity type ID for zombie villager.
 const ZOMBIE_VILLAGER ="minecraft:zombie_villager"
+/// Entity type ID for blaze.
 const BLAZE ="minecraft:blaze"
+/// Entity type ID for ghast.
 const GHAST ="minecraft:ghast"
+/// Entity type ID for magma cube.
 const MAGMA_CUBE ="minecraft:magma_cube"
+/// Entity type ID for slime.
 const SLIME ="minecraft:slime"
+/// Entity type ID for piglin brute.
 const PIGLIN_BRUTE ="minecraft:piglin_brute"
+/// Entity type ID for hoglin.
 const HOGLIN ="minecraft:hoglin"
+/// Entity type ID for zoglin.
 const ZOGLIN ="minecraft:zoglin"
+/// Entity type ID for endermite.
 const ENDERMITE ="minecraft:endermite"
+/// Entity type ID for silverfish.
 const SILVERFISH ="minecraft:silverfish"
+/// Entity type ID for shulker.
 const SHULKER ="minecraft:shulker"
+/// Entity type ID for guardian.
 const GUARDIAN ="minecraft:guardian"
+/// Entity type ID for elder guardian.
 const ELDER_GUARDIAN ="minecraft:elder_guardian"
+/// Entity type ID for bogged.
 const BOGGED ="minecraft:bogged"
+/// Entity type ID for breeze.
 const BREEZE ="minecraft:breeze"
 
 // Passive mobs
+/// Entity type ID for pig.
 const PIG ="minecraft:pig"
+/// Entity type ID for cow.
 const COW ="minecraft:cow"
+/// Entity type ID for sheep.
 const SHEEP ="minecraft:sheep"
+/// Entity type ID for chicken.
 const CHICKEN ="minecraft:chicken"
+/// Entity type ID for horse.
 const HORSE ="minecraft:horse"
+/// Entity type ID for donkey.
 const DONKEY ="minecraft:donkey"
+/// Entity type ID for mule.
 const MULE ="minecraft:mule"
+/// Entity type ID for rabbit.
 const RABBIT ="minecraft:rabbit"
+/// Entity type ID for cod.
 const COD ="minecraft:cod"
+/// Entity type ID for salmon.
 const SALMON ="minecraft:salmon"
+/// Entity type ID for tropical fish.
 const TROPICAL_FISH ="minecraft:tropical_fish"
+/// Entity type ID for pufferfish.
 const PUFFERFISH ="minecraft:pufferfish"
+/// Entity type ID for squid.
 const SQUID ="minecraft:squid"
+/// Entity type ID for glow squid.
 const GLOW_SQUID ="minecraft:glow_squid"
+/// Entity type ID for bat.
 const BAT ="minecraft:bat"
+/// Entity type ID for villager.
 const VILLAGER ="minecraft:villager"
+/// Entity type ID for wandering trader.
 const WANDERING_TRADER ="minecraft:wandering_trader"
+/// Entity type ID for snow golem.
 const SNOW_GOLEM ="minecraft:snow_golem"
+/// Entity type ID for strider.
 const STRIDER ="minecraft:strider"
+/// Entity type ID for axolotl.
 const AXOLOTL ="minecraft:axolotl"
+/// Entity type ID for frog.
 const FROG ="minecraft:frog"
+/// Entity type ID for tadpole.
 const TADPOLE ="minecraft:tadpole"
+/// Entity type ID for allay.
 const ALLAY ="minecraft:allay"
+/// Entity type ID for sniffer.
 const SNIFFER ="minecraft:sniffer"
+/// Entity type ID for armadillo.
 const ARMADILLO ="minecraft:armadillo"
+/// Entity type ID for turtle.
 const TURTLE ="minecraft:turtle"
 
 // Neutral mobs
+/// Entity type ID for wolf.
 const WOLF ="minecraft:wolf"
+/// Entity type ID for bee.
 const BEE ="minecraft:bee"
+/// Entity type ID for polar bear.
 const POLAR_BEAR ="minecraft:polar_bear"
+/// Entity type ID for dolphin.
 const DOLPHIN ="minecraft:dolphin"
+/// Entity type ID for iron golem.
 const IRON_GOLEM ="minecraft:iron_golem"
+/// Entity type ID for piglin.
 const PIGLIN ="minecraft:piglin"
+/// Entity type ID for zombified piglin.
 const ZOMBIFIED_PIGLIN ="minecraft:zombified_piglin"
+/// Entity type ID for panda.
 const PANDA ="minecraft:panda"
+/// Entity type ID for llama.
 const LLAMA ="minecraft:llama"
+/// Entity type ID for trader llama.
 const TRADER_LLAMA ="minecraft:trader_llama"
+/// Entity type ID for cat.
 const CAT ="minecraft:cat"
+/// Entity type ID for ocelot.
 const OCELOT ="minecraft:ocelot"
+/// Entity type ID for fox.
 const FOX ="minecraft:fox"
+/// Entity type ID for goat.
 const GOAT ="minecraft:goat"
+/// Entity type ID for camel.
 const CAMEL ="minecraft:camel"
 
 // Bosses
+/// Entity type ID for ender dragon.
 const ENDER_DRAGON ="minecraft:ender_dragon"
+/// Entity type ID for wither.
 const WITHER ="minecraft:wither"
 
 // Special / misc
+/// Entity type ID for armor stand.
 const ARMOR_STAND ="minecraft:armor_stand"
+/// Entity type ID for item frame.
 const ITEM_FRAME ="minecraft:item_frame"
+/// Entity type ID for glow item frame.
 const GLOW_ITEM_FRAME ="minecraft:glow_item_frame"
+/// Entity type ID for painting.
 const PAINTING ="minecraft:painting"
+/// Entity type ID for boat.
 const BOAT ="minecraft:boat"
+/// Entity type ID for minecart.
 const MINECART ="minecraft:minecart"
+/// Entity type ID for primed TNT.
 const TNT ="minecraft:tnt"
+/// Entity type ID for falling block.
 const FALLING_BLOCK ="minecraft:falling_block"
+/// Entity type ID for dropped item.
 const ITEM ="minecraft:item"
+/// Entity type ID for experience orb.
 const XP_ORB ="minecraft:experience_orb"
+/// Entity type ID for fireball.
 const FIREBALL ="minecraft:fireball"
+/// Entity type ID for player.
 const PLAYER ="minecraft:player"

package/src/stdlib/noise.mcrs

@@ -15,8 +15,12 @@ module library;
 
 // ─── Hash functions ───────────────────────────────────────────────────────────
 
-// hash_1d(x): pseudo-random int from a 1D coordinate
-// Returns any int (use % to restrict range)
+/// Generate a pseudo-random integer from a 1D integer coordinate.
+/// @since 1.0.0
+/// @param x  Input coordinate (any integer)
+/// @returns  Pseudo-random integer (any value; use % to restrict range)
+/// @example
+/// let h: int = hash_1d(42)  // deterministic hash of coordinate 42
 fn hash_1d(x: int): int {
     let h: int = x * 374761393;
     h = h + 1013904223;
@@ -25,19 +29,36 @@ fn hash_1d(x: int): int {
     return h;
 }
 
-// hash_2d(x, z): pseudo-random int from 2D coordinates
+/// Generate a pseudo-random integer from a 2D integer coordinate pair.
+/// @since 1.0.0
+/// @param x  First coordinate (any integer)
+/// @param z  Second coordinate (any integer)
+/// @returns  Pseudo-random integer combining both inputs deterministically
+/// @example
+/// let h: int = hash_2d(10, 20)  // deterministic hash of (10, 20)
 fn hash_2d(x: int, z: int): int {
     return hash_1d(x + hash_1d(z));
 }
 
-// hash_1d_pos(x): hash in [0, 10000]
+/// Generate a non-negative hash in [0, 10000] from a 1D coordinate.
+/// @since 1.0.0
+/// @param x  Input coordinate
+/// @returns  Integer in [0, 10000]
+/// @example
+/// let v: int = hash_1d_pos(5)  // value between 0 and 10000
 fn hash_1d_pos(x: int): int {
     let h: int = hash_1d(x);
     if (h < 0) { h = 0 - h; }
     return h % 10001;
 }
 
-// hash_2d_pos(x, z): hash in [0, 10000]
+/// Generate a non-negative hash in [0, 10000] from a 2D coordinate pair.
+/// @since 1.0.0
+/// @param x  First coordinate
+/// @param z  Second coordinate
+/// @returns  Integer in [0, 10000]
+/// @example
+/// let v: int = hash_2d_pos(3, 7)  // value between 0 and 10000
 fn hash_2d_pos(x: int, z: int): int {
     let h: int = hash_2d(x, z);
     if (h < 0) { h = 0 - h; }
@@ -46,9 +67,12 @@ fn hash_2d_pos(x: int, z: int): int {
 
 // ─── Value noise ─────────────────────────────────────────────────────────────
 
-// value_noise_1d(x_fx): smooth 1D noise at position x_fx (fixed-point ×10000)
-// Returns value in [0, 10000]
-// Uses linear interpolation between random values at integer coords
+/// Smooth 1D value noise at a fixed-point position.
+/// @since 1.0.0
+/// @param x_fx  Position ×10000 (e.g. 10000 = coordinate 1.0)
+/// @returns  Noise value in [0, 10000] with smooth interpolation between integer coords
+/// @example
+/// let n: int = value_noise_1d(15000)  // smooth noise at x=1.5
 fn value_noise_1d(x_fx: int): int {
     let xi: int = x_fx / 10000;   // integer part
     let xf: int = x_fx % 10000;   // fractional part [0, 9999]
@@ -62,8 +86,13 @@ fn value_noise_1d(x_fx: int): int {
     return v0 + (v1 - v0) * t / 10000;
 }
 
-// value_noise_2d(x_fx, z_fx): smooth 2D noise
-// Returns value in [0, 10000]
+/// Smooth 2D value noise at a fixed-point position.
+/// @since 1.0.0
+/// @param x_fx  X position ×10000
+/// @param z_fx  Z position ×10000
+/// @returns  Noise value in [0, 10000] with bilinear smooth interpolation
+/// @example
+/// let n: int = value_noise_2d(15000, 23000)  // noise at (1.5, 2.3)
 fn value_noise_2d(x_fx: int, z_fx: int): int {
     let xi: int = x_fx / 10000;
     let xf: int = x_fx % 10000;
@@ -91,11 +120,14 @@ fn value_noise_2d(x_fx: int, z_fx: int): int {
 
 // ─── Fractal Brownian Motion ──────────────────────────────────────────────────
 
-// fbm_1d(x_fx, octaves, persistence_fx):
-//   x_fx: position ×10000
-//   octaves: number of noise layers (1-6, more = more detail)
-//   persistence_fx: amplitude decay per octave ×10000 (typical: 5000 = 0.5)
-// Returns value in approximately [0, 10000]
+/// 1D Fractal Brownian Motion — stacks multiple octaves of value noise.
+/// @since 1.0.0
+/// @param x_fx           Position ×10000
+/// @param octaves        Number of noise layers (1–6; more = more detail but slower)
+/// @param persistence_fx Amplitude decay per octave ×10000 (5000 = 0.5 recommended)
+/// @returns  Normalized noise value in approximately [0, 10000]
+/// @example
+/// let h: int = fbm_1d(50000, 4, 5000)  // 4 octave noise at x=5.0
 fn fbm_1d(x_fx: int, octaves: int, persistence_fx: int): int {
     let value: int = 0;
     let amplitude: int = 10000;
@@ -117,7 +149,15 @@ fn fbm_1d(x_fx: int, octaves: int, persistence_fx: int): int {
     return value * 10000 / max_val;
 }
 
-// fbm_2d(x_fx, z_fx, octaves, persistence_fx): 2D fractal Brownian motion
+/// 2D Fractal Brownian Motion — stacks multiple octaves of 2D value noise.
+/// @since 1.0.0
+/// @param x_fx           X position ×10000
+/// @param z_fx           Z position ×10000
+/// @param octaves        Number of noise layers (1–6)
+/// @param persistence_fx Amplitude decay per octave ×10000 (5000 = 0.5)
+/// @returns  Normalized noise value in approximately [0, 10000]
+/// @example
+/// let h: int = fbm_2d(30000, 50000, 3, 5000)  // 3 octave 2D noise
 fn fbm_2d(x_fx: int, z_fx: int, octaves: int, persistence_fx: int): int {
     let value: int = 0;
     let amplitude: int = 10000;
@@ -141,11 +181,15 @@ fn fbm_2d(x_fx: int, z_fx: int, octaves: int, persistence_fx: int): int {
 
 // ─── Convenience: terrain height ─────────────────────────────────────────────
 
-// terrain_height(x, z, base_y, amplitude):
-//   Generates a terrain height using 3-octave fbm.
-//   x, z: block coordinates (integers, NOT fixed-point)
-//   base_y: baseline height in blocks
-//   amplitude: max height variation in blocks
+/// Generate a terrain height using 3-octave FBM noise.
+/// @since 1.0.0
+/// @param x          Block X coordinate (integer, not fixed-point)
+/// @param z          Block Z coordinate (integer, not fixed-point)
+/// @param base_y     Baseline height in blocks
+/// @param amplitude  Maximum height variation above/below base_y in blocks
+/// @returns  Block height at (x, z): base_y + noise * amplitude / 10000
+/// @example
+/// let h: int = terrain_height(100, 200, 64, 16)  // terrain at (100, 200) near y=64
 fn terrain_height(x: int, z: int, base_y: int, amplitude: int): int {
     // Scale x,z by ×10000 for fixed-point, divide by 4 for wider features
     let noise: int = fbm_2d(x * 2500, z * 2500, 3, 5000);

package/src/stdlib/ode.mcrs

@@ -21,10 +21,24 @@
 
 module library
 
+/// Fixed-point multiplication: `a_fx * b_fx / 10000`.
+///
+/// @since 2.0.0
+/// @param a_fx  First operand ×10000
+/// @param b_fx  Second operand ×10000
+/// @returns     Product in ×10000 scale
 fn ode_mul_fx(a_fx: int, b_fx: int): int {
     return a_fx * b_fx / 10000
 }
 
+/// Compute the RK4 weighted increment: `h * (k1 + 2k2 + 2k3 + k4) / 6`.
+///
+/// All values are ×10000. The divisor 60000 = 6 × 10000.
+///
+/// @since 2.0.0
+/// @param h_fx          Step size ×10000
+/// @param deriv_sum_fx  `k1 + 2k2 + 2k3 + k4` in ×10000
+/// @returns             Weighted increment in ×10000
 fn ode_weighted_increment(h_fx: int, deriv_sum_fx: int): int {
     return h_fx * deriv_sum_fx / 60000
 }
@@ -47,6 +61,17 @@ fn _ode_get_slot5(): int { raw("execute store result score $ret __OBJ__ run data
 fn _ode_get_slot6(): int { raw("execute store result score $ret __OBJ__ run data get storage rs:ode state[6]"); raw("return 1"); return 0 }
 fn _ode_get_slot7(): int { raw("execute store result score $ret __OBJ__ run data get storage rs:ode state[7]"); raw("return 1"); return 0 }
 
+/// Initialise the ODE module state in `storage rs:ode`.
+///
+/// @since 2.0.0
+/// @param system_id  Built-in system constant (1=decay, 2=growth, 3=oscillator)
+/// @param t_fx       Initial time ×10000
+/// @param y_fx       Initial primary variable y(0) ×10000
+/// @param y2_fx      Initial secondary variable y'(0) ×10000 (for system 3)
+/// @param k_fx       Rate/spring constant ×10000
+/// @param extra_fx   Damping coefficient ×10000 (for system 3)
+/// @example
+/// ode_reset(1, 0, 10000, 0, 10000, 0)
 fn ode_reset(system_id: int, t_fx: int, y_fx: int, y2_fx: int, k_fx: int, extra_fx: int) {
     raw("data modify storage rs:ode state set value [0,0,0,0,0,0,0,0]")
     _ode_set_slot0(system_id)
@@ -59,12 +84,46 @@ fn ode_reset(system_id: int, t_fx: int, y_fx: int, y2_fx: int, k_fx: int, extra_
     _ode_set_slot7(0)
 }
 
+/// Return the current system ID from ODE state.
+///
+/// @since 2.0.0
+/// @returns  System ID stored in slot 0
 fn ode_get_system(): int { return _ode_get_slot0() }
+
+/// Return the current time `t` from ODE state (×10000).
+///
+/// @since 2.0.0
+/// @returns  Current time ×10000
 fn ode_get_t(): int { return _ode_get_slot1() }
+
+/// Return the current primary variable `y` from ODE state (×10000).
+///
+/// @since 2.0.0
+/// @returns  Current y value ×10000
 fn ode_get_y(): int { return _ode_get_slot2() }
+
+/// Return the current secondary variable `y'` from ODE state (×10000).
+///
+/// @since 2.0.0
+/// @returns  Current y' value ×10000 (meaningful for system 3 only)
 fn ode_get_y2(): int { return _ode_get_slot3() }
+
+/// Return the rate constant `k` from ODE state (×10000).
+///
+/// @since 2.0.0
+/// @returns  Rate constant ×10000
 fn ode_get_k(): int { return _ode_get_slot4() }
+
+/// Return the extra parameter from ODE state (×10000).
+///
+/// @since 2.0.0
+/// @returns  Extra parameter ×10000 (damping for system 3)
 fn ode_get_extra(): int { return _ode_get_slot5() }
+
+/// Return the number of steps taken so far.
+///
+/// @since 2.0.0
+/// @returns  Step count (plain integer)
 fn ode_get_steps(): int { return _ode_get_slot6() }
 
 // Scalar-system dispatcher helper matching the callback-free pattern.
@@ -100,6 +159,13 @@ fn ode_eval_y2(system_id: int, t_fx: int, y_fx: int, y2_fx: int, k_fx: int, extr
     return 0
 }
 
+/// Advance the ODE state by one RK4 step of size `h_fx`.
+///
+/// Updates time `t`, primary variable `y` (and `y2` for system 3), and
+/// increments the step counter in `storage rs:ode`.
+///
+/// @since 2.0.0
+/// @param h_fx  Step size ×10000 (e.g. `1000` = 0.1 time unit)
 fn ode_step(h_fx: int) {
     let system_id: int = ode_get_system()
     let t_fx: int = ode_get_t()
@@ -149,6 +215,21 @@ fn ode_step(h_fx: int) {
     _ode_set_slot6(step_count + 1)
 }
 
+/// Run `steps` RK4 steps of a scalar ODE system and store results in module state.
+///
+/// Built-in systems: `1` = exponential decay (`dy/dt = -k·y`),
+/// `2` = exponential growth (`dy/dt = k·y`).
+///
+/// @since 2.0.0
+/// @param system_id  Built-in system constant (1 or 2 for scalar systems)
+/// @param t0_fx      Initial time ×10000
+/// @param y0_fx      Initial y value ×10000
+/// @param h_fx       Step size ×10000
+/// @param steps      Number of RK4 steps to execute
+/// @param k_fx       Rate constant ×10000
+/// @example
+/// ode_run(1, 0, 10000, 1000, 10, 10000)
+/// let y: int = ode_get_y()
 fn ode_run(system_id: int, t0_fx: int, y0_fx: int, h_fx: int, steps: int, k_fx: int) {
     ode_reset(system_id, t0_fx, y0_fx, 0, k_fx, 0)
     let i: int = 0
@@ -158,6 +239,21 @@ fn ode_run(system_id: int, t0_fx: int, y0_fx: int, h_fx: int, steps: int, k_fx:
     }
 }
 
+/// Run `steps` RK4 steps of a 2D ODE system (e.g. harmonic oscillator).
+///
+/// Built-in system 3: `y' = y2`, `y2' = -k·y - extra·y2`.
+///
+/// @since 2.0.0
+/// @param system_id  Built-in system constant (use `3` for harmonic oscillator)
+/// @param t0_fx      Initial time ×10000
+/// @param y0_fx      Initial y value ×10000
+/// @param y20_fx     Initial y' value ×10000
+/// @param h_fx       Step size ×10000
+/// @param steps      Number of RK4 steps to execute
+/// @param k_fx       Spring constant ×10000
+/// @param extra_fx   Damping coefficient ×10000
+/// @example
+/// ode_run2(3, 0, 10000, 0, 1000, 20, 10000, 500)
 fn ode_run2(system_id: int, t0_fx: int, y0_fx: int, y20_fx: int, h_fx: int, steps: int, k_fx: int, extra_fx: int) {
     ode_reset(system_id, t0_fx, y0_fx, y20_fx, k_fx, extra_fx)
     let i: int = 0