MI文档——自动化GUI绘制

介绍

  现代工业 中包含了很多的通用 API，这篇文章就详细介绍一下其中的自动化 GUI 绘制 API——graphics包的用法及工作原理。

  这套系统的主要目的是免去手动绘制GUI材质以及手动定位控件坐标的流程，使用代码在运行期计算控件的位置。

  系统的设计过程中参考了html + css + js，最终效果是通过一个pug文件、一个stylus文件即可构建出一个基本的 GUI 图像，然后再使用代码加以支持，即可实现完整的功能。

结构文件

  我们使用一个pug文件来告诉代码一个 GUI 中包含哪些元素，这个文件应当放置在assets/[modid]/mi_files/gui/pugs内。

  pugs文件夹内分为两个文件夹：common和client，前者用于放置双端 GUI，后者用来放置客户端 GUI（客户端 GUI 就是无需服务端支持即可实现的 GUI，比如合成表查看器）。

  文件名将会被当作 GUI 的key（不用写modid），尽量让key由英文小写字母、下划线（或减号）及数字组成。

  声明元素的语法为：

1

tag#id.className1.className2(attributes)

  其中id、className、attributes均可省略不写，但是如果该控件需要进行网络通信，则必须为其设定一个唯一的id。

  attribute的格式为name=value，value可以使用双引号包围也可以不使用双引号包围，多个attribute用英文逗号分隔。

  attributes中我们允许填写布尔类型的值，大部分情况我们将属性存在记为true，不存在记为false。

  然后通过缩进来控制各个元素的包含关系，标准缩进为4个空格，当然为了照顾一些功能不太好的编辑器，也可以使用制表符\t来表达缩进，一个制表符解析为4个空格。

  下面我们给出一个例子：

1
2
3
4
5
6
7
8
9
10
11

mask
    background
        title(value="i18n:tile.mi.fluid_pump.name")
        div#show
            p
            progress#fluid
            p
            progress#energy
            p
            progress#consume
        button#switch

注意事项

• tag、className均仅允许包含下列字符：英文字母、-、阿拉伯数字
• tag的名称不能与已有的样式属性名重复
• attribute中不可包含英文逗号，如果确实需要包含，可以通过I18n或直接使用代码为其添加attribute

样式文件

  我们使用stylus文件来描述 GUI 样式，该文件应当放置在assets/[modid]/mi_files/gui/styles/文件夹内，且以key.styl命名（key不需要写modid）。

  API 并没有支持stylus的所有语法，我们仅支持如下语法：

1
2

元素选择器
  key value

  key和value可以通过空格或英文冒号分隔，不能使用冒号等其它符号，且行尾不能携带分号（除非是value本身有一个分号）。

  与pug不同，stylus使用2个空格表达缩进，一个制表符等价于4个空格。（当然你每一级都用4个空格也可以正常解析）

  元素选择器也是支持了一部分：

• 当我们通过tag选择元素时直接键入tagName即可
• 当我们通过id选择元素时则需要在id之前添加一个井号(#)
• 当我们通过className选择元素时需要在其前方添加一个英文句号(.)
  如果需要选择同时包含多个className的元素，可以通过.className1.className2的方式连接
• 可以使用*选定所有元素
• 如果需要选择被指定元素直接或间接包含的元素，使用空格分隔两个元素的选择器即可
• 可以使用英文逗号让两个选择器并列，并列的选择器可以分行书写，但所有选择器必须持有相同的缩进

  例如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

background
  width 180
  height 120
  padding-top 8

  button
    display inline
    width 20
    height 25
    margin-left 3
    
#show
  display inline
  margin-bottom 9
  align-x flex-start

  p
  div
    margin-top: 2
    margin-left: 2

元素空间

  我们将一个控件的空间从外到内分为以下三部分：margin、padding、content

  其中：

• 所有空间加起来的宽度（或高度）我们称之为spaceWidth（或spaceHeight）
• 除去margin的空间的宽度（或高度）我们称之为width（或height）
• content的宽度（或高度）我们称之为contentWidth（或contentHeight）

  为了行文方便，下文不再写出height，height和width是完全一致的。

  设置width时有三大类，分别是：父级依赖型、子级依赖型、非依赖型。

  顾名思义，父级依赖要求在计算其尺寸时父级元素的尺寸已经确定，当我们尝试计算一个父级依赖型控件的尺寸时会从该控件的直接父级控件开始向上搜索，通过第一个非子级依赖型的控件来计算当前控件的尺寸。

  子级依赖型和非依赖型均可直接计算得出控件尺寸，不需要链式搜索。

  我们可以通过width来定义一个控件的宽度，我们支持以下语法：

注：`number`和`percent`表示任意整正整数

  我们可以通过以下方式设置margin（仅允许使用固定值作为value）：

  padding的设置与margin相同，将margin改为padding即可。

框的类型

  我们可以使用display来修改框的类型，目前我们支持三种类型：

定位与排版

  我们可以使用positon来修改元素的定位方式，目前我们支持三种定位方式：

  我们可以使用align系列语句修改一个元素内子元素的排版方式，语法格式如下：

  vertical和horizontal支持的值有（下标以水平对齐为例进行说明，垂直方向上方对应水平的左侧，然后将元素改为行即可）：

  我们还可以通过以下语句修改元素的坐标，具体效果会因为定位方式的不同而有区别，在使用static定位时这四个值没有作用：

  当top、bottom被同时设置时，会忽略bottom的值，left和right被同时设置时，会忽略right的值。

颜色的表示

  当前支持以 10 进制或 16 进制的方式来描述颜色：

颜色相关设置

元素描边

  元素的描边会被绘制到元素内部，不会增加元素尺寸。元素的描边有两个可修改的参数：颜色和厚度。

元素裁剪

  可以使用overflow系列语句控制元素的裁剪方式：

  支持的裁剪方式有（默认为visible）：

• visible - 不裁剪，超出显示区域的内容正常渲染
• hidden - 裁剪，超出显示区域的内容隐藏
• scroll - 滚动，超出显示区域的内容滚动显示

  对于scroll属性，API 会在右侧或底部添加一个滚动条，垂直滚动条的宽度和水平滚动条的高度为 14。API 不支持通过 padding 调整滚动条的位置，滚动条固定在最左侧和最底部，使用 padding 会调整内部属性与滚动条的间距，该项设计与浏览器的行为不同，主要是为了方便实现与创造模式背包类似的异性滚动样式。如果需要调整滚动条位置，可以在元素外添加一个元素，通过这个元素进行调整。不过 API 不支持将滚动条放置在左侧或顶部。

按钮专有样式

  当将按钮设置为rect时direction会被忽略。

进度条专有样式

  进度条中的两个min值一般在绘制箭头形进度条时使用，用该值来控制箭头的矩形区域的尺寸。当进度条样式为矩形时这两个值用来控制长宽的最小值。

  当进度条长宽设置的不合理时，绘制可能会出现奇奇怪怪的效果。

注意事项

• 如果元素选择器用到了id，那么为了性能考虑，该选择器仅使用id即可，因为id是唯一的
• 尽量减少styl文件中的层级，以此提高性能
• 代码解析styl文件时没有进行严格的语法判断，所以有时候写错了也能正常解析，但不一定能得出正确的效果
• 每次加载styl文件后都会缓存解析结果，如果需要不关闭游戏重新解析可以使用/clear-mi-graphics指令（切换资源包自动清除缓存）
• stylus文件使用按需加载的方式，只有打开GUI时才会触发样式表加载，可以调用GuiStyleParser.load手动触发指定样式表的加载

API 支持的属性总览

  表中使用...省略同类方向异化的语句。

控件(标签)列表

  当一个控件需要进行网络交互时，我们必须为其分配一个id。这个网络交互操作可能是由控件本身发出的，也有可能是注册在控件之中的事件发出的。

半透明蒙版

  我们使用mask标签表示蒙版，对于该控件我们可以不指定控件的宽高，默认会以游戏窗体大小为控件宽高。

  默认的蒙版颜色为rgba(0 0 0 120)，可以通过修改样式表中的background-color属性来修改蒙版颜色。

GUI背景

  我们使用background标签表示GUI背景板。

  我们可以使用样式表的以下值控制GUI样式：

1. color - 控制背景板的填充色，默认rgb(198 198 198)
2. background-color - 控制背景板的背景色，默认black
3. border - 控制四个方向的阴影样式

GUI标题

  我们使用title标签表示 GUI 标题，对于该控件我们可以不指定控件的宽高和定位方式，API 会自动计算控件尺寸并将其定位到父元素顶部中心位置。

  标题内容存储在attributes的value项中，如果想要搭配I18n实现本地化可以让value的值以i18n:（不区分大小写，无空格间隔）开头，后跟key值即可。

  例如：

1
2

title(value = "这是一个普通的标题")
title(value = "i18n:key.simple")

1

key.simple=这是一个本地化的标题

玩家背包

  我们使用backpack标签表示玩家背包，对于该控件我们无需指定控件的宽度，API 会自动计算控件尺寸。

  允许为一个 GUI 添加多个玩家背包，但没必要。

  由于该控件需要进行网络交互，所以必须为该控件分配一个id。

进度条

  我们使用progress标签表示进度条，进度条目前支持且仅支持两种样式：箭头形和矩形。

  值得注意的是，当进度条样式为箭头形且长款不合理时，可能会绘制出奇怪的图案，箭头形一般采用15/22的比例。尽量让箭头指向的方向的宽度为奇数，否则绘制时三角形会变成一个梯形，后续也可能取消对非奇数的支持。

  进度条的数据存储在attributes中的value和max中，分别表示进度条的值与最大值（最大值可为 0）。

燃烧进度条

  我们使用burn标签表示燃烧进度条（就是熔炉里面那个火焰形状的进度条），该控件无需也不能设定长宽。

  进度条的数据存储在attributes中的value和max中，分别表示进度条的值与最大值（最大值可为 0）。

  与普通进度条不同的是，燃烧进度条的百分比计算是与普通进度条相反的，公式为：percent = 1 - (value / max)。

按钮

  我们使用button标签表示按钮，目前按钮支持且仅支持两种样式：矩形和三角形。

  当按钮样式为三角形时，要求三角形的底边长度必须为奇数，当其长度为偶数时在绘制过程中会将长度减一使其变为奇数。而三角形的高则没有要求，当三角形的高过大时会在三角形底边的下面绘制一个矩形进行补充。

  按钮上显示的文本存储在attributes中的value项中，当文本超过按钮显示范围时默认不会被截断。

文本显示

  我们使用p标签表示文本，对于该控件我们无需手动指定控件的宽高，API 会根据文本长度自动计算。

  控件显示的内容存储在attributes的value项中，如果想要搭配I18n实现本地化可以让value的值以i18n:（不区分大小写，无空格间隔）开头，后跟key值即可。

物品框

  我们使用slot标签表示物品框，该控件默认长宽为18*18。

  由于该控件需要进行网络交互，所以必须为其设定一个唯一的id。

  控件的信息存储在attributes中：

• index - 物品框在ItemStackHandler中的下标（默认0）
• priority - 物品框的优先级，数值越低优先级越高，当用户使用shift + 左键点击物品时，会优先将物品放入优先级高的物品框中（默认100）
• drop - 在关闭 GUI 时是否将物品框中的物品扔到世界中，不会清除ItemStackHandler中的数据（默认false）
• forbidInput - 是否禁止所有玩家向物品框放入物品（默认false）
• forbidOutput - 是否禁止所有玩家从物品框取出物品（默认false）

  同时还有一部分代码层控制的数据：

• handler - 物品框的ItemStackHandler对象，必须在GUI的初始化阶段完成对该值的初始化
• inputChecker - 检查指定物品是否能够放入物品框
• outputChecker - 检查指定物品能否被指定用户取出
• onSlotChanged - 当物品框内的物品被修改时触发（如果用户没有调用handler的onSlotChanged，则该方法不会触发）

输出物品框

  我们使用output标签表示输出物品框，该控件默认长宽为26*26。

  由于该控件需要进行网路交互，所以必须为其设定一个唯一的id。

  该控件是slot的特化版，除forbidInput为true以外没有其它区别。

物品矩阵

  我们使用matrix标签表示由若干个物品框组成的矩形矩阵。

  由于该控件需要进行网络交互，所以必须为其设定一个唯一的id。

  控件的信息存储在attributes中：

• index - 第一个物品框在ItemStackHandler中的下标（默认0）
• priority - 物品框的优先级（默认100）
• drop - 在关闭 GUI 时是否将物品框中的物品扔到世界中，不会清除ItemStackHandler中的数据（默认false）
• forbidInput - 是否禁止所有玩家向物品框放入物品（默认false）
• forbidOutput - 是否禁止所有玩家从物品框取出物品（默认false）
• xCount - X 轴方向上物品框的数量
• yCount - Y 轴方向上物品框的数量

  同时还有一部分代码层控制的逻辑：

• handler - 物品框的ItemStackHandler对象，必须在 GUI 的初始化阶段完成对该值的初始化
• inputChecker - 检查指定物品是否能够放入物品框
• outputChecker - 检查指定物品能否被指定用户取出
• onSlotChanged - 当物品框内的物品被修改时触发（如果用户没有调用handler的onSlotChanged，则该方法不会触发）

空盒子

  我们使用div标签表示一个空盒子，该控件被设计用于辅助排版。

代码层

  这里不会说明所有函数的用法，如果在这里没有找到用法说明这个函数的功能应该相当简单，以至于只需注释即可明确其所有功能。如果你看了注释仍然不能理解函数的功能或者运作细节，请在评论区说明你的问题。

事件系统

  GUI 的运作离不开事件，不然很难实现按钮点击等功能。

事件基础

  我们通过Cmpt#addEventListener来为控件注册一个事件，函数原型如下：

1

fun addEventListener(name: String, listener: IGraphicsListener<*>)

  第一个字符串类型的参数表示事件名称，API自身支持的所有事件可在IGraphicsListener类中查看；第二个参数用来表示事件的执行体。

  注意：任何事件都应在客户端服务端按照相同顺序注册，除非你保证这个控件的所有事件都不需要进行双端通信！！！

  我们通过Cmpt#dispatchEvent来发布事件，函数原型如下：

1

fun dispatchEvent(name: String, message: ListenerData)

  其中第一个参数仍是事件名称，第二个参数表示触发事件时传递的信息，不同事件需求的信息类型不同，ListenerData类的具体内容我们后面再详细说明。

  所有 API 内置的事件都会自动触发，用户无需手动触发，只有当用户希望模拟事件的触发或者自行编写事件时需要手动发布事件。

  我们通过Cmpt#removeEventListener来删除指定事件，函数原型如下：

1

fun removeEventListener(name: String, listener: IGraphicsListener<*>)

  参数含义与addEventListener相同，不再赘述。

事件的传递

  与事件有关的数据均存储在ListenerData中，所有ListenerData均存有以下数据：

• canCancel(Boolean) - 表示事件能否被取消
• reverse(Boolean) - 是否反转事件的触发顺序（这个值下文详细说明）
• prohibitTransfer(Boolean) - 是否禁止事件的传递
• target(Cmpt) - 触发该事件的控件对象
• cancel(Boolean) - 是否取消事件（当canCancel为false时该项无效）
• send2Service(Boolean) - 是否将事件的触发信息发送到服务端（默认为false，设为true时触发事件的控件必须持有唯一的id）

  假设我们有如下结构的树：

1
2
3
4

mask
    background
        button#button
            div

  当button控件触发鼠标点击事件时会先后触发button、background、mask的鼠标点击事件，而如果我们将reverse设置为true就会按照mask、background、button的顺序触发事件。

  不难发现，事件的传递遵循仅向父节点传递的原则。同时如果是客户端发送到服务端的事件触发信息，那么prohibitTransfer一定为true，即不进行任何形式的传递。如果需要在服务端进行事件传递就必须手写网络通信。

事件的触发

  这时候就到IGraphicsListener登场的时候了，当我们创建一个IGraphicsListener对象时仅需重写其中的active函数。

  active函数原型如下：

1
2

// T : ListenerData
fun active(`data`: T?)

  可以发现传入的值为可空类型，当事件是在服务端触发时，传入的值将会为null，因为 API 内置的事件网络通信仅传递事件的触发信息而不传送事件的具体数据。

控件对象

  所有控件都分为服务端对象和客户端对象，所有服务端类都从抽象类Cmpt派生，所有客户端类都从接口ICmptClient派生。

服务端

  一个服务端对象内部仅存储与服务端相关的数据（attributes除外）：

• 控件的节点信息（父节点、子节点）
• 控件注册的事件列表
• 控件的id

  API 不会自动同步双端attributes中的数据（部分控件会同步部分数据），因为大多数情况服务端获取attribute并没有什么用处。

  我们可以通过BaseGraphics或Cmpt中的以下函数获取其中的控件对象：

• getElementByID - 通过 ID 获取对象
• queryCmpt - 获取与表达式匹配的第一个控件
• queryCmptAll - 获取所有与表达式匹配的控件
• queryCmptLimit - 获取小于等于数量限制的数量的与表达式匹配的控件

  注：上述表达式与stylus中的表达式格式与功能相同。

客户端

  客户端对象存储以下数据：

• 服务端存储的所有数据
• 样式表

打开GUI

  我们编写了几个拓展函数用于打开或关闭GUI：

1
2
3

fun EntityPlayer.openGui(key: ResourceLocation, x: Int, y: Int, z: Int)
fun EntityPlayer.openClientGui(key: ResourceLocation, x: Int, y: Int, z: Int)
fun EntityPlayer.closeClientGui(): Boolean

  其中的key就是GUI的key，注意需要加上modid，坐标是最终传入GUI中的坐标，一般该坐标用来指代触发该GUI的方块的坐标。

  上面的两个关于客户端GUI的函数在服务端调用均不会有任何效果且不会产生报错。