自定义基础方块

开发者可以通过在 addon 中配置 JSON 来添加自定义方块。自定义方块支持 ModAPI 中与方块及物品相关的所有事件及接口。本文将介绍方块的完整注册流程、JSON 组件配置、贴图与模型设置，以及常见问题排查。

前置条件

本功能不需要开启实验性玩法。基础方块使用 format_version: "1.10.0"。在开始之前，请确保你已阅读 自定义游戏内容概述，并准备好行为包与资源包的基础目录结构。

概述

自定义方块是中国版 addon 系统中最核心的自定义内容之一。你可以在行为包的 netease_blocks/ 目录下编写 JSON 定义文件，向游戏注册全新的方块。

自定义方块采用 数据驱动 的方式：你在 JSON 中通过 components（组件）声明方块的物理属性和行为，引擎会在运行时读取并应用这些配置。同时，自定义方块完全兼容 Python Mod SDK 的事件与接口，可以实现更复杂的逻辑。

identifier 规则：

• 格式为 命名空间:方块名，例如 mymod:custom_ore
• 必须全局唯一，命名空间建议与 mod 名称一致
• 只允许使用小写字母、数字和下划线，不支持大写字母和特殊字符
• identifier 长度不要过长，建议控制在 32 个字符以内

自定义方块支持以下能力：

• 自定义贴图、声音、亮度、爆炸抗性
• 自定义碰撞盒（AABB）、渲染层、多面向
• 方块实体（Block Entity）数据存储与 tick 事件
• 自定义方块模型（几何体）
• 作为自定义配方的材料或产出
• 在掉落表（loot_table）和村民交易中使用
• 构成自定义群系的地表方块

注册流程

注册一个自定义方块需要 7 个步骤，涉及行为包和资源包两侧的配置：

步骤	操作	所在包
1	在行为包中创建 netease_blocks/ 目录，编写方块定义 JSON	行为包
2	将方块贴图放入 textures/blocks/	资源包
3	在 textures/terrain_texture.json 中配置资源名与贴图的映射	资源包
4	在资源包根目录创建 blocks.json，配置方块贴图与声音	资源包
5	在 texts/zh_CN.lang 中配置方块的中文名称	资源包
6	进入游戏测试 — 创造模式或 /give 指令获取	—
7	重复 1-6 注册更多方块	—

下面按照这个流程，从行为包配置开始，逐步详细说明每一步的配置内容。

行为包配置（netease_blocks）

在行为包根目录下新建 netease_blocks/ 文件夹，然后在其中创建方块定义 JSON 文件。文件名可以自由命名（建议与方块名一致），扩展名必须是 .json。

JSON 中至少有一个 component

行为包中的方块 JSON 必须包含至少一个组件，否则引擎无法正确加载该方块。如果你的方块不需要任何特殊属性，可以只写一个 minecraft:destroy_time。

description 字段

description 是方块定义的核心信息，包含以下字段：

键	类型	默认值	说明
identifier	string	—	方块的唯一标识符，格式为 命名空间:方块名。必须全局唯一，建议使用 mod 名称作为命名空间
register_to_create_menu	bool	false	是否注册到创造模式物品栏。设为 true 后，方块会出现在创造栏中
category	string	"Nature"	注册到创造栏的分类。可选值：Construction、Nature、Equipment、Items
base_block	string	—	可选。用于特殊方块类型，如 "mob_spawner"、"portal" 等。基础方块不需要填写此字段

最小化方块定义

下面是一个最简单的实心方块定义，只包含挖掘时间组件：

{
  "format_version": "1.10.0",
  "minecraft:block": {
    "description": {
      "identifier": "mymod:basic_stone",
      "register_to_create_menu": true,
      "category": "Construction"
    },
    "components": {
      "minecraft:destroy_time": {
        "value": 3.0
      }
    }
  }
}

identifier 不可修改

方块一旦注册并在存档中使用，请勿修改 identifier。修改后会导致已放置的方块变为未知方块，玩家背包中的对应方块物品也会消失。

原版方块组件（minecraft:）

中国版支持多个原版方块组件。不同 format_version 下组件的写法有差异，下面分别列出。

minecraft:destroy_time

控制方块的挖掘硬度。该值的含义与原版的"硬度"一致。

format_version: "1.10.0" 写法：

"minecraft:destroy_time": {
  "value": 4.0
}

format_version: "1.16.0" 写法：

"minecraft:destroy_time": 4.0

minecraft:destructible_by_mining

format_version ≥ 1.19.20 时替代 minecraft:destroy_time 的新写法。

键	类型	默认值	说明
seconds_to_destroy	float	0.0	方块硬度。实际破坏时间 ≈ 1.5 × 该值

"minecraft:destructible_by_mining": {
  "seconds_to_destroy": 4.0
}

• 设为 true：采用默认破坏时间
• 设为 false：方块不可被挖掘破坏

minecraft:explosion_resistance

设置方块的爆炸抗性。原版方块的抗性值可参考 Minecraft Wiki - 爆炸。

format_version: "1.10.0" 写法：

"minecraft:explosion_resistance": {
  "value": 6.0
}

minecraft:destructible_by_explosion

format_version ≥ 1.19.20 时替代 minecraft:explosion_resistance 的新写法。

键	类型	默认值	说明
explosion_resistance	float	0.0	爆炸抗性值

"minecraft:destructible_by_explosion": {
  "explosion_resistance": 20.0
}

• 设为 true：采用默认爆炸抗性
• 设为 false：方块不可被爆炸破坏

minecraft:block_light_emission

设置方块发出的光照等级，取值范围 [0.0, 1.0]，其中 1.0 相当于光照等级 15。

"minecraft:block_light_emission": {
  "value": 1.0
}

minecraft:light_emission

format_version ≥ 1.19.20 时替代 minecraft:block_light_emission。取值范围 [0, 15]（整数）。

"minecraft:light_emission": 15

minecraft:block_light_absorption

设置方块对光照的吸收程度。默认为不透光（值为 15）。取值范围 [0, 15]。

"minecraft:block_light_absorption": {
  "value": 0
}

自定义方块模型必配

使用自定义方块模型时，必须配合 minecraft:block_light_absorption 将值设为 0，否则模型会变黑。

minecraft:light_dampening

format_version ≥ 1.19.20 时替代 minecraft:block_light_absorption。取值范围 [0, 15]。

"minecraft:light_dampening": 0

minecraft:loot

指定方块被破坏时使用的掉落表路径（使用精准采集附魔时忽略）。不配置时，方块破坏后会掉落自身。

"minecraft:loot": {
  "value": "loot_tables/blocks/my_block.json"
}

minecraft:friction

设置方块表面的摩擦力，取值范围 (0.0, 0.9)。值越小方块越滑。

"minecraft:friction": {
  "value": 0.6
}

注意

此摩擦力与原版方块内部的摩擦力不是同一个属性。该组件在船上工作正常，但对其他实体可能表现异常（数值越大反而加速）。

minecraft:map_color

设置方块在地图上显示的颜色，使用十六进制颜色字符串。

"minecraft:map_color": "#4A90D9"

minecraft:display_name

指定语言文件键，用于方块在物品栏中悬停显示的文本。需要 format_version ≥ 1.19.60。

"minecraft:display_name": "tile.mymod:custom_ore.name"

网易方块组件（netease:）

网易独有组件以 netease: 开头，提供了丰富的方块行为扩展。下面逐一介绍。

netease:aabb

设置方块的碰撞盒。

键	类型	说明
collision	object 或 array	物理碰撞盒（实体碰撞）
clip	object 或 array	射线检测碰撞盒（准心选取、弹射物碰撞）

当 collision/clip 为 object 时（固定大小的单一碰撞盒）：

键	类型	默认值	说明
min	array(float)	[0, 0, 0]	最小角坐标。min 的三个值必须 ≤ max
max	array(float)	[1, 1, 1]	最大角坐标

当 collision/clip 为 array 时（可变化的多碰撞盒组合，常配合 netease:connection 使用）：

数组每个元素的结构：

键	类型	默认值	说明
enable	molang	true	控制是否开启此碰撞盒。仅支持 query.is_connect
min	array(float)	[0, 0, 0]	最小角坐标
max	array(float)	[1, 1, 1]	最大角坐标

"netease:aabb": {
  "collision": {
    "min": [0.25, 0, 0.25],
    "max": [0.75, 0.5, 0.75]
  },
  "clip": {
    "min": [0.25, 0, 0.25],
    "max": [0.75, 0.5, 0.75]
  }
}

AABB 注意事项

1. 无碰撞箱的方块请将 collision 的 min 和 max 都设为 [0, 0, 0]
2. clip 的范围需要 小于或等于 collision 的范围，否则弹射物命中时会异常
3. min 不要小于 [-1, -1, -1]，max 不要大于 [2, 2, 2]

netease:face_directional

设置方块的多面向，让方块可以根据玩家放置方向旋转贴图。

键	类型	说明
type	string	"direction" — 四面向方块；"facing_direction" — 六面向方块

"netease:face_directional": {
  "type": "direction"
}

放置时，north 面（正面贴图）始终朝向玩家。详见 多面向方块 章节。

netease:fuel

允许方块的物品形式作为燃料在熔炉中燃烧。

键	类型	默认值	说明
duration	float	0	燃烧时长，单位为秒

"netease:fuel": {
  "duration": 10.0
}

netease:render_layer

设置方块渲染时使用的材质（渲染层）。

键	类型	说明
value	string	渲染层名称

可选值：

值	说明	原版示例
opaque	不透明（默认）	石头、泥土
alpha	全透明，用于异形方块	火焰
blend	半透明	彩色玻璃
optionalAlpha	局部透明，远距离不消失	树叶

"netease:render_layer": {
  "value": "blend"
}

alpha 与 optionalAlpha 的区别

alpha 超过一定距离后方块将不渲染。optionalAlpha 不会消失，能配合 netease:no_crop_face_block 实现原版叶子效果。

netease:solid

设置方块是否为实心方块，影响生物在方块内是否受到窒息伤害。

键	类型	默认值	说明
value	bool	true	true = 方块内窒息；false = 方块内不窒息

"netease:solid": {
  "value": false
}

WARNING

使用此组件后，自定义方块将不会产生阴影。

netease:pathable

设置 AI 寻路时，方块是否被当作障碍物。

键	类型	默认值	说明
value	bool	false	true = 寻路时视为空气（可穿过）；false = 视为障碍物，生物可在方块上方行走

"netease:pathable": {
  "value": true
}

netease:tier

设置方块的挖掘工具与等级要求。

键	类型	默认值	说明
digger	string	—	必填。加速挖掘的工具类型：shovel（铲）、pickaxe（镐）、hatchet（斧）、hoe（锄）
destroy_special	bool	false	为 true 时，只有使用 digger 指定的工具挖掘才会产生掉落物
level	int	0	当 destroy_special 为 true 时生效。挖掘所需的最低工具等级

工具等级对照表：

等级	对应工具
0	空手 / 木制 / 金制工具
1	石制工具
2	铁制工具
3	钻石工具
4	下界合金工具

"netease:tier": {
  "digger": "pickaxe",
  "destroy_special": true,
  "level": 2
}

netease:block_entity

为自定义方块添加方块实体（Block Entity），从而支持数据存储和 tick 事件。

键	类型	默认值	说明
tick	bool	false	为 true 时，玩家进入方块 tick 范围时每秒发送 20 次 ServerBlockEntityTickEvent
client_tick	bool	false	为 true 时，玩家进入方块 tick 范围时每秒发送 20 次 ModBlockEntityTickClientEvent
movable	bool	true	为 true 时可被粘性活塞拉回；为 false 时不可被拉回

"netease:block_entity": {
  "tick": true,
  "client_tick": false,
  "movable": false
}

性能提醒

• 避免在 tick 事件回调中进行频繁打印输出，容易造成卡顿
• 避免在地图中放置过多 tick 为 true 的方块实体
• 已有内置方块实体的特殊方块（如自定义刷怪箱）无法再添加自定义方块实体

添加了方块实体的方块，可通过 GetBlockEntityData 接口读写方块实体数据。详见 方块实体 章节。

netease:random_tick

设置方块是否接收随机 tick，以及是否将事件发送到脚本层。

键	类型	默认值	说明
enable	bool	false	方块是否接收随机 tick
tick_to_script	bool	false	是否发送 BlockRandomTickServerEvent 到 Python 脚本

"netease:random_tick": {
  "enable": true,
  "tick_to_script": true
}

netease:redstone_property

设置自定义方块的红石/活塞交互属性。

键	类型	默认值	说明
value	string	"none"	红石属性

可选值：

值	说明
none	无特殊属性（默认），方块可被活塞推动
break_on_push	被活塞推动时破坏为掉落物
block_push	不可被活塞推动（阻止活塞伸出）

"netease:redstone_property": {
  "value": "break_on_push"
}

netease:neighborchanged_sendto_script

方块周围环境变化时，是否发送 BlockNeighborChangedServerEvent 到脚本层。

键	类型	默认值	说明
value	bool	false	是否发送事件

"netease:neighborchanged_sendto_script": {
  "value": true
}

netease:fire_resistant

设置方块的掉落物是否防火（与下界合金相同，不会被火焰烧毁，掉入岩浆时会弹走）。

键	类型	默认值	说明
value	bool	false	是否防火

"netease:fire_resistant": {
  "value": true
}

netease:connection

为方块定义"连接"属性。当相邻方块在 blocks 列表中时，query.is_connect 查询返回 true。常用于电线、管道等可变模型方块。

键	类型	说明
blocks	array(string)	方块 identifier 列表，表示可连接的方块

"netease:connection": {
  "blocks": [
    "mymod:wire",
    "minecraft:furnace",
    "minecraft:grass"
  ]
}

query.is_connect 参数与对应面的关系：

参数	对应面
0	down（下）
1	up（上）
2	north（北）
3	south（南）
4	west（西）
5	east（东）

netease:block_properties

配置方块的特殊属性标志，这些属性会影响引擎对方块的内部逻辑判断。

键	类型	说明
properties	array(string)	属性字符串数组

可选属性值：

值	说明
piston_block_grabber	被活塞推动时是否带动旁边方块
slime	移动方块时修改对实体力的计算（类似粘液块）
breaks_when_fallen_on_by_heavy	重力方块落在该方块上时，自身是否被摧毁

"netease:block_properties": {
  "properties": ["slime", "piston_block_grabber"]
}

netease:on_stand_on

实体站在方块上时触发事件。

键	类型	说明
send_python_event	bool	为 true 时触发 OnStandOnBlockClientEvent 和 OnStandOnBlockServerEvent

"netease:on_stand_on": {
  "send_python_event": true
}

netease:on_step_on

实体刚移动到实心方块上时触发事件。

"netease:on_step_on": {
  "send_python_event": true
}

netease:on_step_off

实体刚离开实心方块上方时触发事件。

"netease:on_step_off": {
  "send_python_event": true
}

netease:on_before_fall_on

实体刚下落至方块时触发，主要用于伤害计算。

"netease:on_before_fall_on": {}

netease:on_after_fall_on

实体下落至方块后触发，主要用于力的计算（如弹跳效果）。

"netease:on_after_fall_on": {}

netease:on_entity_inside

实体碰撞盒所在位置有该方块时触发（与方块碰撞盒大小无关，只判断方块位置）。

键	类型	说明
send_python_event	bool	为 true 时触发 OnEntityInsideBlockClientEvent 和 OnEntityInsideBlockServerEvent

"netease:on_entity_inside": {
  "send_python_event": true
}

碰撞盒与触发

on_stand_on、on_before_fall_on、on_after_fall_on 等组件，如果方块碰撞盒使用 netease:aabb 改得过小（边长约 0.4 以下），可能会导致无法触发。

netease:custom_tips

为方块的物品形式添加自定义描述文本（tooltip）。

键	类型	默认值	说明
value	string	物品名称	物品的描述信息

"netease:custom_tips": {
  "value": "这是一块特殊的矿石"
}

netease:listen_block_remove

配置方块是否监听 BlockRemoveServerEvent 事件。

键	类型	默认值	说明
value	bool	false	是否监听

"netease:listen_block_remove": {
  "value": true
}

netease:may_place_on

配置方块只能放置在哪些方块的上面。当下方方块发生改变时，如果不再满足条件，方块会自动被破坏。

键	类型	默认值	说明
block	array(string)	—	方块 identifier 列表，所有方块状态均可放置
block_state	array(object)	—	特定方块状态列表（每个元素只对应一个状态）
spawn_resources	bool	true	方块因下方变化被破坏时是否生成掉落物

"netease:may_place_on": {
  "block": ["minecraft:grass", "minecraft:dirt"],
  "spawn_resources": true
}

最终可放置的方块是 block 字段与 block_state 字段的并集。

贴图配置

方块的贴图配置涉及两个文件：terrain_texture.json（资源名映射）和 blocks.json（方块贴图与声音）。

terrain_texture.json

在资源包的 textures/ 目录下创建或编辑 terrain_texture.json，建立资源名与贴图路径的映射关系。资源名必须全局唯一。

{
  "resource_pack_name": "mymod",
  "texture_name": "atlas.terrain",
  "texture_data": {
    "mymod:custom_ore": {
      "textures": "textures/blocks/custom_ore"
    },
    "mymod:custom_ore_top": {
      "textures": "textures/blocks/custom_ore_top"
    }
  }
}

贴图文件放在资源包的 textures/blocks/ 目录中。

高清贴图

支持高于 16×16 分辨率的贴图，但过高的分辨率会导致手机端（尤其是低端机）无法进入游戏。如果面向手机用户，建议保持 16×16 或 32×32 分辨率。

blocks.json

在资源包根目录创建或编辑 blocks.json，配置每个方块的贴图引用和声音类型。贴图值需要与 terrain_texture.json 中配置的资源名一致。

六面相同贴图：

{
  "mymod:custom_ore": {
    "textures": "mymod:custom_ore",
    "sound": "stone"
  }
}

不同面使用不同贴图：

{
  "mymod:custom_ore": {
    "textures": {
      "up": "mymod:custom_ore_top",
      "down": "mymod:custom_ore_top",
      "north": "mymod:custom_ore",
      "south": "mymod:custom_ore",
      "west": "mymod:custom_ore",
      "east": "mymod:custom_ore"
    },
    "sound": "stone"
  }
}

sound 字段使用原版 sounds.json 中 block_sounds 里的类型名称，例如：stone、grass、wood、gravel、sand、cloth、glass、metal 等。不支持添加自定义 block_sounds 类型。

如果需要为方块设置自定义方块模型，还需在 blocks.json 中添加 netease_model 字段指向模型文件的 identifier：

{
  "mymod:custom_flower": {
    "textures": "mymod:custom_flower",
    "sound": "grass",
    "netease_model": "mymod:custom_flower_model"
  }
}

本地化

在资源包的 texts/zh_CN.lang 文件中，为方块配置中文显示名称。键的格式为：

tile.方块identifier.name=显示名称

示例：

tile.mymod:custom_ore.name=自定义矿石
tile.mymod:basic_stone.name=基础石材

TIP

如果忘记配置 lang 文件，游戏中方块名称会显示为 tile.mymod:custom_ore.name 这样的原始键名。

方块模型

自定义方块支持使用 netease:block_geometry 格式的自定义几何体模型，让方块拥有非正方体的外观。

基本流程

1. 使用 BlockBench 制作自由模型，贴图尺寸最大不超过 64×64
2. 通过 MC Studio 导入模型，自动生成模型 JSON 到 models/netease_block/
3. 在 blocks.json 中通过 netease_model 引用模型 identifier
4. 配合 minecraft:block_light_absorption（设为 0）避免模型变黑
5. 如需透明效果，配合 netease:render_layer 使用

模型文件结构

模型 JSON 位于 resource/models/netease_block/，基本结构：

{
  "format_version": "1.13.0",
  "netease:block_geometry": {
    "description": {
      "identifier": "mymod:custom_flower_model",
      "textures": ["mymod:custom_flower"],
      "use_ao": false
    },
    "bones": [
      {
        "name": "root",
        "pivot": [0, 0, 0],
        "cubes": [
          {
            "origin": [0.5, 0, -7.5],
            "size": [15, 16, 15],
            "uv": {
              "north": { "uv": [0, 0], "uv_size": [16, 16] }
            }
          }
        ]
      }
    ]
  }
}

注意事项

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

更多模型制作细节请参考 美术指南。

方块实体

方块实体（Block Entity）让自定义方块能够存储自定义数据，并响应 tick 事件。

基本用法

在方块 JSON 中添加 netease:block_entity 组件：

"netease:block_entity": {
  "tick": true,
  "client_tick": false,
  "movable": false
}

数据读写

通过 GetBlockEntityData 接口获取方块实体数据对象，使用类似 dict 的方式进行读写：

comp = self.CreateComponent(self.levelId, "Minecraft", "blockEntityData")
blockEntityData = comp.GetBlockEntityData(dimension, blockPos)
if blockEntityData:
    # 写入数据
    blockEntityData['myKey'] = {"count": 1, "active": True}
    # 读取数据
    value = blockEntityData['myKey']

相关事件

事件	触发时机
ServerPlaceBlockEntityEvent	玩家手动放置含方块实体的方块
ServerBlockEntityTickEvent	tick 为 true 时，每秒触发 20 次
ModBlockEntityTickClientEvent	client_tick 为 true 时，客户端每秒触发 20 次
ChunkGeneratedServerEvent	通过特征放置的方块实体，在区块生成完毕时触发

更多方块实体外观、动画、特效的高级用法，请参考 特殊方块类型。

多面向方块

通过 netease:face_directional 组件，方块可以根据玩家放置时的朝向自动旋转贴图。放置时，方块的 north 贴图面始终朝向玩家（即玩家准心的反方向）。

四面向（direction）

只支持水平 4 个方向的旋转。

"netease:face_directional": {
  "type": "direction"
}

四面向方块面向与附加值（auxvalue）的对应关系：

方块面向	auxvalue
south	0
west	1
north	2
east	3

六面向（facing_direction）

支持上下左右前后 6 个方向的旋转。

"netease:face_directional": {
  "type": "facing_direction"
}

六面向方块面向与附加值（auxvalue）的对应关系：

方块面向	auxvalue
down	0
up	1
north	2
south	3
west	4
east	5

模型方块限制

使用自定义方块模型时，仅支持四面向，不支持六面向。

卸载行为

若使用了自定义方块的存档在卸载 mod 后再进入：

1. 地图上已存在的自定义方块：

• 自定义方块会变为未知的方块。通过 GetBlockNew 接口查询时，identifier 仍是原来的自定义方块
• 生存模式下玩家可以用手瞬间破坏该未知方块，拾取后名称显示为"未知"，无法放置
• 若某个 subchunk 未进行过方块更新，重新加载 mod 时自定义方块可保留。一旦 subchunk 进行了方块更新，即使重新加载 mod，自定义方块也会永久消失

2. 玩家背包中的自定义方块物品：

• 物品会消失。重新加载 mod 后，卸载期间登录过的玩家物品不会恢复；未登录过的玩家物品可保留

3. 地图上容器内的自定义方块物品：

• 物品会消失。重新加载 mod 后，卸载期间探索过区域的容器中物品不会恢复；未探索区域的容器物品可保留

4. 地图上未拾取的掉落物：

• 掉落物会消失。重新加载 mod 后，已探索区域的掉落物不会恢复（除非 subchunk 内无其他 entity）；未探索区域的掉落物可保留

重要提醒

发布 mod 后请勿随意修改方块的 identifier，否则会导致玩家存档中已有的自定义方块全部丢失。

完整示例

下面是一个完整的自定义矿石方块示例，包含所有需要的文件。

行为包 — 方块定义

文件路径：行为包/netease_blocks/custom_ore.json

{
  "format_version": "1.10.0",
  "minecraft:block": {
    "description": {
      "identifier": "mymod:custom_ore",
      "register_to_create_menu": true,
      "category": "Nature"
    },
    "components": {
      "minecraft:destroy_time": {
        "value": 4.0
      },
      "minecraft:explosion_resistance": {
        "value": 6.0
      },
      "minecraft:block_light_emission": {
        "value": 0.5
      },
      "minecraft:block_light_absorption": {
        "value": 15
      },
      "minecraft:loot": {
        "value": "loot_tables/blocks/custom_ore.json"
      },
      "minecraft:map_color": "#4A90D9",
      "netease:tier": {
        "digger": "pickaxe",
        "destroy_special": true,
        "level": 2
      },
      "netease:fire_resistant": {
        "value": true
      },
      "netease:custom_tips": {
        "value": "需要铁镐或更好的工具挖掘"
      }
    }
  }
}

资源包 — terrain_texture.json

文件路径：资源包/textures/terrain_texture.json

{
  "resource_pack_name": "mymod",
  "texture_name": "atlas.terrain",
  "texture_data": {
    "mymod:custom_ore": {
      "textures": "textures/blocks/custom_ore"
    }
  }
}

贴图文件放在：资源包/textures/blocks/custom_ore.png

资源包 — blocks.json

文件路径：资源包/blocks.json

{
  "mymod:custom_ore": {
    "textures": "mymod:custom_ore",
    "sound": "stone"
  }
}

资源包 — 本地化

文件路径：资源包/texts/zh_CN.lang

tile.mymod:custom_ore.name=自定义矿石

行为包 — 掉落表（可选）

文件路径：行为包/loot_tables/blocks/custom_ore.json

{
  "pools": [
    {
      "rolls": 1,
      "entries": [
        {
          "type": "item",
          "name": "mymod:custom_ore",
          "weight": 1,
          "functions": [
            {
              "function": "set_count",
              "count": {
                "min": 1,
                "max": 3
              }
            }
          ]
        }
      ]
    }
  ]
}

常见问题

方块贴图显示为紫黑色棋盘格

原因： 贴图路径配置错误，引擎找不到对应的贴图文件。

排查步骤：

1. 确认贴图文件已放入 textures/blocks/ 目录
2. 确认 terrain_texture.json 中的贴图路径拼写正确（路径不含 .png 后缀）
3. 确认 blocks.json 中引用的贴图资源名与 terrain_texture.json 中一致
4. 确认资源名全局唯一，没有与其他 mod 冲突

方块不出现在创造模式物品栏

原因： register_to_create_menu 未设为 true。

"description": {
  "identifier": "mymod:custom_ore",
  "register_to_create_menu": true
}

方块名称显示为原始键名

原因： 未在 zh_CN.lang 中配置对应的翻译键。

确认格式为：tile.命名空间:方块名.name=显示名称

方块模型变黑

原因： 使用自定义方块模型时，没有配置 minecraft:block_light_absorption。

添加以下组件即可解决：

"minecraft:block_light_absorption": {
  "value": 0
}

identifier 冲突导致加载失败

原因： 两个不同的方块使用了相同的 identifier。

identifier 必须全局唯一。建议使用你的 mod 名称作为命名空间前缀，如 mymod:block_name。

方块被活塞推动后消失

原因： 如果方块配置了 netease:redstone_property 为 break_on_push，被活塞推动时会变成掉落物。

如果不想被推动，可以使用 block_push：

"netease:redstone_property": {
  "value": "block_push"
}

下一步

• 特殊方块类型 — 刷怪笼、传送门、作物等 12 种特殊方块
• 自定义基础物品 — 自定义物品的注册与配置
• 自定义基础生物 — 自定义生物的开发流程