gratitude.durian.xpcool.com/wechat-miniprogram/README.md

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

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

✨ 项目特点

• ✅ 零依赖 - 不需要 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：安装微信开发者工具

如果没有安装，请先下载并安装 微信开发者工具

步骤 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：

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

配置广告位 ID

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

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

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

获取广告位 ID：

1. 登录 微信公众平台
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：

// 第 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() 方法中修改绘制逻辑：

// 原来绘制圆形
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 中添加：

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

2. 降低渲染频率

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

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() 方法中的距离阈值：

// 原来
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. 登录 微信公众平台
4. 进入"管理" → "版本管理"
5. 找到刚上传的版本，点击"提交审核"
6. 填写审核信息并提交

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

🆚 与 Cocos Creator 版本对比

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

📞 技术支持

如遇问题，请查阅：

• 📖 微信小程序官方文档
• 📖 Canvas API 文档
• 💬 微信开放社区

🎉 下一步计划

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

---

祝你开发顺利！ 🎮🚀

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