redscript-mc 2.6.2 → 3.0.0

package/src/stdlib/parabola.mcrs

@@ -20,10 +20,16 @@ module library;
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
-// GRAVITY: MC gravity per tick ×10000 (≈ 0.08 * 10000 = 800)
+/// Minecraft gravity per tick in ×10000 fixed-point (≈ 0.08 × 10000 = 800).
+///
+/// @since 2.0.0
+/// @returns  `800`
 fn parabola_gravity(): int { return 800; }
 
-// GRAVITY_HALF: gravity/2 for displacement formula ×10000
+/// Half of Minecraft gravity per tick (used for displacement formula).
+///
+/// @since 2.0.0
+/// @returns  `400`
 fn parabola_gravity_half(): int { return 400; }
 
 // ─── Ballistic trajectory (no drag) ──────────────────────────────────────────
@@ -35,16 +41,27 @@ fn parabola_gravity_half(): int { return 400; }
 //
 // All velocities returned ×10000 (blocks/tick × 10000)
 
-// parabola_vx(dx, ticks): initial X velocity ×10000
-// dx: horizontal displacement in blocks
-// ticks: flight time in ticks
+/// Compute the initial X velocity needed to reach `dx` blocks in `ticks` ticks.
+///
+/// @since 2.0.0
+/// @param dx     Horizontal X displacement in blocks
+/// @param ticks  Flight time in ticks
+/// @returns      Initial X velocity ×10000 (`dx * 10000 / ticks`), or `0` if `ticks ≤ 0`
+/// @example
+/// let vx: int = parabola_vx(10, 20)
 fn parabola_vx(dx: int, ticks: int): int {
     if (ticks <= 0) { return 0; }
     return dx * 10000 / ticks;
 }
 
-// parabola_vy(dy, ticks): initial Y velocity ×10000
-// dy: vertical displacement in blocks (positive = up)
+/// Compute the initial Y velocity needed to reach height `dy` in `ticks` ticks.
+///
+/// @since 2.0.0
+/// @param dy     Vertical displacement in blocks (positive = up)
+/// @param ticks  Flight time in ticks
+/// @returns      Initial Y velocity ×10000, or `0` if `ticks ≤ 0`
+/// @example
+/// let vy: int = parabola_vy(5, 20)
 fn parabola_vy(dy: int, ticks: int): int {
     if (ticks <= 0) { return 0; }
     // vy * t = dy * 10000 + gravity_half * t^2
@@ -53,14 +70,24 @@ fn parabola_vy(dy: int, ticks: int): int {
     return (dy * 10000 + g_term) / ticks;
 }
 
-// parabola_vz(dz, ticks): initial Z velocity ×10000
+/// Compute the initial Z velocity needed to reach `dz` blocks in `ticks` ticks.
+///
+/// @since 2.0.0
+/// @param dz     Horizontal Z displacement in blocks
+/// @param ticks  Flight time in ticks
+/// @returns      Initial Z velocity ×10000, or `0` if `ticks ≤ 0`
 fn parabola_vz(dz: int, ticks: int): int {
     if (ticks <= 0) { return 0; }
     return dz * 10000 / ticks;
 }
 
-// parabola_speed_xz(dx, dz, ticks): horizontal speed ×10000 (for launch angle)
-// Returns sqrt(vx^2 + vz^2) ×10000
+/// Compute the horizontal speed `sqrt(vx² + vz²)` needed to reach `(dx, dz)` in `ticks` ticks.
+///
+/// @since 2.0.0
+/// @param dx     X displacement in blocks
+/// @param dz     Z displacement in blocks
+/// @param ticks  Flight time in ticks
+/// @returns      Horizontal launch speed ×10000, or `0` if `ticks ≤ 0`
 fn parabola_speed_xz(dx: int, dz: int, ticks: int): int {
     if (ticks <= 0) { return 0; }
     let vx: int = parabola_vx(dx, ticks);
@@ -77,37 +104,60 @@ fn parabola_speed_xz(dx: int, dz: int, ticks: int): int {
 //   y(t) = vy0 * t / 10000 - gravity_half * t^2 / 10000
 //   z(t) = vz0 * t / 10000
 
-// parabola_x(vx0, t): X position at tick t in blocks
+/// X position at tick `t` given initial X velocity `vx0` ×10000.
+///
+/// @since 2.0.0
+/// @param vx0  Initial X velocity ×10000
+/// @param t    Elapsed ticks
+/// @returns    X displacement in blocks (`vx0 * t / 10000`)
 fn parabola_x(vx0: int, t: int): int {
     return vx0 * t / 10000;
 }
 
-// parabola_y(vy0, t): Y position at tick t in blocks
+/// Y position at tick `t` given initial Y velocity `vy0` ×10000.
+///
+/// @since 2.0.0
+/// @param vy0  Initial Y velocity ×10000
+/// @param t    Elapsed ticks
+/// @returns    Y displacement in blocks (positive = up)
 fn parabola_y(vy0: int, t: int): int {
     let g_term: int = parabola_gravity_half() * t * t / 10000;
     return vy0 * t / 10000 - g_term;
 }
 
-// parabola_z(vz0, t): Z position at tick t in blocks
+/// Z position at tick `t` given initial Z velocity `vz0` ×10000.
+///
+/// @since 2.0.0
+/// @param vz0  Initial Z velocity ×10000
+/// @param t    Elapsed ticks
+/// @returns    Z displacement in blocks
 fn parabola_z(vz0: int, t: int): int {
     return vz0 * t / 10000;
 }
 
 // ─── Flight time estimation ───────────────────────────────────────────────────
-//
-// Given initial upward velocity vy0 (×10000), find the tick when the projectile
-// returns to launch height (y=0):
-//   t = 2 * vy0 / gravity = 2 * vy0 / 800
-// Returns ticks (integer). Returns 0 if vy0 <= 0.
 
-// parabola_flight_time(vy0): ticks until returning to launch height
+/// Estimate the tick when the projectile returns to launch height (`y = 0`).
+///
+/// Formula: `t = 2 × vy0 / gravity`. Returns `0` for non-positive initial velocity.
+///
+/// @since 2.0.0
+/// @param vy0  Initial Y velocity ×10000
+/// @returns    Flight time in ticks, or `0` if `vy0 ≤ 0`
+/// @example
+/// let t: int = parabola_flight_time(8000)
 fn parabola_flight_time(vy0: int): int {
     if (vy0 <= 0) { return 0; }
     return 2 * vy0 / parabola_gravity();
 }
 
-// parabola_max_height(vy0): maximum height above launch point in blocks
-// apex at t = vy0 / gravity
+/// Maximum height (in blocks) above the launch point.
+///
+/// @since 2.0.0
+/// @param vy0  Initial Y velocity ×10000
+/// @returns    Apex height in blocks, or `0` if `vy0 ≤ 0`
+/// @example
+/// let h: int = parabola_max_height(8000)
 fn parabola_max_height(vy0: int): int {
     if (vy0 <= 0) { return 0; }
     let t_apex: int = vy0 / parabola_gravity();
@@ -123,27 +173,46 @@ fn parabola_max_height(vy0: int): int {
 //
 // drag: ×10000 (e.g. 9900 = 0.99 for arrows, 9800 = 0.98 for fireballs)
 
-// parabola_step_vx(vx, drag): apply drag to X velocity
+/// Apply drag to the X velocity for one tick.
+///
+/// @since 2.0.0
+/// @param vx    Current X velocity ×10000
+/// @param drag  Drag factor ×10000 (e.g. `9900` = 0.99 for arrows)
+/// @returns     New X velocity ×10000
 fn parabola_step_vx(vx: int, drag: int): int {
     return mulfix(vx, drag);
 }
 
-// parabola_step_vy(vy, drag): apply gravity then drag to Y velocity
+/// Apply gravity and then drag to the Y velocity for one tick.
+///
+/// @since 2.0.0
+/// @param vy    Current Y velocity ×10000
+/// @param drag  Drag factor ×10000
+/// @returns     New Y velocity ×10000 after `(vy - gravity) * drag`
 fn parabola_step_vy(vy: int, drag: int): int {
     return mulfix(vy - parabola_gravity(), drag);
 }
 
-// parabola_step_vz(vz, drag): apply drag to Z velocity
+/// Apply drag to the Z velocity for one tick.
+///
+/// @since 2.0.0
+/// @param vz    Current Z velocity ×10000
+/// @param drag  Drag factor ×10000
+/// @returns     New Z velocity ×10000
 fn parabola_step_vz(vz: int, drag: int): int {
     return mulfix(vz, drag);
 }
 
 // ─── Targeting helpers ────────────────────────────────────────────────────────
 
-// parabola_ticks_for_range(range): estimate ticks to reach a horizontal range
-// range: distance in blocks
-// Uses average speed heuristic: t ≈ range * 10000 / 8000 (arrow ≈ 0.8 b/t horizontal)
-// For precise aiming use parabola_vx/vy/vz with desired ticks.
+/// Estimate the number of ticks to reach a horizontal range using average arrow speed.
+///
+/// Heuristic: `t ≈ range × 10000 / 8000` (assumes ≈ 0.8 blocks/tick horizontal).
+/// For precise aiming, use `parabola_vx/vy/vz` with a chosen tick count.
+///
+/// @since 2.0.0
+/// @param range  Horizontal distance in blocks
+/// @returns      Estimated ticks (minimum 1)
 fn parabola_ticks_for_range(range: int): int {
     if (range <= 0) { return 1; }
     let t: int = range * 10000 / 8000;
@@ -151,7 +220,13 @@ fn parabola_ticks_for_range(range: int): int {
     return t;
 }
 
-// parabola_in_range(dx, dz, max_range): returns 1 if target within horizontal range
+/// Check whether a target is within horizontal range.
+///
+/// @since 2.0.0
+/// @param dx         X displacement to target in blocks
+/// @param dz         Z displacement to target in blocks
+/// @param max_range  Maximum range in blocks
+/// @returns          `1` if `dist(dx, dz) ≤ max_range`, otherwise `0`
 fn parabola_in_range(dx: int, dz: int, max_range: int): int {
     let dist_sq: int = dx * dx + dz * dz;
     let range_sq: int = max_range * max_range;

package/src/stdlib/particles.mcrs

@@ -1,52 +1,82 @@
 // Particle effect helpers
 // Usage: import "stdlib/particles.mcrs"
 
-/// Spawn heart particles at position
+/// Spawns heart particles at a block position.
+/// @param x  X coordinate
+/// @param y  Y coordinate
+/// @param z  Z coordinate
 fn hearts_at(x: int, y: int, z: int) {
     particle("heart", x, y, z);
 }
 
-/// Spawn flame particles at position
+/// Spawns flame particles at a block position.
+/// @param x  X coordinate
+/// @param y  Y coordinate
+/// @param z  Z coordinate
 fn flames(x: int, y: int, z: int) {
     particle("flame", x, y, z);
 }
 
-/// Spawn smoke effect
+/// Spawns large smoke particles at a block position.
+/// @param x  X coordinate
+/// @param y  Y coordinate
+/// @param z  Z coordinate
 fn smoke(x: int, y: int, z: int) {
     particle("large_smoke", x, y, z);
 }
 
-/// Spawn explosion effect
+/// Spawns an explosion particle at a block position.
+/// @param x  X coordinate
+/// @param y  Y coordinate
+/// @param z  Z coordinate
 fn explosion_effect(x: int, y: int, z: int) {
     particle("explosion", x, y, z);
 }
 
-/// Spawn magic sparkles at position
+/// Spawns enchantment sparkles at a block position.
+/// @param x  X coordinate
+/// @param y  Y coordinate
+/// @param z  Z coordinate
 fn sparkles_at(x: int, y: int, z: int) {
     particle("enchant", x, y, z);
 }
 
-/// Spawn angry villager particles
+/// Spawns angry villager particles at a block position.
+/// @param x  X coordinate
+/// @param y  Y coordinate
+/// @param z  Z coordinate
 fn angry_at(x: int, y: int, z: int) {
     particle("angry_villager", x, y, z);
 }
 
-/// Spawn happy villager particles
+/// Spawns happy villager particles at a block position.
+/// @param x  X coordinate
+/// @param y  Y coordinate
+/// @param z  Z coordinate
 fn happy_at(x: int, y: int, z: int) {
     particle("happy_villager", x, y, z);
 }
 
-/// Spawn portal effect
+/// Spawns portal particles at a block position.
+/// @param x  X coordinate
+/// @param y  Y coordinate
+/// @param z  Z coordinate
 fn portal_effect(x: int, y: int, z: int) {
     particle("portal", x, y, z);
 }
 
-/// Spawn totem particles at position
+/// Spawns totem particles at a block position.
+/// @param x  X coordinate
+/// @param y  Y coordinate
+/// @param z  Z coordinate
 fn totem_at(x: int, y: int, z: int) {
     particle("totem_of_undying", x, y, z);
 }
 
-/// Spawn end rod sparkles
+/// Spawns end rod particles at a block position.
+/// @param x  X coordinate
+/// @param y  Y coordinate
+/// @param z  Z coordinate
 fn end_sparkles_at(x: int, y: int, z: int) {
     particle("end_rod", x, y, z);
 }
@@ -65,8 +95,12 @@ fn end_sparkles_at(x: int, y: int, z: int) {
 //       t = t + step;
 //   }
 
-// particle_at_fx(x_fx, y_fx, z_fx, particle): spawn particle at fixed-point position
-// Coordinates: ×100 (1 block = 100 units)
+/// Spawns a particle at a fixed-point position expressed as blocks ×100.
+/// This helper emits a raw command so sub-block coordinates are preserved.
+/// @param x_fx      X coordinate in blocks ×100
+/// @param y_fx      Y coordinate in blocks ×100
+/// @param z_fx      Z coordinate in blocks ×100
+/// @param particle  Particle ID such as `minecraft:flame`
 fn particle_at_fx(x_fx: int, y_fx: int, z_fx: int, particle: string) {
     let bx: int = x_fx / 100;
     let by: int = y_fx / 100;
@@ -74,9 +108,15 @@ fn particle_at_fx(x_fx: int, y_fx: int, z_fx: int, particle: string) {
     raw("particle {particle} {bx}.{x_fx%100} {by}.{y_fx%100} {bz}.{z_fx%100} 0 0 0 0 1 force");
 }
 
-// draw_line_2d(x0, y0, x1, y1, steps, z, particle):
-// Draw a straight line from (x0,y0) to (x1,y1) with given number of steps
-// All coords ×100
+/// Draws a straight 2D particle line using linear interpolation.
+/// Coordinates are fixed-point blocks ×100; `z` is also passed in ×100.
+/// @param x0        Start X in blocks ×100
+/// @param y0        Start Y in blocks ×100
+/// @param x1        End X in blocks ×100
+/// @param y1        End Y in blocks ×100
+/// @param steps     Number of interpolation steps
+/// @param z         Z plane in blocks ×100
+/// @param particle  Particle ID such as `minecraft:dust`
 fn draw_line_2d(x0: int, y0: int, x1: int, y1: int, steps: int, z: int, particle: string) {
     let i: int = 0;
     while (i <= steps) {
@@ -87,9 +127,14 @@ fn draw_line_2d(x0: int, y0: int, x1: int, y1: int, steps: int, z: int, particle
     }
 }
 
-// draw_circle(cx, cy, cz, r, steps, particle):
-// Draw a circle in the XZ plane
-// cx,cy,cz: center in blocks, r: radius ×100, steps: number of particles
+/// Draws a circle in the XZ plane using `cos_fixed` and `sin_fixed`.
+/// Center coordinates are whole blocks; radius is blocks ×100.
+/// @param cx        Center X in blocks
+/// @param cy        Center Y in blocks
+/// @param cz        Center Z in blocks
+/// @param r         Radius in blocks ×100
+/// @param steps     Number of particle samples around the circle
+/// @param particle  Particle ID such as `minecraft:end_rod`
 fn draw_circle(cx: int, cy: int, cz: int, r: int, steps: int, particle: string) {
     let i: int = 0;
     while (i < steps) {
@@ -101,8 +146,16 @@ fn draw_circle(cx: int, cy: int, cz: int, r: int, steps: int, particle: string)
     }
 }
 
-// draw_helix(cx, cy_start, cz, r, height, rotations, steps, particle):
-// Draw a helix spiral
+/// Draws a helix spiral with configurable radius, height, and turns.
+/// Center coordinates are whole blocks; radius is blocks ×100.
+/// @param cx          Center X in blocks
+/// @param cy_start    Starting Y coordinate in blocks
+/// @param cz          Center Z in blocks
+/// @param r           Radius in blocks ×100
+/// @param height      Total helix height in blocks
+/// @param rotations   Number of full turns
+/// @param steps       Number of particle samples
+/// @param particle    Particle ID such as `minecraft:portal`
 fn draw_helix(cx: int, cy_start: int, cz: int, r: int, height: int, rotations: int, steps: int, particle: string) {
     let i: int = 0;
     while (i < steps) {
@@ -115,7 +168,11 @@ fn draw_helix(cx: int, cy_start: int, cz: int, r: int, height: int, rotations: i
     }
 }
 
-// particle_dot(x, y, z, particle): helper — single particle at integer block coords
+/// Spawns exactly one particle at integer block coordinates.
+/// @param x         X coordinate in whole blocks
+/// @param y         Y coordinate in whole blocks
+/// @param z         Z coordinate in whole blocks
+/// @param particle  Particle ID such as `minecraft:flame`
 fn particle_dot(x: int, y: int, z: int, particle: string) {
     raw("particle {particle} {x} {y} {z} 0 0 0 0 1 force");
 }

package/src/stdlib/pathfind.mcrs

@@ -33,18 +33,38 @@ module library
 
 // ─── Coordinate utilities ─────────────────────────────────────────────────────
 
-// pf_pack(x, z): encode (x, z) as a single int (x*16+z)
+/// Encode a (x, z) grid coordinate pair as a single packed integer.
+/// @since 1.0.0
+/// @param x  Grid X coordinate [0, 15]
+/// @param z  Grid Z coordinate [0, 15]
+/// @returns  x * 16 + z (unique index in [0, 255])
+/// @example
+/// let p: int = pf_pack(3, 7)  // result: 55
 fn pf_pack(x: int, z: int): int { return x * 16 + z }
 
-// pf_unpack_x(packed): recover the x component
+/// Extract the X coordinate from a packed grid index.
+/// @since 1.0.0
+/// @param packed  Packed coordinate from pf_pack
+/// @returns  X component: packed / 16
+/// @example
+/// let x: int = pf_unpack_x(55)  // result: 3
 fn pf_unpack_x(packed: int): int { return packed / 16 }
 
-// pf_unpack_z(packed): recover the z component
+/// Extract the Z coordinate from a packed grid index.
+/// @since 1.0.0
+/// @param packed  Packed coordinate from pf_pack
+/// @returns  Z component: packed % 16
+/// @example
+/// let z: int = pf_unpack_z(55)  // result: 7
 fn pf_unpack_z(packed: int): int { return packed % 16 }
 
 // ─── Obstacle map ─────────────────────────────────────────────────────────────
 
-// pf_new_map(): allocate a 256-element map, all cells passable (value 0)
+/// Allocate a new 16×16 grid obstacle map with all cells passable.
+/// @since 1.0.0
+/// @returns  int[] of 256 zeros; index = pf_pack(x, z), 0=passable, 1=blocked
+/// @example
+/// let map: int[] = pf_new_map()
 fn pf_new_map(): int[] {
     let map: int[] = []
     let i: int = 0
@@ -55,19 +75,40 @@ fn pf_new_map(): int[] {
     return map
 }
 
-// pf_set_blocked(map, x, z): mark cell (x, z) as impassable
+/// Mark a grid cell as impassable (blocked).
+/// @since 1.0.0
+/// @param map  Obstacle map from pf_new_map
+/// @param x    Cell X coordinate [0, 15]
+/// @param z    Cell Z coordinate [0, 15]
+/// @returns  void — sets map[pf_pack(x,z)] = 1
+/// @example
+/// pf_set_blocked(map, 5, 3)  // block cell (5, 3)
 fn pf_set_blocked(map: int[], x: int, z: int) {
     let idx: int = pf_pack(x, z)
     map[idx] = 1
 }
 
-// pf_set_open(map, x, z): mark cell (x, z) as passable
+/// Mark a grid cell as passable (open).
+/// @since 1.0.0
+/// @param map  Obstacle map from pf_new_map
+/// @param x    Cell X coordinate [0, 15]
+/// @param z    Cell Z coordinate [0, 15]
+/// @returns  void — sets map[pf_pack(x,z)] = 0
+/// @example
+/// pf_set_open(map, 5, 3)  // re-open previously blocked cell (5, 3)
 fn pf_set_open(map: int[], x: int, z: int) {
     let idx: int = pf_pack(x, z)
     map[idx] = 0
 }
 
-// pf_is_blocked(map, x, z): 1 if out-of-bounds or impassable, 0 otherwise
+/// Check whether a grid cell is blocked or out of bounds.
+/// @since 1.0.0
+/// @param map  Obstacle map from pf_new_map
+/// @param x    Cell X coordinate
+/// @param z    Cell Z coordinate
+/// @returns  1 if out of bounds (x or z outside [0,15]) or cell is blocked, 0 if passable
+/// @example
+/// let blocked: int = pf_is_blocked(map, 5, 3)
 fn pf_is_blocked(map: int[], x: int, z: int): int {
     if (x < 0) { return 1 }
     if (z < 0) { return 1 }
@@ -78,8 +119,15 @@ fn pf_is_blocked(map: int[], x: int, z: int): int {
 
 // ─── Manhattan heuristic ──────────────────────────────────────────────────────
 
-// pf_heuristic(x1, z1, x2, z2): Manhattan distance ×10000 (fixed-point)
-// Informational — not used by BFS, but useful if you extend to A*.
+/// Compute Manhattan distance between two grid cells, scaled ×10000.
+/// @since 1.0.0
+/// @param x1  First cell X
+/// @param z1  First cell Z
+/// @param x2  Second cell X
+/// @param z2  Second cell Z
+/// @returns  (|x1-x2| + |z1-z2|) * 10000 — useful as A* heuristic
+/// @example
+/// let h: int = pf_heuristic(0, 0, 3, 4)  // result: 70000 (7 Manhattan steps × 10000)
 fn pf_heuristic(x1: int, z1: int, x2: int, z2: int): int {
     let dx: int = x1 - x2
     let dz: int = z1 - z2
@@ -90,14 +138,19 @@ fn pf_heuristic(x1: int, z1: int, x2: int, z2: int): int {
 
 // ─── BFS pathfinding (synchronous) ───────────────────────────────────────────
 
-// pathfind_bfs(map, sx, sz, gx, gz): find shortest path via BFS
-//
-// Returns int[] of packed coords start→goal (inclusive), or [] if unreachable.
-//
-// Internal arrays (size 256):
-//   visited[] — 1 = cell was enqueued; 0 = not yet seen
-//   parent[]  — packed coord of predecessor (-1 = no parent / unvisited)
-//   queue[]   — BFS frontier; consumed via qhead index (no front-dequeue needed)
+/// Find the shortest path between two cells on a 16×16 grid using BFS.
+/// @since 1.0.0
+/// @param map  Obstacle map from pf_new_map (with pf_set_blocked applied)
+/// @param sx   Start cell X [0, 15]
+/// @param sz   Start cell Z [0, 15]
+/// @param gx   Goal cell X [0, 15]
+/// @param gz   Goal cell Z [0, 15]
+/// @returns  int[] of packed coords (pf_pack) from start to goal inclusive, or [] if no path
+/// @example
+/// let map: int[] = pf_new_map()
+/// pf_set_blocked(map, 3, 5)
+/// let path: int[] = pathfind_bfs(map, 0, 0, 7, 7)
+/// let x0: int = pf_unpack_x(path[0])
 fn pathfind_bfs(map: int[], sx: int, sz: int, gx: int, gz: int): int[] {
     // Allocate visited and parent arrays (256 cells each)
     let visited: int[] = []
@@ -181,10 +234,12 @@ fn pathfind_bfs(map: int[], sx: int, sz: int, gx: int, gz: int): int[] {
 
     // Reconstruct path: walk parent[] links from goal back to start
     let rev: int[] = []
+    let rlen: int = 0
     let node: int = goal
     let walking: int = 1
     while (walking == 1) {
         rev.push(node)
+        rlen = rlen + 1
         if (node == start) {
             walking = 0
         } else {
@@ -194,7 +249,6 @@ fn pathfind_bfs(map: int[], sx: int, sz: int, gx: int, gz: int): int[] {
 
     // Reverse rev[] into path[]
     let path: int[] = []
-    let rlen: int = rev.len
     let ri: int = rlen - 1
     while (ri >= 0) {
         path.push(rev[ri])
@@ -206,21 +260,19 @@ fn pathfind_bfs(map: int[], sx: int, sz: int, gx: int, gz: int): int[] {
 
 // ─── Coroutine BFS (tick-spread for server-friendly operation) ────────────────
 
-// pathfind_bfs_coro: identical BFS logic, spread across ticks via @coroutine.
-//
-// @coroutine(batch=16) processes 16 BFS iterations per server tick, preventing
-// lag spikes on busy grids. Results are pushed into caller-supplied out[] when done.
-//
-// Limitations:
-//   - @coroutine functions cannot return values; use the out[] ref pattern instead.
-//   - Replace pf_noop with your own handler if you need a done callback.
-//   - The out[] array must outlive the coroutine; store it in a scoreboard-backed var.
-//
-// Usage:
-//   let out: int[] = []
-//   pathfind_bfs_coro(map, 0, 0, 7, 7, out)
-//   // … several ticks later, out[] contains the packed-coord path
-
+/// BFS pathfinder spread across server ticks to avoid lag spikes (coroutine variant).
+/// @since 1.0.0
+/// @param map  Obstacle map from pf_new_map
+/// @param sx   Start cell X [0, 15]
+/// @param sz   Start cell Z [0, 15]
+/// @param gx   Goal cell X [0, 15]
+/// @param gz   Goal cell Z [0, 15]
+/// @param out  Caller-supplied int[] that receives packed path coords when done
+/// @returns  void — results are pushed into out[] asynchronously; replace pf_noop for callback
+/// @example
+/// let out: int[] = []
+/// pathfind_bfs_coro(map, 0, 0, 7, 7, out)
+/// // several ticks later, out[] contains the path
 @coroutine(batch=16, onDone=pf_noop)
 fn pathfind_bfs_coro(map: int[], sx: int, sz: int, gx: int, gz: int, out: int[]) {
     let visited: int[] = []
@@ -298,17 +350,18 @@ fn pathfind_bfs_coro(map: int[], sx: int, sz: int, gx: int, gz: int, out: int[])
 
     if (found == 1) {
         let rev: int[] = []
+        let rlen: int = 0
         let node: int = goal
         let walking: int = 1
         while (walking == 1) {
             rev.push(node)
+            rlen = rlen + 1
             if (node == start) {
                 walking = 0
             } else {
                 node = parent[node]
             }
         }
-        let rlen: int = rev.len
         let ri: int = rlen - 1
         while (ri >= 0) {
             out.push(rev[ri])
@@ -317,5 +370,6 @@ fn pathfind_bfs_coro(map: int[], sx: int, sz: int, gx: int, gz: int, out: int[])
     }
 }
 
-// pf_noop: default onDone callback — replace with your own handler
+/// Default no-op onDone callback for pathfind_bfs_coro. Replace with your own handler.
+/// @since 1.0.0
 fn pf_noop() {}