xiaokun/netease-modsdk-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

2.6

Browse Source
This commit is contained in:
boybook
2025-12-01 20:59:16 +08:00
parent 12738a142c
commit 760c2dd9ad
5535 changed files with 21070 additions and 2021 deletions
Download Patch File Download Diff File Expand all files Collapse all files

345
docs/mcguide/18-界面与交互/19-控件属性动画.md
View File

@@ -1,5 +1,5 @@
---
front:
front:
hard: 入门
time: 分钟
---
@@ -186,52 +186,52 @@ uv动画和序列帧动画都是uv起点属性的动画，不同于其他属性
要表现一个属性动画，需要先写一个Json数据块，透明度动画举例如下（相关参数会在下文详细描述）：
```json
{
"anim_type" : "alpha",
"duration" : 1.0,
"from" : 0.0,
"to" : 1.0
}
```json
{
"anim_type" : "alpha",
"duration" : 1.0,
"from" : 0.0,
"to" : 1.0
}
```
这段代码块代表一个控件在1秒钟内alpha值从0线性变化到1的属性动画，为了将这个动画绑定到控件上，一共有两种写法。
一种是将Json数据块直接赋给alpha属性：
```json
{
"alphaImg" : {
"alpha" : {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 0.0,
"to" : 1.0
},
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
}
}
```
另一种则是将属性动画写成自定义控件的形式写在UIjson文件的最外层，在alpha属性值以 “@”+动画名 的形式进行赋值：
```json
{
"alphaImg" : {
"alpha" : "@show_alpha_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"show_alpha_ani": {
```json
{
"alphaImg" : {
"alpha" : {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 0.0,
"to" : 1.0
},
}
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
}
}
```
另一种则是将属性动画写成自定义控件的形式写在UIjson文件的最外层，在alpha属性值以 “@”+动画名 的形式进行赋值：
```json
{
"alphaImg" : {
"alpha" : "@show_alpha_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"show_alpha_ani": {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 0.0,
"to" : 1.0
}
}
```
两种写法都能达成相同的效果，不同的是第二种写法能够被复用。
@@ -259,33 +259,34 @@ uv动画和序列帧动画都是uv起点属性的动画，不同于其他属性
* 注2
```json
"alphaImg" : {
"alpha" : "@show_alpha_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"show_alpha_ani": {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 0.0,
"next" : "@hold_alpha_ani",
"to" : 1.0
},
"hold_alpha_ani" : {
"anim_type" : "alpha",
"duration" : 1,
"from" : 1.0,
"next" : "@hide_alpha_ani",
"to" : 1.0
},
"hide_alpha_ani" : {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 1.0,
"to" : 0.0
},
{
"alphaImg" : {
"alpha" : "@show_alpha_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"show_alpha_ani": {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 0.0,
"next" : "@hold_alpha_ani",
"to" : 1.0
},
"hold_alpha_ani" : {
"anim_type" : "alpha",
"duration" : 1,
"from" : 1.0,
"next" : "@hide_alpha_ani",
"to" : 1.0
},
"hide_alpha_ani" : {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 1.0,
"to" : 0.0
}
}
```
### 透明度动画
@@ -301,33 +302,34 @@ uv动画和序列帧动画都是uv起点属性的动画，不同于其他属性
![alpha动画](./picture/UIAnimation/alpha.gif)
```json
"alphaImg" : {
"alpha" : "@show_alpha_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"show_alpha_ani": {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 0.0,
"next" : "@hold_alpha_ani",
"to" : 1.0
},
"hold_alpha_ani" : {
"anim_type" : "alpha",
"duration" : 1,
"from" : 1.0,
"next" : "@hide_alpha_ani",
"to" : 1.0
},
"hide_alpha_ani" : {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 1.0,
"to" : 0.0
},
{
"alphaImg" : {
"alpha" : "@show_alpha_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"show_alpha_ani": {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 0.0,
"next" : "@hold_alpha_ani",
"to" : 1.0
},
"hold_alpha_ani" : {
"anim_type" : "alpha",
"duration" : 1,
"from" : 1.0,
"next" : "@hide_alpha_ani",
"to" : 1.0
},
"hide_alpha_ani" : {
"anim_type" : "alpha",
"duration" : 0.30,
"from" : 1.0,
"to" : 0.0
}
}
```
### 裁剪动画
@@ -343,18 +345,19 @@ uv动画和序列帧动画都是uv起点属性的动画，不同于其他属性
![clip动画](./picture/UIAnimation/clip.gif)
```json
"clipImg" : {
"clip_ratio" : {
"anim_type" : "clip",
"duration" : 1.0,
"from" : 0.0,
"to" : 1.0
},
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
{
"clipImg" : {
"clip_ratio" : {
"anim_type" : "clip",
"duration" : 1.0,
"from" : 0.0,
"to" : 1.0
},
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
}
}
```
### 颜色动画
@@ -370,19 +373,20 @@ uv动画和序列帧动画都是uv起点属性的动画，不同于其他属性
![color动画](./picture/UIAnimation/color.gif)
```json
"colorImg" : {
"color": "@color_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"color_ani": {
"anim_type" : "color",
"duration" : 1.0,
"from" : [1,0,0],
"to" : [0,0,1]
},
{
"colorImg" : {
"color": "@color_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"color_ani": {
"anim_type" : "color",
"duration" : 1.0,
"from" : [1,0,0],
"to" : [0,0,1]
}
}
```
### 序列帧动画
@@ -402,20 +406,22 @@ uv动画和序列帧动画都是uv起点属性的动画，不同于其他属性
![flipbook动画](./picture/UIAnimation/flipbook.gif)
```json
"flipbookImg" : {
"texture" : "textures/ui/my_eating_apple",
"type" : "image",
"uv" : "@flipbook_ani",
"uv_size" : [ 64.0, 64.0 ],
"visible" : true
},
"flipbook_ani": {
"anim_type": "flip_book",
"initial_frame": 10,
"frame_count": 36,
"fps": 10,
"reversible": false
},
{
"flipbookImg" : {
"texture" : "textures/ui/my_eating_apple",
"type" : "image",
"uv" : "@flipbook_ani",
"uv_size" : [ 64.0, 64.0 ],
"visible" : true
},
"flipbook_ani": {
"anim_type": "flip_book",
"initial_frame": 10,
"frame_count": 36,
"fps": 10,
"reversible": false
}
}
```
当一个图片控件被用作序列帧的载体时，该控件的属性配置有以下规则需要遵守：
@@ -441,19 +447,20 @@ uv动画和序列帧动画都是uv起点属性的动画，不同于其他属性
![offset动画](./picture/UIAnimation/offset.gif)
```json
"offsetImg" : {
"offset" : "@offset_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"offset_ani": {
"anim_type" : "offset",
"duration" : 1.0,
"from" : [0, 0],
"to" : [0, 50]
},
{
"offsetImg" : {
"offset" : "@offset_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"offset_ani": {
"anim_type" : "offset",
"duration" : 1.0,
"from" : [0, 0],
"to" : [0, 50]
}
}
```
**注**
@@ -477,19 +484,20 @@ uv动画和序列帧动画都是uv起点属性的动画，不同于其他属性
![size动画](./picture/UIAnimation/size.gif)
```json
"sizeImg" : {
"size" : "@size_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"size_ani": {
"anim_type" : "size",
"duration" : 1.0,
"from" : [100, 100],
"to" : [150, 150]
},
{
"sizeImg" : {
"size" : "@size_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"size_ani": {
"anim_type" : "size",
"duration" : 1.0,
"from" : [100, 100],
"to" : [150, 150]
}
}
```
**注**
@@ -513,19 +521,20 @@ uv动画和序列帧动画都是uv起点属性的动画，不同于其他属性
![uv动画](./picture/UIAnimation/uv.gif)
```json
"sizeImg" : {
"uv" : "@uv_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"uv_ani": {
"anim_type" : "uv",
"duration" : 5,
"from" : [0, 0],
"to" : [2240, 0]
},
{
"sizeImg" : {
"uv" : "@uv_ani",
"texture" : "textures/netease/common/image/default",
"type" : "image",
"visible" : true
},
"uv_ani": {
"anim_type" : "uv",
"duration" : 5,
"from" : [0, 0],
"to" : [2240, 0]
}
}
```

27
docs/mcguide/18-界面与交互/2-从零开始创建UI.md
View File

@@ -1,5 +1,5 @@
---
front:
front:
hard: 入门
time: 分钟
selection: true
@@ -248,23 +248,22 @@ shootButton的锚点，位移XY，尺寸XY的参考属性如下。按照这种
3. 然后激活（显示）对应的界面预设
```python
def InitClient(self):
import mod.client.extraClientApi as clientApi
self.ListenForEngineEvent("UiInitFinished", self, self.OnUIInitFinished)
def InitClient(self):
import mod.client.extraClientApi as clientApi
self.ListenForEngineEvent(UiInitFinishedEvent, self, self.OnUIInitFinished)
```
```python
def OnUIInitFinished(self, args):
import mod.client.extraClientApi as clientApi
if clientApi.GetPlatform() == 0:
uiNodePreset = self.GetParent().GetChildPresetsByName("PC版UI界面")[0]
else:
uiNodePreset = self.GetParent().GetChildPresetsByName("PE版UI界面")[0]
if uiNodePreset:
uiNodePreset.SetUiActive(True)
def OnUIInitFinished(self, args):
import mod.client.extraClientApi as clientApi
if clientApi.GetPlatform() == 0:
uiNodePreset = self.GetParent().GetChildPresetsByName("PC版UI界面")[0]
else:
uiNodePreset = self.GetParent().GetChildPresetsByName("PE版UI界面")[0]
if uiNodePreset:
uiNodePreset.SetUiActive(True)
```
我们利用[UI API文档](40-UIAPI文档.html)中对各个控件的接口和游戏原生支持的格式化，可以在python代码中动态的改变界面的表现，具体可以参考[样式代码](https://zh.minecraft.wiki/w/%E6%A0%B7%E5%BC%8F%E4%BB%A3%E7%A0%81)
我们利用[UI API文档](40-UIAPI文档.html)中对各个控件的接口和游戏原生支持的格式化，可以在python代码中动态的改变界面的表现，具体可以参考[样式代码](https://minecraft-zh.gamepedia.com/index.php?title=%E6%A0%B7%E5%BC%8F%E4%BB%A3%E7%A0%81&variant=zh)
当然，更多API功能还需要你的发现和尝试。

10
docs/mcguide/18-界面与交互/30-UI说明文档.md
View File

@@ -881,7 +881,7 @@ screen，即画布控件，是游戏中一个UI界面的根节点，所有其他
* 注
always_accepts_input，force_render_below， render_game_behind， render_only_when_topmost属性仅在调用PushScreen接口创建UI时才会正常生效。
always_accepts_input，force_render_below， render_game_behind， render_only_when_topmost属性仅在调用<a href="../../mcdocs/1-ModAPI/接口/自定义UI/通用.html#pushscreen" rel="noopenner"> PushScreen </a>接口创建UI时才会正常生效。
名称 | 类型 | 默认值 | 描述
--- | --- | --- | ---
@@ -900,7 +900,7 @@ force_render_below | boolean | false | 是否渲染下方的界面，置true时
send_telemetry | boolean | true | 是否发送遥测数据
close_on_player_hurt | boolean | false | 是否在玩家受伤时关闭屏幕
cache_screen | boolean | false | 是否缓存屏幕上的控件，下次打开界面会更快，但会占用更多内存
load_screen_immediately | boolean | false | 是否在PushScreen后立即加载界面，默认会延迟几帧加载防止卡顿
load_screen_immediately | boolean | false | 是否在<a href="../../mcdocs/1-ModAPI/接口/自定义UI/通用.html#pushscreen" rel="noopenner"> PushScreen </a>后立即加载界面，默认会延迟几帧加载防止卡顿
gamepad_cursor | boolean | false | 是否支持显示手柄光标
gamepad_cursor_deflection_mode | boolean | false | 是否开启手柄光标偏转模式，默认值为false，主要用于手柄适配[轮盘控件](#selection_wheel)
should_be_skipped_during_automation | boolean | false | 是否在自动化测试中应被跳过
@@ -939,7 +939,7 @@ inherit_max_sibling_width | boolean | false | 是否使用兄弟控件的最大
inherit_max_sibling_height | boolean | false | 是否使用兄弟控件的最大高度
contained | false | 该控件可拖动时，是否会被父控件的大小范围所限制
draggable | enum | "not_draggable" | 使控件可以被拖动。控件应能够接受输入才能被拖动（如input_panel, button等），并且必须具有所需的按钮映射。<br>可选值：not_draggable（不可拖动）, vertical（允许垂直拖动）, horizontal（允许水平拖动）, both（自由拖动）
follows_cursor | boolean | false | 控件是否跟随鼠标或手柄指针移动
follows_cursor | boolean | false | 控件是否跟随鼠标或手柄指针移动，仅在调用<a href="../../mcdocs/1-ModAPI/接口/自定义UI/通用.html#pushscreen" rel="noopenner"> PushScreen </a>接口创建的UI中才会正常生效
grid_position | array [row, column] | 取决于自身 | 用于设置控件在grid中的位置，这也允许修改原版硬编码网格的特定网格项
collection_index | int | 取决于自身 | 用于设置控件在集合中的索引
priority | int | 0 | 该控件的优先级，数字越小优先级越高
@@ -1858,7 +1858,7 @@ class UIDemoScreen(ScreenNode):
return index < self.showNum and self.demoGridControl.GetVisible()
```
可以看到grid格子的visible属性我们以"#UIDemo.visible"设置，而该字段经由bindings字段的设置取代了系统变量#visible，再在Python代码中绑定了"#UIDemo.visible"字段的函数更新回调。因此每个格子的visible属性就会读取Python函数的返回值进行动态的设置。有关于数据绑定详情可见[UI绑定和返回](#UI绑定和返回)
可以看到grid格子的visible属性我们以"#UIDemo.visible"设置，而该字段经由bindings字段的设置取代了系统变量#visible，再在Python代码中绑定了"#UIDemo.visible"字段的函数更新回调。因此每个格子的visible属性就会读取Python函数的返回值进行动态的设置，详情可见[集合绑定教程](70-UI数据绑定.md#集合绑定)
### progress_bar
@@ -2201,7 +2201,7 @@ hover事件的触发本质上是与鼠标悬浮相关，在PC模式中，当鼠
* 注2
推荐轮盘所在的Screen用<a href="../../mcdocs/1-ModAPI/接口/自定义UI/通用.html#pushscreen">PushScreen</a>的方式创建，因为PushScreen加载的UI是会对该UI中存在的控件中的贴图资源进行强制加载（如果这个贴图从未显示过的话），考虑到轮盘的贴图资源比较多（6切片的轮盘如果用<a href="../../mcdocs/1-ModAPI/接口/自定义UI/通用.html#createui">CreateUI</a>的方式创建轮盘，并且这些轮盘贴图从未显示过，那么选择轮盘的时候就会产生闪烁现象，原因就是第一次显示的贴图资源会动态加载，而动态加载是需要一定时间的。如果想彻底解决这类加载问题，详见<a href="../20-玩法开发/18-性能优化/内存优化.html#贴图预加载" rel="noopenner"> 贴图预加载 </a>。
推荐轮盘所在的Screen用<a href="../../mcdocs/1-ModAPI/接口/自定义UI/通用.html#pushscreen" rel="noopenner"> PushScreen </a>的方式创建，因为PushScreen加载的UI是会对该UI中存在的控件中的贴图资源进行强制加载（如果这个贴图从未显示过的话），考虑到轮盘的贴图资源比较多（6切片的轮盘如果用<a href="../../mcdocs/1-ModAPI/接口/自定义UI/通用.html#createui" rel="noopenner"> CreateUI </a>的方式创建轮盘，并且这些轮盘贴图从未显示过，那么选择轮盘的时候就会产生闪烁现象，原因就是第一次显示的贴图资源会动态加载，而动态加载是需要一定时间的。如果想彻底解决这类加载问题，详见<a href="../20-玩法开发/18-性能优化/内存优化.html#贴图预加载" rel="noopenner"> 贴图预加载 </a>。
![轮盘控件-9](./picture/IntroduceUI/IntroduceUI-48.gif)

4
docs/mcguide/18-界面与交互/40-UIAPI文档.md
View File

@@ -23,8 +23,8 @@ sidebarDepth: 1
ScreenNode的一些有用的函数，界面Node节点的获取方式在[UI使用文档](30-UI说明文档.html)中有详细说明。
```python
import mod.client.extraClientApi as clientApi
uiNode = clientApi.GetUI("myModName", "myUIName")
import mod.client.extraClientApi as clientApi
uiNode = clientApi.GetUI("myModName", "myUIName")
```
假设下文中的函数，uiNode为获取到的ScreenNode继承类，调用的UI界面是按下面的节点树组织结构的

10
docs/mcguide/18-界面与交互/61-原生界面修改文档.md
View File

@@ -116,8 +116,10 @@ CustomUIScreenProxy是原生界面的代理类，可通过extraClientApi.GetUISc
- 示例
```python
# coding=utf-8
import client.extraClientApi as clientApi
CustomUIScreenProxy = clientApi.GetUIScreenProxyCls()
ViewBinder = clientApi.GetViewBinderCls()
class PauseScreenProxy(CustomUIScreenProxy):
@@ -135,10 +137,10 @@ class PauseScreenProxy(CustomUIScreenProxy):
@ViewBinder.binding(ViewBinder.BF_ToggleChanged, "#myMod.myToggle")
def onToggleChanged(self, args):
"""
proxy也支持binding，这里展示的是绑定一类toggle（这类toggle甚至可以不存在），这类toggle满足"toggle_name"属性是"#myMod.myToggle"这一要求，当他们发生状态改变的时候就会调用该函数。
"""
print("myToggle onToggleChanged: {}".format(args))
"""
proxy也支持binding，这里展示的是绑定一类toggle（这类toggle甚至可以不存在），这类toggle满足"toggle_name"属性是"#myMod.myToggle"这一要求，当他们发生状态改变的时候就会调用该函数。
"""
print("myToggle onToggleChanged: {}".format(args))
```

17
docs/mcguide/18-界面与交互/70-UI数据绑定.md
View File

@@ -169,13 +169,13 @@ property_bag用于定义绑定变量的默认值，假如Python没有返回数
如果直接将 binding_name 与控件需要的属性同名，那么“控件需要的属性名”和“Python 函数里声明的绑定变量名”就会一致，进而“一一对应”，不需要任何额外映射。但在实际项目中，我们可能会遇到以下需求或问题：
1. 你的控件属性名是 #abcdefg，但 Python 中的绑定名偏偏叫 #my_python_binding，二者不一样。
2. 界面上不止一个属性值需要使用同一个绑定变量。举例：我们想让“某个整数”既用来显示文本，又控制可见性（具体见视图绑定部分）。
3. 你不想改 Python 里的函数名，也不想改 JSON 里已有的属性名（因为牵涉到其他位置的调用）。
1. 你的控件属性名是 #abcdefg，但 Python 中的绑定名偏偏叫 #my_python_binding，二者不一样。
2. 界面上不止一个属性值需要使用同一个绑定变量。举例：我们想让“某个整数”既用来显示文本，又控制可见性（具体见视图绑定部分）。
3. 你不想改 Python 里的函数名，也不想改 JSON 里已有的属性名（因为牵涉到其他位置的调用）。
这些场景下，binding_name_override 就能发挥作用：
• binding_name：用来告诉引擎“我要引用 Python 端哪个绑定变量”。
• binding_name：用来告诉引擎“我要引用 Python 端哪个绑定变量”。
• binding_name_override：用来告诉引擎“我把这个绑定变量的值，最终要赋给 UI 的哪个属性”。
假设你原本写了一个 Python 绑定函数，返回一个字符串，名为:
@@ -349,7 +349,7 @@ def ReturnMyStr(self):
## 效果展示
如图所示为季度mod西游：大闹天宫中图鉴的效果展示，下面我们将一步步拆解，通过一个demo复刻来详细介绍如何使用ui数据绑定。这部分是之前的人写的，讲的不是很清楚，看看就好。
如图所示为季度mod西游：大闹天宫中图鉴的效果展示，下面我们将一步步拆解，通过一个demo复刻来详细介绍如何使用ui数据绑定。
![分页](./picture/dataBindingUI/fenye.gif)
@@ -482,6 +482,7 @@ def OnTypeTabChecked(self, args):
self.OnMonsterToggleChecked({ "index": self.mCurMonsterIndex })
```
从JSON中我们可以看到toggle总共有八种状态，各种状态的详细效果可以打开游戏设置界面查看，左侧的按钮就是toggle。主要有选中、未选中两种基础状态，每种状态又有hover和非hover，然后还有锁定、未锁定，所以总共就有2^3=8种状态组合，需要不同的控件展示。由于我们这里比较简单，只考虑了选中、未选中以及锁定三种状态，所以只实现了对应的三种控制panel，其JSON如下：
```json
@@ -700,9 +701,9 @@ def OnItemToggleChecked(self, args):
toggleIndex = 0
self.mCurItemIndex = toggleIndex
itemDict = self.mItemData[self.mCurItemTab][toggleIndex]
self.SetSprite(self.mItemIcon, itemDict["icon"])
self.SetText(self.mItemName, itemDict["name"])
self.SetText(self.mItemDesc, itemDict["desc"])
self.GetBaseUIControl(self.mItemIcon).asImage().SetSprite(itemDict["icon"])
self.GetBaseUIControl(self.mItemName).asLabel().SetText(itemDict["name"])
self.GetBaseUIControl(self.mItemDesc).asLabel().SetText(itemDict["desc"])
self.set_control_visible(self.mItemInfoWrap, True)
```