redscript-mc 3.0.1 → 3.0.2

package/redscript-docs/docs/zh/stdlib/math.md

@@ -0,0 +1,193 @@
+# Math
+
+> 本文档由 `src/stdlib/math.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [abs](#abs)
+- [sign](#sign)
+- [min](#min)
+- [max](#max)
+- [clamp](#clamp)
+- [lerp](#lerp)
+- [sqrt_fixed](#sqrt-fixed)
+
+---
+
+## `abs` <Badge type="info" text="v1.0.0" />
+
+返回 x 的绝对值（支持泛型 T）
+
+```redscript
+fn abs<T>(x: T) -> T
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入值（任意数值类型 T） |
+
+**返回：** 若 x >= 0 则返回 x，否则返回 -x
+
+**示例**
+
+```redscript
+let a = abs(-5)   // result: 5
+let b = abs(3)    // result: 3
+```
+
+---
+
+## `sign` <Badge type="info" text="v1.0.0" />
+
+返回 x 的符号：1、0 或 -1
+
+```redscript
+fn sign(x: int) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入整数 |
+
+**返回：** x > 0 返回 1，x < 0 返回 -1，x == 0 返回 0
+
+**示例**
+
+```redscript
+let s = sign(-42)  // result: -1
+```
+
+---
+
+## `min` <Badge type="info" text="v1.0.0" />
+
+返回两个值中较小的一个
+
+```redscript
+fn min<T>(a: T, b: T) -> T
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个值 |
+| `b` | 第二个值 |
+
+**返回：** a < b 则返回 a，否则返回 b
+
+**示例**
+
+```redscript
+let m = min(3, 7)  // result: 3
+```
+
+---
+
+## `max` <Badge type="info" text="v1.0.0" />
+
+返回两个值中较大的一个
+
+```redscript
+fn max<T>(a: T, b: T) -> T
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个值 |
+| `b` | 第二个值 |
+
+**返回：** a > b 则返回 a，否则返回 b
+
+**示例**
+
+```redscript
+let m = max(3, 7)  // result: 7
+```
+
+---
+
+## `clamp` <Badge type="info" text="v1.0.0" />
+
+将 x 限制在 [lo, hi] 范围内
+
+```redscript
+fn clamp<T>(x: T, lo: T, hi: T) -> T
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入值 |
+| `lo` | 下界（含） |
+| `hi` | 上界（含） |
+
+**返回：** x < lo 返回 lo；x > hi 返回 hi；否则返回 x
+
+**示例**
+
+```redscript
+let c = clamp(150, 0, 100)  // result: 100
+let d = clamp(50, 0, 100)   // result: 50
+```
+
+---
+
+## `lerp` <Badge type="info" text="v1.0.0" />
+
+在 a 和 b 之间进行线性插值，t 为定点数（范围 0-1000）
+
+```redscript
+fn lerp(a: int, b: int, t: int) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 起始值 |
+| `b` | 结束值 |
+| `t` | 插值因子 ×1000（0 = a，1000 = b） |
+
+**返回：** a + (b - a) * t / 1000
+
+**示例**
+
+```redscript
+let v = lerp(0, 1000, 500)    // result: 500
+let w = lerp(100, 200, 750)   // result: 175
+```
+
+---
+
+## `sqrt_fixed` <Badge type="info" text="v1.0.0" />
+
+定点数平方根（精度 ×1000）
+
+```redscript
+fn sqrt_fixed(x: int) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入值 ×1000（即 2.0 传入 2000） |
+
+**返回：** sqrt(x/1000) × 1000
+
+**示例**
+
+```redscript
+let s = sqrt_fixed(2000)  // result: ~1414  (√2 × 1000)
+let t = sqrt_fixed(1000)  // result: 1000   (√1 × 1000)
+```
+
+---

package/redscript-docs/docs/zh/stdlib/math_hp.md

@@ -0,0 +1,143 @@
+# Math_hp
+
+> 本文档由 `src/stdlib/math_hp.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [double_mul_fixed](#double-mul-fixed)
+- [double_mul](#double-mul)
+- [ln_hp](#ln-hp)
+- [ln_5term](#ln-5term)
+- [double_sqrt](#double-sqrt)
+- [pow_fast](#pow-fast)
+
+---
+
+## `double_mul_fixed` <Badge type="info" text="v1.3.0" />
+
+使用宏技巧将双精度值 d 乘以定点整数 f（×10000），全程保持 IEEE 754 双精度精度。
+
+```redscript
+fn double_mul_fixed(d: double, f: int): double
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `d` | 双精度操作数（NBT 存储） |
+| `f` | 定点乘数 ×10000（如 15000 = 1.5） |
+
+**返回：** d × (f/10000) 的双精度结果
+
+**示例**
+
+```redscript
+let r: double = double_mul_fixed(3.14d, 20000); // 6.28  (3.14 × 2.0)
+```
+
+---
+
+## `double_mul` <Badge type="info" text="v1.3.0" />
+
+通过计分板整数近似实现双精度乘法（约 4 位有效小数）。|a|×|b| > ~21474 时会溢出。
+
+```redscript
+fn double_mul(a: double, b: double): double
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个因数（双精度） |
+| `b` | 第二个因数（双精度） |
+
+**返回：** a × b（近似，约 4 位精度）
+
+---
+
+## `ln_hp` <Badge type="info" text="v1.3.0" />
+
+高精度自然对数，通过对 5 项 atanh 级数结果进行一次 Newton 修正（~8–9 位精度）。有效范围 x ∈ [100, 1000000]。
+
+```redscript
+fn ln_hp(x: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入值 ×10000（如 10000 = 1.0，27183 ≈ e） |
+
+**返回：** ln(x/10000) ×10000
+
+**示例**
+
+```redscript
+let r: int = ln_hp(27183); // ≈ 10000  (ln(e) ≈ 1.0)
+```
+
+---
+
+## `ln_5term` <Badge type="info" text="v1.3.0" />
+
+使用 5 项 atanh 级数计算自然对数（比 3 项 ln() 精度高 2 倍，最大误差 ≈ 0.000002）。
+
+```redscript
+fn ln_5term(x: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入值 ×10000 |
+
+**返回：** ln(x/10000) ×10000
+
+---
+
+## `double_sqrt` <Badge type="info" text="v1.3.0" />
+
+双精度平方根，内部转换为定点数后用 isqrt 计算，再转回双精度。
+
+```redscript
+fn double_sqrt(x: double): double
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入双精度值（必须 ≥ 0） |
+
+**返回：** √x（双精度）
+
+---
+
+## `pow_fast` <Badge type="info" text="v1.3.0" />
+
+双精度底数的整数次方，使用二进制快速幂（O(log n)），支持负指数。
+
+```redscript
+fn pow_fast(base: double, exp_val: int): double
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `base` | 底数（双精度） |
+| `exp_val` | 整数指数（可以为负） |
+
+**返回：** base^exp_val（双精度）
+
+**示例**
+
+```redscript
+let r: double = pow_fast(2.0d, 10); // 1024.0
+```
+
+---

package/redscript-docs/docs/zh/stdlib/matrix.md

@@ -0,0 +1,396 @@
+# Matrix
+
+> 本文档由 `src/stdlib/matrix.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [rotate2d_x](#rotate2d-x)
+- [rotate2d_y](#rotate2d-y)
+- [scale_x](#scale-x)
+- [scale_y](#scale-y)
+- [scale_z](#scale-z)
+- [uniform_scale](#uniform-scale)
+- [rotate_y_x](#rotate-y-x)
+- [rotate_y_z](#rotate-y-z)
+- [rotate_x_y](#rotate-x-y)
+- [rotate_x_z](#rotate-x-z)
+- [quat_sin_half](#quat-sin-half)
+- [quat_cos_half](#quat-cos-half)
+- [billboard_y](#billboard-y)
+- [lerp_angle](#lerp-angle)
+- [mat3_mul_elem](#mat3-mul-elem)
+- [mat3_mul_vec3_elem](#mat3-mul-vec3-elem)
+- [mat4_mul_elem](#mat4-mul-elem)
+- [mat4_mul_vec4_elem](#mat4-mul-vec4-elem)
+
+---
+
+## `rotate2d_x` <Badge type="info" text="v2.0.0" />
+
+将 (x, y) 绕原点旋转 angle_deg（×10000°）后的 X 分量
+
+```redscript
+fn rotate2d_x(x: int, y: int, angle_deg: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入 X 坐标 ×10000 |
+| `y` | 输入 Y 坐标 ×10000 |
+| `angle_deg` | 角度 ×10000（如 450000 = 45°） |
+
+**返回：** x*cos(angle) - y*sin(angle)，×10000
+
+**示例**
+
+```redscript
+let rx: int = rotate2d_x(10000, 0, 900000)
+```
+
+---
+
+## `rotate2d_y` <Badge type="info" text="v2.0.0" />
+
+将 (x, y) 绕原点旋转 angle_deg（×10000°）后的 Y 分量
+
+```redscript
+fn rotate2d_y(x: int, y: int, angle_deg: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入 X 坐标 ×10000 |
+| `y` | 输入 Y 坐标 ×10000 |
+| `angle_deg` | 角度 ×10000 |
+
+**返回：** x*sin(angle) + y*cos(angle)，×10000
+
+---
+
+## `scale_x` <Badge type="info" text="v2.0.0" />
+
+对 X 坐标施加缩放（sx_fx ×10000）
+
+```redscript
+fn scale_x(x: int, sx_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入 X 值 ×10000 |
+| `sx_fx` | 缩放系数 ×10000（如 20000 = 2×） |
+
+**返回：** x * sx_fx / 10000
+
+---
+
+## `scale_y` <Badge type="info" text="v2.0.0" />
+
+对 Y 坐标施加缩放
+
+```redscript
+fn scale_y(y: int, sy_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `y` | 输入 Y 值 ×10000 |
+| `sy_fx` | 缩放系数 ×10000 |
+
+**返回：** y * sy_fx / 10000
+
+---
+
+## `scale_z` <Badge type="info" text="v2.0.0" />
+
+对 Z 坐标施加缩放
+
+```redscript
+fn scale_z(z: int, sz_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `z` | 输入 Z 值 ×10000 |
+| `sz_fx` | 缩放系数 ×10000 |
+
+**返回：** z * sz_fx / 10000
+
+---
+
+## `uniform_scale` <Badge type="info" text="v2.0.0" />
+
+对单个分量施加均匀缩放
+
+```redscript
+fn uniform_scale(v: int, s_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `v` | 输入分量 ×10000 |
+| `s_fx` | 均匀缩放系数 ×10000 |
+
+**返回：** v * s_fx / 10000
+
+---
+
+## `rotate_y_x` <Badge type="info" text="v2.0.0" />
+
+绕 Y 轴旋转 angle_deg（×10000°）后的 X 分量
+
+```redscript
+fn rotate_y_x(x: int, z: int, angle_deg: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | Input X coordinate ×10000 |
+| `z` | Input Z coordinate ×10000 |
+| `angle_deg` | 角度 ×10000 |
+
+**返回：** x*cos + z*sin，×10000
+
+---
+
+## `rotate_y_z` <Badge type="info" text="v2.0.0" />
+
+绕 Y 轴旋转 angle_deg（×10000°）后的 Z 分量
+
+```redscript
+fn rotate_y_z(x: int, z: int, angle_deg: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | Input X coordinate ×10000 |
+| `z` | Input Z coordinate ×10000 |
+| `angle_deg` | 角度 ×10000 |
+
+**返回：** -x*sin + z*cos，×10000
+
+---
+
+## `rotate_x_y` <Badge type="info" text="v2.0.0" />
+
+绕 X 轴旋转 angle_deg（×10000°）后的 Y 分量
+
+```redscript
+fn rotate_x_y(y: int, z: int, angle_deg: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `y` | Input Y coordinate ×10000 |
+| `z` | Input Z coordinate ×10000 |
+| `angle_deg` | 角度 ×10000 |
+
+**返回：** y*cos - z*sin，×10000
+
+---
+
+## `rotate_x_z` <Badge type="info" text="v2.0.0" />
+
+绕 X 轴旋转 angle_deg（×10000°）后的 Z 分量
+
+```redscript
+fn rotate_x_z(y: int, z: int, angle_deg: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `y` | Input Y coordinate ×10000 |
+| `z` | Input Z coordinate ×10000 |
+| `angle_deg` | 角度 ×10000 |
+
+**返回：** y*sin + z*cos，×10000
+
+---
+
+## `quat_sin_half` <Badge type="info" text="v2.0.0" />
+
+用于 Display Entity Y 轴四元数的 sin(angle/2)，×1000
+
+```redscript
+fn quat_sin_half(angle_deg_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `angle_deg_fx` | 完整旋转角度 ×10000 |
+
+**返回：** sin(angle/2)，×1000
+
+---
+
+## `quat_cos_half` <Badge type="info" text="v2.0.0" />
+
+用于 Display Entity Y 轴四元数的 cos(angle/2)，×1000
+
+```redscript
+fn quat_cos_half(angle_deg_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `angle_deg_fx` | 完整旋转角度 ×10000 |
+
+**返回：** cos(angle/2)，×1000
+
+---
+
+## `billboard_y` <Badge type="info" text="v2.0.0" />
+
+计算朝向玩家的广告牌 Y 轴旋转角度
+
+```redscript
+fn billboard_y(player_yaw_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `player_yaw_fx` | 玩家偏航角 ×10000（来自实体 NBT Rotation[0]） |
+
+**返回：** 广告牌 Y 旋转 ×10000，范围 [0, 3600000)
+
+**示例**
+
+```redscript
+let by: int = billboard_y(player_yaw)
+```
+
+---
+
+## `lerp_angle` <Badge type="info" text="v2.0.0" />
+
+在两个角度（×10000）之间沿最短弧线性插值
+
+```redscript
+fn lerp_angle(a_fx: int, b_fx: int, t: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a_fx` | 起始角度 ×10000 |
+| `b_fx` | 终止角度 ×10000 |
+| `t` | 插值系数 ×10000（0 = a，10000 = b） |
+
+**返回：** 插值角度 ×10000
+
+**示例**
+
+```redscript
+let a: int = lerp_angle(0, 3600000, 5000)
+```
+
+---
+
+## `mat3_mul_elem` <Badge type="info" text="v2.0.0" />
+
+计算 3×3 矩阵乘积 A×B 的元素 C[row][col]（×10000）
+
+```redscript
+fn mat3_mul_elem( a00: int, a01: int, a02: int, a10: int, a11: int, a12: int, a20: int, a21: int, a22: int, b00: int, b01: int, b02: int, b10: int, b11: int, b12: int,
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a00` | A[0,0] … a22: A[2,2]（9 个行主序元素，×10000） |
+| `b00` | B[0,0] … b22: B[2,2]（9 个行主序元素，×10000） |
+| `row` | 目标行索引（0–2） |
+| `col` | 目标列索引（0–2） |
+
+**返回：** C[row][col]，×10000
+
+---
+
+## `mat3_mul_vec3_elem` <Badge type="info" text="v2.0.0" />
+
+计算 3×3 矩阵与列向量乘积 A×v 的一个分量
+
+```redscript
+fn mat3_mul_vec3_elem( a00: int, a01: int, a02: int, a10: int, a11: int, a12: int, a20: int, a21: int, a22: int, vx: int, vy: int, vz: int, comp: int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a00` | A 的 9 个行主序元素，×10000 |
+| `vx` | Vector X ×10000   @param vy  Vector Y ×10000   @param vz  Vector Z ×10000 |
+| `comp` | 输出分量索引（0=x, 1=y, 2=z） |
+
+**返回：** (A×v)[comp]，×10000
+
+---
+
+## `mat4_mul_elem` <Badge type="info" text="v2.0.0" />
+
+计算 4×4 矩阵乘积 A×B 的元素 C[row][col]（×10000）
+
+```redscript
+fn mat4_mul_elem( a00: int, a01: int, a02: int, a03: int, a10: int, a11: int, a12: int, a13: int, a20: int, a21: int, a22: int, a23: int, a30: int, a31: int, a32: int, a33: int, b00: int, b01: int, b02: int, b03: int,
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a00` | A 的 16 个行主序元素，×10000 |
+| `b00` | B 的 16 个行主序元素，×10000 |
+| `row` | 目标行索引（0–3） |
+| `col` | 目标列索引（0–3） |
+
+**返回：** C[row][col]，×10000
+
+---
+
+## `mat4_mul_vec4_elem` <Badge type="info" text="v2.0.0" />
+
+计算 4×4 矩阵与齐次向量乘积 A×v 的一个分量
+
+```redscript
+fn mat4_mul_vec4_elem( a00: int, a01: int, a02: int, a03: int, a10: int, a11: int, a12: int, a13: int, a20: int, a21: int, a22: int, a23: int, a30: int, a31: int, a32: int, a33: int, vx: int, vy: int, vz: int, vw: int,
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a00` | A 的 16 个行主序元素，×10000 |
+| `vx` | Vector X ×10000   @param vy  Y   @param vz  Z   @param vw  W |
+| `comp` | 输出分量索引（0=x, 1=y, 2=z, 3=w） |
+
+**返回：** (A×v)[comp]，×10000
+
+---