自定义方块模型

自定义方块默认渲染为 16×16×16 的标准正方体。通过 netease:block_geometry 模型格式，你可以制作花朵、装饰品、电线等任意形状的方块。模型使用 BlockBench 制作，通过 MC Studio 导入到项目中。

前置条件

请先阅读自定义基础方块了解方块的注册流程和贴图配置。方块模型使用 format_version: "1.13.0" 的 netease:block_geometry 格式。

概述

自定义方块模型的核心流程：

使用 BlockBench 制作自由模型（Free Model），导出工程文件
使用 MC Studio 导入模型，自动生成模型 JSON 和贴图配置
在 blocks.json 中通过 netease_model 引用模型 identifier
在行为包方块 JSON 中配置 minecraft:block_light_absorption: 0 避免模型变黑

关键限制

每张贴图尺寸不能超过 64×64
特殊方块（刷怪箱、传送门、重力方块等）不支持方块模型，农作物除外
模型方块支持四面向（netease:face_directional 的 direction），但不支持六面向
不要将模型方块用于群系构成，也避免在频繁出现的特征中放置大量模型方块
立方体不支持 inflate 功能

模型文件结构

模型 JSON 位于 resource_pack/models/netease_block/ 目录下，完整结构如下：

description（模型描述）

键	类型	说明
`identifier`	string	模型标识符，建议使用 `命名空间:模型名`
`textures`	array(string)	模型用到的贴图列表，与 `terrain_texture.json` 对应
`item_texture`	string	可选。物品形态使用的贴图（手持/UI/掉落物），不设置时使用方块模型渲染
`use_ao`	bool	可选。是否启用环境光遮蔽（AO），启用后亮度更自然但整体偏暗，默认 `false`
`textures_descriptions`	array(object)	可选。每张贴图的实际分辨率 `{width, length}`，最大 64×64，默认 16×16

bones（骨骼数组）

键	类型	说明
`name`	string	骨骼名称
`parent`	string	父骨骼名称
`pivot`	array(float)	旋转中心
`rotation`	array(float)	绕旋转中心的旋转角度
`texture`	int	可选。使用的贴图索引（对应 `textures` 数组下标），默认 0
`enable`	molang	可选。控制骨骼是否渲染，目前仅支持 `is_connect` 查询（配合 `netease:connection`）
`cubes`	array(object)	该骨骼包含的立方体

cubes（立方体数组）

键	类型	说明
`origin`	array(float)	最小点位置
`size`	array(float)	立方体大小
`pivot`	array(float)	旋转中心
`rotation`	array(float)	旋转角度
`texture`	int	可选。贴图索引，缺省时继承骨骼的贴图
`uv`	object	面的 UV 信息，可选的面：`up`/`down`/`north`/`south`/`west`/`east`

uv（面 UV）

键	类型	说明
`uv`	array(int)	起始 UV 坐标
`uv_size`	array(int)	UV 大小
`texture`	int	可选。该面使用的贴图索引，缺省时继承立方体的贴图
`rot`	int	可选。UV 顺时针旋转角度，可选 90/180/270

案例一：小花方块

一个简单的交叉面片花朵方块，使用两个互相垂直的面片构成。

BlockBench 制作流程

新建自由模型项目，贴图尺寸设为 16×16，不勾选盒子 UV
准备花朵贴图（16×16），拖入 BlockBench
添加两个 cube，分别放在 16×16 网格的两条对角线上
为每个 cube 的 north 面应用花朵贴图，其余面设为透明
保存工程文件

MC Studio 导入

MC Studio 导入时自动完成：

将 bbmodel 转换为 netease:block_geometry JSON → resource_pack/models/netease_block/
将贴图复制到 resource_pack/textures/blocks/
配置 terrain_texture.json

模型 JSON

resource_pack/models/netease_block/flower_model.json：

json

{
  "format_version": "1.13.0",
  "netease:block_geometry": {
    "description": {
      "identifier": "mymod:flower_model",
      "textures": ["mymod_flower"],
      "use_ao": false
    },
    "bones": [
      {
        "name": "cross_a",
        "pivot": [8, 0, 8],
        "rotation": [0, 45, 0],
        "cubes": [
          {
            "origin": [0.5, 0, 0.5],
            "size": [15, 16, 0],
            "uv": {
              "north": { "uv": [0, 0], "uv_size": [16, 16] },
              "south": { "uv": [0, 0], "uv_size": [16, 16] }
            }
          }
        ]
      },
      {
        "name": "cross_b",
        "pivot": [8, 0, 8],
        "rotation": [0, -45, 0],
        "cubes": [
          {
            "origin": [0.5, 0, 0.5],
            "size": [15, 16, 0],
            "uv": {
              "north": { "uv": [0, 0], "uv_size": [16, 16] },
              "south": { "uv": [0, 0], "uv_size": [16, 16] }
            }
          }
        ]
      }
    ]
  }
}

行为包方块 JSON

behavior_pack/netease_blocks/flower.json：

json

{
  "format_version": "1.10.0",
  "minecraft:block": {
    "description": {
      "identifier": "mymod:custom_flower",
      "register_to_create_menu": true,
      "category": "Nature"
    },
    "components": {
      "minecraft:destroy_time": { "value": 0.0 },
      "minecraft:block_light_absorption": { "value": 0 },
      "netease:render_layer": { "value": "alpha" },
      "netease:solid": { "value": false },
      "netease:aabb": {
        "collision": { "min": [4, 0, 4], "max": [12, 14, 12] },
        "clip": { "min": [4, 0, 4], "max": [12, 14, 12] }
      }
    }
  }
}

blocks.json 配置

json

{
  "mymod:custom_flower": {
    "sound": "grass",
    "netease_model": "mymod:flower_model"
  }
}

本地化

tile.mymod:custom_flower.name=自定义小花

关键配置

minecraft:block_light_absorption: 0 — 必须设置，否则模型会全黑
netease:render_layer: "alpha" — 让透明面片正确渲染
netease:solid: false — 花朵不应该窒息玩家

案例二：多贴图装饰方块

当模型较复杂时，单张 16×16 贴图不够用。你可以使用多张贴图，通过 texture 索引在不同骨骼/立方体/面上引用不同贴图。

多贴图模型 JSON

json

{
  "format_version": "1.13.0",
  "netease:block_geometry": {
    "description": {
      "identifier": "mymod:decoration_model",
      "textures": ["mymod_deco_base", "mymod_deco_detail", "mymod_deco_top"],
      "item_texture": "mymod_deco_icon",
      "use_ao": false
    },
    "bones": [
      {
        "name": "base",
        "pivot": [8, 0, 8],
        "texture": 0,
        "cubes": [
          {
            "origin": [2, 0, 2],
            "size": [12, 4, 12],
            "uv": {
              "up":    { "uv": [0, 0], "uv_size": [12, 12] },
              "down":  { "uv": [0, 0], "uv_size": [12, 12] },
              "north": { "uv": [0, 12], "uv_size": [12, 4] },
              "south": { "uv": [0, 12], "uv_size": [12, 4] },
              "east":  { "uv": [0, 12], "uv_size": [12, 4] },
              "west":  { "uv": [0, 12], "uv_size": [12, 4] }
            }
          }
        ]
      },
      {
        "name": "pillar",
        "parent": "base",
        "pivot": [8, 4, 8],
        "texture": 1,
        "cubes": [
          {
            "origin": [6, 4, 6],
            "size": [4, 8, 4],
            "uv": {
              "north": { "uv": [0, 0], "uv_size": [4, 8] },
              "south": { "uv": [0, 0], "uv_size": [4, 8] },
              "east":  { "uv": [4, 0], "uv_size": [4, 8] },
              "west":  { "uv": [4, 0], "uv_size": [4, 8] }
            }
          }
        ]
      },
      {
        "name": "top",
        "parent": "pillar",
        "pivot": [8, 12, 8],
        "texture": 2,
        "cubes": [
          {
            "origin": [3, 12, 3],
            "size": [10, 3, 10],
            "uv": {
              "up":    { "uv": [0, 0], "uv_size": [10, 10] },
              "north": { "uv": [0, 10], "uv_size": [10, 3] },
              "south": { "uv": [0, 10], "uv_size": [10, 3] },
              "east":  { "uv": [0, 10], "uv_size": [10, 3] },
              "west":  { "uv": [0, 10], "uv_size": [10, 3] }
            }
          }
        ]
      }
    ]
  }
}

自定义贴图分辨率

如果某张贴图需要更高分辨率（最大 64×64），在 textures_descriptions 中配置：

json

"textures_descriptions": [
  { "width": 16, "length": 16 },
  { "width": 32, "length": 32 },
  { "width": 16, "length": 16 }
]

数组下标与 textures 数组一一对应。

案例三：可连接的电线方块

使用 netease:connection 组件 + 模型骨骼的 enable 字段，实现根据相邻方块自动变化的连接模型。

工作原理

netease:connection 定义方块可以与哪些方块"连接"
模型中每个方向的骨骼使用 enable: "is_connect(方向)" 来控制显示/隐藏
当某个方向有可连接的方块时，对应骨骼自动显示

行为包 JSON

json

{
  "format_version": "1.10.0",
  "minecraft:block": {
    "description": {
      "identifier": "mymod:wire",
      "register_to_create_menu": true,
      "category": "Construction"
    },
    "components": {
      "minecraft:destroy_time": { "value": 0.5 },
      "minecraft:block_light_absorption": { "value": 0 },
      "netease:render_layer": { "value": "alpha" },
      "netease:solid": { "value": false },
      "netease:connection": {
        "blocks": [
          "mymod:wire",
          "minecraft:furnace",
          "minecraft:redstone_block"
        ]
      },
      "netease:aabb": {
        "collision": [
          { "min": [5, 5, 5], "max": [11, 11, 11] },
          { "min": [0, 5, 5], "max": [5, 11, 11], "is_connect": "west" },
          { "min": [11, 5, 5], "max": [16, 11, 11], "is_connect": "east" },
          { "min": [5, 5, 0], "max": [11, 11, 5], "is_connect": "north" },
          { "min": [5, 5, 11], "max": [11, 11, 16], "is_connect": "south" },
          { "min": [5, 0, 5], "max": [11, 5, 11], "is_connect": "down" },
          { "min": [5, 11, 5], "max": [11, 16, 11], "is_connect": "up" }
        ]
      }
    }
  }
}

模型 JSON（简化）

json

{
  "format_version": "1.13.0",
  "netease:block_geometry": {
    "description": {
      "identifier": "mymod:wire_model",
      "textures": ["mymod_wire"],
      "item_texture": "mymod_wire_icon",
      "use_ao": true
    },
    "bones": [
      {
        "name": "center",
        "pivot": [8, 8, 8],
        "cubes": [{
          "origin": [5, 5, 5], "size": [6, 6, 6],
          "uv": {
            "up":    { "uv": [0, 0], "uv_size": [6, 6] },
            "down":  { "uv": [0, 0], "uv_size": [6, 6] },
            "north": { "uv": [0, 6], "uv_size": [6, 6] },
            "south": { "uv": [0, 6], "uv_size": [6, 6] },
            "east":  { "uv": [6, 6], "uv_size": [6, 6] },
            "west":  { "uv": [6, 6], "uv_size": [6, 6] }
          }
        }]
      },
      {
        "name": "arm_north",
        "pivot": [8, 8, 8],
        "enable": "is_connect(north)",
        "cubes": [{
          "origin": [5, 5, 0], "size": [6, 6, 5],
          "uv": {
            "up":    { "uv": [0, 0], "uv_size": [6, 5] },
            "down":  { "uv": [0, 0], "uv_size": [6, 5] },
            "east":  { "uv": [6, 6], "uv_size": [5, 6] },
            "west":  { "uv": [6, 6], "uv_size": [5, 6] }
          }
        }]
      },
      {
        "name": "arm_south",
        "pivot": [8, 8, 8],
        "enable": "is_connect(south)",
        "cubes": [{
          "origin": [5, 5, 11], "size": [6, 6, 5],
          "uv": {
            "up":    { "uv": [0, 0], "uv_size": [6, 5] },
            "down":  { "uv": [0, 0], "uv_size": [6, 5] },
            "east":  { "uv": [6, 6], "uv_size": [5, 6] },
            "west":  { "uv": [6, 6], "uv_size": [5, 6] }
          }
        }]
      }
    ]
  }
}

实际项目中你需要为六个方向各添加一个带 enable 的骨骼（north/south/east/west/up/down）。

性能优化

对于不可见的面（例如连接臂内侧的两个面），可以在 uv 中省略它们不渲染，减少面数。

UV 翻转与旋转

BlockBench 支持 UV 旋转和镜像功能。在导出的模型 JSON 中，通过 rot 字段表示：

json

"north": { "uv": [0, 0], "uv_size": [8, 8], "rot": 90 }

可选值：90、180、270（顺时针旋转角度）。

注意事项

项目	说明
贴图尺寸	每张最大 64×64
光照吸收	模型方块必须设 `minecraft:block_light_absorption: 0`，否则全黑
透明/半透明	配合 `netease:render_layer` 使用（`alpha`/`blend`/`optionalAlpha`），但属性应用于整个模型
特殊方块	`base_block` 方块不支持模型（农作物除外）
四面向	支持 `netease:face_directional` 的 `direction` 类型，is_connect 会自动适配面向
六面向	不支持
inflate	立方体不支持 inflate 功能
群系构成	不要将模型方块用于群系构成或高频特征

下一步

自定义基础方块 — 方块注册流程和组件配置
自定义方块实体 — 为方块添加数据存储、动画和特效
特殊方块类型 — 刷怪箱、传送门、农作物等
方块组件速查 — 所有方块组件一览

插件开发

基本概念

基础内容

进阶内容

底层内容

玩法开发

上线流程

开发准备

Apollo基础

网络服模板

插件开发

开发技巧与性能

上线运营

第三方框架

自定义方块模型

概述

模型文件结构

description（模型描述）

bones（骨骼数组）

cubes（立方体数组）

uv（面 UV）

案例一：小花方块

BlockBench 制作流程

MC Studio 导入

模型 JSON

行为包方块 JSON

blocks.json 配置

本地化

案例二：多贴图装饰方块

多贴图模型 JSON

自定义贴图分辨率

案例三：可连接的电线方块

工作原理

行为包 JSON

模型 JSON（简化）

UV 翻转与旋转

注意事项

下一步

基本概念

基础内容

进阶内容

底层内容

自定义方块模型 ​

概述 ​

模型文件结构 ​

description（模型描述） ​

bones（骨骼数组） ​

cubes（立方体数组） ​

uv（面 UV） ​

案例一：小花方块 ​

BlockBench 制作流程 ​

MC Studio 导入 ​

模型 JSON ​

行为包方块 JSON ​

blocks.json 配置 ​

本地化 ​

案例二：多贴图装饰方块 ​

多贴图模型 JSON ​

自定义贴图分辨率 ​

案例三：可连接的电线方块 ​

工作原理 ​

行为包 JSON ​

模型 JSON（简化） ​

UV 翻转与旋转 ​

注意事项 ​

下一步 ​

自定义方块模型

概述

模型文件结构

description（模型描述）

bones（骨骼数组）

cubes（立方体数组）

uv（面 UV）

案例一：小花方块

BlockBench 制作流程

MC Studio 导入

模型 JSON

行为包方块 JSON

blocks.json 配置

本地化

案例二：多贴图装饰方块

多贴图模型 JSON

自定义贴图分辨率

案例三：可连接的电线方块

工作原理

行为包 JSON

模型 JSON（简化）

UV 翻转与旋转

注意事项

下一步