redscript-mc 3.0.1 → 3.0.2

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

@@ -0,0 +1,353 @@
+# Color
+
+> 本文档由 `src/stdlib/color.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [rgb_pack](#rgb-pack)
+- [rgb_r](#rgb-r)
+- [rgb_g](#rgb-g)
+- [rgb_b](#rgb-b)
+- [rgb_lerp](#rgb-lerp)
+- [rgb_to_l](#rgb-to-l)
+- [rgb_to_s](#rgb-to-s)
+- [rgb_to_h](#rgb-to-h)
+- [hsl_to_r](#hsl-to-r)
+- [hsl_to_g](#hsl-to-g)
+- [hsl_to_b](#hsl-to-b)
+- [hsl_to_packed](#hsl-to-packed)
+- [rgb_to_hex](#rgb-to-hex)
+
+---
+
+## `rgb_pack` <Badge type="info" text="v1.0.0" />
+
+将 RGB 分量打包为单个整数（0xRRGGBB 格式）
+
+```redscript
+fn rgb_pack(r: int, g: int, b: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `r` | 红色通道，范围 [0, 255] |
+| `g` | 绿色通道，范围 [0, 255] |
+| `b` | 蓝色通道，范围 [0, 255] |
+
+**返回：** r*65536 + g*256 + b
+
+**示例**
+
+```redscript
+let red: int = rgb_pack(255, 0, 0)  // result: 16711680 (0xFF0000)
+```
+
+---
+
+## `rgb_r` <Badge type="info" text="v1.0.0" />
+
+从打包 RGB 整数中提取红色分量
+
+```redscript
+fn rgb_r(packed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `packed` | 打包颜色整数（0xRRGGBB） |
+
+**返回：** 红色通道值，范围 [0, 255]
+
+**示例**
+
+```redscript
+let r: int = rgb_r(16711680)  // result: 255
+```
+
+---
+
+## `rgb_g` <Badge type="info" text="v1.0.0" />
+
+从打包 RGB 整数中提取绿色分量
+
+```redscript
+fn rgb_g(packed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `packed` | 打包颜色整数（0xRRGGBB） |
+
+**返回：** 绿色通道值，范围 [0, 255]
+
+**示例**
+
+```redscript
+let g: int = rgb_g(65280)  // result: 255 (0x00FF00)
+```
+
+---
+
+## `rgb_b` <Badge type="info" text="v1.0.0" />
+
+从打包 RGB 整数中提取蓝色分量
+
+```redscript
+fn rgb_b(packed: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `packed` | 打包颜色整数（0xRRGGBB） |
+
+**返回：** 蓝色通道值，范围 [0, 255]
+
+**示例**
+
+```redscript
+let b: int = rgb_b(255)  // result: 255 (0x0000FF)
+```
+
+---
+
+## `rgb_lerp` <Badge type="info" text="v1.0.0" />
+
+两个打包 RGB 颜色之间的线性插值
+
+```redscript
+fn rgb_lerp(a: int, b: int, t: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 起始颜色（打包 0xRRGGBB） |
+| `b` | 结束颜色（打包 0xRRGGBB） |
+| `t` | 混合因子，范围 [0, 1000]（0=a，1000=b） |
+
+**返回：** a 和 b 之间插值得到的打包 RGB 颜色
+
+**示例**
+
+```redscript
+let mid: int = rgb_lerp(0xFF0000, 0x0000FF, 500)  // halfway between red and blue
+```
+
+---
+
+## `rgb_to_l` <Badge type="info" text="v1.0.0" />
+
+从 RGB 分量计算 HSL 亮度（×10000 精度）
+
+```redscript
+fn rgb_to_l(r: int, g: int, b: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `r` | 红色 ×10000，范围 [0, 2550000] |
+| `g` | 绿色 ×10000 |
+| `b` | 蓝色 ×10000 |
+
+**返回：** 亮度，范围 [0, 10000]（0=黑，10000=白）
+
+**示例**
+
+```redscript
+let l: int = rgb_to_l(2550000, 2550000, 2550000)  // result: 10000 (white)
+```
+
+---
+
+## `rgb_to_s` <Badge type="info" text="v1.0.0" />
+
+从 RGB 分量计算 HSL 饱和度（×10000 精度）
+
+```redscript
+fn rgb_to_s(r: int, g: int, b: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `r` | 红色 ×10000 |
+| `g` | 绿色 ×10000 |
+| `b` | 蓝色 ×10000 |
+
+**返回：** 饱和度，范围 [0, 10000]（0=灰，10000=全饱和）
+
+**示例**
+
+```redscript
+let s: int = rgb_to_s(2550000, 0, 0)  // result: 10000 (pure red is fully saturated)
+```
+
+---
+
+## `rgb_to_h` <Badge type="info" text="v1.0.0" />
+
+从 RGB 分量计算 HSL 色相（×10000 精度）
+
+```redscript
+fn rgb_to_h(r: int, g: int, b: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `r` | 红色 ×10000 |
+| `g` | 绿色 ×10000 |
+| `b` | 蓝色 ×10000 |
+
+**返回：** 色相，范围 [0, 3600000]（度×10000；0=红，1200000=绿，2400000=蓝）
+
+**示例**
+
+```redscript
+let h: int = rgb_to_h(0, 2550000, 0)  // result: 1200000 (120°, pure green)
+```
+
+---
+
+## `hsl_to_r` <Badge type="info" text="v1.0.0" />
+
+Convert HSL to the red channel of RGB (×10000 scale).
+
+```redscript
+fn hsl_to_r(h: int, s: int, l: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h` | Hue ×10000, range [0, 3600000] |
+| `s` | Saturation ×10000, range [0, 10000] |
+| `l` | Lightness ×10000, range [0, 10000] |
+
+**返回：** Red channel ×10000, range [0, 2550000]; divide by 10000 for 0-255
+
+**示例**
+
+```redscript
+let r: int = hsl_to_r(0, 10000, 5000)  // pure red → 2550000
+```
+
+---
+
+## `hsl_to_g` <Badge type="info" text="v1.0.0" />
+
+Convert HSL to the green channel of RGB (×10000 scale).
+
+```redscript
+fn hsl_to_g(h: int, s: int, l: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h` | Hue ×10000, range [0, 3600000] |
+| `s` | Saturation ×10000, range [0, 10000] |
+| `l` | Lightness ×10000, range [0, 10000] |
+
+**返回：** Green channel ×10000, range [0, 2550000]
+
+**示例**
+
+```redscript
+let g: int = hsl_to_g(1200000, 10000, 5000)  // pure green → 2550000
+```
+
+---
+
+## `hsl_to_b` <Badge type="info" text="v1.0.0" />
+
+Convert HSL to the blue channel of RGB (×10000 scale).
+
+```redscript
+fn hsl_to_b(h: int, s: int, l: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h` | Hue ×10000, range [0, 3600000] |
+| `s` | Saturation ×10000, range [0, 10000] |
+| `l` | Lightness ×10000, range [0, 10000] |
+
+**返回：** Blue channel ×10000, range [0, 2550000]
+
+**示例**
+
+```redscript
+let b: int = hsl_to_b(2400000, 10000, 5000)  // pure blue → 2550000
+```
+
+---
+
+## `hsl_to_packed` <Badge type="info" text="v1.0.0" />
+
+将 HSL（×10000 精度）转换为打包 RGB 整数（0xRRGGBB）
+
+```redscript
+fn hsl_to_packed(h: int, s: int, l: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `h` | 色相 ×10000，范围 [0, 3600000] |
+| `s` | 饱和度 ×10000，范围 [0, 10000] |
+| `l` | 亮度 ×10000，范围 [0, 10000] |
+
+**返回：** 打包 RGB 整数，每通道 0-255
+
+**示例**
+
+```redscript
+let col: int = hsl_to_packed(0, 10000, 5000)  // pure red → 0xFF0000
+```
+
+---
+
+## `rgb_to_hex` <Badge type="info" text="v1.0.0" />
+
+Pack RGB into a 0xRRGGBB integer (alias for rgb_pack with explicit naming).
+
+```redscript
+fn rgb_to_hex(r: int, g: int, b: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `r` | Red channel, range [0, 255] |
+| `g` | Green channel, range [0, 255] |
+| `b` | Blue channel, range [0, 255] |
+
+**返回：** r*65536 + g*256 + b (same as rgb_pack)
+
+**示例**
+
+```redscript
+let hex: int = rgb_to_hex(0, 128, 255)  // result: 32895 (0x0080FF)
+```
+
+---

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

@@ -0,0 +1,88 @@
+# Combat
+
+> 本文档由 `src/stdlib/combat.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [weapon_damage](#weapon-damage)
+- [take_damage](#take-damage)
+- [is_dead](#is-dead)
+
+---
+
+## `weapon_damage` <Badge type="info" text="v1.0.0" />
+
+计算武器基础伤害加上加成的总伤害
+
+```redscript
+fn weapon_damage(base: int, bonus: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `base` | 武器基础伤害值 |
+| `bonus` | 额外伤害修饰（如附魔或增益） |
+
+**返回：** base + bonus
+
+**示例**
+
+```redscript
+let dmg: int = weapon_damage(10, 5)  // result: 15
+```
+
+---
+
+## `take_damage` <Badge type="info" text="v1.0.0" />
+
+对生命值应用伤害，结果最低为 0
+
+```redscript
+fn take_damage(health: int, amount: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `health` | 当前生命值（如来自计分板） |
+| `amount` | 要扣减的伤害量 |
+
+**返回：** health - amount，最低为 0；调用后用 scoreboard_set 写回
+
+**示例**
+
+```redscript
+let new_hp: int = take_damage(current_hp, 8)
+scoreboard_set(@p, #health, new_hp)
+```
+
+---
+
+## `is_dead` <Badge type="info" text="v1.0.0" />
+
+判断实体是否已死亡（生命值 <= 0）
+
+```redscript
+fn is_dead(health: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `health` | 要判断的当前生命值 |
+
+**返回：** 若 health <= 0 则返回 1（已死亡），否则返回 0（存活）
+
+**示例**
+
+```redscript
+if (is_dead(current_hp) == 1) {
+    // trigger death logic
+}
+```
+
+---

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

@@ -0,0 +1,84 @@
+# Cooldown
+
+> 本文档由 `src/stdlib/cooldown.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [cooldown_start](#cooldown-start)
+- [cooldown_ready](#cooldown-ready)
+- [cooldown_tick](#cooldown-tick)
+
+---
+
+## `cooldown_start` <Badge type="info" text="v1.2.0" />
+
+启动（或重启）指定槽位的冷却计时，持续 ticks 游戏刻。
+
+```redscript
+fn cooldown_start(name: string, ticks: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `name` | 冷却槽位标识符（保留，供未来多槽位使用） |
+| `ticks` | 冷却持续时间（游戏刻，20 刻 = 1 秒） |
+
+**返回：** 无返回值
+
+**示例**
+
+```redscript
+cooldown_start("sword", 40); // 2-second cooldown
+```
+
+---
+
+## `cooldown_ready` <Badge type="info" text="v1.2.0" />
+
+检查冷却是否已到期（可再次触发）。
+
+```redscript
+fn cooldown_ready(name: string) -> int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `name` | 冷却槽位标识符 |
+
+**返回：** 1 表示已就绪（非活跃或剩余刻数 ≤ 0），0 表示仍在冷却
+
+**示例**
+
+```redscript
+if (cooldown_ready("sword") == 1) { attack(); cooldown_start("sword", 40); }
+```
+
+---
+
+## `cooldown_tick` <Badge type="info" text="v1.2.0" />
+
+冷却计时推进一刻，须在 @tick 函数中每刻调用。剩余刻数归零时自动标记为非活跃。
+
+```redscript
+fn cooldown_tick(name: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `name` | 冷却槽位标识符 |
+
+**返回：** 无返回值
+
+**示例**
+
+```redscript
+@tick fn game_tick() { cooldown_tick("sword"); }
+```
+
+---

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

@@ -0,0 +1,152 @@
+# Dialog
+
+> 本文档由 `src/stdlib/dialog.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [dialog_say](#dialog-say)
+- [dialog_broadcast](#dialog-broadcast)
+- [dialog_say_color](#dialog-say-color)
+- [dialog_title](#dialog-title)
+- [dialog_title_clear](#dialog-title-clear)
+- [dialog_actionbar](#dialog-actionbar)
+
+---
+
+## `dialog_say` <Badge type="info" text="v1.0.0" />
+
+向玩家或选择器发送一条纯白色聊天消息
+
+```redscript
+fn dialog_say(p: selector, msg: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `p` | 接收者选择器 |
+| `msg` | 纯文本消息内容 |
+
+**示例**
+
+```redscript
+dialog_say(@p, "Quest updated")
+```
+
+---
+
+## `dialog_broadcast` <Badge type="info" text="v1.0.0" />
+
+向所有玩家广播一条纯白色聊天消息
+
+```redscript
+fn dialog_broadcast(msg: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `msg` | 纯文本消息内容 |
+
+**示例**
+
+```redscript
+dialog_broadcast("Server restart in 60 seconds")
+```
+
+---
+
+## `dialog_say_color` <Badge type="info" text="v1.0.0" />
+
+向玩家或选择器发送带颜色的聊天消息，未知颜色值会回退为白色
+
+```redscript
+fn dialog_say_color(p: selector, msg: string, color: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `p` | 接收者选择器 |
+| `msg` | 纯文本消息内容 |
+| `color` | 颜色编号（0=white, 1=red, 2=green, 3=gold, 4=aqua） |
+
+**示例**
+
+```redscript
+dialog_say_color(@s, "You died!", 1)
+```
+
+---
+
+## `dialog_title` <Badge type="info" text="v1.0.0" />
+
+在玩家屏幕上显示标题和副标题
+
+```redscript
+fn dialog_title(p: selector, title: string, subtitle: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `p` | 接收者选择器 |
+| `title` | 主标题文本 |
+| `subtitle` | 副标题文本 |
+
+**示例**
+
+```redscript
+dialog_title(@s, "Stage 2", "Defeat the boss")
+```
+
+---
+
+## `dialog_title_clear` <Badge type="info" text="v1.0.0" />
+
+清除目标当前显示的标题
+
+```redscript
+fn dialog_title_clear(p: selector)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `p` | 接收者选择器 |
+
+**示例**
+
+```redscript
+dialog_title_clear(@s)
+```
+
+---
+
+## `dialog_actionbar` <Badge type="info" text="v1.0.0" />
+
+在玩家动作栏显示一条短消息
+
+```redscript
+fn dialog_actionbar(p: selector, msg: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `p` | 接收者选择器 |
+| `msg` | 纯文本消息内容 |
+
+**示例**
+
+```redscript
+dialog_actionbar(@s, "Mana: 80/100")
+```
+
+---