【基岩版】基岩版附加包教程

一颗不帅

该文章是Cat_Anchor大佬制作的教程,已取得授权

附加包教程：1.初步准备
附加包教程：2.配方
附加包教程：3.函数
附加包教程：4.功能域
附加包教程：5.迷雾
附加包教程：6.物品（一）
附加包教程：7.物品（二）
附加包教程：8.物品（三）
附加包教程：9.物品（四）
附加包教程：10.方块（一）
附加包教程：11.方块（二）
附加包教程：12.模型
附加包教程：13.战利品表
附加包教程：14.方块（三）
附加包教程：15.方块（四）
附加包教程：16.子包
附加包教程：17.附着物
附加包教程：18.动画
附加包教程：19.渲染控制器
附加包教程：20.声音
附加包教程：21.字体
附加包教程：22.行为树
附加包教程：23.生物群系
附加包教程：24.对话
附加包教程：25.生成规则
附加包教程：26.结构
附加包教程：27.地物
附加包教程：28.交易
附加包教程：29.实体
附加包教程：30.粒子
附加包教程：31.附加包根目录
附加包教程：32.动态纹理
附加包教程：33.方块（五）
附加包教程：34.方块（六）
附加包教程：35.方块（七）
附加包教程：36.实体（一）
附加包教程：37.实体（三）
附加包教程：38.实体（四）
附加包教程：39.NBT
附加包教程：40.版本兼容性
附加包教程：41.附加包兼容性
附加包教程：42.方块（八）
附加包教程：43.方块（九）
附加包教程：44.方块（十）
附加包教程：45.战利品表（二）
附加包教程：46.自定义组件（一）
附加包教程：47.自定义组件（二）
附加包教程：48.自定义组件（三）
附加包教程：49.拼图结构（一）
附加包教程：50.拼图结构（二）
附加包教程：51.拼图结构（三）
附加包教程：52.拼图结构（四）
附加包教程：53.拼图结构（五）
附加包教程：54.拼图结构（六）
今天是3月30日,先发个目录,明天继续更新

一颗不帅

由于作者对附加包了解不深，本教程存在一些不足之处，欢迎批评指正。物品教程在第6期，方块教程在第10期，实体教程在第29期。

前言

各位在玩各种附加包时，一定会萌生出一种想法，“我能不能做一个自己的附加包？”如果你看过MinecraftLive，就可能会产生“我上我也行”的念头。这篇教程的作用就是把想象照进现实。

准备

首先，需要准备一个用于制作附加包的工具。在Android平台上，我推荐MT管理器。（因为我只有一个手机）我要重点强调，还要准备一个用起来顺手的、支持像素画布的绘画软件。
准备好这两个软件之后，还要初步认识JSON数据格式和能看懂内容日志。在这里，我将简单叙述json格式。
{} 这个东西叫根对象。大部分json文档里都是以这个括号（或者以这个[]）开头和结尾的。
"键":"值" 这个东西叫键值对，键是名称，值是名称对应的内容。
"对象":{"键1":"值1","键2":"值2","键3":"值3",...} 这就是一个对象，它是无序的。
"对象":["值1","值2","值3",...] 这就是一个数组，它是有序的。
true false 这两个，true代表真，false代表假。
如果在双引号""里面要用双引号时，里面的双引号前面要加上转义符\。由于在这里转义符会被解析，故难以举例。
转义符不仅能这么用，还有其他用途。\n代表换行，这是最重要的一个。如果你在json文档里的""里需要换行了，用\n表示它。
\t代表一个制表符，与空格的作用大致相同，但是制表符会自动缩进自身的大小以匹配代码。如果代码使用空格进行缩进，不妨改成制表符，这样会在一定程度上压缩文件大小。
// 这是行注释，会以它开始注释一行。
/* */ 这是块注释，会把它们之间的东西全注释掉。

（注：欢迎大佬指正错误，谢谢。）

至于错误日志，只要会英文就好，实在不行就用翻译器翻译一下。错误日志的开头一般是[xxx][error]，或者[xxx][warning]。前者就是错误，后者就是警告。一个最容易触发的内容日志错误就是故意往你的json文档里造点语法错误，比如不加英文逗号啊，括号不匹配什么的。（所以在实际编写里要避免这些语法错误。）
一个最容易触发的警告就是把你的纹理（尤其是物品纹理）的分辨率搞得很大（大于512*512），一般就会弹出来警告，说这样可能会卡。

建立项目

现在就可以开始了。直接在游戏的com.mojang目录下开发，会省很多时间。打开这个网址(https://minecraft.fandom.com/zh/wiki/Com.mojang)，它能帮你定位到com.mojang文件夹。以后的所有操作都在这里进行。找到com.mojang文件夹后，打开。找到development_behavior_packs（行为包文件夹）。进去，随便用英文字母为名字建个文件夹。进入这个文件夹，下文我叫它“行为包根目录”。找到development_resource_packs（资源包文件夹）。进去，随便用英文字母为名字建个文件夹。进入这个文件夹，下文我叫它“资源包根目录”。

建立清单

在行为包根目录下创建一个叫manifest.json的文件，打开，在里面写这些内容：
{
"format_version": 2,
"header": {
"description": "这里写附加包描述",
"name": "这里写附加包名称",
"uuid": "这里写uuid，要和其他任何uuid不一样，下文有获取uuid的方法",
"version": [1, 0, 0], //版本号
"min_engine_version": [1, 19, 50] //这里决定了附加包内各种东西运作的版本，比如这里写1.19.50意味着要在附加包里用新的execute语法。同时，游戏版本低于这个就无法启动这个附加包。

},
"modules": [
  {
    "type": "data", //这里决定了这个附加包到底是什么包，data代表行为包，resources代表资源包
    "uuid": "这里写uuid，要和其他任何uuid不一样，下文有获取uuid的方法",
    "version": [1, 0, 0]
  }
]
}

在资源包根目录下创建一个叫manifest.json的文件，打开，在里面写这些内容：

{
  "format_version": 2,
  "header": {
    "description": "这里写附加包描述",
    "name": "这里写附加包名称",
    "uuid": "这里写uuid，要和其他任何uuid不一样，下文有获取uuid的方法",
    "version": [1, 0, 0], //版本号
    "min_engine_version": [1, 19, 50] //同上
  },
  "modules": [
    {
      "type": "resources", //这里决定了这个附加包到底是什么包，resources代表资源包
      "uuid": "这里写uuid，要和其他任何uuid不一样，下文有获取uuid的方法",
      "version": [1, 0, 0]
    }
  ]
}

好了，现在你就做好一个最基本的附加包了！打开游戏，你的附加包已经可以被装到存档上了。
这时，你会发现，你的附加包图标是丢失纹理的紫黑方块。把两张png格式的图片重命名为pack_icon.png，扔进行为包根目录和资源包根目录里，这图片就是你的附加包的图标。

你还会发现，即使给存档装了附加包，也没有什么新方块、新物品、新实体啥的。那很正常，你又没有定义任何东西，只是定义了附加包名字、描述和uuid。下期，我们就要向附加包内填充东西了
。
假设你还是不懂如何写一个manifest.json，我会放出一个模板，改就完了。
manifest.txt 请自行更改后缀名

一颗不帅

附加包教程：2.配方

前言

上期，我们成功创建了一个没有任何效果的附加包。这一期，我们将学习自定义配方相关内容。

准备

在行为包根目录下创建recipes文件夹，打开。
（注：以后提到“打开xxx文件夹”时，如果你没有这个文件夹，那就创建xxx文件夹。）

第一个配方

现在就可以开始了，新建一个文件，打开。注意，以后如果不特别说明，新建的文件后缀就都是.json。（关于这个文件的命名以后如果不说，那就都是你的内容的名字。例如你想要沙子合成石头，那就sand_to_stone，差不多就这样。不过这个没什么限制，但只能用英文，而且别太长就行。总之，怎么开心怎么来。）
配方有8种：有序配方、无序配方、烧炼配方、酿造配方、酿造混合配方、材料分解配方、锻造升级配方和锻造纹饰配方。其中，第一和第二种配方是工作台配方；第三种是熔炉（或高炉、烟熏炉、营火、灵魂营火）配方；第四和第五种是酿造台配方；第六种比较特殊，属于教育版独有的内容，创建世界时开启教育版选项即可使用；第七和第八种配方在锻造台上进行，负责盔甲纹饰和升级下界合金装备。
接下来，我会分别讲解这些配方的格式。

有序配方就是有图案、有顺序的配方，例如木板横着放是压力板，竖着放是木棍，这都是有序配方，原料的摆放顺序不能改。代码如下。

{
  "format_version": "1.20.10", //代码的格式版本，不同版本可使用的功能不同，见下文unlock部分
  "minecraft:recipe_shaped": {
    "description": {
      "identifier": "这里直接写配方英文名，要和文件名匹配"
    },
    "tags": [
      "crafting_table" //定义合成的标签，以后自定义方块时会用到
    ],
    "group": "stained_glass", //定义合成属于的组，目前尚不清楚有什么用途
    "priority": 1, //定义合成的优先级
    "pattern": [
      " A ",
      "ABA",
      " A "
    ], //这里就是模拟工作台的地方，相当于3*3网格。放进去的物品要用代号，只能是一个符号或者字母。空格表示不放东西。可以改变形状，例如2*2，2*3等等。
    //注意格式，可以用MT管理器的“格式化代码”功能检查格式，如果没报错就是正确格式，报错就根据错误提示修改。
    "key": {
      "A": {
        "item": "minecraft:leather", //物品ID
        "data": 0 //这里是物品数据值。
      }, //这里就是说，上面的代号表示什么。这个例子中说的是“A代表皮革”。
      "B": {
        "item": "minecraft:ender_pearl" //也是物品ID，这里是末影珍珠
      }
    },
    "unlock": [ //基岩版1.20.10新增了unlock字段，用于定义配方解锁功能。玩家获得下面列出的物品会解锁配方。此字段仅可在代码格式版本1.20.10及以上时存在，1.20.10以下时不需要此字段。
      {
        "item": "minecraft:slime"
      }
    ],
    "result": {
      "item": "supplementary:primary_stronghold", //这里是输出的物品。
      "count": 1, //这里是输出的数量，写正整数。
      "data": 0 //这里是物品数据值，关于“数据值”，查wiki。
    } //当然，也可以在result后接一个数组，把这个对象放进数组里就可以实现多个输出物品了。
  }
}

无序配方与有序配方相反，就是无顺序的配方，例如钻石块分解成钻石，无论放哪个格子，分解出的都是9个钻石，原料的摆放顺序可以改。代码如下。

{
  "format_version": "1.20.10",
  "minecraft:recipe_shapeless": {
    "description": {
      "identifier": "这里直接写配方英文名，要和文件名匹配"
    },
    "tags": [
      "crafting_table" //合成的标签，以后自定义方块时会用到
    ],
    "ingredients": [
      {
        "item": "minecraft:stone" //物品ID，这里是原料，可以有很多个原料，每个原料的物品ID允许一样，例如合成混凝土粉末时的配方。
      }
    ],
    "unlock": { //有序配方和无序配方都可以拥有unlock字段。除了使用列表表示物品以外，还可以使我对象指定上下文触发。
      "context": "PlayerInWater" //玩家在水里时解锁配方。还可以填写“None”，即永远不会触发配方。还可以填写“AlwaysUnlocked”，即配方本来就不用解锁。
    },
    "result": {
      "item": "minecraft:sand", //这里是输出的物品。
      "count": 1, //这里是输出的数量，写正整数。
      "data": 0 //这里是物品数据值，关于“数据值”，查wiki。
    } //注意，这里目前不支持有很多个输出。
  }
}

还可以添加切石机配方，其格式与无序配方相同。

{
  "format_version": "1.12",
  "minecraft:recipe_shapeless": {
    "description": {
    "identifier": "minecraft:stonecutter_brick_slab" //命名空间ID
    },
    "tags": [ "stonecutter" ], //切石机
    "ingredients": [
      {
        "item": "minecraft:brick_block", //输入的物品，只能有一个
        "data": 0 //数据值
      }
    ],
    "result": {
      "item": "minecraft:double_stone_slab", //输出的物品，只能有一种
      "data": 4, //数据值
      "count": 2 //数量
    }
  }
}

烧炼配方很简单，只需要定义输入的原料和输出的成品，如粗铁烧铁锭。代码如下。

{
  "format_version": "1.12",
  "minecraft:recipe_furnace": {
    "description": {
      "identifier": "这里直接写配方英文名，要和文件名匹配"
    },
    "tags": [
      "furnace", //熔炉
      "blast_furnace"  //高炉
    ], //这里决定什么炉可以烧，"smoker"是烟熏炉，"campfire"是篝火，"soul_campfire"是灵魂篝火。
    "input": "supplementary:calcite_ore", //输入物品
    "output": "minecraft:calcite" //输出物品
  }
}

酿造台配方比熔炉配方复杂一些，需要定义输入的原料、催化剂（指酿造台上面放的东西）和输出的成品，如药水加红石酿造加长时间的药水

酿造配方的输入、催化剂和输出忽略指定的数量值。如果酿造配方的输入可以堆叠，那么整个堆叠将被消耗。目前有一个问题，输出的物品不会与完全相同的物品堆叠在一起，不管是否指定了数据值。
酿造混合配方不将输入物品的数据值传递给输出物品。除了指定水瓶、药水、喷溅药水和滞留药水的，指定输入物品的数据值会使配方无效。
酿造容器配方将输入物品的数据值传递给输出物品，指定输入和输出的数据值会被忽略。仅允许输入水瓶、药水、喷溅药水和滞留药水。

以下是酿造混合配方的代码。

{
  "format_version": "1.12",
  "minecraft:recipe_brewing_mix": {
    "description": {
      "identifier": "这里直接写配方英文名，要和文件名匹配"
    },
    "tags": [
      "brewing_stand" //酿造台可以酿造，目前没开放接口，只能写这个
    ],
    "input": "minecraft:potion_type:water", //输入的物品ID，这里是水瓶
    "reagent": "supplementary:ender_blaze_powder", //催化剂，例如红石
    "output": "supplementary:haste_potion" //输出的物品ID，一般是药水（当然其他的也可以）
  }
}

材料分解配方主要用于教育版里的材料分解器，代码如下。

{
  "format_version": "1.14",
  "minecraft:recipe_material_reduction": {
    "description": {
      "identifier": "这里直接写配方英文名，要和文件名匹配"
    },
    "input": "minecraft:diamond", //要分解的物品
    "output": [
      {
        "count": 64, //数量
        "item": "minecraft:element_6" //一项输出，写物品ID
      },
      {
        "count": 36, //数量
        "item": "minecraft:element_6" //又一项输出，写物品ID
      }
    ], //这里是输出的物品，总共输出的物品貌似不能超过9项
    "tags": "material_reducer" //材料分解器
  }
}

锻造升级配方用于升级下界合金装备。

{
  "format_version": "1.12",
  "minecraft:recipe_smithing_transform": {
    "description": {
      "identifier": "这里直接写配方英文名，要和文件名匹配"
    },
    "tags": [
      "smithing_table" //锻造台
    ],
    "base": "minecraft:diamond_axe", //要锻造的装备，这里是钻石斧，只能是标记为可升级物品的装备
    "template": "minecraft:netherite_upgrade_smithing_template", //锻造模板，只能是下界合金升级模板
    "addition": "minecraft:netherite_ingot", //锻造材料，只能是下界合金锭
    "result": "minecraft:netherite_axe" //输出的成品，这里是下界合金斧
  }
}

锻造纹饰配方用于盔甲纹饰系统。这个配方无需填写输出物品，输出物品被自动指定为有纹饰的盔甲。

{
  "format_version": "1.20.10",
  "minecraft:recipe_smithing_trim": {
    "description": {
      "identifier": "minecraft:smithing_armor_trim" //命名空间ID
    },
    "tags": [
      "smithing_table" //锻造台
    ],
    "template": {
      "tag": "minecraft:trim_templates" //锻造模板，使用了tag指定所有锻造模板，这里只能是标记为锻造模板的物品
    },
    "base": {
      "tag": "minecraft:trimmable_armors" //可锻造的盔甲，这里只能是标记为可锻造盔甲的物品
    },
    "addition": {
      "tag": "minecraft:trim_materials" //可锻造的矿石锭、水晶等（如金锭、紫水晶碎片等），这里只能是标记为可纹饰的材料的物品
    }
  }
}

自从1.19.50以来，就可以使用tag标签作为配方的输入。只需要把原料中的 "item": ... 替换为 "tag": ... 后填写一个标签，那么所有拥有这个标签的方块和物品都可以参与合成。可以在这里(https://learn.microsoft.com/en-us/minecraft/creator/reference/content/recipereference/examples/recipetaglist)找到所有原版标签。
配方模板，自行更改后缀为zip

一颗不帅

附加包教程：3.函数

前言

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

准备

第一个函数

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

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

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

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

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

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

一颗不帅

附加包教程：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

一颗不帅

附加包教程：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命令新建一个你自己创建的迷雾了。

一颗不帅

附加包教程：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后解压

一颗不帅

附加包教程：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	物品名称，可以指定本地化键名。	字符串

行为说明：

优先尝试翻译提供的字符串，翻译失败时显示原始字符串
未指定此组件时，游戏自动生成本地化键名：
- 旧版格式：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 这样的组件。
扩展盔甲纹饰。（很久以后）
添加物品存储实体的功能。（很久以后）
目前不会添加自定义唱片。
目前不会添加自定义创造模式物品栏的标签页。

一颗不帅

附加包教程:物品(三)

::: 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":[{"事件方法": ...}]}]}]}]}] //这个也没什么不行的，你开心就好。

总结

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

一颗不帅

附加包教程：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

一颗不帅

附加包教程：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 注意
如果纹理有透明区域，游戏中可能会变黑或失真。这个我们将在下一期学习如何解决
:::

总结

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

渲染相关组件
碰撞箱组件

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

📎 附件：点击下载模板包

一颗不帅

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

总结

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

【基岩版】基岩版附加包教程

由于作者对附加包了解不深，本教程存在一些不足之处，欢迎批评指正。物品教程在第6期，方块教程在第10期，实体教程在第29期。

前言

准备

建立项目

建立清单

附加包教程：2.配方

前言

准备

第一个配方

附加包教程：3.函数

前言

准备

第一个函数

附加包教程：4.功能域

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

前言

准备

第一个功能域

总结

附加包教程：5.迷雾

准备

第一个迷雾

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

准备

第一个物品

渲染

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

前言

** 组件列表**

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

基础信息

参数表格

旧版本参数（风弹专用）

代码示例

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

minecraft:use_animation 组件

可用动画类型

代码示例

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

代码示例

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

可用装备槽位

新旧版本对比

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

杂项

menu_category 可用值说明

附加包教程:物品(三)

前言

事件方法列表

swing

shoot

damage

decrement_stack

transform_item

teleport

add_mob_effect

组件列表

`minecraft:use_animation` 组件

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