# 联机大厅商品2.0文档

《我的世界》手机版联机大厅 现已开放 商业化 与 数据储存 接口，打破开发者的创作边界，为联机游戏开发提供体验式购买、玩家数据持久化等全新条件。

# 数据储存说明

对比资源中心组件，联机大厅的数据储存接口支持上报游戏数据至云端数据库，支持跨存档及跨房间存取数据信息。每创建一个联机大厅作品，皆可在 自测阶段 和 线上阶段 对全局与单个玩家数据进行单独托管。

接口类型	服务范围	有效范围	数量
自定义数据储存	资源中心组件\|联机大厅玩法	单个游戏存档	1
联机大厅数据储存	联机大厅玩法	同玩法内的全部联机大厅房间	∞+

使用联机大厅数据储存功能，开发者便可以根据规范的 接口调用 与 数据结构格式 ，将游戏内的 成长数值 、 货币金额 、甚至 背包信息 等内容由玩家从一个房间带到另一个房间，与不同房间的玩家分享无限可能的乐趣。

常见的数据储存类型	应用方向
成长数值	经验\|等级\|签到天数\|RPG属性等
回合结算	小游戏\|回合制等
货币金额	装备交易\|购买商品等
背包信息	玩家背包\|额外行囊等

# 商品化说明

商品化允许开发者创建体验式购买，即玩家凭意愿和对玩法的认可程度，在联机大厅房间里购买增值服务与物品，让每个开发者的热爱有所回响。

常见的商品类型	应用内容
特殊外观	人物、武器、装备、道具
增值服务	喊话、称号、VIP权限、礼包
游戏通行证	唯一次购买的限量道具

# MODSDK的API与事件

# API

QueryLobbyUserItem

查询还没发货的订单
LobbySetStorageAndUserItem

设置订单已发货或者存数据
LobbyGetStorage

获取存储的数据
LobbyGetStorageBySort

排序获取存储的数据，在开发者平台上配置的可排序的key才可以查询

# 事件

lobbyGoodBuySucServerEvent 当玩家购买完商品，或者玩家登录进联机大厅mod时触发

# 示例mod

lobbyGoodsMod2.0展示了一个基本玩法：

玩法内设计了“金币”的虚拟货币，使用key为money存储，并且设置为可排序的key。
玩法上架了一个商品，玩家购买后可获得100金币，商品的实现指令为add_money_100
玩家可以通过聊天栏输入buysword获得初始装备“钻石剑”的7天有效期，有效期内玩家每次进入新房间都会获得一把钻石剑。重复购买会叠加有效期。
玩家可以在战斗中每击杀一个僵尸获得1个金币，获得的金币在战斗结束时统一结算。聊天栏输入endbattle触发战斗结算。
demo的主要流程如下，详情可阅读demo的代码注释

# Q&A

# 为什么会有数据冲突的情况？

根本原因是，可能会有多个联机大厅房间同时修改同一个玩家的数据，同一个房间的get与set操作之间，可能被插入了其他房间的set操作。

假设我们以这样的流程设置数据（注意这个流程是错的！）：

每个房间记录这一局战斗玩家获得的积分
战斗结束时统一结算，先获取玩家最新积分，然后加上本局积分set回去

就有可能出现这样的情况：

某个玩家在云端的积分是100
这个玩家进入了房间A，并且在这一局游戏内的积分是20
然后这个玩家先阵亡了，于是退出了房间A（这时房间A的战斗还没结束，也还没有进行结算），进了另一个房间B，然后获得了10个积分
然后房间A和房间B同时结算了：两个房间都去获取云端积分，获取到的都是100
于是房间A会设置积分为120，房间B设置积分为110。无论设置的先后顺序如何，结果都是错的！正确的积分应该是130！

# 那应该怎么保证数据的正确性？

为了防止上面所说的这种情况，每次设置数据时都会附带一个“版本号”，每次设置数据的版本都是上一次获取到的版本加一，这样云端就可以根据版本号判断数据时候被别的容器修改过，也就是冲突。这个版本号控制已经由引擎内部控制好，不需要开发者操心，您只需要按api文档里的规范处理好冲突即可。

我们推荐的数据控制流程如下（以积分为例）：

每个房间维护两个容器，一个容器（mPoint）存放云端积分，另一个容器（mDeltaPoint）存放这个房间产生的积分的差异（例如+10分或者-10分）
玩家登录时get数据，存放到mPoint。如果获取不到，则把默认积分（例如1000）放入mPoint
结算，调用LobbySetStorageAndUserItem

上传的积分为mPoint的积分加上mDeltaPoint的积分

def getter():
    return [
        {
            'key': 'point',
        	'value': self.mPoint[playerId] + self.mDeltaPoint[playerId]
        }
    ]

如果返回数据冲突，则用返回的最新积分更新mPoint
然后引擎会自动重试第4步

下面解释一下为何这个流程可以避免数据覆盖：

某个玩家在云端的积分是100
这个玩家进入了房间A，房间获取到该玩家的云端积分是100（同时也会获取到对应的“版本号”），并且在这一局游戏内的积分是20
然后这个玩家先阵亡了，于是退出了房间A（这时房间A的战斗还没结束，也还没有进行结算），进了另一个房间B。

房间获取到该玩家的云端积分是100（同时也会获取到对应的“版本号”），然后玩家在这一局游戏内的积分是10
房间A和房间B同时结算：房间A想要设置积分为100+20，房间B想要设置积分为100+10。

假设房间A的请求先到达，这时云端积分成功设置为120（同时“版本号”+1）
房间B的请求后到达，这时候云端发现版本号不一致！于是将最新的数据（120）返回给房间B。房间B收到后更新本地的mPoint
房间B的引擎重新调用getter并提交数据，此次设置的积分为120+10，设置成功，最终数据正确。

# 为什么demo的lobbyGoodsServerSystem.py，_EndBattle函数中要求将callback，getter以及接口的调用封装到一个子函数内？

假设我们不封装，写成以下的样子：

    def _EndBattle(self):
        for playerId in self.mBattleMoney.keys():
            def getter():
                return [
                    {
                        'key': 'money',
                        'value': self.mMoney[playerId] + self.mBattleMoney[playerId]
                    }
                ]
            def callback(data):
                print playerId
                ...
            httpComp.LobbySetStorageAndUserItem(callback, self.mUid[playerId], None, getter)

因为LobbySetStorageAndUserItem的调用是异步的，getter与callback可能不会马上被调用。

当他们被调用时，这个for循环可能已经结束了，而此时playerId的值是mBattleMoney中的最后一个！

如果多一层函数调用，则不会出现这种情况，playerId的遍历不会影响到子函数的参数。

# 我的玩法不是按局计算，数据会实时更新，我应该如何减小set的频率？

每隔一定时间（例如5分钟）更新数据到云端
玩家退出时更新数据到云端

set接口频率上限为50次/秒，5分钟的间隔可以保证5*60*50=15000名以内的玩家同时在线，以此类推

如果需要承载玩家数量的量级更高，则要舍弃定时上传，只在玩家退出时上传

# 我的玩法不是按局计算，数据会实时更新，我应该如何维护数据的正确性？

对于定时上传，可以参考以下写法：

def callback(data):
    if data:
        code = data['code']
        if code==0：
        	# 设置成功
            newData = {i["key"]: i["value"] for i in data["entity"]["data"]}
            newPoint = newData.get('point', DEFAULT_POINT)
            # 给mDeltaPoint减去上传成功的差量（不能直接清零，因为在调用返回之前mDeltaPoint可能会被更新）
            self.mDeltaPoint[playerId] -= newPoint - self.mPoint[playerId]
            # 使用返回的新数据更新mPoint
            self.mPoint[playerId] = newPoint
        else if code==2:
            # 数据冲突，直接用返回的数据更新mPoint
            newData = {i["key"]: i["value"] for i in data["entity"]["data"]}
            self.mPoint[playerId] = newData.get('point', DEFAULT_POINT)
            
def getter():
    return [
        {
            'key': 'point',
            'value': self.mPoint[playerId] + self.mDeltaPoint[playerId]
        }
    ]

← 联机大厅作品与商品上传文档竞技模式组件文档 →