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