Files
heros/assets/script/game/wx_clound_client_api/WxCloudApi.ts
2025-08-19 22:30:59 +08:00

882 lines
27 KiB
TypeScript
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.

// 云函数返回类型定义
export type CloudReturnType<T = any> = {
code: number, // 200成功其他都是失败
msg?: string, // 消息信息
data?: T, // 返回数据
timestamp?: number, // 时间戳
version?: string, // 数据版本
execution_time?: number // 执行时间(ms)
}
// 用户信息类型
export type UserInfo = {
user_id: string,
openid: string,
regist_time: number,
init_time?: number,
data_version?: string,
last_save_time?: number
}
// 完整用户数据类型
export type UserGameData = UserInfo & {
data: GameData,
fight_heros: FightHeros,
heros: Heros,
items: Items,
tals: Tals,
equips: Equips
}
// 基础游戏数据类型
export type GameData = {
score: number,
mission: number,
gold: number,
diamond: number,
meat: number,
exp: number,
}
// 出战英雄类型
export type FightHeros = {
[position: number]: number // 位置 -> 英雄ID
}
// 英雄数据类型
export type HeroData = {
uuid: number,
lv: number,
exp?: number,
star?: number,
power?: number
}
export type Heros = {
[heroId: number]: HeroData
}
// 库存类型
export type Items = {
[itemId: number]: number
}
export type Tals = {
[talId: number]: number
}
export type Equips = {
[equipId: number]: number
}
// 版本兼容性检查结果
export type VersionCompatibility = {
compatible: boolean,
needsUpgrade: boolean,
message: string
}
// 库存类型枚举
export type InventoryType = 'items' | 'tals' | 'equips'
export class WxCloudApi{
/**
* @en init the cloud
* @zh 初始化云客户端(只调用一次即可)
* @param {string} env 云环境名称
*/
public static init(env:string){
wx?.cloud.init({
env: env
});
}
// ==================== 认证相关接口 ====================
/**
* @en Login to the cloud
* @zh 用户登录,获取完整的用户和游戏数据
* @return Promise<CloudCallFunctionResult<CloudReturnType<UserGameData>>>
*/
public static async login(): Promise<CloudCallFunctionResult<CloudReturnType<UserGameData>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "login"
}
});
}
/**
* @en Get user basic info
* @zh 获取用户基本信息(不包含游戏数据)
* @return Promise<CloudCallFunctionResult<CloudReturnType<UserInfo>>>
*/
public static async getUserInfo(): Promise<CloudCallFunctionResult<CloudReturnType<UserInfo>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "user_info"
}
});
}
/**
* @en Check data version compatibility
* @zh 检查数据版本兼容性
* @return Promise<CloudCallFunctionResult<CloudReturnType<{user_version: string, current_version: string, compatibility: VersionCompatibility}>>>
*/
public static async checkVersion(): Promise<CloudCallFunctionResult<CloudReturnType<{
user_version: string,
current_version: string,
compatibility: VersionCompatibility,
init_time: number,
regist_time: number,
last_save_time: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "version"
}
});
}
/**
* @en Force upgrade user data
* @zh 强制升级用户数据结构
* @return Promise<CloudCallFunctionResult<CloudReturnType<{old_version: string, new_version: string, upgrade_time: number} & UserGameData>>>
*/
public static async upgradeUserData(): Promise<CloudCallFunctionResult<CloudReturnType<{
old_version: string,
new_version: string,
upgrade_time: number
} & UserGameData>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "upgrade"
}
});
}
// ==================== 基础游戏数据接口 ====================
/**
* @en Get game data
* @zh 获取基础游戏数据(金币、钻石、经验等)
* @return Promise<CloudCallFunctionResult<CloudReturnType<GameData>>>
*/
public static async getGameData(): Promise<CloudCallFunctionResult<CloudReturnType<GameData>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "data_get"
}
});
}
/**
* @en Update game data
* @zh 批量更新基础游戏数据
* @param data 要更新的数据
* @param merge 是否合并更新默认true
* @return Promise<CloudCallFunctionResult<CloudReturnType<GameData>>>
*/
public static async updateGameData(data: Partial<GameData>, merge: boolean = true): Promise<CloudCallFunctionResult<CloudReturnType<GameData>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "data_update",
data: data,
merge: merge
}
});
}
/**
* @en Add to game data field
* @zh 增加指定字段的数值
* @param field 字段名
* @param amount 增加的数量
* @return Promise<CloudCallFunctionResult<CloudReturnType<{field: string, old_value: number, new_value: number, change: number}>>>
*/
public static async addGameDataField(field:string, amount: number): Promise<CloudCallFunctionResult<CloudReturnType<{
field: string,
old_value: number,
new_value: number,
change: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "data_add",
field: field,
amount: amount
}
});
}
/**
* @en Spend game data field
* @zh 消耗指定字段的数值(会检查是否足够)
* @param field 字段名
* @param amount 消耗的数量
* @return Promise<CloudCallFunctionResult<CloudReturnType<{field: string, old_value: number, new_value: number, change: number}>>>
*/
public static async spendGameDataField(field:string, amount: number): Promise<CloudCallFunctionResult<CloudReturnType<{
field: string,
old_value: number,
new_value: number,
change: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "data_spend",
field: field,
amount: amount
}
});
}
/**
* @en Set game data field
* @zh 直接设置某个字段的值
* @param field 字段名
* @param value 新的值
* @return Promise<CloudCallFunctionResult<CloudReturnType<{field: string, old_value: any, new_value: any}>>>
*/
public static async setGameDataField(field: keyof GameData, value: any): Promise<CloudCallFunctionResult<CloudReturnType<{
field: string,
old_value: any,
new_value: any
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "data_set",
field: field,
value: value
}
});
}
/**
* @en Reset game data
* @zh 重置基础游戏数据为默认值
* @return Promise<CloudCallFunctionResult<CloudReturnType<GameData>>>
*/
public static async resetGameData(): Promise<CloudCallFunctionResult<CloudReturnType<GameData>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "data_reset"
}
});
}
// 便捷方法:金币操作
/**
* @en Add gold
* @zh 增加金币
* @param amount 金币数量
*/
public static async addGold(amount: number) {
return await this.addGameDataField('gold', amount);
}
/**
* @en Spend gold
* @zh 消耗金币
* @param amount 金币数量
*/
public static async spendGold(amount: number) {
return await this.spendGameDataField('gold', amount);
}
// 便捷方法:钻石操作
/**
* @en Add diamond
* @zh 增加钻石
* @param amount 钻石数量
*/
public static async addDiamond(amount: number) {
return await this.addGameDataField('diamond', amount);
}
/**
* @en Spend diamond
* @zh 消耗钻石
* @param amount 钻石数量
*/
public static async spendDiamond(amount: number) {
return await this.spendGameDataField('diamond', amount);
}
// ==================== 出战英雄接口 ====================
/**
* @en Get fight heros
* @zh 获取出战英雄配置
* @return Promise<CloudCallFunctionResult<CloudReturnType<FightHeros>>>
*/
public static async getFightHeros(): Promise<CloudCallFunctionResult<CloudReturnType<FightHeros>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "fight_heros_get"
}
});
}
/**
* @en Set fight hero
* @zh 设置指定位置的出战英雄
* @param position 出战位置 (0-4)
* @param heroId 英雄ID0表示移除
* @return Promise<CloudCallFunctionResult<CloudReturnType<{position: number, old_hero_id: number, new_hero_id: number}>>>
*/
public static async setFightHero(position: number, heroId: number): Promise<CloudCallFunctionResult<CloudReturnType<{
position: number,
old_hero_id: number,
new_hero_id: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "fight_hero_set",
position: position,
hero_id: heroId
}
});
}
/**
* @en Update fight heros
* @zh 批量更新出战英雄配置
* @param fightHeros 出战英雄配置对象
* @return Promise<CloudCallFunctionResult<CloudReturnType<FightHeros>>>
*/
public static async updateFightHeros(fightHeros: Partial<FightHeros>): Promise<CloudCallFunctionResult<CloudReturnType<FightHeros>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "fight_heros_update",
fight_heros: fightHeros
}
});
}
/**
* @en Get active fight heros
* @zh 获取当前出战的英雄列表(不包含空位)
* @return Promise<CloudCallFunctionResult<CloudReturnType<{active_heros: Array<{position: number, hero_id: number, hero_data: HeroData}>, total_count: number}>>>
*/
public static async getActiveFightHeros(): Promise<CloudCallFunctionResult<CloudReturnType<{
active_heros: Array<{
position: number,
hero_id: number,
hero_data: HeroData
}>,
total_count: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "fight_heros_active"
}
});
}
/**
* @en Swap fight heros
* @zh 交换两个出战位置的英雄
* @param position1 位置1 (0-4)
* @param position2 位置2 (0-4)
* @return Promise<CloudCallFunctionResult<CloudReturnType<{position1: number, position2: number, hero1_moved_to: number, hero2_moved_to: number}>>>
*/
public static async swapFightHeros(position1: number, position2: number): Promise<CloudCallFunctionResult<CloudReturnType<{
position1: number,
position2: number,
hero1_moved_to: number,
hero2_moved_to: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "fight_heros_swap",
position1: position1,
position2: position2
}
});
}
/**
* @en Reset fight heros
* @zh 重置出战英雄配置为默认值
* @return Promise<CloudCallFunctionResult<CloudReturnType<FightHeros>>>
*/
public static async resetFightHeros(): Promise<CloudCallFunctionResult<CloudReturnType<FightHeros>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "fight_heros_reset"
}
});
}
// ==================== 英雄管理接口 ====================
/**
* @en Get all heros
* @zh 获取用户拥有的所有英雄数据
* @return Promise<CloudCallFunctionResult<CloudReturnType<Heros>>>
*/
public static async getHeros(): Promise<CloudCallFunctionResult<CloudReturnType<Heros>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "heros_get"
}
});
}
/**
* @en Get single hero
* @zh 获取指定英雄的详细数据
* @param heroId 英雄ID
* @return Promise<CloudCallFunctionResult<CloudReturnType<HeroData>>>
*/
public static async getHero(heroId: number): Promise<CloudCallFunctionResult<CloudReturnType<HeroData>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "hero_get",
hero_id: heroId
}
});
}
/**
* @en Add new hero
* @zh 添加新英雄到用户库存
* @param heroId 英雄ID
* @param heroData 英雄数据(可选)
* @return Promise<CloudCallFunctionResult<CloudReturnType<HeroData>>>
*/
public static async addHero(heroId: number, heroData?: Partial<HeroData>): Promise<CloudCallFunctionResult<CloudReturnType<HeroData>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "hero_add",
hero_id: heroId,
hero_data: heroData
}
});
}
/**
* @en Update hero
* @zh 批量更新英雄的多个属性
* @param heroId 英雄ID
* @param updateData 要更新的属性
* @return Promise<CloudCallFunctionResult<CloudReturnType<{old_data: HeroData, new_data: HeroData}>>>
*/
public static async updateHero(heroId: number, updateData: Partial<HeroData>): Promise<CloudCallFunctionResult<CloudReturnType<{
old_data: HeroData,
new_data: HeroData
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "hero_update",
hero_id: heroId,
update_data: updateData
}
});
}
/**
* @en Set hero property
* @zh 设置英雄的单个属性值
* @param heroId 英雄ID
* @param property 属性名
* @param value 属性值
* @return Promise<CloudCallFunctionResult<CloudReturnType<{hero_id: number, property: string, old_value: any, new_value: any}>>>
*/
public static async setHeroProperty(heroId: number, property: keyof HeroData, value: any): Promise<CloudCallFunctionResult<CloudReturnType<{
hero_id: number,
property: string,
old_value: any,
new_value: any
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "hero_property_set",
hero_id: heroId,
property: property,
value: value
}
});
}
/**
* @en Level up hero
* @zh 英雄升级指定级数
* @param heroId 英雄ID
* @param levels 升级级数默认1级
* @return Promise<CloudCallFunctionResult<CloudReturnType<{hero_id: number, property: string, old_value: number, new_value: number}>>>
*/
public static async levelUpHero(heroId: number, exp:number,gold:number,levels: number = 1): Promise<CloudCallFunctionResult<CloudReturnType<{
hero_id: number,
property: string,
old_value: number,
new_value: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "hero_levelup",
hero_id: heroId,
exp: exp,
gold:gold,
levels: levels
}
});
}
/**
* @en Delete hero
* @zh 删除指定英雄(会检查是否在出战阵容中)
* @param heroId 英雄ID
* @return Promise<CloudCallFunctionResult<CloudReturnType<HeroData>>>
*/
public static async deleteHero(heroId: number): Promise<CloudCallFunctionResult<CloudReturnType<HeroData>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "hero_delete",
hero_id: heroId
}
});
}
/**
* @en Get owned hero IDs
* @zh 获取用户拥有的所有英雄ID
* @return Promise<CloudCallFunctionResult<CloudReturnType<{hero_ids: number[], total_count: number}>>>
*/
public static async getOwnedHeroIds(): Promise<CloudCallFunctionResult<CloudReturnType<{
hero_ids: number[],
total_count: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "heros_owned"
}
});
}
// ==================== 兼容旧接口 ====================
/**
* @en Save game data to the cloud (Legacy)
* @zh 把客户端数据写入云,此为全覆盖写入,请自行管理完整数据(兼容旧接口)
* @param gameData 游戏数据
* @return Promise<CloudCallFunctionResult<CloudReturnType<{results: any[]}>>>
*/
public static async save(gameData: any): Promise<CloudCallFunctionResult<CloudReturnType<{
results: any[]
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: 'save',
data: gameData
}
});
}
// ==================== 库存管理接口 (items, tals, equips) ====================
/**
* @en Get inventory
* @zh 获取指定类型的所有库存数据
* @param type 库存类型 ('items', 'tals', 'equips')
* @return Promise<CloudCallFunctionResult<CloudReturnType<Items | Tals | Equips>>>
*/
public static async getInventory(type: InventoryType): Promise<CloudCallFunctionResult<CloudReturnType<Items | Tals | Equips>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "inventory_get",
type: type
}
});
}
/**
* @en Get inventory item
* @zh 获取指定物品的数量
* @param type 库存类型
* @param itemId 物品ID
* @return Promise<CloudCallFunctionResult<CloudReturnType<{item_id: number, count: number}>>>
*/
public static async getInventoryItem(type: InventoryType, itemId: number): Promise<CloudCallFunctionResult<CloudReturnType<{
item_id: number,
count: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "inventory_item_get",
type: type,
item_id: itemId
}
});
}
/**
* @en Add inventory item
* @zh 增加指定物品的数量
* @param type 库存类型
* @param itemId 物品ID
* @param count 添加数量
* @return Promise<CloudCallFunctionResult<CloudReturnType<{item_id: number, old_count: number, new_count: number, added: number}>>>
*/
public static async addInventoryItem(type: InventoryType, itemId: number, count: number): Promise<CloudCallFunctionResult<CloudReturnType<{
item_id: number,
old_count: number,
new_count: number,
added: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "inventory_item_add",
type: type,
item_id: itemId,
count: count
}
});
}
/**
* @en Consume inventory item
* @zh 消耗指定数量的物品(会检查是否足够)
* @param type 库存类型
* @param itemId 物品ID
* @param count 消耗数量
* @return Promise<CloudCallFunctionResult<CloudReturnType<{item_id: number, old_count: number, new_count: number, added: number}>>>
*/
public static async consumeInventoryItem(type: InventoryType, itemId: number, count: number): Promise<CloudCallFunctionResult<CloudReturnType<{
item_id: number,
old_count: number,
new_count: number,
added: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "inventory_item_consume",
type: type,
item_id: itemId,
count: count
}
});
}
/**
* @en Set inventory item
* @zh 直接设置物品的数量
* @param type 库存类型
* @param itemId 物品ID
* @param count 新的数量
* @return Promise<CloudCallFunctionResult<CloudReturnType<{item_id: number, old_count: number, new_count: number}>>>
*/
public static async setInventoryItem(type: InventoryType, itemId: number, count: number): Promise<CloudCallFunctionResult<CloudReturnType<{
item_id: number,
old_count: number,
new_count: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "inventory_item_set",
type: type,
item_id: itemId,
count: count
}
});
}
/**
* @en Update inventory
* @zh 批量更新多个物品的数量
* @param type 库存类型
* @param data 更新数据对象
* @param merge 是否合并更新默认true
* @return Promise<CloudCallFunctionResult<CloudReturnType<Items | Tals | Equips>>>
*/
public static async updateInventory(type: InventoryType, data: Partial<Items | Tals | Equips>, merge: boolean = true): Promise<CloudCallFunctionResult<CloudReturnType<Items | Tals | Equips>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "inventory_update",
type: type,
data: data,
merge: merge
}
});
}
/**
* @en Reset inventory
* @zh 重置指定类型的库存为默认值
* @param type 库存类型
* @return Promise<CloudCallFunctionResult<CloudReturnType<Items | Tals | Equips>>>
*/
public static async resetInventory(type: InventoryType): Promise<CloudCallFunctionResult<CloudReturnType<Items | Tals | Equips>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "inventory_reset",
type: type
}
});
}
/**
* @en Get owned items
* @zh 获取数量大于0的物品列表
* @param type 库存类型
* @return Promise<CloudCallFunctionResult<CloudReturnType<{owned_items: Array<{item_id: number, count: number}>, total_types: number}>>>
*/
public static async getOwnedItems(type: InventoryType): Promise<CloudCallFunctionResult<CloudReturnType<{
owned_items: Array<{
item_id: number,
count: number
}>,
total_types: number
}>>> {
return await wx?.cloud.callFunction({
name: 'cocos_cloud',
data: {
cmd: "inventory_owned",
type: type
}
});
}
// ==================== 便捷方法:道具操作 ====================
/**
* @en Get items
* @zh 获取所有道具数据
*/
public static async getItems() {
return await this.getInventory('items');
}
/**
* @en Add item
* @zh 添加道具
* @param itemId 道具ID
* @param count 数量
*/
public static async addItem(itemId: number, count: number) {
return await this.addInventoryItem('items', itemId, count);
}
/**
* @en Consume item
* @zh 消耗道具
* @param itemId 道具ID
* @param count 数量
*/
public static async consumeItem(itemId: number, count: number) {
return await this.consumeInventoryItem('items', itemId, count);
}
// ==================== 便捷方法:天赋操作 ====================
/**
* @en Get talents
* @zh 获取所有天赋数据
*/
public static async getTalents() {
return await this.getInventory('tals');
}
/**
* @en Add talent
* @zh 添加天赋点
* @param talId 天赋ID
* @param count 数量
*/
public static async addTalent(talId: number, count: number) {
return await this.addInventoryItem('tals', talId, count);
}
/**
* @en Consume talent
* @zh 消耗天赋点
* @param talId 天赋ID
* @param count 数量
*/
public static async consumeTalent(talId: number, count: number) {
return await this.consumeInventoryItem('tals', talId, count);
}
// ==================== 便捷方法:装备操作 ====================
/**
* @en Get equipments
* @zh 获取所有装备数据
*/
public static async getEquipments() {
return await this.getInventory('equips');
}
/**
* @en Add equipment
* @zh 添加装备
* @param equipId 装备ID
* @param count 数量
*/
public static async addEquipment(equipId: number, count: number) {
return await this.addInventoryItem('equips', equipId, count);
}
/**
* @en Consume equipment
* @zh 消耗装备
* @param equipId 装备ID
* @param count 数量
*/
public static async consumeEquipment(equipId: number, count: number) {
return await this.consumeInventoryItem('equips', equipId, count);
}
// ==================== 其他便捷方法 ====================
/**
* @en Load game data (Legacy compatible)
* @zh 加载游戏数据(兼容旧接口)
*/
public static async load() {
return await this.login();
}
/**
* @en Get all game data at once
* @zh 一次性获取所有游戏数据
* @return Promise<CloudCallFunctionResult<CloudReturnType<UserGameData>>>
*/
public static async getAllGameData(): Promise<CloudCallFunctionResult<CloudReturnType<UserGameData>>> {
return await this.login();
}
}