2.6

docs/mconline/15-玩法组件教程/12-开始自定义方块实体/0-摘要.md

@@ -0,0 +1,16 @@
+---
+front: https://nie.res.netease.com/r/pic/20211104/69055361-2e7a-452f-8b1a-f23e1262a03a.jpg
+hard: 入门
+time: 5分钟
+---
+
+# 摘要
+
+在本章中，我们将一起学习**方块实体**（**Block Entity**，又称**Tile Entity**）的制作，了解这种强大且实用的功能，使我们的自定义方块具有更加丰富的特性。
+
+- 在第一节（*了解方块实体*）中，我们将一起了解什么是方块实体，了解方块实体存在的必要性和使用方法。
+- 在第二节（*了解方块实体外观*）中，我们将接触方块实体的外观，了解方块实体是如何拥有自定义外观的。
+- 在第三节（*制作一个加速火把*）中，我们将一起制作一个演示用的加速火把，利用模组SDK为方块实体添加功能。
+- 在最后一节（*挑战：制作一个自定义箱子（无法储藏版）*）中，我们将一起进行一个挑战，制作一个不具备储物界面的仅具备外观的箱子。
+
+本章关键词：方块实体 方块状态 附加值 置换 滴答 额外数据 加速火把 箱子

docs/mconline/15-玩法组件教程/12-开始自定义方块实体/1-了解方块实体.md

@@ -0,0 +1,50 @@
+---
+front: https://nie.res.netease.com/r/pic/20211104/69055361-2e7a-452f-8b1a-f23e1262a03a.jpg
+hard: 高级
+time: 20分钟
+---
+
+# 了解方块实体
+
+在第十章中，我们曾一起了解了自定义方块，通过各种示例学会了如何自定义一个基本方块。其中，我们学会了如何给予一个方块自定义模型，也学会了如何使用各种组件控制方块的行为。但是，通过这种方式定义的方块还有着种种不足。这是因为普通的方块存在一些固有缺陷。
+
+众所周知，普通的方块或者说是常规的方块都是以如下这些机制在世界中运作的。首先，方块具备各种**方块状态**（**Block State**），而每种方块状态拥有一个或多个允许的值，世界中每一个该类型的方块都是所有方块状态各赋予一个允许值中的值产生的。换句话说，世界中每种方块的实例都是其方块状态的排列组合。在旧版中，我们知道方块具有一种被称为特殊值、数据值、损坏值或**附加值**（**Aux Value**）的属性，这其实是和现在的方块状态系统等价的。每种附加值都对应一种方块状态的组合。各方块状态的一种组合称为方块的一个**置换**（或**排列**，**Permutation**）。这种由方块状态组成方块置换的模式只能存储布尔值或整数等基本值的组合，却无法将字符串等更高级的值存储在一个方块中，因此具备存储上的局限性。比如，如果我想将一个物品标识符存储在一个方块中，这只靠常规方块的定义是做不到的。
+
+第二种机制是方块滴答机制。这里的**滴答**（**Tick**）可以大致理解为更新，但实际上指的是一种可以随着游戏的系统主滴答循环的有序推进而进行的一种更新。常规的方块都无法保证自己的每游戏刻（即每次系统主滴答循环）都能滴答。液体方块的两个方块中动态的那一个是例外，但是即使是例外，也不能长期地保证每刻的更新性，那是因为动态液体一旦停止流动，它将转换为静态液体。常规的方块只有在自己的**毗邻**（**Neighbor**）发生变化或者发生**随机滴答**（**Random Tick**，又称**随机刻**）事件时才能进行一次滴答或将自身加入**挂起滴答队列**（**Pending Tick Queue**）中，用社区的说法为进入了**计划刻**。而计划刻内的方块会在每次系统主滴答循环顺序中的指定时刻位置处集中进行滴答，这是一种性能缓冲机制。总而言之，常规方块几乎不可以“自主地”进行滴答或更新，也无法侦测到除了自身毗邻之外的其他方块或实体发生的变化。这是常规方块的一个重大缺陷。
+
+第三种缺陷就是无法像实体那样使模型播放动画。常规定义的方块的模型几乎都是静态的，定义之后便不会再进行变动，至多存在随着方块状态的改变稍微改变一下模型的朝向或部分骨骼的显示等，但无法完成复杂的动画。为了使模型具备动画，我们必须另寻高法。
+
+所以，和附着物与物品的关系类似，我们拥有了一种可以将客户端实体作为一种“资源控制器”的容器挂接到方块上的功能，这种挂接到方块上的仅仅具备客户端实体定义的实体便被称为**方块实体**（**Block Entity**，又称**Tile Entity**）。方块实体可以帮助我们存储大规模数据、自主地进行滴答和播放模型动画。原版游戏中的箱子、告示牌、熔炉、信标、附魔台、床、钟、活塞臂等都具备方块实体。
+
+## 定义方块实体
+
+了解了这么多理论机制，我们如何实际定义一个方块实体呢？我们可以在方块的服务端定义文件中通过`netease:block_entity`组件定义方块实体。我们在编辑器中新建一个方块，并在服务端组件中添加“**方块实体**”组件。
+
+![](./images/13.1_block_entity_component.png)
+
+我们可以看到其对应的JSON组件字段
+
+```json
+"netease:block_entity": {
+  "tick": true,
+  "movable": false
+}
+```
+
+`tick`字段决定了方块实体是否会每刻向脚本发送一个`ServerBlockEntityTickEvent`事件，通过配合脚本可以做到每刻执行滴答逻辑。`movable`字段决定了该方块是否可以被粘性活塞拉回。
+
+一旦定义好了`netease:block_entity`组件，一个方块便算是拥有了一个基础的方块实体。接下来，我们就需要配合模组SDK来添加方块实体的逻辑了。
+
+## 连接模组SDK
+
+我们可以在模组SDK中通过一系列接口操纵方块实体。
+
+### 引擎组件
+
+我们可以通过在服务端创建`blockEntityData`组件来修改方块实体的**额外数据**（**Extra Data**）。额外数据是中国版自定义方块实体的一个存储器，存储着开发者可以自定义的各种数据。我们可以通过该组件的<a href="../../../mcdocs/1-ModAPI/接口/方块/方块实体.html#getblockentitydata" rel="noopenner"> `GetBlockEntityData` </a>方法得到额外数据的引用，然后直接读取额外数据或在这个引用上修改额外数据的值。
+
+### 事件
+
+<a href="../../../mcdocs/1-ModAPI/事件/方块.html#serverplaceblockentityevent" rel="noopenner"> `ServerPlaceBlockEntityEvent` </a>事件可以用于在方块实体被放置时触发。<a href="../../../mcdocs/1-ModAPI/事件/世界.html#chunkgeneratedserverevent" rel="noopenner"> `ChunkGeneratedServerEvent` </a>事件可以在区块结束生成是触发，数据中包含一个方块实体列表。<a href="../../../mcdocs/1-ModAPI/事件/方块.html#serverblockentitytickevent" rel="noopenner"> `ServerBlockEntityTickEvent` </a>事件可以在开启了每刻滴答的方块实体进行滴答时触发。这三个事件都位于服务端。
+
+在文档中还有更多的方块实体相关的模组SDK接口等待我们发现和使用。有效利用各种接口将使我们的方块实体拥有各种丰富的逻辑与功能！

docs/mconline/15-玩法组件教程/12-开始自定义方块实体/2-了解方块实体外观.md

@@ -0,0 +1,60 @@
+---
+front: https://nie.res.netease.com/r/pic/20211104/69055361-2e7a-452f-8b1a-f23e1262a03a.jpg
+hard: 高级
+time: 15分钟
+---
+
+# 了解方块实体外观
+
+在行为包定义了方块实体的组件之后，我们还可以在客户端定义方块实体所使用的客户端实体。
+
+## 定义实体及其外观
+
+我们像第八章中讲的实体那样制作一个客户端实体定义文件，包括实体的各种资源，然后将其准备在资源包中。为了让实体挂接在方块实体上，我们需要修改资源包根目录下的`blocks.json`文件。
+
+```json
+{
+  "format_version": [ 1, 1, 0 ],
+  ///...
+  "customblocks:custom_block_entity": {
+    "sound": "grass",
+     // 可与netease_model字段一起使用，定义方块的方块模型
+    "netease_model": "customblocks:customblocks_model_decoration",
+     // --- 实体模型配置 ---
+     // 这个方块实体将会使用到实体模型
+    "client_entity": {
+       // 对应custom_block_entity.entity.json里面的identifier
+      "identifier": "customblocks:custom_block_entity",
+       // 这个方块实体的手持模型或掉落时模型是否使用该实体模型。
+      "hand_model_use_client_entity": true,
+       // 这个方块实体的物品icon贴图
+      "block_icon": "test_block_icon",
+       // 方块实体被破坏时使用的贴图
+      "destoryed_textures":"destroy_entity"
+    },
+  },
+  ///...
+}
+```
+
+这是一个示例的方块实体的实体挂接定义。我们可以看到，`client_entity`字段将负责将实体挂接到方块上。
+
+- `identifier`：字符串，实体的标识符，需要与实体的客户端定义中标识符相一致。
+- `hand_model_use_client_entity`：可选，布尔值，玩家的手持模型和该方块的掉落物模型是否适用实体的模型，若为`false`，则仅仅在方块被放置在世界中时使用实体的模型，其余情况（手持和掉落物）使用`netease_model`定义的模型或原版的方块形状。
+- `block_icon`：可选，字符串，方块在物品栏中作为物品时的图标纹理的短名称。事实上，由于游戏机制，物品的图标并不能渲染一个实体，因而对于方块来说只能渲染一个平面图标、按照微软方块形状渲染或按照自定义的方块模型渲染。如果这里没有定义，则会自动渲染`netease_model`定义的方块模型或原版方块形状作为图标。短名称在资源包的纹理图集定义文件`textures/terrain_texture.json`中定义。
+- `destoryed_textures`：可选，字符串，方块破坏粒子的纹理短名称。方块被破坏时会产生旧版粒子（介绍见第二章）中的`terrain`粒子，而`terrain`粒子会从方块的地形图集（定义见第十章）中指定UV处选取纹理作为其贴图。这里可以通过更改地形图集中的短名称来变相地指定产生的`terrain`粒子的纹理UV。若未定义，则自动依次检测`block_icon`字段中定义的纹理、`netease_model`字段中定义的模型中定义的纹理、`textures`字段中定义的纹理的存在性并使用最先检测到的那个。该字段的短名称也在资源包的纹理图集定义文件`textures/terrain_texture.json`中定义。
+
+至此，我们便定义好了方块实体对应的实体，而方块实体的包括模型在内的各种资源将交由该实体来进行控制，这样，我们便可以将我们的方块玩出更多的“花样”。
+
+## 连接模组SDK
+
+方块实体的服务端实体定义完成后，我们又多出了很多接口来对接这个实体。与上一节中的接口不同的是，针对于方块实体的实体部分的接口全都位于客户端。这也很容易理解，毕竟这是在代表客户端的资源包中定义的实体。
+
+| 接口                                                         | 所属端                                                   | 用处                                           |
+| ------------------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------- |
+| <a href="../../../mcdocs/1-ModAPI/接口/方块/渲染.html#setblockentitymodelposoffset" rel="noopenner"> `SetBlockEntityModelPosOffset` </a> | <span style="display:inline;color:#7575f9">客户端</span> | 设置自定义方块实体的实体模型的位置偏移。       |
+| <a href="../../../mcdocs/1-ModAPI/接口/方块/渲染.html#setblockentitymodelrotation" rel="noopenner"> `SetBlockEntityModelRotation` </a> | <span style="display:inline;color:#7575f9">客户端</span> | 设置自定义方块实体的实体模型在各个轴上的旋转。 |
+| <a href="../../../mcdocs/1-ModAPI/接口/方块/渲染.html#setblockentitymodelscale" rel="noopenner"> `SetBlockEntityModelScale` </a> | <span style="display:inline;color:#7575f9">客户端</span> | 设置自定义方块实体的实体模型的尺度。           |
+| <a href="../../../mcdocs/1-ModAPI/接口/方块/渲染.html#setenableblockentityanimations" rel="noopenner"> `SetEnableBlockEntityAnimations` </a> | <span style="display:inline;color:#7575f9">客户端</span> | 设置是否开启自定义方块实体的动画。             |
+| <a href="../../../mcdocs/1-ModAPI/接口/方块/渲染.html#setblockentitymolangvalue" rel="noopenner"> `SetBlockEntityMolangValue` </a> | <span style="display:inline;color:#7575f9">客户端</span> | 设置自定义方块实体的Molang变量的值。           |
+| <a href="../../../mcdocs/1-ModAPI/接口/方块/渲染.html#getblockentitymolangvalue" rel="noopenner"> `GetBlockEntityMolangValue` </a> | <span style="display:inline;color:#7575f9">客户端</span> | 获取自定义方块实体的Molang变量的值。           |

docs/mconline/15-玩法组件教程/12-开始自定义方块实体/3-制作一个加速火把.md

@@ -0,0 +1,225 @@
+---
+front: https://nie.res.netease.com/r/pic/20211104/69055361-2e7a-452f-8b1a-f23e1262a03a.jpg
+hard: 进阶
+time: 35分钟
+---
+
+# 制作一个加速火把
+
+本节中，我们将通过制作一个加速火把的过程来学习方块实体方块的制作。
+
+## 使用Blockbench准备火把模型
+
+我们的加速火把不需要骨骼动画或资源控制，只需要一个静态的火把模型即可。所以我们在Blockbench中绘制一个火把模型。
+
+![](./images/13.3_torch.png)
+
+## 使用编辑器导入模型并配置火把方块
+
+![](./images/13.3_torch_import.png)
+
+我们在编辑器中使用导入方块模型的功能导入我们的火把模型。
+
+![](./images/13.3_torch_model_set.png)
+
+然后新建一个火把方块，在“基础属性”中配置模型，这等价于我们在`blocks.json`中配置`netease_model`字段。
+
+![](./images/13.3_torch_component_set.png)
+
+然后为我们的火把加上“方块实体”的组件。与此同时，我们为了使火把正常渲染，将其调整为可寻路、透明材质和非固体，同时设置好其碰撞箱。
+
+我们也可以在JSON文件中进行编辑。方块的服务端定义如下：
+
+```json
+{
+  "format_version": "1.16.0",
+  "minecraft:block": {
+    "description": {
+      "identifier": "design:custom_torch"
+    },
+    "components": {
+      "minecraft:block_light_absorption": 0,
+      "minecraft:block_light_emission": 1.0,
+      "minecraft:destroy_time": 1.0,
+      "netease:render_layer": {
+        "value": "alpha"
+      },
+      "netease:aabb": {
+        "collision": {
+          "min": [0.4375, 0.0, 0.4375],
+          "max": [0.5625, 0.6875, 0.5625]
+        },
+        "clip": {
+          "min": [0.4375, 0.0, 0.4375],
+          "max": [0.5625, 0.6875, 0.5625]
+        }
+      },
+      "netease:solid": {
+        "value": false
+      },
+      "netease:pathable": {
+        "value": true
+      },
+      "netease:block_entity": {
+        "tick": true,
+        "movable": false
+      }
+    }
+  }
+}
+```
+
+客户端定义如下：
+
+```json
+{
+  "format_version": [ 1, 1, 0 ],
+  "design:custom_torch": {
+    "netease_model": "design:custom_torch",
+    "sound": "wood"
+  }
+}
+```
+
+同时我们也可以查看已经导入的火把模型文件：
+
+```json
+{
+  "format_version": "1.13.0",
+  "netease:block_geometry": {
+    "description": {
+      "identifier": "design:custom_torch",
+      "textures": ["torch_on"],
+      "use_ao": false
+    },
+    "bones": [{
+      "name": "root",
+      "pivot": [0, 0, 0],
+      "rotation": [0, 0, 0],
+      "cubes": [{
+        "origin": [-9, 0, 7],
+        "pivot": [-8, 0, 8],
+        "rotation": [0, 0, 0],
+        "size": [2, 11, 2],
+        "uv": {
+          "down": {
+            "texture": 0,
+            "uv": [7, 14],
+            "uv_size": [2, 2]
+          },
+          "east": {
+            "texture": 0,
+            "uv": [7, 6],
+            "uv_size": [2, 10]
+          },
+          "north": {
+            "texture": 0,
+            "uv": [7, 6],
+            "uv_size": [2, 10]
+          },
+          "south": {
+            "texture": 0,
+            "uv": [7, 6],
+            "uv_size": [2, 10]
+          },
+          "up": {
+            "texture": 0,
+            "uv": [9, 8],
+            "uv_size": [-2, -2]
+          },
+          "west": {
+            "texture": 0,
+            "uv": [7, 6],
+            "uv_size": [2, 10]
+          }
+        }
+      }]
+    }]
+  }
+}
+```
+
+## 监听事件并催熟作物
+
+接下来我们制作脚本部分。我们可以通过`ServerBlockEntityTickEvent`事件来监听滴答。我们通过编辑器在行为包中创建一个主模组目录和一个服务端控制中心，并在主模组文件中注册服务端系统：
+
+```python
+# -*- coding: UTF-8 -*-
+from mod.common.mod import Mod
+import mod.server.extraServerApi as serverApi
+
+
+@Mod.Binding(name="CustomTorch", version="0.1")
+class CustomTorch(object):
+
+    def __init__(self):
+        pass
+
+    @Mod.InitClient()
+    def initClient(self):
+        pass
+
+    @Mod.InitServer()
+    def initServer(self):
+        serverApi.RegisterSystem("CustomTorch", "CustomTorchServer", "CustomTorchScripts.ServerMgr.Main")
+
+    @Mod.DestroyClient()
+    def destroyClient(self):
+        pass
+
+    @Mod.DestroyServer()
+    def destroyServer(self):
+        pass
+
+```
+
+然后我们在`ServerMgr.py`文件中写入服务端系统：
+
+```python
+# -*- coding: UTF-8 -*-
+from mod.server.system.serverSystem import ServerSystem
+import mod.server.extraServerApi as serverApi
+
+
+class Main(ServerSystem):
+
+    def __init__(self, namespace, system_name):
+        ServerSystem.__init__(self, namespace, system_name)
+        namespace, system = serverApi.GetEngineNamespace(), serverApi.GetEngineSystemName()
+        self.ListenForEvent(namespace, system, "ServerBlockEntityTickEvent", self, self.on_torch_grow)  # 监听ServerBlockEntityTickEvent事件
+
+    def on_torch_grow(self, event):
+        x = event['posX']  # 获取坐标X
+        y = event['posY']  # 获取坐标Y
+        z = event['posZ']  # 获取坐标Z
+        dim_id = event['dimension']  # 获取维度ID
+        block_comp = serverApi.GetEngineCompFactory().CreateBlockInfo(serverApi.GetLevelId())
+        block_state_comp = serverApi.GetEngineCompFactory().CreateBlockState(serverApi.GetLevelId())
+        block_entity_comp = serverApi.GetEngineCompFactory().CreateBlockEntityData(serverApi.GetLevelId())
+        block_entity_data = block_entity_comp.GetBlockEntityData(dim_id, (x, y, z))  # 获取方块数据
+        tick = block_entity_data['tick']  # 获取方块滴答次数
+        if not tick:
+            tick = 0  # 如果额外数据中没有tick属性便创建tick的值
+        tick += 1  # 加速火把方块会在每一刻自增一次滴答次数
+        block_entity_data['tick'] = tick  # 应用回tick属性
+        if tick % 20 != 0:  # 1秒=20刻，当刷新次数与20求模为0时，即过了一秒钟
+            return
+        # 运用列表推导式，获得[(x - 1, y, z - 1), (x, y, z - 1), (x + 1, y, z - 1), (x + 1, y, z + 1), (x, y, z),
+        # (x - 1, y, z + 1), (x, y, z + 1), (x - 1, y, z), (x + 1, y, z)]的坐标列表
+        grow_poses = [(x + x_offset, y, z + z_offset) for x_offset in xrange(-1, 2) for z_offset in xrange(-1, 2)]
+        grow_poses.remove((x, y, z))  # 由于坐标(x, y, z)是加速火把，所以移除这个坐标
+        for grow_pos in grow_poses:
+            block = block_comp.GetBlockNew(grow_pos, dim_id)
+            if block and block['name'] == 'minecraft:wheat':  # 如果是小麦
+                block_state = block_state_comp.GetBlockStates(grow_pos, dim_id)
+                if block_state['growth'] < 7:  # 且小麦还未成熟，即成长值小于7
+                    block_state['growth'] += 1  # 增加一级成长值
+                    block_state_comp.SetBlockStates(grow_pos, block_state, dim_id)
+
+```
+
+这样，我们便完成了可以为小麦加速的加速火把的制作，每秒将为小麦加速一个成长阶段。我们进入游戏查看效果。
+
+![](./images/13.3_in-game.gif)
+
+可以看到，我们的加速火把如期加速了周围的小麦！