redscript-mc 3.0.1 → 3.0.2

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

@@ -0,0 +1,104 @@
+# Sort
+
+> 本文档由 `src/stdlib/sort.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [insertion_sort](#insertion-sort)
+- [insertion_sort_desc](#insertion-sort-desc)
+- [sort_merge](#sort-merge)
+- [merge_sort_noop](#merge-sort-noop)
+
+---
+
+## `insertion_sort` <Badge type="info" text="v1.0.0" />
+
+就地升序排序整数数组（插入排序，O(n²)，适合 n≤64）
+
+```redscript
+fn insertion_sort(arr: int[], len: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `arr` | 要排序的整数数组（就地修改） |
+| `len` | 要排序的元素数量（arr[0..len-1]） |
+
+**返回：** void — 调用后 arr 升序排列
+
+**示例**
+
+```redscript
+let data: int[] = [30, 10, 50, 20]
+insertion_sort(data, 4)
+// data is now [10, 20, 30, 50]
+```
+
+---
+
+## `insertion_sort_desc` <Badge type="info" text="v1.0.0" />
+
+就地降序排序整数数组（插入排序）
+
+```redscript
+fn insertion_sort_desc(arr: int[], len: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `arr` | 要排序的整数数组（就地修改） |
+| `len` | 要排序的元素数量 |
+
+**返回：** void — 调用后 arr 降序排列
+
+**示例**
+
+```redscript
+let scores: int[] = [30, 10, 50, 20]
+insertion_sort_desc(scores, 4)
+// scores is now [50, 30, 20, 10]
+```
+
+---
+
+## `sort_merge` <Badge type="info" text="v1.0.0" />
+
+将两个已排序数组合并为一个新的排序数组
+
+```redscript
+fn sort_merge(a: int[], la: int, b: int[], lb: int): int[]
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个已排序数组 |
+| `la` | a 的元素数量 |
+| `b` | 第二个已排序数组 |
+| `lb` | b 的元素数量 |
+
+**返回：** 包含 a 和 b 所有元素的新排序 int[]，长度 la+lb
+
+**示例**
+
+```redscript
+let merged: int[] = sort_merge([1, 3, 5], 3, [2, 4, 6], 3)
+// result: [1, 2, 3, 4, 5, 6]
+```
+
+---
+
+## `merge_sort_noop` <Badge type="info" text="v1.0.0" />
+
+Default no-op callback for merge_sort_coro. Replace with your own handler to react when sorting completes.
+
+```redscript
+fn merge_sort_noop()
+```
+
+---

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

@@ -0,0 +1,142 @@
+# Spawn
+
+> 本文档由 `src/stdlib/spawn.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [teleport_to](#teleport-to)
+- [teleport_to_entity](#teleport-to-entity)
+- [spread_players](#spread-players)
+- [gather_all](#gather-all)
+- [launch_up](#launch-up)
+- [goto_lobby](#goto-lobby)
+- [goto_arena](#goto-arena)
+
+---
+
+## `teleport_to`
+
+将目标选择器传送到固定坐标
+
+```redscript
+fn teleport_to(target: selector, x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 要传送的目标选择器 |
+| `x` | 目标 X 坐标 |
+| `y` | 目标 Y 坐标 |
+| `z` | 目标 Z 坐标 |
+
+**示例**
+
+```redscript
+teleport_to(@p, 0, 64, 0)
+```
+
+---
+
+## `teleport_to_entity`
+
+将目标选择器传送到另一个实体当前位置
+
+```redscript
+fn teleport_to_entity(target: selector, dest: selector)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 要传送的目标选择器 |
+| `dest` | 作为目的地的实体选择器 |
+
+---
+
+## `spread_players`
+
+预留的随机分散玩家辅助函数；当前仅输出提示消息，尚未真正执行 spreadplayers
+
+```redscript
+fn spread_players(x: int, z: int, radius: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 中心点 X 坐标 |
+| `z` | 中心点 Z 坐标 |
+| `radius` | 最大分散半径（方块） |
+
+---
+
+## `gather_all`
+
+将所有玩家传送到同一位置
+
+```redscript
+fn gather_all(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 目标 X 坐标 |
+| `y` | 目标 Y 坐标 |
+| `z` | 目标 Z 坐标 |
+
+---
+
+## `launch_up`
+
+按相对坐标将目标向上抬升
+
+```redscript
+fn launch_up(target: selector, height: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 要传送的目标选择器 |
+| `height` | 相对 Y 偏移（方块） |
+
+---
+
+## `goto_lobby`
+
+将目标传送到内置大厅坐标，并显示欢迎标题
+
+```redscript
+fn goto_lobby(target: selector)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 要传送到大厅的目标选择器 |
+
+---
+
+## `goto_arena`
+
+将目标传送到内置竞技场坐标，并显示开战标题
+
+```redscript
+fn goto_arena(target: selector)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 要传送到竞技场的目标选择器 |
+
+---

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

@@ -0,0 +1,134 @@
+# State
+
+> 本文档由 `src/stdlib/state.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [get_state](#get-state)
+- [set_state](#set-state)
+- [is_state](#is-state)
+- [init_state](#init-state)
+- [transition](#transition)
+
+---
+
+## `get_state` <Badge type="info" text="v1.0.0" />
+
+读取实体的当前状态值
+
+```redscript
+fn get_state(entity: selector) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `entity` | 目标实体选择器 |
+
+**返回：** rs.state 中存储的状态值；未初始化时返回 -1
+
+**示例**
+
+```redscript
+let s: int = get_state(@s)
+```
+
+---
+
+## `set_state` <Badge type="info" text="v1.0.0" />
+
+将状态值写入实体
+
+```redscript
+fn set_state(entity: selector, state: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `entity` | 目标实体选择器 |
+| `state` | 要写入的整数状态常量 |
+
+**示例**
+
+```redscript
+set_state(@s, 1)
+```
+
+---
+
+## `is_state` <Badge type="info" text="v1.0.0" />
+
+检查实体当前是否处于指定状态
+
+```redscript
+fn is_state(entity: selector, state: int) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `entity` | 目标实体选择器 |
+| `state` | 要对比的整数状态常量 |
+
+**返回：** 实体处于该状态返回 1，否则返回 0
+
+**示例**
+
+```redscript
+if (is_state(@s, STATE_COMBAT) == 1) { /* per-tick combat logic */ }
+```
+
+---
+
+## `init_state` <Badge type="info" text="v1.0.0" />
+
+仅在实体未初始化时（得分为 -1）写入初始状态，避免覆盖进行中的状态
+
+```redscript
+fn init_state(entity: selector, initial: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `entity` | 目标实体选择器 |
+| `initial` | 未初始化时写入的状态常量 |
+
+**示例**
+
+```redscript
+init_state(@s, STATE_IDLE)
+```
+
+---
+
+## `transition` <Badge type="info" text="v1.0.0" />
+
+仅当实体处于 from 状态时执行受保护的状态转换
+
+```redscript
+fn transition(entity: selector, from: int, to: int) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `entity` | 目标实体选择器 |
+| `from` | 所需的当前状态 |
+| `to` | 目标状态 |
+
+**返回：** 转换成功返回 1；实体不在 from 状态返回 0
+
+**示例**
+
+```redscript
+let ok: int = transition(@s, STATE_IDLE, STATE_COMBAT)
+```
+
+---

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

@@ -0,0 +1,107 @@
+# Strings
+
+> 本文档由 `src/stdlib/strings.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [str_len](#str-len)
+- [str_concat](#str-concat)
+- [str_contains](#str-contains)
+- [str_slice](#str-slice)
+
+---
+
+## `str_len` <Badge type="info" text="v1.0.0" />
+
+返回 rs:strings.{s} 中字符串的长度（MC 限制：普通字符串总返回 1）
+
+```redscript
+fn str_len(s: string) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `s` | rs:strings 中的 NBT 字段名（如 "A"） |
+
+**返回：** 普通字符串返回 1；字符列表返回元素数量
+
+**示例**
+
+```redscript
+str_len("A")  // result: 1 (plain string) or char count (char-list)
+```
+
+---
+
+## `str_concat` <Badge type="info" text="v1.0.0" />
+
+将 rs:strings 中的两个字符串拼接，结果以 NBT 列表形式写入 rs:strings.Result
+
+```redscript
+fn str_concat(a: string, b: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个字符串的 NBT 字段名（如 "A"） |
+| `b` | 第二个字符串的 NBT 字段名（如 "B"） |
+
+**返回：** rs:strings.Result 被设为 [valueA, valueB] 的 NBT 列表
+
+**示例**
+
+```redscript
+str_concat("A", "B")  // rs:strings.Result = ["hello", "world"]
+```
+
+---
+
+## `str_contains` <Badge type="info" text="v1.0.0" />
+
+检测 rs:strings.{s} 是否包含 rs:strings.{sub}（因 MC 限制始终返回 0）
+
+```redscript
+fn str_contains(s: string, sub: string) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `s` | 被搜索字符串的 NBT 字段名 |
+| `sub` | 子字符串的 NBT 字段名 |
+
+**返回：** 0（始终，MC 原生不支持子串搜索）
+
+---
+
+## `str_slice` <Badge type="info" text="v2.2.0" />
+
+从 rs:strings.{s} 中提取子串，写入 rs:strings.Result（需要 MC 1.20.2+）
+
+```redscript
+fn str_slice(s: string, start: int, end: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `s` | 源字符串的 NBT 字段名（如 "A"） |
+| `start` | 起始索引（含，0-based） |
+| `end` | 结束索引（不含，负数从末尾计） |
+
+**返回：** rs:strings.Result 包含提取的子串
+
+**示例**
+
+```redscript
+str_slice("A", 0, 5)   // first 5 chars of rs:strings.A
+str_slice("A", 2, -1)  // drop first 2 and last 1 chars
+```
+
+---