---
front:
hard: 入门
time: 分钟
---

# 微缩方块

微缩方块用于将游戏内的若干区域的方块形状缩小成若干个单个小方块进行显示，目前游戏内仅开放预微缩方块。

1. 预微缩方块，通过使用 modsdk 接口生成对应的微缩方块信息并由开发者保存为微缩方块文件，然后将该文件放入到 mod 中，重进游戏后，微缩方块便类似于游戏的原生方块，可以在物品列表里找到并使用

## Demo 解释

MicroBlocksMod 定义了三个不同的微缩方块：

1. number_9，一个 2x2x2 大小的微缩方块，并附带图标
2. number_9_2，一个 1x1x1 大小的微缩方块
3. number_9_3，和 number_9_2 一样，只是修改了方块颜色。


## 预微缩方块注册

注意：以下文件都可以在 MicroBlocksMod 里找到

首先需要在 `MicroBlocksMod_behavior/netease_micro_blocks/` 文件夹下新建微缩方块信息，然后需要在 `MicroBlocksMod_resource/models/netease_micro_block/` 文件夹下新建微缩方块图像信息，这里我们以建立 number_9_2.json 为例：

1. 在 MicroBlocksMod_behavior/netease_micro_blocks/ 文件夹下新建 number_9_2.json 文件

2. 向 number_9_2.json 中写入如下信息，其中：

    - `identifier` 用于表示微缩方块的唯一标识，对于微缩方块来说，必须以 `micro_block:` 开头，否则游戏中无法识别为微缩方块，推荐 identifier 为 micro_block:命名空间_方块名。命名空间推荐与 mod 名称一致。而冒号后的方块名必须全局唯一，为避免与原版方块以及其他mod重复，请加上 命名空间_ 作为前缀来保证唯一。
    - `category` 用于控制微缩方块注册到的创造物品栏分类，通过设置为 `construction`，即可像原版方块一样在创造物品栏“建筑”找到。
    - `micro_size` 用于表示当前微缩方块占据的方格大小，例如 `"1 1 2"` 即表示该微缩方块占据 1x1x2 大小的方格（注：原版草方块占据 1x1x1 的方格大小），配置时必须为整数且中间需要使用空格分隔，注意目前微缩方块最大支持为 4x4x4 的大小，即使配置超过 4 也无法占据更多方格。
    - 注意：微缩方块不支持原版和网易版的json组件。

```
{
    "format_version": "1.13.0",
    "minecraft:block": {
        "description": {
            "identifier": "micro_block:number_9_2",
            "category": "construction",
            "micro_size": "1 1 1"
        },
        "components": {
        }
    }
}
```

3. 在 `MicroBlocksMod_resource/models/netease_micro_block/` 文件夹下新建 number_9_2.json 文件，文件的内容可以通过 `blockCompServer` 下的 `CreateMicroBlockResStr` 获取，其中函数的原型如下：

`CreateMicroBlockResStr(self, identifier, start, end, colorMap=None, isMerge=False, icon="")`

- identifier，str，微缩方块的唯一标识，由于会自动添加 `micro_block:`，所以这里只用填入 `x` 即可
- start，(int, int, int)，微缩的起始坐标，例如 (30, 65, 78)
- end，(int, int, int)，微缩的结束坐标，例如 (44, 77, 90)
- colorMap，Dict，用于指定某类型方块的微缩后的方块颜色，例如 colorMap={"minecraft:grass": [12, 12, 12, 255], "minecraft:stone": [12, 233, 24]}，会将所有符合类型的方块的颜色改变
- isMerge，Bool，用于标识是否合并同类型方块，（这样可以减少性能消耗）
- icon，str，用于指定微缩方块的 icon。注意 icon 并不能直接使用图标所在的相对路径，而是需要先将图标添加到 terrain_texture.json 中，然后引用图标的注册名称，具体使用方法可以参考 [自定义方块注册](https://mc.163.com/mcstudio/mc-dev/MCDocs/2-ModSDK%E6%A8%A1%E7%BB%84%E5%BC%80%E5%8F%91/03-%E8%87%AA%E5%AE%9A%E4%B9%89%E6%B8%B8%E6%88%8F%E5%86%85%E5%AE%B9/05-%E8%87%AA%E5%AE%9A%E4%B9%89%E6%96%B9%E5%9D%97/0-%E8%87%AA%E5%AE%9A%E4%B9%89%E6%96%B9%E5%9D%97%E6%A6%82%E8%BF%B0.html)

使用 `CreateMicroBlockResStr` 返回的结果的为字符串，需要开发者主动进行保存

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlock(levelId)
result = comp.CreateMicroBlockResStr("x", (12, 60, 12), (26, 76, 26), colorMap={'minecraft:grass': [12, 22, 123, 255]}, isMerge=True, icon="micro_block_datiangou")
with open("micro_block_x.json", "w+") as f:
    f.write(result)
#该例子中，方块将以 (12 60 12) 为起点，以 (26 76 26) 为终点进行微缩，最终微缩方块里所有草方块的颜色为 rgba(12,22,123,255)，实际显示颜色会依据环境光照微调，物品栏里的图标为 terrain_texture.json 里 micro_block_datiangou 对应的图片。
```

- 使用 start 和 end 选中的区域，仅仅会生成其中的方块数据（包括自定义方块），对于生物等实体数据并不会包含其中。当选中的区域没有被加载时，不会产生数据，当选中的区域包含已加载区域和未加载区域时，仅仅只会产生已加载区域的数据。
- 将 start 和 end 反向，渲染方向会相反。

## 微缩方块资源数据说明

下面来查看 MicroBlocksMod 里自带的 number_9_2 微缩方块资源数据

```
{
    "netease:micro_block": {
        "data": {
            "11": [[], [], [0, 0, 0, 1], [0, 0, 0, 1], [], [], [], [], [], [0, 0, 0, 1], [0, 0, 0, 1]],
            "10": [[], [], [0, 0, 0, 1], [], [], [], [], [], [], [], [0, 0, 0, 1]],
            "13": [[], [], [], [], [0, 0, 0, 1], [0, 0, 0, 1], [], [0, 0, 0, 1], [0, 0, 0, 1]],
            "12": [[], [], [], [0, 0, 0, 1], [0, 0, 0, 1], [], [], [], [0, 0, 0, 1], [0, 0, 0, 1]],
            "14": [[], [], [], [], [], [0, 0, 0, 1], [0, 0, 0, 1], [0, 0, 0, 2]],
            "1": [[], [], [], [], [], [0, 0, 0, 1], [0, 0, 0, 1], [0, 0, 0, 1]],
            "3": [[], [], [], [0, 0, 0, 1], [0, 0, 0, 1], [], [], [], [0, 0, 0, 1], [0, 0, 0, 1]],
            "2": [[], [], [], [], [0, 0, 0, 1], [0, 0, 0, 1], [], [0, 0, 0, 1], [0, 0, 0, 1]],
            "5": [[], [], [0, 0, 0, 1], [0, 0, 0, 1], [], [], [], [], [], [], [0, 0, 0, 1]],
            "4": [[], [], [0, 0, 0, 1], [0, 0, 0, 1], [], [], [], [], [], [0, 0, 0, 1], [0, 0, 0, 1]],
            "7": [[], [], [0, 0, 0, 1], [0, 0, 0, 1], [0, 0, 0, 1], [0, 0, 0, 1], [], [0, 0, 0, 1], [0, 0, 0, 1]],
            "6": [[], [], [0, 0, 0, 1], [0, 0, 0, 1], [], [0, 0, 0, 1], [0, 0, 0, 1], [0, 0, 0, 1]],
            "9": [[], [], [0, 0, 0, 1], [0, 0, 0, 1], [], [], [], [], [], [0, 0, 0, 1], [0, 0, 0, 1]],
            "8": [[], [], [0, 0, 0, 1], [0, 0, 0, 1], [0, 0, 0, 1], [], [], [], [0, 0, 0, 1], [0, 0, 0, 1]]
        },
        "description": {
            "identifier": "micro_block:number_9_2",
            "blocks": {
                "1": {
                    "aux": 0,
                    "name": "minecraft:grass",
                    "color": [254, 46, 45, 255]
                },
                "2": {
                    "aux": 1,
                    "name": "minecraft:grass",
                    "color": [254, 46, 45, 255]
                }
            }
            "icon": "",
            "size": [11, 15, 6]
        }
    },
    "format_version": "1.13.0"
}
```

对于一个基本的微缩方块资源数据来说，主要有 6 个需要专注的数据：

1. identifier，需要在 behavior 下有同样匹配的方块 identifier
2. icon，微缩方块所对应的图标
3. block_size，用于标识微缩方块渲染图形所占的大小，对于 1x1x1 的方格来说，其渲染大小为 [16, 16, 16]，即游戏会使用 16x16x16 的方块数据去渲染一个体积为游戏原生方格大小的微缩模型。 从游戏性能的角度，目前最大支持 [64, 64, 64]，即一个微缩方块集合所生成的最大范围为 `4*4*4` 的方格（注意这里的大小需要匹配 behavior 下的方块 micro_size）
4. blocks，该微缩方块所包含的所有方块信息，每个字符串序号对应的序号方块的信息
5. data，微缩方块具体的组成数据。
    - 对于 block_size 小于或等于 [16, 16, 16] 的数据来说（即整个模型只占用一个原版方块的位置），其 data 由单个字典组成，每个字典下的标识，例如数据中的 `"3"` 用于标识第三层的组成数据，然后对应 `"3"` 的数据来说，依次为从北向南的每排渲染数据，对于具体到某一排的数据来说，依次会从东向西进行渲染。渲染数据中，用 0 表示空气方块，代表这里并没有任何方块，1 表示这里为 "blocks" 里的第一个方块，依此类推。
    - 对于 block_size 大于 [16, 16, 16] 的数据来说，即包含较多的微缩方块，例如为 [32, 32, 32] 的数据（模型需要占用 `(32 / 16) x (32 / 16) x (32 / 16) = 8` 格），data 下的数据由一个列表组成，分别对应以 `x + z*x + y*z*x` 为序的列表数据。
6. light_factor，默认值 [1.0, 1.0, 1.0, 1.0, 1.0, 1.0]，每个值的范围为 0 ~ 1.0，用于调整微缩方块各个面的光照强度

注意：对于 PE 端来说，如果微缩方块的数据过大，会导致游戏的初始加载时间延长，如果包含的微缩方块过多，且每个数据都特别大，会导致游戏初始加载时间大大延长。