redscript-mc 3.0.1 → 3.0.2

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

@@ -0,0 +1,124 @@
+# Queue
+
+> 本文档由 `src/stdlib/queue.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [queue_push](#queue-push)
+- [queue_pop](#queue-pop)
+- [queue_peek](#queue-peek)
+- [queue_size](#queue-size)
+- [queue_empty](#queue-empty)
+- [queue_clear](#queue-clear)
+
+---
+
+## `queue_push` <Badge type="info" text="v3.0.0" />
+
+将一个整数入队到 storage rs:arrays Queue 末尾。
+
+```redscript
+fn queue_push(val: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `val` | 要入队的整数值 |
+
+**示例**
+
+```redscript
+queue_push(42)
+```
+
+---
+
+## `queue_pop` <Badge type="info" text="v3.0.0" />
+
+出队并返回队头元素；队列为空时返回 -1。
+
+```redscript
+fn queue_pop(): int
+```
+
+**返回：** 队头整数值，若为空则返回 -1
+
+**示例**
+
+```redscript
+let v: int = queue_pop()
+```
+
+---
+
+## `queue_peek` <Badge type="info" text="v3.0.0" />
+
+查看队头元素但不移除；队列为空时返回 -1。
+
+```redscript
+fn queue_peek(): int
+```
+
+**返回：** 队头整数值，若为空则返回 -1
+
+**示例**
+
+```redscript
+let front: int = queue_peek()
+```
+
+---
+
+## `queue_size` <Badge type="info" text="v3.0.0" />
+
+返回队列中尚未出队的元素数量。
+
+```redscript
+fn queue_size(): int
+```
+
+**返回：** 队列长度（整数）
+
+**示例**
+
+```redscript
+let n: int = queue_size()
+```
+
+---
+
+## `queue_empty` <Badge type="info" text="v3.0.0" />
+
+检查队列是否为空。
+
+```redscript
+fn queue_empty(): int
+```
+
+**返回：** 队列为空返回 1，否则返回 0
+
+**示例**
+
+```redscript
+if (queue_empty() == 1) { }
+```
+
+---
+
+## `queue_clear` <Badge type="info" text="v3.0.0" />
+
+清空队列：将 storage rs:arrays Queue 重置为空列表并将头指针归零。
+
+```redscript
+fn queue_clear()
+```
+
+**示例**
+
+```redscript
+queue_clear()
+```
+
+---

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

@@ -0,0 +1,222 @@
+# Random
+
+> 本文档由 `src/stdlib/random.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [next_lcg](#next-lcg)
+- [random_range](#random-range)
+- [random_bool](#random-bool)
+- [pcg_next_lo](#pcg-next-lo)
+- [pcg_next_hi](#pcg-next-hi)
+- [pcg_output](#pcg-output)
+- [binomial_sample](#binomial-sample)
+- [hypergeometric_sample](#hypergeometric-sample)
+
+---
+
+## `next_lcg` <Badge type="info" text="v1.0.0" />
+
+推进 LCG 状态一步，返回下一个伪随机 int32
+
+```redscript
+fn next_lcg(seed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `seed` | 当前 LCG 状态（任意非零整数） |
+
+**返回：** 下一个伪随机 int32（同时作为下次调用的种子）
+
+**示例**
+
+```redscript
+let seed: int = 12345
+seed = next_lcg(seed)
+seed = next_lcg(seed)  // advance two steps
+```
+
+---
+
+## `random_range` <Badge type="info" text="v1.0.0" />
+
+生成 [lo, hi) 范围内的伪随机整数
+
+```redscript
+fn random_range(seed: int, lo: int, hi: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `seed` | next_lcg 的输出值 |
+| `lo` | 下界（含） |
+| `hi` | 上界（不含，必须 > lo） |
+
+**返回：** 范围 [lo, hi) 内的整数
+
+**示例**
+
+```redscript
+seed = next_lcg(seed)
+let roll: int = random_range(seed, 1, 7)  // dice roll: 1-6
+```
+
+---
+
+## `random_bool` <Badge type="info" text="v1.0.0" />
+
+以相等概率生成 0 或 1 的伪随机布尔值
+
+```redscript
+fn random_bool(seed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `seed` | next_lcg 的输出值 |
+
+**返回：** 0 或 1，各约 50% 概率
+
+**示例**
+
+```redscript
+seed = next_lcg(seed)
+let coin: int = random_bool(seed)  // 0 or 1
+```
+
+---
+
+## `pcg_next_lo` <Badge type="info" text="v1.0.0" />
+
+Advance the PCG low-word state by one step.
+Call together with pcg_next_hi; use pcg_output to extract the random value.
+
+```redscript
+fn pcg_next_lo(state_lo: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `state_lo` | Current low word of PCG state |
+
+**返回：** New low word
+
+**示例**
+
+```redscript
+let lo: int = pcg_next_lo(state_lo)
+```
+
+---
+
+## `pcg_next_hi` <Badge type="info" text="v1.0.0" />
+
+Advance the PCG high-word state by one step.
+
+```redscript
+fn pcg_next_hi(state_hi: int, state_lo: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `state_hi` | Current high word of PCG state |
+| `state_lo` | Current low word of PCG state (previous, before pcg_next_lo) |
+
+**返回：** New high word
+
+**示例**
+
+```redscript
+let hi: int = pcg_next_hi(state_hi, state_lo)
+```
+
+---
+
+## `pcg_output` <Badge type="info" text="v1.0.0" />
+
+Extract an output value from the PCG low word using XSH-RR permutation.
+
+```redscript
+fn pcg_output(state_lo: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `state_lo` | Current low word of PCG state (after pcg_next_lo) |
+
+**返回：** Pseudo-random output value (unsigned, any int)
+
+**示例**
+
+```redscript
+let rng: int = pcg_output(state_lo)
+```
+
+---
+
+## `binomial_sample` <Badge type="info" text="v1.0.0" />
+
+模拟 n 次伯努利试验并统计成功次数（二项分布）
+
+```redscript
+fn binomial_sample(n: int, p_x10000: int, seed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `n` | 试验次数 |
+| `p_x10000` | 成功概率 ×10000（如 5000 = 50%） |
+| `seed` | LCG 种子（任意非零整数） |
+
+**返回：** 成功次数，范围 [0, n]
+
+**示例**
+
+```redscript
+let hits: int = binomial_sample(10, 5000, 99999)  // ~5 successes on average
+```
+
+---
+
+## `hypergeometric_sample` <Badge type="info" text="v1.0.0" />
+
+无放回抽样并统计成功项数（超几何分布）
+
+```redscript
+fn hypergeometric_sample(pop_size: int, success_states: int, draws: int, seed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `pop_size` | 总体大小 |
+| `success_states` | 总体中成功项数量 |
+| `draws` | 抽取数量 |
+| `seed` | LCG 种子 |
+
+**返回：** 抽中的成功项数，范围 [0, min(draws, success_states)]
+
+**示例**
+
+```redscript
+// 52-card deck, 4 aces, draw 5 cards
+let aces: int = hypergeometric_sample(52, 4, 5, 42)
+```
+
+---

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

@@ -0,0 +1,147 @@
+# Result
+
+> 本文档由 `src/stdlib/result.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [result_ok](#result-ok)
+- [result_err](#result-err)
+- [result_is_ok](#result-is-ok)
+- [result_is_err](#result-is-err)
+- [result_value](#result-value)
+- [result_code](#result-code)
+- [result_divide](#result-divide)
+
+---
+
+## `result_ok` <Badge type="info" text="v1.0.0" />
+
+构造一个携带成功值的 Result
+
+```redscript
+fn result_ok(value: int): Result
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `value` | 成功值（任意整数） |
+
+**返回：** Result::Ok(value)
+
+**示例**
+
+```redscript
+let r = result_ok(42)  // Ok result carrying 42
+```
+
+---
+
+## `result_err` <Badge type="info" text="v1.0.0" />
+
+构造一个携带错误码的 Result
+
+```redscript
+fn result_err(code: int): Result
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `code` | 错误码（按惯例使用负数：-1 通用错误，-2 除零） |
+
+**返回：** Result::Err(code)
+
+**示例**
+
+```redscript
+let r = result_err(-2)  // division-by-zero error
+```
+
+---
+
+## `result_is_ok` <Badge type="info" text="v1.0.0" />
+
+判断 Result 是否为 Ok
+
+```redscript
+fn result_is_ok(r: Result): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `r` | 要检测的 Result |
+
+**返回：** Ok 返回 1，Err 返回 0
+
+**示例**
+
+```redscript
+let ok = result_is_ok(result_ok(5))  // result: 1
+```
+
+---
+
+## `result_is_err`
+
+判断 Result 是否为 Err
+
+```redscript
+fn result_is_err(r: Result): int
+```
+
+**返回：** Err 返回 1，Ok 返回 0
+
+---
+
+## `result_value` <Badge type="info" text="v1.0.0" />
+
+从 Ok 结果中提取值（Err 时返回 0，请先调用 result_is_ok 检查）
+
+```redscript
+fn result_value(r: Result): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `r` | 要解包的 Result |
+
+**返回：** Ok 的值，或 0（Err 时）
+
+**示例**
+
+```redscript
+let v = result_value(result_ok(99))  // result: 99
+```
+
+---
+
+## `result_code`
+
+从 Err 结果中提取错误码（Ok 时返回 0）
+
+```redscript
+fn result_code(r: Result): int
+```
+
+**返回：** Err 的错误码，或 0（Ok 时）
+
+---
+
+## `result_divide`
+
+带安全检查的整数除法，除数为零时返回 Err(-2)
+
+```redscript
+fn result_divide(a: int, b: int): Result
+```
+
+**返回：** Ok(a/b) 或 Err(-2)（b == 0 时）
+
+---

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

@@ -0,0 +1,173 @@
+# Scheduler
+
+> 本文档由 `src/stdlib/scheduler.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [task_schedule](#task-schedule)
+- [task_cancel](#task-cancel)
+- [task_ready](#task-ready)
+- [gtask_schedule](#gtask-schedule)
+- [gtask_cancel](#gtask-cancel)
+- [gtask_ready](#gtask-ready)
+- [scheduler_tick](#scheduler-tick)
+
+---
+
+## `task_schedule` <Badge type="info" text="v1.0.0" />
+
+为玩家排程指定槽位的任务，在 delay 个 tick 后触发
+
+```redscript
+fn task_schedule(p: selector, task_id: int, delay: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `p` | 目标玩家或实体选择器 |
+| `task_id` | 槽位索引 [0, 7] |
+| `delay` | 等待的 tick 数 |
+
+**示例**
+
+```redscript
+task_schedule(@s, 0, 40)
+```
+
+---
+
+## `task_cancel` <Badge type="info" text="v1.0.0" />
+
+取消玩家指定槽位的任务（将计数器归零）
+
+```redscript
+fn task_cancel(p: selector, task_id: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `p` | 目标玩家或实体选择器 |
+| `task_id` | 槽位索引 [0, 7] |
+
+**示例**
+
+```redscript
+task_cancel(@s, 0)
+```
+
+---
+
+## `task_ready` <Badge type="info" text="v1.0.0" />
+
+检查玩家指定槽位的任务是否在本 tick 触发；触发后自动清除
+
+```redscript
+fn task_ready(p: selector, task_id: int) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `p` | 目标玩家或实体选择器 |
+| `task_id` | 槽位索引 [0, 7] |
+
+**返回：** 任务触发返回 1，否则返回 0
+
+**示例**
+
+```redscript
+if (task_ready(@s, 0) == 1) { /* handle event */ }
+```
+
+---
+
+## `gtask_schedule` <Badge type="info" text="v1.0.0" />
+
+排程全局槽位任务（绑定到
+
+```redscript
+fn gtask_schedule(task_id: int, delay: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `task_id` | 槽位索引 [0, 7] |
+| `delay` | 等待的 tick 数 |
+
+**示例**
+
+```redscript
+gtask_schedule(0, 200)
+```
+
+---
+
+## `gtask_cancel` <Badge type="info" text="v1.0.0" />
+
+取消全局槽位任务
+
+```redscript
+fn gtask_cancel(task_id: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `task_id` | 槽位索引 [0, 7] |
+
+**示例**
+
+```redscript
+gtask_cancel(0)
+```
+
+---
+
+## `gtask_ready` <Badge type="info" text="v1.0.0" />
+
+检查全局槽位任务是否在本 tick 触发；触发后自动清除
+
+```redscript
+fn gtask_ready(task_id: int) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `task_id` | 槽位索引 [0, 7] |
+
+**返回：** 任务触发返回 1，否则返回 0
+
+**示例**
+
+```redscript
+if (gtask_ready(0) == 1) { /* handle global event */ }
+```
+
+---
+
+## `scheduler_tick` <Badge type="info" text="v1.0.0" />
+
+每 tick 将所有激活的玩家和全局计时器减 1；在 @tick 函数中调用
+
+```redscript
+fn scheduler_tick()
+```
+
+**示例**
+
+```redscript
+// In your @tick mcfunction:
+scheduler_tick()
+```
+
+---