附加包教程：11.方块（二）
前言
上期，我们成功向附加包中添加了方块，了解了方块组件。这一期，我们将类比学习物品组件地学习方块组件。
1. 组件列表
geometry
模型组件：指定方块的模型
- 决定方块的模型、骨骼可见性、剔除面设置和渲染设置
- 必须与
minecraft:material_instances组件配合使用 - 模型路径：
resource_pack/models/blocks/*.geo.json
"minecraft:geometry": {
"identifier": "geometry.custom_block",
"bone_visibility": {
"bone_name": "q.block_state('complementary:lit_bit')"
},
"culling": "complementary:test_cull"
}
| 字段 | 功能描述 | 类型 |
|---|---|---|
| identifier | 方块模型ID | 字符串 |
| bone_visibility | 骨骼可见性设置 | 对象 |
| culling | 剔除规则ID | 字符串 |
原版模型ID：
minecraft:geometry.full_block(替代unit_cube)minecraft:geometry.cross(交叉模型)
material_instances
材质实例组件：指定方块的渲染设置
"minecraft:material_instances": {
"*": {
"texture": "atlas_texture",
"render_method": "alpha_test"
},
"up": { "texture": "top_texture" }
}
| 参数 | 说明 | 类型 |
|---|---|---|
| texture | 纹理短名 | 字符串 |
| render_method | 渲染方法 | 字符串 |
| ambient_occlusion | 环境光遮蔽强度 | 浮点数 |
渲染方法性能排序：
blend > alpha_test > double_sided > opaque
transformation
变换组件：变换方块的模型
"minecraft:transformation": {
"translation": [0.0, 0.125, -0.125],
"scale": [0.5, 0.1, 0.5],
"rotation": [0, 90, 90]
}
| 字段 | 功能描述 | 类型 |
|---|---|---|
| translation | 平移距离（单位：方块） | 浮点数组 |
| scale | 缩放比例 | 浮点数组 |
| rotation | 旋转角度（90的倍数） | 整数数组 |
⚠️ 使用minecraft:geometry.full_block时：
- 禁止使用平移/缩放
- 仅支持90度整数倍旋转
item_visual
物品外观组件
"minecraft:item_visual": {
"geometry": "geometry.custom_item",
"material_instances": {
"*": { "texture": "item_texture" }
}
}
| 字段 | 对应组件 | 描述 |
|---|---|---|
| geometry | geometry | 物品模型设置 |
| material_instances | material_instances | 物品材质设置 |
map_color
地图颜色组件
// 完整写法
"minecraft:map_color": {
"color": "#FF5733",
"tint_method": "grass"
}
// 简写
"minecraft:map_color": "#FF5733"
| 格式 | 示例 | 说明 |
|---|---|---|
| 十六进制 | #RRGGBB |
直接定义颜色 |
| 染色方法 | "grass" |
使用生态染色 |
可用染色方法：
grass（草地）water（水域）default_foliage（默认植被）
selection_box
判定箱组件
"minecraft:selection_box": {
"origin": [-8, 0, -8],
"size": [16, 16, 16]
}
| 参数 | 单位 | 限制 |
|---|---|---|
| origin | 像素（1/16方块） | [-8, -8, -8] 到 [8, 8, 8] |
| size | 像素 | 总尺寸 ≤16 |
collision_box
碰撞箱组件
"minecraft:collision_box": {
"origin": [0, 0, 0],
"size": [16, 16, 16]
}
特殊特性：
- 允许通过
transformation突破尺寸限制 - 与流体交互时优先使用碰撞箱
destructible_by_mining
挖掘属性组件
"minecraft:destructible_by_mining": {
"seconds_to_destroy": 3.0,
"item_specific_speeds": [
{"item": "pickaxe", "speed": 5}
]
}
| 字段 | 默认值 | 说明 |
|---|---|---|
| seconds_to_destroy | 0.05（瞬间破坏） | 基础挖掘时间 |
| item_specific_speeds | 无 | 工具加速倍率 |
flammable
燃烧属性组件
"minecraft:flammable": {
"catch_chance_modifier": 30,
"destroy_chance_modifier": 20
}
| 参数 | 效果 | 范围 |
|---|---|---|
| catch_chance_modifier | 引燃概率 | 0-100 |
| destroy_chance_modifier | 烧毁概率 | 0-100 |
light_emission
发光组件
"minecraft:light_emission": 15
| 值域 | 效果 |
|---|---|
| 0 | 无光源 |
| 15 | 最大亮度 |
crafting_table
工作台组件
"minecraft:crafting_table": {
"crafting_tags": ["custom_table"],
"table_name": "ui.custom_workbench"
}
| 字段 | 本地化要求 | 用途 |
|---|---|---|
| table_name | 需在.lang文件定义 | 界面显示名称 |
tick
计划刻组件
"minecraft:tick": {
"interval_range": [20, 40],
"looping": true
}
时间计算：
- 1秒 = 20 ticks
- 随机范围示例：1-2秒触发
custom_components
自定义组件
"minecraft:custom_components": [
"custom:growth_stage"
]
开发说明：
- 需配合脚本使用
- 命名建议使用命名空间
- 可堆叠多个组件
entity_fall_on
坠落事件组件
"minecraft:entity_fall_on": {
"min_fall_distance": 4
}
触发条件：
- 方块高度 ≥4像素（0.25方块）
- 坠落距离 ≥设定值
中场休息
以上就是所有可用的组件了。有可能会有遗漏，我会尽力补充。也可以给方块添加标签，标签和组件同级。标签应该是下面这样的。
"tag:标签名字": {} //这里的标签名字最好使用命名空间ID。
::: info
标签似乎没有现成的用途。
自定义方块的标签会被原版物品忽略。
添加特定的标签可能可以给这个方块一些原版方块拥有的功能，然而不确定这样的标签的存在。
目前还没有已知办法给自定义方块加上合成标签，使其被配方文档中的{"tag":"..."}识别。
对于此功能，请创建方块物品。
:::
以下是方块的开发计划，可能不准确或不会实现。
- 移除blocks.json。
- 发布自定义重力方块的教程文档。
- 同步 Java 版的方块标签。
- 添加改变原版方块战利品表的功能。（短期）
- 使自定义组件可以传参，并使其看起来更像其他组件，很可能需要脚本v2.0.0。（2025 年）
- 添加colormap对自定义方块的支持，例如树叶和草地颜色。（2025 年，中长期）
- 添加数据驱动原版方块模型ID。原版方块模型可能用了一些硬编码功能，也将添加这些功能。（长期）
- 重新添加minecraft:unwalkable和minecraft:immovable这样的组件。
- 通过minecraft:material_instances组件设置方块的纹理变种。（长期）
- 自定义方块音效。（长期）
- 添加“一个方块有多个碰撞箱”的功能。（长期）
- 进一步设置方块红石属性，如定义接收红石信号的反应/发出红石信号。
- 添加onBlockDestroyed触发器。（很久之后）
- 尝试添加beforeOnPlayerInteract触发器。
- 使方块可以含雪或含熔岩。
- 逐渐实现原版所有方块的数据驱动。
- 目前不会添加onBlockUpdate触发器，遇到了技术困难。
- 目前不会添加通过SAPI修改方块模型的功能。
- 绝对不会添加方块模型的polymesh。
2.触发器组件
::: danger
注意：此段落所述功能已被移除，请使用脚本代替其功能。
然而，出于学习并理解旧版附加包的必要性，我保留了这个段落。
:::
on_fall_on
坠落事件触发器
"minecraft:on_fall_on": {
"min_fall_distance": 4,
"condition": "q.is_sneaking",
"event": "trigger_fall",
"target": "self"
}
| 字段 | 必填 | 说明 |
|---|---|---|
| min_fall_distance | 是 | 最小触发高度（单位：方块） |
| condition | 否 | Molang条件表达式 |
| event | 是 | 事件名称（需在事件表中定义） |
| target | 否 | 目标对象（self/other） |
实现要求：
- 方块高度 ≥4像素（0.25方块）
- 需配合
minecraft:entity_fall_on组件使用
on_interact
交互事件触发器
"minecraft:on_interact": {
"condition": "q.has_item('minecraft:stick')",
"event": "activate_lever",
"target": "other"
}
典型应用场景：
- 开关类方块（拉杆/按钮）
- 可交互道具（工作台/熔炉）
on_placed
放置事件触发器
"minecraft:on_placed": {
"event": "init_block_data",
"target": "self"
}
应用案例：
- 初始化方块NBT数据
- 触发连锁放置事件
random_ticking
随机刻触发器
"minecraft:random_ticking": {
"on_tick": {
"event": "grow_plant"
}
}
特性：
- 平均每1-60秒触发一次
- 适用于自然生长类逻辑
queued_ticking
计划刻触发器
"minecraft:queued_ticking": {
"interval_range": [20, 40],
"looping": false,
"on_tick": {
"event": "countdown_explode"
}
}
| 参数 | 单位 | 说明 |
|---|---|---|
| interval_range | tick | [最小值, 最大值] |
| looping | - | 是否循环执行 |
应用场景：
- 倒计时爆炸（TNT）
- 阶段性状态变化
总结
这一期，我把所有方块组件罗列了一遍。下一期，我们不讲方块事件，而是先把模型讲了，因为这篇教程里多次提到了模型。下下期讲战利品表，然后再讲方块事件。
