# 服务端ExtraAPI接口
这里是一些服务端的基础API接口,完成基础的系统和组件的初始化,同时也能从这个module中获取到一些通用的枚举类和levelId等信息。
# 实体
# AddEntityTickEventWhiteList
描述
添加实体类型到EntityTickServerEvent事件的触发白名单。
参数
参数名 数据类型 说明 identifier str 实体的类型名,原版的实体需要加上minecraft命名空间 返回值
数据类型 说明 bool 是否成功 示例
import mod.server.extraServerApi as serverApi
# 让牛触发EntityTickServerEvent事件
serverApi.AddEntityTickEventWhiteList('minecraft:cow')
# 通用
# GenerateColor
描述
生成颜色字符,用于部分组件的参数设置。
参数
参数名 数据类型 说明 color str 颜色字符,支持的颜色有'BLACK','DARK_BLUE','DARK_GREEN','DARK_AQUA','DARK_RED','DARK_PURPLE','GOLD','GRAY','DARK_GRAY','BLUE','GREEN','AQUA','RED','LIGHT_PURPLE','YELLOW','WHITE' 返回值
数据类型 说明 str 用于引擎接口的颜色字符 示例
import mod.server.extraServerApi as serverApi
ServerSystem = serverApi.GetServerSystemCls()
class FpsServerSystem(ServerSystem):
def GameMsgTest(args):
gameComp = serverApi.GetEngineCompFactory().CreateGame(serverApi.GetLevelId())
#游戏通知栏消息
gameComp.msg = "消息通知"
#游戏通知栏消息颜色
gameComp.msgColor = serverApi.GenerateColor("BLUE")
# GetDirFromRot
描述
通过旋转角度获取朝向
参数
参数名 数据类型 说明 rot tuple(float,float) 俯仰角度及绕竖直方向的角度,单位是角度 返回值
数据类型 说明 tuple(float,float,float) 玩家朝向的单位向量 示例
import mod.server.extraServerApi as serverApi
direction = serverApi.GetDirFromRot((0, 0))
# GetEngineActor
描述
获取所有实体。
参数
无
返回值
数据类型 说明 dict 当前地图中的所有实体信息,key:实体id,value:实体dict 备注
- 实体信息字典 entityDict
关键字 数据类型 说明 dimensionId int 维度id entityType int 实体类型id,可参考EntityType
- 实体信息字典 entityDict
示例
import mod.server.extraServerApi as serverApi
entityDicts = serverApi.GetEngineActor()
# GetEngineNamespace
描述
获取引擎事件的命名空间。监听引擎事件时,namespace传该接口返回的namespace
参数
无
返回值
数据类型 说明 str 引擎的命名空间 示例
import mod.server.extraServerApi as serverApi
ServerSystem = serverApi.GetServerSystemCls()
class FpsServerSystem(ServerSystem):
def __init__(self, namespace, systemName):
ServerSystem.__init__(self, namespace, systemName)
self.ListenForEvent(serverApi.GetEngineNamespace(), serverApi.GetEngineSystemName(), ‘AddServerPlayerEvent’, self, self.OnPlayerAdd)
# GetEngineSystemName
描述
获取引擎系统名。监听引擎事件时,systemName传该接口返回的systemName
参数
无
返回值
数据类型 说明 str 引擎的systemName 示例
import mod.server.extraServerApi as serverApi
ServerSystem = serverApi.GetServerSystemCls()
class FpsServerSystem(ServerSystem):
def __init__(self, namespace, systemName):
ServerSystem.__init__(self, namespace, systemName)
self.ListenForEvent(serverApi.GetEngineNamespace(), serverApi.GetEngineSystemName(), ‘AddServerPlayerEvent’, self, self.OnPlayerAdd)
# GetEntityLimit
描述
获取当前level最大实体数量(上限值,非现有值)
参数
无
返回值
数据类型 说明 int 当前level最大实体数量 示例
import mod.server.extraServerApi as serverApi
print serverApi.GetEntityLimit()
# GetLevelId
描述
获取levelId。某些组件需要levelId创建,可以用此接口获取levelId。其中level即为当前地图的游戏。
参数
无
返回值
数据类型 说明 str 当前地图的levelId 示例
import mod.server.extraServerApi as serverApi
ServerSystem = serverApi.GetServerSystemCls()
class FpsServerSystem(ServerSystem):
def ExtraDataTest(args):
extraDataComp = serverApi.GetEngineCompFactory().CreateExtraData(serverApi.GetLevelId())
extraDataComp.score = 100
# GetMinecraftEnum
描述
用于获取Minecraft枚举值文档中的枚举值
参数
无
返回值
数据类型 说明 minecraftEnum 枚举集合类 示例
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreatePlayer(playerId)
# 使用枚举值作为其他接口的参数
comp.SetPlayerGameType(serverApi.GetMinecraftEnum().GameType.Survival)
# GetPlayerList
描述
获取level中所有玩家的id列表
参数
无
返回值
数据类型 说明 list(str) 返回玩家id列表 示例
import mod.server.extraServerApi as serverApi
print serverApi.GetPlayerList()
# IsInApollo
描述
返回当前游戏Mod是否运行在Apollo网络服,True是说明当前Mod运行于Apollo网络服环境,False时说明当前Mod运行于租赁服、联机大厅或者单机环境
参数
无
返回值
数据类型 说明 bool True:当前Mod运行于Apollo网络服环境 False:当前Mod运行于租赁服、联机大厅或者单机环境 示例
import mod.server.extraServerApi as serverApi
IsInApollo = serverApi.IsInApollo()
# IsInServer
描述
获取当前游戏是否跑在服务器环境下
参数
无
返回值
数据类型 说明 bool True:在服务器环境下 False:不在服务器环境下 示例
import mod.server.extraServerApi as serverApi
isInServer = serverApi.IsInServer()
# SetEntityLimit
描述
设置以玩家为中心,6个chunk范围内的最大实体数量,实体数量超过该值后将不再随机生成实体,不影响summon指令和sdk相关生成实体接口
参数
参数名 数据类型 说明 num int 以玩家为中心,6个chunk范围内的最大实体数量 返回值
数据类型 说明 bool 返回是否设置成功 备注
- 该上限与生物json文件中配置的种群密度共同作用,比如上限是200,但种群密度是10,那么该生物随机生成不会超过10个。此外生物上限还和适合生成的区块容量相关,设置上限过高的话可能因其他限制条件而不能达到该高度。
示例
import mod.server.extraServerApi as serverApi
print serverApi.SetEntityLimit(300)
# StartMultiProfile
描述
开始启动服务端与客户端双端脚本性能分析,启动后调用StopMultiProfile(path)即可在路径path生成函数性能火焰图。双端采集时数据误差较大,建议优先使用StartProfile()单端版本,此接口只支持PC端
参数
无
返回值
数据类型 说明 bool 执行结果 示例
import mod.server.extraServerApi as serverApi
serverApi.StartMultiProfile()
modfunc()# 处理对应的逻辑
# 之后通过计时器或者其他触发方式调用StopMultiProfile
serverApi.StopMultiProfile()
# StartProfile
描述
开始启动服务端脚本性能分析,启动后调用StopProfile(path)即可在路径path生成函数性能火焰图,此接口只支持PC端。生成的火焰图可以用浏览器打开,推荐chrome浏览器。
参数
无
返回值
数据类型 说明 bool 执行结果 备注
- 火焰图主页面示例:
- 如火焰图所示,竖直方向表示调用栈,每一层都是一个函数。调用栈越深,火焰就越高,顶部就是正在执行的函数,下方都是它的父函数。分析性能时主要看火焰图的宽度(其中颜色没有特别意义),火焰图越宽,表示该函数对整体性能的消耗越大。因此需要对该函数进行优化。
- 优化的核心主要是减少调用次数以及优化函数的写法。其中对于开发者而言,只需要关注开发者开发的代码即可,对于部分函数调用到mod框架或者引擎顶层框架进而导致性能消耗较大的,可以尝试通过减少调用次数来进行优化。
- 另外,火焰图支持通过右上方的Search框或者“F3”快捷键对函数关键词进行搜索。同时可以点击函数缩放查看对应的调用栈。
- 火焰图主页面示例:
示例
import mod.server.extraServerApi as serverApi
serverApi.StartProfile()
modfunc()# 处理对应的逻辑
# 之后通过计时器或者其他触发方式调用StopProfile
serverApi.StopProfile()
# StartRecordEvent
描述
开始启动服务端与客户端之间的脚本事件收发包统计,启动后调用StopRecordEvent()即可获取两个函数调用之间引擎收发包的统计信息
参数
无
返回值
数据类型 说明 bool 执行结果 示例
import mod.server.extraServerApi as serverApi
suc = serverApi.StartRecordEvent()
# 之后通过计时器或者其他触发方式调用StopRecordEvent
result = serverApi.StopRecordEvent()
for eventName, data in result.iteritems():
print "event[{}] send={} sendSize={} recv={} recvSize={}".format(eventName, data["send_num"], data["send_size"], data["recv_num"], data["recv_size"])
# StartRecordPacket
描述
开始启动服务端与客户端之间的引擎收发包统计,启动后调用StopRecordPacket()即可获取两个函数调用之间引擎收发包的统计信息
参数
无
返回值
数据类型 说明 bool 执行结果 示例
import mod.server.extraServerApi as serverApi
suc = serverApi.StartRecordPacket()
# 之后通过计时器或者其他触发方式调用StopRecordPacket
result = serverApi.StopRecordPacket()
for packetName, data in result.iteritems():
print "packet[{}] send={} sendSize={} recv={} recvSize={}".format(packetName, data["send_num"], data["send_size"], data["recv_num"], data["recv_size"])
# StopMultiProfile
描述
停止双端脚本性能分析并生成火焰图,与StartMultiProfile()配合使用,此接口只支持PC端
参数
参数名 数据类型 说明 fileName str 具体路径,相对于PC开发包的路径,默认为"flamegraph.svg",位于PC开发包目录下,自定义路径请确保文件后缀名为".svg" 返回值
数据类型 说明 bool 执行结果 示例
import mod.server.extraServerApi as serverApi
serverApi.StartMultiProfile()
modfunc()# 处理对应的逻辑
# 之后通过计时器或者其他触发方式调用StopMultiProfile
serverApi.StopMultiProfile()
# StopProfile
描述
停止服务端脚本性能分析并生成火焰图,与StartProfile()配合使用,此接口只支持PC端
参数
参数名 数据类型 说明 fileName str 具体路径,相对于PC开发包的路径,默认为"flamegraph.svg",位于PC开发包目录下,自定义路径请确保文件后缀名为".svg" 返回值
数据类型 说明 bool 执行结果 示例
import mod.server.extraServerApi as serverApi
serverApi.StartProfile()
modfunc()# 处理对应的逻辑
# 之后通过计时器或者其他触发方式调用StopProfile
serverApi.StopProfile()
# StopRecordEvent
描述
停止服务端与客户端之间的脚本事件收发包统计并输出结果,与StartRecordEvent()配合使用,输出结果为字典,key为网络包名,value字典中记录收发信息,具体见示例
参数
无
返回值
数据类型 说明 dict 收发包信息,假如没有调用过StartRecordEvent,则返回为None 示例
import mod.server.extraServerApi as serverApi
suc = serverApi.StartRecordEvent()
# 之后通过计时器或者其他触发方式调用StopRecordEvent
result = serverApi.StopRecordEvent()
for eventName, data in result.iteritems():
print "event[{}] send={} sendSize={} recv={} recvSize={}".format(eventName, data["send_num"], data["send_size"], data["recv_num"], data["recv_size"])
# StopRecordPacket
描述
停止服务端与客户端之间的引擎收发包统计并输出结果,与StartRecordPacket()配合使用,输出结果为字典,key为网络包名,value字典中记录收发信息,具体见示例
参数
无
返回值
数据类型 说明 dict 收发包信息,假如没有调用过StartRecordPacket,则返回为None 示例
import mod.server.extraServerApi as serverApi
suc = serverApi.StartRecordPacket()
# 之后通过计时器或者其他触发方式调用StopRecordPacket
result = serverApi.StopRecordPacket()
for packetName, data in result.iteritems():
print "packet[{}] send={} sendSize={} recv={} recvSize={}".format(packetName, data["send_num"], data["send_size"], data["recv_num"], data["recv_size"])
# 系统
# GetServerSystemCls
描述
用于获取服务器system基类。实现新的system时,需要继承该接口返回的类
参数
无
返回值
数据类型 说明 type(ServerSystem) 服务端系统类 示例
import mod.server.extraServerApi as serverApi
ServerSystem = serverApi.GetServerSystemCls()
class FpsServerSystem(ServerSystem):
def __init__(self, namespace, systemName):
ServerSystem.__init__(self, namespace, systemName)
# GetSystem
描述
获取已注册的系统
参数
参数名 数据类型 说明 nameSpace str 命名空间,建议为mod名字 systemName str 系统名称,自定义名称,可以使用英文、拼音和下划线,建议尽量个性化 返回值
数据类型 说明 ServerSystem 返回具体系统的实例 示例
import mod.server.extraServerApi as serverApi
serverSystem = serverApi.GetSystem("TutorialMod", "TutorialServerSystem")
# RegisterSystem
描述
系统可以执行我们引擎赋予的基本逻辑,例如监听事件、执行Tick函数、与客户端进行通讯等。
参数
参数名 数据类型 说明 nameSpace str 命名空间,建议为mod名字 systemName str 系统名称,自定义名称,可以使用英文、拼音和下划线,建议尽量个性化 clsPath str 组件类路径,路径从脚本的第一层开始算起 返回值
数据类型 说明 ServerSystem 返回具体系统的实例 示例
import mod.server.extraServerApi as serverApi
# 系统system的注册是在modMain.py的MOD类中
# 服务端系统system的注册方式
@Mod.InitServer()
def TutorialServerInit(self):
serverApi.RegisterSystem("TutorialMod", "TutorialServerSystem", "tutorialScripts.tutorialServerSystem.TutorialServerSystem")
# 组件
# GetComponentCls
描述
用于获取服务器component基类。实现新的component时,需要继承该接口返回的类
参数
无
返回值
数据类型 说明 type(BaseComponent) 组件基类 示例
import mod.server.extraServerApi as serverApi
ServerComponentCls = serverApi.GetComponentCls()
# Component要继承于基类才能生效
class ShootComponentServer(ServerComponentCls):
def __init__(self, entityId):
ServerComponentCls.__init__(self, entityId)
# 这里设置了一个开关来开关更新射击
self.mShoot = False
# GetEngineCompFactory
描述
获取引擎组件的工厂,通过工厂可以创建服务端的引擎组件
参数
无
返回值
数据类型 说明 EngineCompFactoryServer 服务端引擎组件工厂 示例
import mod.server.extraServerApi as serverApi
compFactory = serverApi.GetEngineCompFactory()
gameComp = compFactory.CreateGame(serverApi.GetLevelId())
# RegisterComponent
描述
用于将组件注册到引擎中
参数
参数名 数据类型 说明 nameSpace str 命名空间,建议为mod名字 name str 组件名称 clsPath str 组件类路径,路径从脚本的第一层开始算起 返回值
数据类型 说明 bool 注册成功与否 示例
import mod.server.extraServerApi as serverApi
@Mod.InitServer()
def TutorialServerInit(self):
# 注册一个自定义的服务端Component
serverApi.RegisterComponent("TutorialMod", "ServerShoot", "tutorialScripts.modServer.serverComponent.shootComponentServer.ShootComponentServer")
← 名词解释 客户端ExtraAPI接口 →