# 联机大厅
# 索引
| 接口 | 描述 | |
|---|---|---|
| GetHostPlayerUid | 服务端 | 获取当前联机大厅房主的uid，非联机大厅时返回空字符串 |
| GetPlayerRoomId | 服务端 | 异步获取uid对应的玩家所在的房间id，非联机大厅时回调返回None |
| GetPlayerUid | 服务端 | 获取玩家的uid。只有在线玩家才可获取 |
| GetRoomInfo | 服务端 | 获取当前所在联机大厅的房间信息，非联机大厅时返回None |
| GetRoomMeta | 服务端 | 异步获取指定房间的所有元数据。非联机大厅时返回False |
| KickPlayer | 服务端 | 踢出玩家，可传入自定义提示信息在客户端断线提示中展示，非联机大厅时返回False |
| KickPlayerByUid | 服务端 | 通过uid踢出玩家，可传入自定义提示信息。 |
| LobbyGetStorage | 服务端 | 获取存储的数据。仅联机大厅可用 |
| LobbyGetStorageBySort | 服务端 | 排序获取存储的数据。仅联机大厅可用 |
| LobbySetStorageAndUserItem | 服务端 | 设置订单已发货或者存数据。仅联机大厅可用 |
| QueryLobbyUserItem | 服务端 | 查询还没发货的订单。仅联机大厅可用 |
| SetRoomMeta | 服务端 | 设置当前联机大厅房间的元数据，房间关闭时清除数据。非联机大厅返回False |
| TransferRoomHost | 服务端 | 将联机大厅房主转移给指定在线玩家。仅联机大厅可用，且目标玩家必须在线。 |
| TransferRoomHostByUid | 服务端 | 通过uid将联机大厅房主转移给指定在线玩家。仅联机大厅可用，且目标玩家必须在线。 |
# GetHostPlayerUid
服务端
method in mod.server.component.lobbyGameCompServer.LobbyGameCompServer
描述
获取当前联机大厅房主的uid，非联机大厅时返回空字符串
参数
无
返回值
数据类型说明 int 房主uid；非联机大厅或房主uid不存在时返回0 示例
import mod.server.extraServerApi as serverApi
levelId = serverApi.GetLevelId()
lobbyComp = serverApi.GetEngineCompFactory().CreateLobbyGame(levelId)
uid = lobbyComp.GetHostPlayerUid()
# GetPlayerRoomId
服务端
method in mod.server.component.lobbyGameCompServer.LobbyGameCompServer
描述
异步获取uid对应的玩家所在的房间id，非联机大厅时回调返回None
参数
参数名 数据类型说明 callback function 回调函数，需接受一个参数：成功时为玩家所在房间id(int)，失败/非联机大厅时为None uid int 玩家uid 返回值
数据类型说明 bool 是否已发起请求，非联机大厅时返回False。结果经callback异步返回 备注
- callback(int)的参数为玩家所在的房间id，为None表示该玩家当前不在线/不在该作品房间内
- 当玩家进入房间（此时玩家不一定已经进入游戏里），接口即可返回房间id
示例
import mod.server.extraServerApi as serverApi
levelId = serverApi.GetLevelId()
lobbyComp = serverApi.GetEngineCompFactory().CreateLobbyGame(levelId)
def cb(roomId):
if roomId is None:
print("获取失败或玩家不在联机大厅")
else:
print(roomId)
lobbyComp.GetPlayerRoomId(cb, playerUid)
# GetPlayerUid
服务端
method in mod.server.component.httpToWebServerCompServer.HttpToWebServerCompServer
描述
获取玩家的uid。只有在线玩家才可获取
参数
参数名 数据类型说明 playerId str 玩家实体id 返回值
数据类型说明 int 玩家uid 示例
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateHttp(levelId)
uid = comp.GetPlayerUid(playerId)
# GetRoomInfo
服务端
method in mod.server.component.lobbyGameCompServer.LobbyGameCompServer
描述
获取当前所在联机大厅的房间信息，非联机大厅时返回None
参数
无
返回值
数据类型说明 dict/None 房间信息字典， 备注
- 房间信息字典字段说明：包含 roomId、modId、playerCount、maxCount、ownerEntityId、ownerUid 字段
- ownerEntityId 为 None 表示房主不在当前游戏世界中
示例
import mod.server.extraServerApi as serverApi
levelId = serverApi.GetLevelId()
lobbyComp = serverApi.GetEngineCompFactory().CreateLobbyGame(levelId)
roomInfo = lobbyComp.GetRoomInfo()
if roomInfo:
roomId = roomInfo["roomId"]
modId = roomInfo["modId"]
ownerEntityId = roomInfo["ownerEntityId"]
# GetRoomMeta
服务端
method in mod.server.component.lobbyGameCompServer.LobbyGameCompServer
描述
异步获取指定房间的所有元数据。非联机大厅时返回False
参数
参数名 数据类型说明 callback function 回调函数，需接受一个参数：成功时为包含房间所有元数据的dict，失败/房间不存在时为None roomId int 目标房间id 返回值
数据类型说明 bool 是否已发起请求，非联机大厅时返回False。结果经callback异步返回 示例
import mod.server.extraServerApi as serverApi
levelId = serverApi.GetLevelId()
lobbyComp = serverApi.GetEngineCompFactory().CreateLobbyGame(levelId)
def cb(meta):
if meta is None:
print("获取失败或房间不存在")
else:
print(meta)
roomInfo = lobbyComp.GetRoomInfo()
if roomInfo:
lobbyComp.GetRoomMeta(cb, roomInfo["roomId"])
# KickPlayer
服务端
method in mod.server.component.lobbyGameCompServer.LobbyGameCompServer
描述
踢出玩家，可传入自定义提示信息在客户端断线提示中展示，非联机大厅时返回False
参数
参数名 数据类型说明 playerId str 被踢出玩家的entityId message str 自定义踢出提示信息，默认为None，使用默认提示 返回值
数据类型说明 bool 是否踢出成功 备注
- 返回true表示该玩家必定被踢出，但因退出逻辑是异步，所以此时玩家仍然在playerList中。
- 该接口不能踢房主
示例
import mod.server.extraServerApi as serverApi
levelId = serverApi.GetLevelId()
lobbyComp = serverApi.GetEngineCompFactory().CreateLobbyGame(levelId)
# 使用默认提示踢出玩家
lobbyComp.KickPlayer(playerId)
# 使用自定义提示踢出玩家
lobbyComp.KickPlayer(playerId, "自定义踢出信息")
# KickPlayerByUid
服务端
method in mod.server.component.lobbyGameCompServer.LobbyGameCompServer
描述
通过uid踢出玩家，可传入自定义提示信息。
参数
参数名 数据类型说明 uid int 玩家uid message str 自定义踢出提示信息，默认None，使用默认提示 返回值
数据类型说明 bool 是否踢出成功 备注
- 返回true表示该玩家必定被踢出，但因退出逻辑是异步，所以此时玩家仍然在playerList中。
- 该接口不能踢房主
示例
import mod.server.extraServerApi as serverApi
levelId = serverApi.GetLevelId()
lobbyComp = serverApi.GetEngineCompFactory().CreateLobbyGame(levelId)
lobbyComp.KickPlayerByUid(uid, "自定义踢出信息")
# LobbyGetStorage
服务端
method in mod.server.component.httpToWebServerCompServer.HttpToWebServerCompServer
描述
获取存储的数据。仅联机大厅可用
参数
参数名 数据类型说明 callback function 请求回调函数 uid int 玩家uid，如果传0表示获取全局数据 keys list(str) 查询数据的key列表，排序key与非排序key都可获取 返回值
无
备注
- 可以使用uid为0，key为op_config获取开发者平台的运营管理配置中配置的json
- callback需要接受一个参数
当请求失败时，参数返回None，当请求成功时，参数为一个dict，格式如下。（获取的key如果没有设置过，就不会出现在返回的最新数据中）
{ "entity": { "data": [ { "key": str, # 数据的key "value": int/float/str # 数据的值 }, ... ] } } - 该接口有调用频率限流，同一个组件所有联机大厅房间的请求频率最多为每秒200次。如果请求超过该频率会导致阻塞，请求的相应时间变长。
示例
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateHttp(levelId)
def cb(data):
if data:
print { i["key"]: i["value"] for i in data["entity"]["data"] }
else:
print "获取数据失败"
keys = ["money"]
comp.LobbyGetStorage(cb, uid, keys)
# LobbyGetStorageBySort
服务端
method in mod.server.component.httpToWebServerCompServer.HttpToWebServerCompServer
描述
排序获取存储的数据。仅联机大厅可用
参数
参数名 数据类型说明 callback function 请求回调函数 key str 查询数据的key。在开发者平台上配置的可排序的key才可以查询 ascend bool 是否升序 offset int 从排序后的第几个数据开始返回（从0开始计算） length int 返回多少个数据，上限为50 返回值
无
备注
- 全局数据（即uid为0）不参与排序
- 最多只能获取前200的数据（升序前200及降序前200）
- 返回的结果不一定是最新数据，会有两分钟的刷新间隔，建议只用来作客户端显示，获取业务逻辑所需的数据请使用LobbyGetStorage
- callback需要接受一个参数
当请求失败时，参数返回None，当请求成功时，参数为一个dict，格式如下。（获取的key如果没有设置过，就不会出现在返回的最新数据中）
{ "entity": { "data": [ { "uid": int, # 玩家uid "nickname": str # 玩家的用户名 "value": int/float/str, # 数据的值 }, ... ] } }
示例
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateHttp(levelId)
def cb(data):
if data:
print data["entity"]["data"]
else:
print "获取数据失败"
# 获取money从大到小排序第1到第50的数据
comp.LobbyGetStorageBySort(cb, 'money', False, 0, 50)
# 获取money从大到小排序第51到第100的数据
comp.LobbyGetStorageBySort(cb, 'money', False, 50, 50)
# LobbySetStorageAndUserItem
服务端
method in mod.server.component.httpToWebServerCompServer.HttpToWebServerCompServer
描述
设置订单已发货或者存数据。仅联机大厅可用
参数
参数名 数据类型说明 callback function 请求回调函数 uid int 玩家uid，如果传0表示设置全局数据 orderId int或None 订单Id，可选 entitiesGetter function或None 用于返回存储的数据的函数，可选 返回值
无
备注
uid为0，key为op_config对应开发者平台的运营管理配置中配置的json，使用这个接口时请避免覆盖掉
callback需要接受一个参数 当请求失败时，参数返回None。 当请求成功时，参数为一个dict，包含返回码，最新数据等信息。
- 当code为0时，表示设置成功。
- 当code为2时，表示数据冲突，例如多个房间同时设置同一个玩家的数据或者全局数据。
- 当code为5时，表示订单冲突，例如该订单已经标记为发货了。
当请求成功时，无论返回码是多少，都应该使用返回的最新数据更新本地数据。 当数据冲突时，callback回调结束后会自动重新调用entitiesGetter获取数据并发起重试。 当订单冲突时，callback回调结束后不会重试。 （当发生冲突时，设置的key如果之前没有设置过，就不会出现在返回的最新数据中）） 具体格式如下：
{ “code”: int, # 返回码 "message": str # 返回信息 "entity": { "data": [ # 数据库最新值 { "key": str, # 数据的key "value": object # 数据的值 }, ... ] } }entitiesGetter需要返回一个list(dict)，格式为：
[ { "key": str, # 数据的key，长度最大为64个字符 # uid为0，key为op_config对应开发者平台的运营管理配置中配置的json，请注意避免覆盖掉 "value": object # 数据的值 # 1. 如果是排序的key，value只能是int或者long，范围为-2^63到2^63-1 # 2. 如果是非排序的key，value需要是可以被json序列化的对象，如int/float/str/list/dict等 # 该object序列化为json字符串后，最大不能超过1024*1024个字符 # 中文字符串需要是utf8编码，不要用unicode # 请留意json跟dict的区分，例如json的key一定要是字符串，json没有tuple等 }, ... ]该接口有调用频率限流，同一个组件所有联机大厅房间的请求频率最多为每秒50次。如果请求超过该频率会导致阻塞，请求的相应时间变长。
同一个uid的LobbyGetStorage与LobbySetStorageAndUserItem调用会保证顺序执行
示例
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateHttp(levelId)
playerId = "12345"
orderId = 12345
money = { playerId: 100 }
def cb(data):
if data:
# 更新本地数据
newData = { i["key"]: i["value"] for i in data["entity"]["data"] }
money[playerId] = newData["money"]
else:
print "发货/设置数据失败"
def getter():
return [
{
"key": "money",
"value": money[playerId] + 100
}
]
comp.LobbySetStorageAndUserItem(cb, uid, orderId, getter)
# QueryLobbyUserItem
服务端
method in mod.server.component.httpToWebServerCompServer.HttpToWebServerCompServer
描述
查询还没发货的订单。仅联机大厅可用
参数
参数名 数据类型说明 callback function 请求回调函数 uid int 玩家uid 返回值
无
备注
- callback需要接受一个参数
当请求失败时，参数返回None，当请求成功时，参数为一个dict，格式为：
{ "entity": { "orders": [ { "order_id": int, # 订单id "timestamp": int, # 购买时间 "cmd": str # 实现指令 "product_count": int # 购买数量。目前不允许一次购买多个，所以返回都是1 }, ... ] } }
- callback需要接受一个参数
当请求失败时，参数返回None，当请求成功时，参数为一个dict，格式为：
示例
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateHttp(levelId)
def cb(data):
if data:
print data["entity"]["orders"]
else:
print "查询订单失败"
comp.QueryLobbyUserItem(cb, uid)
# SetRoomMeta
服务端
method in mod.server.component.lobbyGameCompServer.LobbyGameCompServer
描述
设置当前联机大厅房间的元数据，房间关闭时清除数据。非联机大厅返回False
参数
参数名 数据类型说明 key str 元数据键名 value any 元数据值，须为JSON可序列化类型（dict/list/str/int/float/bool/None及其嵌套），非JSON可序列化时返回False 返回值
数据类型说明 bool 是否设置成功。 备注
- 非联机大厅、key非str、value非JSON可序列化时返回False
示例
import mod.server.extraServerApi as serverApi
levelId = serverApi.GetLevelId()
lobbyComp = serverApi.GetEngineCompFactory().CreateLobbyGame(levelId)
lobbyComp.SetRoomMeta("seasonId", 2026)
lobbyComp.SetRoomMeta("scores", {"p1": 10})
# TransferRoomHost
服务端
method in mod.server.component.lobbyGameCompServer.LobbyGameCompServer
描述
将联机大厅房主转移给指定在线玩家。仅联机大厅可用，且目标玩家必须在线。
参数
参数名 数据类型说明 playerId str 目标玩家entityId，必须为当前在线玩家 返回值
数据类型说明 bool 是否转移成功。非联机大厅、目标不在线、目标非玩家、或与当前房主相同时返回False 示例
import mod.server.extraServerApi as serverApi
levelId = serverApi.GetLevelId()
lobbyComp = serverApi.GetEngineCompFactory().CreateLobbyGame(levelId)
lobbyComp.TransferRoomHost(targetPlayerId)
# TransferRoomHostByUid
服务端
method in mod.server.component.lobbyGameCompServer.LobbyGameCompServer
描述
通过uid将联机大厅房主转移给指定在线玩家。仅联机大厅可用，且目标玩家必须在线。
参数
参数名 数据类型说明 playerUid str 目标玩家uid，必须为当前在线玩家 返回值
数据类型说明 bool 是否转移成功。非联机大厅、目标不在线、或与当前房主相同时返回False 示例
import mod.server.extraServerApi as serverApi
levelId = serverApi.GetLevelId()
lobbyComp = serverApi.GetEngineCompFactory().CreateLobbyGame(levelId)
lobbyComp.TransferRoomHostByUid(targetUid)