# PRD —— Third-Person-MC 体素世界引擎（v3.0）

## 1. 产品概述与目标

### 1.1 产品定位
基于 **Three.js + Vue 3** 搭建的网页 3D 演示，展示 **MC 风格无限地形生成** 与 **第三人称角色控制** 的技术预热体验。目标是将 Web3D 做成"可跑、可玩、可继续迭代"的项目，而不只是一个截图 Demo。

### 1.2 核心体验流程
```
加载界面 → 主菜单（世界设置） → 无限地形探索 → 与世界互动 → 暂停/设置 → 继续探索
```

### 1.3 在线预览
| 环境 | 地址 |
|------|------|
| 生产环境 | `https://third-person-mc.vercel.app/` |
| Debug 模式 | `https://third-person-mc.vercel.app/#debug` |

---

## 2. 目标受众
- Web3D 技术爱好者，对体素风格和程序化生成感兴趣
- Minecraft 或类似沙盒游戏玩家
- 主要使用 **PC 端 Chrome 浏览器**
- 最低支持分辨率：**1380 × 840**

---

## 3. 核心功能模块

### 3.1 无限地形系统

#### 3.1.1 Chunk 管理
| 属性 | 规格 |
|------|------|
| Chunk 尺寸 | 16 × 16 × 64 方块 |
| 动态加载 | 基于玩家位置动态加载/卸载 Chunk |
| 渲染距离 | 可调节，默认 8 Chunks |
| 数据持久化 | 支持 Chunk 数据缓存 |

#### 3.1.2 地形生成
| 属性 | 规格 |
|------|------|
| 噪声算法 | Perlin Noise + FBM |
| 种子系统 | 相同 Seed 生成相同世界 |
| 地形振幅 | 可调节高度变化幅度 |
| 地面细节 | FBM 控制表面侵蚀细节 |

#### 3.1.3 生态系统（Biome）
| 生态类型 | 特征 |
|----------|------|
| 平原 | 广阔草地，稀疏树木 |
| 森林 | 橡树为主，密集植被 |
| 白桦林 | 白桦树群落 |
| 樱花林 | 粉色樱花树 |
| 沙漠 | 沙地，仙人掌 |
| 冻洋 | 冰雪地形 |

#### 3.1.4 Chunk 随机事件（新功能）
每个新生成的 Chunk 有 **0~1** 个随机特殊事件生成：

| 事件类型 | 描述 | 出现概率 |
|----------|------|---------|
| 🐕 可爱小狗 | 一只可互动的宠物狗，可跟随玩家 | 10% |
| 🌀 神秘传送门 | 传送到随机位置的传送门 | 5% |
| 🧑‍🌾 村民 NPC | 可对话的村民角色 | 8% |
| 💎 宝箱 | 可开启的宝箱（装饰性） | 15% |
| 🏠 废弃小屋 | 预制建筑结构 | 3% |
| ❌ 无事件 | 正常 Chunk，无特殊内容 | 59% |

#### 3.1.5 验收标准
- [x] Chunk 动态加载/卸载正常工作
- [x] 相同 Seed 生成一致的地形
- [x] 多生态平滑过渡
- [x] 地形振幅与 FBM 参数可调节
- [ ] Chunk 随机事件系统实现

---

### 3.2 第三人称角色控制

#### 3.2.1 运动系统
| 操作 | 按键 | 说明 |
|------|------|------|
| 移动 | `W / A / S / D` | 八向位移，包含姿态切换 |
| 跳跃 | `空格` | 单次跳跃 |
| 冲刺 | `Shift` | 加速移动 |
| 普通攻击 | `Z` | 支持连击 Combo |
| 重攻击 | `X` | 强力打击反馈 |
| 格挡 | `C` | 防御动作 |

#### 3.2.2 相机系统
| 功能 | 规格 |
|------|------|
| 相机类型 | 第三人称跟随 |
| 避障系统 | 自动检测地形，防止穿模 |
| 视角旋转 | 鼠标控制，360° 自由旋转 |
| 越肩切换 | 支持左/右肩视角平滑过渡 |

#### 3.2.3 验收标准
- [x] 角色移动流畅，动画衔接自然
- [x] 相机跟随不穿透地形
- [x] 攻击 Combo 连击正常
- [x] 越肩切换动画平滑

---

### 3.3 HUD / UI 系统

#### 3.3.1 游戏内 HUD
| 组件 | 位置 | 功能 |
|------|------|------|
| 血量条 | 屏幕下方 | 显示玩家当前血量 |
| 饥饿条 | 屏幕下方 | 显示饥饿值 |
| 经验条 | 屏幕下方 | 显示经验进度 |
| 快捷栏 | 屏幕下方 | 物品快捷栏（装饰性） |
| 坐标显示 | 左上角 | 显示玩家世界坐标 |
| 指南针 | 右上角 | 方向指示 |
| 信息面板 | 右上角 | FPS、时间、天数等 |
| 按键提示 | 左下角 | 实时按键反馈 |
| 聊天框 | 左下角 | 聊天/命令输入 |
| 准星 | 屏幕中央 | 瞄准指示 |
| 小地图 | 右下角 | 周围地形预览 |

#### 3.3.2 菜单系统
| 菜单 | 功能 |
|------|------|
| 加载界面 | 显示世界加载进度 |
| 主菜单 | 世界创建、高级设置 |
| 暂停菜单 | 继续/返回主菜单/设置 |
| 设置菜单 | 画质、渲染距离等选项 |
| 操作指南 | 按键说明弹窗 |

#### 3.3.3 验收标准
- [x] 所有 HUD 组件正确渲染
- [x] 菜单导航流畅
- [x] 暂停时游戏正确冻结
- [x] 设置项正确生效

---

### 3.4 渲染与视觉效果

#### 3.4.1 体素渲染
| 技术 | 规格 |
|------|------|
| 渲染方式 | InstancedMesh 实例化渲染 |
| 方块贴图 | 纹理图集 (Texture Atlas) |
| AO 效果 | GPU 端环境光遮蔽 |
| 植被动画 | 风吹摇摆效果 (Vertex Shader) |

#### 3.4.2 环境效果
| 效果 | 说明 |
|------|------|
| 光照 | 方向光 + 环境光 |
| 阴影 | 级联阴影贴图 (CSM) |
| 天空 | 渐变天空盒 |
| 雾效 | 距离雾营造氛围 |

#### 3.4.3 验收标准
- [x] 大规模方块渲染帧率稳定
- [x] AO 效果正确显示
- [x] 植被风动效果自然
- [x] 阴影质量可调节

---

## 4. 技术栈与架构

### 4.1 核心技术栈
| 类别 | 技术 |
|------|------|
| 渲染框架 | Vite + Three.js (v0.172+) |
| UI 框架 | Vue 3 |
| 状态管理 | Pinia + mitt 事件总线 |
| 样式工具 | Tailwind CSS + Sass |
| 动画库 | GSAP |
| 着色器 | GLSL + vite-glsl-plugin |
| 材质增强 | three-custom-shader-material |
| 测试框架 | Playwright |

### 4.2 系统架构
```
┌─────────────────────────────────────────────────────────────┐
│                        Vue 3 UI Layer                        │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │   Menu      │ │    HUD      │ │  Settings   │            │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
└─────────────────────────────────────────────────────────────┘
                           │
                     mitt (事件总线)
                           │
┌─────────────────────────────────────────────────────────────┐
│                   Experience (单例核心)                       │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │   World     │ │   Camera    │ │  Renderer   │            │
│  │             │ │             │ │             │            │
│  │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │            │
│  │ │ Player  │ │ │ │  Rig    │ │ │ │ Shader  │ │            │
│  │ │ Terrain │ │ │ └─────────┘ │ │ │ Effects │ │            │
│  │ │ Environ │ │ │             │ │ └─────────┘ │            │
│  │ └─────────┘ │ │             │ │             │            │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
└─────────────────────────────────────────────────────────────┘
```

### 4.3 地形系统架构
```
ChunkManager (区块管理器)
    │
    ├── TerrainChunk (地形区块)
    │       │
    │       ├── TerrainContainer (数据容器)
    │       │       └── 方块数据、AO 数据
    │       │
    │       ├── TerrainGenerator (地形生成器)
    │       │       ├── BiomeGenerator (生态生成)
    │       │       └── Noise Functions
    │       │
    │       └── TerrainRenderer (渲染器)
    │               ├── InstancedMesh
    │               └── PlantRenderer
    │
    └── TerrainPersistence (持久化)
```

### 4.4 部署与监控
| 类别 | 方案 |
|------|------|
| 托管 | Vercel 静态部署 |
| 压缩 | gzip + HTTP2 |
| 代码规范 | Husky + Commitlint |

---

## 5. 项目结构

```text
Third-Person-MC/
├── public/                 # 静态资源
│   ├── models/             # GLB/GLTF 模型 (角色、方块)
│   ├── textures/           # 材质贴图 (环境、方块、HUD)
│   └── fonts/              # Minecraft 字体
├── src/
│   ├── components/         # Vue UI 组件
│   │   ├── hud/            # 游戏内 HUD (血条、快捷栏等)
│   │   ├── menu/           # 菜单系统
│   │   ├── Crosshair.vue   # 准星组件
│   │   └── MiniMap.vue     # 小地图组件
│   ├── js/                 # 核心逻辑
│   │   ├── camera/         # 相机控制器与 Rig
│   │   ├── world/          # 场景元素、玩家逻辑
│   │   │   ├── player/     # 玩家控制与动画
│   │   │   └── terrain/    # 地形生成系统
│   │   ├── interaction/    # 射线拾取、方块交互
│   │   ├── utils/          # 调试、事件、输入解析
│   │   ├── config/         # 配置文件
│   │   └── experience.js   # 框架单例入口
│   ├── shaders/            # 自定义 GLSL 着色器
│   └── vue/                # Pinia Stores
├── docs/                   # 产品文档与开发计划
└── vite.config.js          # 构建配置
```

---

## 6. 素材出处

| 素材类型 | 来源 |
|----------|------|
| 角色模型 | 基于 MC 风格自定义建模 (character.glb) |
| 皮肤 | [minecraftskins.com](https://www.minecraftskins.com/) |
| 方块贴图 | 提取自 Minecraft [Mojang/bedrock-samples](https://github.com/Mojang/bedrock-samples)，由 hexianWeb 优化 |
| 字体 | [Minecraftia-Regular.ttf](https://www.dafont.com/minecraftia.font) & [TakWolf/fusion-pixel-font](https://github.com/TakWolf/fusion-pixel-font) |
| 音效 | 计划由 Suno AI 生成 (待实现) |

---

## 7. 按键操作速查表

| 操作 | 按键 |
|------|------|
| 移动 | `W / A / S / D` |
| 跳跃 | `空格` |
| 冲刺 | `Shift` |
| 普通攻击 | `Z` |
| 重攻击 | `X` |
| 格挡 | `C` |
| 互动 | `E / F` |
| 越肩切换 | `Q` |
| 打开菜单 | `ESC` |

---

## 8. 开发计划 (TODO)

### 高优先级 (P0)
- [ ] **Chunk 随机事件系统**：实现 Chunk 生成时随机触发特殊事件
  - [ ] 可爱小狗：宠物 AI 逻辑与跟随系统
  - [ ] 神秘传送门：传送功能实现
  - [ ] 村民 NPC：基础对话系统
- [ ] **敌人锁定特效**：魂类锁定视觉反馈增强

### 中优先级 (P1)
- [ ] **更好的 Biome**：优化生态转换平滑度与更多植被种类
- [ ] **背包功能**：实现完整的物品存放与交互 UI
- [ ] **挖掘特效**：方块破坏时的粒子效果与动画
- [ ] **换肤功能**：实时切换玩家模型贴图

### 低优先级 (P2)
- [ ] **音效系统**：命中、环境音效 (Suno AI)
- [ ] **多语言支持**：国际化
- [ ] **移动端适配**：触控操作支持

---

## 9. 潜在挑战与应对

| 挑战 | 解决方案 |
|------|----------|
| **大规模方块渲染性能** | InstancedMesh + 视锥剔除 + LOD |
| **Chunk 加载卡顿** | Web Worker 异步生成 |
| **相机穿模** | 射线检测 + 动态调整距离 |
| **生态过渡突兀** | 噪声混合 + 边界模糊 |
| **随机事件平衡** | 概率配置 + 距离限制 |

---

## 10. 未来扩展

- 多人联机支持 (WebSocket/WebRTC)
- 方块放置/破坏系统
- 更多生物类型 (动物、怪物)
- 天气系统 (雨、雪、雷电)
- 日夜循环
- 成就系统
- 世界存档导出/导入

---

> **版本记录**
> - v3.0 (2026-01) - 重大更新：基于实际项目状态重写 PRD，新增 Chunk 随机事件系统规划
> - v2.0 (2024-12) - 多世界传送门系统、实时动作战斗（已废弃）
> - v1.0 - 初版：单地牢回合制战斗演示（已废弃）

---

请在实现过程中根据 Three.js 框架规范，保持 Experience 单例的依赖获取方式，并为新增组件添加中文调试注释与控制面板（`debugInit`），确保与现有代码风格一致。