模型

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

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

规范

另请参阅：Minecraft Wiki上的模型

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

• loader：NeoForge添加。设置自定义模型加载器。有关更多信息，请参阅自定义模型加载器。
• parent：设置父模型，形式为相对于models文件夹的资源位置。所有父属性将被应用，然后被声明模型中设置的属性覆盖。常见的父模型包括：
  • 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块。
  • 方块物品通常（但不总是）使用其对应的方块模型作为其[物品模型][itemmodels]。例如，圆石客户端物品使用minecraft:block/cobblestone模型。
• ambientocclusion：是否启用环境光遮蔽。仅对方块模型有效。默认为true。如果你的自定义方块模型有奇怪的阴影，尝试将其设置为false。
• render_type：NeoForge添加。设置要使用的渲染类型。有关更多信息，请参阅渲染类型。
• gui_light：可以是"front"或"side"。如果为"front"，光线将来自前方，适用于平面2D模型。如果为"side"，光线将来自侧面，适用于3D模型（尤其是方块模型）。默认为"side"。仅对物品模型有效。
• textures：一个子对象，将名称（称为纹理变量）映射到纹理位置。然后可以在元素中使用纹理变量。它们也可以在元素中指定，但留空以便子模型指定它们。
  • 方块模型应额外指定一个particle纹理。此纹理在落在方块上、跑过方块或破坏方块时使用。
  • 物品模型也可以使用层纹理，命名为layer0、layer1等，其中索引较高的层渲染在索引较低的层之上（例如layer1将渲染在layer0之上）。仅当父模型为item/generated时有效，并且最多支持5层（layer0到layer4）。
• elements：立方体元素的列表。
• display：一个子对象，保存不同视角的不同显示选项，有关可能的键，请参阅链接文章。仅对物品模型有效，但通常在方块模型中指定，以便物品模型可以继承显示选项。每个视角都是一个可选的子对象，可能包含以下选项，按此顺序应用：
  • translation：模型的平移，指定为[x, y, z]。
  • rotation：模型的旋转，指定为[x, y, z]。
  • scale：模型的缩放，指定为[x, y, z]。
  • right_rotation：NeoForge添加。缩放后应用的第二次旋转，指定为[x, y, z]。
• transform：请参阅根变换。

提示

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

渲染类型

使用可选的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添加。应由从物品渲染时不考虑光线方向的方块使用。

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

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

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

元素

元素是立方体对象的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：请参阅额外面数据。
• 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：可选。指定颜色处理程序可能使用的色调索引，有关更多信息，请参阅着色。默认为-1，表示不着色。
  • neoforge_data：请参阅额外面数据。

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

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

额外面数据

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

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

根变换

在模型顶层添加transform属性告诉加载器，应在方块状态文件中的旋转（对于方块模型）或display块中的变换（对于物品模型）应用之前对所有几何体应用变换。这是由NeoForge添加的。

根变换可以通过两种方式指定。第一种方式是作为名为matrix的单个属性，包含变换3x4矩阵（行主序，省略最后一行），形式为嵌套JSON数组。矩阵是平移、左旋转、缩放、右旋转和变换原点的组合，按此顺序。示例如下所示：

{
    // ...
    "transform": {
        "matrix": [
            [0, 0, 0, 0],
            [0, 0, 0, 0],
            [0, 0, 0, 0]
        ]
    }
}

第二种方式是指定一个JSON对象，包含以下条目的任意组合，按此顺序应用：

• translation：相对平移。指定为三维向量（[x, y, z]），如果不存在则默认为[0, 0, 0]。
• rotation或left_rotation：围绕平移原点的旋转，在缩放之前应用。默认为无旋转。可以通过以下方式之一指定：
  • 具有单轴到旋转映射的JSON对象，例如{"x": 90}
  • 具有单轴到旋转映射的JSON对象数组，按指定顺序应用，例如[{"x": 90}, {"y": 45}, {"x": -22.5}]
  • 具有三个值的数组，每个值指定围绕每个轴的旋转，例如[90, 45, -22.5]
  • 具有四个值的数组，直接指定四元数，例如[0.38268346, 0, 0, 0.9238795]（= 围绕X轴45度）
• scale：相对于平移原点的缩放。指定为三维向量（[x, y, z]），如果不存在则默认为[1, 1, 1]。
• post_rotation或right_rotation：围绕平移原点的旋转，在缩放之后应用。默认为无旋转。指定方式与rotation相同。
• origin：用于旋转和缩放的原点。变换也作为最后一步移动到这里。可以指定为三维向量（[x, y, z]），或使用三个内置值之一："corner"（= [0, 0, 0]）、"center"（= [0.5, 0.5, 0.5]）或"opposing-corner"（= [1, 1, 1]，默认）。

方块状态文件

另请参阅：Minecraft Wiki上的方块状态文件

方块状态文件被游戏用来为不同的[方块状态][blockstates]分配不同的模型。每个注册到游戏的方块必须恰好有一个方块状态文件。为方块状态指定方块模型有两种互斥的方式：通过变体或通过多部分。

在variants块内部，每个方块状态都有一个元素。这是将方块状态与模型关联的主要方式，被绝大多数方块使用。

• 键是方块状态的字符串表示，不带方块名称，因此例如"type=top,waterlogged=false"表示非含水顶部台阶，或""表示没有属性的方块。值得注意的是，未使用的属性可以省略。例如，如果waterlogged属性对选择的模型没有影响，两个对象type=top,waterlogged=false和type=top,waterlogged=true可以合并为一个type=top对象。这也意味着空字符串对每个方块都有效。
• 值可以是单个模型对象或模型对象数组。如果使用模型对象数组，将从中随机选择一个模型。模型对象由以下数据组成：
  • model：模型文件位置的路径，相对于命名空间的models文件夹，例如minecraft:block/cobblestone。
  • x和y：模型在x轴/y轴上的旋转。限制为90度的步长。每个可选，默认为0。
  • uvlock：旋转时是否锁定模型的UV。可选，默认为false。
  • weight：仅对模型对象数组有用。为对象赋予权重，用于选择随机模型对象时。可选，默认为1。

相比之下，在multipart块内部，元素根据方块状态的属性组合。此方法主要由栅栏和墙使用，它们基于布尔属性启用四个方向部分。多部分元素由两部分组成：when块和apply块。

• when块指定方块状态的字符串表示或元素应用必须满足的属性列表。列表可以命名为"OR"或"AND"，对其内容执行相应的逻辑操作。单个方块状态和列表值都可以通过用|分隔来指定多个实际值（例如facing=east|facing=west）。
• apply块指定要使用的模型对象或模型对象数组。这与variants块的工作方式完全相同。

客户端物品

客户端物品被游戏用来为ItemStack的状态分配一个或多个模型。虽然模型JSON中有一些物品特定的字段，但客户端物品根据上下文使用模型进行渲染，因此它们的大部分信息已移至其独立的章节。

着色

一些方块，如草或树叶，会根据其位置和/或属性改变其纹理颜色。模型元素可以在其面上指定色调索引，这将允许颜色处理程序处理相应的面。代码方面通过三个事件工作，一个用于方块颜色处理程序，一个用于基于生物群系的方块色调（与方块颜色处理程序结合使用），一个用于物品色调源。它们的工作方式非常相似，所以让我们先看一个方块处理程序：

@SubscribeEvent // 仅在物理客户端的模组事件总线上
public static void registerBlockColorHandlers(RegisterColorHandlersEvent.Block event) {
    // 参数是方块的状态、方块所在的层级、方块的位置和色调索引。
    // 层级和位置可能为null。
    event.register((state, level, pos, tintIndex) -> {
        // 替换为你自己的计算。有关原版参考，请参阅BlockColors类。
        // 颜色为ARGB格式。通常，如果色调索引为-1，意味着不应进行着色，而应使用默认值。
        return 0xFFFFFFFF;
    },
    // 要应用着色的方块的可变参数
    EXAMPLE_BLOCK.get(), ...);
}

这是一个颜色解析器的示例：

@SubscribeEvent // 仅在物理客户端的模组事件总线上
public static void registerColorResolvers(RegisterColorHandlersEvent.ColorResolvers event) {
    // 参数是当前的生物群系、方块的X位置和方块的Z位置。
    event.register((biome, x, z) -> {
        // 替换为你自己的计算。有关原版参考，请参阅BiomeColors类。
        // 颜色为ARGB格式。
        return 0xFFFFFFFF;
    });
}

对于物品着色，请参阅客户端物品文章中的相关部分。

注册额外模型

那些不与方块或物品关联，但在其他上下文中仍然需要的模型（例如方块实体渲染器），可以通过ModelEvent.RegisterAdditional进行注册：

@SubscribeEvent // 仅在物理客户端的模组事件总线上
public static void registerAdditional(ModelEvent.RegisterAdditional event) {
    // 模型ID，相对于`assets/<命名空间>/models/<路径>.json`
    event.register(ResourceLocation.fromNamespaceAndPath("examplemod", "block/example_unused_model"));
}