redscript-mc 3.0.1 → 3.0.2

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

@@ -0,0 +1,180 @@
+# Set_int
+
+> 本文档由 `src/stdlib/set_int.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [set_add](#set-add)
+- [set_has](#set-has)
+- [set_remove](#set-remove)
+- [set_size](#set-size)
+- [set_clear](#set-clear)
+- [set_union](#set-union)
+- [set_intersect](#set-intersect)
+
+---
+
+## `set_add` <Badge type="info" text="v3.0.0" />
+
+向 storage rs:set_int.{set_name} 中插入一个整数；若已存在则不会重复添加
+
+```redscript
+fn set_add(set_name: string, value: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `set_name` | rs:set_int 下的集合名称 |
+| `value` | 要插入的整数值 |
+
+**示例**
+
+```redscript
+set_add("Visited", 42)
+```
+
+---
+
+## `set_has` <Badge type="info" text="v3.0.0" />
+
+检查整数是否存在于 storage rs:set_int.{set_name} 中
+
+```redscript
+fn set_has(set_name: string, value: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `set_name` | rs:set_int 下的集合名称 |
+| `value` | 要检测的整数值 |
+
+**返回：** 元素存在返回 1，否则返回 0
+
+**示例**
+
+```redscript
+if (set_has("Visited", 42) == 1) { }
+```
+
+---
+
+## `set_remove` <Badge type="info" text="v3.0.0" />
+
+从 storage rs:set_int.{set_name} 中删除一个整数
+
+```redscript
+fn set_remove(set_name: string, value: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `set_name` | rs:set_int 下的集合名称 |
+| `value` | 要删除的整数值 |
+
+**示例**
+
+```redscript
+set_remove("Visited", 42)
+```
+
+---
+
+## `set_size` <Badge type="info" text="v3.0.0" />
+
+返回 storage rs:set_int.{set_name} 中当前元素数量
+
+```redscript
+fn set_size(set_name: string): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `set_name` | rs:set_int 下的集合名称 |
+
+**返回：** 集合中的整数个数；若集合不存在则返回 0
+
+**示例**
+
+```redscript
+let count: int = set_size("Visited")
+```
+
+---
+
+## `set_clear` <Badge type="info" text="v3.0.0" />
+
+将 storage rs:set_int.{set_name} 重置为空整数列表
+
+```redscript
+fn set_clear(set_name: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `set_name` | rs:set_int 下的集合名称 |
+
+**示例**
+
+```redscript
+set_clear("Visited")
+```
+
+---
+
+## `set_union` <Badge type="info" text="v3.0.0" />
+
+计算两个整数集合的并集，并将结果写入目标集合
+
+```redscript
+fn set_union(a: string, b: string, result: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 左侧输入集合名称 |
+| `b` | 右侧输入集合名称 |
+| `result` | 目标集合名称 |
+
+**示例**
+
+```redscript
+set_union("SeenA", "SeenB", "SeenAll")
+```
+
+---
+
+## `set_intersect` <Badge type="info" text="v3.0.0" />
+
+计算两个整数集合的交集，并将结果写入目标集合
+
+```redscript
+fn set_intersect(a: string, b: string, result: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 左侧输入集合名称 |
+| `b` | 右侧输入集合名称 |
+| `result` | 目标集合名称 |
+
+**示例**
+
+```redscript
+set_intersect("SeenA", "SeenB", "SeenBoth")
+```
+
+---

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

@@ -0,0 +1,107 @@
+# Sets
+
+> 本文档由 `src/stdlib/sets.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [set_new](#set-new)
+- [set_add](#set-add)
+- [set_contains](#set-contains)
+- [set_remove](#set-remove)
+- [set_clear](#set-clear)
+
+---
+
+## `set_new` <Badge type="info" text="v1.1.0" />
+
+创建一个新的空集合并返回唯一集合 ID（字符串句柄）。
+
+```redscript
+fn set_new(): string
+```
+
+**返回：** 集合 ID（字符串句柄）
+
+**示例**
+
+```redscript
+let s: string = set_new();
+set_add(s, "apple");
+```
+
+---
+
+## `set_add` <Badge type="info" text="v1.1.0" />
+
+若值不存在则将其加入集合（已存在则无操作）。
+
+```redscript
+fn set_add(set: string, value: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `set` | set_new 返回的集合 ID |
+| `value` | 要添加的值 |
+
+**返回：** 无返回值
+
+---
+
+## `set_contains` <Badge type="info" text="v1.1.0" />
+
+检查集合中是否存在某个值。
+
+```redscript
+fn set_contains(set: string, value: string): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `set` | 集合 ID |
+| `value` | 要查找的值 |
+
+**返回：** 存在返回 1，否则返回 0
+
+---
+
+## `set_remove` <Badge type="info" text="v1.1.0" />
+
+从集合中移除某个值（不存在则无操作）。
+
+```redscript
+fn set_remove(set: string, value: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `set` | 集合 ID |
+| `value` | 要移除的值 |
+
+**返回：** 无返回值
+
+---
+
+## `set_clear` <Badge type="info" text="v1.1.0" />
+
+清空集合中的所有值。
+
+```redscript
+fn set_clear(set: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `set` | 集合 ID |
+
+**返回：** 无返回值
+
+---

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

@@ -0,0 +1,373 @@
+# Signal
+
+> 本文档由 `src/stdlib/signal.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [uniform_int](#uniform-int)
+- [uniform_frac](#uniform-frac)
+- [normal_approx12](#normal-approx12)
+- [exp_dist_approx](#exp-dist-approx)
+- [bernoulli](#bernoulli)
+- [weighted2](#weighted2)
+- [weighted3](#weighted3)
+- [gamma_sample](#gamma-sample)
+- [poisson_sample](#poisson-sample)
+- [geometric_sample](#geometric-sample)
+- [negative_binomial_sample](#negative-binomial-sample)
+- [dft_real](#dft-real)
+- [dft_imag](#dft-imag)
+- [dft_magnitude](#dft-magnitude)
+
+---
+
+## `uniform_int` <Badge type="info" text="v2.0.0" />
+
+返回 [lo, hi] 内的均匀随机整数（使用 LCG 随机数生成器）
+
+```redscript
+fn uniform_int(seed: int, lo: int, hi: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `seed` | 任意整数种子 |
+| `lo` | 下界（含） |
+| `hi` | 上界（含） |
+
+**返回：** [lo, hi] 内的伪随机整数
+
+**示例**
+
+```redscript
+let dmg: int = uniform_int(seed, 5, 15)
+```
+
+---
+
+## `uniform_frac` <Badge type="info" text="v2.0.0" />
+
+返回 [0, 10000] 内的均匀随机分数（×10000 精度）
+
+```redscript
+fn uniform_frac(seed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `seed` | 任意整数种子 |
+
+**返回：** [0, 10000] 内的伪随机整数
+
+**示例**
+
+```redscript
+let frac: int = uniform_frac(seed)
+```
+
+---
+
+## `normal_approx12` <Badge type="info" text="v2.0.0" />
+
+使用 Irwin-Hall 方法（12 个均匀采样之和）近似 N(0,1) 变量
+
+```redscript
+fn normal_approx12(seed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `seed` | 任意整数种子 |
+
+**返回：** 近似 N(0,1) 采样值 ×10000，范围约 [-60000, 60000]
+
+**示例**
+
+```redscript
+let z: int = normal_approx12(seed)
+```
+
+---
+
+## `exp_dist_approx` <Badge type="info" text="v2.0.0" />
+
+从速率为 lambda_fx 的指数分布中采样（结果上限为 100000）
+
+```redscript
+fn exp_dist_approx(seed: int, lambda_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `seed` | 任意整数种子 |
+| `lambda_fx` | 速率参数 ×10000（如 10000 = 速率 1.0） |
+
+**返回：** 指数分布变量 ×10000，上限 100000
+
+**示例**
+
+```redscript
+let wait: int = exp_dist_approx(seed, 10000)
+```
+
+---
+
+## `bernoulli` <Badge type="info" text="v2.0.0" />
+
+以 p_fx/10000 的概率返回 1，否则返回 0
+
+```redscript
+fn bernoulli(seed: int, p_fx: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `seed` | 任意整数种子 |
+| `p_fx` | 概率 ×10000（如 5000 = 50%，1000 = 10%） |
+
+**返回：** 以给定概率返回 1，否则返回 0
+
+**示例**
+
+```redscript
+if (bernoulli(seed, 3000) == 1) { /* 30% chance */ }
+```
+
+---
+
+## `weighted2` <Badge type="info" text="v2.0.0" />
+
+按权重 w0、w1 随机选择 0 或 1
+
+```redscript
+fn weighted2(seed: int, w0: int, w1: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `seed` | 任意整数种子 |
+| `w0` | 结果 0 的权重 |
+| `w1` | 结果 1 的权重 |
+
+**返回：** 按权重比例采样的 0 或 1
+
+**示例**
+
+```redscript
+let side: int = weighted2(seed, 3, 7)
+```
+
+---
+
+## `weighted3` <Badge type="info" text="v2.0.0" />
+
+按权重 w0、w1、w2 随机选择 0、1 或 2
+
+```redscript
+fn weighted3(seed: int, w0: int, w1: int, w2: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `seed` | 任意整数种子 |
+| `w0` | 结果 0 的权重 |
+| `w1` | 结果 1 的权重 |
+| `w2` | 结果 2 的权重 |
+
+**返回：** 按权重比例采样的 0、1 或 2
+
+**示例**
+
+```redscript
+let tier: int = weighted3(seed, 50, 30, 20)
+```
+
+---
+
+## `gamma_sample` <Badge type="info" text="v2.0.0" />
+
+从 Gamma(k, θ) 分布中采样（支持整数 k = 1..5）
+
+```redscript
+fn gamma_sample(shape_k: int, scale_theta: int, seed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `shape_k` | 形状参数 k ×10000（如 20000 = k=2） |
+| `scale_theta` | 尺度参数 θ ×10000（如 10000 = θ=1.0） |
+| `seed` | 任意整数种子 |
+
+**返回：** Gamma 分布变量 ×10000
+
+**示例**
+
+```redscript
+let g: int = gamma_sample(20000, 10000, seed)
+```
+
+---
+
+## `poisson_sample` <Badge type="info" text="v2.0.0" />
+
+使用 Knuth 算法从 Poisson(λ) 分布中采样（λ ≤ 20 时效果最佳）
+
+```redscript
+fn poisson_sample(lambda: int, seed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `lambda` | 速率参数 ×10000（如 30000 = λ=3.0） |
+| `seed` | 任意整数种子 |
+
+**返回：** Poisson 计数（普通整数，非 ×10000）
+
+**示例**
+
+```redscript
+let n: int = poisson_sample(30000, seed)
+```
+
+---
+
+## `geometric_sample` <Badge type="info" text="v2.0.0" />
+
+从几何分布 Geometric(p) 中采样（首次成功前失败次数）
+
+```redscript
+fn geometric_sample(p_success: int, seed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `p_success` | 成功概率 ×10000（如 5000 = p=0.5） |
+| `seed` | 任意整数种子 |
+
+**返回：** 非负整数失败次数
+
+**示例**
+
+```redscript
+let fails: int = geometric_sample(5000, seed)
+```
+
+---
+
+## `negative_binomial_sample` <Badge type="info" text="v2.0.0" />
+
+从负二项分布 NegBin(r, p) 中采样（r 次成功前的总失败次数）
+
+```redscript
+fn negative_binomial_sample(r: int, p_success: int, seed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `r` | 成功次数（普通整数，如 1, 2, 3） |
+| `p_success` | 成功概率 ×10000 |
+| `seed` | 任意整数种子 |
+
+**返回：** 总失败次数
+
+**示例**
+
+```redscript
+let n: int = negative_binomial_sample(3, 5000, seed)
+```
+
+---
+
+## `dft_real` <Badge type="info" text="v2.0.0" />
+
+计算最多 8 个样本的实值信号第 k 个 DFT 频段实部
+
+```redscript
+fn dft_real(s0: int, s1: int, s2: int, s3: int, s4: int, s5: int, s6: int, s7: int, n: int, k: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `s0` | 样本 0 ×10000  …  s7: 样本 7 ×10000 |
+| `n` | 样本数（1–8） |
+| `k` | 频段索引（0 到 n−1） |
+
+**返回：** DFT 第 k 频段实部，×10000
+
+**示例**
+
+```redscript
+let re0: int = dft_real(10000, 0, -10000, 0, 0, 0, 0, 0, 4, 0)
+```
+
+---
+
+## `dft_imag` <Badge type="info" text="v2.0.0" />
+
+计算最多 8 个样本的实值信号第 k 个 DFT 频段虚部
+
+```redscript
+fn dft_imag(s0: int, s1: int, s2: int, s3: int, s4: int, s5: int, s6: int, s7: int, n: int, k: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `s0` | 样本 0 ×10000  …  s7: 样本 7 ×10000 |
+| `n` | 样本数（1–8） |
+| `k` | 频段索引 |
+
+**返回：** DFT 第 k 频段虚部，×10000（使用负正弦约定）
+
+---
+
+## `dft_magnitude` <Badge type="info" text="v2.0.0" />
+
+计算 DFT 第 k 频段的幅度 sqrt(re² + im²)，×10000
+
+```redscript
+fn dft_magnitude(s0: int, s1: int, s2: int, s3: int, s4: int, s5: int, s6: int, s7: int, n: int, k: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `s0` | 样本 0 ×10000  …  s7: 样本 7 ×10000 |
+| `n` | 样本数 |
+| `k` | 频段索引 |
+
+**返回：** 第 k 频段幅度，×10000
+
+**示例**
+
+```redscript
+let mag: int = dft_magnitude(10000, 0, -10000, 0, 0, 0, 0, 0, 4, 1)
+```
+
+---