# 《报恩榴莲》Cocos Creator 3.8 核心玩法原型 - 快速入门指南

> 🎮 一款三三合成休闲小游戏，从开发到微信上架的完整原型

**重要文档**：
- 📖 [完整项目开发指南](PROJECT_GUIDE.md) - 从零开始到上架的完整流程
- 🏗️ [场景搭建与预制体配置](SCENE_SETUP_GUIDE.md) - 详细的场景节点和预制体制作说明
- 📄 [游戏策划案](../01_报恩榴莲_游戏策划案.md) - 完整的游戏设计文档
- 🎵 [音效与台词语料设计](../03_报恩榴莲_音效与台词语料设计.md) - AI音频生成提示词
- 🎨 [UI界面设计描述](../04_报恩榴莲_UI界面设计描述.md) - UI设计和AI绘图提示词
- 📱 [微信小游戏上架资料](../05_报恩榴莲_微信小游戏上架资料.md) - 上架所需的全部文案

---

## 🚀 5分钟快速运行

### 前置要求

- ✅ Cocos Creator 3.8.x 已安装
- ✅ 微信开发者工具（可选，用于真机测试）

### 步骤 1：导入项目

1. 打开 Cocos Creator 3.8
2. 点击 **"打开其他项目"**
3. 选择 `cocos-prototype` 文件夹
4. 等待资源导入完成

### 步骤 2：创建主场景

1. 在资源管理器中右键 `assets/` → 新建 → Scene
2. 命名为 `MainGame`
3. 双击打开场景编辑

### 步骤 3：搭建最简场景

按照以下层级创建节点（详细步骤见 [SCENE_SETUP_GUIDE.md](SCENE_SETUP_GUIDE.md)）：

```
Canvas
└── GameScene
    ├── GameContainer (Node)
    │   ├── LeftWall (Node + BoxCollider2D)
    │   ├── RightWall (Node + BoxCollider2D)
    │   ├── BottomWall (Node + BoxCollider2D)
    │   └── FruitLayer (Node)
    ├── DropArea (Node + UITransform)
    └── GameManagerNode (空节点，挂载 GameManager.ts)
```

### 步骤 4：制作 Fruit 预制体

1. 右键 `assets/prefabs/` → 新建 → Prefab → 命名 `Fruit`
2. 双击进入预制体编辑
3. 创建节点并添加组件：
   ```
   FruitRoot
   ├── FruitSprite (Sprite)
   ├── CircleCollider2D
   ├── RigidBody2D (Type=Dynamic, Fixed Rotation=true)
   └── Fruit.ts (脚本组件)
   ```
4. 保存预制体

### 步骤 5：绑定 GameManager 属性

1. 选中 `GameManagerNode`
2. 添加组件 → 搜索 `GameManager`
3. 拖拽绑定：
   - `gameContainer` → GameContainer
   - `dropArea` → DropArea
   - `fruitLayer` → FruitLayer
   - `fruitPrefab` → Fruit.prefab

### 步骤 6：运行测试

1. 点击编辑器顶部 **"预览"** 按钮（Ctrl+P）
2. 浏览器自动打开
3. 点击场景顶部区域
4. 观察水果掉落和物理碰撞

**✅ 如果看到水果掉落并堆积，核心玩法已跑通！**

---

## 📁 项目结构

```
cocos-prototype/
├── assets/
│   └── scripts/
│       ├── config/
│       │   └── GameConfig.ts          # 游戏配置数据（水果链、关卡表）
│       ├── core/
│       │   ├── GameManager.ts         # 游戏主控制器（集成所有系统）
│       │   ├── MergeCore.ts           # 三三合成核心逻辑（纯逻辑层）
│       │   ├── AudioManager.ts        # 音频管理器（BGM/SFX/Voice）
│       │   ├── SaveManager.ts         # 存档管理器（localStorage）
│       │   └── AdManager.ts           # 广告管理器（微信SDK接入）
│       ├── components/
│       │   ├── Fruit.ts               # 水果组件（视觉+动画）
│       │   ├── BossManager.ts         # Boss饱食度系统
│       │   └── GoldenLegendEffect.ts  # 金色传说特效
│       └── ui/
│           ├── MainMenuUI.ts          # 主菜单界面
│           ├── ResultPanel.ts         # 结算面板
│           └── CollectionUI.ts        # 图鉴界面
├── SCENE_SETUP_GUIDE.md               # 场景搭建详细指南
├── PROJECT_GUIDE.md                   # 完整项目开发指南
└── README.md                          # 本文件（快速入门）
```

---

## 🎯 核心功能清单

### ✅ 已实现系统

- **三三合成引擎**：纯逻辑层 MergeCore，支持连击倍率
- **物理掉落系统**：RigidBody2D + CircleCollider2D
- **Boss 饱食度系统**：投喂进度条、对话气泡
- **金色传说特效**：7步时间轴（暗化→光柱→粒子→彩带）
- **音频管理**：BGM淡入淡出、SFX池化、语音打断
- **存档系统**：localStorage 持久化，支持断点续玩
- **广告集成**：激励视频（复活/道具/双倍）、插屏广告
- **UI界面**：主菜单、结算面板、图鉴界面
- **关卡系统**：20关Boss progression，难度递增

### 🔄 待补充内容

- 美术资源替换（9个水果精灵、Boss图片、UI元素）
- 音频资源配置（BGM、SFX、Voice）
- 微信小游戏打包与上架

---

## 🎨 美术资源替换

详细的素材替换指南请查看 [PROJECT_GUIDE.md](PROJECT_GUIDE.md#六美术资源替换)

**快速参考**：

### 水果精灵规格

| 等级 | 名称 | 推荐尺寸 | 文件名 |
|------|------|----------|--------|
| 1 | 果切丁 | 36x36 | fruit_1.png |
| 2 | 西瓜片 | 50x50 | fruit_2.png |
| 3 | 紫葡萄 | 64x64 | fruit_3.png |
| 4 | 黄柠檬 | 80x80 | fruit_4.png |
| 5 | 红苹果 | 96x96 | fruit_5.png |
| 6 | 甜橙 | 112x112 | fruit_6.png |
| 7 | 粉桃子 | 128x128 | fruit_7.png |
| 8 | 金菠萝 | 152x152 | fruit_8.png |
| 9 | 报恩榴莲 | 180x180 | fruit_9.png |

**使用图集（推荐）**：
1. 将9张图片打包成 Sprite Atlas
2. 在 Fruit.ts 中动态加载对应等级的精灵帧

---

## 🔊 音频资源配置

详细的音频配置请查看 [PROJECT_GUIDE.md](PROJECT_GUIDE.md#七音频资源配置)

**必需音频文件**：

### BGM（背景音乐）
- `bgm_main.mp3` - 主游戏BGM
- `bgm_golden.mp3` - 金色传说BGM
- `bgm_result.mp3` - 结算BGM

### SFX（音效）
至少需要：`sfx_drop_fruit.mp3`, `sfx_merge_success.mp3`, `sfx_game_over.mp3`

### Voice（语音）
可选：`voice_golden_legend_a.mp3` 等

**存放路径**：`assets/audio/`

---

## 📱 微信小游戏集成

详细的微信小游戏集成步骤请查看 [PROJECT_GUIDE.md](PROJECT_GUIDE.md#八微信小游戏集成)

**关键步骤**：

1. **构建微信小游戏包**：
   - Cocos Creator → 项目 → 构建发布
   - 平台选择：WeChat Mini Game
   - 填写 AppID

2. **配置广告位ID**：
   - 在 `AdManager.ts` 中替换为你的真实广告位ID
   - 支持激励视频和插屏广告

3. **上传到微信开发者工具**：
   - 导入 `build/wechatgame/` 目录
   - 预览测试后提交审核

---

## ⚙️ 关键参数调优

所有数值配置都在 `GameConfig.ts` 中：

```typescript
// 物理参数
export const PhysicsConfig = {
    gravity: -9.8,           // 重力加速度
    restitution: 0.3,        // 弹性系数
    friction: 0.5,           // 摩擦系数
    dropCooldown: 0.3,       // 掉落冷却时间（秒）
};

// 性能限制
export const PerformanceConfig = {
    maxFruitsOnScreen: 50,   // 同屏最大水果数
};

// 水果链配置（9个等级）
export const FRUIT_CHAIN: FruitLevelConfig[] = [
    { level: 1, name: '果切丁', radius: 18, score: 1 },
    { level: 2, name: '西瓜片', radius: 25, score: 3 },
    // ... 更多等级
    { level: 9, name: '报恩榴莲', radius: 90, score: 6561 },
];

// 关卡配置（20关）
export const LEVEL_CONFIGS: LevelConfig[] = [
    { level: 1, bossName: '贪吃喵星人', targetLevel: 3, feedCount: 3 },
    // ... 更多关卡
];
```

**调优建议**：
- 如果低端机卡顿，降低 `maxFruitsOnScreen` 到 30
- 如果觉得水果下落太慢，增加 `gravity` 绝对值（如 -12）
- 如果想调整难度，修改关卡的 `targetLevel` 和 `feedCount`

---

## 🐛 常见问题

更多问题排查请查看 [SCENE_SETUP_GUIDE.md](SCENE_SETUP_GUIDE.md#九常见问题排查) 和 [PROJECT_GUIDE.md](PROJECT_GUIDE.md#十二常见问题faq)

### Q1: 水果不掉下来？

**检查清单**：
- [ ] RigidBody2D.Type 是否为 Dynamic？
- [ ] Allow Sleep 是否取消勾选？
- [ ] Gravity Scale 是否为 1？

### Q2: 合成判定不触发？

**检查清单**：
- [ ] MergeCore 是否正确初始化？
- [ ] 是否在合适时机调用 `tryMerge()`？
- [ ] 水果的 level 属性是否正确设置？

### Q3: 金色传说特效不播放？

**检查清单**：
- [ ] goldenEffectNode 是否正确绑定？
- [ ] GoldenLegendEffect 组件是否挂载？
- [ ] 特效节点 Z-order 是否在最上层？

### Q4: 音效不播放？

**检查清单**：
- [ ] AudioManager 是否已 init()？
- [ ] 音频文件是否在 `assets/audio/` 目录？
- [ ] 音量是否被设为 0 或静音？

### Q5: 微信真机测试广告不显示？

**可能原因**：
- 未开通流量主（需 ≥ 1000 UV）
- 广告位ID错误
- 使用的是模拟器而非真机

---

## 📞 技术支持与参考资料

### 官方文档
- [Cocos Creator 3.8 手册](https://docs.cocos.com/creator/3.8/manual/zh/)
- [微信小游戏开发指南](https://developers.weixin.qq.com/minigame/dev/guide/)
- [TypeScript 官方文档](https://www.typescriptlang.org/docs/)

### 项目文档
- 📖 [完整项目开发指南](PROJECT_GUIDE.md) - 从零开始到上架的全流程
- 🏗️ [场景搭建与预制体配置](SCENE_SETUP_GUIDE.md) - 详细的节点层级和组件配置
- 📄 [游戏策划案](../01_报恩榴莲_游戏策划案.md) - 完整的游戏设计文档
- 🎵 [音效与台词语料设计](../03_报恩榴莲_音效与台词语料设计.md) - AI音频生成提示词
- 🎨 [UI界面设计描述](../04_报恩榴莲_UI界面设计描述.md) - UI设计和AI绘图提示词
- 📱 [微信小游戏上架资料](../05_报恩榴莲_微信小游戏上架资料.md) - 上架所需的全部文案

### 社区支持
- [QoderWork 论坛](https://forum.qoder.com/) - 提问与交流
- [Cocos 中文社区](https://forum.cocos.org/) - 引擎相关问题
- [微信开放社区](https://developers.weixin.qq.com/community/) - 小游戏相关问题

---

## 🎉 下一步行动

1. **立即运行**：按照"5分钟快速运行"章节搭建场景并测试
2. **阅读详细文档**：查看 [PROJECT_GUIDE.md](PROJECT_GUIDE.md) 了解完整开发流程
3. **替换美术资源**：准备9个水果精灵图和Boss图片
4. **配置音频**：使用 AI 工具生成 BGM 和音效
5. **真机测试**：在微信开发者工具中预览并扫码测试
6. **提交审核**：构建微信小游戏包并提交上架

**祝你开发顺利！🚀**

---

**项目版本**：v1.0  
**最后更新**：2026-08-14  
**适用引擎**：Cocos Creator 3.8.x  
**许可证**：MIT