联机大厅

索引

接口		描述
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
示例

数据类型	说明
int	房主uid；非联机大厅或房主uid不存在时返回0

python

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
示例

参数名	数据类型	说明
callback	function	回调函数，需接受一个参数：成功时为玩家所在房间id(int)，失败/非联机大厅时为None
uid	int	玩家uid

数据类型	说明
bool	是否已发起请求，非联机大厅时返回False。结果经callback异步返回

python

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
示例

参数名	数据类型	说明
playerId	str	玩家实体id

数据类型	说明
int	玩家uid

python

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 表示房主不在当前游戏世界中
示例

数据类型	说明
dict/None	房间信息字典，

python

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异步返回
示例

参数名	数据类型	说明
callback	function	回调函数，需接受一个参数：成功时为包含房间所有元数据的dict，失败/房间不存在时为None
roomId	int	目标房间id

数据类型	说明
bool	是否已发起请求，非联机大厅时返回False。结果经callback异步返回

python

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中。
- 该接口不能踢房主
示例

参数名	数据类型	说明
playerId	str	被踢出玩家的entityId
message	str	自定义踢出提示信息，默认为None，使用默认提示

数据类型	说明
bool	是否踢出成功

python

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中。
- 该接口不能踢房主
示例

参数名	数据类型	说明
uid	int	玩家uid
message	str	自定义踢出提示信息，默认None，使用默认提示

数据类型	说明
bool	是否踢出成功

python

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如果没有设置过，就不会出现在返回的最新数据中）
  python
```
{
    "entity": {
        "data": [
            {
                "key": str,     # 数据的key
                "value": int/float/str  # 数据的值
            },
            ...
        ]
    }
}
```
- 该接口有调用频率限流，同一个组件所有联机大厅房间的请求频率最多为每秒200次。如果请求超过该频率会导致阻塞，请求的相应时间变长。
示例

python

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如果没有设置过，就不会出现在返回的最新数据中）
  python
```
{
    "entity": {
        "data": [
            {
                "uid": int,     # 玩家uid
                "nickname": str     # 玩家的用户名
                "value": int/float/str,  # 数据的值
            },
            ...
        ]
    }
}
```
示例

python

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如果之前没有设置过，就不会出现在返回的最新数据中））具体格式如下：
python
```
{
    “code”: int,  # 返回码
    "message": str  # 返回信息
    "entity": {
        "data": [  # 数据库最新值
            {
                "key": str,     # 数据的key
                "value": object  # 数据的值
            },
            ...
        ]
    }
}
```

entitiesGetter需要返回一个list(dict)，格式为：

python

[
    {
        "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调用会保证顺序执行

示例

python

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，格式为：

python

{
    "entity": {
        "orders": [
            {
                "order_id": int,    # 订单id
                "timestamp": int,   # 购买时间
                "cmd": str          # 实现指令
                "product_count": int  # 购买数量。目前不允许一次购买多个，所以返回都是1
            },
            ...
        ]
    }
}

示例

python

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
示例

参数名	数据类型	说明
key	str	元数据键名
value	any	元数据值，须为JSON可序列化类型（dict/list/str/int/float/bool/None及其嵌套），非JSON可序列化时返回False

数据类型	说明
bool	是否设置成功。

python

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
示例

参数名	数据类型	说明
playerId	str	目标玩家entityId，必须为当前在线玩家

数据类型	说明
bool	是否转移成功。非联机大厅、目标不在线、目标非玩家、或与当前房主相同时返回False

python

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
示例

参数名	数据类型	说明
playerUid	str	目标玩家uid，必须为当前在线玩家

数据类型	说明
bool	是否转移成功。非联机大厅、目标不在线、或与当前房主相同时返回False

python

import mod.server.extraServerApi as serverApi
levelId = serverApi.GetLevelId()
lobbyComp = serverApi.GetEngineCompFactory().CreateLobbyGame(levelId)
lobbyComp.TransferRoomHostByUid(targetUid)

通用

世界

实体

玩家

方块

自定义UI

特效

后处理

虚拟世界

物理

零件

通用

预设

联机大厅

索引

GetHostPlayerUid

GetPlayerRoomId

GetPlayerUid

GetRoomInfo

GetRoomMeta

KickPlayer

KickPlayerByUid

LobbyGetStorage

LobbyGetStorageBySort

LobbySetStorageAndUserItem

QueryLobbyUserItem

SetRoomMeta

TransferRoomHost

TransferRoomHostByUid

联机大厅 ​

索引 ​

GetHostPlayerUid ​

GetPlayerRoomId ​

GetPlayerUid ​

GetRoomInfo ​

GetRoomMeta ​

KickPlayer ​

KickPlayerByUid ​

LobbyGetStorage ​

LobbyGetStorageBySort ​

LobbySetStorageAndUserItem ​

QueryLobbyUserItem ​

SetRoomMeta ​

TransferRoomHost ​

TransferRoomHostByUid ​

联机大厅

索引

GetHostPlayerUid

GetPlayerRoomId

GetPlayerUid

GetRoomInfo

GetRoomMeta

KickPlayer

KickPlayerByUid

LobbyGetStorage

LobbyGetStorageBySort

LobbySetStorageAndUserItem

QueryLobbyUserItem

SetRoomMeta

TransferRoomHost

TransferRoomHostByUid