redscript-mc 3.0.0 → 3.0.2

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

@@ -1,135 +0,0 @@
-# `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

@@ -1,104 +0,0 @@
-# `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

@@ -1,113 +0,0 @@
-# `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

@@ -1,104 +0,0 @@
-# `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 不会走出地图。

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

@@ -1,134 +0,0 @@
-# `physics` — 简单定点物理辅助
-
-导入：`import "stdlib/physics.mcrs"`
-
-面向 Minecraft datapack 的简化物理辅助函数。这个模块按轴分别处理整数物理量，并使用 **×100** 定点约定，其中 `100` 表示 `1.0 方块` 或 `1.0 方块/刻`。
-
-## 单位约定
-
-- 位置：方块 ×100
-- 速度：方块/刻 ×100
-- 时间：tick
-- 重力：`8` 表示 `0.08 方块/tick^2`
-- 阻力与恢复系数：×10000
-
-## 快速示例
-
-```rs
-import "stdlib/physics.mcrs";
-
-let y0: int = 6400;    // 64.00 方块
-let vy0: int = 120;    // 1.20 方块/刻
-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% 反弹
-```
-
-## 常量
-
-### `gravity_fx(): int`
-
-返回 `8`，表示 ×100 单位下近似 Minecraft 的重力。
-
-### `air_drag_fx(): int`
-
-返回 `9800`，表示每 tick `0.98` 的阻力因子。
-
-### `water_drag_fx(): int`
-
-返回 `8000`，表示每 tick `0.80` 的阻力因子。
-
-## 抛体运动
-
-### `projectile_y(p0: int, v0: int, t: int): int`
-
-在恒定重力、无阻力下，经过 `t` tick 后的纵向位置。
-
-### `projectile_x(p0: int, v0: int, t: int): int`
-
-在无阻力下，经过 `t` tick 后的横向位置。
-
-### `projectile_vy(v0: int, t: int): int`
-
-受到重力作用 `t` tick 后的纵向速度。
-
-### `projectile_land_t(v0y: int): int`
-
-近似返回回到发射高度所需的 tick 数。若 `v0y <= 0` 则返回 `0`。
-
-### `projectile_max_height(v0y: int): int`
-
-返回相对发射点的最大高度，单位为 ×100。
-
-## 阻力与积分
-
-### `apply_drag(v_fx: int, drag_fx: int): int`
-
-执行一步乘性阻力：`v * drag / 10000`。
-
-### `apply_gravity(vy_fx: int): int`
-
-对纵向速度应用一次重力。
-
-### `update_pos(p_fx: int, v_fx: int): int`
-
-将速度直接加到位置上，推进一个 tick。
-
-## 碰撞与限幅
-
-### `bounce_v(v_fx: int, restitution_fx: int): int`
-
-反转速度并应用恢复系数。
-
-- `10000` = 完全弹性
-- `5000` = 半速反弹
-- `0` = 不反弹
-
-### `clamp_velocity(v_fx: int, max_fx: int): int`
-
-把速度限制到 `[-max_fx, max_fx]`。
-
-## 弹簧辅助
-
-### `spring_force(pos_fx: int, target_fx: int, k_fx: int): int`
-
-按 Hooke 定律计算朝向 `target_fx` 的弹簧力，`k_fx` 使用 ×10000 缩放。
-
-### `spring_update_v(v_fx: int, pos_fx: int, target_fx: int, k_fx: int, damping_fx: int): int`
-
-同时施加弹簧力与阻尼，得到下一步速度估计。
-
-## 圆周运动
-
-这一部分依赖 `stdlib/math` 的三角函数。
-
-### `circular_x(cx: int, r: int, angle_deg: int): int`
-
-返回以 `cx` 为圆心的圆周 X 坐标。
-
-### `circular_z(cz: int, r: int, angle_deg: int): int`
-
-返回以 `cz` 为圆心的圆周 Z 坐标。
-
-## 摩擦与撞击
-
-### `friction_decel(v_fx: int, friction_fx: int): int`
-
-按固定绝对值每 tick 把速度衰减到 0。
-
-### `is_grounded(y_fx: int, ground_y_fx: int): int`
-
-若 `y_fx <= ground_y_fx` 则返回 `1`，否则返回 `0`。
-
-### `impact_velocity(h_fx: int): int`
-
-根据下落高度近似计算撞击速度，高度单位为 ×100。非正高度返回 `0`。
-
-## 说明
-
-- 这是一个刻意保持简单、按轴分离的模块。
-- 没有向量类型，调用方需要自己组合 `x`、`y`、`z`。
-- `circular_x()`、`circular_z()` 与 `impact_velocity()` 依赖 `sin_fixed`、`cos_fixed`、`isqrt` 等数学辅助函数。