redscript-mc 3.0.1 → 3.0.2

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

@@ -0,0 +1,185 @@
+# Heap
+
+> 本文档由 `src/stdlib/heap.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [heap_new](#heap-new)
+- [heap_size](#heap-size)
+- [heap_peek](#heap-peek)
+- [heap_push](#heap-push)
+- [heap_pop](#heap-pop)
+- [max_heap_push](#max-heap-push)
+- [max_heap_pop](#max-heap-pop)
+
+---
+
+## `heap_new` <Badge type="info" text="v1.0.0" />
+
+分配一个可容纳 64 个元素的新空堆
+
+```redscript
+fn heap_new(): int[]
+```
+
+**返回：** int[]，h[0]=0（大小），h[1..64] 预分配为零
+
+**示例**
+
+```redscript
+let h: int[] = heap_new()
+```
+
+---
+
+## `heap_size` <Badge type="info" text="v1.0.0" />
+
+返回堆中当前存储的元素数量
+
+```redscript
+fn heap_size(h: int[]): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h` | 由 heap_new 创建的堆数组 |
+
+**返回：** 当前元素数量（h[0]）
+
+**示例**
+
+```redscript
+let sz: int = heap_size(h)
+```
+
+---
+
+## `heap_peek` <Badge type="info" text="v1.0.0" />
+
+查看堆顶元素但不移除（最小堆返回最小值，最大堆返回最大值）
+
+```redscript
+fn heap_peek(h: int[]): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h` | 非空堆数组；前置条件：heap_size(h) > 0 |
+
+**返回：** 堆顶元素（h[1]）
+
+**示例**
+
+```redscript
+let top: int = heap_peek(h)  // peek min without modifying heap
+```
+
+---
+
+## `heap_push` <Badge type="info" text="v1.0.0" />
+
+向最小堆插入一个值
+
+```redscript
+fn heap_push(h: int[], val: int): int[]
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h` | 由 heap_new 创建的堆数组 |
+| `val` | 要插入的值 |
+
+**返回：** 保持堆属性的更新堆数组
+
+**示例**
+
+```redscript
+h = heap_push(h, 42)
+h = heap_push(h, 7)
+// heap_peek(h) == 7
+```
+
+---
+
+## `heap_pop` <Badge type="info" text="v1.0.0" />
+
+移除并丢弃最小堆的最小元素
+
+```redscript
+fn heap_pop(h: int[]): int[]
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h` | 非空最小堆；前置条件：heap_size(h) > 0 |
+
+**返回：** 移除最小值并恢复堆属性的更新堆数组
+
+**示例**
+
+```redscript
+let min_val: int = heap_peek(h)
+h = heap_pop(h)  // remove the minimum
+```
+
+---
+
+## `max_heap_push` <Badge type="info" text="v1.0.0" />
+
+向最大堆插入一个值
+
+```redscript
+fn max_heap_push(h: int[], val: int): int[]
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h` | 由 heap_new 创建的堆数组 |
+| `val` | 要插入的值 |
+
+**返回：** 保持最大堆属性的更新堆数组
+
+**示例**
+
+```redscript
+h = max_heap_push(h, 5)
+h = max_heap_push(h, 99)
+// heap_peek(h) == 99
+```
+
+---
+
+## `max_heap_pop` <Badge type="info" text="v1.0.0" />
+
+移除并丢弃最大堆的最大元素
+
+```redscript
+fn max_heap_pop(h: int[]): int[]
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h` | 非空最大堆；前置条件：heap_size(h) > 0 |
+
+**返回：** 移除最大值并恢复最大堆属性的更新堆数组
+
+**示例**
+
+```redscript
+let max_val: int = heap_peek(h)
+h = max_heap_pop(h)  // remove the maximum
+```
+
+---

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

@@ -0,0 +1,160 @@
+# Interactions
+
+> 本文档由 `src/stdlib/interactions.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [interactions_init](#interactions-init)
+- [on_right_click](#on-right-click)
+- [example_right_click](#example-right-click)
+- [is_sneaking](#is-sneaking)
+- [on_sneak_start](#on-sneak-start)
+- [check_look_up](#check-look-up)
+- [check_look_down](#check-look-down)
+- [check_look_straight](#check-look-straight)
+- [check_holding_item](#check-holding-item)
+- [on_sneak_click](#on-sneak-click)
+- [DOUBLE_TAP_WINDOW](#double-tap-window)
+- [on_double_sneak](#on-double-sneak)
+
+---
+
+## `interactions_init`
+
+初始化本模块所需的计分板目标 `rs.click`、`rs.sneak` 和 `rs.attack`
+
+```redscript
+fn interactions_init()
+```
+
+---
+
+## `on_right_click`
+
+使用 `rs.click` 计分板检测右键，并给检测到的玩家添加 `rs.clicked` 标签
+
+```redscript
+fn on_right_click(callback_fn: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `callback_fn` | 预留的回调标识，当前实现尚未使用 |
+
+---
+
+## `example_right_click`
+
+演示如何直接消费 `rs.click` 计分板并在右键时广播消息
+
+```redscript
+fn example_right_click()
+```
+
+---
+
+## `is_sneaking`
+
+检查目标当前是否处于潜行状态
+
+```redscript
+fn is_sneaking(target: selector) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 要检查的玩家选择器 |
+
+**返回：** 潜行时返回 `1`，否则返回 `0`
+
+---
+
+## `on_sneak_start`
+
+检测玩家是否在当前 tick 开始潜行，并维护 `rs.sneak_start` 标签
+
+```redscript
+fn on_sneak_start()
+```
+
+---
+
+## `check_look_up`
+
+检测玩家是否抬头，并为满足条件者添加 `rs.look_up` 标签
+
+```redscript
+fn check_look_up()
+```
+
+---
+
+## `check_look_down`
+
+检测玩家是否低头，并为满足条件者添加 `rs.look_down` 标签
+
+```redscript
+fn check_look_down()
+```
+
+---
+
+## `check_look_straight`
+
+检测玩家是否平视，并为满足条件者添加 `rs.look_straight` 标签
+
+```redscript
+fn check_look_straight()
+```
+
+---
+
+## `check_holding_item`
+
+预留的手持物检测辅助函数；当前仅输出提示，真实检测需配合谓词或 NBT 检查
+
+```redscript
+fn check_holding_item(item_id: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `item_id` | 期望的物品 ID 或逻辑键名 |
+
+---
+
+## `on_sneak_click`
+
+检测“潜行 + 右键”组合输入，并添加 `rs.sneak_click` 或 `rs.clicked` 标签
+
+```redscript
+fn on_sneak_click()
+```
+
+---
+
+## `DOUBLE_TAP_WINDOW`
+
+双击潜行判定窗口，单位为游戏刻
+
+```redscript
+const DOUBLE_TAP_WINDOW: int = 10;  // 0.5 second
+```
+
+---
+
+## `on_double_sneak`
+
+检测双击潜行；要求调用方自行维护 `rs.last_sneak` 和 `rs.tick`
+
+```redscript
+fn on_double_sneak()
+```
+
+---

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

@@ -0,0 +1,94 @@
+# Inventory
+
+> 本文档由 `src/stdlib/inventory.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [clear_inventory](#clear-inventory)
+- [give_kit_warrior](#give-kit-warrior)
+- [give_kit_archer](#give-kit-archer)
+- [give_kit_mage](#give-kit-mage)
+- [remove_item](#remove-item)
+
+---
+
+## `clear_inventory`
+
+清空目标选择器的全部背包内容
+
+```redscript
+fn clear_inventory(target: selector)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 要清空背包的玩家或实体选择器 |
+
+---
+
+## `give_kit_warrior`
+
+给目标发放战士套装，包含铁甲、近战武器、盾牌和食物
+
+```redscript
+fn give_kit_warrior(target: selector)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 接收套装的玩家或实体选择器 |
+
+---
+
+## `give_kit_archer`
+
+给目标发放弓箭手套装，包含弓箭、轻甲和食物
+
+```redscript
+fn give_kit_archer(target: selector)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 接收套装的玩家或实体选择器 |
+
+---
+
+## `give_kit_mage`
+
+给目标发放法师套装，包含位移、消耗品和范围伤害道具
+
+```redscript
+fn give_kit_mage(target: selector)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 接收套装的玩家或实体选择器 |
+
+---
+
+## `remove_item`
+
+从目标背包中移除指定物品的全部副本
+
+```redscript
+fn remove_item(target: selector, item: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `target` | 要移除物品的玩家或实体选择器 |
+| `item` | 传给 `clear` 命令的物品参数，可包含 NBT |
+
+---