星火 2.0 开发文档

主题

GameCore.UserCloudData ​

BatchTransactionBuilder 仅服务端 ​

命名空间 GameCore.UserCloudData

csharp
public sealed class BatchTransactionBuilder

批量用户事务构建器

方法 ​

ForUser 仅服务端 ​

csharp
public BatchTransactionBuilder ForUser(long userId, Action<TransactionBuilder> builderAction)

为指定用户添加操作

  • userId — 用户ID
  • builderAction — 构建器操作

返回： 当前批量构建器实例

ForAllUsers 仅服务端 ​

csharp
public BatchTransactionBuilder ForAllUsers(Action<TransactionBuilder> builderAction)

为所有用户执行相同的操作

  • builderAction — 构建器操作

返回： 当前批量构建器实例

ExecuteAllAsync 仅服务端 ​

csharp
public Task<Dictionary<long, UserCloudDataResult>> ExecuteAllAsync(string description = "Batch transaction")

执行所有用户的事务

  • description — 事务描述

返回： 每个用户的执行结果

ExecuteSingleCommitAsync 仅服务端 ​

csharp
public Task<UserCloudDataResult> ExecuteSingleCommitAsync(string description = "Batch transaction")

将所有用户已添加的操作合并为一次事务提交。

  • description — 事务描述

返回： 整体事务执行结果。任一操作失败时，后端会回滚整个提交。

备注

与 String) 不同，该方法只发送一次 commit，适用于需要跨用户原子性的场景。

CloudData 仅服务端 ​

命名空间 GameCore.UserCloudData

csharp
public static class CloudData

云数据API的简化别名，用于更简洁的调用

备注

该类提供了 CloudDataApi 的简化别名，用户可以选择使用 CloudData 而不是 CloudDataApi。

属性 ​

IsReady 仅服务端 ​

csharp
public static bool IsReady { get; }

方法 ​

WaitUntilReadyAsync 仅服务端 ​

csharp
public static Task WaitUntilReadyAsync()

QueryUserDataAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IUserDataBatchQueryResult>>> QueryUserDataAsync(long[] userIds, IEnumerable<VarChar180> keys)

QueryPlayersDataAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IUserDataBatchQueryResult>>> QueryPlayersDataAsync(Player[] players, IEnumerable<VarChar180> keys)

QueryCurrencyAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserData<IUserCurrencyRecord>>> QueryCurrencyAsync(long[] userIds, IEnumerable<VarChar180> keys)

QueryPlayersCurrencyAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserData<IUserCurrencyRecord>>> QueryPlayersCurrencyAsync(Player[] players, IEnumerable<VarChar180> keys)

QueryCappedDataAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserData<IUserCappedDataRecord>>> QueryCappedDataAsync(long[] userIds, IEnumerable<VarChar180> keys)

QueryPlayersCappedDataAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserData<IUserCappedDataRecord>>> QueryPlayersCappedDataAsync(Player[] players, IEnumerable<VarChar180> keys)

QueryUserNameBatchAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserNames>> QueryUserNameBatchAsync(long[] userIds)

QueryPlayersUserNameBatchAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserNames>> QueryPlayersUserNameBatchAsync(Player[] players)

QueryUserListItemsAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IListItemRecord>>> QueryUserListItemsAsync(long userId, VarChar180 key, int? maxCount = null)

QueryPlayerListItemsAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IListItemRecord>>> QueryPlayerListItemsAsync(Player player, VarChar180 key, int? maxCount = null)

ScanUserListItemsAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<ListItemScanBatch>> ScanUserListItemsAsync(long userId, VarChar180 key, int batchSize, long? beforeItemUuid = null)

ScanPlayerListItemsAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<ListItemScanBatch>> ScanPlayerListItemsAsync(Player player, VarChar180 key, int batchSize, long? beforeItemUuid = null)

FindListItemByIdAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<RecordFoundStatus<IListItemRecord>>> FindListItemByIdAsync(long listItemUuid)

CheckNameClaimedStatusAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<NameClaimStatus>> CheckNameClaimedStatusAsync(VarChar180 key, VarChar180 name)

SearchClaimedNamesAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<INameRecord>>> SearchClaimedNamesAsync(VarChar180 key, VarChar180 partialName)

ForUser 仅服务端 ​

csharp
public static TransactionBuilder ForUser(long userId)

ForPlayer 仅服务端 ​

csharp
public static TransactionBuilder ForPlayer(Player player)

ForUser 仅服务端 ​

csharp
public static TransactionBuilder ForUser(User user)

ForUsers 仅服务端 ​

csharp
public static BatchTransactionBuilder ForUsers(params long[] userIds)

ForPlayers 仅服务端 ​

csharp
public static BatchTransactionBuilder ForPlayers(params Player[] players)

ExecuteTransactionAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult> ExecuteTransactionAsync(IEnumerable<TransactionOperation> operations, VarChar255 description)

CloudDataApi 仅服务端 ​

命名空间 GameCore.UserCloudData

csharp
public static class CloudDataApi

云数据统一访问入口，提供查询和事务操作的一致API

备注

该类作为云数据系统的主要入口点，解决了查询和修改操作分离的不一致问题。 所有云数据操作都可以从此类开始，提供统一的用户体验。 底层委托给 CloudDataOperations 和 TransactionBuilder 实现。 Key 命名约定：云数据 key 会按调用方传入的大小写原样传递给底层服务，但 ScoreArchive 表结构未强制二进制排序规则，实际落库比较可能随 MySQL collation 变成大小写不敏感。不要依赖大小写区分不同 key，建议统一使用小写 ASCII、下划线分隔的 key。 查询结果中的 key 会保留数据库返回的原始大小写；UserData1` 等本地辅助方法和批量查询返回字典使用大小写不敏感比较，便于兼容数据库侧的 key 命中语义。 重要概念区分： Player.Id: 当局游戏的槽位编号(0,1,2...)，仅在当前游戏会话有意义 User.UserId: 平台用户的全局唯一标识，云数据应使用此ID确保持久性

属性 ​

IsReady 仅服务端 ​

csharp
public static bool IsReady { get; }

获取云数据服务是否已经初始化完成。

备注

在该值为 false 时调用查询或事务接口会返回 ServiceNotInitialized。 游戏逻辑可以在启动阶段先检查此属性，或使用 WaitUntilReadyAsync 等待服务可用。

方法 ​

WaitUntilReadyAsync 仅服务端 ​

csharp
public static Task WaitUntilReadyAsync()

等待云数据服务初始化完成。

返回： 服务已经初始化时立即完成；否则在云数据服务被标记为初始化完成后完成。

备注

该方法只表示服务入口可用，不代表玩家 UserId 已经可用。 需要读写玩家云数据时，仍应确保目标玩家已经连入并拥有有效的 UserId。

QueryUserDataAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IUserDataBatchQueryResult>>> QueryUserDataAsync(long[] userIds, IEnumerable<VarChar180> keys)

异步批量查询指定用户的通用数据

  • userIds — 要查询的用户ID数组，不能为null或空
  • keys — 要检索的数据键集合，每个键不超过180个UTF-8字符，不能为null或空

返回： 包含查询结果的任务。成功时返回 IUserDataBatchQueryResult 集合， 失败时返回相应的错误代码。

备注

委托给 VarChar180}) 实现。

QueryPlayersDataAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IUserDataBatchQueryResult>>> QueryPlayersDataAsync(Player[] players, IEnumerable<VarChar180> keys)

异步批量查询指定玩家的通用数据（便利方法）

  • players — 要查询的玩家数组，自动提取UserId进行查询
  • keys — 要检索的数据键集合，每个键不超过180个UTF-8字符，不能为null或空

返回： 包含查询结果的任务。成功时返回 IUserDataBatchQueryResult 集合， 失败时返回相应的错误代码。

备注

这是便利方法，会自动从Player对象提取对应的UserId进行查询。 只有连接的真人玩家会被包含在查询中，AI玩家会被过滤掉。

QueryCurrencyAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserData<IUserCurrencyRecord>>> QueryCurrencyAsync(long[] userIds, IEnumerable<VarChar180> keys)

异步批量查询指定用户的货币数据

  • userIds — 要查询的用户ID数组，不能为null或空
  • keys — 要检索的货币键集合，每个键不超过180个UTF-8字符，不能为null或空

返回： 包含查询结果的任务。成功时返回 UserData1`， 失败时返回相应的错误代码。

备注

委托给 VarChar180}) 实现。

QueryPlayersCurrencyAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserData<IUserCurrencyRecord>>> QueryPlayersCurrencyAsync(Player[] players, IEnumerable<VarChar180> keys)

异步批量查询指定玩家的货币数据（便利方法）

  • players — 要查询的玩家数组，自动提取UserId进行查询
  • keys — 要检索的货币键集合，每个键不超过180个UTF-8字符，不能为null或空

返回： 包含查询结果的任务。成功时返回 UserData1`， 失败时返回相应的错误代码。

QueryCappedDataAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserData<IUserCappedDataRecord>>> QueryCappedDataAsync(long[] userIds, IEnumerable<VarChar180> keys)

异步批量查询指定用户的有上限数据

  • userIds — 要查询的用户ID数组，不能为null或空
  • keys — 要检索的数据键集合，每个键不超过180个UTF-8字符，不能为null或空

返回： 包含查询结果的任务。成功时返回 UserData1`， 失败时返回相应的错误代码。

备注

委托给 VarChar180}) 实现。

QueryUserNameBatchAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserNames>> QueryUserNameBatchAsync(long[] userIds)

异步批量查询指定用户的平台用户名数据

  • userIds — 要查询的用户ID数组，不能为null或空

返回： 包含用户名称查询结果的任务。成功时返回 UserNames 对象， 失败时返回相应的错误代码。结果可能为空但不会为null。

备注

委托给 Int64[]) 实现。 该方法支持批量查询多个用户的平台用户名信息。

QueryPlayersUserNameBatchAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserNames>> QueryPlayersUserNameBatchAsync(Player[] players)

异步批量查询指定玩家的平台用户名数据（便利方法）

  • players — 要查询的玩家数组，自动提取UserId进行查询

返回： 包含用户名称查询结果的任务。成功时返回 UserNames 对象， 失败时返回相应的错误代码。

备注

这是便利方法，会自动从Player对象提取对应的UserId进行查询。 只有连接的真人玩家会被包含在查询中，AI玩家会被过滤掉。

QueryPlayersCappedDataAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserData<IUserCappedDataRecord>>> QueryPlayersCappedDataAsync(Player[] players, IEnumerable<VarChar180> keys)

异步批量查询指定玩家的有上限数据（便利方法）

  • players — 要查询的玩家数组，自动提取UserId进行查询
  • keys — 要检索的数据键集合，每个键不超过180个UTF-8字符，不能为null或空

返回： 包含查询结果的任务。成功时返回 UserData1`， 失败时返回相应的错误代码。

QueryUserListItemsAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IListItemRecord>>> QueryUserListItemsAsync(long userId, VarChar180 key, int? maxCount = null)

异步查询指定用户的列表项数据

  • userId — 用户ID，必须大于0
  • key — 列表键，不超过180个UTF-8字符，不能为空
  • maxCount — 最大返回数量，如果指定则返回最新的指定数量的项目，null表示返回所有项目

返回： 包含列表项记录的任务。成功时返回 IListItemRecord 集合， 失败时返回相应的错误代码。

备注

委托给 Int32}) 实现。

QueryPlayerListItemsAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IListItemRecord>>> QueryPlayerListItemsAsync(Player player, VarChar180 key, int? maxCount = null)

异步查询指定玩家的列表项数据（便利方法）

  • player — 玩家对象，自动提取UserId进行查询
  • key — 列表键，不超过180个UTF-8字符，不能为空
  • maxCount — 最大返回数量，如果指定则返回最新的指定数量的项目，null表示返回所有项目

返回： 包含列表项记录的任务。成功时返回 IListItemRecord 集合， 失败时返回相应的错误代码。

ScanUserListItemsAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<ListItemScanBatch>> ScanUserListItemsAsync(long userId, VarChar180 key, int batchSize, long? beforeItemUuid = null)

按稳定游标分批扫描指定用户的列表项数据。

  • userId — 用户 ID，必须大于 0。
  • key — 列表键，不超过 180 个 UTF-8 字符，不能为空。
  • batchSize — 本批最多返回的列表项数量，必须大于 0。
  • beforeItemUuid — 上一批结果的 NextBeforeItemUuid；传 null 表示从最新列表项开始。

返回： 包含扫描批次的任务。成功时返回 ListItemScanBatch，失败时返回相应的错误代码。

备注

该方法适合需要把一个较大的 ListItem 列表分多次读完的场景。每批结果按 ItemUUID 倒序返回；当 HasMore 为 true 时，将 NextBeforeItemUuid 传给下一次调用即可继续。 与 Int32}) 只取最新若干条不同，扫描游标按列表项 ID 向更旧记录推进，正常情况下不会重复返回已经扫描过的列表项。该方法不是强一致数据库快照；扫描过程中新增的列表项 通常会留到下一轮完整扫描，删除或移动列表项会影响后续批次。

ScanPlayerListItemsAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<ListItemScanBatch>> ScanPlayerListItemsAsync(Player player, VarChar180 key, int batchSize, long? beforeItemUuid = null)

按稳定游标分批扫描指定玩家的列表项数据。

  • player — 玩家对象，会自动提取真人玩家的 UserId。
  • key — 列表键，不超过 180 个 UTF-8 字符，不能为空。
  • batchSize — 本批最多返回的列表项数量，必须大于 0。
  • beforeItemUuid — 上一批结果的 NextBeforeItemUuid；传 null 表示从最新列表项开始。

返回： 包含扫描批次的任务。成功时返回 ListItemScanBatch，失败时返回相应的错误代码。

备注

这是 Int64}) 的玩家便利方法。

FindListItemByIdAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<RecordFoundStatus<IListItemRecord>>> FindListItemByIdAsync(long listItemUuid)

异步通过全局唯一ID查找列表项

  • listItemUuid — 列表项的全局唯一标识符

返回： 包含查找结果的任务。成功时返回 RecordFoundStatus1`， 指示是否找到项目以及项目数据，失败时返回相应的错误代码。

备注

委托给 Int64) 实现。

CheckNameClaimedStatusAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<NameClaimStatus>> CheckNameClaimedStatusAsync(VarChar180 key, VarChar180 name)

异步检查指定名称在给定命名空间中是否已被占用

  • key — 命名空间键，不超过180个UTF-8字符，不能为空
  • name — 要检查的名称，不超过180个UTF-8字符，不能为空

返回： 包含名称占用状态的任务。成功时返回 NameClaimStatus， 失败时返回相应的错误代码。

备注

委托给 VarChar180) 实现。

SearchClaimedNamesAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<INameRecord>>> SearchClaimedNamesAsync(VarChar180 key, VarChar180 partialName)

异步搜索包含指定部分名称的已占用名称

  • key — 命名空间键，不超过180个UTF-8字符，不能为空
  • partialName — 要搜索的部分名称，支持模糊匹配，不能为空

返回： 包含匹配名称记录的任务。成功时返回 INameRecord 集合， 失败时返回相应的错误代码。最多返回15个结果。

备注

委托给 VarChar180) 实现。

ForUser 仅服务端 ​

csharp
public static TransactionBuilder ForUser(long userId)

为指定用户创建事务构建器

  • userId — 用户ID，必须大于0

返回： 事务构建器实例

备注

委托给 Int64) 实现。

ForPlayer 仅服务端 ​

csharp
public static TransactionBuilder ForPlayer(Player player)

为指定玩家创建事务构建器（便利方法）

  • player — 玩家对象，自动提取UserId创建事务

返回： 事务构建器实例

备注

这是便利方法，会自动从Player对象提取对应的UserId创建事务构建器。 确保传入的是连接的真人玩家，AI玩家不支持云数据操作。

ForUser 仅服务端 ​

csharp
public static TransactionBuilder ForUser(User user)

为指定用户创建事务构建器（便利方法）

  • user — 用户对象，自动提取UserId创建事务

返回： 事务构建器实例

备注

这是便利方法，会自动从User对象提取UserId创建事务构建器。 委托给 Int64) 实现。

ForUsers 仅服务端 ​

csharp
public static BatchTransactionBuilder ForUsers(params long[] userIds)

创建批量用户事务构建器

  • userIds — 用户ID数组

返回： 批量事务构建器

备注

委托给 Int64[]) 实现。

ForPlayers 仅服务端 ​

csharp
public static BatchTransactionBuilder ForPlayers(params Player[] players)

创建批量玩家事务构建器（便利方法）

  • players — 玩家数组，自动提取UserId创建批量事务

返回： 批量事务构建器

备注

这是便利方法，会自动从Player对象数组提取对应的UserId创建批量事务构建器。 只有连接的真人玩家会被包含，AI玩家会被过滤掉。

ExecuteTransactionAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult> ExecuteTransactionAsync(IEnumerable<TransactionOperation> operations, VarChar255 description)

直接执行事务操作（便捷方法）

  • operations — 事务操作集合
  • description — 事务描述

返回： 事务执行结果

备注

委托给 VarChar255) 实现。 适用于已经构建好操作列表的场景。

CloudDataOperations 仅服务端 ​

命名空间 GameCore.UserCloudData

csharp
public static class CloudDataOperations

云数据操作实现类，提供所有云数据操作的具体实现

备注

该类是云数据系统的中间层，负责:

  • 实现所有云数据查询和事务操作
  • 提供参数验证和错误处理
  • 管理请求ID生成和异步等待
  • 封装底层Provider调用

方法 ​

QueryUserDataBatchAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IUserDataBatchQueryResult>>> QueryUserDataBatchAsync(long[] userIds, IEnumerable<VarChar180> keys)

异步批量查询指定用户的通用数据

  • userIds — 要查询的用户ID数组，不能为null或空
  • keys — 要检索的数据键集合，每个键不超过180个UTF-8字符，不能为null或空

返回： 包含查询结果的任务。成功时返回 IUserDataBatchQueryResult 集合， 失败时返回相应的错误代码。结果可能为空但不会为null。

备注

该方法支持批量查询多个用户的多个数据键，适用于需要同时获取大量用户数据的场景。 查询结果按用户分组，每个用户的数据包含BigInt、VarChar和Blob三种类型。

QueryUserNameBatchAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<UserNames>> QueryUserNameBatchAsync(long[] userIds)

异步批量查询指定用户的平台用户名数据

  • userIds — 要查询的用户ID数组，不能为null或空

返回： 包含用户平台用户名查询结果的任务。成功时返回 UserNames 对象， 失败时返回相应的错误代码。结果可能为空但不会为null。

备注

该方法支持批量查询多个用户的名称信息，适用于需要同时获取大量用户名称的场景。 查询结果包含用户ID和对应的名称，如果某个用户没有设置名称，则返回空字符串。 可以通过返回的 UserNames 对象的 Int64) 方法获取特定用户的名称。

QueryCurrencyBatchAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IUserCurrencyRecord>>> QueryCurrencyBatchAsync(long[] userIds, IEnumerable<VarChar180> keys)

异步批量查询指定用户的货币数据

  • userIds — 要查询的用户ID数组，不能为null或空
  • keys — 要检索的货币键集合，每个键不超过180个UTF-8字符，不能为null或空

返回： 包含查询结果的任务。成功时返回 IUserCurrencyRecord 集合， 失败时返回相应的错误代码。

备注

货币数据具有特殊的原子性保证，支持AddCurrency和CostCurrency等事务操作。 货币值不能为负数，CostCurrency操作会验证余额充足性。

QueryCappedDataBatchAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IUserCappedDataRecord>>> QueryCappedDataBatchAsync(long[] userIds, IEnumerable<VarChar180> keys)

异步批量查询指定用户的有上限数据

  • userIds — 要查询的用户ID数组，不能为null或空
  • keys — 要检索的数据键集合，每个键不超过180个UTF-8字符，不能为null或空

返回： 包含查询结果的任务。成功时返回 IUserCappedDataRecord 集合， 失败时返回相应的错误代码。

备注

有上限数据支持动态调整上限值，常用于体力、经验等有最大值限制的数值。 可以通过 UserDataResetOption) 操作修改数值和上限。

CheckNameClaimedStatusAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<NameClaimStatus>> CheckNameClaimedStatusAsync(VarChar180 key, VarChar180 name)

异步检查指定名称在给定命名空间中是否已被占用

  • key — 命名空间键，不超过180个UTF-8字符，不能为空
  • name — 要检查的名称，不超过180个UTF-8字符，不能为空

返回： 包含名称占用状态的任务。成功时返回 NameClaimStatus， 失败时返回相应的错误代码。

备注

名称系统提供全局唯一性保证，常用于玩家昵称、公会名称等需要唯一标识的场景。 名称一旦被占用，可以通过 DeleteName 操作进行删除，或通过新的 ClaimNewName 操作占用其他名称。

SearchClaimedNamesAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<INameRecord>>> SearchClaimedNamesAsync(VarChar180 key, VarChar180 partialName)

异步搜索包含指定部分名称的已占用名称

  • key — 命名空间键，不超过180个UTF-8字符，不能为空
  • partialName — 要搜索的部分名称，支持模糊匹配，不能为空

返回： 包含匹配名称记录的任务。成功时返回 INameRecord 集合， 失败时返回相应的错误代码。最多返回15个结果。

备注

该方法执行大小写不敏感的部分匹配搜索，适用于名称联想和重复检查。 为了防止性能问题，单次搜索最多返回15个匹配结果。

QueryUserListItemsAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<IEnumerable<IListItemRecord>>> QueryUserListItemsAsync(long userId, VarChar180 key, int? maxCount = null)

异步查询指定用户的列表项数据

  • userId — 用户ID，必须大于0
  • key — 列表键，不超过180个UTF-8字符，不能为空
  • maxCount — 最大返回数量，如果指定则返回最新的指定数量的项目，null表示返回所有项目

返回： 包含列表项记录的任务。成功时返回 IListItemRecord 集合， 失败时返回相应的错误代码。

备注

列表项按时间倒序排列，最新添加的项目排在前面。 如果指定了maxCount，将返回最新的指定数量的项目。 列表项支持添加、修改和删除操作，可以存储任意二进制数据。

ScanUserListItemsAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<ListItemScanBatch>> ScanUserListItemsAsync(long userId, VarChar180 key, int batchSize, long? beforeItemUuid = null)

按稳定游标分批扫描指定用户的列表项数据。

  • userId — 用户 ID，必须大于 0。
  • key — 列表键，不超过 180 个 UTF-8 字符，不能为空。
  • batchSize — 本批最多返回的列表项数量，必须大于 0。
  • beforeItemUuid — 上一批结果的 NextBeforeItemUuid；传 null 表示从最新列表项开始。

返回： 包含扫描批次的任务。成功时返回 ListItemScanBatch，失败时返回相应的错误代码。

备注

每批结果按 ItemUUID 倒序返回。调用方应在 HasMore 为 true 时继续传入 NextBeforeItemUuid，直到该值为 null。 该扫描不是强一致快照；扫描过程中新增的列表项通常会留到下一轮完整扫描，删除或移动列表项会影响后续批次。

FindListItemByIdAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult<RecordFoundStatus<IListItemRecord>>> FindListItemByIdAsync(long listItemUuid)

异步通过全局唯一ID查找列表项

  • listItemUuid — 列表项的全局唯一标识符

返回： 包含查找结果的任务。成功时返回 RecordFoundStatus1`， 指示是否找到项目以及项目数据，失败时返回相应的错误代码。

备注

该方法通过全局唯一ID进行精确查找，不需要指定用户ID或列表键。 返回的 RecordFoundStatus1` 提供类型安全的空值检查。

ExecuteTransactionAsync 仅服务端 ​

csharp
public static Task<UserCloudDataResult> ExecuteTransactionAsync(IEnumerable<TransactionOperation> operations, VarChar255 description)

异步执行云数据事务，如果任何操作失败，整个事务将被回滚

  • operations — 要执行的事务操作集合，不能为null或空
  • description — 事务描述，将存储到数据库中用于审计，不超过255个UTF-8字符

返回： 包含事务执行结果的任务。成功时返回 Success， 失败时返回相应的错误代码。

备注

事务提供ACID特性保证，所有操作要么全部成功，要么全部失败。 支持的操作类型包括：数据设置/删除、货币加减、列表项管理、名称占用等。 事务描述将记录在审计日志中，建议提供有意义的描述信息。

CloudDataType 仅服务端 ​

命名空间 GameCore.UserCloudData

csharp
public enum CloudDataType

云数据类型枚举

枚举值 ​

  • BigInt
  • VarChar
  • Blob
  • Utf8Blob — UTF-8 字符串(以 blob 存储, tag=Utf8)。删除时与 Blob 等价。
  • Double — 双精度浮点(以 8 字节 IEEE754 存入 blob, tag=Double)。删除时与 Blob 等价。

ListItemReferenceTransactionOperationExtensions 仅服务端 ​

命名空间 GameCore.UserCloudData

csharp
public static class ListItemReferenceTransactionOperationExtensions

Extension methods for converting prepared list item references into transaction operations.

方法 ​

ToListItemAddOperation 仅服务端 ​

csharp
public static TransactionOperation ToListItemAddOperation(this ListItemReference listItemReference)

Converts a prepared list item reference into an AddListItem transaction operation.

  • listItemReference — The prepared list item reference.

返回： The transaction operation that adds the referenced list item.

ListItemScanBatch 仅服务端 ​

命名空间 GameCore.UserCloudData

csharp
public sealed class ListItemScanBatch

ListItem 分批扫描的一批结果。

备注

将成功结果中的 NextBeforeItemUuid 传给下一次扫描调用，可以继续读取更旧的列表项。 扫描按 ItemUUID 倒序推进，适合把同一个用户、同一个 key 下的大量 ListItem 分多次读完。它不是数据库快照：扫描过程中新增的列表项通常会留到下一轮完整扫描；删除或移动 列表项会影响之后批次还能读到的内容。

构造函数 ​

ListItemScanBatch 仅服务端 ​

csharp
public ListItemScanBatch(IReadOnlyList<IListItemRecord> items, bool hasMore, long? nextBeforeItemUuid)

属性 ​

Items 仅服务端 ​

csharp
public IReadOnlyList<IListItemRecord> Items { get; }

本批返回的列表项，按 ItemUUID 倒序排列。

HasMore 仅服务端 ​

csharp
public bool HasMore { get; }

是否还有更旧的列表项可以继续扫描。

NextBeforeItemUuid 仅服务端 ​

csharp
public long? NextBeforeItemUuid { get; }

下一次扫描要传入的排他游标；为 null 时表示已经读到当前列表末尾。

TransactionBuilder 仅服务端 ​

命名空间 GameCore.UserCloudData

csharp
public sealed class TransactionBuilder

云数据事务构建器，提供流式API来构建和执行事务操作

备注

该构建器简化了事务的创建过程，提供类型安全和链式调用支持。 支持自动优化、操作验证和错误预检等高级功能。

属性 ​

OperationCount 仅服务端 ​

csharp
public int OperationCount { get; }

获取操作数量

HasOperations 仅服务端 ​

csharp
public bool HasOperations { get; }

检查是否有操作

方法 ​

ForUser 仅服务端 ​

csharp
public static TransactionBuilder ForUser(long userId)

为指定用户创建事务构建器

  • userId — 用户ID，必须大于0

返回： 事务构建器实例

ForUsers 仅服务端 ​

csharp
public static BatchTransactionBuilder ForUsers(params long[] userIds)

创建批量用户事务构建器

  • userIds — 用户ID数组

返回： 批量事务构建器

SetData 仅服务端 ​

csharp
public TransactionBuilder SetData(string key, long value)

设置整数数据

  • key — 数据键，不超过180个UTF-8字符
  • value — 整数值

返回： 当前构建器实例，支持链式调用

SetData 仅服务端 ​

csharp
public TransactionBuilder SetData(string key, string value)

设置字符串数据

  • key — 数据键，不超过180个UTF-8字符
  • value — 字符串值，不超过255个UTF-8字符

返回： 当前构建器实例，支持链式调用

SetData 仅服务端 ​

csharp
public TransactionBuilder SetData(string key, byte[] data)

设置二进制数据

  • key — 数据键，不超过180个UTF-8字符
  • data — 二进制数据

返回： 当前构建器实例，支持链式调用

SetUtf8Blob 仅服务端 ​

csharp
public TransactionBuilder SetUtf8Blob(string key, string value)

设置 UTF-8 字符串数据（以 blob 形式存储，不受 String) 的 255 字符限制；后台可编辑）

  • key — 数据键，不超过180个UTF-8字符
  • value — UTF-8 字符串值

返回： 当前构建器实例，支持链式调用

SetDoubleBlob 仅服务端 ​

csharp
public TransactionBuilder SetDoubleBlob(string key, double value)

设置双精度浮点数据（以 8 字节 IEEE754 存入 blob；后台可编辑）。用于存储小数云变量。

  • key — 数据键，不超过180个UTF-8字符
  • value — 双精度浮点值

返回： 当前构建器实例，支持链式调用

AddToData 仅服务端 ​

csharp
public TransactionBuilder AddToData(string key, long delta)

增加整数数据

  • key — 数据键
  • delta — 增加的数值

返回： 当前构建器实例，支持链式调用

DeleteData 仅服务端 ​

csharp
public TransactionBuilder DeleteData(string key, CloudDataType dataType = CloudDataType.BigInt)

删除数据

  • key — 要删除的数据键
  • dataType — 数据类型

返回： 当前构建器实例，支持链式调用

AddCurrency 仅服务端 ​

csharp
public TransactionBuilder AddCurrency(string currencyKey, long amount)

添加货币，可为负数，可以将货币扣到负数

  • currencyKey — 货币键
  • amount — 添加的金额，可为负数，可以将货币扣到负数

返回： 当前构建器实例，支持链式调用

CostCurrency 仅服务端 ​

csharp
public TransactionBuilder CostCurrency(string currencyKey, long amount)

消耗货币，若余额不足，则事务失败

  • currencyKey — 货币键
  • amount — 消耗的金额，必须大于0

返回： 当前构建器实例，支持链式调用

AddListItem 仅服务端 ​

csharp
public TransactionBuilder AddListItem(ListItemReference listItemReference)

添加列表项到事务中

  • listItemReference — 列表项引用，包含ID、列表键、用户ID和数据

返回： 当前构建器实例，支持链式调用

备注

该方法要求传入一个完整的 ListItemReference，通常通过 Byte[]) 方法获得。 这种设计确保了ID、列表键和数据的一致性，避免了参数传递错误。

PrepareListItem 仅服务端 ​

csharp
public ListItemReference PrepareListItem(string listKey, byte[] itemData)

准备列表项引用（自动生成全局唯一ID），但不添加到事务中

  • listKey — 列表键
  • itemData — 项目数据

返回： 列表项引用，包含自动生成的ID

备注

该方法会自动调用内部ID生成器生成全局唯一ID。 返回的引用对象包含生成的ID，需要通过 ListItemReference) 方法添加到事务中。 这种两阶段设计确保了ID的预先获取和类型安全的操作。

PrepareUtf8ListItem 仅服务端 ​

csharp
public ListItemReference PrepareUtf8ListItem(string listKey, string itemData)

准备 UTF-8 字符串列表项引用（自动生成全局唯一ID），但不添加到事务中

  • listKey — 列表键
  • itemData — UTF-8 字符串数据

返回： 列表项引用，包含自动生成的ID

PrepareDoubleListItem 仅服务端 ​

csharp
public ListItemReference PrepareDoubleListItem(string listKey, double itemData)

准备双精度浮点列表项引用（自动生成全局唯一ID），但不添加到事务中

  • listKey — 列表键
  • itemData — 双精度浮点数据

返回： 列表项引用，包含自动生成的ID

DeleteListItem 仅服务端 ​

csharp
public TransactionBuilder DeleteListItem(long itemId)

删除列表项（使用全局唯一ID）

  • itemId — 全局唯一的项目ID

返回： 当前构建器实例，支持链式调用

DeleteListItem 仅服务端 ​

csharp
public TransactionBuilder DeleteListItem(ListItemReference itemReference)

删除列表项（使用引用）

  • itemReference — 项目引用

返回： 当前构建器实例，支持链式调用

UpdateListItem 仅服务端 ​

csharp
public TransactionBuilder UpdateListItem(long itemId, byte[] newData)

更新列表项（使用全局唯一ID）

  • itemId — 全局唯一的项目ID
  • newData — 新的项目数据

返回： 当前构建器实例，支持链式调用

UpdateListItemUtf8 仅服务端 ​

csharp
public TransactionBuilder UpdateListItemUtf8(long itemId, string newData)

更新列表项为 UTF-8 字符串数据（使用全局唯一ID）

  • itemId — 全局唯一的项目ID
  • newData — 新的 UTF-8 字符串数据

返回： 当前构建器实例，支持链式调用

UpdateListItemDouble 仅服务端 ​

csharp
public TransactionBuilder UpdateListItemDouble(long itemId, double newData)

更新列表项为双精度浮点数据（使用全局唯一ID）

  • itemId — 全局唯一的项目ID
  • newData — 新的双精度浮点数据

返回： 当前构建器实例，支持链式调用

UpdateListItem 仅服务端 ​

csharp
public TransactionBuilder UpdateListItem(ListItemReference itemReference, byte[] newData)

更新列表项（使用引用）

  • itemReference — 项目引用
  • newData — 新的项目数据

返回： 当前构建器实例，支持链式调用

UpdateListItemUtf8 仅服务端 ​

csharp
public TransactionBuilder UpdateListItemUtf8(ListItemReference itemReference, string newData)

更新列表项为 UTF-8 字符串数据（使用引用）

  • itemReference — 项目引用
  • newData — 新的 UTF-8 字符串数据

返回： 当前构建器实例，支持链式调用

UpdateListItemDouble 仅服务端 ​

csharp
public TransactionBuilder UpdateListItemDouble(ListItemReference itemReference, double newData)

更新列表项为双精度浮点数据（使用引用）

  • itemReference — 项目引用
  • newData — 新的双精度浮点数据

返回： 当前构建器实例，支持链式调用

MoveListItem 仅服务端 ​

csharp
public TransactionBuilder MoveListItem(long itemId, string targetListKey)

移动列表项到另一个列表

  • itemId — 全局唯一的项目ID
  • targetListKey — 目标列表的键名

返回： 当前构建器实例，支持链式调用

MoveListItem 仅服务端 ​

csharp
public TransactionBuilder MoveListItem(ListItemReference itemReference, string targetListKey)

移动列表项到另一个列表（使用引用）

  • itemReference — 项目引用
  • targetListKey — 目标列表的键名

返回： 当前构建器实例，支持链式调用

AddListItems 仅服务端 ​

csharp
public TransactionBuilder AddListItems(ListItemReference[] listItemReferences)

批量添加列表项到事务中

  • listItemReferences — 列表项引用数组，每个引用包含完整的项目信息

返回： 当前构建器实例，支持链式调用

备注

该方法将多个列表项引用批量添加到事务中，适用于需要同时添加多个项目的场景。 所有引用通常通过 Byte[][]) 方法批量准备。

PrepareListItems 仅服务端 ​

csharp
public ListItemReference[] PrepareListItems(string listKey, params byte[][] itemsData)

批量准备列表项引用（仅生成ID，不添加到事务中）

  • listKey — 列表键
  • itemsData — 项目数据数组

返回： 列表项引用数组，包含所有生成的全局唯一ID

备注

该方法仅准备列表项引用，不会将它们添加到事务中。 需要调用 ListItemReference[]) 方法将引用添加到事务中。

PrepareUtf8ListItems 仅服务端 ​

csharp
public ListItemReference[] PrepareUtf8ListItems(string listKey, params string[] itemsData)

批量准备 UTF-8 字符串列表项引用（仅生成ID，不添加到事务中）

  • listKey — 列表键
  • itemsData — UTF-8 字符串数据数组

返回： 列表项引用数组，包含所有生成的全局唯一ID

PrepareDoubleListItems 仅服务端 ​

csharp
public ListItemReference[] PrepareDoubleListItems(string listKey, params double[] itemsData)

批量准备双精度浮点列表项引用（仅生成ID，不添加到事务中）

  • listKey — 列表键
  • itemsData — 双精度浮点数据数组

返回： 列表项引用数组，包含所有生成的全局唯一ID

DeleteListItems 仅服务端 ​

csharp
public TransactionBuilder DeleteListItems(params ListItemReference[] itemReferences)

批量删除列表项（使用引用）

  • itemReferences — 项目引用数组

返回： 当前构建器实例，支持链式调用

ModifyCappedData 仅服务端 ​

csharp
public TransactionBuilder ModifyCappedData(string key, long delta, long newCap, UserDataResetOption? resetOption = null)

修改有上限的数据，若修改后的值超过上限，则整个事务失败。 若从未设置过指定Key的数据，则设置上限为newCap，并设置当前值为delta。

  • key — 数据键，不超过180个UTF-8字符
  • delta — 变化量，可以为正数（增加）或负数（减少）
  • newCap — 新的上限值，必须大于等于0
  • resetOption — 重置选项，控制数据何时自动重置为0。可选值： Int32): 每N小时重置 Int32): 每N天重置 DayOfWeek): 每N周的指定星期重置 Int32): 每N月重置 Int32): 每N年重置 Never: 永不重置（默认）

返回： 当前构建器实例，支持链式调用

备注

此方法用于管理具有上限限制的数据，如体力、经验池等。 计算逻辑：新值 = 当前值 + delta，如果新值 > newCap，则事务失败。 重置选项可以实现定期重置功能，例如每日体力恢复、每周活跃度重置等。 如果数据不存在，则从0开始计算。

ResetCappedData 仅服务端 ​

csharp
public TransactionBuilder ResetCappedData(string key)

重置有上限数据，将当前值重置为0

  • key — 数据键名

返回： 当前构建器实例，支持链式调用

ClaimName 仅服务端 ​

csharp
public TransactionBuilder ClaimName(string nameKey, string name, string description = "")

占用新名称

  • nameKey — 名称空间键
  • name — 要占用的名称
  • description — 名称描述

返回： 当前构建器实例，支持链式调用

DeleteName 仅服务端 ​

csharp
public TransactionBuilder DeleteName(string nameKey, string name)

删除已声明的名称

  • nameKey — 名称空间键
  • name — 要删除的名称

返回： 当前构建器实例，支持链式调用

WithDescription 仅服务端 ​

csharp
public TransactionBuilder WithDescription(string description)

设置事务描述 通常可以在云数据后台查看

  • description — 事务描述，用于审计日志

返回： 当前构建器实例，支持链式调用

WithOptimization 仅服务端 ​

csharp
public TransactionBuilder WithOptimization(bool enable = true)

启用或禁用事务优化

  • enable — 是否启用优化

返回： 当前构建器实例，支持链式调用

备注

优化包括：合并相同键的操作、去除冗余操作等

WithValidation 仅服务端 ​

csharp
public TransactionBuilder WithValidation(bool enable = true)

启用或禁用操作验证

  • enable — 是否启用验证

返回： 当前构建器实例，支持链式调用

Build 仅服务端 ​

csharp
public IEnumerable<TransactionOperation> Build()

构建事务操作列表

返回： 优化后的事务操作列表

ExecuteAsync 仅服务端 ​

csharp
public Task<UserCloudDataResult> ExecuteAsync()

执行事务

返回： 事务执行结果

UserData 双端 ​

命名空间 GameCore.UserCloudData

csharp
public class UserData<T> where T : IUserKeyRecord<T>

用户数据集合，提供高效的数据查询和分组功能

备注

该类封装了用户数据记录集合，提供按用户ID和数据键进行分组查询的功能。 适用于云数据查询结果的后续处理和分析。 数据键相关的便利查询使用 OrdinalIgnoreCase 比较，贴近底层云数据存储可能大小写不敏感的命中语义。

构造函数 ​

UserData 双端 ​

csharp
public UserData(IEnumerable<T> records)

用户数据集合，提供高效的数据查询和分组功能

备注

该类封装了用户数据记录集合，提供按用户ID和数据键进行分组查询的功能。 适用于云数据查询结果的后续处理和分析。 数据键相关的便利查询使用 OrdinalIgnoreCase 比较，贴近底层云数据存储可能大小写不敏感的命中语义。

属性 ​

Records 双端 ​

csharp
public IEnumerable<T> Records { get; }

原始记录集合

Count 双端 ​

csharp
public int Count { get; }

获取记录总数

UserCount 双端 ​

csharp
public int UserCount { get; }

获取唯一用户ID的数量

KeyCount 双端 ​

csharp
public int KeyCount { get; }

获取唯一键的数量

方法 ​

GetByKey 双端 ​

csharp
public IEnumerable<T>? GetByKey(string key)

根据数据键分组查询

  • key — 数据键，不能为null或空

返回： 匹配的记录集合，如果键为空则返回null

备注

此方法会按大小写不敏感比较过滤出所有Key属性等于指定键的记录。

GetByUserId 双端 ​

csharp
public IEnumerable<T> GetByUserId(long userId)

根据用户ID分组查询

  • userId — 用户ID

返回： 该用户的所有记录

备注

此方法会过滤出所有UserId属性等于指定用户ID的记录。

GetByUserIds 双端 ​

csharp
public IEnumerable<T> GetByUserIds(params long[] userIds)

根据多个用户ID查询

  • userIds — 用户ID数组

返回： 指定用户的所有记录

GetByKeys 双端 ​

csharp
public IEnumerable<T> GetByKeys(params string[] keys)

根据多个数据键查询

  • keys — 数据键数组

返回： 指定键的所有记录

HasUserId 双端 ​

csharp
public bool HasUserId(long userId)

检查是否包含指定用户ID的记录

  • userId — 用户ID

返回： 如果包含该用户的记录则返回true

HasKey 双端 ​

csharp
public bool HasKey(string key)

检查是否包含指定键的记录

  • key — 数据键

返回： 如果包含该键的记录则返回true

GetByPlayer 仅服务端 ​

csharp
public IEnumerable<T>? GetByPlayer(Player player)

根据玩家对象分组查询（仅服务端）

  • player — 玩家对象

返回： 该玩家的所有记录，如果玩家无效则返回null

备注

此方法会自动从Player对象提取UserId进行查询。 只有连接的真人玩家才会返回数据，AI玩家会返回null。

UserNames 双端 ​

命名空间 GameCore.UserCloudData

csharp
public class UserNames

构造函数 ​

UserNames 双端 ​

csharp
public UserNames(IEnumerable<IUserNameRecord> records)

属性 ​

Records 双端 ​

csharp
public IEnumerable<IUserNameRecord> Records { get; }

方法 ​

GetUserName 双端 ​

csharp
public string? GetUserName(long userId)

ListItemReference 仅服务端 ​

命名空间 GameCore.UserCloudData.Internal

csharp
public sealed class ListItemReference

列表项引用，包含自动生成的ID和相关信息

备注

该类用于在事务构建过程中引用列表项，确保ID、列表键、用户ID和数据的一致性。 通过引用对象可以避免参数传递错误，提供类型安全的操作。

属性 ​

Id 仅服务端 ​

csharp
public long Id { get; }

列表项的全局唯一ID

ListKey 仅服务端 ​

csharp
public string ListKey { get; }

列表键，标识该项目属于哪个列表

UserId 仅服务端 ​

csharp
public long UserId { get; }

所属用户ID

Data 仅服务端 ​

csharp
public byte[] Data { get; }

项目数据

ValueType 仅服务端 ​

csharp
public CloudDataListItemValueType ValueType { get; }

项目数据类型。

DoubleValue 仅服务端 ​

csharp
public double DoubleValue { get; }

当 ValueType 为 Double 时保存双精度浮点值。

方法 ​

ToString 仅服务端 ​

csharp
public override string ToString()

返回引用的字符串表示

返回： 包含ID、列表键和用户ID的描述字符串

Equals 仅服务端 ​

csharp
public override bool Equals(object? obj)

比较两个列表项引用是否相等

  • obj — 要比较的对象

返回： 如果引用相同的列表项则返回true

GetHashCode 仅服务端 ​

csharp
public override int GetHashCode()

获取引用的哈希码

返回： 基于ID的哈希码