MC 开发者文档

# UI API

下面是UI的一些API接口文档，关于UI的使用请参照UI使用文档。

下面的文档分为两个部分，一部分是在extraClientApi中，另一部分是ScreenNode基类的成员函数。

# extraClientApi

有一部分UI相关的接口分布在extraClientApi的UI分类中。

# ScreenNode

ScreenNode的一些有用的函数，界面Node节点的获取方式在UI使用文档中有详细说明。

	import mod.client.extraClientApi as clientApi
	uiNode = clientApi.GetUI("myModName", "myUIName")

假设下文中的函数，uiNode为获取到的ScreenNode继承类，调用的UI界面是按下面的节点树组织结构的

my_namespace
| main
	| image
	| image_button
	| text1
	| panel
		| text2
	| panel2
		| text_edit_box

# ChangeBindAutoScale

  • 描述

    设置已绑定实体的UI是否根据绑定实体与本地玩家间的距离动态缩放，只对已绑定实体的UI界面生效，如何将UI与实体绑定详见创建UI界面

  • 参数

    参数名 数据类型 说明
    autoScale int 1:动态缩放 0:不动态缩放

  • 返回值

    数据类型 说明
    bool 是否设置成功 True:成功 False:失败

  • 示例

succ = uiNode.ChangeBindAutoScale(1)

# ChangeBindEntityId

  • 描述

    修改绑定的实体id，只对已绑定实体的UI界面生效，如何将UI与实体绑定详见创建UI界面

  • 参数

    参数名 数据类型 说明
    entityId str 绑定的实体id

  • 返回值

    数据类型 说明
    bool 是否修改成功 True:成功 False:失败

  • 示例

succ = uiNode.ChangeBindEntityId(entityId)

# ChangeBindOffset

  • 描述

    修改与绑定实体之间的偏移量，只对已绑定实体的UI界面生效，如何将UI与实体绑定详见创建UI界面

  • 参数

    参数名 数据类型 说明
    offset tuple(float,float,float) 偏移量

  • 返回值

    数据类型 说明
    bool 是否修改成功 True:成功 False:失败

  • 备注

    • 不建议在第一人称视角下，将本地玩家绑定UI的偏移量设为(0, 0, 0)

  • 示例

succ = uiNode.ChangeBindOffset((0, 3, 0))

# Clone

  • 描述

    克隆一个已有的控件，修改它的名称，并将它挂接到指定的父节点上，目前文本、图片、按钮控件的克隆控件表现正常，其他复杂控件的克隆控件可能存在运行问题，建议在json编写的过程中，手动复制一份对应控件使用。

  • 参数

    参数名 数据类型 说明
    componentPath str 为从main节点开始的控件路径
    parentPath str 为从main节点开始，父节点的控件路径
    newName str 为克隆成功后创建的新控件名称，新控件的路径为parentPath/newName

  • 返回值

    数据类型 说明
    bool 是否克隆成功

  • 示例

# we want to clone text2 named text3 on panel
parentPath = "/panel"
text2Path = "/panel/text2"
text3Name = "text3"
uiNode.Clone(text2Path, parentPath, text3Name)

# GetAllChildrenPath

  • 描述

    获取所有子节点的路径list

  • 参数

    参数名 数据类型 说明
    parentPath str 为从main节点开始，父节点的控件路径

  • 返回值

    数据类型 说明
    list(str) 返回父节点下的子节点的路径，会递归返回所有子节点，若节点无子节点，返回空list

  • 示例

# get panel's all children path
node.GetAllChildrenPath("/panel")

# GetBaseUIControl

  • 描述

    根据路径获取BaseUIControl实例

  • 参数

    参数名 数据类型 说明
    path str 当前控件的路径

  • 返回值

    数据类型 说明
    BaseUIControl 路径对应控件的BaseUIControl实例

  • 示例

# 根据路径获得BaseUIControl实例
text2Path = "/panel/text2"
text2UIControl = uiNode.GetBaseUIControl(text2Path)

# GetBindAutoScale

  • 描述

    获取该绑定实体的UI是否动态缩放，未绑定的UI将传回默认值1

  • 参数

    无

  • 返回值

    数据类型 说明
    int 1:动态缩放 0:不动态缩放

  • 示例

autoScale = uiNode.GetBindAutoScale()

# GetBindEntityId

  • 描述

    获取该UI绑定的实体id，未绑定的UI将传回默认值None

  • 参数

    无

  • 返回值

    数据类型 说明
    str 绑定的实体id

  • 示例

entityId = uiNode.GetBindEntityId()

# GetBindOffset

  • 描述

    获取该UI绑定实体的偏移量，未绑定的UI将传回默认值(0, 0, 0)

  • 参数

    无

  • 返回值

    数据类型 说明
    tuple(float,float,float) 偏移量

  • 示例

offset = uiNode.GetBindOffset()

# GetChildrenName

  • 描述

    获取子节点的名称list

  • 参数

    参数名 数据类型 说明
    parentPath str 为从main节点开始，父节点的控件路径

  • 返回值

    数据类型 说明
    list(str) 返回父节点下的子节点的名称，不会递归返回所有子节点，若节点无子节点，返回空list

  • 示例

# get panel's children name
node.GetChildrenName("/panel")

# GetIsHud

  • 描述

    获得本界面的输入模式

  • 参数

    无

  • 返回值

    数据类型 说明
    int 返回1表示该界面不屏蔽游戏操作，返回0则屏蔽。

  • 示例

# 我们需要获得本界面的输入模式
isHud = uiNode.GetIsHud()

# GetRichTextItem

  • 描述

    返回一个富文本控件实例

  • 参数

    参数名 数据类型 说明
    componentPath str 为从main节点开始，继承自rich_text.RichTextPanel控件的路径

  • 返回值

    无

  • 示例

# we want get a rich-text-item
richTextPath = "/RichTextPanel"
richTextItem = uiNode.GetRichTextItem(richTextPath)

# RemoveComponent

  • 描述

    动态删除某一控件

  • 参数

    参数名 数据类型 说明
    componentPath str 为从main节点开始，被删除控件路径
    parentPath str 为从main节点开始，父节点的控件路径

  • 返回值

    无

  • 示例

# we want to remove text2
text2Path = "/panel/text2"
parentPath = "/panel"
uiNode.RemoveComponent(text2Path, parentPath)

# SetIsHud

  • 描述

    设置本界面的输入模式

  • 参数

    参数名 数据类型 说明
    isHud int 设置1表示该界面不屏蔽游戏操作，设置0则屏蔽。

  • 返回值

    无

  • 示例

# 我们需要设置本界面为HUD操作模式
uiNode.SetIsHud(1)

# SetRemove

  • 描述

    删除本界面节点

  • 参数

    无

  • 返回值

    无

  • 示例

# we want to remove this screen
uiNode.SetRemove()

# SetScreenVisible

  • 描述

    设置是否显示本界面

  • 参数

    参数名 数据类型 说明
    visible bool False为隐藏该界面，True为显示该界面

  • 返回值

    无

  • 示例

# 我们隐藏当前UI的界面
uiNode.SetScreenVisible(False)

# SetSelectControl

  • 描述

    设置当年焦点所在的控件

  • 参数

    参数名 数据类型 说明
    componentPath str 为从main节点开始，所要选中控件的路径
    enable bool True为选中componentPath所代表的控件，false为取消选中

  • 返回值

    无

  • 示例

path = "/text_edit_box0"
uiNode.SetSelectControl(path, True)

# SetStackGridCount

  • 描述

    设置StackGrid控件的大小

  • 参数

    参数名 数据类型 说明
    componentPath str 为从main节点开始，Grid控件的路径
    count int 设置StackGrid的内容数量

  • 返回值

    无

  • 示例

# we want change stackgrid count
stackgridPath = "/stack_grid1"
uiNode.SetStackGridCount(stackgridPath, 3)

# SetUiEntity

  • 描述

    设置PaperDoll控件需要显示的生物模型,PaperDoll控件的配置方式详见控件介绍PaperDoll

  • 参数

    参数名 数据类型 说明
    componentPath str 为从main节点开始的控件路径
    entityIdentifier str 生物定义中设定的identifier（暂不支持squid、horse、donkey、mule、zombie_horse、skeleton_horse、drowned、elder_guardian、ender_dragon，将在后续版本支持）

  • 返回值

    无

  • 示例

# we want to show an entity model
imagePath = "/paper_doll0"
uiNode.SetUiEntity(imagePath, 'minecraft:cat')  # 而根据参数说明，传入'minecraft:squid'则无模型显示

# SetUiItem

  • 描述

    设置ItemRenderer控件显示的物品，ItemRenderer控件的配置方式详见控件介绍ItemRenderer

  • 参数

    参数名 数据类型 说明
    componentPath str 为从main节点开始，需要被修改控件的路径
    itemName str 物品identifier
    auxValue int 物品附加值
    isEnchanted bool 可选参数，是否显示附魔效果，默认为False不显示
    userData dict 可选参数，如果是灾厄旗帜或焰火之星等带有userData的需要传入该参数才能正确显示，目前已知仅有灾厄旗帜和焰火之星需要传

  • 返回值

    数据类型 说明
    bool 是否设置结果，True为成功

  • 示例

#设置显示为木板block
itemRenderPath = "/panel/item_renderer"
itemName = "minecraft:wool"
auxValue = 0
uiNode.SetUiItem(itemRenderPath, itemName, auxValue)

# SetUiModel

  • 描述

    设置PaperDoll控件需要显示的模型,PaperDoll控件的配置方式详见控件介绍PaperDoll

  • 参数

    参数名 数据类型 说明
    componentPath str 为从main节点开始的控件路径
    modelName str 骨骼模型的名称
    animateName str 动画名称，默认为'idle'
    looped bool 是否循环播放动画，默认为True

  • 返回值

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

  • 示例

# we want to change model
imagePath = "/paper_doll0"
uiNode.SetUiModel(imagePath, 'saber', 'idle', True)

# SetUiModelScale

  • 描述

    设置PaperDoll控件模型的缩放比例

  • 参数

    参数名 数据类型 说明
    componentPath str 为从main节点开始，被删除控件路径
    scale float PaperDoll的缩放比例，默认为1.0

  • 返回值

    无

  • 备注

    • 当设置为原版生物模型时会导致偏移，建议开发者自行调整位置

  • 示例

imagePath = "/paper_doll0"
uiNode.SetUiModelScale(imagePath, 1.2)

# MiniMapBaseScreen

MiniMapBaseScreen继承于ScreenNode，实现了小地图基本的功能，并且封装了一些操作小地图的接口。 备注：该功能属于实验性功能，目前在低端机可能会出现性能问题，建议开发者合理地使用该功能。 注意事项： 1）不建议在飞行模式或者跑图模式下开启小地图； 2）如果重写了Create接口，请先调用一下super(MiniMapBaseScreen, self).Create()； 3）如果重写了Destroy接口，请先调用一下super(MiniMapBaseScreen, self).Destroy()；

# AddEntityMarker

  • 描述

    增加实体位置标记

  • 参数

    参数名 数据类型 说明
    entityId str 实体Id
    texturePath str 头顶ICON贴图，如textures/blocks/border
    size tuple(float,float) 贴图大小，默认为(4,4)
    enableRotation bool 是否启用实体朝向，默认为False

  • 返回值

    数据类型 说明
    bool 是否增加成功

  • 示例

import mod.client.extraClientApi as clientApi
node = clientApi.CreateUI(modConfig.ModName, modConfig.UIName, {"mini_map_root_path": "/mainPanel"})
node.AddEntityMarker(entityId, "textures/ui/custom_head")

# AddStaticMarker

  • 描述

    增加地图上静态位置的标记

  • 参数

    参数名 数据类型 说明
    key str 标记Id
    vec2 tuple(float,float) 地图位置二维坐标(x,z)
    texturePath str 贴图路径
    size tuple(float,float) 贴图大小，默认为(4,4)

  • 返回值

    数据类型 说明
    bool 是否增加成功

  • 示例

import mod.client.extraClientApi as clientApi
node = clientApi.CreateUI(modConfig.ModName, modConfig.UIName, {"mini_map_root_path": "/mainPanel"})
node.AddStaticMarker("this_is_marker_key", (10,2), "textures/blocks/border", (3,3))

# RemoveEntityMarker

  • 描述

    删除实体位置标记

  • 参数

    参数名 数据类型 说明
    entityId str 实体Id

  • 返回值

    数据类型 说明
    bool 是否删除成功

  • 示例

import mod.client.extraClientApi as clientApi
node = clientApi.CreateUI(modConfig.ModName, modConfig.UIName, {"mini_map_root_path": "/mainPanel"})
node.RemoveEntityMarker(entityId)

# RemoveStaticMarker

  • 描述

    删除静态位置标记

  • 参数

    参数名 数据类型 说明
    key str 标记的Id

  • 返回值

    数据类型 说明
    bool 是否删除成功

  • 示例

import mod.client.extraClientApi as clientApi
node = clientApi.CreateUI(modConfig.ModName, modConfig.UIName, {"mini_map_root_path": "/mainPanel"})
node.RemoveStaticMarker(entityId)

# ZoomIn

  • 描述

    放大地图（最多放大一倍）

  • 参数

    参数名 数据类型 说明
    value float 在原有基础上的增量值，可以控制放大速度，默认为0.1

  • 返回值

    数据类型 说明
    bool 是否成功

  • 示例

import mod.client.extraClientApi as clientApi
node = clientApi.CreateUI(modConfig.ModName, modConfig.UIName, {"mini_map_root_path": "/mainPanel"})
node.ZoomIn(0.2)

# ZoomOut

  • 描述

    缩小地图（最多缩小一倍）

  • 参数

    参数名 数据类型 说明
    value float 在原有基础上的减少值，可以控制缩小速度，默认为0.1

  • 返回值

    数据类型 说明
    bool 是否成功

  • 示例

import mod.client.extraClientApi as clientApi
node = clientApi.CreateUI(modConfig.ModName, modConfig.UIName, {"mini_map_root_path": "/mainPanel"})
node.ZoomOut(0.2)

← UI控件对象 →