方块模型 26.1.2

一篇编写和理解方块模型的指南。

本页将指导你编写自己的方块模型并了解其所有选项和可能性。

什么是方块模型？

方块模型本质上是对方块外观和视觉效果的定义。 其指定了纹理、模型平移、旋转、缩放和其他属性。

模型以 JSON 文件的形式存储在你的 resources 文件夹中。

文件结构

每个方块模型文件都有一个必须遵循的定义结构。 它以空的花括号开头，代表模型的根标签。 以下是方块模型结构的简要示意：

{
  "parent": "...",
  "ambientocclusion": "true/false",
  "display": {
    "<position>": {
      "rotation": [0.0, 0.0, 0.0],
      "translation": [0.0, 0.0, 0.0],
      "scale": [0.0, 0.0, 0.0]
    }
  },
  "textures": {
    "particle": "...",
    "<texture_variable>": "..."
  },
  "elements": [
    {
      "from": [0.0, 0.0, 0.0],
      "to": [0.0, 0.0, 0.0],
      "rotation": {
        "origin": [0.0, 0.0, 0.0],
        "axis": "...",
        "angle": "...",
        "rescale": "true/false"
      },
      "shade": "true/false",
      "light_emission": "...",
      "faces": {
        "<key>": {
          "uv": [0, 0, 0, 0],
          "texture": "...",
          "cullface": "...",
          "rotation": "...",
          "tintindex": "..."
        }
      }
    }
  ]
}

父级

{
  "parent": "..."
}

从给定路径加载一个包含所有属性的不同模型，并以标识符（namespace:path）的形式加载。

将此标签设置为 builtin/generated 以使用从指定图标创建的模型。 旋转可以通过方块状态实现。

环境光遮蔽

{
  "ambientocclusion": "true/false"
}

此标签指定是否使用环境光遮蔽。 默认为 true。

显示

{
  "display": {
    "<position>": {
      "rotation": [0.0, 0.0, 0.0],
      "translation": [0.0, 0.0, 0.0],
      "scale": [0.0, 0.0, 0.0]
    }
  }
}

此标签负责设置模型在指定位置的平移、旋转和缩放。

位置对象可以是以下字符串之一，用于定义模型在不同位置的外观：

值	说明
firstperson_righthand	右手，以第一人称视角
firstperson_lefthand	左手，以第一人称视角
thirdperson_righthand	右手，以第三人称视角（F5）
thirdperson_lefthand	左手，以第三人称视角（F5）
gui	在 GUI 中，例如物品栏
head	戴在玩家头上，例如旗帜
ground	在地面上
fixed	放在物品展示框中

此外，每个位置可以包含以下三个值，以浮点数组的形式：

{
  "rotation": [0.0, 0.0, 0.0],
  "translation": [0.0, 0.0, 0.0],
  "scale": [0.0, 0.0, 0.0]
}

1. rotation：三个浮点数。 根据方案 [x, y, z] 指定模型的旋转。
2. translation：三个浮点数。 根据 [x, y, z] 格式指定模型的平移。 该值必须介于 -80 到 80 之间；超出此范围的值将被设为最接近的极值。
3. scale：三个浮点数。 根据 [x, y, z] 格式指定模型的缩放。 最大值为 4，更大的值将被视为 4。

纹理

{
  "textures": {
    "particle": "...",
    "<texture_variable>": "..."
  }
}

textures 标签以标识符或纹理变量的形式保存模型的纹理。 它包含三个附加对象：

1. particle：字符串。 定义从中加载粒子的纹理。 此纹理也会用作站在下界传送门中时的叠加层，也用于水和熔岩的静态纹理。 它也被视为一个纹理变量，可以引用为 #particle。
2. <texture_variable>：字符串。 创建一个变量并分配一个纹理。 稍后可以使用 # 前缀引用（例如 "top": "namespace:path" ⇒ #top）。

元素

{
  "elements": [
    {
      "from": [0.0, 0.0, 0.0],
      "to": [0.0, 0.0, 0.0],
      "rotation": {
        "origin": [0.0, 0.0, 0.0],
        "axis": "...",
        "angle": "...",
        "rescale": "true/false"
      },
      "shade": "true/false",
      "light_emission": "...",
      "faces": {
        "<face>": {
          "uv": [0, 0, 0, 0],
          "texture": "...",
          "cullface": "...",
          "rotation": "...",
          "tintindex": "..."
        }
      }
    }
  ]
}

包含模型的所有元素，且只能是立方体。 如果同时设置了 parent 和 elements 标签，则该文件的 elements 标签将覆盖父级的 elements 标签。

{
  "from": [0.0, 0.0, 0.0],
  "to": [0.0, 0.0, 0.0]
}

from 指定长方体的起点，按照 [x, y, z] 格式，相对于左下角。 to 指定终点。 一个与标准方块大小相同的长方体将从 [0, 0, 0] 开始，到 [16, 16, 16] 结束。 两者的值都必须在 -16 到 32 之间，这意味着每个方块模型的最大尺寸为 3×3 方块。

{
  "rotation": {
    "origin": [0.0, 0.0, 0.0],
    "axis": "...",
    "angle": "...",
    "rescale": "true/false"
  }
}

rotation 定义元素的旋转。 其包含四个值：

1. origin：三个浮点数。 根据 [x, y, z] 格式设置旋转中心。
2. axis：字符串。 指定旋转方向，必须是以下值之一：x、y 或 z。
3. angle：浮点数。 指定旋转角度。 范围从 -45 到 45。
4. rescale：布尔值。 指定是否在整个方块上缩放面。 默认为 false。

{
  "shade": "true/false"
}

shade 定义是否渲染阴影。 默认为 true。

{
  "light_emission": "..."
}

light_emission 定义元素可以接收到的最小光照等级。 取值范围为 0 到 15。 默认为 0。

{
  "faces": {
    "<key>": {
      "uv": [0, 0, 0, 0],
      "texture": "...",
      "cullface": "...",
      "rotation": 0,
      "tintindex": 0
    }
  }
}

faces 保存长方体的所有面。 如果某个面未设置，则不会被渲染。 它的键（<key>）可以是以下之一：down、up、north、south、west 或 east。 每个键包含该面的属性：

1. uv：四个整数。 根据 [x1, y1, x2, y2] 格式定义要使用的纹理区域。 如果未设置，则默认为元素 xyz 位置的值。 翻转 x1 和 x2 的值（例如从 0, 0, 16, 16 到 16, 0, 0, 16）会翻转纹理。 UV 是可选的，如果未提供，则根据元素的位置自动生成。
2. texture：字符串。 以纹理变量的形式指定面的纹理，前缀为 #。
3. cullface：字符串。 可以为：down、up、north、south、west 或 east。 指定当在指定位置有方块接触该面时，该面是否不需要渲染。 它还决定使用方块的哪一侧的光照等级来照亮该面，如果未设置，则默认为该侧。
4. rotation：整数。 将纹理以 90 度为增量顺时针旋转指定的度数。 旋转不会影响纹理的使用部分。 而是相当于对所选纹理顶点（隐式选择或通过 uv 显式选择）进行置换。
5. tintidex：整数。 使用色调值对该面的纹理进行着色。 默认值 -1 表示不使用色调。 向 BlockColors 传入任何其他数字即可获取与该索引对应的色调值（当方块未定义色调索引时返回白色）。