redscript-mc 3.0.0 → 3.0.2

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

@@ -0,0 +1,337 @@
+# Parabola
+
+> 本文档由 `src/stdlib/parabola.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [parabola_gravity](#parabola-gravity)
+- [parabola_gravity_half](#parabola-gravity-half)
+- [parabola_vx](#parabola-vx)
+- [parabola_vy](#parabola-vy)
+- [parabola_vz](#parabola-vz)
+- [parabola_speed_xz](#parabola-speed-xz)
+- [parabola_x](#parabola-x)
+- [parabola_y](#parabola-y)
+- [parabola_z](#parabola-z)
+- [parabola_flight_time](#parabola-flight-time)
+- [parabola_max_height](#parabola-max-height)
+- [parabola_step_vx](#parabola-step-vx)
+- [parabola_step_vy](#parabola-step-vy)
+- [parabola_step_vz](#parabola-step-vz)
+- [parabola_ticks_for_range](#parabola-ticks-for-range)
+- [parabola_in_range](#parabola-in-range)
+
+---
+
+## `parabola_gravity` <Badge type="info" text="v2.0.0" />
+
+每 tick 的 Minecraft 重力加速度（×10000，固定为 800）
+
+```redscript
+fn parabola_gravity(): int
+```
+
+**返回：** 800
+
+---
+
+## `parabola_gravity_half` <Badge type="info" text="v2.0.0" />
+
+每 tick 重力加速度的一半（用于位移公式）
+
+```redscript
+fn parabola_gravity_half(): int
+```
+
+**返回：** 400
+
+---
+
+## `parabola_vx` <Badge type="info" text="v2.0.0" />
+
+计算在 ticks 个 tick 内水平移动 dx 格所需的初始 X 速度（×10000）
+
+```redscript
+fn parabola_vx(dx: int, ticks: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `dx` | X 方向位移（格） |
+| `ticks` | 飞行时间（tick） |
+
+**返回：** 初始 X 速度 ×10000；ticks ≤ 0 时返回 0
+
+**示例**
+
+```redscript
+let vx: int = parabola_vx(10, 20)
+```
+
+---
+
+## `parabola_vy` <Badge type="info" text="v2.0.0" />
+
+计算在 ticks 个 tick 内垂直移动 dy 格所需的初始 Y 速度（×10000）
+
+```redscript
+fn parabola_vy(dy: int, ticks: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `dy` | 垂直位移（格，正值向上） |
+| `ticks` | 飞行时间（tick） |
+
+**返回：** 初始 Y 速度 ×10000；ticks ≤ 0 时返回 0
+
+**示例**
+
+```redscript
+let vy: int = parabola_vy(5, 20)
+```
+
+---
+
+## `parabola_vz` <Badge type="info" text="v2.0.0" />
+
+计算在 ticks 个 tick 内水平移动 dz 格所需的初始 Z 速度（×10000）
+
+```redscript
+fn parabola_vz(dz: int, ticks: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `dz` | Z 方向位移（格） |
+| `ticks` | 飞行时间（tick） |
+
+**返回：** 初始 Z 速度 ×10000；ticks ≤ 0 时返回 0
+
+---
+
+## `parabola_speed_xz` <Badge type="info" text="v2.0.0" />
+
+计算到达 (dx, dz) 所需的水平速度大小（×10000）
+
+```redscript
+fn parabola_speed_xz(dx: int, dz: int, ticks: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `dx` | X 位移（格） |
+| `dz` | Z 位移（格） |
+| `ticks` | 飞行时间（tick） |
+
+**返回：** 水平发射速度 ×10000；ticks ≤ 0 时返回 0
+
+---
+
+## `parabola_x` <Badge type="info" text="v2.0.0" />
+
+在 t tick 时的 X 位置（格）
+
+```redscript
+fn parabola_x(vx0: int, t: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `vx0` | 初始 X 速度 ×10000 |
+| `t` | 已过 tick 数 |
+
+**返回：** X 位移（格）
+
+---
+
+## `parabola_y` <Badge type="info" text="v2.0.0" />
+
+在 t tick 时的 Y 位置（格）
+
+```redscript
+fn parabola_y(vy0: int, t: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `vy0` | 初始 Y 速度 ×10000 |
+| `t` | 已过 tick 数 |
+
+**返回：** Y 位移（格，正值向上）
+
+---
+
+## `parabola_z` <Badge type="info" text="v2.0.0" />
+
+在 t tick 时的 Z 位置（格）
+
+```redscript
+fn parabola_z(vz0: int, t: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `vz0` | 初始 Z 速度 ×10000 |
+| `t` | 已过 tick 数 |
+
+**返回：** Z 位移（格）
+
+---
+
+## `parabola_flight_time` <Badge type="info" text="v2.0.0" />
+
+估算抛体返回发射高度时的 tick 数
+
+```redscript
+fn parabola_flight_time(vy0: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `vy0` | 初始 Y 速度 ×10000 |
+
+**返回：** 飞行时间（tick）；vy0 ≤ 0 时返回 0
+
+**示例**
+
+```redscript
+let t: int = parabola_flight_time(8000)
+```
+
+---
+
+## `parabola_max_height` <Badge type="info" text="v2.0.0" />
+
+抛体高出发射点的最大高度（格）
+
+```redscript
+fn parabola_max_height(vy0: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `vy0` | 初始 Y 速度 ×10000 |
+
+**返回：** 顶点高度（格）；vy0 ≤ 0 时返回 0
+
+**示例**
+
+```redscript
+let h: int = parabola_max_height(8000)
+```
+
+---
+
+## `parabola_step_vx` <Badge type="info" text="v2.0.0" />
+
+对 X 速度施加一 tick 阻力
+
+```redscript
+fn parabola_step_vx(vx: int, drag: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `vx` | 当前 X 速度 ×10000 |
+| `drag` | 阻力系数 ×10000（如 9900 = 0.99 箭矢） |
+
+**返回：** 新 X 速度 ×10000
+
+---
+
+## `parabola_step_vy` <Badge type="info" text="v2.0.0" />
+
+对 Y 速度先施加重力再施加阻力（一 tick）
+
+```redscript
+fn parabola_step_vy(vy: int, drag: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `vy` | 当前 Y 速度 ×10000 |
+| `drag` | 阻力系数 ×10000 |
+
+**返回：** 新 Y 速度 ×10000
+
+---
+
+## `parabola_step_vz` <Badge type="info" text="v2.0.0" />
+
+对 Z 速度施加一 tick 阻力
+
+```redscript
+fn parabola_step_vz(vz: int, drag: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `vz` | 当前 Z 速度 ×10000 |
+| `drag` | 阻力系数 ×10000 |
+
+**返回：** 新 Z 速度 ×10000
+
+---
+
+## `parabola_ticks_for_range` <Badge type="info" text="v2.0.0" />
+
+根据水平距离估算飞行 tick 数（启发式，约 0.8 格/tick 水平速度）
+
+```redscript
+fn parabola_ticks_for_range(range: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `range` | 水平距离（格） |
+
+**返回：** 估算 tick 数（最小为 1）
+
+---
+
+## `parabola_in_range` <Badge type="info" text="v2.0.0" />
+
+检查目标是否在水平射程内
+
+```redscript
+fn parabola_in_range(dx: int, dz: int, max_range: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `dx` | 到目标的 X 位移（格） |
+| `dz` | 到目标的 Z 位移（格） |
+| `max_range` | 最大射程（格） |
+
+**返回：** dist(dx,dz) ≤ max_range 返回 1，否则返回 0
+
+---

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

@@ -0,0 +1,307 @@
+# Particles
+
+> 本文档由 `src/stdlib/particles.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [hearts_at](#hearts-at)
+- [flames](#flames)
+- [smoke](#smoke)
+- [explosion_effect](#explosion-effect)
+- [sparkles_at](#sparkles-at)
+- [angry_at](#angry-at)
+- [happy_at](#happy-at)
+- [portal_effect](#portal-effect)
+- [totem_at](#totem-at)
+- [end_sparkles_at](#end-sparkles-at)
+- [particle_at_fx](#particle-at-fx)
+- [draw_line_2d](#draw-line-2d)
+- [draw_circle](#draw-circle)
+- [draw_helix](#draw-helix)
+- [particle_dot](#particle-dot)
+
+---
+
+## `hearts_at`
+
+在指定坐标生成爱心粒子
+
+```redscript
+fn hearts_at(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标 |
+| `y` | Y 坐标 |
+| `z` | Z 坐标 |
+
+---
+
+## `flames`
+
+在指定坐标生成火焰粒子
+
+```redscript
+fn flames(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标 |
+| `y` | Y 坐标 |
+| `z` | Z 坐标 |
+
+---
+
+## `smoke`
+
+在指定坐标生成大烟雾粒子
+
+```redscript
+fn smoke(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标 |
+| `y` | Y 坐标 |
+| `z` | Z 坐标 |
+
+---
+
+## `explosion_effect`
+
+在指定坐标生成爆炸粒子
+
+```redscript
+fn explosion_effect(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标 |
+| `y` | Y 坐标 |
+| `z` | Z 坐标 |
+
+---
+
+## `sparkles_at`
+
+在指定坐标生成附魔闪烁粒子
+
+```redscript
+fn sparkles_at(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标 |
+| `y` | Y 坐标 |
+| `z` | Z 坐标 |
+
+---
+
+## `angry_at`
+
+在指定坐标生成愤怒村民粒子
+
+```redscript
+fn angry_at(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标 |
+| `y` | Y 坐标 |
+| `z` | Z 坐标 |
+
+---
+
+## `happy_at`
+
+在指定坐标生成开心村民粒子
+
+```redscript
+fn happy_at(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标 |
+| `y` | Y 坐标 |
+| `z` | Z 坐标 |
+
+---
+
+## `portal_effect`
+
+在指定坐标生成传送门粒子
+
+```redscript
+fn portal_effect(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标 |
+| `y` | Y 坐标 |
+| `z` | Z 坐标 |
+
+---
+
+## `totem_at`
+
+在指定坐标生成不死图腾粒子
+
+```redscript
+fn totem_at(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标 |
+| `y` | Y 坐标 |
+| `z` | Z 坐标 |
+
+---
+
+## `end_sparkles_at`
+
+在指定坐标生成末地烛粒子
+
+```redscript
+fn end_sparkles_at(x: int, y: int, z: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标 |
+| `y` | Y 坐标 |
+| `z` | Z 坐标 |
+
+---
+
+## `particle_at_fx`
+
+在以方块 ×100 表示的定点坐标上生成粒子
+
+```redscript
+fn particle_at_fx(x_fx: int, y_fx: int, z_fx: int, particle: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x_fx` | X 坐标（方块 ×100） |
+| `y_fx` | Y 坐标（方块 ×100） |
+| `z_fx` | Z 坐标（方块 ×100） |
+| `particle` | 粒子 ID，如 `minecraft:flame` |
+
+---
+
+## `draw_line_2d`
+
+使用线性插值绘制二维粒子直线
+
+```redscript
+fn draw_line_2d(x0: int, y0: int, x1: int, y1: int, steps: int, z: int, particle: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x0` | 起点 X（方块 ×100） |
+| `y0` | 起点 Y（方块 ×100） |
+| `x1` | 终点 X（方块 ×100） |
+| `y1` | 终点 Y（方块 ×100） |
+| `steps` | 插值步数 |
+| `z` | 所在 Z 平面（方块 ×100） |
+| `particle` | 粒子 ID |
+
+---
+
+## `draw_circle`
+
+在 XZ 平面绘制粒子圆环
+
+```redscript
+fn draw_circle(cx: int, cy: int, cz: int, r: int, steps: int, particle: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `cx` | 圆心 X（方块） |
+| `cy` | 圆心 Y（方块） |
+| `cz` | 圆心 Z（方块） |
+| `r` | 半径（方块 ×100） |
+| `steps` | 采样点数量 |
+| `particle` | 粒子 ID |
+
+---
+
+## `draw_helix`
+
+绘制可配置半径、高度和圈数的粒子螺旋
+
+```redscript
+fn draw_helix(cx: int, cy_start: int, cz: int, r: int, height: int, rotations: int, steps: int, particle: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `cx` | 中心 X（方块） |
+| `cy_start` | 起始 Y（方块） |
+| `cz` | 中心 Z（方块） |
+| `r` | 半径（方块 ×100） |
+| `height` | 总高度（方块） |
+| `rotations` | 完整旋转圈数 |
+| `steps` | 采样点数量 |
+| `particle` | 粒子 ID |
+
+---
+
+## `particle_dot`
+
+在整数方块坐标生成单个粒子
+
+```redscript
+fn particle_dot(x: int, y: int, z: int, particle: string)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | X 坐标（整数方块） |
+| `y` | Y 坐标（整数方块） |
+| `z` | Z 坐标（整数方块） |
+| `particle` | 粒子 ID |
+
+---