云变量概述
云变量的基本概念
云变量相当于传统意义上的『数据库』，我们将复杂的数据库操作封装成了简单的云变量语句，开发者可以用云变量来保存游戏的存档，可以用云变量来保存通用的设定，也可以用云变量来构造一个交易行……相信我们的开发者还会为云变量探索出更多的用法。
云变量的使用限制
我们对云变量的提交次数和云变量的数据大小进行了有所限制，默认的限制为：
- 单局游戏（例如一个玩家进入单人模式算一局，6个玩家进入3V3也算一局）每 60s，可以执行300次云变量提交操作，并可以查询300次云变量
- 每一次云变量提交的内容大小不可超过 32MB，约等于一本1120万字的小说的大小，约等于星火编辑器中 40万个物品的序列化数据，但每60s提交的总大小不得超过48MB。
常用云变量类型
通用云变量
大多场景使用的云变量，包括数字、字符串、数组、简单表等。
注意：云变量不能使用无法序列化的类型，如元组、Map、集合等原生TS类型；玩家、单位、技能等运行时游戏对象；以及拥有上述成员变量的简单表或类。存储前可以使用触发语句检测该值是否可以存进云变量。
云变量货币
一种特殊的云变量，其特殊之处在于：
- 格式必须为整数，否则整条提交全部回滚
- 仅提供『消耗』、『添加』和『修改』三种方法，禁止直接对云变量货币进行『设置』
- 使用『消耗』方法时，如果扣除后结果为负，则会返回失败（用于购买物品等场景） ，整条提交全部回滚
- 『修改』方法可以通过添加负数来让实际的值减少，常用于排位积分的增减；而『添加』方法只能添加正数，用于增加一种货币云变量的值
名字型云变量
名字型云变量用来存储唯一字符串键值对，可以理解为文件夹-文件结构。名字类型相当于文件夹，在该类型中，可以定义不同的名字值（也就是文件）; 这些值必须保证唯一性，即它们的值互不相等。
云变量物品
云变量物品是一个物品集合，它可以存储玩家的一组物品，并可以在需要的时候还原到玩家的背包或场景中。此外，还可以在云变量物品里保存自定义数据结构。
云变量触发语句示例
通用/排行榜云变量
使用方法(货币、名字型云变量同理)：
- 新建云变量提交对象
- 向刚才创建的提交对象添加对应操作(设置/添加云变量值)
- 向云端提交该提交对象
修改
查询
货币云变量
增加/消耗
示例：消耗100钻石并增加64800金币
修改
示例：通过修改语句实现强制扣除100钻石的行为
注意：『消耗』语句和通过『修改』语句添加负数值是两种完全不同的行为。如果该云变量值小于消耗值，整个云变量提交对象里的所有操作将会失败；但修改操作会强制添加传入的值，即使这个值为负数，或此时现有云变量值为负数也如此
查询
与通用/排行榜云变量一致
名字型云变量
分配
查询
示例：分别为【角色名字】和【角色】两种名字类型分配 ”哈利波特1“ 和 ”哈利波特2“，并用 “哈利” 前缀查找
输出结果：
哈利波特1
哈利波特2
哈利波特1
哈利波特2
复杂数据类型云变量
云变量还支持存储简单表、类等较复杂的数据结构，通常用于存储玩家存档等数据。
存储
查询
示例：存储一个自定义类和一张套了简单表和类的简单表，并查询它们的值
输出结果：
0
5
检测某个值是否可以存进云变量
在存储云变量数据的时候，有时并不清楚这个值是否可以存进云变量，或者不清楚这个类型是否是合法的。此时可以用触发中提供的『检测云变量是否合法』语句来检测并返回合法值的云变量存储大小（按字节计）。该函数返回一个布尔值，表明值是否合法；如果待检测的云变量值合法，则打印序列化后的长度，否则报错提示非法原因。
示例：判断一个Map、一个单位和一张简单表是否可以存储进云变量
输出结果：
参数含有Map或Set等无法上传的对象false
无法在云变量直接保存游戏对象（如单位、物品、玩家、技能等实例）。若想要保存物品拷贝，请先将物品实例转化为数据信息false
序列化后的云变量长度为: 19
true
注：该语句为调试语句，建议不要把含有该语句的触发器带入正式环境中。
常见云变量错误码和对应解决思路
| 错误码 | 错误原因 | 解决方法 |
|---|---|---|
| -100000 | 该云变量为空 | 检查云变量上传逻辑，并重新上传云变量 |
| -200000 | 云变量配置存在错误 | 添加或修改货币云变量操作传入了预期外的值 |
| -20007 | 云变量超时 | 检查云变量查询逻辑中是否有过于耗时的计算（比如排序函数、循环等） |
| 20 | 云变量调用次数超上限（每分钟300次，同时错误信息为MysqlCountLimit） | 检查云变量查询、上传逻辑的频率，建议使用批量查询 |
| 1213 | 两次云变量的commit同时触发，并且操作的数据的顺序不一致 |
|
| 1205 | 锁等待超时错误 | |
| 7534 | 突发流量，导致并发量急剧上升，数据库底层自动限流 | |
| 1405 | 超出云变量最大长度限制 | 确保存储的数据量在最大范围(32M)内 |
批量查询云变量语句
批量查询云变量语句，配置方式如图，直接放入待查询数组即可
其中需要注意，查询的数组和结果数组并不能保证一一对应，需要对结果重新遍历
此外，当批量查询时，只要有一个能查到结果就会返回成功，因此如果查询『钻石, 不存在的货币，金币』
得到的结果中只有『钻石, 金币』
在此场景下还需要考虑自己处理批量查询结果遍历时的性能问题，不能滥用批量查询
云变量物品
详见【云变量物品】保存和读取云变量物品一节。