pan/heros
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dbe2da292707d59be0c587fd9fc8ae40c117d4cf
heros/build-templates/wechatgame/cloud_functions/cocos_cloud/API.md
panfudan dbe2da2927 奖励结算++
2025-08-20 09:59:01 +08:00

14 KiB
Raw Blame History

游戏云函数 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接口文档

🚀 通用调用格式

wx.cloud.callFunction({
  name: 'cocos_cloud',
  data: {
    cmd: '命令名',
    // 其他参数...
  }
}).then(res => {
  console.log('调用结果:', res.result);
}).catch(err => {
  console.error('调用失败:', err);
});

📊 通用响应格式

{
  code: 200,                    // 状态码 (200=成功, 负数=错误)
  msg: "Success",              // 响应消息
  data: { /* 返回数据 */ },     // 具体数据
  timestamp: 1234567890,       // 时间戳
  version: "1.0.0",           // 数据版本
  execution_time: 50          // 执行时间(ms)
}

🔐 认证相关接口

1. 用户登录

获取用户完整信息和游戏数据。

// 请求
{ 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. 获取用户信息

获取用户基本信息（不包含游戏数据）。

// 请求
{ 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. 检查版本信息

检查用户数据版本兼容性。

// 请求
{ 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. 强制升级数据

手动触发用户数据结构升级。

// 请求
{ cmd: 'upgrade' }

// 响应
{
  code: 200,
  data: {
    old_version: "1.0.0",
    new_version: "1.1.0",
    upgrade_time: 1234567890,
    // ... 升级后的完整数据
  }
}

🎮 基础游戏数据接口

1. 获取游戏数据

获取用户的基础游戏数据（金币、钻石、经验等）。

// 请求
{ cmd: 'data_get' }

// 响应
{
  code: 200,
  data: {
    score: 0,
    mission: 1,
    gold: 100,
    diamond: 100,
    meat: 0,
    exp: 0,
    // ... 更多字段
  }
}

2. 更新游戏数据

批量更新基础游戏数据。

// 请求
{
  cmd: 'data_update',
  data: {
    gold: 1000,
    diamond: 200,
    exp: 500
  },
  merge: true  // 可选，默认true（合并更新）
}

// 响应
{
  code: 200,
  data: {
    // 更新后的完整数据
  }
}

3. 增加指定字段

增加某个字段的数值。

// 请求
{
  cmd: 'data_add',
  field: 'gold',
  amount: 100
}

// 响应
{
  code: 200,
  data: {
    field: 'gold',
    old_value: 1000,
    new_value: 1100,
    change: 100
  }
}

4. 消耗指定字段

消耗某个字段的数值（会检查是否足够）。

// 请求
{
  cmd: 'data_spend',
  field: 'gold',
  amount: 50
}

// 响应
{
  code: 200,
  data: {
    field: 'gold',
    old_value: 1100,
    new_value: 1050,
    change: -50
  }
}

5. 设置指定字段

直接设置某个字段的值。

// 请求
{
  cmd: 'data_set',
  field: 'mission',
  value: 5
}

// 响应
{
  code: 200,
  data: {
    field: 'mission',
    old_value: 1,
    new_value: 5
  }
}

6. 重置游戏数据

重置基础游戏数据为默认值。

// 请求
{ cmd: 'data_reset' }

// 响应
{
  code: 200,
  data: {
    // 重置后的默认数据
  }
}

⚔️ 出战英雄接口

1. 获取出战英雄配置

获取当前的出战英雄配置。

// 请求
{ 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. 设置单个出战英雄

设置指定位置的出战英雄。

// 请求
{
  cmd: 'fight_hero_set',
  position: 2,
  hero_id: 5007
}

// 响应
{
  code: 200,
  data: {
    position: 2,
    old_hero_id: 0,
    new_hero_id: 5007
  }
}

3. 批量更新出战英雄

批量更新多个位置的出战英雄。

// 请求
{
  cmd: 'fight_heros_update',
  fight_heros: {
    0: 5001,
    1: 5005,
    2: 5007
  }
}

// 响应
{
  code: 200,
  data: {
    // 更新后的完整出战配置
  }
}

4. 获取激活的出战英雄

获取当前出战的英雄列表（不包含空位）。

// 请求
{ 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. 交换出战英雄位置

交换两个位置的英雄。

// 请求
{
  cmd: 'fight_heros_swap',
  position1: 0,
  position2: 2
}

// 响应
{
  code: 200,
  data: {
    position1: 0,
    position2: 2,
    hero1_moved_to: 5007,
    hero2_moved_to: 5001
  }
}

6. 重置出战英雄

重置出战英雄配置为默认值。

// 请求
{ cmd: 'fight_heros_reset' }

// 响应
{
  code: 200,
  data: {
    // 重置后的默认配置
  }
}

🦸 英雄管理接口

1. 获取所有英雄

获取用户拥有的所有英雄数据。

// 请求
{ 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. 获取单个英雄

获取指定英雄的详细数据。

// 请求
{
  cmd: 'hero_get',
  hero_id: 5001
}

// 响应
{
  code: 200,
  data: {
    uuid: 5001,
    lv: 10,
    exp: 500,
    star: 2,
    power: 150
  }
}

3. 添加新英雄

添加新英雄到用户库存。

// 请求
{
  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. 更新英雄属性

批量更新英雄的多个属性。

// 请求
{
  cmd: 'hero_update',
  hero_id: 5001,
  update_data: {
    lv: 15,
    exp: 800,
    star: 3
  }
}

// 响应
{
  code: 200,
  data: {
    old_data: { /* 更新前的数据 */ },
    new_data: { /* 更新后的数据 */ }
  }
}

5. 设置英雄单个属性

设置英雄的单个属性值。

// 请求
{
  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. 英雄升级

英雄升级指定级数。

// 请求
{
  cmd: 'hero_levelup',
  hero_id: 5001,
  levels: 3  // 可选，默认1级
}

// 响应
{
  code: 200,
  data: {
    hero_id: 5001,
    property: 'lv',
    old_value: 20,
    new_value: 23
  }
}

7. 删除英雄

删除指定英雄（会检查是否在出战阵容中）。

// 请求
{
  cmd: 'hero_delete',
  hero_id: 5008
}

// 响应
{
  code: 200,
  data: {
    // 被删除的英雄数据
  }
}

8. 获取拥有的英雄ID列表

获取用户拥有的所有英雄ID。

// 请求
{ cmd: 'heros_owned' }

// 响应
{
  code: 200,
  data: {
    hero_ids: [5001, 5005, 5007],
    total_count: 3
  }
}

🎒 库存管理接口

库存管理接口支持三种类型的数据：

  • items: 道具
  • tals: 天赋
  • equips: 装备

1. 获取库存数据

获取指定类型的所有库存数据。

// 请求
{
  cmd: 'inventory_get',
  type: 'items'  // 'items', 'tals', 'equips'
}

// 响应
{
  code: 200,
  data: {
    1001: 5,   // 道具1001: 5个
    1002: 3,   // 道具1002: 3个
    1003: 0,   // 道具1003: 0个
    // ...
  }
}

2. 获取单个物品

获取指定物品的数量。

// 请求
{
  cmd: 'inventory_item_get',
  type: 'items',
  item_id: 1001
}

// 响应
{
  code: 200,
  data: {
    item_id: 1001,
    count: 5
  }
}

3. 添加物品

增加指定物品的数量。

// 请求
{
  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. 消耗物品

消耗指定数量的物品（会检查是否足够）。

// 请求
{
  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. 设置物品数量

直接设置物品的数量。

// 请求
{
  cmd: 'inventory_item_set',
  type: 'items',
  item_id: 1001,
  count: 20
}

// 响应
{
  code: 200,
  data: {
    item_id: 1001,
    old_count: 12,
    new_count: 20
  }
}

6. 批量更新库存

批量更新多个物品的数量。

// 请求
{
  cmd: 'inventory_update',
  type: 'items',
  data: {
    1001: 25,
    1002: 10,
    1003: 5
  },
  merge: true  // 可选，默认true（合并更新）
}

// 响应
{
  code: 200,
  data: {
    // 更新后的完整库存数据
  }
}

7. 重置库存

重置指定类型的库存为默认值。

// 请求
{
  cmd: 'inventory_reset',
  type: 'items'
}

// 响应
{
  code: 200,
  data: {
    // 重置后的默认库存数据
  }
}

8. 获取拥有的物品

获取数量大于0的物品列表。

// 请求
{
  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 命令。

// 请求
{ cmd: 'load' }

// 响应：与login相同

2. 保存数据 (兼容)

批量保存多种类型的数据。

// 请求
{
  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 操作被拒绝 英雄正在出战中无法删除等

📝 使用示例

完整的游戏流程示例

// 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. 启用调试日志

在开发环境中，云函数会输出详细的调试日志：

// 请求日志
[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年
维护者: 游戏开发团队