374 lines
11 KiB
Markdown
374 lines
11 KiB
Markdown
# 报恩榴莲 - 微信小程序原生版本
|
||
|
||
> 🎮 一款纯原生实现的三三合成休闲小游戏，无需游戏引擎，直接在微信开发者工具中运行
|
||
|
||
## ✨ 项目特点
|
||
|
||
- ✅ **零依赖** - 不需要 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
|