附加包教程：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）
• 阶段性状态变化

总结

这一期，我把所有方块组件罗列了一遍。下一期，我们不讲方块事件，而是先把模型讲了，因为这篇教程里多次提到了模型。下下期讲战利品表，然后再讲方块事件。

附加包教程：10.方块（一）

前言

前面 4 期，我们已经学完了有关物品的知识。这次，我们就来学习如何添加一个方块。这是一个很复杂的内容，它的难度比物品要大得多。
然而，如果只需要一个简单的方块，那么方块和物品就大同小异了。接下来，我们将花若干期的时间学习关于方块的所有内容。

准备

学习方块是一个由简到难的过程。
在行为包根目录下打开 blocks 文件夹，新建一个文件。命名就是你的方块的英文名，这样比较好管理。
你也可以新建一个文件夹，把它命名英文名，把所有相关的文件都放进去，方便管理。

方块的文档结构和物品大同小异，具体格式见下。

但方块的命名分化十分严重：

• 你可能看到 minecraft:aim_collision、minecraft:selection_box、minecraft:pick_collision。
• 其实这三个作用相同，都是指定方块的判定框。
• 区别是它们出现在不同版本：
  • minecraft:pick_collision → 1.17.0
  • minecraft:aim_collision → 1.18.0
  • minecraft:selection_box → 1.19.40

再如：

• minecraft:destroy_time 是旧版本写法（1.16.100）
• minecraft:destructible_by_mining 是新版本写法（1.19.40）

所以命名确实很混乱。
我在这篇文档里一律采用 1.21.0 版本格式。

注意： 格式版本控制着方块能访问哪些特性，建议始终保持最新。

第一个方块

现在就可以开始了。在你新建的文件里写以下代码：

<details>
<summary>点击展开代码</summary>

{
  "format_version": "1.21.0",
  "minecraft:block": {
    "description": {
      "identifier": "namespace:identifier",
      "menu_category": {
        "category": "items",
        "group": "",
        "is_hidden_in_commands": false
      }
    },
    "components": {
      "minecraft:loot": "loot_tables/example_block_loot.json",
      "minecraft:friction": 0.4,
      "minecraft:map_color": "#00ff00"
    }
  }
}

</details>

上面是一个基础方块的结构。
如果你想让方块有更丰富功能，就要用更多组件。
如果你想让它在某些情形下响应，就要用“触发器组件”。

渲染

这一期我们还要给方块添加纹理。
最常见的方法是在资源包根目录的 blocks.json 中添加如下内容：

{
  "方块ID": {
    "textures": "起一个短名",
    "sound": "amethyst"
  }
}

然后打开 textures/terrain_texture.json 文件，加入以下内容：

<details>
<summary>点击展开代码</summary>

{
  "texture_data": {
    "这里写之前起的短名": {
      "textures": "textures/blocks/test"
    }
  }
}

</details>

接着：

• 在 textures 文件夹中新建 blocks 文件夹
• 放入一张正方形图片，命名为你指定的短名（例如 test.png）

建议图片为 .png 格式，兼容性最好。
优先级为 .tga > .png > .jpg.

最后，为了让游戏内名字显示正常：

• 打开资源包的 texts/zh_CN.lang
• 添加：

tile.命名空间ID.name=方块名字

注意不能换行，也不能使用 \ 进行转义。

打开游戏，你应该可以在物品栏看到你的方块了。
::: info 注意
如果纹理有透明区域，游戏中可能会变黑或失真。这个我们将在下一期学习如何解决
:::

总结

下一期我们将开始讲解方块组件。
与物品组件不同，我会按照类别讲解，比如：

• 渲染相关组件
• 碰撞箱组件

如果你有点跟不上，我会提供模板包，照着修改就可以啦！

📎 附件：点击下载模板包

附加包教程：9.物品（四）

📖 前言

上期，我们学习了我已知的所有物品事件方法。也就是说，我们已经完成了物品相关的知识储备。

这一期，我们要进行一次实战演练！

---

🎯 演练目标

根据演练目标，使用对应的组件和事件，完成一个自定义武器。

::: info 目标

• 命名空间 ID：test_pack:test_sword
• 伤害为 26
• 创造模式下 不能破坏方块
• 附魔闪光（即使没有附魔）
• 附魔能力为 70
• 耐久为 5000
• 耐久损耗概率 50%
• 潜行攻击实体：范围 5 格伤害 + 掉 5 点耐久
• 潜行打方块：1/4 几率清除所有状态，添加力量 5 和急迫 5（持续 30 秒）+ 掉 5 点耐久
• 可副手持有
• 不会刷新掉
  :::

---

🧠 思路分析

让我们按照顺序，逐步实现以上所有功能。

---

🏗️ 基础设置

既然是一把剑，那么在 components 中先添加标签：

"tag:minecraft:sword"

添加基础组件

"minecraft:damage": 26,
"minecraft:can_destroy_in_creative": false,
"minecraft:glint": true

添加附魔能力

"minecraft:enchantable": {
  "value": 70,
  "slot": "sword"
}

添加耐久系统

"minecraft:durability": {
  "damage_chance": 0.5,
  "max_durability": 5000
}

---

⚙️ 通用组件

"minecraft:should_despawn": false,
"minecraft:allow_off_hand": true

---

🧱 特殊破坏功能

::: tip 小技巧
作为一把剑，应该快速破坏蜘蛛网和竹子。这部分我们还要加上破坏时触发的事件。
:::

添加相关组件和事件

"minecraft:hand_equipped": true,
"minecraft:max_stack_size": 1,
"minecraft:digger": {
  "use_efficiency": false,
  "destroy_speeds": [
    {
      "block": "minecraft:web",
      "speed": 30,
      "on_dig": {
        "event": "damage"
      }
    },
    {
      "block": "minecraft:bamboo",
      "speed": 30,
      "on_dig": {
        "event": "damage"
      }
    }
  ]
}

"damage": {
  "damage": {
    "type": "durability",
    "amount": 1,
    "target": "self"
  }
}

---

🛠️ 创造栏分类

"minecraft:creative_category": {
  "parent": "itemGroup.name.sword"
}

---

🧨 潜行攻击逻辑（重点）

::: danger 注意
minecraft:weapon 组件在 1.20.40.21 版本中已被移除，若你使用的是此版本或更高版本，请使用脚本实现类似逻辑。
:::

添加组件

"minecraft:weapon": {
  "on_hit_block": "destroy",
  "on_hurt_entity": "hurt",
  "on_not_hurt_entity": "damage"
}

事件定义（点击查看）

---

<details>
<summary>📜 事件结构：使用 sequence 和 randomize</summary>

"hurt": {
  "sequence": [
    {
      "damage": {
        "type": "durability",
        "amount": 5,
        "target": "self"
      }
    },
    {
      "condition": "q.is_sneaking",
      "run_command": {
        "command": "damage @e[r=5,rm=0.1] 26 entity_attack entity @p"
      }
    }
  ]
},
"destroy": {
  "randomize": [
    {
      "weight": 3,
      "sequence": [
        {
          "run_command": {
            "command": "effect @p clear"
          }
        },
        {
          "run_command": {
            "command": [
              "effect @p strength 30 4",
              "effect @p haste 30 4"
            ]
          }
        },
        {
          "damage": {
            "type": "durability",
            "amount": 5,
            "target": "self"
          }
        }
      ]
    },
    {
      "weight": 1
    }
  ]
}

</details>

---

✅ 总结

这一期我们打造了一把拥有多个特殊功能的自定义剑，学习了大量组件的组合使用和事件系统的写法。在下期教程中，我们将继续深入学习更多复杂的组件使用方法。

---

下载

模板包，请解压.zip

附加包教程:物品(三)

::: danger 弃用警告
此页面所述功能在现版本已被弃用.

仅适用于 1.21.0 及以下版本

保留此页面作为旧版本参考
:::

前言

上期，我们学习了所有我已知的物品组件。这一期，我们将继续学习物品相关知识。这次，我们要学习物品事件。事件存储在与组件同级的地方。下面是一个例子。

{
  "format_version": "1.16.100",
  "minecraft:item": {
    "description": {不要在意这些细节},
    "components": {不要在意这些细节},
    "events": { //在意这个就对了，这就是事件存放的地方。
      "loot": { //“loot”是这个事件的名字。
        "run_command": { //一个事件方法（意思是运行命令）
          "command": [ //要运行的命令组
            "loot spawn ~~~ loot \"items/ancientcity_map\" minecraft:air" //一个命令，注意转义符的用法。
          ]
        },
        "decrement_stack": {} //又一个事件方法（意思是将当前物品减少1个）
      }
    }
  }
}

事件方法列表

• swing

  让玩家播放摇晃动画

"swing": {}

• shoot

  射出实体

"shoot": {
  "projectile": "minecraft:snowball", //实体ID。要射出的实体必须要有minecraft:projectile组件，否则只会在原地生成实体。
  "launch_power": 5, //射出去的力量。力量越大，射程越远。
  "angle_offset": 20 //指定可能的角度偏移大小。（不确定）
}

• damage

  伤害实体或磨损物品耐久

"damage": {
  "type": "magic", //造成的伤害类型。
  "target": "other", //伤害的目标。如果是self，那么就是磨损自身的耐久值。
  "amount": 4 //伤害的生命值。如果目标是自身，那么是磨损的耐久值。
}

• decrement_stack

  减少 1 个物品。

"decrement_stack":{
  "ignore_game_mode": false //设置为false，在创造模式下就没有作用。设置为true，就无论什么游戏模式都会起作用。
}

• transform_item

  1 把物品转化为另一物品

"transform_item": {
    "transform": "minecraft:apple" //要转化为的物品ID。
}

• teleport

  传送目标

"teleport": {
  "target": "holder", //传送的目标。一般是holder（物品持有者）。
  "max_range": [8, 8, 8] //填写长、宽、高。传送时以传送目标为中心，按照这个数组指定的范围画一个立方体，在立方体内随机传送1次。
}

• add_mob_effect

  给目标增加状态效果

"add_mob_effect": {
  "effect": "poison", //效果ID
  "target": "holder", //目标。一般是holder（物品持有者）。
  "duration": 8, //持续时间，填写正整数，单位是秒。
  "amplifier": 3 //效果的倍率。这个数字-1就是效果的等级。（如倍率是2，等级是1。倍率是6，等级是5。）
}

• remove_mob_effect

  给目标移除状态效果

"remove_mob_effect": {
  "effect": "poison", //要移除的效果ID。
  "target": "holder" //目标。一般是holder（物品持有者）。
}

• run_command

  运行命令

"run_command": {
  "command": [ //要运行的命令或命令组。
    "say test", //命令组中的一条命令。
    "say testtest" //命令组中的又一条命令。
  ],
  "target": "other" //目标。
}

• trigger

  触发另一个事件

"trigger": {
  "event": "mine_the_end" //要触发的事件名称。
}

以上就是所有可用的物品事件方法了。还有两个特殊结构，这两个特殊结构可以算作特殊的事件方法，我在下面列出。
下面这个用于有序执行事件方法。

特殊结构

有序执行事件

"sequence": [
  {
    "condition": "表达式a" //Molang表达式。如果输出true，那么就会执行事件方法a。输出false则不会。
    "target": "holder" //目标。
    "事件方法a": ...
  },
  {
    "condition": "表达式b" //又一个Molang表达式。如果输出true，那么就会执行事件方法b。输出false则不会。
    "target": "holder" //目标。
    "事件方法b": ...
  }
] //这一大堆东西的效果是：游戏将先评估表达式a，如果输出true，那么执行事件方法a，执行完之后进行下一个。如果输出false，那么进行下一个。然后评估表达式b，如果输出true，那么执行事件方法b，执行完之后进行下一个。如果输出false，那么进行下一个。以此类推，直到执行完毕。

随机执行事件

"randomize":[
  {
    "weight": 1 //执行这个事件的权重。
    "事件方法c": ...
  },
  {
    "weight": 3 //执行这个事件的权重。
    "事件方法d": ...
  }
] //这一大堆东西的效果是：游戏有1/(1+3)的概率（说人话就是4分之1）执行事件方法c，有3/(1+3)的概率（说人话就是4分之3）执行事件方法d。某个对象的概率的计算公式是这个对象的weight值除以所有对象的weight值之和。

---

以上的两个事件可以互相套用，没什么限制，随便用。

"sequence":[{"randomize":[{"weight":2,"事件方法": ...},{"weight":3,"事件方法": ...}]}] //这一类用法没什么不行的。

"sequence":[{"sequence":[{"sequence":[{"sequence":[{"sequence":[{"事件方法": ...}]}]}]}]}] //这个也没什么不行的，你开心就好。

总结

这一期，我把所有物品事件方法罗列了一遍。下一期，我们就开始实战演练！如果你想要模板包告诉你这两期的知识到底怎么用，去下期就对了！

附加包教程：7.物品（二）

前言

上期，我们成功向附加包中添加了物品，了解了物品组件。这一期，我们将继续学习物品组件。我们把所有组件和事件学习完之后，我会教你如何运用这些组件和事件。

** 组件列表**

1.普通组件

• allow_off_hand 允许副手组件：使物品可以被放在副手。

"minecraft:allow_off_hand": true

• block_placer 放置方块组件：使物品可以被放置为方块。

需要格式版本：1.20.10+
"minecraft:block_placer": {
  "block": "bedrock",
  "use_on": [
    "dirt", //泥土
    "grass" //草方块
  ],
  "replace_block_item": false
}

字段	功能描述	类型
block	要放置的方块ID，不能是隐藏方块(如下界反应核)，否则放置时游戏崩溃。可以填写方块描述符。	字符串或方块描述符
use_on	仅允许在某些方块上放置，留空表示允许全部方块。	字符串列表或方块描述符列表
replace_block_item	替换被放置方块的物品形态。设为true时，物品的ID必须与被放置方块的ID一致。	布尔值

旧名称：相同
版本：~1.16.100
旧语法：
"minecraft:block_placer": {
"block": "bedrock", //要放置的方块ID。
"use_on": [ //指定允许在哪些方块上放置。
 "dirt", //泥土
 "grass" //草方块
],
"use_block_description": true
}
旧名称：minecraft:seed
版本：≤1.10
旧语法：
"minecraft:seed": {
"crop_result": "cave_vines", //种植的作物ID（放置的方块ID）
"plant_at": [ //可以种植（放置）在...方块上
 "cave_vines", //洞穴藤蔓
 "cave_vines_head_with_berries"  //带果实的洞穴藤蔓头
],
"plant_at_any_solid_surface": true, //可以种植（放置）在任何固体表面上
"plant_at_face": "DOWN" //种植（放置）的方块面，这里是方块的下方
}

• bundle_interaction 收纳交互组件：指定物品有收纳袋的 UI 和交互。

需要格式版本：1.21.40+
必须与 minecraft:storage_item 一起用。
"minecraft:bundle_interaction": {
  "num_viewable_slots": 64
}

字段	功能描述	类型
num_viewable_slots	物品太多时显示多少种物品，范围是1到64。	整数

注：收纳袋有分层纹理，让交互时的物品看起来真的在收纳袋里面。这个特性使用三个纹理，要在物品纹理映射到路径时指定，命名格式为 <物品名>_open <物品名>_open_front 和 <物品名>_open_back。例如：

{
  "texture_data": {
    "my_item": {
      "textures": [
        "textures/items/my_item",
        "textures/items/my_item_open",
        "textures/items/my_item_open_back",
        "textures/items/my_item_open_front"
      ]
    }
  }
}

此时，点击物品后物品纹理是 my_item_open，选中物品准备取出时的物品纹理是 my_item_open_back 和 my_item_open_front 的组合。

• can_destroy_in_creative 禁用破坏组件：指定拿着物品时是否允许在创造模式下破坏方块。

"minecraft:can_destroy_in_creative": true

• compostable 堆肥组件：使物品可以堆肥并指定堆肥概率。

"minecraft:compostable": {
  "composting_chance": 50
}

• cooldown 冷却组件：使物品使用后需要冷却一段时间才能继续使用。

需要格式版本：1.20.10+
"minecraft:cooldown": {
  "category": "custom_cooldown_type",
  "duration": 0.2
}

字段	功能描述	类型
category	冷却类型。尝试使用不存在的冷却类型时，会注册为新的冷却类型。冷却类型一致的物品共享冷却时间。	字符串
duration	冷却时间，单位是秒。设为负数会让物品图标覆盖上冷却层。	浮点数

• custom_components 自定义组件：使用由脚本定义的自定义物品组件。

需要格式版本：1.21.10+
"minecraft:custom_components": [
  "complementary:fish_effect",
  "complementary:apple_effect"
]

字段	功能描述	类型
minecraft :custom_components	一个或多个自定义组件的名称，自定义组件的触发器将按照顺序被触发。	字符串列表

• damage 伤害组件：指定物品造成的额外伤害。

"minecraft:damage": 6  //必须正整数

• damage_absorption 伤害吸收组件：使物品被穿戴时，将外界伤害转化为耐久度消耗。

"minecraft:damage_absorption": {
  "absorbable_causes": [
    "entity_attack",
    "lava"
  ]
}  //注：需要首先指定耐久组件。

• durability 耐久组件：让物品拥有耐久度，并允许这种物品在工作台和铁砧上合并。

需要格式版本：1.20.0+
"minecraft:durability": {
  "damage_chance": {
    "min": 15,
    "max": 100
  },
  "max_durability": 36
}

字段	功能描述	类型
max_durability	最大耐久值。	整数
damage_chance	掉耐久的概率。	对象
damage_chance/min	掉耐久的概率范围中的最小值，必须在0-100之间，不能大于最大值。	整数
damage_chance/max	掉耐久的概率范围中的最大值，必须在0-100之间，不能小于最小值。	整数

耐久魔咒影响系数：

魔咒等级	系数
无	1.0
Ⅰ	0.5
Ⅱ	0.33
Ⅲ	0.25

注：原版耐久附魔会影响物品被使用时掉耐久的概率，实际概率 = damage_chance × 对应附魔系数。

旧名称：minecraft:damageable
版本：~1.16.100
旧语法：
"minecraft:damageable": {
  "max_damage": 326 //耐久值
}

• digger 挖掘组件：使物品能加速挖掘方块。

"minecraft:digger": {
  "use_efficiency": false,
  "destroy_speeds": [
    "dirt", // 方块 ID
    {
      "block": "minecraft:nether_wart_block",
      "speed": 5
    },
    {
      "block": {
        "tags": "q.any_tag('wood', 'pumpkin', 'plant')"
      },
      "speed": 4
    }
  ]
}

字段	功能描述	类型
use_efficiency	是否使用效率魔咒。	布尔值
destroy_speeds	加速挖掘的方块配置列表。	字符串列表或对象列表
destroy_speeds/*	单个方块及其挖掘速度配置。	字符串列表或对象列表
destroy_speeds/*/block	加速挖掘的方块ID或描述符。	字符串或方块描述符
destroy_speeds/*/speed	挖掘速度值。设为0或负值会使物品无法挖掘此方块。	整数

原版工具挖掘速度参考：

速度值	对应工具类型
0	无法挖掘
2	木制工具
3	石制工具
4	铁制工具
6	钻石工具
7	下界合金工具
8	金制工具

• display_name 名称组件：设置物品名称。

需要格式版本：1.20.0+
"minecraft:display_name": "名称"

字段	功能描述	类型
minecraft:display_name	物品名称，可以指定本地化键名。	字符串

行为说明：

1. 优先尝试翻译提供的字符串，翻译失败时显示原始字符串
2. 未指定此组件时，游戏自动生成本地化键名：
   • 旧版格式：item.<命名空间ID>.name
     （示例：item.minecraft:iron_sword.name）
   • 1.16.100+新版格式：item.<命名空间ID>
     （示例：item.minecraft:iron_sword）

使用示例：

// 直接显示文本
"minecraft:display_name": "传奇宝剑"

// 使用本地化键名
"minecraft:display_name": "item.custom_sword.legendary"

• durability_sensor 耐久检测组件：检测耐久值低于某值，并播放声音或显示粒子。

"minecraft:durability_sensor": {
  "durability_thresholds": [
    {
      "durability": 4000,
      "particle_type": "campfiresmoketall",
      "sound_event": "ambient"
    },
    {
      "durability": 1000,
      "particle_type": "shriek",
      "sound_event": "add.chest"
    }
  ]
}

字段	功能描述	类型
durability_thresholds	检测阈值。同时触发时，最低阈值的优先级最高。	对象列表
durability_thresholds/*/durability	耐久检测阈值。	整数
durability_thresholds/*/particle_type	旧版粒子 ID。注意，不是 /particle 命令中的ID，而是旧版粒子的 ID。	字符串
durability_thresholds/*/sound_event	声音ID。可填写的值可以参考 minecraft:record 组件的声音字段可用值。	字符串

• dyeable 染色组件：使物品可在炼药锅中染色，并指定基色。

"minecraft:dyeable":{
  "default_color": "#17714A"
}  //此组件需要 1.21.30+ 的版本。

• enchantable 附魔组件：使物品可被附魔。

"minecraft:enchantable": {
  "value": 59,
  "slot": "sword"
}

字段	功能描述	类型
value	附魔能力，值越高，出好附魔、高等级的概率就越大。实际使用的值在 [0, 255] 范围内。	整数
slot	附魔槽位，也就是物品可附上哪些魔咒。可用值见下。	字符串

附魔槽位可用值：

字段	描述
bow	弓
armor_feet	靴子
armor_torso	胸甲
armor_head	头盔
armor_legs	护腿
hoe	锄
axe	斧
pickaxe	镐
shovel	锹
sword	剑
elytra	鞘翅
fishing_rod	钓鱼竿
flintsteel	打火石
shears	剪刀
cosmetic_head	生物头颅
all	全部，类似于书

原版物品附魔能力值：

物品名称或类型	能力值
木质工具	15
皮革服装	15
石质工具	5
锁链护甲	12
铁质护甲	9
铁质工具	14
金质护甲	25
金质工具	22
钻石质装备	10
海龟壳	9
下界合金质装备	15
其他可在附魔台附魔的物品	1

注：

• 工具指剑、镐、斧、锹和锄
• 服装指帽子、外套、裤子和靴子
• 护甲指头盔、胸甲、护腿和靴子
• 装备指剑、镐、斧、锹、锄、头盔、胸甲、护腿和靴子

• entity_placer 实体放置组件：使物品可以放置为实体。(类似刷怪蛋)

"minecraft:entity_placer": {
  "entity": "minecraft:cat",
  "dispense_on": [
    {
      "tags": "q.any_tag('water')"
    }
  ],
  "use_on": [
    "dirt" //方块 ID
  ]
}

字段	功能描述	类型
entity	要放置的实体ID。	字符串
use_on	仅允许在某些方块上放置，留空表示允许全部方块。	字符串列表或方块描述符列表
dispense_on	仅允许在某些方块上发射，留空表示允许全部方块。	字符串列表或方块描述符列表

版本说明：
当物品格式版本为1.19.80及以上时，此组件会导致物品可设置刷怪笼刷出的实体。

• food 食物组件：使物品可以被食用。

字段	功能描述	类型
nutrition	回复的饥饿值，可以是负数。负数即扣除饥饿值。范围是整型的范围。	整数
saturation_modifier	回复的饱和度。必须是正数。计算公式：饥饿值 * 这里的值 * 2 = 饱和度。	浮点数
can_always_eat	是否允许在饥饿值满时食用。	布尔值
using_converts_to	食用后转化为物品的ID。忽略会导致物品直接消失。	字符串

饱和度新旧版本对应关系：

旧版	新版
poor	0.1
low	0.3
normal	0.6
good	0.8
max	1.0
supernatural	1.2

旧版语法说明（≤1.10）：

"minecraft:food": {
  "saturation_modifier": "normal",  // 可使用特定字符串
  "is_meat": true,  // 是否为肉类
  "on_use_action": "chorus_teleport",  // 可选值：chorus_teleport/suspicious_stew_effect/none
  "on_use_range": [8, 8, 8],  // 紫颂果传送范围（方块）
  "cooldown_type": "chorusfruit",  // 可选值：chorusfruit/none
  "cooldown_time": 20,  // 冷却时间（刻）
  "effects": [  // 食用效果列表
    {
      "name": "regeneration",  // 效果ID
      "chance": 1.0,  // 触发概率（0.0-1.0）
      "duration": 30,  // 持续时间（秒）
      "amplifier": 4  // 效果倍率（实际等级=值+1）
    }
  ]
}

• fuel 燃料组件：使物品可以在熔炉等方块里当燃料。

需要格式版本：1.20.0+
"minecraft:fuel":{
  "duration": 3.0
}
字段	功能描述	类型
duration	燃烧的时间（秒），以0.05为分度值，必须≥0.05。	浮点数

• glint 闪光组件：指定物品是否有带魔咒物品的光效。

"minecraft:glint": true

旧名称：minecraft:foil
版本：≤~1.20
旧语法：
"minecraft:foil": true //物品是否有附魔的闪光。true是有，false是没有。

• hand_equipped 手持组件：指定物品是否有手持动画。

"minecraft:hand_equipped": true

• hover_text_color 文本颜色组件：指定物品的悬停文本的颜色。

"minecraft:hover_text_color": "material_amethyst"

字段	功能描述	类型	备注
minecraft: hover_text_color	控制物品悬停时的文本颜色	字符串	1. 可接受颜色代码值 2. 在 1.16-1.19 版本期间不可用 3. 旧版需通过资源包文件指定

颜色代码示例：

"minecraft:hover_text_color": "material_amethyst"

查看所有颜色

• icon 图标组件：指定物品纹理。

字段路径	功能描述	类型	格式版本
minecraft:icon	物品图标配置	字符串/对象	1.20.10+
textures	图标纹理合集	对象	1.20.10+
textures/default	默认纹理短名	字符串	1.20.10+
textures/dyed	染色模板的灰度纹理短名	字符串	1.20.10+
textures/icon_trim	带纹饰的物品纹饰层纹理（需完整命名空间ID）	字符串	1.20.10+

完整代码示例（1.20.10+）：

"minecraft:icon": {
  "textures": {
    "default": "custom_chestplate_icon",
    "dyed": "custom_chestplate_gray_icon",
    "icon_trim": "test:custom_chestplate"
  }
}

简化写法（1.20.10+）：

"minecraft:icon": "test"

旧版本（1.20.10-）
"minecraft:icon": {
  "texture": "custom_chestplate"
}

• interact_button 交互按钮组件：指定物品的交互按钮及文本。

字段	功能描述	类型
minecraft:interact_button	拿着物品时添加交互按钮，可设置按钮文字（支持本地化键名）或设为布尔值（true时显示默认"使用物品"提示）	字符串或布尔值

完整代码示例：

"minecraft:interact_button": "文本"
"minecraft:interact_button": true

• liquid_clipped 接触水面组件：指定物品是否能接触水面。

"minecraft:liquid_clipped": true

• max_stack_size 最大堆叠组件：指定物品的最大堆叠数。

"minecraft:max_stack_size": 1

• projectile 投掷物组件：定义物品为投掷物。

字段	功能描述	类型	格式版本
minimum_critical_power	暴击需要的蓄力大小	浮点数	1.20.10+
projectile_entity	发射的实体ID（该实体必须包含minecraft:projectile组件）	字符串	1.20.10+

完整代码示例（1.20.10+）：

"minecraft:projectile": {
  "minimum_critical_power": 1.25,
  "projectile_entity": "arrow"
}

• rarity 稀有度组件：指定物品的稀有度。

"minecraft:rarity": "common"

以下是所有可用的稀有度。
值	描述
common	常见
uncommon罕见
rare	稀有
epic	史诗

• record 唱片组件：指定物品为唱片。

"minecraft:record": {
  "comparator_signal": 1,
  "duration": 5,
  "sound_event": "ambient.tame"
}

字段	功能描述	类型
comparator_signal	在唱片机中播放时比较器输出的信号强度（默认1，范围[1,15]）	整数
duration	唱片机持续生成粒子的时间长度（可为0）	浮点数
sound_event	要播放的声音事件ID（仅支持原版声音事件）	字符串

声音事件ID

• repairable 修复组件：使物品可以被修复。

字段	功能描述	类型
repair_items	可以用于修复的物品列表	字符串列表或对象列表
repair_items/*/items	可以用于修复的物品ID列表	字符串列表
repair_items/*/repair_amount	修复的耐久量（数值或Molang表达式）<br>• 使用c.other访问修复物品<br>• 支持随机数表达式	数值/Molang

完整代码示例：

  "repair_items": [
    "anvil", //可以是单个物品ID。
    { //还可以是一个对象。
      "items": [
        "anvil" //物品ID
      ],
      "repair_amount": "math.min(q.remaining_durability + c.other->q.remaining_durability + math.floor(q.max_durability /20), c.other->q.max_durability)"
    }
  ]
}

• shooter 射手组件：使物品可以射出弹射物。

需要格式版本：1.20.10+
"minecraft:shooter": {
  "ammunition": [
    {
      "item": "minecraft:arrow",
      "use_offhand": true,
      "search_inventory": true,
      "use_in_creative": true
    }
  ],
  "charge_on_draw": false,
  "max_draw_duration": 0.0,
  "scale_power_by_draw_duration": true
}

字段	功能描述	类型
scale_power_by_draw_duration	是否按照长按的时间增加蓄力力度	布尔值
charge_on_draw	控制射击行为模式：<br>- true：类似弩（长按装弹，再按发射）<br>- false：类似弓（长按蓄力，松开发射）	布尔值
max_draw_duration	最大蓄力时间（必须≤物品使用时间）	浮点数
ammunition	可用弹药配置列表	对象列表
ammunition/*/item	弹药物品ID（需含minecraft:projectile组件）	字符串
ammunition/*/use_offhand	是否允许使用副手物品作为弹药	布尔值
ammunition/*/search_inventory	是否从物品栏搜索弹药	布尔值
ammunition/*/use_in_creative	创造模式是否消耗弹药	布尔值

• should_despawn 防止刷新组件：指定物品的掉落物形式是否可以被刷新而消失。

"minecraft:should_despawn": false

• stacked_by_data 数据值堆叠组件：指定物品是否根据数据值堆叠。

字段	功能描述	类型
minecraft:stacked_by_data	控制物品是否根据数据值(stack data)堆叠：- true：不同数据值的物品不能堆叠，物品实体不会自动合并- false：不同数据值的物品可以堆叠，物品实体会自动合并	布尔值

完整代码示例：

"minecraft:stacked_by_data": false

• storage_item 收纳组件：指定物品有收纳袋的功能。

字段	功能描述	类型	格式版本
minecraft:storage_item	收纳袋物品配置	对象	1.21.40+
max_slots	能存储的物品种类数（范围1-64）	整数	1.21.40+
allow_nested_storage_items	是否允许嵌套其他收纳袋	布尔值	1.21.40+
banned_items	禁止放入的物品ID列表	字符串列表	1.21.40+
allowed_items	允许放入的物品ID列表（留空表示允许所有）	字符串列表	1.21.40+

完整代码示例（1.21.40+）：

"minecraft:storage_item": {
  "max_slots": 64,
  "allow_nested_storage_items": true,
  "banned_items": [
    "minecraft:shulker_box",
    "minecraft:undyed_shulker_box"
  ],
  "allowed_items": []
}

旧版语法（<1.21.30.23）

"minecraft:item_storage": {
  "capacity": 64
}

物品数量 / 最大堆叠数 * 64 = 占用容量

版本阶段	关键变化
1.19.60	• 最后一个稳定支持旧版item_storage的测试版（如1.19.60.24）
1.19.70	• 正式移除此组件
1.19.80(Dev)	• 实验性改动：直接赋值决定容量（需格式版本1.16.0）• 正式版使用会报错
1.20.0(Dev)	• 更新空收纳袋纹理• 仍使用旧版组件
1.21.30.23	• 正式重新加入收纳袋功能
1.21.40+	• 采用新版storage_item语法• 强制要求物品不可堆叠

• storage_weight_limit 最大收纳容量：指定收纳袋类物品的最大收纳容量。

"minecraft:storage_weight_limit": {
  "max_weight_limit": 64
}
收纳袋的最大容量，填写正整数，不能超过 64。容量公式：物品数量 / 最大堆叠数 * 64

• storage_weight_modifier 占用容量修饰符：指定物品在收纳袋类容器中占用的容量。

"minecraft:storage_weight_modifier": {
  "weight_in_storage_item": 4
}

• tags 标签组件：指定物品的标签。

这个组件取代了以前的 "tag:xxx": {} 。
"minecraft:tags": {
  "tags": [
    "minecraft:is_food"
  ]
}

标签名称	功能说明
minecraft:is_sword	标记物品为剑
minecraft:is_pickaxe	标记物品为镐
minecraft:is_axe	标记物品为斧
minecraft:is_shovel	标记物品为锹
minecraft:is_hoe	标记物品为锄
minecraft:is_shears	标记物品为剪刀
minecraft:is_food	标记物品为食物
minecraft:is_meat	标记物品为肉类食物
minecraft:is_crop	标记物品为作物
minecraft:transform_materials	锻造台升级材料
minecraft:transformable_items	可升级装备
minecraft:transform_templates	装备升级模板
minecraft:trim_materials	盔甲纹饰材料
minecraft:trimmable_armors	可添加纹饰的盔甲
minecraft:trim_templates	盔甲纹饰模板
minecraft:bookshelf_books	可放入雕纹书架的书籍
minecraft:decorated_pot_sherds	饰纹陶罐碎片
minecraft:lectern_books	可放置在讲台上的书籍
minecraft:stone_tool_materials	可替代圆石制作石质工具的材料

此外，给物品添加标签可以让物品参与使用标签作为输入的配方。

• throwable 投掷组件：使物品可以被投掷。

基础信息

属性	说明
功能	使物品可以被投掷
最低版本	1.20.10+
必需组件	minecraft:projectile
语法版本	~1.21

参数表格

参数	类型	默认值	说明
do_swing_animation	boolean	false	投掷时是否播放手臂摆动动画
launch_power_scale	float	1.0	蓄力系数（负数=反向发射）
max_draw_duration	float	0.0	最大蓄力时间（≤0=立即发射）
min_draw_duration	float	0.0	最小蓄力时间（≤0=立即发射）
max_launch_power	float	1.0	最大发射力度（支持负数）
scale_power_by_draw_duration	boolean	false	力度是否随蓄力时间增加

旧版本参数（风弹专用）

参数	类型	默认值	说明
default_offset_scale	float	0.8	风弹发射偏移量
inside_block_offset_scale	float	0.05	在方块内时的偏移量

代码示例

"minecraft:throwable": {
  "do_swing_animation": false,
  "launch_power_scale": 1.0,
  "max_draw_duration": 0.0,
  "min_draw_duration": 0.0,
  "max_launch_power": 1.0,
  "scale_power_by_draw_duration": false
}

• use_animation 使用动画组件：指定物品的使用动画和音效。

minecraft:use_animation 组件

字段	类型	必填	描述
minecraft:use_animation	字符串	是	定义物品使用时触发的动画和音效

可用动画类型

值	描述	适用物品	音效
eat	食用动画	食物	咀嚼音效
drink	饮用动画	药水/牛奶	吞咽音效
bow	拉弓动画	弓*	拉弦音效
crossbow	弩装填动画	弩*	机械音效
camera	拍照动画	相机	快门声
spyglass	望远镜动画	望远镜*	无
spear	投掷动画	三叉戟*	挥舞声
brush	刷扫动画	刷子	沙沙声
block	格挡动画	盾牌*	碰撞声
none	无动画	任何物品	无

1 * 表示需要特定类型的物品才能正确显示动画

代码示例

{
  "minecraft:use_animation": "drink"
}

• use_modifiers 使用修饰符组件：指定物品使用的效果。

字段	类型	范围	默认值	描述
use_duration	浮点数	>0	-	使用物品所需时间（秒）
movement_modifier	浮点数	[0.0,1.0]	1.0	使用时的移动速度系数

代码示例

// 新版本语法（1.20.10+）
"minecraft:use_modifiers": {
  "use_duration": 1.6,
  "movement_modifier": 0.35
}

// 旧版设置（≤1.20.40）
"minecraft:use_duration": 1.1

// 旧版系统（≤1.20.40） 
"minecraft:chargeable": {
  "movement_modifier": 0.0,
  "on_complete": {
    "event": "use_complete",
    "target": "self"
  }
}

• wearable 穿戴组件：让物品可以被穿戴，并提供护甲值。

字段	类型	必填	描述
protection	整数	是	护甲值（0-∞），值越高防护效果越好
slot	字符串	是	指定装备栏位（自动限制堆叠数为1）

可用装备槽位

槽位值	对应部位	备注
slot.weapon.offhand	副手	不限制堆叠数
slot.armor.head	头部
slot.armor.chest	胸部
slot.armor.legs	腿部
slot.armor.feet	足部

新旧版本对比

// 新版语法（1.20.20+）
"minecraft:wearable": {
  "protection": 5,
  "slot": "slot.armor.chest"
}

// 旧版语法（≤1.20.20）
"minecraft:armor": {
  "protection": 5,
  "texture_type": "diamond"  // 已废弃参数
}

| 已废弃组件和已移除组件

一些组件已被废弃或移除，非常不建议使用已废弃组件，现已无法使用已移除组件。这种东西肯定没人看,就不写了。

杂项

字段	功能描述	类型	备注
identifier	物品的唯一ID	字符串	必须包含命名空间（如namespace:item_id）
menu_category	控制物品在创造模式物品栏的位置和命令可见性	对象	可选字段
menu_category/category	指定创造模式标签页	字符串	默认值：items
menu_category/group	物品分组（需带命名空间）	字符串	使用原版或自定义本地化键名
menu_category/is_hidden_in_commands	是否在命令中隐藏	布尔值	默认值：false

完整示例：

{
  "description": {
    "identifier": "complementary:example",
    "menu_category": {
      "category": "equipment",
      "group": "minecraft:itemGroup.name.cookedFood",
      "is_hidden_in_commands": false
    }
  }
}

menu_category 可用值说明

字段值	描述	行为表现
construction	建筑分类	出现在创造模式"建筑"标签页
equipment	装备分类	出现在创造模式"装备"标签页
items	物品分类	出现在创造模式"物品"标签页（默认值）
nature	自然分类	出现在创造模式"自然"标签页
none	无分类	不会出现在任何创造模式物品栏中

重要说明：

• 当设置为 none 时：
  • 物品将完全从创造模式物品栏移除
  • 只能通过命令或合成获取该物品
  • 不影响物品在生存模式中的正常使用

| 你知道吗？

在 1.21.40 以前的格式版本中，true 可以写为 1，false 可以写为 0，反之亦然。浮点数可以写为整数，例如本应写为 2.0 的值可以写为 2。1.21.40 及以后，JSON 语法分析程序更加严格，不再允许这么写。
item_properties 字段可能出现在与组件同级的位置，是一个含有物品属性的对象，其作用未知。
一些物品的定义文件中可能会出现一些例如 minecraft:armor_toughness 的组件，但这些组件没有任何作用。这说明某些情况下，无效组件并不会引发内容日志。

开发计划

• 注：以下内容可能不准确或不会实现。
• 通过SAPI获取收纳袋存储的物品。
• 添加物品组。（已实现）
• 添加物品属性。（中长期）
• 添加物品动态纹理。（中长期）
• 添加onEquip和onUnequip触发器。（中长期）
• 重新添加 minecraft:knockback_resistance 这样的组件。
• 扩展盔甲纹饰。（很久以后）
• 添加物品存储实体的功能。（很久以后）
• 目前不会添加自定义唱片。
• 目前不会添加自定义创造模式物品栏的标签页。

附加包教程：6.物品（一）

准备

在行为包根目录下打开items文件夹，新建一个文件。命名就是你的物品的英文名，这样比较好管理。你也可以新建一个文件夹，把它命名英文名，把所有相关的文件都放进去，方便管理。这对于方块和实体也适用。

第一个物品

现在就可以开始了。在你新建的文件里写以下代码。

{
  "format_version": "1.21.50", //这个是格式版本，写物品时只能用这个版本能用的语法。建议保持一个比较新的版本号，如1.21.50。
  "minecraft:item": {
    "description": {
      "identifier": "以后这里我称为“命名空间ID”", //前面写一个附加包名称，加上英文冒号，后面写具体的这个物品的英文名（例如test_pack:test_item），这个要牢记。
      "menu_category": {
        "category": "items", //定义物品位于创造模式物品栏下的哪个标签页。construction是建筑，equipment是装备，items是物品，nature是自然，none是不在创造模式物品栏中显示。
        "group": "minecraft:itemGroup.name.bed", //创造模式物品栏标签页下的组，填写物品组的本地化键名，如果是 1.21.60+ 那么还要在前面加一个 minecraft: 作为命名空间。找不到对应物品组时，不会放进任何物品组中。
        "is_hidden_in_commands": false //物品是否在命令列表中隐藏，例如是否可以通过命令获取。设为true后将不能用命令获得此物品。
      }
    },
    "components": { //这就是这个物品拥有的功能的列表，叫“组件”。
      "minecraft:icon": "test_name"
    }
  }
}

上面我给出的示例文档里描述的是一个命名空间是test_pack:test_item的物品，有一个组件，分别指定了图标和创造模式物品栏分类。如果想要创造功能更丰富的物品，就必须借助更多组件，甚至脚本的帮助。所以，下期我将列出所有可用的组件。使用时，直接重复并粘贴到与示例组件同级的位置就好了。
minecraft:icon：这个组件可以指定物品的纹理图标（就是这个物品长啥样）。要想指定纹理，首先确定纹理短名，短名可以随便起（英文名，建议与这个物品的命名空间ID保持一致）。每个短名都指代一个路径，而这个路径指向图片。简单地说，这个物品告诉基岩引擎，“我的纹理叫 test_name！”基岩引擎就跑去登记表那里，问“test_name 对应哪个路径？”登记表回答，“是 textures/items/test 路径！”基岩引擎就去这个路径指向的纹理，把纹理贴到物品上。

渲染

这一期我们不仅会列出如何创建一个最基础的物品，还要谈到如何让这个物品有纹理。
打开资源包根目录下的textures文件夹，创建item_texture.json，把下面的代码粘贴进去。

{
  "texture_data": {
    "test_name": { //这里写之前起的短名。
      "textures": "textures/items/test" //这里就是你的纹理的路径。不需要后缀，只需要保证它指向了一张正方形的图片即可。
    }
  }
}

在textures文件夹下新建items文件夹，打开，随便一张正方形图片扔进去，改名成你刚才写的名字（刚才的示例里是test，那就改成test.png）。其实这里没那么严格，照片格式只要是.png、.jpg中的一种就好了。然而我建议你把图片转换格式成.png。是转换格式，不是单纯改后缀！
在基岩版1.19.51.01中，物品纹理过大会导致渲染错误，需要用附着物和模型改变渲染大小才能修复这个问题，例如64像素大小的物品需要0.01的scale值，所以建议避免过大的物品纹理。
在基岩版1.19.60.24中，物品纹理的大小可以大于16*16，而且不是正方形也没关系。这些物品在外观上会被缩放到一个适当的位置，然后像普通物品一样渲染。以后的版本中可能会再次出现此漏洞。

打开游戏，你应该能找到你新增的物品，用着你刚才添加的图片，不过它的名字看起来像是乱码。如果要让它显示成正常名字，那就退出游戏，打开资源包根目录下的texts文件夹，创建一个叫zh_CN.lang的文件。
打开它，输入以下这行内容。

item.命名空间ID=物品名字

其中，命名空间ID就是上文提到的“test_pack:test_item”，物品名字随便写，可以用§改变格式，但是不能用\n换行，而且在末尾的用 Tab 打出来的制表符显示的时候会被自动删掉。
一行代表一个本地化键名和物品名字的对应关系。如果要写注释，注释要以##开头，而且只会持续到这一行结束。

再次打开游戏，应该就能正常地看到一个物品了。
模板包，更改后缀为zip后解压

附加包教程：5.迷雾

准备

在资源包根目录下创建并打开fogs文件夹，新建一个文件。

第一个迷雾

现在就可以开始了。在你新建的文件里写以下数据。

{
  "format_version": "1.16.100", //不像其他内容，迷雾的格式版本只能是1.16.100，不能变。
  "minecraft:fog_settings": {
    "description": {
      "identifier": "前面写一个附加包名称，加上英文冒号，后面写具体的这个文档的英文名（例如test_pack:test_fog），这个要牢记"
    },
    "distance": { //这里就是迷雾的各种属性
      "water": {
        "fog_start": 10.0, //玩家和迷雾开始时的距离，此时迷雾是半透明的。
        "fog_end": 40.0, //迷雾变得完全不透明时离玩家的距离。必须大于或等于“fog_start”。
        "fog_color": "#0677ce", //迷雾的颜色，使用十六进制
        "render_distance_type": "fixed" //决定迷雾渲染距离的方法。 fixed的意思是以方块为单位，render的意思是把距离当成因数，乘以当前的渲染距离。
      }, //水下的远处
      "air": {
        "fog_start": 20.0, //这些值的意思和上面说的一样。
        "fog_end": 100.0,
        "fog_color": "#eedde1",
        "render_distance_type": "fixed"
      }, //空气中远处
      "weather": {
        "fog_start": 20.0,
        "fog_end": 80.0,
        "fog_color": "#eedde1",
        "render_distance_type": "fixed"
      }, //下雨或下雪时远处
      "lava": {
        "fog_start": 20.0,
        "fog_end": 80.0,
        "fog_color": "#eedde1",
        "render_distance_type": "fixed"
      }, //在熔岩里时远处
      "lava_resistance": {
        "fog_start": 40.0,
        "fog_end": 80.0,
        "fog_color": "#eedde1",
        "render_distance_type": "fixed"
      }, //拥有抗火效果时熔岩里远处
      "powder_snow": {
        "fog_start": 20.0,
        "fog_end": 80.0,
        "fog_color": "#eedde1",
        "render_distance_type": "fixed"
      } //细雪里远处
    }
  }
}

好了，一般来说制作附加包只需要上面那些数据。下面是高级内容，不怎么常用，如果要测试一下，那么新开一个迷雾文件，写上以下代码。

{
  "format_version": "1.16.100",
  "minecraft:fog_settings": {
    "description": {
      "identifier": "前面写一个附加包名称，加上英文冒号，后面写具体的这个文档的英文名（例如test_pack:advanced_fog），这个要牢记"
    },
    "distance": { //这里与上面的意思相同。
      "water": {
        "fog_start": 10.0,
        "fog_end": 40.0,
        "fog_color": "#0677ce",
        "render_distance_type": "fixed",
        "transition_fog": { //当玩家的摄像机在水中时，水中的渐变迷雾。
          "init_fog": { //初始时的迷雾
            "fog_start": 0.0,
            "fog_end": 0.01,
            "fog_color": "#157cab",
            "render_distance_type": "fixed" //这四项与上面那四项的作用相同。
          },
          "min_percent": 0.25, //渐变的最小百分比（范围是0.0-1.0），迷雾从这个百分比开始渐变
          "mid_seconds": 5, //迷雾达到下面百分比所需的时间（秒）
          "mid_percent": 0.6, //迷雾经过上面mid_seconds秒数的渐变后，到达的百分比
          "max_seconds": 30 //迷雾渐变完成所需要的时间（秒，范围是0.0-1.0），以上四项共同定义了迷雾渐变的速度轨迹等。
        }
      },
      "air": {
        "fog_start": 20.0,
        "fog_end": 100.0,
        "fog_color": "#eedde1",
        "render_distance_type": "fixed"
      },
      "weather": {
        "fog_start": 20.0,
        "fog_end": 80.0,
        "fog_color": "#eedde1",
        "render_distance_type": "fixed"
      },
      "lava": {
        "fog_start": 20.0,
        "fog_end": 80.0,
        "fog_color": "#eedde1",
        "render_distance_type": "fixed"
      },
      "lava_resistance": {
        "fog_start": 20.0,
        "fog_end": 80.0,
        "fog_color": "#eedde1",
        "render_distance_type": "fixed"
      },
      "powder_snow": {
        "fog_start": 20.0,
        "fog_end": 80.0,
        "fog_color": "#eedde1",
        "render_distance_type": "fixed"
      }
    },
    "volumetric": { //这里是高级内容，一般不会用到。这个是迷雾的体积设置。
      "density": { //迷雾的密度。下面的air，water等等的对象，意义是光穿过air（空气）/water（水）等等，的迷雾密度值。
        "air": {
          "max_density": 0.95, //迷雾的（最大）不透明度（密度），介于0和1之间，可以是小数。
          "zero_density_height": 320, //迷雾完全透明并开始出现（渐渐变浓）的高度，以方块为单位。需要至少比“max_density_height”大1，介于0-320之间。
          "max_density_height": 128, //迷雾将达到其最大密度（最浓）的高度，单位是方块，介于0-320之间。
          "uniform": false //如果设置为true，密度在所有高度上都是一致的，因此不能也不需要使用max_density_height和zero_density_height。如果设置为false，则密度不一致，使用max_density_height和zero_density_height决定密度。
        },
        "water": {
          "max_density": 0, //这些结构都是重复的，意义和上面的相同。
          "uniform": true
        },
        "lava": {
          "max_density": 0,
          "uniform": true
        },
        "lava_resistance": {
          "max_density": 0,
          "uniform": true
        }
      },
      "media_coefficients": { //不同方块中迷雾体积的系数设置。
        "air": { //光线穿过空气时的迷雾系数。
          "scattering": "#000000", //每个方块被散射的光的比例。也可以填写含三个范围是0-255的整数的数组。
          "absorption": "#000000" //每个方块被吸收的光的比例。
        },
        "water": { //光线穿过水时的迷雾系数。
          "scattering": "#000000", //这些结构都是重复的，意义和上面的相同。
          "absorption": "#000000"
        },
        "cloud": { //光线穿过云时的迷雾系数。
          "scattering": "#000000",
          "absorption": "#000000"
        }
      }
    }
  }
}

现在你应该可以使用/fog命令新建一个你自己创建的迷雾了。

附加包教程：4.功能域

注意：此页面所述功能和/volumearea命令在现版本已被弃用，此页面现仅作为旧版本参考。

此页面所述功能只能在1.21.0及以下的游戏中使用。
然而，出于学习并理解旧版附加包的必要性，我保留了这个页面。

前言

上期，我们成功向附加包中添加了函数。这一期，我们将学习功能域相关内容。注意，功能域属于实验性内容中的实验性内容，从未正式发布，测试了四个大版本就移除了。需要1.18到1.21的版本。

准备

打开行为包根目录，打开volumes文件夹。不过，在你迫不及待地新建文件之前，你一定很疑惑：什么是功能域？我怎么从来没听说过？？如果你想知道答案，打开折叠块。你也可以跳过，反正我一会儿还要放出使用方法。

这个问题，只有玩命令的玩家才可能会回答，而且回答的不一定对。如果你经常玩命令，你应该会注意到有个命令叫/volumearea。这个命令的解释大概是“列出、添加或删除卷”，这一定让你大惑不解。“卷”？卷是什么？你带着这个疑问，看到了它的语法大致与/tickingarea（常加载区域）相同，于是你猜测这个“卷”就像常加载区域一样，是一种区域。没错，所谓“卷”，就是功能域。
在你尝试输入/volumearea然后招惹来一堆错误提示时，你一定不会想到这东西居然需要附加包的支持。换句话说，还没有已知的原版的功能域。功能域，只能通过附加包添加，这就是我把它放在函数后面这一期的原因。

我说了这么多，只是因为我想让你在自然情况里了解功能域，你会有兴趣的。
现在我来回答到底什么是功能域。一个实体进入或离开特定区域后触发了事件，或者在区域内有迷雾效果，这个特定区域就是功能域。比如，走进房子，系统提示：“已进入房子”；走出房子，系统提示：“已离开房子”，房子在一个特定的区域里，这个区域就是功能域。

不过现在，连/volumearea命令都被移除了，功能域这个特性算是几乎没人知道的东西了，它本身也并不实用。

好了，在volumes文件夹里新建文件吧，文件名称见后面的解释。

第一个功能域

现在就可以开始了。在你新建的文件里写以下代码。

{
  "format_version": "1.18.0",
  "minecraft:volume": {
    "description": {
      "identifier": "前面写一个附加包名称，加上英文冒号，后面写具体的这个文档的英文名（例如test_pack:test_volume），这个叫命名空间ID，要牢记"
    },
    "components": {
      "minecraft:bounds": {
        "min": [
          -512,
          -64,
          -512
        ],
        "max": [
          512,
          320,
          512
        ] //这两个数组可能是指定这个功能域的范围，又或者是限制放置的坐标，目前不清楚它的功能
      },
      "minecraft:fog": { //给功能域附加一个迷雾，进入后显示这个迷雾
        "fog_identifier": "minecraft:fog_hell", //下界荒地的迷雾ID
        "priority": 0 //迷雾的优先级，多个功能域重叠时使用。数字越小，优先级越大。
      },
      "minecraft:on_actor_enter": { //指定当实体进入时触发的事件
        "on_enter": [
          {
            "condition": "1", //指定一个Molang表达式，返回true时才触发这个事件
            "event": "enter", //触发的事件
            "target": "other" //other意思是进入功能域的实体，self意思是功能域本身
          }
        ]
      },
      "minecraft:on_actor_leave": { //指定当实体离开时触发的事件
        "on_leave": [
          {
            "condition": "1", //指定一个Molang表达式，返回true时才触发这个事件
            "event": "leave", //触发的事件
            "target": "other" //other意思是离开功能域的实体，self意思是功能域本身
          }
        ]
      }
    },
    "events": {
      "enter": { //进入时触发的事件
        "run_command": {
          "command": [
            "title @s 进入测试功能域" //要运行的命令
          ]
        }
      },
      "leave": { //离开时触发的事件
        "run_command": {
          "command": [
            "title @s 离开测试功能域"
          ]
        }
      }
    }
  }
}

总结

好了，现在，你应该会如何添加一个功能域了，也明白什么是功能域了。功能域的内容单一，热度较低，目前由于特性（见折叠块）实际用途不多，一期就可以说完。下期，我们就要学习如何添加迷雾了。

文件下载 test_volume.txt 自行更改后缀名为 json

@IF_IceFire 光影刚开始看着还行,但是似乎优化并不太好,包括锁帧问题严重,明暗处理也不太行.夜晚.矿洞.末地都超级黑暗.发光物体亮度处理不太行.红石火把 火把 灵魂火把.等等亮度并不符合预期.入水面渲染没处理好,会产生类似矿透的效果

附加包教程：3.函数

前言

上期，我们成功向附加包中添加了配方。这一期，我们将学习函数相关内容。

准备

第一个函数

现在就可以开始了。不要以为函数是一个很高深莫测的东西，它实际上就是一堆按顺序执行的命令。新建一个文件，给它命一个好记的英文名，后缀改成.mcfunction，用文本文档打开。
在里面开始写命令吧。这里的命令开头不能有斜杠，每一行代表一个命令。写好的函数文件可以在游戏里用/function 文件名（不带后缀）运行，游戏会在一个游戏刻里按顺序运行全部命令，从第一行运行到最后一行，包括一个函数里的命令调用的另一个函数里的命令。
如果函数数量太多，可以用“/gamerule functioncommandlimit <正整数>”这个命令来修改函数一次最多能执行多少命令。

还有，如果你需要重复执行一个或很多函数，那就在functions文件夹下新建tick.json，打开。里面写的数据如下。

{
  "values": [
    "warden_armor", //一个函数的名称，注意没有后缀。
    "table/craft" //又一个函数的名称，这个函数放在一个文件夹里。
  ]
}

当然了，正在运行的函数越多，游戏就越卡，和命令一样。所以控制一下要在这个文件列出的函数的数量，尽量用其他的方法代替这种循环执行的函数。有时迫不得已需要上百条循环执行的命令，那只好用这种方法。
如果要在函数文档里写注释，注释要以#开头，而且注释只能持续到这一行结束。
一次执行的函数（包括这个函数里调用的函数）中，命令数量有限制。可以使用命令“/gamerule functioncommandlimit 数量”来调整这个限制。

好了，这就是函数的全部。

函数模板，自行更改后缀为.zip