跳到主要内容
版本：1.21.5

模型(Models)

模型(Models)是确定方块或物品视觉形状和纹理的JSON文件。模型由立方体元素组成，每个元素都有自己的大小，然后为每个面分配纹理。

物品使用由其客户端物品(client item)定义的关联模型，而方块使用方块状态文件(blockstate file)中的关联模型。这些位置相对于models目录，因此名为examplemod:item/example_model引用的模型将由assets/examplemod/models/item/example_model.json处的JSON定义。

规范​

另请参阅：Minecraft Wiki上的模型(Model)

模型是一个JSON文件，根标签中具有以下可选属性：

  • loader: NeoForge添加。设置自定义模型加载器。有关更多信息，请参阅模型加载器(Model Loaders)。
  • parent: 设置父模型，形式为相对于models文件夹的资源位置(resource location)。所有父属性将被应用，然后由声明模型中设置的属性覆盖。常见的父模型包括：
    • minecraft:block/block: 所有方块模型的公共父模型。
    • minecraft:block/cube: 使用1x1x1立方体模型的所有模型的父模型。
    • minecraft:block/cube_all: 立方体模型的变体，在所有六个面上使用相同的纹理，例如圆石或木板。
    • minecraft:block/cube_bottom_top: 立方体模型的变体，在所有四个水平面上使用相同的纹理，顶部和底部使用单独的纹理。常见示例包括砂岩或錾制石英。
    • minecraft:block/cube_column: 立方体模型的变体，具有侧面纹理和底部及顶部纹理。示例包括原木，以及石英和紫珀柱。
    • minecraft:block/cross: 使用两个具有相同纹理的平面的模型，一个顺时针旋转45°，另一个逆时针旋转45°，从上方看时形成X形（因此得名）。示例包括大多数植物，例如草、树苗和花。
    • minecraft:item/generated: 经典2D平面物品模型的父模型。被游戏中的大多数物品使用。忽略elements块，因为其四边形是从纹理生成的。
    • minecraft:item/handheld: 看起来实际上由玩家持有的2D平面物品模型的父模型。主要用于工具。item/generated的子模型，这也导致它忽略elements块。
    • 方块物品通常（但不总是）使用其相应的方块模型作为其物品模型(item model)。例如，圆石客户端物品使用minecraft:block/cobblestone模型。
  • ambientocclusion: 是否启用环境光遮蔽(ambient occlusion)。仅对方块模型有效。默认为true。如果你的自定义方块模型有奇怪的阴影，尝试将其设置为false。
  • render_type: NeoForge添加。设置要使用的渲染类型。有关更多信息，请参阅渲染类型(Render Types)。
  • gui_light: 可以是"front"或"side"。如果是"front"，光将从前面来，适用于平面2D模型。如果是"side"，光将从侧面来，适用于3D模型（尤其是方块模型）。默认为"side"。仅对物品模型有效。
  • textures: 将名称（称为纹理变量）映射到纹理位置(texture locations)的子对象。纹理变量然后可以在[元素(elements)]中使用。它们也可以在元素中指定，但留空以便子模型指定它们。
    • 方块模型应额外指定particle纹理。此纹理在方块掉落、跑过或破坏时使用。
    • 物品模型也可以使用层纹理，命名为layer0、layer1等，其中索引较高的层渲染在索引较低的层之上（例如，layer1将渲染在layer0之上）。仅当父模型是item/generated时有效，并且最多只适用于5层（layer0到layer4）。
  • elements: 立方体[元素(elements)]的列表。
  • display: 保存不同[视角(perspectives)]的不同显示选项的子对象，请参阅链接文章了解可能的键。仅对物品模型有效，但通常在方块模型中指定，以便物品模型可以继承显示选项。每个视角是一个可选的子对象，可能包含以下选项，按此顺序应用：
    • translation: 模型的平移，指定为[x, y, z]。
    • rotation: 模型的旋转，指定为[x, y, z]。
    • scale: 模型的缩放，指定为[x, y, z]。
    • right_rotation: NeoForge添加。缩放后应用的第二个旋转，指定为[x, y, z]。
  • transform: 请参阅根变换(Root Transforms)。
提示

如果你在确定如何准确指定某些内容时遇到困难，请查看执行类似操作的原版模型。

渲染类型(Render Types)​

使用可选的NeoForge添加的render_type字段，你可以为模型设置渲染类型。如果未设置此字段（所有原版模型都是这种情况），游戏将回退到ItemBlockRenderTypes中硬编码的渲染类型。如果ItemBlockRenderTypes也不包含该方块的渲染类型，它将回退到minecraft:solid。原版提供以下默认渲染类型：

  • minecraft:solid: 用于完全实心的方块，例如石头。
  • minecraft:cutout: 用于任何像素要么完全实心要么完全透明的方块，即具有完全透明度或无透明度，例如玻璃。
  • minecraft:cutout_mipped: minecraft:cutout的变体，将在远距离缩放纹理以避免视觉伪影（mipmapping）。不将mipmapping应用于物品渲染，因为物品上通常不需要它，并且可能导致伪影。例如，树叶使用此类型。
  • minecraft:cutout_mipped_all: minecraft:cutout_mipped的变体，也将mipmapping应用于物品模型。
  • minecraft:translucent: 用于任何像素可能部分透明的方块，例如染色玻璃。
  • minecraft:tripwire: 由具有渲染到天气目标的特殊要求的方块使用，即绊线。
  • neoforge:item_unlit: NeoForge添加。应由从物品渲染时不考虑光照方向的方块使用。

选择正确的渲染类型在某种程度上是性能问题。实体渲染比剪切渲染快，剪切渲染比半透明渲染快。因此，你应该为你的用例指定适用的"最严格"渲染类型，因为它也将是最快的。

如果你愿意，也可以添加自己的渲染类型。为此，订阅模组总线(mod bus)[事件(event)]RegisterNamedRenderTypesEvent并#register你的渲染类型。#register有三个参数：

  • 渲染类型的名称。应该是带有模组ID前缀的ResourceLocation。
  • 区块渲染类型。可以使用RenderType.chunkBufferLayers()返回的列表中的任何类型。
  • 实体渲染类型。必须是具有DefaultVertexFormat.NEW_ENTITY顶点格式的渲染类型。

元素(Elements)​

元素是立方体对象的JSON表示。它具有以下属性：

  • from: 立方体起始角的坐标，指定为[x, y, z]。以1/16方块单位指定。例如，[0, 0, 0]将是"左下"角，[8, 8, 8]将是中心，[16, 16, 16]将是方块的"右上"角。
  • to: 立方体结束角的坐标，指定为[x, y, z]。与from一样，这以1/16方块单位指定。
提示

from和to中的值被Minecraft限制在范围[-16, 32]内。然而，强烈建议不要超过[0, 16]，因为这将导致光照和/或剔除问题。

  • neoforge_data: 请参阅额外面数据(Extra Face Data)。
  • faces: 一个包含最多6个面数据的对象，分别命名为north、south、east、west、up和down。每个面具有以下数据：
    • uv: 面的uv，指定为[u1, v1, u2, v2]，其中u1, v1是左上角uv坐标，u2, v2是右下角uv坐标。
    • texture: 用于面的纹理。必须是带有#前缀的纹理变量。例如，如果你的模型有一个名为wood的纹理，你将使用#wood来引用该纹理。技术上可选，如果不存在将使用缺失纹理。
    • rotation: 可选。将纹理顺时针旋转90、180或270度。
    • cullface: 可选。告诉渲染引擎当指定方向有完整方块接触时跳过渲染该面。方向可以是north、south、east、west、up或down。
    • tintindex: 可选。指定可由颜色处理器使用的色调索引，有关更多信息，请参阅着色(Tinting)。默认为-1，表示无着色。
    • neoforge_data: 请参阅额外面数据(Extra Face Data)。

此外，它可以指定以下可选属性：

  • shade: 仅适用于方块模型。可选。此元素的各个面是否应具有方向相关的阴影。默认为true。
  • rotation: 对象的旋转，指定为包含以下数据的子对象：
    • angle: 旋转角度，以度为单位。可以是-45到45，步长为22.5度。
    • axis: 要围绕旋转的轴。目前无法围绕多个轴旋转对象。
    • origin: 可选。要围绕旋转的起点，指定为[x, y, z]。请注意，这些是绝对值，即它们不相对于立方体的位置。如果未指定，将使用[0, 0, 0]。

额外面数据(Extra Face Data)​

额外面数据（neoforge_data）可以应用于元素和元素的单个面。在所有可用的上下文中都是可选的。如果同时指定了元素级别和面级别的额外面数据，面级别数据将覆盖元素级别数据。额外数据可以指定以下数据：

  • color: 用给定颜色为面着色。必须是ARGB值。可以指定为字符串或十进制整数（JSON不支持十六进制字面量）。默认为0xFFFFFFFF。如果颜色值是常量，这可以用作着色的替代方案。
  • block_light: 覆盖用于此面的方块光照值。默认为0。
  • sky_light: 覆盖用于此面的天空光照值。默认为0。
  • ambient_occlusion: 为此面禁用或启用环境光遮蔽。默认为模型中设置的值。

根变换(Root Transforms)​

根变换（transform）是NeoForge添加的功能，允许在应用显示变换之前对模型应用变换。这对于需要在不同视角之间保持一致的模型很有用。根变换可以指定以下数据：

  • translation: 模型的平移，指定为[x, y, z]。
  • rotation: 模型的旋转，指定为[x, y, z]。
  • scale: 模型的缩放，指定为[x, y, z]。
  • right_rotation: 缩放后应用的第二个旋转，指定为[x, y, z]。

根变换在显示变换之前应用，这意味着它们影响模型的基础几何形状，然后显示变换在此基础上应用。

最佳实践​

  1. 使用适当的父模型：选择最适合你需求的父模型。
  2. 优化渲染类型：选择最严格的适用渲染类型以提高性能。
  3. 正确使用纹理变量：使用纹理变量使模型更易于维护。
  4. 考虑性能：避免不必要的元素和面。
  5. 测试兼容性：确保模型在不同视角和光照条件下正常工作。

通过遵循这些指南，你可以有效地在模组中创建和使用模型。