redscript-mc 3.0.1 → 3.0.2

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

@@ -0,0 +1,244 @@
+# Noise
+
+> 本文档由 `src/stdlib/noise.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [hash_1d](#hash-1d)
+- [hash_2d](#hash-2d)
+- [hash_1d_pos](#hash-1d-pos)
+- [hash_2d_pos](#hash-2d-pos)
+- [value_noise_1d](#value-noise-1d)
+- [value_noise_2d](#value-noise-2d)
+- [fbm_1d](#fbm-1d)
+- [fbm_2d](#fbm-2d)
+- [terrain_height](#terrain-height)
+
+---
+
+## `hash_1d` <Badge type="info" text="v1.0.0" />
+
+从一维整数坐标生成伪随机整数
+
+```redscript
+fn hash_1d(x: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 输入坐标（任意整数） |
+
+**返回：** 伪随机整数（任意值；用 % 限制范围）
+
+**示例**
+
+```redscript
+let h: int = hash_1d(42)  // deterministic hash of coordinate 42
+```
+
+---
+
+## `hash_2d` <Badge type="info" text="v1.0.0" />
+
+从二维整数坐标对生成伪随机整数
+
+```redscript
+fn hash_2d(x: int, z: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 第一个坐标 |
+| `z` | 第二个坐标 |
+
+**返回：** 确定性组合两个输入的伪随机整数
+
+**示例**
+
+```redscript
+let h: int = hash_2d(10, 20)  // deterministic hash of (10, 20)
+```
+
+---
+
+## `hash_1d_pos` <Badge type="info" text="v1.0.0" />
+
+Generate a non-negative hash in [0, 10000] from a 1D coordinate.
+
+```redscript
+fn hash_1d_pos(x: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | Input coordinate |
+
+**返回：** Integer in [0, 10000]
+
+**示例**
+
+```redscript
+let v: int = hash_1d_pos(5)  // value between 0 and 10000
+```
+
+---
+
+## `hash_2d_pos` <Badge type="info" text="v1.0.0" />
+
+Generate a non-negative hash in [0, 10000] from a 2D coordinate pair.
+
+```redscript
+fn hash_2d_pos(x: int, z: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | First coordinate |
+| `z` | Second coordinate |
+
+**返回：** Integer in [0, 10000]
+
+**示例**
+
+```redscript
+let v: int = hash_2d_pos(3, 7)  // value between 0 and 10000
+```
+
+---
+
+## `value_noise_1d` <Badge type="info" text="v1.0.0" />
+
+定点数位置处的平滑一维值噪声
+
+```redscript
+fn value_noise_1d(x_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x_fx` | 位置 ×10000（如 10000 = 坐标 1.0） |
+
+**返回：** 噪声值，范围 [0, 10000]，整数坐标间平滑插值
+
+**示例**
+
+```redscript
+let n: int = value_noise_1d(15000)  // smooth noise at x=1.5
+```
+
+---
+
+## `value_noise_2d` <Badge type="info" text="v1.0.0" />
+
+定点数位置处的平滑二维值噪声
+
+```redscript
+fn value_noise_2d(x_fx: int, z_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x_fx` | X 位置 ×10000 |
+| `z_fx` | Z 位置 ×10000 |
+
+**返回：** 噪声值，范围 [0, 10000]，双线性平滑插值
+
+**示例**
+
+```redscript
+let n: int = value_noise_2d(15000, 23000)  // noise at (1.5, 2.3)
+```
+
+---
+
+## `fbm_1d` <Badge type="info" text="v1.0.0" />
+
+一维分形布朗运动（fBm）— 叠加多组八度值噪声
+
+```redscript
+fn fbm_1d(x_fx: int, octaves: int, persistence_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x_fx` | 位置 ×10000 |
+| `octaves` | 噪声层数（1–6；越多细节越丰富但越慢） |
+| `persistence_fx` | 每八度振幅衰减因子 ×10000（5000 = 0.5 推荐） |
+
+**返回：** 归一化噪声值，约在 [0, 10000]
+
+**示例**
+
+```redscript
+let h: int = fbm_1d(50000, 4, 5000)  // 4 octave noise at x=5.0
+```
+
+---
+
+## `fbm_2d` <Badge type="info" text="v1.0.0" />
+
+二维分形布朗运动 — 叠加多组二维值噪声
+
+```redscript
+fn fbm_2d(x_fx: int, z_fx: int, octaves: int, persistence_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x_fx` | X 位置 ×10000 |
+| `z_fx` | Z 位置 ×10000 |
+| `octaves` | 噪声层数（1–6） |
+| `persistence_fx` | 振幅衰减因子 ×10000 |
+
+**返回：** 归一化噪声值，约在 [0, 10000]
+
+**示例**
+
+```redscript
+let h: int = fbm_2d(30000, 50000, 3, 5000)  // 3 octave 2D noise
+```
+
+---
+
+## `terrain_height` <Badge type="info" text="v1.0.0" />
+
+使用 3 组八度 fBm 噪声生成地形高度
+
+```redscript
+fn terrain_height(x: int, z: int, base_y: int, amplitude: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 方块 X 坐标（整数，非定点数） |
+| `z` | 方块 Z 坐标（整数，非定点数） |
+| `base_y` | 基础高度（方块） |
+| `amplitude` | 最大高度变化（方块） |
+
+**返回：** 坐标 (x, z) 处的方块高度
+
+**示例**
+
+```redscript
+let h: int = terrain_height(100, 200, 64, 16)  // terrain at (100, 200) near y=64
+```
+
+---

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

@@ -0,0 +1,243 @@
+# Ode
+
+> 本文档由 `src/stdlib/ode.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [ode_mul_fx](#ode-mul-fx)
+- [ode_weighted_increment](#ode-weighted-increment)
+- [ode_reset](#ode-reset)
+- [ode_get_system](#ode-get-system)
+- [ode_get_t](#ode-get-t)
+- [ode_get_y](#ode-get-y)
+- [ode_get_y2](#ode-get-y2)
+- [ode_get_k](#ode-get-k)
+- [ode_get_extra](#ode-get-extra)
+- [ode_get_steps](#ode-get-steps)
+- [ode_step](#ode-step)
+- [ode_run](#ode-run)
+- [ode_run2](#ode-run2)
+
+---
+
+## `ode_mul_fx` <Badge type="info" text="v2.0.0" />
+
+定点数乘法：a_fx * b_fx / 10000
+
+```redscript
+fn ode_mul_fx(a_fx: int, b_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a_fx` | 第一个操作数 ×10000 |
+| `b_fx` | 第二个操作数 ×10000 |
+
+**返回：** 乘积（×10000）
+
+---
+
+## `ode_weighted_increment` <Badge type="info" text="v2.0.0" />
+
+计算 RK4 加权增量：h * (k1 + 2k2 + 2k3 + k4) / 6
+
+```redscript
+fn ode_weighted_increment(h_fx: int, deriv_sum_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h_fx` | 步长 ×10000 |
+| `deriv_sum_fx` | k1 + 2k2 + 2k3 + k4，×10000 |
+
+**返回：** 加权增量 ×10000
+
+---
+
+## `ode_reset` <Badge type="info" text="v2.0.0" />
+
+在 storage rs:ode 中初始化 ODE 模块状态
+
+```redscript
+fn ode_reset(system_id: int, t_fx: int, y_fx: int, y2_fx: int, k_fx: int, extra_fx: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `system_id` | 内置系统常量（1=衰减，2=增长，3=振荡器） |
+| `t_fx` | 初始时间 ×10000 |
+| `y_fx` | 初始主变量 y(0) ×10000 |
+| `y2_fx` | 初始次变量 y'(0) ×10000（仅 system 3 使用） |
+| `k_fx` | 速率/弹性常数 ×10000 |
+| `extra_fx` | 阻尼系数 ×10000（仅 system 3 使用） |
+
+**示例**
+
+```redscript
+ode_reset(1, 0, 10000, 0, 10000, 0)
+```
+
+---
+
+## `ode_get_system` <Badge type="info" text="v2.0.0" />
+
+返回 ODE 状态中的系统 ID
+
+```redscript
+fn ode_get_system(): int
+```
+
+**返回：** 槽位 0 中存储的系统 ID
+
+---
+
+## `ode_get_t` <Badge type="info" text="v2.0.0" />
+
+返回当前时间 t（×10000）
+
+```redscript
+fn ode_get_t(): int
+```
+
+**返回：** 当前时间 ×10000
+
+---
+
+## `ode_get_y` <Badge type="info" text="v2.0.0" />
+
+返回当前主变量 y（×10000）
+
+```redscript
+fn ode_get_y(): int
+```
+
+**返回：** 当前 y 值 ×10000
+
+---
+
+## `ode_get_y2` <Badge type="info" text="v2.0.0" />
+
+返回当前次变量 y'（×10000，仅对 system 3 有意义）
+
+```redscript
+fn ode_get_y2(): int
+```
+
+**返回：** 当前 y' 值 ×10000
+
+---
+
+## `ode_get_k` <Badge type="info" text="v2.0.0" />
+
+返回速率常数 k（×10000）
+
+```redscript
+fn ode_get_k(): int
+```
+
+**返回：** 速率常数 ×10000
+
+---
+
+## `ode_get_extra` <Badge type="info" text="v2.0.0" />
+
+返回额外参数（×10000，system 3 中表示阻尼）
+
+```redscript
+fn ode_get_extra(): int
+```
+
+**返回：** 额外参数 ×10000
+
+---
+
+## `ode_get_steps` <Badge type="info" text="v2.0.0" />
+
+返回已执行的步数
+
+```redscript
+fn ode_get_steps(): int
+```
+
+**返回：** 步数（普通整数）
+
+---
+
+## `ode_step` <Badge type="info" text="v2.0.0" />
+
+向前推进一个 RK4 步
+
+```redscript
+fn ode_step(h_fx: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h_fx` | 步长 ×10000（如 1000 = 0.1 时间单位） |
+
+---
+
+## `ode_run` <Badge type="info" text="v2.0.0" />
+
+对标量 ODE 系统执行 steps 步 RK4 积分
+
+```redscript
+fn ode_run(system_id: int, t0_fx: int, y0_fx: int, h_fx: int, steps: int, k_fx: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `system_id` | 内置系统常量（1 或 2 用于标量系统） |
+| `t0_fx` | 初始时间 ×10000 |
+| `y0_fx` | 初始 y 值 ×10000 |
+| `h_fx` | 步长 ×10000 |
+| `steps` | RK4 步数 |
+| `k_fx` | 速率常数 ×10000 |
+
+**示例**
+
+```redscript
+ode_run(1, 0, 10000, 1000, 10, 10000)
+let y: int = ode_get_y()
+```
+
+---
+
+## `ode_run2` <Badge type="info" text="v2.0.0" />
+
+对二维 ODE 系统（如谐振子）执行 steps 步 RK4 积分
+
+```redscript
+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)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `system_id` | 内置系统常量（system 3 = 谐振子） |
+| `t0_fx` | 初始时间 ×10000 |
+| `y0_fx` | 初始 y 值 ×10000 |
+| `y20_fx` | 初始 y' 值 ×10000 |
+| `h_fx` | 步长 ×10000 |
+| `steps` | RK4 步数 |
+| `k_fx` | 弹性常数 ×10000 |
+| `extra_fx` | 阻尼系数 ×10000 |
+
+**示例**
+
+```redscript
+ode_run2(3, 0, 10000, 0, 1000, 20, 10000, 500)
+```
+
+---