# 交互系统技术设计文档（v0.1 原型）

> 任务ID: P-003（部分）
> 对应执行案: `docs/design/prototype/interaction-system-execution.md`
> 关联系统: 角色控制、物品系统、收集系统
> 阶段: 原型
> 日期: 2026-06-06

---

## 概述

交互系统是 v0.1 的核心体验系统，让玩家通过"走近并按键"与环境物体、NPC 产生互动。包含四种交互类型（观察/拾取/操作/对话），涉及状态机管理、摄像机推镜、UI 显示、跨系统通知等多个子系统。

**实现复杂度**：中-高
**预估工期**：5-7 天
**新增代码量**：约 800-1200 行 C++ + 2 个 UMG 蓝图

---

## 类与组件架构

### 新增类

| 类名 | 类型 | 职责 | 位置 |
|------|------|------|------|
| `IChildHoodInteractable` | UInterface | 交互物统一接口 | `Interaction/` |
| `UInteractableComponent` | UActorComponent | 可附着到任意 Actor，提供交互数据与触发检测 | `Interaction/` |
| `UInteractionManager` | UActorComponent | 交互状态机 + 检测 + 选择 + 摄像机推镜 + UI 管理 | `Interaction/` |

### 修改类

| 类名 | 修改内容 |
|------|---------|
| `AChildHoodCharacter` | 持有 InteractionManager，提供交互状态查询接口 |
| `AChildHoodPlayerController` | 注册交互相关 IA（E/ESC/Tab/滚轮） |

### 新增蓝图

| 蓝图名 | 类型 | 用途 |
|--------|------|------|
| `WBP_InteractionPrompt` | UMG Widget | 交互提示 UI（`[E] 查看旧冰箱`） |
| `WBP_InteractionText` | UMG Widget | 文本底框（半透明背景 + 文字） |
| `BP_InteractableActor` | Actor Blueprint | 可交互物基类蓝图（带 InteractableComponent） |
| `BP_PickupItem` | Actor Blueprint | 拾取物蓝图（继承 BP_InteractableActor） |
| `BP_InteractableDoor` | Actor Blueprint | 门蓝图（继承 BP_InteractableActor，含开关状态） |
| `BP_InteractableNPC` | Actor Blueprint | NPC 蓝图（继承 BP_InteractableActor） |

### 架构关系

```
AChildHoodPlayerController
├── Enhanced Input
│   ├── IA_Interact (E) ──────────┐
│   ├── IA_Cancel (ESC) ──────────┤
│   └── IA_SwitchInteract (Tab) ──┤
│                                  ▼
AChildHoodCharacter               UInteractionManager
├── CapsuleComponent              ├── 状态机 (Free/Interacting)
├── SkeletalMesh                  ├── 检测列表 (NearbyInteractables)
├── SpringArm + Camera            ├── 当前选中 (SelectedInteractable)
├── UInteractionManager ◄─────────┤── 摄像机推镜控制
└── bIsInteracting 标志           ├── UI 管理 (Prompt + Text)
                                  └── 交互流程驱动

场景中的可交互物:
AActor (任意 Actor)
└── UInteractableComponent (实现 IChildHoodInteractable)
    ├── FInteractableData (配置数据)
    ├── USphereComponent (触发检测范围)
    └── UStaticMeshComponent (占位模型)
```

---

## 核心数据结构

### 枚举

```cpp
// 交互类型
UENUM(BlueprintType)
enum class EInteractType : uint8
{
    Examine,  // 观察
    Pickup,   // 拾取
    Operate,  // 操作
    Talk      // 对话
};

// 操作子类型
UENUM(BlueprintType)
enum class EOperateSubType : uint8
{
    None,
    Door,    // 门（开关切换）
    Search   // 翻找
};

// 交互系统顶层状态
UENUM(BlueprintType)
enum class EInteractionState : uint8
{
    Free,        // 自由状态
    Interacting, // 交互中
    SubSystem,   // 子系统（v0.1 预留）
    Cutscene     // 过场（v0.1 预留）
};

// Interacting 子阶段
UENUM(BlueprintType)
enum class EInteractPhase : uint8
{
    None,
    Enter,     // 进入：转向 + 推镜
    AnimLock,  // 动画锁定：等待动画播完
    Active,    // 活跃：等待玩家输入
    Exit       // 退出：回位 + 淡出
};

// 交互结束后的动作
UENUM(BlueprintType)
enum class EPostAction : uint8
{
    Return,      // 回到 Free
    Minigame,    // 进入小游戏（v0.1 预留）
    Dialogue,    // 进入对话（v0.1 预留）
    SceneChange  // 场景切换（v0.1 预留）
};
```

### 配置数据结构

```cpp
USTRUCT(BlueprintType)
struct FInteractableData
{
    GENERATED_BODY()

    // 基本信息
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FName ItemId;                    // 物品唯一ID（如 "fridge_home"）

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FString DisplayName;            // 显示名称（如 "旧冰箱"）

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    EInteractType Type = EInteractType::Examine;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    EOperateSubType SubType = EOperateSubType::None;

    // 触发
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float TriggerRadius = 150.0f;   // 触发半径（cm）

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    bool bOneShot = false;          // 一次性消耗

    // 提示文本
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FString InteractVerb;           // 动作词（如 "查看"、"拾取"）

    // 叙事文本
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TArray<FString> NarrativeTexts; // 文本列表，随机选取

    // 摄像机推镜
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    bool bUseCameraPush = false;    // 是否推镜

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float CameraPushDistance = 100.0f; // 推镜距离（cm）

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float CameraPushHeightOffset = -20.0f; // 推镜高度偏移（略低于物体中心）

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float CameraPushDuration = 0.5f;  // 推镜时长（秒）

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float CameraReturnDuration = 0.3f; // 回位时长（秒）

    // 动画
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    UAnimMontage* InteractionMontage = nullptr; // 交互动画

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float AnimEventProgress = 0.6f; // 动画中触发事件的进度点（0-1）

    // 物品（拾取/翻找）
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FName RewardItemId;             // 获得的物品ID

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FString RewardItemCategory = TEXT("杂物"); // 物品品类

    // 结束动作
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    EPostAction PostAction = EPostAction::Return;
};
```

---

## 行为规则 → 实现方案映射

### 一、状态机实现（UInteractionManager）

#### 状态机设计

```cpp
UCLASS()
class UInteractionManager : public UActorComponent
{
    GENERATED_BODY()

    // 当前状态
    EInteractionState State = EInteractionState::Free;
    EInteractPhase Phase = EInteractPhase::None;

    // 检测
    bool bInDetectionRange = false;
    TArray<TWeakObjectPtr<UInteractableComponent>> NearbyInteractables;
    int32 SelectedIndex = 0;

    // 当前交互
    UPROPERTY()
    UInteractableComponent* CurrentInteractable = nullptr;

    // 摄像机推镜
    UPROPERTY()
    ACameraActor* PushCamera = nullptr;

    // 计时器
    float PhaseTimer = 0.f;
    float TurnProgress = 0.f;

    // UI
    UPROPERTY()
    UUserWidget* PromptWidget = nullptr;
    UPROPERTY()
    UUserWidget* TextWidget = nullptr;
};
```

#### 状态转换逻辑

```
Tick 流程:

Free 状态:
  ├── 更新 NearbyInteractables（基于 Overlap 事件维护）
  ├── 按距离排序
  ├── 更新 bInDetectionRange
  ├── 更新 PromptWidget（选中物的提示）
  └── 等 E 键触发

E 键触发:
  Free → Interacting/Enter
  ├── 保存当前摄像机状态
  ├── 设置 bIsInteracting = true（通知角色控制）
  ├── 启动角色转向（0.2s）
  └── 如需推镜，启动推镜

Enter 阶段完成:
  Enter → AnimLock 或 Active（取决于交互类型）
  ├── 有动画 → AnimLock（等动画播完）
  └── 无动画 → Active（等文本显示 + 玩家输入）

AnimLock 结束（动画播完）:
  ├── 拾取类 → 执行物品逻辑 → Exit
  ├── 门操作 → 执行状态切换 → Exit
  └── 翻找类 → 结果判定 → Active 或 Exit

Active 阶段（等 E/ESC）:
  E/ESC → Exit

Exit 阶段:
  ├── 淡出 UI
  ├── 摄像机回位
  └── 完成后 → Free（检查 postAction，v0.1 全为 Return）
```

---

### 二、通用规则

#### G1. 触发条件

**实现**：UInteractableComponent 持有 USphereComponent 作为触发范围

```cpp
// UInteractableComponent 初始化
TriggerSphere = CreateDefaultSubobject<USphereComponent>("TriggerSphere");
TriggerSphere->SetSphereRadius(Data.TriggerRadius);
TriggerSphere->SetCollisionEnabled(ECollisionEnabled::QueryOnly);
TriggerSphere->SetCollisionResponseToAllChannels(ECR_Ignore);
TriggerSphere->SetCollisionResponseToChannel(ECC_Pawn, ECR_Overlap);
TriggerSphere->SetupAttachment(GetOwner()->GetRootComponent());

// Overlap 事件 → 通知 InteractionManager
TriggerSphere->OnComponentBeginOverlap.AddDynamic(this, &UInteractableComponent::OnOverlapBegin);
TriggerSphere->OnComponentEndOverlap.AddDynamic(this, &UInteractableComponent::OnOverlapEnd);
```

InteractionManager 维护 NearbyInteractables 列表，按距离排序。

**消耗检查**：
```cpp
bool IChildHoodInteractable::CanInteract() const
{
    return !bConsumed; // oneShot 且已消耗则返回 false
}
```

#### G2. 提示 UI 显示规则

**实现**：WBP_InteractionPrompt（UMG Widget）

- **位置**：通过 `ProjectWorldLocationToScreen` 将交互物注册点投影到屏幕空间
- **格式**：`[E] {动词} {物体名}`（如 `[E] 查看旧冰箱`）
- **淡入/淡出**：Widget Animation 0.2s
- **更新时机**：每 Tick 更新位置和内容（仅当选中物变化时刷新内容）

**多交互物切换**：
```cpp
void UInteractionManager::SwitchToNext()
{
    if (NearbyInteractables.Num() == 0) return;
    SelectedIndex = (SelectedIndex + 1) % NearbyInteractables.Num();
    UpdatePromptWidget();
}

void UInteractionManager::SwitchToPrevious()
{
    if (NearbyInteractables.Num() == 0) return;
    SelectedIndex = (SelectedIndex - 1 + NearbyInteractables.Num()) % NearbyInteractables.Num();
    UpdatePromptWidget();
}
```

**距离排序**：
```cpp
NearbyInteractables.Sort([this](const TWeakObjectPtr<UInteractableComponent>& A,
                                const TWeakObjectPtr<UInteractableComponent>& B)
{
    float DistA = FVector::Dist2D(Character->GetActorLocation(), A->GetInteractLocation());
    float DistB = FVector::Dist2D(Character->GetActorLocation(), B->GetInteractLocation());
    return DistA < DistB;
});
```

#### G3. 交互触发（E 键）

**实现**：InteractionManager::OnInteractPressed()

```cpp
void UInteractionManager::OnInteractPressed()
{
    if (State != EInteractionState::Free || !bInDetectionRange) return;

    auto Selected = GetSelectedInteractable();
    if (!Selected || !Selected->CanInteract()) return;

    StartInteraction(Selected);
}
```

#### G4. 通用文本显示 UI

**实现**：WBP_InteractionText（UMG Widget）

- **位置**：屏幕正中偏下（Anchors: Center, Offset Y = +10% 屏幕高度）
- **底框**：半透明黑色背景（Background Color: Black, Opacity 0.6），圆角
- **文字**：白色，居中，内容自适应宽高
- **显示**：整句一次性显示（无打字机效果）
- **淡入/淡出**：Widget Animation 0.2s

---

### 三、交互类型一：观察（Examine）

#### 流程实现

```cpp
void UInteractionManager::StartExamine(UInteractableComponent* Interactable)
{
    Phase = EInteractPhase::Enter;
    PhaseTimer = 0.f;

    // 1. 角色转向（0.2s）
    StartCharacterTurn(Interactable->GetInteractLocation());
    TurnDuration = 0.2f;

    // 2. 推镜（与转向同时，0.5s ease-out）
    StartCameraPush(Interactable, 0.5f);

    // 3. 设置 Enter 阶段完成时间 = max(转向, 推镜) + 0.2s 等待
    EnterCompleteDelay = FMath::Max(0.2f, 0.5f) + 0.2f;
}
```

**Enter → Active 转换**：

```cpp
// Tick 中
if (Phase == EInteractPhase::Enter)
{
    PhaseTimer += DeltaTime;
    UpdateCharacterTurn(DeltaTime);
    UpdateCameraPush(DeltaTime);

    if (PhaseTimer >= EnterCompleteDelay)
    {
        // 4. 显示文本
        FString Text = SelectRandomText(CurrentInteractable);
        ShowInteractionText(Text);
        Phase = EInteractPhase::Active;
    }
}
```

**关闭（E/ESC）**：

```cpp
void UInteractionManager::CloseExamine()
{
    Phase = EInteractPhase::Exit;
    HideInteractionText();        // 淡出 0.2s
    StartCameraReturn(0.3f);      // ease-in 回位
    ExitDuration = 0.3f;
}
```

**文本随机选取**：

```cpp
FString UInteractionManager::SelectRandomText(UInteractableComponent* Interactable)
{
    auto& Texts = Interactable->GetNarrativeTexts();
    if (Texts.Num() == 0) return TEXT("");
    if (Texts.Num() == 1) return Texts[0];

    // 不重复上一次
    int32 Index;
    do {
        Index = FMath::RandRange(0, Texts.Num() - 1);
    } while (Index == LastTextIndex && Texts.Num() > 1);

    LastTextIndex = Index;
    return Texts[Index];
}
```

---

### 四、交互类型二：拾取（Pickup）

#### 流程实现

```cpp
void UInteractionManager::StartPickup(UInteractableComponent* Interactable)
{
    Phase = EInteractPhase::Enter;
    PhaseTimer = 0.f;

    // 1. 角色转向（0.2s）
    StartCharacterTurn(Interactable->GetInteractLocation());

    // 拾取不推镜，相机保持第三人称位置
    // 2. 转向完成后播放动画 → AnimLock
    bPendingAnimLock = true;
    PendingMontage = nullptr; // v0.1 可能无动画
    PendingAnimDuration = 1.0f; // 拾取动画时长

    // 3. 物品消失在动画 60% 处
    AnimEventProgress = 0.6f;
    bAnimEventTriggered = false;
}

// Tick 中处理 AnimLock
if (Phase == EInteractPhase::AnimLock)
{
    PhaseTimer += DeltaTime;
    float Progress = PhaseTimer / PendingAnimDuration;

    // 物品消失时间点
    if (!bAnimEventTriggered && Progress >= AnimEventProgress)
    {
        bAnimEventTriggered = true;
        CurrentInteractable->SetVisibility(false); // 视觉消失

        // 通知物品系统
        NotifyItemSystem(CurrentInteractable->GetRewardItemId(),
                        CurrentInteractable->GetRewardItemCategory());
    }

    // 动画播完
    if (PhaseTimer >= PendingAnimDuration)
    {
        CurrentInteractable->MarkConsumed(); // 标记已消耗
        Phase = EInteractPhase::Exit;
        // Exit 立即完成（无回位动画）
        FinishInteraction();
    }
}
```

**拾取物外观**：所有拾取物使用同一个占位模型（简单球形或方块，0.1m 直径）。通过材质颜色区分稀有度（普通=白色，稀有=金色）。

**不支持手动关闭**：拾取全程 AnimLock，忽略所有按键。

---

### 五、交互类型三：操作（Operate）

#### 3A. 门（开关切换）

```cpp
void UInteractionManager::StartDoor(UInteractableComponent* Interactable)
{
    Phase = EInteractPhase::Enter;
    PhaseTimer = 0.f;

    // 1. 角色转向（0.2s）
    StartCharacterTurn(Interactable->GetInteractLocation());

    // 不推镜
    // 2. 转向完成后播放动画 → AnimLock
    bPendingAnimLock = true;
    PendingAnimDuration = 0.8f; // 门操作动画时长
    AnimEventProgress = 0.4f;   // 40% 处切换状态
}

// AnimLock 中的事件
if (!bAnimEventTriggered && Progress >= AnimEventProgress)
{
    bAnimEventTriggered = true;
    // 通知门的蓝图切换开关状态
    CurrentInteractable->OnInteractEvent();
}

// 动画播完 → Exit
if (PhaseTimer >= PendingAnimDuration)
{
    FinishInteraction(); // 直接回到 Free
}
```

**门状态切换**：在 BP_InteractableDoor 蓝图中实现。InteractableComponent 触发事件 → 蓝图响应旋转门 Mesh + 更新提示文本（"打开门" ↔ "关上门"）。

#### 3B. 废纸箱（翻找）

```cpp
void UInteractionManager::StartSearch(UInteractableComponent* Interactable)
{
    Phase = EInteractPhase::Enter;
    PhaseTimer = 0.f;

    // 1. 角色转向（0.2s）
    StartCharacterTurn(Interactable->GetInteractLocation());

    // 2. 推镜（与转向同时，0.5s）
    StartCameraPush(Interactable, 0.5f);

    // 3. 转向完成后播放翻找动画 → AnimLock
    bPendingAnimLock = true;
    PendingAnimDuration = 1.5f; // 翻找动画时长
}

// AnimLock 完成后
void UInteractionManager::OnSearchAnimComplete()
{
    if (CurrentInteractable->HasRewardItem())
    {
        // 有物品分支
        NotifyItemSystem(CurrentInteractable->GetRewardItemId(),
                        CurrentInteractable->GetRewardItemCategory());
        CurrentInteractable->MarkConsumed();
        // 物品系统弹出拾取通知，收集系统弹出收集通知
        // 等待 E/ESC
        Phase = EInteractPhase::Active;
    }
    else
    {
        // 无物品分支（架构预留）
        ShowInteractionText(TEXT("什么都没找到。"));
        Phase = EInteractPhase::Active;
    }
}
```

---

### 六、交互类型四：对话（Talk）— 简化版

```cpp
void UInteractionManager::StartTalk(UInteractableComponent* Interactable)
{
    // 与观察类流程几乎相同
    Phase = EInteractPhase::Enter;
    PhaseTimer = 0.f;

    StartCharacterTurn(Interactable->GetInteractLocation());
    StartCameraPush(Interactable, 0.5f);

    // Enter 完成后显示 NPC 对话文本
    // Active 阶段等 E/ESC 关闭
}
```

与观察类的区别：
- 文本来源不同（对话内容 vs 小孩想法）
- 无功能差异，v0.1 共用同一流程

---

### 七、摄像机推镜系统

#### 实现方案：ACameraActor + SetViewTargetWithBlend

**原理**：交互时创建临时 CameraActor，通过 UE5 内置的摄像机混合系统平滑切换视角。

```cpp
void UInteractionManager::StartCameraPush(UInteractableComponent* Interactable, float Duration)
{
    if (!Interactable->GetData().bUseCameraPush) return;

    // 计算推镜目标位置
    FVector InteractLoc = Interactable->GetInteractLocation();
    FVector CharacterLoc = GetOwner()->GetActorLocation();
    FVector DirToCharacter = (CharacterLoc - InteractLoc).GetSafeNormal2D();

    // 推镜位置：物体前方指定距离，略低于物体中心
    float PushDist = Interactable->GetData().CameraPushDistance;
    float HeightOffset = Interactable->GetData().CameraPushHeightOffset;

    FVector PushLocation = InteractLoc - DirToCharacter * PushDist;
    PushLocation.Z = InteractLoc.Z + HeightOffset + 80.f; // 80 = 角色站立高度补偿

    FRotator PushRotation = (InteractLoc - PushLocation).Rotation();

    // 创建或复用推镜摄像机
    if (!PushCamera)
    {
        FActorSpawnParameters Params;
        PushCamera = GetWorld()->SpawnActor<ACameraActor>(ACameraActor::StaticClass(),
                                                           PushLocation, PushRotation, Params);
    }
    else
    {
        PushCamera->SetActorLocationAndRotation(PushLocation, PushRotation);
    }

    // 混合到推镜摄像机
    APlayerController* PC = Cast<APlayerController>(Cast<APawn>(GetOwner())->GetController());
    PC->SetViewTargetWithBlend(PushCamera, Duration,
        EViewTargetBlendFunction::VTBlend_EaseInOut, 1.0f);

    bIsCameraPushed = true;
}

void UInteractionManager::StartCameraReturn(float Duration)
{
    if (!bIsCameraPushed) return;

    APlayerController* PC = Cast<APlayerController>(Cast<APawn>(GetOwner())->GetController());
    APawn* Pawn = PC->GetPawn();

    // 混合回角色（SpringArm 恢复控制）
    PC->SetViewTargetWithBlend(Pawn, Duration,
        EViewTargetBlendFunction::VTBlend_EaseInOut, 1.0f);

    bIsCameraPushed = false;
}
```

**生命周期**：PushCamera 在 InteractionManager 初始化时创建，整个游戏期间复用，不需要每次交互都 Spawn/Destroy。

---

### 八、角色转向实现

```cpp
void UInteractionManager::StartCharacterTurn(const FVector& TargetLocation)
{
    ACharacter* Character = Cast<ACharacter>(GetOwner());
    if (!Character) return;

    TurnStartRotation = Character->GetActorRotation();
    FVector Direction = (TargetLocation - Character->GetActorLocation());
    Direction.Z = 0.f;
    TurnTargetRotation = Direction.Rotation();
    TurnProgress = 0.f;
    TurnDuration = 0.2f;
    bIsTurning = true;

    // 暂停 CMC 的自动转向，防止冲突
    Character->GetCharacterMovement()->bOrientRotationToMovement = false;
}

void UInteractionManager::UpdateCharacterTurn(float DeltaTime)
{
    if (!bIsTurning) return;

    TurnProgress += DeltaTime / TurnDuration;
    if (TurnProgress >= 1.f)
    {
        TurnProgress = 1.f;
        bIsTurning = false;
        // 不立即恢复 bOrientRotationToMovement，等交互结束
    }

    // Ease-out 插值
    float Alpha = 1.f - FMath::Pow(1.f - TurnProgress, 3.f);
    FRotator NewRotation = FMath::Lerp(TurnStartRotation, TurnTargetRotation, Alpha);
    GetOwner()->SetActorRotation(NewRotation);
}
```

---

### 九、物品系统中转（补充执行案缺失部分）

> 执行案要求"物品系统（通知中转+拾取通知+背包记录）需在本步骤纳入技术方案"。

#### UItemManager — 轻量物品管理组件

```cpp
UCLASS()
class UItemManager : public UActorComponent
{
    GENERATED_BODY()

    // 简单背包：ItemID → 数量
    UPROPERTY()
    TMap<FName, int32> Inventory;

public:
    // 接收交互系统的拾取通知
    void OnItemPickedUp(FName ItemId, const FString& Category, const FString& ItemNumber);

    // 查询
    int32 GetItemCount(FName ItemId) const;
    bool HasItem(FName ItemId) const;

    // 事件：通知 UI 显示拾取通知
    UPROPERTY(BlueprintAssignable)
    FOnItemPickedUpSignature OnItemPickedUpEvent;

    // 事件：通知收集系统
    UPROPERTY(BlueprintAssignable)
    FOnItemCollectedSignature OnItemCollectedEvent;
};
```

#### 数据流

```
交互系统 (InteractionManager)
    │ OnItemPickedUp(ItemId, Category, Number)
    ▼
物品系统 (ItemManager)
    ├── Inventory[ItemId]++ （背包记录）
    ├── OnItemPickedUpEvent → WBP_PickupNotification（"找到了 XXX"）
    └── OnItemCollectedEvent → 收集系统（"发现了新的杂物，进度 X/Y"）
```

#### 拾取通知 UI（WBP_PickupNotification）

- **位置**：屏幕右上角
- **内容**：物品名称 + 简短描述
- **效果**：弹出后 2 秒自动淡出
- **v0.1 简化**：只显示文字，不显示图标

#### 背包

v0.1 不做背包 UI，仅内部记录。Inventory 使用 `TMap<FName, int32>` 存储，支持计数查询。

---

## 数据流总览

```
Enhanced Input
    │
    ├── WASD → AChildHoodCharacter::DoMove()
    │         ├── 检查 bIsInteracting（由 InteractionManager 控制）
    │         └── CMC::AddMovementInput()
    │
    ├── 鼠标 → AChildHoodCharacter::DoLook()
    │         └── Controller::AddYawInput/AddPitchInput
    │
    ├── E → UInteractionManager::OnInteractPressed()
    │       ├── Free 状态 → StartInteraction()
    │       └── Active 状态 → CloseCurrentInteraction()
    │
    ├── ESC → UInteractionManager::OnCancelPressed()
    │         └── Active 状态 → CloseCurrentInteraction()
    │
    ├── Tab/滚轮 → UInteractionManager::SwitchToNext/Previous()
    │
    └── Interacting 状态下 WASD/Tab/滚轮被忽略

UInteractableComponent (场景中的交互物)
    │ Overlap 事件
    ▼
UInteractionManager (角色上的组件)
    ├── 维护 NearbyInteractables 列表
    ├── 管理状态机 (Free ↔ Interacting)
    ├── 控制摄像机推镜 (SetViewTargetWithBlend)
    ├── 控制角色转向 (SetActorRotation)
    ├── 控制 UI 显示 (Prompt / Text)
    └── 通知 UItemManager (拾取/翻找获得物品)
        ├── Inventory 记录
        ├── PickupNotification UI
        └── → 收集系统通知
```

---

## 边界情况处理

| 边界情况 | 实现方案 |
|---------|---------|
| 快速连续按 E | AnimLock 阶段忽略所有输入；Exit 完成才回到 Free |
| 交互物被消耗后范围残留 | MarkConsumed() 使 CanInteract() 返回 false；从 NearbyInteractables 移除 |
| 推镜期间角色位置 | 移动输入已被 bIsInteracting 阻断，角色不移动 |
| 同一交互物反复进出范围 | Prompt 每次淡入淡出，无累积。NearbyInteractables 列表自动增减 |
| 切换交互物同时按 E | Tab/Scroll 先执行切换，下一帧 E 按下时读取新 SelectedIndex |
| 距离恰好在触发半径 | Sphere Overlap 使用 ≤ 语义，边界上视为在范围内 |
| 窄空间推镜位置不理想 | v0.1 接受不完美；推镜目标位置计算后可做简单碰撞检测（射线检测到阻挡则缩短距离） |

---

## 美术资源需求

### 占位模型（第一轮，5 个）

| 资源类型 | 名称 | 数量 | 规格 | 触发时机/用途 |
|----------|------|------|------|---------------|
| 3D 占位模型 | 旧冰箱 | 1 | 白色方箱体，约 1.7m 高 × 0.7m 宽 × 0.7m 深 | 家区域观察交互 |
| 3D 占位模型 | 家的门 | 1 | 扁平方片（约 2.0m × 0.9m），可绕一侧轴旋转 | 家区域操作交互（开关） |
| 3D 占位模型 | 拾取物通用模型 | 1 | 简单球形，直径约 0.1m | 拾取交互（多个实例，颜色区分） |
| 3D 占位模型 | 公用电话亭 | 1 | 窄高方柱，约 2.0m 高 × 0.8m 宽 | 街道区域观察交互 |
| 3D 占位模型 | NPC 老板（简化） | 1 | 简单人形胶囊体，坐姿 | 小卖部对话交互 |

### 占位模型（第二轮，5 个）

| 资源类型 | 名称 | 数量 | 规格 | 触发时机/用途 |
|----------|------|------|------|---------------|
| 3D 占位模型 | 老式电视 | 1 | 方箱 + 凸起背部，约 0.5m 高 × 0.6m 宽 | 家区域观察交互 |
| 3D 占位模型 | 零食货架 | 1 | 多层架结构，约 1.8m 高 × 1.0m 宽 | 小卖部观察交互 |
| 3D 占位模型 | 拾取物（水浒卡） | 1 | 小方片，约 0.06m × 0.09m | 拾取交互（复用通用拾取模型也可） |
| 3D 占位模型 | 墙面涂鸦 | 1 | 墙面贴花/平面色块，约 0.5m × 0.5m | 街道观察交互 |
| 3D 占位模型 | 废纸箱 | 1 | 开口方箱，约 0.5m 高 × 0.4m 宽 | 巷子翻找交互 |

### 材质

| 资源类型 | 名称 | 数量 | 规格 | 用途 |
|----------|------|------|------|------|
| 材质 | 拾取物_普通 | 1 | 白色/浅灰，Unlit 或简单 Lit | 通用拾取物材质 |
| 材质 | 拾取物_稀有 | 1 | 金色，可加简单闪烁 | 稀有拾取物材质 |

### 动画

| 资源类型 | 名称 | 数量 | 规格 | 用途 |
|----------|------|------|------|------|
| 动画 Montage | 弯腰拾取 | 1 | 约 1.0 秒，从站立→弯腰→站起 | 拾取交互 |
| 动画 Montage | 推门 | 1 | 约 0.8 秒，伸手推/拉动作 | 门操作交互 |
| 动画 Montage | 翻找 | 1 | 约 1.5 秒，弯腰翻动物品 | 废纸箱翻找交互 |

> v0.1 执行案明确允许"若无动画资源，角色在地面滑动也可接受"。动画可简化为角色原地不动（跳过 AnimLock，直接触发事件）。

### UI

| 资源类型 | 名称 | 数量 | 规格 | 用途 |
|----------|------|------|------|------|
| UMG Widget | 交互提示 | 1 | `[E] 动作词 物体名`，白色文字 + 轻描边 | 显示在交互物上方 |
| UMG Widget | 文本底框 | 1 | 半透明黑底（60%），白色居中文字，自适应大小 | 观察/对话/翻找无结果文本 |
| UMG Widget | 拾取通知 | 1 | 屏幕右上角，物品名称，2 秒淡出 | 拾取/翻找获得物品提示 |

---

## 技术风险与注意事项

| 风险 | 等级 | 说明 | 缓解措施 |
|------|------|------|---------|
| 推镜位置计算不准确 | 🟡 中 | 贴墙物体的推镜位置可能在墙内 | v0.1 接受不完美；加简单射线检测缩短距离 |
| 摄像机混合与 SpringArm 冲突 | 🟡 中 | SetViewTargetWithBlend 切换时可能有跳变 | 使用 ACameraActor 作为中间目标，确保初始位置匹配当前摄像机位置 |
| 多交互物切换延迟感 | 🟢 低 | Tab 切换后提示更新需要即时 | 切换时立即刷新 UI 内容 |
| Overlap 事件遗漏 | 🟢 低 | 角色快速移动可能错过 Overlap 事件 | 用 Tick 补充检测（每隔 N 帧全量扫描）或增大触发范围 |
| 动画缺失时的降级处理 | 🟢 低 | 无拾取/操作动画时需跳过 AnimLock | AnimLock 阶段无 Montage 时直接用定时器模拟时长 |
| 蓝图与 C++ 的交互复杂度 | 🟢 低 | 交互物具体行为（门旋转、物品消失）在蓝图中实现 | C++ 提供虚函数/委托，蓝图 Override |

### 需要注意

1. **摄像机推镜的初始位置同步**：创建 PushCamera 时必须设置到当前摄像机位置，否则混合开始瞬间会有跳变。
2. **bOrientRotationToMovement 的恢复时机**：交互结束时必须恢复此标志，否则角色退出交互后不再自动转向。
3. **交互物 Overlap 性能**：每个交互物有独立的 SphereComponent，10 个交互物最多 10 个 Overlap 检测。v0.1 规模无性能问题，后续扩展需考虑优化。
4. **PushCamera 的生命周期**：不要每次交互都 Spawn 新的，复用同一个 CameraActor。EndPlay 时清理。

---

## 文件结构

```
Source/ChildHood/
├── Interaction/
│   ├── InteractableInterface.h          # IChildHoodInteractable 接口
│   ├── InteractableComponent.h/.cpp     # 交互物组件（数据 + 触发范围）
│   ├── InteractionManager.h/.cpp        # 交互状态机 + 检测 + 推镜 + UI
│   ├── InteractionTypes.h               # 枚举、结构体定义
│   └── ItemManager.h/.cpp              # 物品系统（背包 + 通知中转）
├── Player/
│   ├── ChildHoodCharacter.h/.cpp        # 修改：添加 InteractionManager
│   └── ChildHoodPlayerController.h/.cpp # 修改：添加交互 IA 注册
└── UI/
    ├── InteractionPromptWidget.h/.cpp   # （可选：C++ 基类，也可纯蓝图）
    └── InteractionTextWidget.h/.cpp     # （可选：C++ 基类，也可纯蓝图）

Content/
├── Blueprints/
│   ├── Interaction/
│   │   ├── BP_InteractableActor         # 可交互物基类蓝图
│   │   ├── BP_PickupItem               # 拾取物蓝图
│   │   ├── BP_InteractableDoor         # 门蓝图
│   │   ├── BP_InteractableSearch       # 翻找物蓝图（废纸箱）
│   │   └── BP_InteractableNPC          # NPC 蓝图
│   └── Characters/
│       └── BP_ChildHoodCharacter        # 玩家角色蓝图（修改）
├── UI/
│   ├── WBP_InteractionPrompt           # 交互提示 Widget
│   ├── WBP_InteractionText             # 文本底框 Widget
│   └── WBP_PickupNotification          # 拾取通知 Widget
└── Input/
    ├── IMC_Default                     # 输入映射上下文（修改：添加交互 IA）
    ├── IA_Move                         # 已有
    ├── IA_MouseLook                    # 已有
    ├── IA_Interact                     # 新增：E 键
    ├── IA_Cancel                       # 新增：ESC 键
    └── IA_SwitchInteract               # 新增：Tab / 鼠标滚轮
```