# 报恩榴莲 - 微信小程序原生版本

> 🎮 一款纯原生实现的三三合成休闲小游戏，无需游戏引擎，直接在微信开发者工具中运行

## ✨ 项目特点

- ✅ **零依赖** - 不需要 Cocos Creator、Unity 等任何游戏引擎
- ✅ **纯原生** - 使用微信小程序原生 Canvas API 绘制
- ✅ **轻量级** - 代码简洁，性能优秀
- ✅ **快速上手** - 直接在微信开发者工具中打开即可运行
- ✅ **完整功能** - 包含物理系统、合成逻辑、音频管理、广告集成、存档系统等
- ✅ **音频支持** - 完整的BGM和音效管理系统（需配置音频文件）

## 📁 项目结构

```
wechat-miniprogram/
├── app.json                    # 小程序全局配置
├── app.js                      # 小程序入口和全局逻辑
├── project.config.json         # 项目配置文件
├── sitemap.json                # 站点地图配置
├── pages/
│   ├── game/
│   │   ├── index.wxml          # 游戏页面结构
│   │   ├── index.wxss          # 游戏页面样式
│   │   ├── index.js            # 游戏核心逻辑（含音频集成）
│   │   └── index.json          # 页面配置
│   └── index/
│       ├── index.wxml          # 主菜单页面结构
│       ├── index.wxss          # 主菜单页面样式
│       ├── index.js            # 主菜单逻辑
│       └── index.json          # 页面配置
├── utils/
│   └── AudioManager.js         # 音频管理器（BGM/SFX/Voice）
├── images/                     # 图片资源目录（可选）
└── audio/                      # 音频资源目录（可选）
    ├── bgm_main.mp3            # 主BGM
    ├── sfx_drop.mp3            # 掉落音效
    ├── sfx_merge.mp3           # 合成音效
    └── ...
```

## 🚀 快速开始

### 步骤 1：安装微信开发者工具

如果没有安装，请先下载并安装 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)

### 步骤 2：导入项目

1. 打开微信开发者工具
2. 点击 **"导入项目"**
3. 选择项目目录：**`E:\xxcool\project\gratitude.durian.xpcool.com\wechat-miniprogram`**
4. 填写 AppID：
   - 测试阶段：可以使用 **测试号**（点击"注册测试号"）
   - 正式开发：使用你的真实小程序 AppID
5. 点击"导入"

### 步骤 3：运行预览

导入成功后，点击工具栏的 **"编译"** 按钮，即可在模拟器中看到游戏运行。

### 步骤 4：真机测试

1. 点击工具栏的 **"预览"** 按钮
2. 用手机微信扫码
3. 在手机上体验游戏

## 🎯 游戏功能

### 页面结构

- **主菜单** (`pages/index/`) - 游戏入口，显示最高分数、连击记录，提供开始游戏按钮
- **游戏页** (`pages/game/`) - 核心游戏界面，包含掉落、合成、Boss投喂等玩法

### 核心玩法

1. **点击屏幕顶部** - 掉落水果
2. **三个相同等级水果相邻** - 自动合成更高等级
3. **投喂Boss** - 合成出指定等级水果可投喂Boss
4. **通关条件** - 投喂Boss达到指定次数

### 道具系统

- 💣 **炸弹** - 移除最低等级的水果
- ❄️ **冰冻** - 暂停所有水果运动3秒
- 🎬 **看视频复活** - 观看激励视频广告后复活

### 连击系统

- 2秒内连续合成触发连击
- 连击数越高，得分倍率越高
- 最高连击记录会保存

### 金色传说

- 合成出 Lv9 "报恩榴莲" 时触发
- 播放特殊特效和音效
- Boss 立即饱食度+1

## ⚙️ 配置说明

### 修改 AppID

编辑 `project.config.json`：

```json
{
  "appid": "wxb2b7651c561f9d53",  // 替换为你的真实 AppID
  "projectname": "grateful-durian-miniprogram"
}
```

### 配置广告位 ID

编辑 `app.js`，找到以下位置并替换：

```javascript
// 第 58 行 - 激励视频广告
this.globalData.rewardedVideoAd = wx.createRewardedVideoAd({
  adUnitId: 'adunit-xxxxxxxxxxxxxxxx'  // TODO: 替换为真实广告位ID
});

// 第 78 行 - 插屏广告
this.globalData.interstitialAd = wx.createInterstitialAd({
  adUnitId: 'adunit-yyyyyyyyyyyyyyyy'  // TODO: 替换为真实广告位ID
});
```

获取广告位 ID：
1. 登录 [微信公众平台](https://mp.weixin.qq.com/)
2. 进入"推广" → "流量主"
3. 创建广告位并复制 ID

⚠️ **注意**：需要 ≥ 1000 UV 才能开通流量主

### 添加音频资源

将音频文件放入 `audio/` 目录：

```
audio/
├── bgm_main.mp3           # 主BGM（循环播放）
├── bgm_golden.mp3         # 金色传说BGM（可选）
├── bgm_result.mp3         # 结算BGM（可选）
├── sfx_drop.mp3           # 掉落音效
├── sfx_merge.mp3          # 合成音效
├── sfx_combo2.mp3         # 2连击音效（可选）
├── sfx_combo3.mp3         # 3连击音效（可选）
├── sfx_combo4.mp3         # 4连击音效（可选）
├── sfx_combo5.mp3         # 5连击音效（可选）
├── sfx_golden.mp3         # 金色传说音效
├── sfx_clear.mp3          # 通关音效
├── sfx_gameover.mp3       # 失败音效
└── sfx_revive.mp3         # 复活音效（可选）
```

**音频管理器已集成**：
- 游戏启动时自动播放 BGM
- 暂停时停止 BGM，继续时恢复
- 所有音效通过 `AudioManager.js` 统一管理
- 页面卸载时自动释放音频资源

**AI 生成提示词**：详细的声音设计指南请参考项目根目录的 `03_报恩榴莲_音效与台词语料设计.md`

### 调整游戏参数

编辑 `pages/game/index.js`：

```javascript
// 第 5 行 - 水果配置
const FRUIT_CONFIGS = [
  { level: 1, name: '果切丁', radius: 18, color: '#FF6B6B', score: 1 },
  // ... 可以修改半径、颜色、分数
];

// 第 15 行 - 关卡配置
const LEVEL_CONFIGS = [
  { 
    level: 1, 
    bossName: '贪吃喵星人', 
    targetLevel: 3,      // 需要合成的水果等级
    feedCount: 3,        // 需要投喂次数
    dropMin: 1,          // 掉落水果最小等级
    dropMax: 2           // 掉落水果最大等级
  },
  // ... 可以添加更多关卡
];

// 第 150 行 - 物理参数
const gravity = 0.5;     // 重力加速度
const damping = 0.98;    // 阻尼系数
const bounce = 0.3;      // 弹性系数
```

## 🎨 自定义美术资源

### 替换水果贴图（可选）

如果想使用图片而非纯色圆形：

1. 准备9张水果图片（PNG格式），命名为 `fruit_1.png` ~ `fruit_9.png`
2. 放入 `images/` 目录
3. 在 `pages/game/index.js` 的 `render()` 方法中修改绘制逻辑：

```javascript
// 原来绘制圆形
ctx.beginPath();
ctx.arc(fruit.x, fruit.y, fruit.radius, 0, 2 * Math.PI);
ctx.fillStyle = fruit.color;
ctx.fill();

// 改为绘制图片
const imgPath = `/images/fruit_${fruit.level}.png`;
ctx.drawImage(imgPath, fruit.x - fruit.radius, fruit.y - fruit.radius, 
              fruit.radius * 2, fruit.radius * 2);
```

## 📊 性能优化建议

### 1. 限制同屏水果数量

在 `pages/game/index.js` 中添加：

```javascript
dropFruit(x, level) {
  // 限制最多50个水果
  if (this.gameState.fruits.length >= 50) {
    console.warn('[Game] 水果数量已达上限');
    return;
  }
  // ... 原有逻辑
}
```

### 2. 降低渲染频率

如果低端机卡顿，可以降低渲染帧率：

```javascript
startGameLoop() {
  let lastTime = Date.now();
  
  const loop = () => {
    const now = Date.now();
    
    // 每33ms渲染一次（约30fps）
    if (now - lastTime >= 33) {
      if (!this.data.isPaused) {
        this.update();
        this.render();
      }
      lastTime = now;
    }
    
    requestAnimationFrame(loop);
  };
  
  loop();
}
```

### 3. 减少粒子特效

金色传说特效可以简化或禁用。

## 🔧 常见问题

### Q1: 编译时报错 "Canvas not found"

**原因**：WXML 中的 canvas-id 与 JS 中的不一致  
**解决**：确保 `index.wxml` 和 `index.js` 中的 canvas-id 都是 `'gameCanvas'`

### Q2: 真机测试时广告不显示

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

**解决**：
1. 确保已申请微信流量主资格
2. 使用真机扫码测试
3. 检查 `app.js` 中的广告位 ID 是否正确

### Q3: 音频不播放

**原因**：
- 音频文件路径错误
- 文件格式不支持（建议使用 MP3）
- 音量设置为 0

**解决**：
1. 确保音频文件在 `audio/` 目录
2. 使用 MP3 格式
3. 检查手机音量是否开启

### Q4: 水果合成判定不准确

**解决**：调整 `checkMerges()` 方法中的距离阈值：

```javascript
// 原来
if (distance < f1.radius + f2.radius - 5) {

// 改为（更宽松）
if (distance < f1.radius + f2.radius - 10) {
```

### Q5: 低端机卡顿严重

**解决**：
1. 降低同屏水果数量至 30
2. 降低渲染帧率至 30fps
3. 关闭调试日志（发布前）

## 📱 提交审核

### 准备材料

1. **5张 gameplay 截图** - 展示不同关卡的游戏画面
2. **应用描述** - 简要介绍游戏玩法
3. **分类选择** - 游戏 → 休闲

### 提交步骤

1. 在微信开发者工具中点击 **"上传"**
2. 填写版本号（如 1.0.0）和版本描述
3. 登录 [微信公众平台](https://mp.weixin.qq.com/)
4. 进入"管理" → "版本管理"
5. 找到刚上传的版本，点击"提交审核"
6. 填写审核信息并提交

审核通常需要 **1-3个工作日**。

## 🆚 与 Cocos Creator 版本对比

| 特性 | 微信小程序原生版 | Cocos Creator 版 |
|------|------------------|------------------|
| 学习成本 | ⭐ 低（只需JS基础） | ⭐⭐⭐ 高（需学引擎API） |
| 开发速度 | ⭐⭐⭐ 快 | ⭐⭐ 中等 |
| 代码量 | ~500行 | ~2000行 |
| 包体积 | ~50KB | ~2MB+ |
| 性能 | ⭐⭐⭐ 优秀 | ⭐⭐ 良好 |
| 跨平台 | ❌ 仅微信 | ✅ 多平台支持 |
| 物理引擎 | 简单自实现 | Box2D 完整支持 |
| 动画系统 | 手动实现 | Timeline 编辑器 |
| 适合场景 | 简单休闲游戏 | 复杂商业游戏 |

## 📞 技术支持

如遇问题，请查阅：
- 📖 [微信小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
- 📖 [Canvas API 文档](https://developers.weixin.qq.com/miniprogram/dev/api/canvas/CanvasContext.html)
- 💬 [微信开放社区](https://developers.weixin.qq.com/community/)

## 🎉 下一步计划

- [ ] 添加更多关卡（目前只有3关示例）
- [ ] 完善音频系统（加载真实音频文件）
- [ ] 添加成就系统
- [ ] 添加排行榜功能
- [ ] 优化物理引擎（更真实的碰撞检测）
- [ ] 添加粒子特效（合成时的光效）

---

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

**项目版本**：v1.0  
**最后更新**：2026-08-14  
**适用平台**：微信小程序  
**许可证**：MIT