4.2 KiB
title, description, category, nav_order, mentions
| title | description | category | nav_order | mentions | |
|---|---|---|---|---|---|
| 方块状态 | 方块状态允许你的方块拥有多种变体，每种变体通过使用置换具备独特的功能和外观。 | 基础 | 4 |
|
方块状态
:::tip 格式要求 & 最低引擎版本 1.20.30
使用方块状态时，请确保资源包清单中的 min_engine_version 设置为 1.20.20 或更高。
:::
方块状态允许你的方块拥有多种变体，每种变体通过使用置换具备独特的功能和外观。
定义状态
有效状态值可以定义为布尔值、整数或字符串数组，也可以通过对象定义为整数范围。values 数组中的第一个元素将作为默认值使用。
置换数量限制
每个状态最多可定义 16 个有效值。所有可能的状态值组合（置换）总数不应超过 65,536。
计算方块置换总数时，需将所有状态的有效值数量相乘。例如下方示例的计算公式为 3 × 2 × 3 × 6，说明该方块具有 108 种可能的置换组合。
该功能需启用 Holiday Creator Features 实验性玩法（格式版本 1.19.70 及以上）。
::: code-group
{
"format_version": "1.20.30",
"minecraft:block": {
"description": {
"identifier": "wiki:custom_block",
"states": {
"wiki:string_state_example": ["red", "green", "blue"],
"wiki:boolean_state_example": [false, true],
"wiki:integer_state_example": [1, 2, 3],
"wiki:integer_range_state_example": {
"values": { "min": 0, "max": 5 } // 等同于 [0, 1, 2, 3, 4, 5]
}
}
},
"components": { ... },
"permutations": [ ... ]
}
}
:::
获取状态值
以下列出在不同上下文中获取方块状态当前值的方法。
Molang 查询函数
可通过 block_state 查询函数获取状态值。
q.block_state('wiki:string_state_example') == 'blue'
命令参数
在 execute 和 testforblock 等命令中使用方块状态参数来检查状态值。
execute if block ~~~ wiki:custom_block["wiki:string_state_example"="blue", "wiki:integer_state_example"=4] run kill
脚本API
:::warning 实验性功能
使用 BlockPermutation.getState() 方法需启用 Beta APIs 实验性玩法。
:::
通过 BlockPermutation.getState() 方法可获取不同状态的当前值。
customBlock.permutation.getState("wiki:integer_state_example") === 3
设置状态值
命令参数
在 setblock 和 fill 等命令中使用方块状态参数来修改默认状态值。
setblock ~~~ wiki:custom_block["wiki:string_state_example"="blue", "wiki:integer_state_example"=4]
脚本API
:::warning 实验性功能
使用 BlockPermutation.withState() 方法需启用 Beta APIs 实验性玩法。
:::
BlockPermutation.withState() 方法会返回修改了指定状态值的新置换对象。可通过 Block.setPermutation() 方法应用此置换，如下所示：
customBlock.setPermutation(
customBlock.permutation.withState("wiki:boolean_state_example", false)
);
事件响应
:::warning 实验性功能
方块事件需启用 Holiday Creator Features 实验性玩法。
:::
使用 set_block_state 事件响应可以修改自定义方块状态的值。
::: code-group
"wiki:change_state": {
"set_block_state": {
"wiki:boolean_state_example": false,
"wiki:string_state_example": "'red'"
}
}
:::