VFSUnity/README.md

# VFSUnity - 运动伤害现场急救处理虚拟仿真实验

基于 Unity 2022.3.62f3c1 (URP) 的体育虚拟仿真教学项目。

## 环境要求

| 工具 | 版本 |
|------|------|
| Unity Editor | **2022.3.62f3c1**（必须一致，建议通过 Unity Hub 安装） |
| Unity Hub | 3.x+ |
| 渲染管线 | Universal Render Pipeline (URP) 14.0.12 |

## 快速开始

### 1. 克隆仓库

```bash
git clone https://git.yangbear.cn/yangbear/VFSUnity.git
```

### 2. 用 Unity Hub 打开

1. 打开 **Unity Hub**
2. 确保已安装 **Unity 2022.3.62f3c1**
3. 点击 **Open** → 选择 clone 下来的 `VFSUnity` 文件夹
4. Unity 自动加载并解析 `Packages/manifest.json` 中的依赖包

### 3. 运行

- 在 **Project** 窗口中双击 `Assets/Scenes/main.unity` 打开主菜单场景
- 点击顶部工具栏的 ▶ **Play** 按钮即可运行

---

## 项目结构

```
VFSUnity/
├── Assets/
│   ├── Scripts/
│   │   ├── Core/                    # 核心管理器
│   │   │   ├── GameManager.cs       # 全局状态管理（单例）
│   │   │   ├── ExperimentController.cs  # 实验流程控制器
│   │   │   └── ConfigLoader.cs      # JSON 配置加载器
│   │   ├── Data/                    # 数据模型
│   │   │   ├── StepData.cs          # 单步定义 ScriptableObject
│   │   │   ├── ExamQuestionData.cs  # 考核题目 ScriptableObject
│   │   │   └── ExperimentConfig.cs  # 实验配置 ScriptableObject
│   │   ├── Interaction/             # 交互系统
│   │   │   ├── InteractionSystem.cs # 射线检测与点击处理
│   │   │   └── DraggableObject.cs   # 拖拽交互组件
│   │   ├── UI/                      # UI 控制器
│   │   │   ├── MainMenuUI.cs        # 主菜单界面
│   │   │   ├── ModeSelectionUI.cs   # 模式选择界面
│   │   │   ├── HUDController.cs     # 游戏内 HUD
│   │   │   ├── PopupSystem.cs       # 弹窗系统
│   │   │   └── VideoPlayerController.cs  # 画中画视频
│   │   └── Animation/
│   │       └── AnimationController.cs   # 角色动画控制
│   ├── Scenes/
│   │   ├── main.unity               # 主菜单场景 ⭐
│   │   ├── ModeSelection.unity      # 模式选择场景
│   │   └── Experiment.unity         # 实验场景（核心）
│   ├── Models/
│   │   ├── Characters/              # 角色模型（伤者、施救者）
│   │   ├── Props/                   # 道具模型（急救箱、绷带、夹板）
│   │   └── Environment/             # 场景模型（田径馆）
│   ├── Animations/                  # 动画文件（待导入）
│   ├── Prefabs/                     # 预制体
│   ├── Materials/                   # 材质
│   ├── Textures/                    # 贴图
│   │   └── UI/                      # UI 贴图
│   ├── Audio/                       # 音频文件（语音解说）
│   ├── Video/                       # 视频文件（真人演示）
│   └── Resources/
│       └── Data/
│           ├── fracture_fixation_steps.json  # 肢体固定步骤配置
│           └── splint_fixation_steps.json    # 夹板固定步骤配置
├── Packages/                        # Unity 包依赖清单
├── ProjectSettings/                 # 项目全局设置
└── README.md
```

---

## 🏗 架构设计

### 核心流程

```
MainMenu (scene: main.unity)
    │ 选择实验类型（骨折固定/心肺复苏/...）
    ▼
ModeSelection (scene: ModeSelection.unity)
    │ 选择固定方式 + 运行模式
    ▼
Experiment (scene: Experiment.unity)
    │ GameManager（全局状态）
    │ ExperimentController（步骤控制）
    │ InteractionSystem（点击检测）
    │ HUD（顶部提示栏 + 右侧按钮 + 进度条）
    │ PopupSystem（弹窗 + 考核题 + 成绩显示）
    │ VideoPlayer（画中画，学习模式）
```

### 状态管理

| 类 | 职责 |
|----|------|
| **GameManager** | 全局单例。管理实验类型、固定方式、运行模式、当前步骤、分数、考核结果 |
| **ExperimentController** | 接收用户交互事件，验证步骤完成条件，推进实验流程 |
| **InteractionSystem** | 处理鼠标射线检测，区分 UI 点击和 3D 物体点击 |
| **ConfigLoader** | 从 `Resources/Data/*.json` 加载实验步骤和考核题目数据 |

### 数据模型

| 类 | 说明 |
|----|------|
| **StepData** (ScriptableObject) | 定义单个步骤：提示文案、对话文案、交互类型、目标标签 |
| **ExamQuestionData** (ScriptableObject) | 定义考核题目：题目文案、选项、正确答案、反馈文案 |
| **ExperimentConfig** (ScriptableObject) | 实验配置容器：步骤列表 + 考核题目列表 + 固位方式 + 分数设置 |

---

## 🎮 场景说明

### 1. 主菜单场景 (`main.unity`)

- 主标题："运动伤害现场急救处理虚拟仿真实验"
- 底部 5 个功能图标按钮：心肺复苏 | 骨折固定 | 扭伤包扎 | 出血包扎 | 伤员搬运
- 点击按钮 → 跳转 `ModeSelection` 场景

### 2. 模式选择场景 (`ModeSelection.unity`)

- 顶部提示：Tip：请选择实验模式
- 固定方式选项：肢体固定 | 夹板固定
- 运行模式选项：学习模式 | 考核模式
- 底部：开始实验 | 返回主菜单

### 3. 实验场景 (`Experiment.unity`)

**场景物体：**
| 物体 | 标签 | 说明 |
|------|------|------|
| Ground | - | 地板（Plane 10x10） |
| InjuredPerson | InjuredPerson | 伤者（占位 Capsule） |
| InjuryLeg | InjuryLeg | 伤腿交互区（Sphere，伤者子物体） |
| Rescuer | Rescuer | 施救者（占位 Capsule） |
| Shoe | Shoe | 鞋子（可点击交互） |
| Bandage | Bandage | 绷带（拖拽交互） |
| Splint | Splint | 夹板（拖拽交互） |
| FirstAidKit | FirstAidKit | 急救箱 |

**UI 层：**
| 组件 | 说明 |
|------|------|
| TipBar | 顶部提示栏（学习模式显示） |
| DialogueBubble | 角色对话气泡（自动4秒消失） |
| ProgressSlider | 底部进度条 |
| 右侧按钮 | 全屏、上一步、下一步、学习/考核切换、返回 |
| VideoPanel | 右下角画中画视频（学习模式特定步骤激活） |
| PopupSystem | 弹窗系统（考核题、成绩显示、注意事项） |

---

## 📝 骨折固定实验流程（学习模式）

| 步骤 | Tip 提示 | 交互方式 | 目标标签 |
|------|----------|----------|----------|
| 0. 环境评估 | 观察周围环境是否有危险，做好防护措施 | 按钮确认 | - |
| 1. 伤情检查 | 请检查伤员受伤位置 | 点击物体 | InjuryLeg |
| 2. 脱鞋袜检查 | 请将伤员鞋袜脱掉并保存好 | 点击物体 | Shoe |
| 3. 放置衬带 | 请在正确的位置穿宽度约10cm的带子 | 拖拽交互 | Bandage |
| 4. 肢体并拢 | 请在两下肢间加衬垫 | 按钮确认 | - |
| 5. 主干固定 | 固定骨折近心端、远心端、膝关节下 | 拖拽交互 | Bandage |
| 6. 踝关节固定 | 踝关节"8"字固定 | 拖拽交互 | Bandage |
| 7. 终末检查 | 包扎完毕请检查伤肢血液循环 | 按钮确认 | - |

## 📝 考核模式题目

| 考核点 | 题目 | 选项 | 正确答案 |
|--------|------|------|----------|
| 考核点一 | 按正确顺序进行环境评估与自我介绍 | 确定 | - |
| 考核点二 | 按正确顺序检查伤情 | 确定 | - |
| 考核点三 | 请选择合适的带子宽度 | 5cm / 10cm / 20cm | 10cm |
| 考核点四 | 请选择正确的放带子顺序 | 确定（交互排序） | - |
| 考核点五 | 请选择正确的系带子顺序 | 确定（交互排序） | - |
| 考核点六 | 请选择带子打结位置 | 确定（点击目标） | - |
| 考核点七 | 请选择踝关节打结位置 | 足底 / 足背 | 足背 |

---

## 🔧 交互类型枚举

| 类型 | 值 | 说明 |
|------|-----|------|
| None | 0 | 无交互 |
| ClickObject | 1 | 点击3D物体（需匹配 targetTag） |
| ClickGround | 2 | 点击地面空白处 |
| DragDrop | 3 | 拖拽物体到目标位置 |
| ButtonConfirm | 4 | 点击 UI 按钮确认 |
| MultipleChoice | 5 | 选择选项（考核模式） |

---

## 📦 待添加资源清单

### 3D 模型
- [ ] 室内田径馆场景（跑道、看台、跳高架、跳高垫）
- [ ] 伤者角色模型（男性、运动装、骨骼绑定）
- [ ] 施救者角色模型（女性、急救员装束、骨骼绑定）
- [ ] 急救箱（带红十字）
- [ ] 绷带/三角巾
- [ ] 夹板模型
- [ ] 鞋子/袜子模型

### 动画
- [ ] 伤者：跑步循环、跳高起跳、空中姿态、落地摔倒、躺地受伤
- [ ] 施救者：站立、蹲下、检查、脱鞋、包扎手部特写
- [ ] 推荐使用 Mixamo 获取基础动画或动捕制作

### 音频
- [ ] 背景音乐
- [ ] 语音解说 TTS

### 视频
- [ ] 真人演示视频（画中画，学习模式使用）

### UI 素材
- [ ] 5 个主功能图标
- [ ] 按钮样式
- [ ] 背景图

---

## 🚀 后续开发指南

### 添加新实验类型

1. 创建新的 `Resources/Data/xxx_steps.json` 配置
2. 在 `MainMenuUI.cs` 中添加按钮监听
3. 在 `ConfigLoader.cs` 中添加加载方法

### 替换占位模型

1. 导入真实模型到 `Assets/Models/` 对应子目录
2. 在 Experiment 场景中替换 Capsule/Cube 占位物
3. 确保各物体的 Tag 和 Collider 设置正确

### 添加真实动画

1. 导入动画到 `Assets/Animations/`
2. 为角色创建 Animator Controller
3. 在 `AnimationController.cs` 中关联 Animator 引用和状态名

### 部署 MCP for Unity（可选）

在 Unity 中：**Window → Package Manager → + → Add package from git URL**，粘贴：
```
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
```
然后 **Window → MCP for Unity → Configure All Detected Clients**。

---

## 依赖包

核心依赖已在 `Packages/manifest.json` 中锁定版本：

- **Universal RP** 14.0.12 — 渲染管线
- **TextMeshPro** 3.0.7 — 文字渲染
- **Timeline** 1.7.7 — 过场动画
- **UGUI** 1.0.0 — UI 系统

---

## 注意事项

- **不要删除 `.meta` 文件** — Unity 用它们追踪资源和 GUID
- `.gitignore` 已配置忽略 Library、Temp、Logs、UserSettings 等生成目录
- 占位模型 (Capsule/Cube) 后续需替换为真实美术资源
- 考核判分逻辑在 `GameManager.RecordExamAnswer()` 中实现
- 步骤配置通过 `Resources/Data/*.json` 管理，可在 Unity 外编辑