game-cards/docs/superpowers/specs/2026-06-02-hand-wrap-and-play-animation-design.md

# 手牌换行 + 出牌动画 + 点评 — 设计规格

**日期：** 2026-06-02
**范围：** 训练模式 UI 改进
**相关模块：** `src/ui/components/hand_area.*`、`src/ui/scenes/training_room.*`

---

## 一、目标

解决训练模式当前三个 UX 问题：

1. **手牌溢出：** 起手 27 张牌在 1280×720 视口下，水平方向硬滚动 2200px 才能看完，竖直方向空闲（320px 高度只用了 110px）。
2. **出牌零反馈：** `_show_table_cards()` 直接 `position =` 赋值给桌牌，玩家无视觉引导，从手牌"跳"到桌面。
3. **缺点评信息：** 玩家只能从 `status_label` 看到 "玩家X 出了 牌型（N张）"，没有主阶、动作质量等结构化信息。

实现后达到：
- 手牌自动两行（极端窄屏可滚动至 3+ 行）
- 出牌有"飞牌 + 缩放"动画
- 桌面上方有"基础点评"浮层（牌型 + 张数 + 主阶）

---

## 二、范围与非目标

### 范围内
- `hand_area.tscn` / `hand_area.gd`：HBoxContainer → FlowContainer；手牌渲染前按 rank+suit 排序
- `training_room.tscn` / `training_room.gd`：新增 CommentaryLabel + TableCardRoot；重写 `_on_cards_played()` 串行执行"飞行 → 桌牌 → 点评 fade"
- 验证：手动跑 Godot + 截图比对

### 非目标（YAGNI）
- 扇形/重叠手牌布局（设计文档 8.1.1 描述的「重叠率 50-65%」）—— 工作量与改动面远超本次范围
- AI 评分驱动的增强点评（"✓ 优解 / ✗ 浪费" 标签）—— 留作后续
- 音效（`AudioManager.play_card_place()` 仍为 `pass`）—— 与本次无耦合
- 复杂的多张牌并发动画（炸弹/连对的"分组飞入"）—— 本次只做线性整体飞行
- 移动端拖拽框选、V-Filtering、智能理牌折叠 —— 后续 UI 阶段

---

## 三、架构

```
UI 层 (Godot)              业务逻辑层 (core/)
─────────                  ────────────────
training_room.gd           GameState (零改动)
  ├─ _on_cards_played()
  │   ├─ 取源位置 (hand_area.card_nodes)
  │   ├─ ghost 飞行 tween
  │   ├─ 桌牌替换 ghost
  │   ├─ 点评 fade in
  │   └─ 点评 fade out + 清桌 + 刷新手牌
  └─ _show_commentary()
      └─ 直接读 EvaluatedPlay {type, cards, primary_rank}
                          hand_evaluator.gd (零改动)
                          rule_engine.gd (零改动)
```

**约束：** 业务逻辑层零改动。动画/点评是纯表现，违反此约束的设计直接否决。

---

## 四、详细设计

### 4.1 手牌换行（FlowContainer）

#### 4.1.1 场景文件改动

`src/ui/components/hand_area.tscn`（场景根节点）：

```diff
-[node name="HandArea" type="HBoxContainer"]
-offset_right = 800.0
-offset_bottom = 150.0
-script = ExtResource("1_script")
+[node name="HandArea" type="FlowContainer"]
+script = ExtResource("1_script")
```

`src/ui/scenes/training_room.tscn`（HandArea 实例的 type 也要改）：

```diff
-[node name="HandArea" type="HBoxContainer" parent="ScrollContainer"]
+[node name="HandArea" type="FlowContainer" parent="ScrollContainer"]
 layout_mode = 2
-size_flags_horizontal = 0
+size_flags_horizontal = 3
 script = ExtResource("2_script")
-custom_minimum_size = Vector2(2200, 140)
+custom_minimum_size = Vector2(1240, 200)
```

`src/ui/scenes/training_room.tscn` — ScrollContainer 区域：

```diff
[node name="ScrollContainer" type="ScrollContainer" parent="."]
offset_top = 380.0
offset_right = 1280.0
-offset_bottom = 520.0
+offset_bottom = 660.0
-horizontal_scroll_mode = 2
-vertical_scroll_mode = 0
+horizontal_scroll_mode = 0
+vertical_scroll_mode = 2
```

新增节点：

```ini
[node name="CommentaryLabel" type="Label" parent="."]
layout_mode = 0
offset_top = 360.0
offset_right = 1280.0
offset_bottom = 380.0
horizontal_alignment = 1
modulate = Color(1, 1, 1, 0)

[node name="TableCardRoot" type="Control" parent="."]
layout_mode = 0
offset_top = 85.0
offset_right = 1280.0
offset_bottom = 370.0
mouse_filter = 2
```

#### 4.1.2 脚本改动

`src/ui/components/hand_area.gd`：

```gdscript
class_name HandArea
extends FlowContainer  # HBoxContainer → FlowContainer
# ... 字段、信号、其它方法保持不变 ...

func update_hand(hand: Array) -> void:
    for cn in card_nodes:
        cn.queue_free()
    card_nodes.clear()
    selected_cards.clear()

    # 副本排序，不污染 GameState.player_hands
    var sorted_hand: Array[Card] = []
    for c in hand:
        sorted_hand.append(c)
    sorted_hand.sort_custom(func(a: Card, b: Card): return a.compare_to(b) < 0)

    for c in sorted_hand:
        var node := CARD_SCENE.instantiate() as CardNode
        if node == null:
            continue
        add_child(node)
        node.setup(c)
        node.card_clicked.connect(_on_card_clicked)
        node.card_double_clicked.connect(_on_card_double_clicked)
        card_nodes.append(node)
```

**为什么副本排序：** 设计文档 §一"禁止共享引用"约束。所有 getter 返回副本或只读包装，手牌区显示需要排序则不能直接修改 `GameState.player_hands[0]`。

### 4.2 出牌动画 + 点评

#### 4.2.1 常量

`src/ui/scenes/training_room.gd` 顶部：

```gdscript
const FLIGHT_DURATION := 0.30   # 飞行 + 缩放时长
const COMMENTARY_FADE_IN := 0.20
const COMMENTARY_HOLD   := 0.60
const COMMENTARY_FADE_OUT := 0.30
```

#### 4.2.2 新增 @onready 引用

```gdscript
@onready var commentary_label: Label = $CommentaryLabel
@onready var table_card_root: Control = $TableCardRoot
```

#### 4.2.3 `_on_cards_played()` 重写

```gdscript
func _on_cards_played(player_idx: int, play: HandEvaluator.EvaluatedPlay) -> void:
    hand_area.disable_input()

    # 1. 排序（与现有 _show_table_cards 行为一致）
    var sorted_cards: Array[Card] = []
    for c in play.cards:
        sorted_cards.append(c)
    sorted_cards.sort_custom(func(a: Card, b: Card): return a.compare_to(b) < 0)

    # 2. 计算目标位置（中央对齐）
    var card_w := 60.0
    var total_w := card_w * sorted_cards.size()
    var start_x := (1280.0 - total_w) / 2.0
    var table_y := 80.0   # table_card_root 内坐标（与原 _show_table_cards 的 y=80 保持一致）

    # 3. 生成 ghost 卡牌 + 飞行 tween
    var ghosts: Array[CardNode] = []
    var targets: Array[Vector2] = []

    for i in range(sorted_cards.size()):
        var src_node := _find_hand_node(sorted_cards[i])
        var src_pos := src_node.global_position if src_node else Vector2(start_x + i*card_w, 600.0)

        var ghost := CARD_NODE_SCENE.instantiate() as CardNode
        get_tree().root.add_child(ghost)  # 关键：加到根节点，不受 FlowContainer 重排
        ghost.setup(sorted_cards[i])
        ghost.global_position = src_pos
        ghost.mouse_filter = Control.MOUSE_FILTER_IGNORE
        ghosts.append(ghost)
        targets.append(Vector2(start_x + i*card_w, table_y))

    for i in range(ghosts.size()):
        var g := ghosts[i]
        var t := create_tween().set_parallel(true)
        t.tween_property(g, "global_position", targets[i], FLIGHT_DURATION)\
            .set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_OUT)
        t.tween_property(g, "scale", Vector2(0.7, 0.7), FLIGHT_DURATION)\
            .set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_IN)

    await get_tree().create_timer(FLIGHT_DURATION).timeout

    # 4. 收起 ghost，桌牌出现
    for g in ghosts:
        g.queue_free()
    _show_table_cards(sorted_cards)

    # 5. 点评 fade in
    _show_commentary(player_idx, play)
    await get_tree().create_timer(COMMENTARY_HOLD).timeout

    # 6. 点评 fade out
    var fade := create_tween()
    fade.tween_property(commentary_label, "modulate:a", 0.0, COMMENTARY_FADE_OUT)
    await get_tree().create_timer(COMMENTARY_FADE_OUT).timeout

    # 7. 清桌 + 刷新手牌
    _clear_table_cards()
    _refresh_ui()
```

#### 4.2.4 新增辅助方法

```gdscript
func _show_commentary(player_idx: int, play: HandEvaluator.EvaluatedPlay) -> void:
    if not commentary_label:
        return
    var name := controller.game_state.player_names[player_idx]
    var type_name := _get_type_name(play.type)
    commentary_label.text = "%s 出了 %s（%d张，主阶=%d）" \
        % [name, type_name, play.cards.size(), play.primary_rank]
    commentary_label.modulate.a = 0.0
    var t := create_tween()
    t.tween_property(commentary_label, "modulate:a", 1.0, COMMENTARY_FADE_IN)


func _find_hand_node(card: Card) -> CardNode:
    for cn in hand_area.card_nodes:
        if cn.card_data != null and cn.card_data.card_id == card.card_id:
            return cn
    return null
```

#### 4.2.5 `_show_table_cards()` 微调

```diff
-table_label.add_child(node)
+table_card_root.add_child(node)
```

其余不变（仍按 55×80 桌牌尺寸渲染）。

---

## 五、行为规格

### 5.1 序列时序

```
T=0.0s   cards_played 信号触发
         ├─ hand_area.disable_input()
         ├─ 创建 N 个 ghost 节点（global_position = 源手牌节点位置）
         └─ 启动 N 个并行 tween（position + scale）

T=0.3s   ghost 飞行结束
         ├─ 销毁所有 ghost
         ├─ _show_table_cards() 创建桌牌（位置 = targets）
         └─ 启动 commentary fade in

T=0.5s   commentary 完全可见

T=1.1s   commentary 开始 fade out

T=1.4s   commentary 完全隐藏
         ├─ _clear_table_cards() 销毁桌牌
         └─ _refresh_ui() 重建手牌区（27-张数）

T=1.4s+  hand_area.enable_input() 由 turn_ready 信号在下个回合触发
```

### 5.2 边界行为

| 场景 | 行为 |
|---|---|
| 玩家在动画期间关掉场景 | `_exit_tree()` 自动 `kill()` 所有活跃 tween（设计文档 §四），ghost 节点随父节点释放 |
| AI 紧接玩家出牌触发 `_on_cards_played` | `await` 串行执行，AI 的 handler 等候直到当前 handler 的 1.4s 流程结束。无并发状态 |
| 玩家选择非法牌型 | `controller.handle_human_play()` 早于 `cards_played` 校验失败，`_on_cards_played` 不会触发，零影响 |
| `_find_hand_node` 找不到对应手牌节点 | 兜底：使用兜底位置 `Vector2(start_x + i*60, 600)`，不抛错 |
| 极端窄屏（手牌 3+ 行） | `vertical_scroll_mode = 2` 启用，FlowContainer 超出 ScrollContainer 高度时竖向滚动 |

### 5.3 不变性约束

- `controller.game_state.player_hands[0]` 的牌序在 `update_hand()` 排序前后**完全一致**（`update_hand` 内 `duplicate(false)` + 本地排序）
- `EvaluatedPlay` 的 `cards` 字段在 `_on_cards_played()` 内被 `duplicate(false)`，不修改 controller 持有的引用
- ghost 节点生命周期限定在 `_on_cards_played` 作用域内，函数返回前必须 `queue_free` 全部 ghost

---

## 六、文件清单

| 状态 | 路径 | 改动量 |
|---|---|---|
| 修改 | `src/ui/components/hand_area.tscn` | 1 行（容器类型 + 2 个属性） |
| 修改 | `src/ui/components/hand_area.gd` | 1 行（extends）+ 4 行（排序逻辑） |
| 修改 | `src/ui/scenes/training_room.tscn` | 3 行（ScrollContainer 高度+滚动模式）+ 12 行（新节点） |
| 修改 | `src/ui/scenes/training_room.gd` | 新增 ~50 行（动画 + 点评），重写 `_on_cards_played` ~30 行 |
| 不变 | `src/core/*` | 0 |
| 不变 | `src/ai/*` | 0 |
| 不变 | `src/game/*` | 0 |
| 不变 | `src/autoload/*` | 0 |
| 不变 | `assets/*` | 0 |
| 不变 | `tests/*` | 0 |

**总计：** 4 个文件，预计净增 ~70 行 GDScript + 16 行 .tscn。

---

## 七、验证

### 7.1 手动验证清单

打开 Godot → 运行 `training_room.tscn`：

- [ ] 起手 27 张牌自动分两行，全部可见，无横向滚动条
- [ ] 手牌按 rank 升序（2 → A → 小王 → 大王），同行内 suit 升序
- [ ] 选中牌后点击"出牌"，观察：
  - [ ] 飞行动画流畅，无卡顿
  - [ ] 卡牌从手牌对应位置飞出，0.3s 内落到桌面中央
  - [ ] 飞完后桌面出现 55×80 的桌牌
  - [ ] 桌面上方点评文字淡入，显示"玩家X 出了 TYPE（N张，主阶=R）"
  - [ ] 0.6s 后点评淡出
  - [ ] 桌牌清掉，手牌区重建（少 N 张）
- [ ] 飞机过程中手牌区不可点击
- [ ] 跑完一局完整对局，无报错、无残留节点

### 7.2 自动化检查

不新增 GUT 用例（与设计文档 §五"UI 测试：手动 + 截图对比"一致）。

### 7.3 风险监控

- **Tween 残留：** 若 `_exit_tree` 未清理 tween，可能导致 ghost 节点在场景销毁后继续触发 `tween_property` 写入。Godot 4.x tween 在父节点 free 时自动 `kill()`，但显式 `kill()` 更稳。本次依赖 Godot 默认行为，不额外加保险。
- **FlowContainer 重排抖动：** 出牌后 `_refresh_ui` 重建手牌区时，FlowContainer 会重新计算布局，可能在 1 帧内出现位置跳变。本次的"飞行 + 缩放"动画用 0.3s 覆盖此跳变，玩家感知不到。

---

## 八、与设计文档既有约束的一致性

| 设计文档条款 | 本次设计是否合规 |
|---|---|
| §一「禁止共享引用」 | ✓ `duplicate(false)` 后排序 |
| §一「Tween 清理：`_exit_tree` 中 `stop_all()` + `kill()`」 | ✓ Godot 4.x 默认行为；不修改既有 `training_room.gd` 的 `_exit_tree`（无新增） |
| §四「核心层不引用 Godot 节点类」 | ✓ 零 `core/` 改动 |
| §四「UI 节点销毁时断 EventBus 连接」 | ✓ 本次不新增 EventBus 订阅 |
| §八.1.1「手牌按 Rank→Suit 排序后均匀分布」 | ✓ 4.1.2 `sort_custom` |
| §八「UI Transition Lock：动画期间锁住输入」 | ✓ `hand_area.disable_input()` |
| §六.1「训练模式优先完成：核心逻辑 + L1/L2 AI + 牌型提示 UI」 | ✓ 牌型提示 UI 增强（点评）符合训练模式范围 |