redscript-mc 2.6.2 → 3.0.0

package/doc-drafts/redscript-docs/docs/en/stdlib/pathfind.md

@@ -0,0 +1,104 @@
+# `pathfind` — 16×16 Grid BFS Pathfinding
+
+Import: `import "stdlib/pathfind.mcrs"`
+
+Breadth-first pathfinding on a fixed **16×16** XZ grid. Obstacles are stored in a 256-element `int[]`, and paths are returned as packed grid coordinates.
+
+## Coordinate Packing
+
+Cells are encoded as:
+
+```text
+packed = x * 16 + z
+```
+
+Helpers:
+
+- `pf_unpack_x(packed) = packed / 16`
+- `pf_unpack_z(packed) = packed % 16`
+
+## Quick Example
+
+```rs
+import "stdlib/pathfind.mcrs";
+
+let map: int[] = pf_new_map();
+pf_set_blocked(map, 3, 5);
+pf_set_blocked(map, 3, 6);
+
+let path: int[] = pathfind_bfs(map, 0, 0, 7, 7);
+let first_x: int = pf_unpack_x(path[0]);
+let first_z: int = pf_unpack_z(path[0]);
+```
+
+## Map Helpers
+
+### `pf_pack(x: int, z: int): int`
+
+Pack a grid coordinate into one integer.
+
+### `pf_unpack_x(packed: int): int`
+
+Recover the X coordinate from a packed cell id.
+
+### `pf_unpack_z(packed: int): int`
+
+Recover the Z coordinate from a packed cell id.
+
+### `pf_new_map(): int[]`
+
+Allocate a 256-element obstacle map with all cells open.
+
+### `pf_set_blocked(map: int[], x: int, z: int)`
+
+Mark `(x, z)` as blocked by writing `1`.
+
+### `pf_set_open(map: int[], x: int, z: int)`
+
+Mark `(x, z)` as open by writing `0`.
+
+### `pf_is_blocked(map: int[], x: int, z: int): int`
+
+Return `1` if the cell is blocked or out of bounds, otherwise `0`.
+
+## Heuristic Helper
+
+### `pf_heuristic(x1: int, z1: int, x2: int, z2: int): int`
+
+Return Manhattan distance in ×10000 fixed-point form.
+
+This function is informational in the current module. `pathfind_bfs()` does not use it, but it is useful if you build A* on top of the same map representation.
+
+## Synchronous Pathfinding
+
+### `pathfind_bfs(map: int[], sx: int, sz: int, gx: int, gz: int): int[]`
+
+Find the shortest 4-direction path from start to goal.
+
+- Returns packed coordinates from start to goal, inclusive.
+- Returns `[]` when no path exists.
+- Expansion order is North, South, West, East.
+
+Because this is BFS on a uniform-cost grid, the returned path is shortest in number of steps.
+
+## Coroutine Pathfinding
+
+### `pathfind_bfs_coro(map: int[], sx: int, sz: int, gx: int, gz: int, out: int[])`
+
+Coroutine version of BFS:
+
+- Decorated with `@coroutine(batch=16, onDone=pf_noop)`.
+- Processes up to 16 BFS iterations per tick.
+- Cannot return a value directly, so it pushes the finished path into `out`.
+
+Use this when a synchronous search would be too expensive in one tick.
+
+### `pf_noop()`
+
+Default empty `onDone` callback for the coroutine variant.
+
+## Notes
+
+- The grid is hard-coded to `0..15` on both axes.
+- Start and goal cells are not validated explicitly before indexing, so callers should pass valid coordinates.
+- `pf_is_blocked()` treats out-of-bounds cells as blocked, which keeps BFS inside the grid.

package/doc-drafts/redscript-docs/docs/en/stdlib/physics.md

@@ -0,0 +1,134 @@
+# `physics` — Simple Fixed-Point Physics Helpers
+
+Import: `import "stdlib/physics.mcrs"`
+
+Simple physics simulation helpers for Minecraft datapacks. This module uses per-axis integer math and a fixed-point scale of **×100**, where `100` means `1.0 block` or `1.0 block/tick` depending on context.
+
+## Units
+
+- Position: blocks ×100
+- Velocity: blocks/tick ×100
+- Time: ticks
+- Gravity: `8` means `0.08 blocks/tick^2`
+- Drag and restitution: ×10000
+
+## Quick Example
+
+```rs
+import "stdlib/physics.mcrs";
+
+let y0: int = 6400;    // 64.00 blocks
+let vy0: int = 120;    // 1.20 blocks/tick
+let t: int = 10;
+
+let y: int = projectile_y(y0, vy0, t);
+let vy: int = projectile_vy(vy0, t);
+
+let bounced: int = bounce_v(vy, 7000);   // 70% bounce
+```
+
+## Constants
+
+### `gravity_fx(): int`
+
+Returns `8`, representing Minecraft-like gravity in ×100 units.
+
+### `air_drag_fx(): int`
+
+Returns `9800`, meaning a drag factor of `0.98` per tick.
+
+### `water_drag_fx(): int`
+
+Returns `8000`, meaning a drag factor of `0.80` per tick.
+
+## Projectile Motion
+
+### `projectile_y(p0: int, v0: int, t: int): int`
+
+Vertical position after `t` ticks with constant gravity and no drag.
+
+### `projectile_x(p0: int, v0: int, t: int): int`
+
+Horizontal position after `t` ticks with no drag.
+
+### `projectile_vy(v0: int, t: int): int`
+
+Vertical velocity after `t` ticks of gravity.
+
+### `projectile_land_t(v0y: int): int`
+
+Approximate tick when vertical position returns to launch height. Returns `0` if `v0y <= 0`.
+
+### `projectile_max_height(v0y: int): int`
+
+Maximum height above the launch point in ×100 units.
+
+## Drag and Integration
+
+### `apply_drag(v_fx: int, drag_fx: int): int`
+
+Apply one multiplicative drag step: `v * drag / 10000`.
+
+### `apply_gravity(vy_fx: int): int`
+
+Apply one gravity tick to a vertical velocity.
+
+### `update_pos(p_fx: int, v_fx: int): int`
+
+Advance one tick by adding velocity directly to position.
+
+## Collision and Clamping
+
+### `bounce_v(v_fx: int, restitution_fx: int): int`
+
+Reflect velocity and apply a restitution factor.
+
+- `10000` = perfectly elastic
+- `5000` = half-speed rebound
+- `0` = no rebound
+
+### `clamp_velocity(v_fx: int, max_fx: int): int`
+
+Clamp velocity into `[-max_fx, max_fx]`.
+
+## Spring Helpers
+
+### `spring_force(pos_fx: int, target_fx: int, k_fx: int): int`
+
+Hooke-style spring force toward `target_fx`, with `k_fx` scaled by ×10000.
+
+### `spring_update_v(v_fx: int, pos_fx: int, target_fx: int, k_fx: int, damping_fx: int): int`
+
+Apply spring force and damping to produce the next velocity estimate.
+
+## Circular Motion
+
+This section depends on trig helpers from `stdlib/math`.
+
+### `circular_x(cx: int, r: int, angle_deg: int): int`
+
+X coordinate on a circle around center `cx`.
+
+### `circular_z(cz: int, r: int, angle_deg: int): int`
+
+Z coordinate on a circle around center `cz`.
+
+## Friction and Impact
+
+### `friction_decel(v_fx: int, friction_fx: int): int`
+
+Reduce velocity toward zero by a fixed per-tick amount.
+
+### `is_grounded(y_fx: int, ground_y_fx: int): int`
+
+Return `1` if `y_fx <= ground_y_fx`, otherwise `0`.
+
+### `impact_velocity(h_fx: int): int`
+
+Approximate impact speed from a fall height in ×100 units. Returns `0` for non-positive heights.
+
+## Notes
+
+- This module is intentionally simple and axis-separated.
+- No vector type is used; callers combine `x`, `y`, and `z` themselves.
+- `circular_x()`, `circular_z()`, and `impact_velocity()` rely on math helpers such as `sin_fixed`, `cos_fixed`, and `isqrt`.

package/doc-drafts/redscript-docs/docs/en/stdlib/quaternion.md

@@ -0,0 +1,135 @@
+# `quaternion` — Fixed-Point Quaternion Math
+
+Import: `import "stdlib/quaternion.mcrs"`
+
+Quaternion helpers for Minecraft Display Entity rotations. Components are stored separately, each in **×10000** scale, matching the `[x, y, z, w]` convention used by display entity rotation fields.
+
+Requires `stdlib/math` for `sin_fixed()`, `cos_fixed()`, `mulfix()`, and `isqrt()`.
+
+## Scale and Conventions
+
+- `10000` means `1.0`
+- Identity quaternion is `(0, 0, 0, 10000)`
+- A unit quaternion has `qx^2 + qy^2 + qz^2 + qw^2 ≈ 10000^2`
+- Euler conversion uses **YXZ** order: yaw, then pitch, then roll
+
+## Quick Example
+
+```rs
+import "stdlib/quaternion.mcrs";
+
+let qx: int = quat_axis_y_x(90);
+let qy: int = quat_axis_y_y(90);
+let qz: int = quat_axis_y_z(90);
+let qw: int = quat_axis_y_w(90);
+
+let mid_y: int = quat_slerp_y(0, 0, 0, 10000, qx, qy, qz, qw, 500);
+```
+
+## Identity Quaternion
+
+### `quat_identity_w(): int`
+
+Return `10000`.
+
+### `quat_identity_x(): int`
+
+Return `0`.
+
+### `quat_identity_y(): int`
+
+Return `0`.
+
+### `quat_identity_z(): int`
+
+Return `0`.
+
+## Axis-Angle Constructors
+
+Each axis-angle constructor is split into per-component functions. Angles are plain integer degrees, and the implementation uses `sin(angle / 2)` and `cos(angle / 2)`.
+
+### X-axis rotation
+
+- `quat_axis_x_x(angle_deg: int): int`
+- `quat_axis_x_y(angle_deg: int): int`
+- `quat_axis_x_z(angle_deg: int): int`
+- `quat_axis_x_w(angle_deg: int): int`
+
+### Y-axis rotation
+
+- `quat_axis_y_x(angle_deg: int): int`
+- `quat_axis_y_y(angle_deg: int): int`
+- `quat_axis_y_z(angle_deg: int): int`
+- `quat_axis_y_w(angle_deg: int): int`
+
+### Z-axis rotation
+
+- `quat_axis_z_x(angle_deg: int): int`
+- `quat_axis_z_y(angle_deg: int): int`
+- `quat_axis_z_z(angle_deg: int): int`
+- `quat_axis_z_w(angle_deg: int): int`
+
+## Quaternion Product
+
+These functions compute the component-wise result of `a * b`.
+
+- `quat_mul_x(ax, ay, az, aw, bx, by, bz, bw): int`
+- `quat_mul_y(ax, ay, az, aw, bx, by, bz, bw): int`
+- `quat_mul_z(ax, ay, az, aw, bx, by, bz, bw): int`
+- `quat_mul_w(ax, ay, az, aw, bx, by, bz, bw): int`
+
+Use them together when composing rotations.
+
+## Conjugate
+
+For unit quaternions, the conjugate is also the inverse.
+
+- `quat_conj_x(qx, qy, qz, qw): int`
+- `quat_conj_y(qx, qy, qz, qw): int`
+- `quat_conj_z(qx, qy, qz, qw): int`
+- `quat_conj_w(qx, qy, qz, qw): int`
+
+## Magnitude and Dot
+
+### `quat_mag_sq(qx: int, qy: int, qz: int, qw: int): int`
+
+Return magnitude squared in ×10000 scale. A normalized quaternion should be close to `10000`.
+
+### `quat_dot(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int`
+
+Return dot product in ×10000 scale.
+
+## Interpolation
+
+### `quat_slerp_x(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int`
+
+### `quat_slerp_y(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int`
+
+### `quat_slerp_z(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int`
+
+### `quat_slerp_w(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int`
+
+Approximate spherical interpolation between `a` and `b`.
+
+- `t` is in `[0, 1000]`
+- `0` returns `a`
+- `1000` returns `b`
+
+Implementation detail: this is a lerp-plus-normalize approximation rather than true trig-based SLERP, which is cheaper and suitable for Minecraft animation.
+
+## Euler to Quaternion
+
+### `quat_euler_x(yaw: int, pitch: int, roll: int): int`
+
+### `quat_euler_y(yaw: int, pitch: int, roll: int): int`
+
+### `quat_euler_z(yaw: int, pitch: int, roll: int): int`
+
+### `quat_euler_w(yaw: int, pitch: int, roll: int): int`
+
+Convert yaw, pitch, and roll in degrees into a quaternion using YXZ order.
+
+## Notes
+
+- These helpers return components separately instead of a single array, which matches how RedScript users often write NBT fields.
+- Axis-angle constructors and Euler conversion depend on the math trig tables being available.

package/doc-drafts/redscript-docs/docs/zh/stdlib/graph.md

@@ -0,0 +1,104 @@
+# `graph` — 有向与无向加权图
+
+导入：`import "stdlib/graph.mcrs"`
+
+RedScript datapack 的固定容量图工具。图存储在单个扁平 `int[]` 中，支持最多 **64 个节点**与 **256 条有向边**，并提供遍历与最短路径辅助函数，无需额外的图对象类型。
+
+## 数据布局
+
+`graph_new()` 会分配一个 770 元素的 `int[]`，布局如下：
+
+| 索引 | 含义 |
+|------|------|
+| `g[0]` | 当前有向边数量 |
+| `g[1]` | 节点数量 |
+| `g[2 + i * 3]` | 第 `i` 条边的起点 |
+| `g[2 + i * 3 + 1]` | 第 `i` 条边的终点 |
+| `g[2 + i * 3 + 2]` | 第 `i` 条边的权重 |
+
+节点使用从 `0` 开始的整数编号，范围为 `[0, graph_node_count(g))`。
+
+## 快速示例
+
+```rs
+import "stdlib/graph.mcrs";
+
+let g: int[] = graph_new(5);
+g = graph_add_edge(g, 0, 1, 1);
+g = graph_add_edge(g, 0, 2, 4);
+g = graph_add_undirected(g, 2, 3, 2);
+g = graph_add_edge(g, 1, 3, 2);
+g = graph_add_edge(g, 3, 4, 1);
+
+let vis: int[] = [0, 0, 0, 0, 0];
+let bfs_order: int[] = graph_bfs(g, 0, vis);
+
+let dist: int[] = [0, 0, 0, 0, 0];
+let shortest: int = graph_shortest_path(g, 0, 4, dist);
+// shortest = 4，对应 0 -> 1 -> 3 -> 4
+```
+
+## 函数
+
+### `graph_new(n: int): int[]`
+
+创建一个包含 `n` 个节点、初始无边的新图。`n` 会被限制到 `[0, 64]`。
+
+### `graph_add_edge(g: int[], src: int, dst: int, weight: int): int[]`
+
+追加一条 `src -> dst` 的有向边。若 `src` 或 `dst` 非法，或者图中已经有 256 条有向边，则原样返回输入图。
+
+### `graph_add_undirected(g: int[], a: int, b: int, weight: int): int[]`
+
+追加 `a -> b` 与 `b -> a` 两条同权重边，相当于加入一条无向边。会消耗两个有向边槽位。
+
+### `graph_node_count(g: int[]): int`
+
+返回图配置的节点数。
+
+### `graph_edge_count(g: int[]): int`
+
+返回当前有向边数量。
+
+### `graph_bfs(g: int[], start: int, out_visited: int[]): int[]`
+
+从 `start` 开始执行广度优先搜索。
+
+- 返回按 BFS 顺序访问的节点索引数组。
+- 对每个可达节点，把 `out_visited[i]` 写成 `1`。
+- 如果 `start` 非法，则返回 `[]`。
+
+`out_visited` 至少需要有 `graph_node_count(g)` 个槽位，并且应由调用方先初始化为全 0。
+
+### `graph_dfs(g: int[], start: int, out_visited: int[]): int[]`
+
+从 `start` 开始执行深度优先搜索。
+
+- 返回按 DFS 顺序访问的节点索引数组。
+- 对每个可达节点，把 `out_visited[i]` 写成 `1`。
+- 如果 `start` 非法，则返回 `[]`。
+
+与 `graph_bfs()` 一样，输出数组的大小由调用方保证。
+
+### `graph_has_path(g: int[], src: int, dst: int): int`
+
+若从 `src` 到 `dst` 存在有向路径则返回 `1`，否则返回 `0`。
+
+- 端点非法时同样返回 `0`。
+- 实现上会对存储的有向边做一次 BFS。
+
+### `graph_shortest_path(g: int[], src: int, dst: int, out_dist: int[]): int`
+
+从 `src` 运行 Dijkstra，并把最短距离写入 `out_dist`。
+
+- `out_dist[i]` 会变成从 `src` 到节点 `i` 的最短距离。
+- 不可达节点会写成 `-1`。
+- 函数返回 `out_dist[dst]`。
+- `src` 或 `dst` 非法时返回 `-1`。
+
+## 说明
+
+- 边权重是普通整数。
+- 不安全支持负权重，因为这里使用的是 Dijkstra。
+- `graph_bfs()` 与 `graph_dfs()` 的内部工作数组按 64 个节点固定分配。
+- `graph_shortest_path()` 内部使用 `999999` 作为无穷大哨兵值。

package/doc-drafts/redscript-docs/docs/zh/stdlib/parabola.md

@@ -0,0 +1,113 @@
+# `parabola` — 抛射瞄准与轨迹辅助
+
+导入：`import "stdlib/parabola.mcrs"`
+
+用于 Minecraft 风格抛射运动的辅助函数。这个模块主要服务于发射参数求解与简单逐 tick 模拟，速度使用 **×10000 定点**，重力常量也按 Minecraft 抛射物运动进行调整。
+
+## 单位约定
+
+- 位置偏移：方块
+- 速度：方块/刻 ×10000
+- 时间：tick
+- 重力：`800` 表示 `0.08 方块/tick^2`
+- 阻力：×10000
+
+依赖 `stdlib/math` 提供的 `mulfix()` 与 `isqrt()`。
+
+## 快速示例
+
+```rs
+import "stdlib/parabola.mcrs";
+
+let ticks: int = 20;
+let vx: int = parabola_vx(16, ticks);
+let vy: int = parabola_vy(4, ticks);
+let vz: int = parabola_vz(0, ticks);
+
+let y_at_10: int = parabola_y(vy, 10);
+let flight: int = parabola_flight_time(vy);
+```
+
+## 常量
+
+### `parabola_gravity(): int`
+
+返回 `800`，表示 ×10000 缩放下每 tick 的重力常量。
+
+### `parabola_gravity_half(): int`
+
+返回 `400`，用于位移公式中的 `g / 2` 项。
+
+## 初速度求解
+
+### `parabola_vx(dx: int, ticks: int): int`
+
+计算在 `ticks` tick 内移动 `dx` 方块所需的初始 X 速度。若 `ticks <= 0` 返回 `0`。
+
+### `parabola_vy(dy: int, ticks: int): int`
+
+计算在恒定重力下，于 `ticks` tick 后达到垂直偏移 `dy` 所需的初始 Y 速度。若 `ticks <= 0` 返回 `0`。
+
+### `parabola_vz(dz: int, ticks: int): int`
+
+计算在 `ticks` tick 内移动 `dz` 方块所需的初始 Z 速度。若 `ticks <= 0` 返回 `0`。
+
+### `parabola_speed_xz(dx: int, dz: int, ticks: int): int`
+
+根据求得的 `vx` 和 `vz` 计算水平速度模长，返回值为 ×10000 缩放。
+
+## 第 `t` Tick 的位置
+
+### `parabola_x(vx0: int, t: int): int`
+
+返回经过 `t` tick 后的 X 方向位移。
+
+### `parabola_y(vy0: int, t: int): int`
+
+返回在恒定重力下经过 `t` tick 后的 Y 方向位移。
+
+### `parabola_z(vz0: int, t: int): int`
+
+返回经过 `t` tick 后的 Z 方向位移。
+
+## 飞行估算
+
+### `parabola_flight_time(vy0: int): int`
+
+近似返回抛射物回到发射高度所需的 tick 数。若 `vy0 <= 0` 返回 `0`。
+
+### `parabola_max_height(vy0: int): int`
+
+近似返回相对发射点的最高高度，单位为方块。
+
+## 逐 Tick 阻力辅助
+
+这些函数用于逐 tick 模拟，而不是封闭形式的瞄准求解。
+
+### `parabola_step_vx(vx: int, drag: int): int`
+
+对 X 速度应用一次阻力。
+
+### `parabola_step_vy(vy: int, drag: int): int`
+
+先施加重力，再对 Y 速度应用阻力。
+
+### `parabola_step_vz(vz: int, drag: int): int`
+
+对 Z 速度应用一次阻力。
+
+## 目标辅助
+
+### `parabola_ticks_for_range(range: int): int`
+
+根据一个简单的平均速度启发式，为水平射程估算一个实用的飞行 tick 数。返回值至少为 `1`。
+
+### `parabola_in_range(dx: int, dz: int, max_range: int): int`
+
+若目标在水平最大范围 `max_range` 内则返回 `1`，否则返回 `0`。
+
+## 说明
+
+- 这里的封闭形式位置函数默认不考虑阻力。
+- 考虑阻力时，只提供逐 tick 的速度推进辅助。
+- `parabola_y()` 与 `parabola_max_height()` 返回整数方块值，因此会有截断误差。

package/doc-drafts/redscript-docs/docs/zh/stdlib/pathfind.md

@@ -0,0 +1,104 @@
+# `pathfind` — 16×16 网格 BFS 寻路
+
+导入：`import "stdlib/pathfind.mcrs"`
+
+在固定 **16×16** XZ 网格上执行广度优先寻路。障碍物保存在一个 256 元素的 `int[]` 中，路径结果则以压缩坐标数组的形式返回。
+
+## 坐标压缩
+
+单元格编码方式：
+
+```text
+packed = x * 16 + z
+```
+
+对应辅助函数：
+
+- `pf_unpack_x(packed) = packed / 16`
+- `pf_unpack_z(packed) = packed % 16`
+
+## 快速示例
+
+```rs
+import "stdlib/pathfind.mcrs";
+
+let map: int[] = pf_new_map();
+pf_set_blocked(map, 3, 5);
+pf_set_blocked(map, 3, 6);
+
+let path: int[] = pathfind_bfs(map, 0, 0, 7, 7);
+let first_x: int = pf_unpack_x(path[0]);
+let first_z: int = pf_unpack_z(path[0]);
+```
+
+## 地图辅助
+
+### `pf_pack(x: int, z: int): int`
+
+将网格坐标压缩为一个整数。
+
+### `pf_unpack_x(packed: int): int`
+
+从压缩坐标中取回 X。
+
+### `pf_unpack_z(packed: int): int`
+
+从压缩坐标中取回 Z。
+
+### `pf_new_map(): int[]`
+
+创建一个 256 元素的障碍图，初始时所有单元都可通行。
+
+### `pf_set_blocked(map: int[], x: int, z: int)`
+
+把 `(x, z)` 标记为阻塞，写入 `1`。
+
+### `pf_set_open(map: int[], x: int, z: int)`
+
+把 `(x, z)` 标记为可通行，写入 `0`。
+
+### `pf_is_blocked(map: int[], x: int, z: int): int`
+
+若单元阻塞或越界则返回 `1`，否则返回 `0`。
+
+## 启发式辅助
+
+### `pf_heuristic(x1: int, z1: int, x2: int, z2: int): int`
+
+返回 ×10000 缩放的曼哈顿距离。
+
+当前模块里这个函数主要是信息性辅助，`pathfind_bfs()` 本身并不会使用它；如果你要在同样的数据结构上扩展 A*，它会很有用。
+
+## 同步寻路
+
+### `pathfind_bfs(map: int[], sx: int, sz: int, gx: int, gz: int): int[]`
+
+寻找从起点到终点的最短四方向路径。
+
+- 返回从起点到终点的压缩坐标数组，包含两端。
+- 无路可走时返回 `[]`。
+- 扩展邻居的顺序为 North、South、West、East。
+
+因为这是统一代价网格上的 BFS，所以返回路径在步数意义下是最短的。
+
+## 协程寻路
+
+### `pathfind_bfs_coro(map: int[], sx: int, sz: int, gx: int, gz: int, out: int[])`
+
+BFS 的协程版本：
+
+- 带有 `@coroutine(batch=16, onDone=pf_noop)` 注解。
+- 每个 tick 最多处理 16 次 BFS 迭代。
+- 不能直接返回值，因此会把完成后的路径 push 到 `out`。
+
+当你不想把一次同步搜索的开销集中在单个 tick 内时，用这个版本更合适。
+
+### `pf_noop()`
+
+协程版本默认的空 `onDone` 回调。
+
+## 说明
+
+- 网格范围固定为两个轴的 `0..15`。
+- 起点和终点不会在索引前做显式边界校验，因此调用方应保证坐标有效。
+- `pf_is_blocked()` 会把越界位置视为阻塞，从而保证 BFS 不会走出地图。