---
sidebarDepth: 1
---
# 方块状态与附加值

## GetBlockAuxValueFromStates

<span style="display:inline;color:#ff5555">服务端</span>

method in mod.server.component.blockStateCompServer.BlockStateComponentServer

- 描述

    根据方块名称和<a href="../../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#方块状态">方块状态</a>获取方块附加值AuxValue

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | blockName | str | 方块名称 |
    | states | dict | 方块状态 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | int | 方块附加值AuxValue，异常时为-1 |

- 备注
    - 基岩版1.19更新后，部分包含多个种类的方块（例如，羊毛类，珊瑚类，栅栏类等类型的方块）被拆分成单独的方块identifier及方块附加值，因此原来的方块附加值及方块状态不再适用。请注意尽量使用新的方块identifier，被拆分出来的这些单独的方块可能不会包含任何方块状态，例如橙色羊毛（minecraft:orange_wool）不会包含"color"的方块状态。因此无法使用"color"状态进行查询获取附加值。
    - 截止至基岩版1.20.10，被拆分的方块种类包含：
        1. 羊毛类方块。根据羊毛颜色拆分成独立方块
        2. 原木类方块。根据原木种类拆分成独立方块
        3. 栅栏类方块。根据栅栏种类拆分成独立方块
        4. 珊瑚类方块。根据珊瑚颜色拆分成独立方块
        5. 地毯类方块。根据地毯颜色拆分成独立方块
        6. 潜影盒类方块。根据潜影盒颜色拆分成独立方块
        7. 混凝土类方块。根据混凝土颜色拆分成独立方块

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockState(levelId)
states = comp.GetBlockAuxValueFromStates("minecraft:hopper", {"facing_direction": 0, "toggle_bit": 0})
```



## GetBlockStates

<span style="display:inline;color:#ff5555">服务端</span>

method in mod.server.component.blockStateCompServer.BlockStateComponentServer

- 描述

    获取<a href="../../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#方块状态">方块状态</a>

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(float,float,float) | 方块位置 |
    | dimensionId | int | 方块所在维度 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | dict | 方块状态，异常时为None |

- 备注
    - 仅可获取到已加载区块内的方块状态，支持获取对应维度的常加载区块内方块状态
    - 基岩版1.19更新后，部分包含多个种类的方块（例如，羊毛类，珊瑚类，栅栏类等类型的方块）被拆分成单独的方块identifier及方块附加值，因此原来的方块附加值及方块状态不再适用。请注意尽量使用新的方块identifier，被拆分出来的这些单独的方块可能不会包含任何方块状态，例如橙色羊毛（minecraft:orange_wool）不会包含"color"的方块状态。因此会返回空的状态。
    - 截止至基岩版1.20.10，被拆分的方块种类包含：
        1. 羊毛类方块。根据羊毛颜色拆分成独立方块
        2. 原木类方块。根据原木种类拆分成独立方块
        3. 栅栏类方块。根据栅栏种类拆分成独立方块
        4. 珊瑚类方块。根据珊瑚颜色拆分成独立方块
        5. 地毯类方块。根据地毯颜色拆分成独立方块
        6. 潜影盒类方块。根据潜影盒颜色拆分成独立方块
        7. 混凝土类方块。根据混凝土颜色拆分成独立方块

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockState(levelId)
comp.GetBlockStates((4,4,3), 0)
```



## GetBlockStatesFromAuxValue

<span style="display:inline;color:#ff5555">服务端</span>

method in mod.server.component.blockStateCompServer.BlockStateComponentServer

- 描述

    根据方块名称和方块附加值AuxValue获取<a href="../../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#方块状态">方块状态</a>

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | blockName | str | 方块名称 |
    | auxValue | int | 方块附加值AuxValue |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | dict | 方块状态，异常时为None |

- 备注
    - 基岩版1.19更新后，部分包含多个种类的方块（例如，羊毛类，珊瑚类，栅栏类等类型的方块）被拆分成单独的方块identifier及方块附加值，因此原来的方块附加值及方块状态不再适用。请注意尽量使用新的方块identifier，被拆分出来的这些单独的方块可能不会包含任何方块状态，例如橙色羊毛（minecraft:orange_wool）不会包含”color"的方块状态。因此查询橙色羊毛时会返回空的状态。
    - 截止至基岩版1.20.10，被拆分的方块种类包含：
        1. 羊毛类方块。根据羊毛颜色拆分成独立方块
        2. 原木类方块。根据原木种类拆分成独立方块
        3. 栅栏类方块。根据栅栏种类拆分成独立方块
        4. 珊瑚类方块。根据珊瑚颜色拆分成独立方块
        5. 地毯类方块。根据地毯颜色拆分成独立方块
        6. 潜影盒类方块。根据潜影盒颜色拆分成独立方块
        7. 混凝土类方块。根据混凝土颜色拆分成独立方块
    - 特殊值和方块状态的对应关系见[微软文档](https://learn.microsoft.com/en-us/minecraft/creator/reference/content/blockreference/examples/auxvaluetoblockstatemap?view=minecraft-bedrock-stable)

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockState(levelId)
states = comp.GetBlockStatesFromAuxValue('minecraft:sapling', 9)
```



## SetBlockStates

<span style="display:inline;color:#ff5555">服务端</span>

method in mod.server.component.blockStateCompServer.BlockStateComponentServer

- 描述

    设置<a href="../../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#方块状态">方块状态</a>

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(float,float,float) | 方块位置 |
    | data | dict | 方块状态 |
    | dimensionId | int | 方块所在维度 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 设置是否成功 |

- 备注
    - 仅可设置已加载区块内的方块状态，支持设置对应维度的常加载区块内方块状态
    - 基岩版1.19更新后，部分包含多个种类的方块（例如，羊毛类，珊瑚类，栅栏类等类型的方块）被拆分成单独的方块identifier及方块附加值，因此原来的方块附加值及方块状态不再适用。请注意尽量使用新的方块identifier，被拆分出来的这些单独的方块可能不会包含任何方块状态，例如橙色羊毛（minecraft:orange_wool）不会包含"color"的方块状态。因此无法设置"color"状态。
    - 截止至基岩版1.20.10，被拆分的方块种类包含：
        1. 羊毛类方块。根据羊毛颜色拆分成独立方块
        2. 原木类方块。根据原木种类拆分成独立方块
        3. 栅栏类方块。根据栅栏种类拆分成独立方块
        4. 珊瑚类方块。根据珊瑚颜色拆分成独立方块
        5. 地毯类方块。根据地毯颜色拆分成独立方块
        6. 潜影盒类方块。根据潜影盒颜色拆分成独立方块
        7. 混凝土类方块。根据混凝土颜色拆分成独立方块

- 示例

```python
# 将白色羊毛设置为橙色羊毛
pos = (4,4,3)
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockState(levelId)
state = comp.GetBlockStates(pos, 0) # state = { 'color': 'white' }
state['color'] = 'orange'
comp.SetBlockStates(pos, state, 0)
```