422 lines
11 KiB
Markdown
422 lines
11 KiB
Markdown
# 《报恩榴莲》微信小程序 - 测试与部署指南
|
||
|
||
> 🎮 纯原生微信小程序版本，无需 Cocos Creator
|
||
|
||
---
|
||
|
||
## 🚀 快速开始（5分钟运行）
|
||
|
||
### 前置要求
|
||
|
||
- ✅ 微信开发者工具已安装（[下载地址](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)）
|
||
- ✅ 拥有微信小程序 AppID（或使用测试号）
|
||
|
||
### 步骤 1：导入项目
|
||
|
||
1. 打开 **微信开发者工具**
|
||
2. 点击 **"导入项目"** 或 **"+"** 按钮
|
||
3. 选择目录：`E:\xxcool\project\gratitude.durian.xpcool.com\wechat-miniprogram`
|
||
4. 填写 AppID（如果没有，可先使用测试号）
|
||
5. 点击 **"导入"**
|
||
|
||
### 步骤 2：配置 AppID（如果需要）
|
||
|
||
如果使用的是自己的 AppID，需要修改以下文件：
|
||
|
||
**app.json** 和 **project.config.json** 中的 `appid` 字段：
|
||
```json
|
||
{
|
||
"appid": "你的AppID"
|
||
}
|
||
```
|
||
|
||
### 步骤 3：编译并预览
|
||
|
||
1. 等待项目编译完成（通常几秒）
|
||
2. 左侧模拟器会自动显示游戏界面
|
||
3. 点击顶部区域掉落水果，观察物理效果和合成逻辑
|
||
|
||
**✅ 如果看到水果掉落并能合成，核心玩法已跑通！**
|
||
|
||
---
|
||
|
||
## 📱 真机测试
|
||
|
||
### 方法 1：扫码预览
|
||
|
||
1. 在微信开发者工具中点击 **"预览"** 按钮
|
||
2. 用微信扫描生成的二维码
|
||
3. 在手机上体验游戏
|
||
|
||
### 方法 2：真机调试
|
||
|
||
1. 点击 **"真机调试"** 按钮
|
||
2. 扫码连接真机
|
||
3. 可以实时查看控制台日志和性能数据
|
||
|
||
---
|
||
|
||
## 🎯 功能测试清单
|
||
|
||
### ✅ 核心玩法
|
||
|
||
- [ ] 点击屏幕顶部能掉落水果
|
||
- [ ] 水果受重力影响下落
|
||
- [ ] 水果与地面、墙壁碰撞正常
|
||
- [ ] 相同等级的两个水果接触时自动合成
|
||
- [ ] 合成后生成更高等级的水果
|
||
- [ ] 分数随合成增加
|
||
- [ ] 连击系统正常工作（2秒内连续合成）
|
||
|
||
### ✅ Boss 系统
|
||
|
||
- [ ] Boss 进度条显示正确
|
||
- [ ] 投喂达到目标等级的水果时进度增加
|
||
- [ ] 进度满时触发通关
|
||
|
||
### ✅ UI 交互
|
||
|
||
- [ ] 分数、连击数实时更新
|
||
- [ ] 下一个水果预览显示正确
|
||
- [ ] 暂停/继续按钮工作正常
|
||
- [ ] 道具按钮（炸弹、冰冻）可用
|
||
- [ ] 结算面板在通关/失败时显示
|
||
|
||
### ✅ 音频系统
|
||
|
||
- [ ] 游戏开始时播放背景音乐
|
||
- [ ] 暂停时停止BGM，继续时恢复
|
||
- [ ] 掉落水果时播放音效
|
||
- [ ] 合成时播放音效
|
||
- [ ] 通关/失败时播放对应音效
|
||
- [ ] 金色传说特效播放特殊音效
|
||
|
||
> **注意**：音频文件需要手动添加到 `audio/` 目录，详见下方"音频资源配置"章节
|
||
|
||
### ✅ 广告系统（需配置真实广告位ID）
|
||
|
||
- [ ] 复活按钮点击后弹出激励视频
|
||
- [ ] 观看完整广告后成功复活
|
||
- [ ] 插屏广告在关卡切换时显示
|
||
|
||
> **注意**：广告功能需要开通流量主并配置真实广告位ID
|
||
|
||
### ✅ 存档系统
|
||
|
||
- [ ] 游戏进度自动保存
|
||
- [ ] 重新进入小游戏时加载上次进度
|
||
- [ ] 最高分数、连击记录正确
|
||
|
||
---
|
||
|
||
## 🎨 美术资源替换
|
||
|
||
当前版本使用彩色圆形代表水果，如需替换为精美贴图：
|
||
|
||
### 水果精灵图规格
|
||
|
||
| 等级 | 名称 | 推荐尺寸 | 文件名建议 |
|
||
|------|------|----------|-----------|
|
||
| 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张PNG图片（透明背景）
|
||
2. 放入 `assets/images/` 目录
|
||
3. 修改 `pages/game/index.js` 的渲染逻辑，将圆形绘制改为图片绘制：
|
||
|
||
```javascript
|
||
// 原代码（绘制圆形）
|
||
ctx.beginPath();
|
||
ctx.arc(fruit.x, fruit.y, fruit.radius, 0, 2 * Math.PI);
|
||
ctx.fillStyle = fruit.color;
|
||
ctx.fill();
|
||
|
||
// 替换为（绘制图片）
|
||
const imgPath = `/assets/images/fruit_${fruit.level}.png`;
|
||
ctx.drawImage(imgPath, fruit.x - fruit.radius, fruit.y - fruit.radius,
|
||
fruit.radius * 2, fruit.radius * 2);
|
||
```
|
||
|
||
---
|
||
|
||
## 🔊 音频资源配置
|
||
|
||
### 必需音频文件
|
||
|
||
#### BGM（背景音乐）
|
||
- `bgm_main.mp3` - 主游戏BGM（循环播放）
|
||
- `bgm_golden.mp3` - 金色传说BGM（可选）
|
||
- `bgm_result.mp3` - 结算界面BGM（可选）
|
||
|
||
#### SFX（音效）
|
||
- `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` - 复活
|
||
|
||
### 存放路径
|
||
|
||
将所有音频文件放入 `audio/` 目录：
|
||
```
|
||
wechat-miniprogram/
|
||
└── audio/
|
||
├── bgm_main.mp3
|
||
├── sfx_drop.mp3
|
||
├── sfx_merge.mp3
|
||
└── ...（其他音效）
|
||
```
|
||
|
||
### AI 音频生成提示词
|
||
|
||
可使用以下工具生成音频：
|
||
- **Suno AI** / **Udio** - 生成BGM
|
||
- **ElevenLabs** - 生成语音
|
||
- **Freesound.org** - 免费音效素材
|
||
|
||
详细提示词请参考项目根目录的 `03_报恩榴莲_音效与台词语料设计.md`
|
||
|
||
---
|
||
|
||
## ⚙️ 关键参数调优
|
||
|
||
所有游戏参数都在 `pages/game/index.js` 中：
|
||
|
||
### 物理参数
|
||
|
||
```javascript
|
||
updateFruits(dt) {
|
||
const gravity = 0.5; // 重力加速度（增大则下落更快）
|
||
const damping = 0.98; // 阻尼系数（减小则摩擦更大）
|
||
const bounce = 0.3; // 弹性系数（增大则弹跳更高）
|
||
const groundY = 600; // 地面Y坐标
|
||
// ...
|
||
}
|
||
```
|
||
|
||
**调优建议**：
|
||
- 如果觉得水果下落太慢，增加 `gravity`（如 0.8）
|
||
- 如果觉得水果弹跳太多，减小 `bounce`（如 0.2）
|
||
- 如果想让水果更快静止，减小 `damping`（如 0.95）
|
||
|
||
### 关卡配置
|
||
|
||
```javascript
|
||
const LEVEL_CONFIGS = [
|
||
{ level: 1, bossName: '贪吃喵星人', targetLevel: 3, feedCount: 3, dropMin: 1, dropMax: 2 },
|
||
{ level: 2, bossName: '吃货柴犬', targetLevel: 4, feedCount: 4, dropMin: 1, dropMax: 3 },
|
||
{ level: 3, bossName: '美食家熊猫', targetLevel: 5, feedCount: 5, dropMin: 2, dropMax: 4 },
|
||
// 可继续添加更多关卡...
|
||
];
|
||
```
|
||
|
||
**参数说明**：
|
||
- `targetLevel`: Boss需要的水果等级（玩家需合成到此等级才能投喂）
|
||
- `feedCount`: 需要投喂的次数
|
||
- `dropMin/dropMax`: 掉落水果的等级范围
|
||
|
||
**难度调整**：
|
||
- 想降低难度：减小 `targetLevel` 和 `feedCount`
|
||
- 想提高难度：增大 `targetLevel` 和 `feedCount`
|
||
|
||
### 失败判定
|
||
|
||
```javascript
|
||
checkFailCondition(dt) {
|
||
const warningY = 150; // 警戒线Y坐标（越小越难）
|
||
// 超过3秒则失败
|
||
if (this.gameState.failTimer >= 3000) {
|
||
this.handleGameOver();
|
||
}
|
||
}
|
||
```
|
||
|
||
**调优建议**：
|
||
- 想降低难度：增大 `warningY`（如 200）或增加超时时间（如 5000）
|
||
- 想提高难度：减小 `warningY`（如 100）或减少超时时间（如 2000）
|
||
|
||
---
|
||
|
||
## 📱 微信小游戏上架
|
||
|
||
### 步骤 1：开通流量主（可选，用于广告变现）
|
||
|
||
1. 登录 [微信公众平台](https://mp.weixin.qq.com/)
|
||
2. 进入小程序后台 → 推广 → 流量主
|
||
3. 满足条件（累计独立访客 ≥ 1000）后申请开通
|
||
4. 创建广告位，获取广告位ID
|
||
|
||
### 步骤 2：配置广告位ID
|
||
|
||
修改 `app.js` 中的广告位ID：
|
||
|
||
```javascript
|
||
// 激励视频广告（复活用）
|
||
this.rewardedVideoAd = wx.createRewardedVideoAd({
|
||
adUnitId: '你的激励视频广告位ID' // 替换这里
|
||
});
|
||
|
||
// 插屏广告
|
||
this.interstitialAd = wx.createInterstitialAd({
|
||
adUnitId: '你的插屏广告位ID' // 替换这里
|
||
});
|
||
```
|
||
|
||
### 步骤 3：上传代码
|
||
|
||
1. 在微信开发者工具中点击 **"上传"**
|
||
2. 填写版本号和备注
|
||
3. 等待上传完成
|
||
|
||
### 步骤 4：提交审核
|
||
|
||
1. 登录微信公众平台
|
||
2. 进入小程序后台 → 版本管理
|
||
3. 找到刚上传的版本，点击 **"提交审核"**
|
||
4. 填写审核信息（游戏分类、服务类目等）
|
||
5. 等待审核通过（通常1-3个工作日）
|
||
|
||
### 步骤 5：发布上线
|
||
|
||
审核通过后，在后台点击 **"发布"** 即可上线。
|
||
|
||
---
|
||
|
||
## 🐛 常见问题排查
|
||
|
||
### Q1: 水果不掉下来？
|
||
|
||
**检查清单**：
|
||
- [ ] Canvas 上下文是否正确初始化（`wx.createCanvasContext`）
|
||
- [ ] `onTouchStart` 事件是否绑定到 canvas
|
||
- [ ] `updateFruits` 函数是否在每帧调用
|
||
|
||
### Q2: 合成判定不触发？
|
||
|
||
**检查清单**：
|
||
- [ ] `checkMerges()` 是否在每帧调用
|
||
- [ ] 距离判断阈值是否合理（当前为 `radius1 + radius2 - 5`）
|
||
- [ ] 水果的 `level` 属性是否正确设置
|
||
|
||
### Q3: 音频不播放？
|
||
|
||
**可能原因**：
|
||
- 音频文件不存在于 `audio/` 目录
|
||
- 文件路径错误（注意大小写）
|
||
- 微信开发者工具中禁用了音频（检查设置）
|
||
- 真机上需要用户交互后才能播放音频（这是微信的限制）
|
||
|
||
**解决方法**：
|
||
- 确认音频文件存在且格式正确（MP3）
|
||
- 检查 `AudioManager.js` 中的路径映射
|
||
- 在真机上测试（模拟器音频支持有限）
|
||
|
||
### Q4: 广告不显示？
|
||
|
||
**可能原因**：
|
||
- 未开通流量主
|
||
- 广告位ID错误或未配置
|
||
- 使用的是模拟器而非真机（部分广告类型不支持模拟器）
|
||
- 广告加载失败（网络问题或广告库存不足）
|
||
|
||
**解决方法**：
|
||
- 确认已开通流量主并配置正确的广告位ID
|
||
- 在真机上测试
|
||
- 查看控制台是否有广告加载失败的错误信息
|
||
|
||
### Q5: 存档不生效？
|
||
|
||
**检查清单**：
|
||
- [ ] `app.saveGameData()` 是否在适当时机调用
|
||
- [ ] `wx.setStorageSync` 是否执行成功
|
||
- [ ] 重新进入时是否调用 `app.loadGameData()`
|
||
|
||
---
|
||
|
||
## 📊 性能优化建议
|
||
|
||
### 1. 限制同屏水果数量
|
||
|
||
```javascript
|
||
// 在 dropFruit 前检查
|
||
if (this.gameState.fruits.length >= 50) {
|
||
wx.showToast({ title: '水果太多了', icon: 'none' });
|
||
return;
|
||
}
|
||
```
|
||
|
||
### 2. 对象池优化（高级）
|
||
|
||
对于频繁创建/销毁的水果，可以使用对象池复用节点，减少GC压力。
|
||
|
||
### 3. 降低渲染频率
|
||
|
||
如果不需要60fps，可以降低渲染频率：
|
||
|
||
```javascript
|
||
startGameLoop() {
|
||
const loop = () => {
|
||
if (!this.data.isPaused) {
|
||
this.update();
|
||
this.render();
|
||
}
|
||
|
||
// 降低到30fps
|
||
setTimeout(() => requestAnimationFrame(loop), 33);
|
||
};
|
||
|
||
loop();
|
||
}
|
||
```
|
||
|
||
### 4. 使用 Canvas 离屏渲染
|
||
|
||
对于复杂的特效，可以先渲染到离屏Canvas，再绘制到主Canvas。
|
||
|
||
---
|
||
|
||
## 📞 技术支持
|
||
|
||
### 官方文档
|
||
- [微信小程序开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
|
||
- [Canvas API 参考](https://developers.weixin.qq.com/miniprogram/dev/api/canvas/wx.createCanvasContext.html)
|
||
- [音频API参考](https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.createInnerAudioContext.html)
|
||
|
||
### 社区支持
|
||
- [微信开放社区](https://developers.weixin.qq.com/community/)
|
||
- [QoderWork 论坛](https://forum.qoder.com/)
|
||
|
||
---
|
||
|
||
## 🎉 下一步行动
|
||
|
||
1. **立即测试**：按照"快速开始"导入项目并运行
|
||
2. **替换美术资源**：准备9个水果精灵图和Boss图片
|
||
3. **配置音频**：生成或下载音频文件放入 `audio/` 目录
|
||
4. **真机测试**：扫码在手机上体验
|
||
5. **配置广告**（可选）：开通流量主并配置广告位ID
|
||
6. **提交审核**：上传代码并提交微信审核
|
||
|
||
**祝你上架顺利！🚀**
|
||
|
||
---
|
||
|
||
**项目版本**：v1.0
|
||
**最后更新**：2026-08-14
|
||
**适用平台**：微信小程序
|
||
**许可证**：MIT
|