方块组件

应用组件 ​

方块组件用于改变方块在世界中的外观和功能。它们被应用在minecraft:block或其permutation(变体)的components子项中。

{
    "format_version": "1.21.70",
    "minecraft:block": {
        "description": {
            "identifier": "wiki:lamp",
            "menu_category": {
                "category": "items"
            }
        },
        "components": {
            "minecraft:light_dampening": 0,
            "minecraft:light_emission": 15,
            "minecraft:map_color": [210, 200, 190],
            "minecraft:geometry": "geometry.lamp",
            "minecraft:material_instances": {
                "*": {
                    "texture": "wiki:lamp"
                },
                "shade": {
                    "texture": "wiki:lamp_shade"
                }
            }
        }
    }
}

组件列表 ​

碰撞箱 ​

定义方块与实体碰撞的区域。若设为true则使用默认值；若设为false则禁用方块与实体的碰撞；若省略该组件则使用默认值。

从实验性玩法Holiday Creator Features中释放，适用于格式版本1.19.50及以上。

类型：布尔值/对象

• origin: 向量 [a, b, c]
  • 碰撞箱边界的最小位置。origin以[x, y, z]格式指定，必须在(-8, 0, -8)到(8, 16, 8)范围内（含边界值）。
• size: 向量 [a, b, c]
  • 碰撞箱各边的尺寸。size以[x, y, z]格式指定。origin+size必须在(-8, 0, -8)到(8, 16, 8)范围内（含边界值）。

布尔值用法示例 ​

"minecraft:collision_box": true

对象用法示例 ​

"minecraft:collision_box": {
    "origin": [-8, 0, -8],
    "size": [16, 16, 16]
}

工作台 ​

将方块设为自定义工作台，启用工作台UI和配方合成功能。

从实验性玩法Holiday Creator Features中释放，适用于格式版本1.19.50及以上。

类型：对象

• crafting_tags: 数组
  • 必填字段
  • 定义需要在该工作台上合成的配方标签。最多64个标签，每个标签最多64个字符。
• table_name: 字符串
  • 指定语言文件键值，映射到该工作台UI中显示的文本。若字符串无法解析为本地化字符串，则直接显示原始字符串。若省略该字段，默认显示"display_name"组件指定的名称；若方块无"display_name"组件，则显示方块名称。

"minecraft:crafting_table": {
    "table_name": "Wiki工作台",
    "crafting_tags": [
        "crafting_table",
        "wiki_workbench"
    ]
}

可被爆炸破坏 ​

描述方块的抗爆属性。若设为true则使用默认爆炸抗性；若设为false则方块不会被爆炸破坏；若省略该组件则使用默认爆炸抗性。

类型：布尔值/对象

• explosion_resistance: 双精度浮点数
  • 描述方块对爆炸的抗性。值越大意味着方块在爆炸附近越不容易被破坏（或具有更高的爆炸抗性）。不同爆炸威力等级的抗性比例不同。负值或0表示极易被炸毁；数值越大抗性越高。

布尔值用法示例 ​

"minecraft:destructible_by_explosion": false

对象用法示例 ​

"minecraft:destructible_by_explosion": {
    "explosion_resistance": 20
}

可被挖掘破坏 ​

描述方块的抗挖掘属性。

若省略或设为true，方块将被瞬间破坏。 若设为false，方块无法被挖掘破坏。

类型：布尔值/对象

• seconds_to_destroy: 双精度浮点数
  • 设置方块的硬度。数值越大挖掘时间越长。

布尔值用法示例 ​

"minecraft:destructible_by_mining": false

对象用法示例 ​

"minecraft:destructible_by_mining": {
    "seconds_to_destroy": 20
}

显示名称 ​

指定语言文件键值，映射到物品栏和快捷栏中悬停时显示的文本。若字符串无法解析为本地化字符串，则直接显示原始字符串。若省略该组件，则使用方块名称作为显示名称。

从实验性玩法Holiday Creator Features中释放，适用于格式版本1.19.60及以上。

类型：字符串

字符串用法示例 ​

"minecraft:display_name": "自定义方块"

本地化字符串用法示例 ​

"minecraft:display_name": "tile.wiki:custom_block.name"

tile.wiki:custom_block.name=自定义方块

实体跌落触发 ​

当实体跌落到该方块上时触发事件。

类型：对象

• min_fall_distance: 双精度浮点数
  • 触发事件所需的最小跌落距离（以方块为单位）。

从实验性玩法Beta APIs中释放，适用于格式版本1.21.10及以上。

"minecraft:entity_fall_on": {
    "min_fall_distance": 5
}

可燃性 ​

描述方块的可燃属性。若设为true则使用默认值；若设为false或省略该组件，方块不会被邻近火焰自然引燃，但仍可直接点燃。

类型：布尔值/对象

• catch_chance_modifier: 整数
  • 影响方块在火源旁被引燃几率的修饰符。值大于等于0，数值越高越容易被引燃。对于catch_chance_modifier大于0的情况，火焰将持续燃烧直到方块被摧毁（若destroy_chance_modifier为0则永久燃烧）。若catch_chance_modifier为0且方块被直接点燃，火焰最终会熄灭而不破坏方块（若destroy_chance_modifier大于0则有机会被破坏）。默认值5与木板相同。

布尔值用法示例 ​

"minecraft:flammable": true

对象用法示例 ​

"minecraft:flammable": {
    "catch_chance_modifier": 5,
    "destroy_chance_modifier": 20
}

摩擦系数 ​

描述方块的摩擦系数（范围0.0-0.9）。摩擦系数影响实体在方块上移动的速度。值越大摩擦力越强。

类型：双精度浮点数

"minecraft:friction": 0.4

几何模型 ​

用于渲染该方块的几何模型描述标识符。此标识符必须匹配任意已加载资源包中的现有几何标识符，或引用当前支持的原版模型之一。

自定义方块模型限制：

• 方块尺寸限制为30×30×30 像素。

• 方块在每个轴上至少要有1像素包含在基础的16×16×16方块内。

• 30×30×30方块的绝对位置边界为原点各方向30像素。只要遵守规则#2，方块可放置在这些边界内的任意位置。

注意：不传导红石信号。即使使用原版full_block标识符。同时会使方块可呼吸。生物也无法在其上生成。有趣的是，尽管在生成性和传导性方面属于"非固体"方块，蝙蝠仍能倒挂在上面。

从实验性玩法Holiday Creator Features中释放，适用于格式版本1.19.40及以上。

类型：字符串/对象

• identifier: 字符串
  • 几何模型的标识符。
• bone_visibility: 对象
  • 可选的布尔值"数组"，定义几何文件中各骨骼的可见性。要设置bone_visibility，必须以几何文件名作为标识符。指定标识符后，可根据指定几何文件中骨骼名称以true/false为基础定义bone_visibility。
  • 注意所有骨骼默认为true，因此仅当设置为false时才需要定义骨骼。包含设置为true的骨骼与默认行为相同。

字符串用法示例 ​

"minecraft:geometry": "geometry.example_block"

对象用法示例 ​

"minecraft:geometry": {
    "identifier": "geometry.example_block"
}

骨骼可见性 ​

隐藏模型中骨骼的直接子立方体。

Molang表达式必须遵守permutation conditions(变体条件)限制。

在格式版本1.20.10及以上支持bone_visibility中的Molang表达式。

"minecraft:geometry": {
    "identifier": "geometry.example_block",
    "bone_visibility": {
        "wiki_bone": false,
        "conditional_bone": "q.block_state('wiki:example_state') == 3",
        "another_bone": true
    }
}

物品可视化 ​

决定方块作为物品时的显示方式。

类型：对象

• geometry: 字符串/对象 - 显示的几何模型组件。
• material_instances: 对象 - 显示的材质实例组件。

从实验性玩法Upcoming Creator Features中释放，适用于格式版本1.21.60及以上。

"minecraft:item_visual": {
    "geometry": "minecraft:geometry.full_block",
    "material_instances": {
        "*": {
            "texture": "wiki:block_texture"
        }
    }
}

光线衰减 ​

光线穿过方块时的衰减量（范围0-15）。值越大光线衰减越多。

类型：整数

"minecraft:light_dampening": 7

发光强度 ​

方块发出的光照强度（范围0-15）。值越大发出的光越强。

类型：整数

"minecraft:light_emission": 10

液体检测 ​

决定方块与不同类型液体的交互方式。

类型：对象

• detection_rules: 数组
  • liquid_type: 字符串 - 该规则适用的液体类型。目前仅支持water。
  • can_contain_liquid: 布尔值 - 该液体类型是否能与方块共处同一空间（如水淹）。
  • on_liquid_touches: 字符串 - 当液体流入方块时触发的行为。
  • stops_liquid_flowing_from_direction: 数组 - 定义液体不能从哪些方向流出该方块。

从实验性玩法Upcoming Creator Features中释放，适用于格式版本1.21.60及以上。

"minecraft:liquid_detection": {
    "detection_rules": [
        {
            "liquid_type": "water",
            "can_contain_liquid": true, // 可被水淹
            "on_liquid_touches": "no_reaction", // 水像穿过空气一样流过方块
        }
    ]
}

战利品表 ​

战利品表的路径，相对于行为包。精准采集会覆盖此设置。

若省略，则掉落方块本身。

类型：字符串

"minecraft:loot": "loot_tables/blocks/custom_block.json"

地图颜色 ​

设置方块在地图上渲染的颜色。颜色以#RRGGBB格式的十六进制值表示。也可表示为0到255的[R, G, B]数组。若省略该组件，方块不会显示在地图上。

类型：字符串/对象/向量 [a, b, c]

字符串用法示例 ​

"minecraft:map_color": "#FFFFFF"

对象用法示例 ​

"minecraft:map_color": {
    "color": "#FFFFFF"
}

向量用法示例 ​

"minecraft:map_color": [255, 255, 255]

材质实例 ​

配置方块的渲染方式，包括纹理和光照。

• 所有实例必须使用相同的渲染方法。
• 方块面在与其他方块相交时会无条件变暗。
• down面的纹理用于破坏粒子效果。

材质实例可与RP/blocks.json条目结合使用，创建具有类不透明属性的方块。这主要用于在自定义玻璃方块上启用面剔除。

从实验性玩法Holiday Creator Features中释放，适用于格式版本1.19.40及以上。

渲染方法 ​

渲染方法本质上控制方块在世界中的显示方式，类似于实体材质。以下是各类型的关键属性：

• 透明度 - 完全透明的区域。
• 半透明 - 半透明的区域。
• 背面剔除 - 从背面观察时不可见的面。
• 远距剔除 - 在达到完整渲染距离前方块变为不可见。

"minecraft:material_instances": {
  // '*' 实例必需 - 立方体面的默认实例
  // 内置实例名称为 'up', 'down', 'north', 'east', 'south' 和 'west'
  "*": {
    "texture": "wiki:texture_name", // 在`RP/textures/terrain_texture.json`中定义的短名称
    "render_method": "blend", // 上表中的渲染方法之一
    "face_dimming": true, // 默认为true；具有此材质的面是否应根据其方向变暗？
    "ambient_occlusion": true // 默认为true(1)；是否根据周围方块创建阴影？浮点数决定环境遮挡强度。
  }
}

自定义实例名称 ​

可在材质实例中定义自定义实例名称，并可被内置实例名称或方块模型引用。