pan/heros
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f5a13de4b5e9dd13a0665647a27d3940da1d6689
heros/build-templates/wechatgame/cloud_functions/cocos_cloud/API.md
panfudan 3884b35829 dd
2025-08-18 17:47:06 +08:00

916 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 游戏云函数 API 文档
## 📋 概述
本文档详细说明了游戏云函数的所有可用接口，包括认证、数据管理、英雄系统、库存管理等功能。
## 🏗️ 项目结构
```
cocos_cloud/
├── index.js # 路由入口文件
├── user_init_data.js # 用户初始化数据配置
├── modules/ # 功能模块目录
│ ├── auth.js # 认证模块
│ ├── gameData.js # 基础游戏数据模块
│ ├── fightHeros.js # 出战英雄模块
│ ├── heros.js # 英雄管理模块
│ ├── inventory.js # 库存管理模块
│ └── response.js # 响应处理模块
├── README.md # 项目说明文档
└── API.md # API接口文档
```
## 🚀 通用调用格式
```javascript
wx.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: '命令名',
// 其他参数...
}
}).then(res => {
console.log('调用结果:', res.result);
}).catch(err => {
console.error('调用失败:', err);
});
```
## 📊 通用响应格式
```javascript
{
code: 200, // 状态码 (200=成功, 负数=错误)
msg: "Success", // 响应消息
data: { /* 返回数据 */ }, // 具体数据
timestamp: 1234567890, // 时间戳
version: "1.0.0", // 数据版本
execution_time: 50 // 执行时间(ms)
}
```
## 🔐 认证相关接口
### 1. 用户登录
获取用户完整信息和游戏数据。
```javascript
// 请求
{ cmd: 'login' }
// 响应
{
code: 200,
data: {
user_id: "用户ID",
openid: "微信OpenID",
regist_time: 1234567890,
data: { /* 基础游戏数据 */ },
fight_heros: { /* 出战英雄配置 */ },
heros: { /* 英雄属性数据 */ },
items: { /* 道具数据 */ },
tals: { /* 天赋数据 */ },
equips: { /* 装备数据 */ },
data_version: "1.0.0",
last_save_time: 1234567890
}
}
```
### 2. 获取用户信息
获取用户基本信息（不包含游戏数据）。
```javascript
// 请求
{ cmd: 'user_info' }
// 响应
{
code: 200,
data: {
user_id: "用户ID",
openid: "微信OpenID",
regist_time: 1234567890,
init_time: 1234567890,
data_version: "1.0.0",
last_save_time: 1234567890
}
}
```
### 3. 检查版本信息
检查用户数据版本兼容性。
```javascript
// 请求
{ cmd: 'version' }
// 响应
{
code: 200,
data: {
user_version: "1.0.0",
current_version: "1.1.0",
compatibility: {
compatible: true,
needsUpgrade: true,
message: "Minor version update available"
},
init_time: 1234567890,
regist_time: 1234567890,
last_save_time: 1234567890
}
}
```
### 4. 强制升级数据
手动触发用户数据结构升级。
```javascript
// 请求
{ cmd: 'upgrade' }
// 响应
{
code: 200,
data: {
old_version: "1.0.0",
new_version: "1.1.0",
upgrade_time: 1234567890,
// ... 升级后的完整数据
}
}
```
## 🎮 基础游戏数据接口
### 1. 获取游戏数据
获取用户的基础游戏数据（金币、钻石、经验等）。
```javascript
// 请求
{ cmd: 'data_get' }
// 响应
{
code: 200,
data: {
score: 0,
mission: 1,
gold: 100,
diamond: 100,
meat: 0,
exp: 0,
// ... 更多字段
}
}
```
### 2. 更新游戏数据
批量更新基础游戏数据。
```javascript
// 请求
{
cmd: 'data_update',
data: {
gold: 1000,
diamond: 200,
exp: 500
},
merge: true // 可选，默认true（合并更新）
}
// 响应
{
code: 200,
data: {
// 更新后的完整数据
}
}
```
### 3. 增加指定字段
增加某个字段的数值。
```javascript
// 请求
{
cmd: 'data_add',
field: 'gold',
amount: 100
}
// 响应
{
code: 200,
data: {
field: 'gold',
old_value: 1000,
new_value: 1100,
change: 100
}
}
```
### 4. 消耗指定字段
消耗某个字段的数值（会检查是否足够）。
```javascript
// 请求
{
cmd: 'data_spend',
field: 'gold',
amount: 50
}
// 响应
{
code: 200,
data: {
field: 'gold',
old_value: 1100,
new_value: 1050,
change: -50
}
}
```
### 5. 设置指定字段
直接设置某个字段的值。
```javascript
// 请求
{
cmd: 'data_set',
field: 'mission',
value: 5
}
// 响应
{
code: 200,
data: {
field: 'mission',
old_value: 1,
new_value: 5
}
}
```
### 6. 重置游戏数据
重置基础游戏数据为默认值。
```javascript
// 请求
{ cmd: 'data_reset' }
// 响应
{
code: 200,
data: {
// 重置后的默认数据
}
}
```
## ⚔️ 出战英雄接口
### 1. 获取出战英雄配置
获取当前的出战英雄配置。
```javascript
// 请求
{ cmd: 'fight_heros_get' }
// 响应
{
code: 200,
data: {
0: 5001, // 位置0: 英雄5001
1: 5005, // 位置1: 英雄5005
2: 0, // 位置2: 空
3: 0, // 位置3: 空
4: 0 // 位置4: 空
}
}
```
### 2. 设置单个出战英雄
设置指定位置的出战英雄。
```javascript
// 请求
{
cmd: 'fight_hero_set',
position: 2,
hero_id: 5007
}
// 响应
{
code: 200,
data: {
position: 2,
old_hero_id: 0,
new_hero_id: 5007
}
}
```
### 3. 批量更新出战英雄
批量更新多个位置的出战英雄。
```javascript
// 请求
{
cmd: 'fight_heros_update',
fight_heros: {
0: 5001,
1: 5005,
2: 5007
}
}
// 响应
{
code: 200,
data: {
// 更新后的完整出战配置
}
}
```
### 4. 获取激活的出战英雄
获取当前出战的英雄列表（不包含空位）。
```javascript
// 请求
{ cmd: 'fight_heros_active' }
// 响应
{
code: 200,
data: {
active_heros: [
{
position: 0,
hero_id: 5001,
hero_data: { /* 英雄详细数据 */ }
},
{
position: 1,
hero_id: 5005,
hero_data: { /* 英雄详细数据 */ }
}
],
total_count: 2
}
}
```
### 5. 交换出战英雄位置
交换两个位置的英雄。
```javascript
// 请求
{
cmd: 'fight_heros_swap',
position1: 0,
position2: 2
}
// 响应
{
code: 200,
data: {
position1: 0,
position2: 2,
hero1_moved_to: 5007,
hero2_moved_to: 5001
}
}
```
### 6. 重置出战英雄
重置出战英雄配置为默认值。
```javascript
// 请求
{ cmd: 'fight_heros_reset' }
// 响应
{
code: 200,
data: {
// 重置后的默认配置
}
}
```
## 🦸 英雄管理接口
### 1. 获取所有英雄
获取用户拥有的所有英雄数据。
```javascript
// 请求
{ cmd: 'heros_get' }
// 响应
{
code: 200,
data: {
5001: { uuid: 5001, lv: 10, exp: 500, star: 2, power: 150 },
5005: { uuid: 5005, lv: 8, exp: 300, star: 1, power: 120 },
5007: { uuid: 5007, lv: 1, exp: 0, star: 1, power: 90 }
}
}
```
### 2. 获取单个英雄
获取指定英雄的详细数据。
```javascript
// 请求
{
cmd: 'hero_get',
hero_id: 5001
}
// 响应
{
code: 200,
data: {
uuid: 5001,
lv: 10,
exp: 500,
star: 2,
power: 150
}
}
```
### 3. 添加新英雄
添加新英雄到用户库存。
```javascript
// 请求
{
cmd: 'hero_add',
hero_id: 5008,
hero_data: { // 可选，不提供则使用默认数据
lv: 1,
exp: 0,
star: 1,
power: 110
}
}
// 响应
{
code: 200,
data: {
uuid: 5008,
lv: 1,
exp: 0,
star: 1,
power: 110
}
}
```
### 4. 更新英雄属性
批量更新英雄的多个属性。
```javascript
// 请求
{
cmd: 'hero_update',
hero_id: 5001,
update_data: {
lv: 15,
exp: 800,
star: 3
}
}
// 响应
{
code: 200,
data: {
old_data: { /* 更新前的数据 */ },
new_data: { /* 更新后的数据 */ }
}
}
```
### 5. 设置英雄单个属性
设置英雄的单个属性值。
```javascript
// 请求
{
cmd: 'hero_property_set',
hero_id: 5001,
property: 'lv',
value: 20
}
// 响应
{
code: 200,
data: {
hero_id: 5001,
property: 'lv',
old_value: 15,
new_value: 20
}
}
```
### 6. 英雄升级
英雄升级指定级数。
```javascript
// 请求
{
cmd: 'hero_levelup',
hero_id: 5001,
levels: 3 // 可选，默认1级
}
// 响应
{
code: 200,
data: {
hero_id: 5001,
property: 'lv',
old_value: 20,
new_value: 23
}
}
```
### 7. 删除英雄
删除指定英雄（会检查是否在出战阵容中）。
```javascript
// 请求
{
cmd: 'hero_delete',
hero_id: 5008
}
// 响应
{
code: 200,
data: {
// 被删除的英雄数据
}
}
```
### 8. 获取拥有的英雄ID列表
获取用户拥有的所有英雄ID。
```javascript
// 请求
{ cmd: 'heros_owned' }
// 响应
{
code: 200,
data: {
hero_ids: [5001, 5005, 5007],
total_count: 3
}
}
```
## 🎒 库存管理接口
库存管理接口支持三种类型的数据：
- `items`: 道具
- `tals`: 天赋
- `equips`: 装备
### 1. 获取库存数据
获取指定类型的所有库存数据。
```javascript
// 请求
{
cmd: 'inventory_get',
type: 'items' // 'items', 'tals', 'equips'
}
// 响应
{
code: 200,
data: {
1001: 5, // 道具1001: 5个
1002: 3, // 道具1002: 3个
1003: 0, // 道具1003: 0个
// ...
}
}
```
### 2. 获取单个物品
获取指定物品的数量。
```javascript
// 请求
{
cmd: 'inventory_item_get',
type: 'items',
item_id: 1001
}
// 响应
{
code: 200,
data: {
item_id: 1001,
count: 5
}
}
```
### 3. 添加物品
增加指定物品的数量。
```javascript
// 请求
{
cmd: 'inventory_item_add',
type: 'items',
item_id: 1001,
count: 10
}
// 响应
{
code: 200,
data: {
item_id: 1001,
old_count: 5,
new_count: 15,
added: 10
}
}
```
### 4. 消耗物品
消耗指定数量的物品（会检查是否足够）。
```javascript
// 请求
{
cmd: 'inventory_item_consume',
type: 'items',
item_id: 1001,
count: 3
}
// 响应
{
code: 200,
data: {
item_id: 1001,
old_count: 15,
new_count: 12,
added: -3
}
}
```
### 5. 设置物品数量
直接设置物品的数量。
```javascript
// 请求
{
cmd: 'inventory_item_set',
type: 'items',
item_id: 1001,
count: 20
}
// 响应
{
code: 200,
data: {
item_id: 1001,
old_count: 12,
new_count: 20
}
}
```
### 6. 批量更新库存
批量更新多个物品的数量。
```javascript
// 请求
{
cmd: 'inventory_update',
type: 'items',
data: {
1001: 25,
1002: 10,
1003: 5
},
merge: true // 可选，默认true（合并更新）
}
// 响应
{
code: 200,
data: {
// 更新后的完整库存数据
}
}
```
### 7. 重置库存
重置指定类型的库存为默认值。
```javascript
// 请求
{
cmd: 'inventory_reset',
type: 'items'
}
// 响应
{
code: 200,
data: {
// 重置后的默认库存数据
}
}
```
### 8. 获取拥有的物品
获取数量大于0的物品列表。
```javascript
// 请求
{
cmd: 'inventory_owned',
type: 'items'
}
// 响应
{
code: 200,
data: {
owned_items: [
{ item_id: 1001, count: 25 },
{ item_id: 1002, count: 10 },
{ item_id: 1003, count: 5 }
],
total_types: 3
}
}
```
## 🔄 兼容旧接口
为了保持向后兼容，保留了一些旧接口：
### 1. 加载数据 (兼容)
等同于 `login` 命令。
```javascript
// 请求
{ cmd: 'load' }
// 响应：与login相同
```
### 2. 保存数据 (兼容)
批量保存多种类型的数据。
```javascript
// 请求
{
cmd: 'save',
data: {
data: { gold: 1000, diamond: 200 },
fight_heros: { 0: 5001, 1: 5005 },
heros: { 5001: { lv: 10, exp: 500 } },
items: { 1001: 10, 1002: 5 },
tals: { 1001: 1 },
equips: { 1001: 2 }
}
}
// 响应
{
code: 200,
data: {
results: [
// 各个模块的保存结果
]
},
msg: "All data saved successfully"
}
```
## ❌ 错误码说明
| 错误码 | 说明 | 示例 |
|-------|------|------|
| 200 | 成功 | 操作成功完成 |
| -1 | 操作失败 | 数据库更新失败 |
| -2 | 未知命令 | 命令不存在 |
| -3 | 参数错误 | 缺少必需参数或参数格式错误 |
| -4 | 用户未找到 | 用户不存在或创建失败 |
| -5 | 系统错误 | 服务器内部错误 |
| -6 | 资源不足 | 金币、道具等资源不够 |
| -7 | 资源已存在 | 英雄已存在等 |
| -8 | 操作被拒绝 | 英雄正在出战中无法删除等 |
## 📝 使用示例
### 完整的游戏流程示例
```javascript
// 1. 用户登录
wx.cloud.callFunction({
name: 'cocos_cloud',
data: { cmd: 'login' }
}).then(res => {
console.log('用户登录成功:', res.result.data);
// 2. 增加金币
return wx.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: 'data_add',
field: 'gold',
amount: 100
}
});
}).then(res => {
console.log('金币增加成功:', res.result.data);
// 3. 添加新英雄
return wx.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: 'hero_add',
hero_id: 5008
}
});
}).then(res => {
console.log('英雄添加成功:', res.result.data);
// 4. 设置出战英雄
return wx.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: 'fight_hero_set',
position: 2,
hero_id: 5008
}
});
}).then(res => {
console.log('出战英雄设置成功:', res.result.data);
}).catch(err => {
console.error('操作失败:', err);
});
```
## 🔧 开发调试
### 1. 启用调试日志
在开发环境中，云函数会输出详细的调试日志：
```javascript
// 请求日志
[data_add] Request from oxxx: { field: 'gold', amount: 100 }
// 响应日志
[data_add] Response (45ms): 200 gold updated successfully
```
### 2. 性能监控
每个响应都包含 `execution_time` 字段，显示接口执行时间。
### 3. 版本管理
使用 `version` 命令检查数据版本兼容性，确保客户端和服务端数据结构一致。
---
**版本**: 1.0.0
**更新时间**: 2024年
**维护者**: 游戏开发团队
Reference in New Issue View Git Blame Copy Permalink