first commit

docs/mconline/10-addon教程/第16章：创建界面/课程01.认识界面控件.md

@@ -0,0 +1,109 @@
+---
+front: 
+hard: 进阶
+time: 20分钟
+---
+
+# 认识界面控件
+
+ 
+
+#### 作者：境界
+
+ 
+
+UI界面是由一个个界面控件组合而成，常见的控件有按钮、文字板、网格、输入框等。目前MCSTUDIO支持使用界面编辑器来制作UI，同时可以根据不同分辨率来模拟UI在手机、PC电脑、平板上的效果，最大程度去适配不同终端的屏幕。因此本章会通过界面编辑器来带开发者了解界面控件，对于常用的控件能够获得基本的认识。
+
+ 
+
+#### 画布
+
+画布可以视为界面的入口，一张画布包含着多个属性，同时将界面放入画布内容中，还可以直接适配异形屏，最大程度地使界面在多种屏幕上都能正常使用。
+
+#### 画布属性有以下几种：
+
+①始终支持按键，即这个界面生成时，若玩家按到如移动按键等，人物也会响应按键效果产生移动。
+
+②创建时运行游戏，即这个界面生成时，界面背后的游戏世界是否照常在屏幕上渲染。
+
+③点击穿透，即这个界面生成时，点击后是否会同样在下方的旧界面上响应到这个输入。例如，我们在HUD界面（带有移动键、快捷栏的界面）上生成了另一个新界面，手指点击屏幕时会先点到新界面，而这个属性若勾选起来，则下方的HUD界面也会响应，即可能隔着一个界面还是能点到移动键等。
+
+④代替暂停界面，即这个界面生成后，若在允许弹出暂停界面的情况下，将此属性勾选，则无法弹出暂停界面。
+
+⑤限制光标移动范围，即这个界面生成后，PC电脑上光标只会在界面范围内出现。勾选后非常适合用来将界面与电脑基岩版适配。
+
+⑥强制持续渲染，即这个界面生成后，在电脑资源占用过高时依旧会渲染，不勾选的话，在电脑运算压力过大时，可能不会渲染。
+
+⑦继承基类画布，即界面使用了被绝大多数原版界面使用的画布属性。
+
+ 
+
+#### 画板
+
+面板可以视为界面里一个被分割的区块，是一个区域部分。想象一下，在一个画布中，我们希望在左上角横铺四个按钮，让它们紧贴在一起。比较寻常的方法是使用界面编辑器在画布控件下新建四个按钮，并将它们依次移动到左上角。有时我们希望在控件结构里隐藏按钮显示其他区域，或者在代码里隐藏这几个按钮，可能一下子就要多写很多额外的代码。而通过把控件归纳到面板下，移动面板的位置，面板所包含的控件会一并移动，隐藏面板时，也会一并消失。它更像是电脑文件管理系统的文件夹。学会使用面板，可以将一个界面的功能分开成好几个独立的区域，也可能会让控件结构和在后续的代码编写中起到更加简洁、方便的效果噢！
+
+ 
+
+#### 按钮
+
+按钮可以被玩家点击，在界面编辑器中，通过设置按钮大小和不同按入状态的贴图，可以做出许多丰富的样式。同时编辑器还为开发者在按钮内包装了一个文本，若开发者选择不将文本画在按钮贴图内时，可以选择使用自定义按钮文本的功能。默认情况下按钮贴图会指向无，即使用原版的常用按钮贴图。若使用原生贴图，则会打开原版textures文件夹，点击ui文件夹后可以看到所有的原版贴图，方便开发者选择自己心仪的原版资源。而若选择自定义的话，则会下方资源管理器中，出现由开发者导入的新贴图。
+
+#### 需要注意以下几点：
+
+①按钮使用的贴图一共要用到三种，分别是普通、悬浮、按下，普通即是看到按钮默认下的状态，悬浮是指针放在按钮上的状态，按下则是点击按钮的状态。
+
+②九宫格指九宫格拉伸原理，它是处理贴图纹理在游戏界面减少资源占用中应用到的一种高级方法。更多详细内容可以[查看官方教程](http://mc.163.com/mcstudio/mc-dev/MCDocs/2-ModSDK%E6%A8%A1%E7%BB%84%E5%BC%80%E5%8F%91/04-Mod%E5%BC%80%E5%8F%91%E8%A7%84%E8%8C%83/2-%E8%B4%B4%E5%9B%BE%E8%A7%84%E8%8C%83%E5%8F%8A%E4%B9%9D%E5%AE%AB%E6%A0%BC%E4%BD%BF%E7%94%A8.html)。
+
+ 
+
+#### 图片
+
+图片控件会显示一张图片。需要将图片类型选择原生或者自定义的方式，来选择需要使用的资源。下方的UV起点和UV尺寸，前者会决定图片从哪个端点开始，尺寸决定从UV起点开始，向下延长宽度，向右延长长度。在上一章自定义粒子的时候，我们使用原版粒子贴图可以看到基岩版将所有常用粒子放在一张128x128的尺寸贴图上，使用uv起点和尺寸就是决定显示它的某一个区域。
+
+ 
+
+#### 文本
+
+文本控件顾名思义，就是用来显示文本。文本支持文字投影，文字颜色、字号、行间距、字对齐等功能。所有原版界面显示的文本都依赖它，包括输入框这样的控件，本质上也是将玩家输入的内容以文本的形式呈现出来，是非常重要的控件。
+
+ 
+
+#### 文本输入框
+
+文本输入框允许玩家输入文本进入框内，同时通过代码监听绑定输入框交互和绑定输入框内容，可以知道在脚本内获得文本输入框的内容。需要注意的是，一个新的界面若用到了文本输入框，则会阻止其他输入，如主界面的移动、跳跃按钮等。因此使用到文本输入框的界面，我们应将它处理为一个静止游戏界面。就像原版的聊天界面、背包界面一样。
+
+ 
+
+#### 开关
+
+开关控件常用来决定一个功能或者状态是开启还是关闭。它只带有真假两种状态，在原版的设置界面中大量用到了开关控件。因此在决定一个新界面是否需要用到这样的控件，就要清楚自己是否需要设置一种开启或者关闭的功能。通过代码监听绑定开关交互和按钮状态，可以知道某个开关的状态。
+
+ 
+
+#### 纸娃娃
+
+纸娃娃控件用来渲染一个实体模型到屏幕上。在编辑器中当前只支持显示玩家模型和FBX 三维模型，使用MODSDK可以更加方便地设置模型的缩放大小、实体类型、沿Y轴的旋转角度等。非常适合用来做展示实体生物的界面。
+
+ 
+
+#### 物品渲染
+
+物品渲染控件用来渲染一个物品在界面上。在原版界面里，它常被应用在需要显示物品的地方。如背包界面、附魔台界面、铁砧界面等。这些界面中允许玩家放入物品的物品栏，本质上就是一个按钮下挂载了一个物品渲染控件。当按钮被点选时，按钮呈现按住状态，若里面存在物品时，则在它挂载下的物品渲染控件显示一个物品道具。
+
+ 
+
+#### 进度条
+
+进度条控件常用来显示某种流程的进度。比如某种机器的工作进度、某个状态的变动程度等等。进度条的贴图一般使用一张完整的长贴图，使用modsdk可以对进度条控件设置切割图片的程度，以1.0为一个完整的长度，若通过接口设置切割程度为0.1，则只会显示10%的进度条。
+
+ 
+
+#### 滚动列表
+
+滚动列表常用来滑动一块内容区域，这个内容可以是文本输入框、图片、网格等。想象一下，原版的创造背包栏，物品从头到尾排序下来，显示的按钮数量之多远远超过了屏幕可以容纳的范围。使用滚动列表可以只显示背包栏中间的一块区域，其他部分通过滚动内容区域的形式慢慢向上呈现。
+
+ 
+
+#### 网格
+
+网格控件可以帮助开发者将其他画布的控件内容绑定在网格控件上。例如，原版的大箱子界面内置了一个网格控件，网格的格数大小是从左往右数9格，从上往下数6行，并将网格控件里的内容指向物品栏按钮。这方便开发者统一管理一序列重复的控件，而不需要专门为了实现类似的功能，真的去手动新建多个控件并计算它们之间的间隔排列组合。

docs/mconline/10-addon教程/第16章：创建界面/课程02.使用UI编辑器绘制基础界面.md

@@ -0,0 +1,51 @@
+---
+front: https://mc.res.netease.com/pc/zt/20201109161633/mc-dev/assets/img/2_1.00b439ab.jpg
+hard: 进阶
+time: 20分钟
+---
+
+# 使用UI编辑器绘制基础界面
+
+
+
+#### 作者：境界
+
+
+
+①进入工程后，左上角的编辑器选项选择UI编辑器。
+
+![](./images/2_1.jpg)
+
+
+
+②UI内容最后会被放入一个JSON文件，它位于资源包的ui文件夹内。因此我们在左下角的界面文件列表右侧，点击“+”号新建一个界面文件，命名为custom_ui
+
+![](./images/2_2.jpg)
+
+
+
+③界面文件新建后，会自动在左上角的控件结构中，新增一个名为main的主画布，这个名字可以任意更改，在后续使用MODSDK声明界面的画布入口时，填对即可。为了统一辨识度，我们将在下面的内容中，对每个控件进行严格的命名，比以节点代称，方便开发者能够更好的阅读。
+
+④在main节点下，新建一个面板控件，并将它的名称改为entry_panel，即入口面板。
+
+⑤将entry_panel节点设置为125px长，125px宽，点击属性中的锚点，将锚点设置为左上角。它会自动对齐左上角，而无需通过拖曳的方式来对齐。
+
+⑥在入口面板节点下挂载一个图片控件，我们将其命名为color_image。向下拉，将使用贴图设置为原生，轻击原生按钮入口，会跳出一个电脑的资源管理器，它会自动定位到原版资源文件夹下的textures文件夹，我们选择ui文件夹，并找到white_background.png贴图，选择它。
+
+⑦在color_image节点属性下拉到最低，找到图片适配选项，将九宫格类型选择原版类型，在上、下、左、右四个栏的任意一栏将0像素点写为1像素点。这样贴图资源将会与节点大小匹配，平铺整个控件。
+
+![](./images/2_3.jpg)
+
+
+
+⑧将图片节点拉为100px长，100px宽，锚点的父节点和子节点都选择向中间上部对齐。
+
+⑨在entry_panel节点下，新建一个名为black_button按钮，将大小设置为50px长，20px宽。此时按钮内文字会超过按钮的大小，显示不全，在black_button节点属性下，将文字字号设置为8号。并将文字设置为：按我黑色。
+
+![](./images/2_4.jpg)
+
+
+
+⑩在控件结构面板下，右键black_button节点，复制一次。紧接着选择entry_panel节点，粘贴上去。并将新的按钮控件名称改为white_button。将文字设置为：按我白色。
+
+⑪将black_button、white_button节点锚点对齐中间下部，将两个按钮平行分开。在后面使用MODSDK创建界面时，我们将会学习如何绑定按钮，通过代码让白色贴图在黑色和白色之间来回变化。

docs/mconline/10-addon教程/第16章：创建界面/课程03.在游戏内弹出界面.md

@@ -0,0 +1,31 @@
+---
+front: https://mc.res.netease.com/pc/zt/20201109161633/mc-dev/assets/img/3_1.7d892d10.jpg
+hard: 进阶
+time: 15分钟
+---
+
+# 在游戏内弹出界面
+
+ 
+
+#### 作者：境界
+
+ 
+
+①切换回关卡编辑器，在资源管理器面板下，选择行为包，右键打开行为包所在的文件夹。在文件夹内新建一个脚本文件夹工程。　 
+
+②由于UI界面运行在客户端，并且界面功能仅需调用客户端接口，因此我们只注册一个客户端系统。
+
+③新建一个CustomUi.py文件，导入ScreenNode类。新增一个Main类，并继承ScreenNode。
+
+![](./images/3_2.jpg)
+
+
+
+④监听UiInitFinished事件，在回调函数内使用注册UI接口，UI必须注册才能创建。其中第一个参数是命名空间，第二个参数是UI名称，第三个参数是ui节点路径。ui节点路径的格式与注册系统类似，即"脚本文件夹.CustomUi.Main"。第四个是ui json文件入口，即"custom_ui.main"。
+
+![](./images/3_1.jpg)
+
+
+
+⑤使用客户端的PushScreen接口，第一个参数即UI的命名空间，第二个参数即UI名称，分别对应注册UI的前两个参数。进入游戏后，查看效果。

docs/mconline/10-addon教程/第16章：创建界面/课程04.绑定界面控件和脚本.md

@@ -0,0 +1,23 @@
+---
+front: https://mc.res.netease.com/pc/zt/20201109161633/mc-dev/assets/img/4_1.2374ef65.jpg
+hard: 进阶
+time: 20分钟
+---
+
+# 绑定界面控件和脚本
+
+
+
+#### 作者：境界
+
+
+
+①在 __ init __ 下新建四个实例变量，分别对应继承基础画布后出现的主节点路径，主节点路径下的color_image路径，主节点路径下的black_button路径，主节点路径下的white_button路径。
+
+②重写Main类的Create方法，使用AddTouchEventHandler接口添加两个按钮的回调，第一个参数是路径，第二个是回调函数名。
+
+![](./images/4_1.jpg)
+
+
+
+③在回调函数内，将color_image图片设置为黑色或白色，其中白色的rgb值为255，255，255，除以255后为0.0,0.0,0.0。黑色的rgb值为0，0，0，除以255后为1.0，1.0，1.0。

docs/mconline/10-addon教程/第16章：创建界面/课程05.简易教程①制作一个滚动弹幕.md

@@ -0,0 +1,41 @@
+---
+front: https://mc.res.netease.com/pc/zt/20201109161633/mc-dev/assets/img/5_1.e36f376b.jpg
+hard: 进阶
+time: 25分钟
+---
+
+# 简易教程①：制作一个滚动弹幕
+
+
+
+#### 作者：境界
+
+
+
+#### 设计UI部分：
+
+①在主节点下新建一个图片控件，命名为background，将图片资源类型改为原生，指向textures/ui/white_background.png。并打开原版九宫格，在“上"位置填入1px，使贴图可以被自由拉伸到与控件大小相符合。紧接着，将图片长度大小从固定大小改为百分比大小，设置为100%，将宽度大小设置为固定大小16px。
+
+![](./images/5_1.jpg)
+
+
+
+②将background节点的锚点设置为居中靠上，向下偏移15px。
+
+③在background节点下，新建一个文本控件，命名为text，锚点设置为居中，长度大小同样设置为100%的百分比大小，宽度大小设置为固定大小16px。将字颜色设置为黑色，字号设置为8，添加6的行间距让字靠中对齐，并将字的对齐方式设置为向右对齐。
+
+![](./images/5_2.jpg)
+
+
+
+④将text节点偏移量设置为向左偏移100%的百分比大小，即-100%。这样字就会超出屏幕显示区域，同时顶在屏幕的左边。
+
+⑤打开ui源文件，对background控件进行自定义，向里面加入alpha键对，值为透明度的值，1.0代表不透明，0.0代表全透明，这里设置为0.9。同时添加color键对，可以对图片进行颜色叠加，这里设置为"color": [0.3647, 0.3647, 0.3647]，即灰色的RGB值92，92，92除以255得出的结果。这样可以让白色背景变成灰色，并带有透明度。会更加的好看。
+
+
+
+#### 脚本代码部分：
+
+![](./images/5_3.jpg)
+
+重写UI类的Create方法和Update方法，当UI每一游戏刻更新时，都会调用Update方法，我们在里面更新text节点的位置，让它从左边往右边移动。而Create方法会在UI创建后调用，在这里我们对文本内容进行设置。

docs/mconline/10-addon教程/第16章：创建界面/课程06.简易教程②制作一个简易的生物血条.md

@@ -0,0 +1,39 @@
+---
+front: https://mc.res.netease.com/pc/zt/20201109161633/mc-dev/assets/img/6_1.67d4a73b.jpg
+hard: 进阶
+time: 30分钟
+---
+
+# 简易教程② 制作一个简易的生物血条
+
+
+
+#### 作者：境界
+
+
+
+生物血条示例包下载：下载[示例包](https://g79.gdl.netease.com/guidedemo-case16.zip) 。
+
+#### 设计UI部分：
+
+①在主节点下新建一个进度条控件，取名为health_bar。锚点设置为置中，并将长度设置为80像素，宽度设置为10像素。
+
+②在主节点下新建一个文本控件，取名为health_text。锚点设置为置中，并将长度宽度设置为与health_bar相当，同时字号设置为8号，行间距设置为3。
+
+
+
+#### 脚本代码部分：
+
+![](./images/6_1.jpg)
+
+
+
+重写UI类的Create方法和Update方法，当UI每一游戏刻更新时，都会调用Update方法，我们在里面使用一个小技巧，通过query函数表可知，query.health会返回生物的生命值，而query.max_health会返回生物的最大生命值。往常处理时，获取生物的血量需要通过服务端获取，而使用GetMolangValue接口可以在客户端获取生物的血量信息。我们在这里更新血量的数值和进度条的裁切程度。
+
+![](./images/6_2.jpg)
+
+![](./images/6_3.jpg)
+
+
+
+而在客户端系统上，我们通过在UiInitFinish事件里，添加一个实例变量来确保从这之后开始，在AddEntityClientEvent事件里才能为其他实体生物绑定UI。在RemoveEntityClientEvent里移除UI。