From 66672f51887c8f9cf3f2af5cb68deef19a57a37d Mon Sep 17 00:00:00 2001
From: bottlefish <781230111@qq.com>
Date: Sat, 11 Jul 2026 12:32:17 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E9=A3=8E=E7=AD=9D?=
 =?UTF-8?q?=E5=91=BD=E4=BB=A4=E4=BD=BF=E7=94=A8=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 Docs/风筝命令使用指南.md | 113 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 Docs/风筝命令使用指南.md

diff --git a/Docs/风筝命令使用指南.md b/Docs/风筝命令使用指南.md
new file mode 100644
index 000000000..d49c7a9b3
--- /dev/null
+++ b/Docs/风筝命令使用指南.md
@@ -0,0 +1,113 @@
+# 风筝 Yarn 命令使用指南
+
+适用范围：`Assets/Yarn/FP/FP_Day2_sleep/FP_Day2_sleep.yarn` 的 `风筝1` / `风筝2` 节点。
+
+## 背景
+
+放风筝段落原来用 `D2S风筝1/2/3` 三张切图按高度阈值硬切，跨阈值时尺寸跳变，且节点顶部的常驻动效会覆盖选项里的一次性反馈。现已改为**单张风筝图 + 连续参数驱动**，不再使用切图。
+
+实现在 [`SpriteShowcase.cs`](../Assets/Scripts/SceneManagement/SpriteShowcase.cs) 的“风筝 Rig”区域（`#region 风筝 Rig`），命令注册在 [`BaseYarnCommand.cs`](../Assets/Scripts/Dialog%20System/BaseYarnCommand.cs)。
+
+### Rig 结构
+
+```
+Kite Rig（高度层：缩放 + 位移，对应 $h）
+ └─ Kite Sway（风况层：常驻循环，对应 $wind / 乱度）
+     └─ Kite Accent（顿挫层：一次性动效 + 实际 SpriteRenderer）
+
+Kite Base（白色底图，独立静态节点，不随高度缩放）
+Kite Mask（SpriteMask，以底图为形状，风筝层被裁在天空范围内）
+```
+
+三层动效各自持有独立 Tween，互不 `Kill`，所以选项里的一次性顿挫不会被节点顶部的常驻风况覆盖掉。
+
+只用到两张图（Addressable key `Sprite/梦境/{图名}`）：
+
+- `D2S风筝1_风筝层`：风筝本体，挂在顶层可动。
+- `D2S风筝1_底图`：白色天空底图，静态显示 + 兼作遮罩形状。
+
+`D2S风筝2/3/4/5` 全套图不再使用（文件保留，未删除）。
+
+## 命令一览
+
+| 命令 | 签名 | 说明 |
+|---|---|---|
+| `kite_show` | `height=0 wind=0 duration=0.35` | 显示风筝 Rig。若已显示则等价于 `kite_state`（幂等）。会顺带隐藏正在显示的小图/大图。**总是把乱度重置为平稳**，之后要乱流需再调 `kite_wind`。 |
+| `kite_state` | `height wind duration=0.9 leadDuration=0.35` | 高度补间（缩放+位移，**每次选择的主反馈**）+ 按当前乱度重放风况循环。`leadDuration` 是命令返回前的等待时间，一般不用传。 |
+| `kite_wind` | `wind turbulence=-1` | 只切换风况循环，不改变高度。用于在选项出现**之前** telegraph 风况，让玩家读画面做判断。 |
+| `kite_accent` | `profile leadDuration=0.18` | 播放一次性顿挫动效，叠加在顶层，结束后自动回到原位，不打断高度/风况补间。 |
+| `kite_hide` | `duration=1` | 隐藏风筝 Rig（含底图、遮罩）。 |
+
+### 参数含义
+
+- `height` 对应 Yarn 变量 `$h`，范围会被 clamp 到 `[0, 13]`。缩放曲线是 `0.84^height`，且不低于 12%（避免缩到看不见）。
+- `wind` 对应 Yarn 变量 `$wind`：`1` 强风 / `0` 无风 / `-1` 风弱。
+- `turbulence`（乱度）范围 `0~1`，**默认表示平稳（0），不是“保持不变”**：
+  - 省略或传负数 → 平稳，风筝沿 CatmullRom 曲线大而缓地漫游（有风时顶风侧倾巡游，无风时自由漂，风弱时缓缓下坠），绝不抖动。
+  - 传正数 → 阵风：静一下 → 猛地被拽走一截（位移+旋转，X/Y 不同步走出弧线）→ 慢慢荡回 → 再来一阵。**每一阵的方向、力度、间隔都是随机的，节奏不重复**；数值越大拉扯越猛、间隔越短，乱度 ≥0.7 时还会概率性甩过头再弹回，读出“失控”。
+  - **乱度是粘滞的**：由 `kite_wind` 显式设定后会保留，后续 `kite_state` 只切高度和风向，仍沿用当前乱度，直到下一次 `kite_wind` 改变它。`kite_show` 会把乱度重置为 0。
+
+### `kite_accent` 支持的 profile
+
+| profile | 效果 | 典型使用场景 |
+|---|---|---|
+| `lift` | 上冲后回落 | 放线时风筝被吹高 |
+| `sink` | 下坠沉降 | 收线、风弱掉高度 |
+| `taut` | 猛地扯直，然后绷住小幅慢速拉锯（不是震动） | 线绷紧、风大顶线 |
+| `drop` | 猛地下坠（比 sink 更快更急） | 风筝真的掉下去了 |
+| `flutter` | 左右交替的几下小拉扯，力度递减 | 保持不动、原地挣扎 |
+
+轱辘特写（`D2S轱辘`）不属于这套 Rig，仍用旧的 `<<show_sprite_motion "D2S轱辘" "reel_tension" duration>>`，动效在 `SpriteShowcase.PlaySmallMotion` / `PlayReelHold` 里维护：先被猛地拽进受力姿态（只进一次），之后绷在那里持续高频颤抖，偶尔再被拽深一点——是“全力拉住”的发力感，不会松回原位。
+
+## 典型用法模式
+
+### 1. 进入风筝段落：`kite_show`
+
+```yarn
+<<if $t==0>>
+    <<fade_in 1>>
+    <<kite_show 1 0 0.35>>
+    <<fade_out 1>>
+```
+
+首次显示传初始高度/风向，乱度自动是平稳的。
+
+### 2. 每轮风况变化：先 `kite_wind` 让画面 telegraph，再给选项
+
+`风筝2` 节点里，每次 `<<set $wind=...>>` 之后紧跟一次 `kite_wind`，选项出现前画面已经在演风况了：
+
+```yarn
+<<elseif $t==5>>
+    <<set $wind=1>>
+    <<kite_wind {$wind} 0.55>>
+    me: 风…好像停了。好像…没有什么规律。 #line:0c86a64
+    ...
+    <<kite_accent flutter>>
+    风筝开始抖动起来。手上感受到的拉力变大、变乱了。  #line:09afac0
+```
+
+**乱度取值要对着台词**：台词说“平稳/懒洋洋”就不传乱度（或传 0）；台词明确说“乱”“没有规律”“胡乱刮着”才传正数，且数值随描述的混乱程度递增（本节点里 0.55 → 0.8 → 0.95 → 1，逐轮加码）。
+
+### 3. 选项分支：`kite_state` 是主反馈，`kite_accent` 是点缀
+
+```yarn
+->放线  #line:08c3eee
+    <<if $wind==1>>
+        <<set $h = $h + 1>>
+        <<kite_state {$h} {$wind}>>
+        <<kite_accent lift>>
+        风把风筝吹得越来越高，越来越远。  #line:001a06f
+```
+
+先改 `$h`，再调用 `kite_state {$h} {$wind}` 让缩放/位置连续补间过去（这是玩家能感知到的主要反馈），再叠加一个短促的 `kite_accent` 强调这次选择的性质。乱度不用每次都传，`kite_state` 会沿用当前乱度。
+
+### 4. 离场：`kite_hide` 或让互斥逻辑自动处理
+
+风筝 Rig 已经接入 `ShowObj` / `ShowObjWithMotion` / `ShowLargeObj` / `HideObj` / `HideAll` 的互斥逻辑，切到大图或普通小图时会自动隐藏，不必每次手动 `kite_hide`。只有明确要求“风筝消失但暂不显示别的图”时才需要显式调用。
+
+## 常见坑
+
+- **忘记补 `kite_wind` 就直接改 `$wind` 用于选项判断**：`$wind` 变量本身不会驱动画面，画面只认 `kite_wind`/`kite_state` 里传入的 `wind` 参数。改了变量务必配一次画面调用，否则玩家看不出风况变了。
+- **乱度传太随意**：乱度是“文本说乱才乱”，不要在台词写“平稳”“懒洋洋”的段落里传正数乱度，也不要在台词强调失控时仍用默认的 0。
+- **以为 `kite_state` 会重置乱度**：不会，乱度只由 `kite_wind` 改变。如果需要在同一句里既改高度又改乱度，要显式调用两条命令（先 `kite_wind` 定乱度，再 `kite_state` 走高度）。
+- **给风筝以外的图误用 `kite_*` 命令**：这套 Rig 硬编码只加载 `D2S风筝1_风筝层` / `D2S风筝1_底图`，不接受图名参数，不能拿来做别的分层动效——别的分层动效（如轱辘）继续用 `show_sprite_motion`/`sprite_motion`。