Tutorial:制作附加包/方块:修订间差异

来自Minecraft基岩版开发Wiki
添加的内容 删除的内容
(文本替换 - 替换“Manual:附加包教程”为“Manual:制作附加包”)
(文本替换 - 替换“MoLang”为“Molang”)
(未显示5个用户的30个中间版本)
第1行: 第1行:
<!--至编者:该教程为方块的最基础教程,请勿向该教程中添加关于进阶内容的教程或详解,这会导致读者感到理解困难并且偏离总方向。若需讲解有关内容,请前往有关页面编辑或创建新的页面!-->{{Tutorial
{{about|自定义方块教程|方块开发信息|方块}}
| type = serial
< [[Manual:制作附加包/物品组件|物品组件]] | [[Manual:制作附加包/方块组件|方块组件]] >
| difficulty = normal
| series = 制作附加包
| required = [[Manual:制作附加包/开始之前|开始之前]];[[Manual:制作附加包/包的构建|包的构建]];[[Manual:制作附加包/运行、调试与导出|运行、调试与导出]]
| version = 1.16.100.59
| vname = 国际版
| devices = {{OS|win10|ios|android}}
| recommend = {{OS|win10}}
| software = {{SoftwareSprite|vs code}}
| more = [[方块]];[[纹理]]
| prevparent = 物品
| nextparent = 配方
| prev = 物品组件
| next = 方块资源定义
}}


本教程默认读者已掌握附加包的基本构架。教程为自定义方块的基础教程,关于自定义方块的更多内容请查看进阶教程页面。
本教程版本为基岩版1.16及以上版本。在阅读本教程前,请先确保自身已有一定的[[附加包]]基础。如果还未掌握,请先浏览[[Manual:制作附加包/开始之前|教程/开始之前]],[[Manual:制作附加包/包的构建|教程/包的构建]],[[Manual:制作附加包/运行、调试与导出|教程/运行、调试与导出]]和[[Manual:制作附加包/本地化|教程/本地化]]页面后再来学习本教程。在浏览完本教程之后,你将学会如何创建一个全新的自定义方块。


==概述==
==概述==
自定义方块是在[[mcwikizh:基岩版|基岩版]][[mcwikizh:基岩版1.12.0.2|beta 1.12.0.2]]中的新增内容。<ref group="注">[[mcwikizh:基岩版1.16.0|基岩版1.15]]后,方块不能被注册到创造模式物品栏且旧版本的自定义方块无法在新版本中使用。</ref>在[[mcwikizh:基岩版1.16.100.56|基岩版1.16.100.56]]及之后的部分版本更新中, [[mcwikizh:mojang|Mojang]] 为自定义方块提供了大量的接口,这使得自定义方块的功能大大增加,不过现在仍有绝大多数的接口未被开放。
自定义方块是在[[mcwikizh:基岩版|基岩版]][[mcwikizh:基岩版1.12.0.2|beta 1.12.0.2]]中的新增内容。在[[mcwikizh:基岩版1.16.100.56|基岩版1.16.100.56]]及之后的部分版本更新中, [[mcwikizh:mojang|Mojang]] 为自定义方块提供了大量的接口,这使得自定义方块的功能大大增加,不过现在仍有绝大多数的接口未被开放。


通过自定义方块,可以在游戏中创造出属于您的全新方块,并通过添加属性、组件和事件等内容赋予它许多有趣的特性。
通过自定义方块,创作者可以在游戏中创造出属于您的全新方块,并通过添加属性、组件和事件等内容赋予它许多有趣的特性。
==添加方块==
==添加方块==
添加自定义方块首先需要了解一下自定义方块行为部分的基本结构。
您可在[[行为包]]中的 <code>blocks</code> 文件夹下新增自定义的方块配置文件。其数据结构如下:<syntaxhighlight lang="json" line="1">

自定义方块配置文件存储在[[行为包]]中的 {{samp|blocks}}文件夹下,其数据结构如下:
<syntaxhighlight lang="json" line="1">
{
{
"format_version": "1.16.0",
"format_version": "1.16.0",
第19行: 第36行:
"events": {
"events": {
}, //事件
}, //事件
"permutations" [
"permutations": [
] //置换内容
] //置换
}
}
}
}
</syntaxhighlight>
</syntaxhighlight>如上,方块配置文件由描述、组件、事件与置换内容四部分构成。
如上,方块配置文件由描述、组件、事件与置换四部分内容构成。下面对上述四种基本内容进行了简要阐述:


===描述===
===描述===
第33行: 第51行:
|-
|-
|identifier
|identifier
|字符串
|String
|设置此方块的标识符。'''须包含命名空间但不得使用<code>minecraft:</code>作为命名空间'''。(除非所编辑的方块为原版方块)
|设置此方块的标识符。'''须包含命名空间但不得使用<code>minecraft:</code>作为命名空间'''。(除非所编辑的方块为原版方块)
|-
|-
|is_experimental
|is_experimental
|布尔值
|Boolean
|(可选)决定了该方块是否为实验性方块。默认值为 <code>false</code> 。若此属性值为 <code>true</code> ,则该方块需开启实验性玩法才可获得。
|(可选)决定了该方块是否为实验性方块。默认值为 <code>false</code> 。若此属性值为 <code>true</code> ,则该方块需开启实验性玩法才可获得。
|-
|-
|properties
|properties
|对象
|Object
|设置此方块所具有的一个或多个属性。例如:<code>"test:block_property": [ 0, 1, 2, 3 ]</code>,其中<code>test:block_property</code>为属性名称,数组中的参数为该方块此属性可能拥有的值(游戏默认该方块初始属性为所有属性数组中的第一个参数)。数组的参数类型可以为整数、小数、布尔值或字符串。
|设置此方块所具有的一个或多个属性。例如:<code>"test:block_property": [ 0, 1, 2, 3 ]</code>,其中<code>test:block_property</code>为属性名称,数组中的参数为该方块此属性可能拥有的值(游戏默认该方块初始属性为所有属性数组中的第一个参数)。数组的参数类型可以为整数、小数、布尔值或字符串。
|-
|-
|register_to_creative_menu
|register_to_creative_menu
|布尔值
|Boolean
|设置此方块是否出现在创造模式物品栏。(基岩版1.15.0至今由于不明原因导致此API失效,待修复)
|设置此方块是否出现在创造模式物品栏。(基岩版1.15.0至今由于不明原因导致此API失效,待修复)
|}
|}


=== 组件===
===组件===
'''组件(components)'''对象决定了该方块的功能属性,您可选择并添加您需要的组件属性。
'''组件(components)'''对象决定了该方块的功能属性,您可选择并添加您需要的组件属性。


第72行: 第90行:
}
}
</syntaxhighlight>
</syntaxhighlight>
===置换===
通过序列触发多个事件时可以为每个事件单独设置触发条件:
'''置换(permutations)'''数组储存了该方块在对应条件下会置换或新增的对应所有组件。一般使用 query.block_property<ref group="注">query.block_property 是[[Molang|Molang]]中的一项查询功能。</ref> 来获取方块属性并以此作为置换条件。
<div class="treeview">
*{{json|object|<''test_event''>}}:''事件名称''
**{{json|array|sequence}}:序列
***{{json|object|<''index''>}}:''序列的元素''
****{{json|string|condition}}:该事件触发的条件,使用[[MoLang]]来表达
****{{json|string|<''event''>}}:''[[Manual:数据驱动/方块|事件]]''
****{{json|string|target}}:事件执行的[[过滤器#字符串过滤器|目标]],默认值为<code>self</code>
***{{json|object|<''index''>}}:''序列的元素''
****'''……'''
***'''……'''
</div>
'''示例:'''
<syntaxhighlight lang="json" start="0">
"events": {
"test_event": {
"sequence": [
{
"condition": "query.block_property(test:direction) == 0",
"rotation": [ 180.0, 0.0, 0.0 ]
},
{
"condition": "query.block_property(test:direction) == 1",
"run_command": {
"command": "say Hello"
}
}
]
}
}
</syntaxhighlight>


===置换===
'''置换(permutations)'''数组储存了该方块在对应条件下会置换或新增的对应所有组件。一般使用 query.block_property<ref group="注">query.block_property 是[[MoLang|MoLang]]中的一项查询功能。</ref> 来获取方块属性并以此作为置换条件。
===示例===
===示例===
现在仿照下面的示例,通过创建一个方块的JSON行为文件来向游戏中添加一个简单的自定义方块:
<syntaxhighlight lang="json" line="1">
<syntaxhighlight lang="json" line="1">
{
{
第112行: 第100行:
"minecraft:block": {
"minecraft:block": {
"description": {
"description": {
"identifier": "test:on_interact_change_state_block",
"identifier": "example:test_block"
"properties": {
"minecraft:direction": {
}
}
},
},
"components": {
"components": {
"minecraft:loot": "loot_tables/blocks/test.json",
"minecraft:destroy_time": 1.0,
"minecraft:destroy_time": 0.55,
"minecraft:explosion_resistance": 2.5,
"minecraft:explosion_resistance": 2.5,
"minecraft:friction": 0.1,
"minecraft:friction": 0.6,
"minecraft:map_color": "#FFFFFF",
"minecraft:map_color": "#FFFFFF",
"minecraft:block_light_absorption": 15,
"minecraft:block_light_absorption": 0,
"minecraft:block_light_emission": 15,
"minecraft:block_light_emission": 0
"minecraft:on_interact": {
"event": "test_event"
}
},
"events": {
"test_event": {
"set_block_property": {
"minecraft:direction": 1
}
}
}
},
"permutations" [
"condition": "query.block_property('minecraft:direction') == 1",
"components": {
"minecraft:geometry": "geometry.test"
}
]
}
}
}
}
</syntaxhighlight>
</syntaxhighlight>

{{notelist}}


==定义资源==
==定义资源==
创建完自定义方块后,还需要对其增添纹理、音效等内容来改变其外观表现。首先需要对添加的纹理进行定义。
===block.json===
===定义纹理===
===定义纹理===
准备好两张PNG格式的图片,这里以自定义类似原版[[原木]]的方块作为示例:
===翻书动画===
==你知道吗==
*自定义方块的Json文件名称并不要求必须与物品ID相同。


[[File:Tutorial_block_textures_0.png|替代=Tutorial Block Texture|居中]]
< [[Manual:制作附加包/物品组件|物品组件]] | [[Manual:制作附加包/方块组件|方块组件]] >
<div style="display:flex; flex-direction: column; align-items: center;">{{samp|custom_log_end.png}} —— “原木”顶部和底部的图片</div>
[[File:Tutorial_block_textures_1.png|替代=Tutorial Block Texture|居中]]
<div style="display:flex; flex-direction: column; align-items: center;">{{samp|custom_log_side.png}} —— “原木”侧面的图片</div>

将这两张图片分别命名并放到资源包的{{samp|<''RP''>/textures/blocks/}}路径下,这里分别命名为“{{samp|custom_log_end.png}}”和“{{samp|custom_log_side.png}}”。

现在准备好了图片,还需要对这两张图片进行定义。创建一个名为“{{samp|terrain_texture.json}}”的文件到{{samp|<''RP''>/textures/}}路径下,然后向其中添加如下内容:
<syntaxhighlight lang="json" line="1">
{
"resource_pack_name": "tutorial_pack", //这里填写任意名称
"num_mip_levels": 4,
"padding": 8,
"texture_name": "atlas.terrain",
"texture_data": {
"log_end": { //定义后的名称
"textures": "textures/blocks/custom_log_end" //图片文件的路径
},
"log_side": {
"textures": "textures/blocks/custom_log_side"
}
}
}
</syntaxhighlight>
这样就将刚刚的{{samp|custom_log_end.png}}和{{samp|custom_log_side.png}}两张图片分别定义为了“<code>log_end</code>”和“<code>log_side</code>”这两个名称。

每添加一张新的图片都需要在{{samp|terrain_texture.json}}中定义一次,定义后的名称将用于在以后给各种文件或组件调用。

===blocks.json===
定义完了图片,现在需要将这两张图片应用到刚刚的自定义方块上,并且为它添加音效。

首先创建一个名为“{{samp|blocks.json}}”的文件到资源包根目录下,然后向其中添加如下内容:
<syntaxhighlight lang="json" line="1">
{
"format_version": [ 1, 1, 0 ],
"example:test_block": { //刚刚创建的自定义方块的标识符
"sound" : "wood", //使用木头的音效
"textures" : {
"down" : "log_end", //刚刚定义的图片名称,下同
"side" : "log_side",
"up" : "log_end"
}
}
}
</syntaxhighlight>
现在保存文件并进入游戏,将附加包添加进一个世界并进入世界,输入如下命令:
{{cmd|give @s example:test_block}}
就可以获取到刚刚添加的自定义方块了。
[[File:Tutorial_test_custom_block.png|替代=Tutorial Test Customer Block|居中|自定义“原木”被成功添加到了游戏|缩略图]]
<br>
{{notelist}}

2021年11月29日 (一) 14:35的版本

方块
系列教程
所属系列
难度
中级
前置知识
适用版本
国际版
实践设备
所需软件

本教程默认读者已掌握附加包的基本构架。教程为自定义方块的基础教程,关于自定义方块的更多内容请查看进阶教程页面。

概述

自定义方块是在基岩版beta 1.12.0.2中的新增内容。在基岩版1.16.100.56及之后的部分版本更新中, Mojang 为自定义方块提供了大量的接口,这使得自定义方块的功能大大增加,不过现在仍有绝大多数的接口未被开放。

通过自定义方块,创作者可以在游戏中创造出属于您的全新方块,并通过添加属性、组件和事件等内容赋予它许多有趣的特性。

添加方块

添加自定义方块首先需要了解一下自定义方块行为部分的基本结构。

自定义方块配置文件存储在行为包中的 blocks文件夹下,其数据结构如下:

{
  "format_version": "1.16.0",
  "minecraft:block": {
    "description": {
    }, //描述
    "components": {
    }, //组件
    "events": {
    }, //事件
    "permutations": [
    ] //置换
  }
}

如上,方块配置文件由描述、组件、事件与置换四部分内容构成。下面对上述四种基本内容进行了简要阐述:

描述

描述 (description) 对象储存了用于描述该方块的基础信息,其数据结构如下:

属性名称 数据类型 描述
identifier 字符串 设置此方块的标识符。须包含命名空间但不得使用minecraft:作为命名空间。(除非所编辑的方块为原版方块)
is_experimental 布尔值 (可选)决定了该方块是否为实验性方块。默认值为 false 。若此属性值为 true ,则该方块需开启实验性玩法才可获得。
properties 对象 设置此方块所具有的一个或多个属性。例如:"test:block_property": [ 0, 1, 2, 3 ],其中test:block_property为属性名称,数组中的参数为该方块此属性可能拥有的值(游戏默认该方块初始属性为所有属性数组中的第一个参数)。数组的参数类型可以为整数、小数、布尔值或字符串。
register_to_creative_menu 布尔值 设置此方块是否出现在创造模式物品栏。(基岩版1.15.0至今由于不明原因导致此API失效,待修复)

组件

组件(components)对象决定了该方块的功能属性,您可选择并添加您需要的组件属性。

组件分为一般组件和触发器。一般组件用于定义该方块的属性,触发器用于在特定条件下使方块触发事件。

事件

事件(events)对象储存了该方块可能用到的所有事件。

通过在一个事件下直接添加多个事件或使用序列间接添加多个事件可以使一个触发器同时触发多个事件:

示例:

"events": {
  "test_event": { //事件名称
    "set_block_property": { //第一个事件
      "minecraft:direction": 1
    },
    "run_command": { //第二个事件
      "command": "say Hello world"
    }
  }
}

置换

置换(permutations)数组储存了该方块在对应条件下会置换或新增的对应所有组件。一般使用 query.block_property[注 1] 来获取方块属性并以此作为置换条件。

示例

现在仿照下面的示例,通过创建一个方块的JSON行为文件来向游戏中添加一个简单的自定义方块:

{
  "format_version": "1.16.0",
  "minecraft:block": {
    "description": {
      "identifier": "example:test_block"
    },
    "components": {
      "minecraft:destroy_time": 1.0,
      "minecraft:explosion_resistance": 2.5,
      "minecraft:friction": 0.6,
      "minecraft:map_color": "#FFFFFF",
      "minecraft:block_light_absorption": 0,
      "minecraft:block_light_emission": 0
      }
  }
}

定义资源

创建完自定义方块后,还需要对其增添纹理、音效等内容来改变其外观表现。首先需要对添加的纹理进行定义。

定义纹理

准备好两张PNG格式的图片,这里以自定义类似原版原木的方块作为示例:

Tutorial Block Texture
custom_log_end.png —— “原木”顶部和底部的图片
Tutorial Block Texture
custom_log_side.png —— “原木”侧面的图片

将这两张图片分别命名并放到资源包的<RP>/textures/blocks/路径下,这里分别命名为“custom_log_end.png”和“custom_log_side.png”。

现在准备好了图片,还需要对这两张图片进行定义。创建一个名为“terrain_texture.json”的文件到<RP>/textures/路径下,然后向其中添加如下内容:

{
  "resource_pack_name": "tutorial_pack", //这里填写任意名称
  "num_mip_levels": 4,
  "padding": 8,
  "texture_name": "atlas.terrain",
  "texture_data": {
    "log_end": { //定义后的名称
      "textures": "textures/blocks/custom_log_end"  //图片文件的路径
    },
    "log_side": {
      "textures": "textures/blocks/custom_log_side"
    }
  }
}

这样就将刚刚的custom_log_end.pngcustom_log_side.png两张图片分别定义为了“log_end”和“log_side”这两个名称。

每添加一张新的图片都需要在terrain_texture.json中定义一次,定义后的名称将用于在以后给各种文件或组件调用。

blocks.json

定义完了图片,现在需要将这两张图片应用到刚刚的自定义方块上,并且为它添加音效。

首先创建一个名为“blocks.json”的文件到资源包根目录下,然后向其中添加如下内容:

{
  "format_version": [ 1, 1, 0 ],
  "example:test_block": { //刚刚创建的自定义方块的标识符
    "sound" : "wood", //使用木头的音效
    "textures" : {
      "down" : "log_end", //刚刚定义的图片名称,下同
      "side" : "log_side", 
      "up" : "log_end"
    }
  }
}

现在保存文件并进入游戏,将附加包添加进一个世界并进入世界,输入如下命令: /give @s example:test_block 就可以获取到刚刚添加的自定义方块了。

Tutorial Test Customer Block
自定义“原木”被成功添加到了游戏


  1. query.block_property 是Molang中的一项查询功能。