# 通用

# CheckCanBindUI

客户端

method in mod.client.extraClientApi

  • 描述

    检查实体是否可以绑定头顶UI,如何将UI与实体绑定详见CreateUI接口

  • 参数

    参数名
    数据类型
    说明
    entityId str 实体id
  • 返回值

    数据类型
    说明
    bool 是否可以绑定头顶UI True:可以绑定 False:不能绑定
  • 备注

    • 不能绑定头顶UI通常是由于该实体已经死亡或该实体刚创建出来。刚创建的实体若无法绑定头顶UI,等待1-3帧后再次尝试绑定即可
  • 示例

import mod.client.extraClientApi as clientApi
canBind = clientApi.CheckCanBindUI(entityId)

# CreateUI

客户端

method in mod.client.extraClientApi

  • 描述

    创建UI,详见界面创建流程及生命周期

  • 参数

    参数名
    数据类型
    说明
    nameSpace str 命名空间,建议为mod名字
    uiKey str UI唯一标识
    createParams dict 创建UI的参数,会传到UI类的_init_函数中
  • 返回值

    数据类型
    说明
    ScreenNode UI节点
  • 备注

    • createParams参数解释如下:

      参数 类型 解释
      isHud int 值为( 0 / 1) ,意为是否为HUD界面的UI。一般情况下,射击按钮不屏蔽游戏, 原生的操作的界面应该isHud为1;商城界面等不是游戏内操作的界面isHud应该为0,默认值为0。当isHud取0时,创建的UI会默认从比当前UI的层级大1000的地方生成,可能会造成控件遮挡情况;当isHud为1时,创建的UI会从层级为0的地方生成
      inputMode int 值为( 0 / 1 ) ,属于旧版本写法,和isHud含义相同但取值相反,即isHud取0 等于 inputMode取1,两者同时存在优先判断isHud。
      bindEntityId str 意为绑定实体的id。若不传入该键值对或值为None,则会以isHud = 0来处理该UI界面。
      bindWorldPosition (int, (float, float, float)) 第一个元素为绑定的维度,第二个为世界坐标, 若传入这个参数,autoScale默认为1,isHud强制为1,其他传入参数无效。
      bindOffset tuple 意为UI与绑定实体的偏移量,默认值为(0, 1, 0)。
      autoScale int 值为( 0 / 1 ) ,意为绑定实体的UI是否会自动根据实体与本地玩家的距离动态缩放大小,默认值为1,即会动态缩放头顶UI的大小。
      mini_map_root_path str 小地图控件根路径
    • 当isHud参数设置为0或不传时,会在比当前UI的层级大1000的地方生成,生成后再调用SetIsHud接口无法再修改层级!如果新创建的UI导致了其他UI无法正常交互,可以把新UI中main的type由screen改为panel,并删除screen相关属性来解决遮挡问题。

    • 设置自动缩放需要将UI写为百分比形式,设置为固定尺寸将无法缩放,超过一定距离会不可见。

    • 注意: 绑定实体的UI缩放仅作用于根节点(比如"main"节点)下的子节点。

      建议在根节点下挂载一个panel类型的节点,然后将所有需要缩放的UI节点设置为百分比属性并挂载在这个panel节点下。

      如果开启了自动缩放,父节点(如上述panel)的偏移需要设置为[0,0],缩放功能才能正常使用

    • 注意: 若同屏中存在太多绑定实体的UI或一次性创建、删除大量绑定实体UI,都可能会造成卡顿等性能问题。

      建议使用资源池来管理绑定实体UI,当实体与本地玩家距离超过一定范围时,隐藏/移除其绑定UI,或使其绑定UI改为绑定其他有需求的实体。

      当需要大批量创建绑定实体UI时,建议将创建UI的任务分为小批量多次执行,每批次间相距至少一帧。例如需要创建100个绑定实体UI,将任务分散在5帧中,每帧创建20个绑定实体UI。

  • 示例

import mod.client.extraClientApi as clientApi
from mod_log import logger as logger
# 监听引擎初始化完成事件,在这个事件后创建我们的战斗UI
def OnUIInitFinished(self, args):
    logger.info("OnUIInitFinished : %s" % args)
    # 注册UI 详细解释参照《UI API》
    clientApi.RegisterUI(modConfig.ModName, modConfig.FpsBattleUIName, modConfig.FpsBattleUIPyClsPath, modConfig.FpsBattleUIScreenDef)
    # 创建普通UI界面
    clientApi.CreateUI(modConfig.ModName, modConfig.FpsBattleUIName, {"isHud" : 1})
    # 获取创建的UI界面
    self.mFpsBattleUINode = clientApi.GetUI(modConfig.ModName, modConfig.FpsBattleUIName)
    if self.mFpsBattleUINode:
        self.mFpsBattleUINode.Init()

# 不同于上面的例子,这里展示的是如何创建绑定实体的UI界面
def OnUIInitFinished(self, args):
    logger.info("OnUIInitFinished : %s" % args)
    # 同样先注册UI
    clientApi.RegisterUI(modConfig.ModName, modConfig.FpsBattleUIName, modConfig.FpsBattleUIPyClsPath, modConfig.FpsBattleUIScreenDef)
    # 创建绑定id为entityId的实体的UI
    clientApi.CreateUI(
        modConfig.ModName,
        modConfig.FpsBattleUIName,
        {
            "bindEntityId": entityId,
            "bindOffset": (0, 2, 0),
            "autoScale": 1
        }
    )
    self.mFpsBattleUINode = clientApi.GetUI(modConfig.ModName, modConfig.FpsBattleUIName)
    if self.mFpsBattleUINode:
        self.mFpsBattleUINode.Init()

# GetCustomUIControlProxyCls

客户端

method in mod.client.extraClientApi

  • 描述

    获得原生界面自定义UI代理基类

  • 参数

  • 返回值

    数据类型
    说明
    type(CustomUIControlProxy) 原生界面自定义UI代理基类
  • 示例

import client.extraClientApi as clientApi
CustomUIControlProxy = clientApi.GetCustomUIControlProxyCls()

# GetMiniMapScreenNodeCls

客户端

method in mod.client.extraClientApi

  • 描述

    获取小地图ScreenNode基类

  • 参数

  • 返回值

    数据类型
    说明
    type(MiniMapBaseScreen) 小地图ScreenNode基类
  • 示例

import mod.client.extraClientApi as clientApi
MiniMapBaseScreen = clientApi.GetMiniMapScreenNodeCls()

# GetNativeScreenManagerCls

客户端

method in mod.client.extraClientApi

  • 描述

    获得NativeScreenManager类

  • 参数

  • 返回值

    数据类型
    说明
    type(NativeScreenManager) NativeScreenManager类
  • 示例

import client.extraClientApi as clientApi
NativeScreenManager = clientApi.GetNativeScreenManagerCls()

# GetScreenNodeCls

客户端

method in mod.client.extraClientApi

  • 描述

    获得ScreenNode类

  • 参数

  • 返回值

    数据类型
    说明
    type(ScreenNode) ScreenNode类
  • 示例

import client.extraClientApi as clientApi
ScreenNode = clientApi.GetScreenNodeCls()

# GetTopScreen

客户端

method in mod.client.extraClientApi

  • 描述

    获取UI堆栈栈顶的UI节点

  • 参数

  • 返回值

    数据类型
    说明
    ScreenNode UI节点,堆栈为空时返回None
  • 备注

    • 该接口获取最后一次PushScreen创建的界面,区别于GetTopUI接口,GetTopScreen仅可获取PushScreen创建的UI,GetTopUI可获取创建的原生UI或PushScreen创建的UI
  • 示例

import mod.client.extraClientApi as clientApi
node = clientApi.GetTopScreen()

# GetTopUI

客户端

method in mod.client.extraClientApi

  • 描述

    获取UI栈顶的UI名称

  • 参数

  • 返回值

    数据类型
    说明
    str 最顶层的UI名称,如果弹出为原生UI则名称为(原生UI枚举)
  • 备注

    • 获取UI堆栈栈顶的UI名称,区别于GetTopScreen接口,GetTopUI可获取原生UI及PushScreen生成的UI,GetTopScreen仅可获取PushScreen创建的UI。
    • 获取到PushScreen生成UI返回为main,如果在ui的json文件中修改main名称,这里获得的返回值也会与之对应。
  • 示例

import mod.client.extraClientApi as clientApi
TopUIName = clientApi.GetTopUI()

# GetTopUINode

客户端

method in mod.client.extraClientApi

import mod.client.extraClientApi as clientApi
uiNode = clientApi.GetTopUINode()

# GetUI

客户端

method in mod.client.extraClientApi

  • 描述

    获取UI节点,详见界面创建流程及生命周期

  • 参数

    参数名
    数据类型
    说明
    nameSpace str 命名空间,建议为mod名字
    uiKey str UI唯一标识
  • 返回值

    数据类型
    说明
    ScreenNode UI节点
  • 示例

import mod.client.extraClientApi as clientApi
uiNode = clientApi.GetUI(modConfig.ModName, modConfig.FpsBattleUIName)

# GetUIScreenProxyCls

客户端

method in mod.client.extraClientApi

  • 描述

    获得原生界面Screen代理基类

  • 参数

  • 返回值

    数据类型
    说明
    type(CustomUIControlProxy) 原生界面Screen代理基类
  • 示例

import client.extraClientApi as clientApi
CustomUIScreenProxy = clientApi.GetUIScreenProxyCls()

# GetViewBinderCls

客户端

method in mod.client.extraClientApi

  • 描述

    获得ViewBinder类

  • 参数

  • 返回值

    数据类型
    说明
    type(ViewBinder) ViewBinder类
  • 示例

import client.extraClientApi as clientApi
ViewBinder = clientApi.GetViewBinderCls()

# GetViewViewRequestCls

客户端

method in mod.client.extraClientApi

  • 描述

    获得ViewRequest类

  • 参数

  • 返回值

    数据类型
    说明
    type(ViewRequest) ViewRequest类
  • 示例

import client.extraClientApi as clientApi
ViewRequest = clientApi.GetViewViewRequestCls()

# PopScreen

客户端

method in mod.client.extraClientApi

  • 描述

    使用堆栈管理的方式关闭UI

  • 参数

  • 返回值

    数据类型
    说明
    bool 是否关闭成功
  • 备注

    • 该接口关闭由PushScreen创建的界面,区别于PopTopUI接口,PopScreen仅可弹出PushScreen创建的UI,PopTopUI可弹出游戏原生UI及PushScreen创建的UI
  • 示例

import mod.client.extraClientApi as clientApi
clientApi.PopScreen()

# PopTopUI

客户端

method in mod.client.extraClientApi

  • 描述

    弹出UI栈顶的UI

  • 参数

  • 返回值

    数据类型
    说明
    bool 是否成功
  • 备注

    • 弹出UI堆栈栈顶的UI,区别于PopScreen接口,PopTopUI可弹出原生UI及PushScreen生成的UI,PopScreen仅可弹出PushScreen创建的UI。
    • 不允许在同一帧里面进行多次操作,只允许一帧弹出一个UI
  • 示例

import mod.client.extraClientApi as clientApi
MyBool = clientApi.PopTopUI()

# PushScreen

客户端

method in mod.client.extraClientApi

  • 描述

    使用堆栈管理的方式创建UI

  • 参数

    参数名
    数据类型
    说明
    namespace str 命名空间,建议为mod名字
    uiname str UI唯一标识
    createParams dict 创建UI的自定义参数,会传到UI类的_init_函数中,默认为None
  • 返回值

    数据类型
    说明
    ScreenNode UI节点,创建失败时返回None
  • 备注

    • 使用PopScreen可以关闭该接口创建的界面
    • createParams为自定义参数,该参数和CreateUI方法中的createParams不同,不支持CreateUI所列举的所有参数。
    • 生成UI的json文件中is_showing_menu必须设置为True
  • 示例

import mod.client.extraClientApi as clientApi
# 监听引擎初始化完成事件,在这个事件后创建我们的战斗UI
# 由于UI不会在PushScreen被调用后立即创建完成,请不要在Init函数中对控件进行操作,创建完成后会调用screenNode的Create函数
def OnUIInitFinished(self, args):
    clientApi.RegisterUI(modConfig.ModName, modConfig.FpsBattleUIName, modConfig.FpsBattleUIPyClsPath, modConfig.FpsBattleUIScreenDef)
    self.mFpsBattleUINode = clientApi.PushScreen(modConfig.ModName, modConfig.FpsBattleUIName)
    if self.mFpsBattleUINode:
        self.mFpsBattleUINode.Init()

# RegisterUI

客户端

method in mod.client.extraClientApi

  • 描述

    注册UI,创建UI前,需要先注册UI。同一UI只需要注册一次即可。详见界面创建流程及生命周期

  • 参数

    参数名
    数据类型
    说明
    nameSpace str 命名空间,建议为mod名字
    uiKey str UI唯一标识
    clsPath str UI类路径
    uiScreenDef str UI画布路径,格式为"namespace.screenName"。namespace对应uiJson文件中"namespace"对应的值,UI编辑器生成的uiJson文件该值等于文件名。screenName对应想打开的画布的名称。
  • 返回值

    数据类型
    说明
    bool 是否注册成功
  • 示例

import mod.client.extraClientApi as clientApi
from mod_log import logger as logger
# 监听引擎初始化完成事件,在这个事件后创建我们的战斗UI
def OnUIInitFinished(self, args):
    logger.info("OnUIInitFinished : %s" % args)
    # 注册UI 详细解释参照《UI API》
    clientApi.RegisterUI(modConfig.ModName, modConfig.FpsBattleUIName, modConfig.FpsBattleUIPyClsPath, modConfig.FpsBattleUIScreenDef)
    # 创建UI 详细解释参照《UI API》
    clientApi.CreateUI(modConfig.ModName, modConfig.FpsBattleUIName, {"isHud" : 1})
    self.mFpsBattleUINode = clientApi.GetUI(modConfig.ModName, modConfig.FpsBattleUIName)
    if self.mFpsBattleUINode:
        self.mFpsBattleUINode.Init()

# RegisterUIAnimations

客户端

method in mod.client.extraClientApi

  • 描述

    注册UI动画

  • 参数

    参数名
    数据类型
    说明
    data dict 动画的json数据,详见备注
    override bool 是否覆盖原先注册的同命名空间同名的动画(相当于对原先动画的修改),默认值是True,表示覆盖(如果为False,则会检测是否有覆盖,有的话会打印错误信息)
  • 返回值

    数据类型
    说明
    bool 是否注册成功
  • 备注

    • UI属性动画相关,详见属性动画
    • 需要注意的是,动态注册的动画是不支持外部继承以及变量解析的,除此之外,这里是通过代码动态注入动画,实际上和用json写动画是一致的。
  • 示例

# 准备动画的数据,其中必须要有 "namespace" 作为动画的命名空间
# 这里我们一次注册了两个动画片段,分别是 "alpha_animation_1" 以及 "alpha_animation_2"(一次可以注册多个回调,和写 ui json是一致的)
data = {
    "namespace": "alphaTest",
    "alpha_animation_1": {
        "anim_type": "alpha",
        "duration": 1.5,
        "from": 0,
        "to": 1,
        "next": "@namespace.alpha_animation_2"
    },
    "alpha_animation_2": {
        "anim_type": "alpha",
        "duration": 1.5,
        "from": 1,
        "to": 0,
        "next": "@namespace.alpha_animation_1"
    }
}
import mod.client.extraClientApi as clientApi
clientApi.RegisterUIAnimations(data, True)

# UnregisterUIAnimation

客户端

method in mod.client.extraClientApi

  • 描述

    取消UI动画的注册

  • 参数

    参数名
    数据类型
    说明
    namespace str 动画的命名空间
    defName str 动画的名称
  • 返回值

    数据类型
    说明
    bool 是否取消注册成功
  • 备注

  • 示例

# 取消 "alphaTest" 命名空间下的 "alpha_animation_1" 动画,后续无法通过 setAnimation 设置该动画到控件中
import mod.client.extraClientApi as clientApi
clientApi.UnregisterUIAnimation("alphaTest", "alpha_animation_1")