gratitude.durian.xpcool.com/cocos-prototype/README.md

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

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

重要文档：

• 📖 完整项目开发指南 - 从零开始到上架的完整流程
• 🏗️ 场景搭建与预制体配置 - 详细的场景节点和预制体制作说明
• 📄 游戏策划案 - 完整的游戏设计文档
• 🎵 音效与台词语料设计 - AI音频生成提示词
• 🎨 UI界面设计描述 - UI设计和AI绘图提示词
• 📱 微信小游戏上架资料 - 上架所需的全部文案

---

🚀 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）：

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

快速参考：

水果精灵规格

等级	名称	推荐尺寸	文件名
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

必需音频文件：

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

关键步骤：

1. 构建微信小游戏包：

   • Cocos Creator → 项目 → 构建发布
   • 平台选择：WeChat Mini Game
   • 填写 AppID

2. 配置广告位ID：

   • 在 AdManager.ts 中替换为你的真实广告位ID
   • 支持激励视频和插屏广告

3. 上传到微信开发者工具：

   • 导入 build/wechatgame/ 目录
   • 预览测试后提交审核

---

⚙️ 关键参数调优

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

// 物理参数
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 和 PROJECT_GUIDE.md

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 手册
• 微信小游戏开发指南
• TypeScript 官方文档

项目文档

• 📖 完整项目开发指南 - 从零开始到上架的全流程
• 🏗️ 场景搭建与预制体配置 - 详细的节点层级和组件配置
• 📄 游戏策划案 - 完整的游戏设计文档
• 🎵 音效与台词语料设计 - AI音频生成提示词
• 🎨 UI界面设计描述 - UI设计和AI绘图提示词
• 📱 微信小游戏上架资料 - 上架所需的全部文案

社区支持

• QoderWork 论坛 - 提问与交流
• Cocos 中文社区 - 引擎相关问题
• 微信开放社区 - 小游戏相关问题

---

🎉 下一步行动

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

祝你开发顺利！🚀

---

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