# 4-控制服API

这里是一些Master的基础API接口。

# 配置

# GetCommonConfig

  • 描述

    获取服务器公共配置,包括所有服务器和db的配置,具体参见备注

  • 返回值

    数据类型 说明
    dict 配置内容
  • 备注

    服务器公共配置的示例如下,只展示了核心配置信息:

    {
    "apolloid":111,
    "extra_redis":{
    },
    "game_id":0,
    "game_key":"game_key",
    "gas_server_url":"http://127.0.0.1:111",
    "log_debug_level":true,
    "master":{
    "app_type":"master",
    "app_version":"1.21.0.release20210401",
    "gb":8,
    "ip":"127.0.0.1",
    "keep_alive_period":30,
    "master_port":0,
    "mods":"",
    "port":8000,
    "serverid":0,
    "type":"master"
    },
    "mongo":null,
    "mysql":{
    "database":"test_db",
    "host":"127.0.0.1",
    "password":"test_password",
    "port":3306,
    "user":"test_user"
    },
    "redis":{
    "host":"127.0.0.1",
    "password":"",
    "port":6379
    },
    "review_stage":0,
    "serverlist":[
    {
    "app_type":"proxy",
    "app_version":"1.21.0.release20210401",
    "gb":8,
    "ip":"127.0.0.1",
    "log_debug_level":false,
    "master_port":11003,
    "max_players":0,
    "mods":"",
    "optimum_players":0,
    "port":11002,
    "save":false,
    "serverid":2000,
    "type":"proxy"
    },
    {
    "app_type":"lobby",
    "app_version":"1.21.0.release20210401",
    "gb":8,
    "ip":"127.0.0.1",
    "log_debug_level":false,
    "master_port":13003,
    "max_players":200,
    "mods":"neteaseRound",
    "optimum_players":0,
    "port":13002,
    "save":false,
    "serverid":4000,
    "type":"lobby"
    }
    ],
    "servicelist":[
    ],
    }
    
  • 示例

import master.netgameApi as netMasterApi
conf = netMasterApi.GetCommonConfig()
serverlist = conf['serverlist'] #获取serverlist配置
bDebugLevel = conf['log_debug_level'] #获取日志等级配置

# GetGameTypeByServerId

  • 描述

    获取指定ID服务器的类型

  • 参数

    参数名 数据类型 说明
    serverId int 服务器ID
  • 返回值

    数据类型 说明
    None或str 指定ID的服务器的类型,没有符合条件的服务器时返回None
  • 示例

import master.netgameApi as netMasterApi
gameType = netMasterApi.GetGameTypeByServerId(6000)

# GetServerIdsByGameType

  • 描述

    获取指定类型的服务器id列表

  • 参数

    参数名 数据类型 说明
    gameType str 服务器类型名
  • 返回值

    数据类型 说明
    list(int) 指定类型的服务器ID的列表,没有符合条件的服务器时返回空列表
  • 示例

import master.netgameApi as netMasterApi
idList = netMasterApi.GetServerIdsByGameType("gameA")

# GetServerLoadedModsById

  • 描述

    根据服务器id获取服务器加载mod列表

  • 参数

    参数名 数据类型 说明
    serverId int 服务器id,id为0表示master
  • 返回值

    数据类型 说明
    list(str) 服务器mod列表
  • 示例

import master.netgameApi as netMasterApi
#返回的一个示例:["neteaseAnnounce", "neteaseAuth", "neteaseShop"]
mods = netMasterApi.GetServerLoadedModsById(4000)

# GetServerLoadedModsByType

  • 描述

    根据服务器类型获取服务器加载mod列表。若同种类型服务器配置了不同的mod,则返回其中一个对应mod列表。

  • 参数

    参数名 数据类型 说明
    serverType str 服务器类型
  • 返回值

    数据类型 说明
    list(str) 服务器mod列表
  • 示例

import master.netgameApi as netMasterApi
#返回的一个示例:["neteaseAnnounce", "neteaseAuth", "neteaseShop"]
mods = netMasterApi.GetServerLoadedModsByType("survivalGame")

# IsService

  • 描述

    服务器是否是service服

  • 参数

    参数名 数据类型 说明
    serverId int 服务器id
  • 返回值

    数据类型 说明
    bool True表示是service,False不是service
  • 备注

    本api取代【masterConf.isService】,【masterConf.isService】废弃。

  • 示例

import master.netgameApi as netMasterApi
bService = netMasterApi.IsService(10)

# 玩家

# BanUser

  • 描述

    封禁某个玩家

  • 参数

    参数名 数据类型 说明
    uid int/long 玩家uid
    banTime int 封禁时间,单位为秒,-1表示永封
    reason str 封禁原因,使用utf8编码
    bCombineReason bool 是否组合显示封禁原因。若为True,则按备注说明处理,否则被封禁玩家登陆会提示【reason】
  • 返回值

    数据类型 说明
    bool True设置成功,False表示失败。失败后请延迟一帧后重试
  • 备注

    效果说明如下:

    若banTime>0,则被封禁玩家登陆会提示:您的账号已经被封禁,剩余封禁时间:x天y小时z分,封禁原因:【reason】。如有疑问,请前往客服专区反馈

    若banTime=-1,则被封禁玩家登陆会提示:您的账号已经被永久封禁,封禁原因:【reason】。如有疑问,请前往客服专区反馈

  • 示例

import master.netgameApi as netMasterApi
#玩家123456,被封禁86400秒,登陆链提示:您的账号已经被封禁,剩余封禁时间:1天0小时0分,封禁原因:作弊被封禁一天
netMasterApi.BanUser(123456, 86400, '作弊被封禁一天', True)
#玩家123457,被封禁86400秒,登陆链提示:作弊被封禁一天
netMasterApi.BanUser(123457, 86400, '作弊被封禁一天', False)

# GetBanUserInfo

  • 描述

    获取玩家的封禁信息

  • 参数

    参数名 数据类型 说明
    uid int/long 玩家uid
    callback function 回调函数,包含两个参数:第一个参数是uid;第二个参数是封禁信息,若获取失败,则为None,若没有被封禁则为“{}”,若被封禁,则为dict,解释参见备注
  • 返回值

  • 备注

    callback中的第二个dict参数内容解释如下:

    关键字 数据类型 说明
    banTime int 封禁持续时间,单位是秒,-1表示永久封禁
    banTimestamp int 开始封禁的时间戳,若不是永久封禁,则截止时间为:banTimestamp + banTime
    reason str 封禁原因
  • 示例

import master.netgameApi as netMasterApi
def cb(uid, info):
        #若被封禁返回示例:result 123456 {banTime:10, banTimestamp: 1623325971, reason:"作弊"}
        #若未被封禁返回示例: result 123456 {}
        print 'result', uid, info
netMasterApi.GetBanUserInfo(123456, cb)

# GetOnlineUidList

  • 描述

    获取所有在线玩家的uid列表

  • 返回值

    数据类型 说明
    list(int) 在线玩家的uid列表,当没有玩家在线时返回空列表
  • 备注

    在线玩家的uid列表是缓存再内存中的,档Master意外dump重启之后,只能获取到重启后再登录的玩家的uid

    此接口返回的uid列表可能会很大,不建议在正式环境使用

  • 示例

import master.netgameApi as netMasterApi
uidList = netMasterApi.GetOnlineUidList()

# GetProtocolVersionByUID

  • 描述

    获取在线玩家客户端协议版本号。多协议版本引擎中(比如同时支持1.14客户端和1.15客户端),需要把客户端分配到相同协议版本的lobby/game中

  • 参数

    参数名 数据类型 说明
    uid int/long 玩家的UID
  • 返回值

    数据类型 说明
    None或者int 玩家在线时,返回此玩家客户端协议版本号,玩家不在线时返回None
  • 示例

import master.netgameApi as netMasterApi
protocolVersion = netMasterApi.GetProtocolVersionByUID(123456)

# GetServerIdByUid

  • 描述

    获取在线玩家所在的服务器的ID,返回的信息为当前控制服内存缓存中的信息,玩家很可能很快就离线或者转服

  • 参数

    参数名 数据类型 说明
    uid int/long 需要获取的玩家的UID
  • 返回值

    数据类型 说明
    None或者int 玩家在线时,返回此玩家当前所在的服务器ID,玩家不在线时返回None
  • 备注

    玩家与当前所在服务器ID的映射关系是缓存在内存中的,当Master意外dump重启之后,只能获取到重启后再登录的玩家当前所在的服务器ID

  • 示例

import master.netgameApi as netMasterApi
serverId = netMasterApi.GetServerIdByUid(123456)

# GetUserSilentInfo

  • 描述

    获取玩家的禁言信息

  • 参数

    参数名 数据类型 说明
    uid int/long 玩家uid
    callback function 回调函数,包含两个参数:第一个参数是uid;第二个参数是禁言信息,若获取失败,则为None,若没有被禁言则为“{}”,若被禁言,则为dict,解释如下:
  • 返回值

  • 备注

    callback中的第二个dict参数内容解释如下:

    关键字 数据类型 说明
    banTime int 禁言持续时间,单位是秒,-1表示永久禁言
    banTimestamp int 开始禁言的时间戳,若不是永久禁言,则截止时间为:banTimestamp + banTime
    reason str 禁言原因
  • 示例

import master.netgameApi as netMasterApi
def cb(uid, info):
        #若被禁言返回示例:result 123456 {banTime:10, banTimestamp: 1623325971, reason:"谈论敏感话题"}
        #若未被禁言返回示例: result 123456 {}
        print 'result', uid, info
netMasterApi.GetUserSilentInfo(123456, cb)

# SetLoginStratege

  • 描述

    设置玩家登陆选服策略,要求服务器启动后加载mod时候设置

  • 参数

    参数名 数据类型 说明
    func function 计算玩家登陆服务器,包含两个参数:第一个参数为玩家uid;第二个参数为回调函数,执行后续登陆逻辑,无论登陆是否成功,必须要执行,回调函数只有一个参数,也即目标服务器。
  • 返回值

    数据类型 说明
    bool True设置成功,False表示失败。失败后请延迟一帧后重试
  • 备注

    示例中提供了两种设置登陆策略方法,示例1是方便开发者理解接口,最好不要应用于生产环境,示例2是生产环境使用方法

    调用此API修改选服策略之后,配置的单服最高人数限制会失效,选服策略需要考虑单服的承载力与玩家人数平衡问题,但配置的全服最高人数限制不会失效

  • 示例

#示例1,不考虑滚动更新,设置固定目标服务器
def loginStratege(uid, callback):
        targetId = 20000 #登陆到id为20000的服务器
        callback(targetId) #必须执行,执行登陆后续操作
import master.netgameApi as netMasterApi
netMasterApi.SetLoginStratege(loginStratege)
#示例2,考虑滚动更新,滚动更新过程中服务器id会发生变化,因此需要提供机制,确保目标服务器的有效性
#master mod
class testMaster(MasterSystem):
        def __init__(self,namespace,systemName):
                MasterSystem.__init__(self, namespace, systemName)
                self.mTargetServerIds = [] #包含有效的目标服务器id列表
                def loginStratege(uid, callback):
                        targetId = random.choice(self.mTargetServerIds) #选择目标服务器
                        if not serverManager.IsValidServer(targetId):#检查目标服务器是否有效。因为滚动更新过程中,服务器会慢慢下线,处于无效状态
                                #若发现有无效服务器,则过滤掉所有无效服务器,然后重新选择目标服务器
                                self.mTargetServerIds = [server for server in self.mTargetServerIds if serverManager.IsValidServer(server)]
                                targetId = random.choice(self.mTargetServerIds)
                        callback(targetId) #必须执行,执行登陆后续操作
                netMasterApi.SetLoginStratege(loginStratege)
                self.ListenForEvent('lobbyNameaspace', 'lobbySystem', 'NewLoginServerEvent', self, self.OnNewLoginServer)
        
        def OnNewLoginServer(self, args):
                # 将有效目标服务器记录下来
                serverId = args['serverId]
                if serverId not in self.mTargetServerIds:
                        self.mTargetServerIds.append(serverId)
#lobby mod
class lobbyServer(ServerSystem):
        def __init__(self, namespace, systemName):
                ServerSystem.__init__(self, namespace, systemName)
                self.ListenForEvent(serverApi.GetEngineNamespace(), serverApi.GetEngineSystemName(), 'MasterConnectStatusEvent', self,
                        self.OnMasterConnectStatus)
        def OnMasterConnectStatus(self, args):
                # 同master建立连接后,马上向master注册为有效服务器
                if args['isConnect']:
                        data = {'serverId' : lobbyGameApi.GetServerId()}
                        self.NotifyToMaster('NewLoginServerEvent', data)

# SilentByUID

  • 描述

    禁言某个玩家

  • 参数

    参数名 数据类型 说明
    uid int/long 玩家uid
    banTime int 禁言时间,单位为秒,-1表示永封
    reason str 禁言原因,使用utf8编码
  • 返回值

    数据类型 说明
    bool True设置成功,False表示失败。失败后请延迟一帧后重试
  • 示例

import master.netgameApi as netMasterApi
#玩家123456被禁言,禁言86400秒,禁言原因“说了敏感内容,被禁言一天”
netMasterApi.SilentByUID(123456, 86400, '说了敏感内容,被禁言一天')

# UnBanUser

  • 描述

    解除某个玩家的封禁

  • 参数

    参数名 数据类型 说明
    uid int/long 玩家uid
  • 返回值

    数据类型 说明
    bool True设置成功,False表示失败。失败后请延迟一帧后重试
  • 示例

import master.netgameApi as netMasterApi
#玩家123456解除封禁
netMasterApi.UnBanUser(123456)

# UnSilentByUID

  • 描述

    解除某个玩家的禁言

  • 参数

    参数名 数据类型 说明
    uid int/long 玩家uid
  • 返回值

    数据类型 说明
    bool True设置成功,False表示失败。失败后请延迟一帧后重试
  • 示例

import master.netgameApi as netMasterApi
#玩家123456被解除禁言
netMasterApi.UnSilentByUID(123456)

这里是Master的Http接口

# HTTP服务器

# RegisterMasterHttp

  • 描述

    注册一个新的HTTP接口

  • 参数

    参数名 数据类型 说明
    url str 接口url
    binder instance 响应HTTP请求的实例
    func function 响应HTTP请求的实例函数
  • 返回值

  • 备注

    若您在机器上架设了自建服务来访问master的http服务(插件通过api调用不需要),那么需要遵循以下规范:

    1. 登录机器,到master目录下打开netgame_common.json,复制apollo_secret的值(该secret不同网络服不一样,不同阶段也不一样,生成之后不会改变)
    2. 在http请求头中添加Request-Timestamp字段,值为当前的秒时间戳
    3. 在http请求头中添加Request-Sign字段,值为md5(请求方法+url+请求参数+上述时间戳+apollo_secret的值) 例如md5(POST/netease/hunter-debug{}1665561365bJetTlJRa60H2Pt3qL6duTIGu0MypJuh) = 84b9ffadbf797cc9d2772fdbc86f411b
  • 示例

import json
import master.masterHttp as masterHttp
class HttpHandler(object):
        def __init__(self):
                # 设置接口URI及回调
                url = '/kick-user'
                func = self.HttpTest
                # 注册
                masterHttp.RegisterMasterHttp(url, self, func)
        def HttpTest(self, clientId, requestBody):
                # clientId识别请求唯一id,SendHttpResponse中要携带该参数
                # requestBody为post body内容。如果是json格式,则可以通过下面方式加载内容。
                # import ujson as json
                # request = json.loads(requestBody)
                # 返回处理结果。code必须为1表示处理成功,否则service请求时会认为请求失败。
                response = '{"code":1,"message":"ok"}'
                masterHttp.SendHttpResponse(clientId, response)

# SendHttpRequestToService

  • 描述

    给service发送http请求

  • 参数

    参数名 数据类型 说明
    serverId int service的服务器id
    requestUrl str 请求url,例如“/test-reqeust”
    body str HTTP post body,是个json字符串
  • 返回值

  • 示例

import json
import master.masterHttp as masterHttp
params = {
        "message":"content",
        "code":1
 }
url = "/test-reqeust"
masterHttp.SendHttpRequestToService(8000, url, json.dumps(params))

# SendHttpResponse

  • 描述

    发送HTTP的Response,支持异步返回,返回时候指定请求传入的clientId

  • 参数

    参数名 数据类型 说明
    clientId int 请求唯一id,识别HTTP请求。
    message str HTTP Response的内容
  • 返回值

  • 示例

import json
import master.masterHttp as masterHttp
class HttpHandler(object):
        def __init__(self):
                # 设置接口URI及回调
                url = '/kick-user'
                func = self.HttpTest
                # 注册
                masterHttp.RegisterMasterHttp(url, self, func)
        def HttpTest(self, clientId, requestBody):
                # clientId识别请求唯一id,SendHttpResponse中要携带该参数
                # requestBody为post body内容。如果是json格式,则可以通过下面方式加载内容。
                # import ujson as json
                # request = json.loads(requestBody)
                # 返回处理结果
                response = '{"code":0,"message":"ok"}'
                masterHttp.SendHttpResponse(clientId, response)

这里是master关于服务器管理的一些接口

# 服务器管理

# GetAllResetingServers

  • 描述

    获取所有重置中服务器的id列表

  • 返回值

    数据类型 说明
    list(int) 服务器id列表
  • 示例

import master.serverManager as serverManager
servers = serverManager.GetAllResetingServers()

# GetAllServerStatus

  • 描述

    获取所有服务器的状态。只有状态2表示服务器正常服务,其他状态表示服务器不能服务。

  • 返回值

    数据类型 说明
    dict key:int类型,服务器id,value:int类型,服务器状态。服务器状态如下:
    1:断开连接状态
    2:已连接状态
    3:关服状态
    4:优雅关服状态
    6, 滚动更新中间状态,即将转换到状态7
    7 也是滚动更新中间状态,即将转换到状态1或2
  • 备注

    服务器状态中,2表示正常服务,其他表示不能正常服务。

  • 示例

import master.serverManager as serverManager
statusDict = serverManager.GetAllServerStatus()

# GetAllServersOnlineNum

  • 描述

    获取所有服务器的在线人数

  • 返回值

    数据类型 说明
    dict key,int类型,表示服务器id,value,int类型,表示服务器在线人数
  • 示例

import master.serverManager as serverManager
onlineDict = serverManager.GetAllServersOnlineNum()

# GetConnectedLobbyAndGameIds

  • 描述

    获取所有已经连接的lobby/game的服务器id列表

  • 返回值

    数据类型 说明
    list 服务器id列表,服务器id是int类型。
  • 示例

import master.serverManager as serverManager
idList = serverManager.GetConnectedLobbyAndGameIds()

# GetOneServerStatus

  • 描述

    获取服务器状态。只有状态2表示服务器正常服务,其他状态表示服务器不能服务

  • 参数

    参数名 数据类型 说明
    serverId int 服务器id
  • 返回值

    数据类型 说明
    int 服务器状态。服务器状态如下:
    1:断开连接状态
    2:已连接状态
    3:关服状态
    4:优雅关服状态
    6, 滚动更新中间状态,即将转换到状态7
    7 也是滚动更新中间状态,即将转换到状态1或2
  • 示例

import master.serverManager as serverManager
status = serverManager.GetOneServerStatus(6000)

# GetOnlineNumByServerId

  • 描述

    获取服务器(lobby/game/proxy)的在线人数

  • 参数

    参数名 数据类型 说明
    serverId int 服务器id
  • 返回值

    数据类型 说明
    int 在线人数
  • 示例

import master.serverManager as serverManager
num = serverManager.GetOnlineNumByServerId(4000)

# GetOnlineNumByServerType

  • 描述

    获取某类型服务器的在线人数

  • 参数

    参数名 数据类型 说明
    serverType str 服务器类型,支持代理服/大厅服/游戏服的游戏类型(具体查看studio游戏配置中“类型”配置)
  • 返回值

    数据类型 说明
    int 在线人数
  • 示例

import master.serverManager as serverManager
num = serverManager.GetOnlineNumByServerType("lobby")

# GetServerProtocolVersion

  • 描述

    获取服务器的协议版本号。多协议版本引擎中(比如同时支持1.14客户端和1.15客户端),需要把客户端分配到相同协议版本的lobby/game中

  • 参数

    参数名 数据类型 说明
    serverId int lobby/game服务器id
  • 返回值

    数据类型 说明
    int 协议版本
  • 示例

import master.serverManager as serverManager
version = serverManager.GetServerProtocolVersion(4000)

# GetTotalOnlineNum

  • 描述

    获取总得在线人数

  • 返回值

    数据类型 说明
    int 在线人数
  • 示例

import master.serverManager as serverManager
num = serverManager.GetTotalOnlineNum()

# IsConnectedServer

  • 描述

    master是否与lobby/game/proxy建立连接

  • 参数

    参数名 数据类型 说明
    serverId int 服务器id
  • 返回值

    数据类型 说明
    bool True,已经建立连接;False未建立连接
  • 示例

import master.serverManager as serverManager
bConnect = serverManager.IsConnectedServer(4000)

# IsValidServer

  • 描述

    服务器是否有效。一种用途:master将玩家分配到服务器之前,会检查服务器是否有效,避免把玩家分配到一个即将关闭的服务器中

  • 参数

    参数名 数据类型 说明
    serverId int 服务器id
  • 返回值

    数据类型 说明
    bool True,master已经同服务器建立链接,且服务器正在提供服务,不是即将关闭的服务。
  • 示例

import master.serverManager as serverManager
bValid = serverManager.IsValidServer(4000)

# ResetServer

  • 描述

    重置某个lobby/game。它会将服务器地图恢复到启动时状态并重启服务器。开始重置会触发ResetGamesBeginEvent事件,重置结束会触发ResetGamesEndEvent事件

  • 参数

    参数名 数据类型 说明
    serverId int lobby/game的服务器id
  • 返回值

  • 备注

    注意,对于生存服,若使用了存档A,则重置后仍使用存档A,且重置过程中不会保存地图。

    若需要重置游戏服GameA,使用方法:重置前确保玩家退出对应GameA,重置过程不允许玩家进入GameA,GameA重置完毕后GameA可以发消息告知master或service,告知GameA就绪,然后玩家可以进入GameA了

  • 示例

import master.serverManager as serverManager
serverManager.ResetServer(4000)

# RollingCloseServers

  • 描述

    滚动关服

  • 参数

    参数名 数据类型 说明
    serverIds list(int) 服务器id列表
  • 返回值

  • 示例

import master.serverManager as serverManager
serverManager.RollingCloseServers([6000])

# RollingUpdateServers

  • 描述

    滚动更新服务器,要求网络服使用了这个ip,要求至少存在一个服务器类型为serverType、引擎版本为appVersion的服务器在运行,只能滚动更新代理服/大厅服/游戏服

  • 参数

    参数名 数据类型 说明
    serverType str 服务器类型,支持代理服/大厅服/游戏服的游戏类型(具体查看studio游戏配置中“类型”配置)
    appVersion str 引擎app_verion
    ip str 服务器ip
    addNum int 新增数量,可以是负数
  • 返回值

  • 示例

import master.serverManager as serverManager
serverManager.RollingUpdateServers('lobby', '2.0.0.release20220120', '10.0.0.1', 1)

# StopServerByServerid

  • 描述

    关闭某个服务器。若MCStudio配置网络游戏时设置了“崩溃自动拉起”,则关闭服务器后会被自动拉起,实现重启功能

  • 参数

    参数名 数据类型 说明
    serverId int proxy/lobby/game服务器id
    actType int 1:强制踢出所有玩家后关服;2:等待所有玩家退出后关服
  • 返回值

  • 示例

import master.serverManager as serverManager
serverManager.StopServerByServerid(4000, 2)