---
sidebarDepth: 1
---
# 方块实体

## CleanBlockTileEntityCustomData

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

method in mod.server.component.blockInfoCompServer.BlockInfoComponentServer

- 描述

    清空指定位置的特殊方块（箱子、头颅、熔炉、花盆等）绑定的TileEntity内存储的自定义数据。

- 参数

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

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 清空结果，假如对应位置的block不存在或者没有绑定的TileEntity，就会失败 |

- 备注
    - 如果dimensionId不传或传入负值，该接口使用创建组件时的playerId来定位具体维度，且仅可获取玩家附近的方块，若方块位置离玩家太远，可能无法获取到正确的返回信息。

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockInfo(playerId)
pos = (-1, 4, 34)
dimensionId = 0
suc = comp.CleanBlockTileEntityCustomData(pos, dimensionId)
print "CleanBlockTileEntityCustomData pos=%s suc=%s" % (str(pos), suc)
```



## CreateFrameEffectForBlockEntity

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.blockInfoCompClient.BlockInfoComponentClient

- 描述

    在自定义方块实体上创建序列帧特效，创建后该接口返回序列帧特效的Id，利用该Id可以使用特效/序列帧中的接口对该序列帧特效进行播放、设置位置、大小等操作。与实体的序列帧特效创建方式类似。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块所在位置 |
    | path | str | 特效资源路径，不需要后缀名，路径为resource_pack/textures文件夹下或resource_pack/effects下的序列帧资源文件的路径，路径名分别以"textures/"开头或"effects/"开头。路径名以"textures/"开头时不需要加.json后缀名， 路径名以"effects/"开头时需要加.json后缀名。 |
    | frameKeyName | str | 该序列帧特效的自定义键值名称，创建序列帧特效后可以使用该键值名称通过GetFrameEffectIdInBlockEntity接口来获取序列帧特效的id。 |
    | effectPos | tuple(float,float,float) | 特效相对自定义方块实体的位置，即以自定方块实体所在的位置为原点的坐标系下的坐标位置。 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | int或None | 创建成功则返回序列帧特效的Id，创建失败则返回None |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateBlockInfo(levelId)
# 以自定义方块实体所在的位置为原点，在这个原点上的坐标(1.0, 1.0, 1.0)的位置上使用resource_pack/textures下的资源创建序列帧特效
id1 = comp.CreateFrameEffectForBlockEntity(pos, "textures/sfxs/snow", "my_frame1", (1.0, 1.0, 1.0))
# 以自定义方块实体所在的位置为原点，在这个原点上的坐标(1.0, 1.0, 1.0)的位置上使用resource_pack/effects下的资源创建序列帧特效
id2 = comp.CreateFrameEffectForBlockEntity(pos, "effects/sfxs/snow.json", "my_frame2", (1.0, 1.0, 1.0))
```



## CreateParticleEffectForBlockEntity

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.blockInfoCompClient.BlockInfoComponentClient

- 描述

    在自定义方块实体上创建粒子特效，创建后该接口返回粒子特效的Id，利用该Id可以使用特效/粒子中的接口对该粒子特效进行播放、设置位置、大小等操作。与实体的粒子特效创建方式类似。若自定义方块实体已存在键值名称相同的特效，则不会创建新的特效，接口返回已有的特效Id。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块所在位置 |
    | path | str | 特效资源路径，需要加上后缀名（一般是json)。路径为resource_pack/effects文件下的粒子特效json文件路径，路径名以"effects/"开头。 |
    | particleKeyName | str | 该粒子特效的自定义键值名称，创建粒子特效后可以使用该键值名称通过GetParticleEffectIdInBlockEntity接口来获取粒子特效的id。 |
    | effectPos | tuple(float,float,float) | 特效相对自定义方块实体的位置，即以自定方块实体所在的位置为原点的坐标系下的坐标位置。 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | int或None | 创建成功则返回粒子特效的Id，创建失败则返回None |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateBlockInfo(levelId)
# 以自定义方块实体所在的位置为原点，在这个原点上的坐标(1.0, 1.0, 1.0)的位置上创建粒子特效
id = comp.CreateParticleEffectForBlockEntity(pos, "effects/fire.json", "my_particle1", (1.0, 1.0, 1.0))
```



## ExecuteCommandBlock

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    执行一次命令方块

- 参数

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

- 返回值

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

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
print comp.ExecuteCommandBlock((x, y, z), 0)
```



## GetBlockEntityData

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

### 服务端接口

<span id="s0"></span>
method in mod.server.component.blockEntityExDataCompServer.BlockEntityExDataCompServer

- 描述

    用于获取可操作某个自定义方块实体数据的对象，操作方式与dict类似

- 参数

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

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | BlockEntityData或None | 可操作该方块实体内数据的对象 |

- 备注
    - GetBlockEntityData返回None通常是由于该方块所在区块未加载、正在退出游戏、该方块不是自定义方块或该自定义方块的json中并未配置netease:block_entity组件。<br>在对GetBlockEntityData返回对象进行操作前，请先判断它是否为空，否则会导致```'NoneType' object has no attribute '__getitem__'```错误。
    - 支持python基本数据类型(int/float/string/bool/dict/list)，不支持tuple且**dict的key必须为字符串**
    - **存储list时，list内各项的数据类型应相同，否则将存储失败**。如[True, False]可成功存储，[True, 1, 0.5]会存储失败
    - **虽然返回的对象操作与dict相似，但并不支持嵌套存储，只允许形如blockEntityData['key'] = value的直接赋值。如blockEntityData["value5"] ["v1"] = 9或blockEntityData["value6"].append(True)的操作将无法成功存储数据。**
    - 存储整数时，若数值范围超过int所能表示的最大范围，将无法成功存储。建议将此类数值转为字符串进行存储。

- 示例

```python
import mod.server.extraServerApi as serverApi
# 设置
blockEntitycomp = serverApi.GetEngineCompFactory().CreateBlockEntityData(levelId)
dimension = 0
pos = (4, 3, 2)
# GetBlockEntityData在某些情况下会返回None，对返回结果进行操作前务必先判断它是否为空
blockEntityData = blockEntitycomp.GetBlockEntityData(dimension, pos)
# 存储数据
# 支持存储python基本数据类型(int/float/string/bool/dict/list)，不支持tuple，并且key必须为字符串
# 存储list时，list内各项的数据类型应相同，否则将存储失败
if blockEntityData:
    blockEntityData['value1'] = 10
    blockEntityData['value2'] = 3.5
    blockEntityData['value3'] = True
    blockEntityData['value4'] = "hello"
    blockEntityData['value5'] = {"v1": 10, "v2": 3.5, "v3": [0,1,2]}
    blockEntityData['value6'] = [True, False]
# 读取数据
if blockEntityData:
    value1 = blockEntityData['value1']
    value5 = blockEntityData['value5']
    # 不存在于方块实体中的数据将返回None
    valueNone = blockEntityData['valueNone']
```



<span id="s1"></span>
method in mod.server.component.blockInfoCompServer.BlockInfoComponentServer

- 描述

    用于获取方块（包括自定义方块）的数据，如需修改，请使用setblockentitydata接口

- 参数

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

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | dict或None | 方块实体内数据的对象 |

- 备注
    - 随着版本更迭，方块中包含的数据结构可能被微软团队调整，并且不会公告，使用该接口的开发者需注意版本更新时做好测试和兼容。数据编码为UTF-8
        适用于：[方块实体](https://minecraft-zh.gamepedia.com/%E6%96%B9%E5%9D%97%E5%AE%9E%E4%BD%93)
        特殊情况：末影箱的物品信息不能通过该接口获取
    - 需要注意的是，由于该接口获取的是包含原版nbttag及自定义方块的数据，为了兼容原版nbttag，Python对象在获取出来时，会做一定的转换，如：
        None -> {"__type__" : 1, "__value__": 2}
        因此，若不希望有类似转换，并且只需要获取自定义方块实体的数据, 请使用CreateBlockEntityData里的GetBlockEntityData接口

- 示例

```python
import mod.server.extraServerApi as serverApi
blockEntitycomp = serverApi.GetEngineCompFactory().CreateBlockInfo(levelId)
blockEntityData = blockEntitycomp.GetBlockEntityData(0, (4, 3, 2))
```



### 客户端接口

<span id="c0"></span>
method in mod.client.component.blockInfoCompClient.BlockInfoComponentClient

- 描述

    用于获取客户端当前维度中方块（包括自定义方块）的数据，数据只读不可写，无法获取箱子内的物品信息。

- 参数

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

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | dict或None | 方块实体内数据的对象 |

- 备注
    - 随着版本更迭，方块中包含的数据结构可能被微软团队调整，并且不会公告，使用该接口的开发者需注意版本更新时做好测试和兼容。数据编码为UTF-8
        适用于：[方块实体](https://minecraft-zh.gamepedia.com/%E6%96%B9%E5%9D%97%E5%AE%9E%E4%BD%93)
        特殊情况：末影箱的物品信息不能通过该接口获取
    - 需要注意的是，由于该接口获取的是包含原版nbttag及自定义方块的数据，为了兼容原版nbttag，Python对象在获取出来时，会做一定的转换，如：
        None -> {"__type__" : 1, "__value__": 2}
        因此，若不希望有类似转换，并且只需要获取自定义方块实体的数据, 请使用CreateBlockEntityData里的GetBlockEntityData接口

- 示例

```python
import mod.client.extraClientApi as clientApi
blockEntitycomp = clientApi.GetEngineCompFactory().CreateBlockInfo(levelId)
blockEntityData = blockEntitycomp.GetBlockEntityData((4, 3, 2))
```



## GetBlockEntityMolangValue

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.blockInfoCompClient.BlockInfoComponentClient

- 描述

    获取自定义方块实体的Molang变量的值。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块所在位置 |
    | variableName | str | molang变量的名称，以"variable."开头，并且不能包含超过两个"."。 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | float | 该molang变量的值，如该变量不存在，则返回None |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateBlockInfo(levelId)
comp.GetBlockEntityMolangValue(pos, "query.mod.idle")
```



## GetBlockTileEntityCustomData

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

method in mod.server.component.blockInfoCompServer.BlockInfoComponentServer

- 描述

    读取指定位置的特殊方块（箱子、头颅、熔炉、花盆等）绑定的TileEntity内存储的自定义数据

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 绑定TileEntity的特殊方块的位置坐标 |
    | key | str | 自定义key |
    | dimensionId | int | 方块所在维度 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | any | 设定的value值，假如对应的数据不存在，则会返回None |

- 备注
    - 如果dimensionId不传或传入负值，该接口使用创建组件时的playerId来定位具体维度，且仅可获取玩家附近的方块，若方块位置离玩家太远，可能无法获取到正确的返回信息。

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockInfo(playerId)
pos = (-1, 4, 34)
dimensionId = 0
key = "owner"
val = comp.GetBlockTileEntityCustomData(pos, key, dimensionId)
print "GetBlockTileEntityCustomData pos=%s key=%s value=%s" % (str(pos), key, val)
```



## GetBlockTileEntityWholeCustomData

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

method in mod.server.component.blockInfoCompServer.BlockInfoComponentServer

- 描述

    读取指定位置的特殊方块（箱子、头颅、熔炉、花盆等）绑定的TileEntity内存储的自定义数据字典。

- 参数

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

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | dict或None | TileEntity自定义存储数据字典，假如没有任何额外存储数据，那么返回None或者空字典 |

- 备注
    - 如果dimensionId不传或传入负值，该接口使用创建组件时的playerId来定位具体维度，且仅可获取玩家附近的方块，若方块位置离玩家太远，可能无法获取到正确的返回信息。

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockInfo(playerId)
pos = (-1, 4, 34)
dimensionId = 0
data = comp.GetBlockTileEntityWholeCustomData(pos, dimensionId)
if not data:
    print "GetBlockTileEntityWholeCustomData pos=%s return empty" % (str(pos), )
else:
    print "GetBlockTileEntityWholeCustomData pos=%s return success" % (str(pos), )
if data:
    for key, val in data.iteritems():
        print "key=%s val=%s" % (key, str(val))
```



## GetCommandBlock

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    获取命令方块的设置内容

- 参数

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

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | dict | 命令方块的设置内容，详见备注 |

- 备注
    - 返回值具体如下：
        | 键值     | 类型      | 内容      |
        | ----------------| -------------| -------------|
        | "cmd"  | str | 命令输入内容 |
        | "name"    | str | 悬浮文本内容 |
        | "mode"     | int | 命令方块类型，详见枚举[命令方块类型](../../枚举值/CommandBlockType.md) |
        | "isConditional"   | int | 触发条件，详见枚举[命令方块条件类型](../../枚举值/ConditionType.md) |
        | "redstoneMode"   | int | 红石模式，详见枚举[命令方块红石类型](../../枚举值/RedstoneModeType.md) |

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
print comp.GetCommandBlock((x, y, z), 0)
```



## GetFrameEffectIdInBlockEntity

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.blockInfoCompClient.BlockInfoComponentClient

- 描述

    获取在自定义方块实体中已创建的指定序列帧特效的Id，已创建的特效分为两种：一是通过resource_pack/entity/下的实体json文件中使用“netease_frame_effects”所定义的特效；二是使用接口CreateFrameEffectForBlockEntity创建的特效。 返回的特效Id可以使用特效/序列帧中的接口对该序列帧特效进行播放、设置位置、大小等操作。与实体的序列帧特效创建方式类似。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块所在位置 |
    | frameKeyName | str | 序列帧特效的自定义键值名称，即：netease_frame_effects: {  "keyName" : {"path“：“textures/sfxs/xxx.json”, "pos": [1.0, 1.0, 1.0f]} } 中的"keyName"，又或者是通过CreateFrameEffectForBlockEntity创建特效时该接口中填写的frameKeyName参数。 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | int或None | 返回序列帧特效的Id，该键值不存在则返回None |

- 示例

```python
# 假设自定义方块实体定义了以下特效
# "minecraft:client_entity": {
#                  ...
#       "netease_frame_effects":{
#             "my_frame1" : { "path" : "textures/sfxs/snow.json", "pos": [1.0 , 1.0 , 1.0]},
#             ...
#        }
# }
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateBlockInfo(levelId)
# 获取名为"my_frame1"这个预设特效的特效Id
id = comp.GetFrameEffectIdInBlockEntity(pos, "my_frame1")
```



## GetFrameItem

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    获取物品展示框的物品

- 参数

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

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | dict | <a href="../../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a>，获取失败或没有物品则返回None |

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
print comp.GetFrameItem((x, y, z), 0)
```



## GetFrameItemDropChange

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    获取物品展示框里物品的掉落几率

- 参数

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

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | float | 掉落几率，取值范围为[0,1]，获取失败返回-1 |

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
print comp.GetFrameItemDropChange((x, y, z), 0)
```



## GetFrameRotation

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    获取物品展示框里物品的顺时针旋转角度

- 参数

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

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | float | 旋转角度，取值范围[0~360]，获取失败返回-1 |

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
print comp.GetFrameRotation((x, y, z), 0)
```



## GetHopperSpeed

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    获取漏斗运输一个物品所需的时间（单位：刻）

- 参数

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

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | int | 运输一个物品所需的时间（单位：刻） |

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
print comp.GetHopperSpeed((x, y, z), 0)
```



## GetParticleEffectIdInBlockEntity

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.blockInfoCompClient.BlockInfoComponentClient

- 描述

    获取在自定义方块实体中已创建的指定粒子特效的Id，已创建的特效分为两种：一是通过resource_pack/entity/下的实体json文件中使用“netease_particle_effects”所定义的特效；二是使用接口CreateParticleEffectForBlockEntity创建的特效。 返回的特效Id可以使用特效/粒子中的接口对该粒子特效进行播放、设置位置、大小等操作。与实体的粒子特效创建方式类似。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块所在位置 |
    | particleKeyName | str | 粒子特效的自定义键值名称，即：netease_particle_effects: {  "keyName" : {"path“：“effects/xxx.json”, "pos": [1.0, 1.0, 1.0f]} } 中的"keyName"，又或者是通过CreateParticleEffectForBlockEntity创建特效时该接口中填写的particleKeyName参数。 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | int或None | 返回粒子特效的Id，该键值不存在则返回None |

- 示例

```python
# 需要自定义方块实体的entity.json文件具有如下定义:
# "minecraft:client_entity": {
#                  ...
#       "netease_particle_effects":{
#             "my_particle1" : { "path" : "effects/fire.json", "pos": [1.0 , 1.0 , 1.0]},
#             ...
#        }
# }
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateBlockInfo(levelId)
# 获取名为"my_particle1"这个预设特效的特效Id
id = comp.GetParticleEffectIdInBlockEntity(pos, "my_particle1")
```



## RemoveFrameEffectInBlockEntity

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.blockInfoCompClient.BlockInfoComponentClient

- 描述

    移除在自定义方块实体上创建的序列帧特效。移除后的特效Id将会失效。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块所在位置 |
    | frameKeyName | str | 该序列帧特效的自定义键值名称。 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 移除成功返回True, 该键值不存在则返回False |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateBlockInfo(levelId)
# 移除键值名为"my_frame1"的特效
comp.RemoveFrameEffectInBlockEntity(pos, "my_frame1")
```



## RemoveParticleEffectInBlockEntity

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.blockInfoCompClient.BlockInfoComponentClient

- 描述

    移除在自定义方块实体上创建的粒子特效。移除后的特效Id将会失效。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块所在位置 |
    | particleKeyName | str | 该粒子特效的自定义键值名称。 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 移除成功返回True, 该键值不存在则返回False |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateBlockInfo(levelId)
# 移除键值名为"my_particle1"的特效
comp.RemoveParticleEffectInBlockEntity(pos, "my_particle1")
```



## SetBlockEntityData

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

method in mod.server.component.blockInfoCompServer.BlockInfoComponentServer

- 描述

    用于设置方块（包括自定义方块）的数据

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | dimension | int | 维度 |
    | pos | tuple(int,int,int) | 方块所在位置 |
    | nbtData | dict | 方块实体内数据的对象，可结合GetBlockEntityData使用，获取后修改部分数据后再进行设置。如果传空dict，大部分数据不会被改变，小部分数据会被设置为默认值 |

- 返回值

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

- 备注
    - 随着版本更迭，方块中包含的数据结构可能被微软团队调整，并且不会公告，使用该接口的开发者需注意版本更新时做好测试和兼容。数据编码为UTF-8
        适用于：[方块实体](https://minecraft-zh.gamepedia.com/%E6%96%B9%E5%9D%97%E5%AE%9E%E4%BD%93)
        特殊情况：末影箱的物品信息不能通过该接口设置
        注意：面向、状态等数据修改只会影响方块实体的数据，不会影响方块的渲染表现
        切记：如果忽略游戏原有规则随意修改nbt数据，可能会导致bug或游戏崩溃

- 示例

```python
import mod.server.extraServerApi as serverApi
blockEntitycomp = serverApi.GetEngineCompFactory().CreateBlockInfo(levelId)
blockEntityData = blockEntitycomp.GetBlockEntityData(0, (4, 3, 2))
if blockEntityData:
    blockEntityData["FrontText"]["Text"]["__value__"] = "test"
    blockEntitycomp.SetBlockEntityData(0, (4, 3, 2), blockEntityData)
```



## SetBlockEntityMolangValue

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.blockInfoCompClient.BlockInfoComponentClient

- 描述

    设置自定义方块实体的Molang变量，与实体的molang变量作用相同。目前主要用于控制自定义实体的动画状态转变。Molang变量的定义方式与原版实体的Molang变量定义方法相同。详细可参考自定义方块实体动画的教学文档。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块所在位置 |
    | variableName | str | molang变量的名称，以"variable."开头，并且不能包含超过两个"."。 |
    | value | float | molang变量的值 |

- 返回值

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

- 备注
    - 注意，自定义方块实体的Molang变量与微软原版的Molang变量定义和使用方式相同， 因此不需要调用实体/molang/中的Register接口及UnRegister接口进行注册和反注册，只需在entity.json中进行定义和初始化即可，这点与微软原版实体的使用方法相同，可参考微软原版实体的entity.json文件。

- 示例

```python
# 需要自定义方块实体的entity.json文件具有如下定义:
# "minecraft:client_entity": {
#                  ...
#       "scripts":{
#             // 注册"variable.mod_is_moving"这个molang变量并将其值初始化为1.0
#             "initialize": [  "variable.mod_is_moving = 1.0;" ],
#             ...
#        }
# }
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateBlockInfo(levelId)
# 设置molang变量的值来转变动画状态
comp.SetBlockEntityMolangValue(pos, "variable.mod_is_moving", 2.0)
```



## SetBlockTileEntityCustomData

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

method in mod.server.component.blockInfoCompServer.BlockInfoComponentServer

- 描述

    设置指定位置的特殊方块（箱子、头颅、熔炉、花盆等）绑定的TileEntity内存储的自定义数据。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 绑定TileEntity的特殊方块的位置坐标 |
    | key | str | 自定义key |
    | value | any | 支持python基本数据类型，tuple不支持 |
    | dimensionId | int | 方块所在维度 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 设置结果，假如对应位置的block不存在或者没有绑定的TileEntity，就会设置失败 |

- 备注
    - 如果dimensionId不传或传入负值，该接口使用创建组件时的playerId来定位具体维度，且仅可获取玩家附近的方块，若方块位置离玩家太远，可能无法获取到正确的返回信息。

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockInfo(playerId)
pos = (-1, 4, 34)
dimensionId = 0
suc = comp.SetBlockTileEntityCustomData(pos, "owner", "Jack", dimensionId)
print "SetBlockTileEntityCustomData pos=%s suc=%s" % (str(pos), suc)
```



## SetCommandBlock

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    对命令方块进行内容设置

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块位置 |
    | dimensionId | int | 方块所在维度 |
    | cmd | str | 命令输入 |
    | name | str | 悬浮文本 |
    | mode | int | 方块类型，详见枚举[命令方块类型](../../枚举值/CommandBlockType.md) |
    | isConditional | int | 条件，详见枚举[命令方块条件类型](../../枚举值/ConditionType.md) |
    | redstoneMode | int | 红石模式，详见枚举[命令方块红石类型](../../枚举值/RedstoneModeType.md) |

- 返回值

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

- 备注
    - 如果使用该接口时，有玩家处于命令方块的操作界面会存在问题，
        （1）如果玩家修改了命令方块内容关闭ui时，客户端会向服务端发包，届时可能出现接口设置被玩家设置覆盖的情况。
        （2）如果没做修改，关闭ui会导致客户端命令方块外观不会按照服务端的修改进行改变。

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
cmd = "give @p green_candle"
name = "hello world"
mode = serverApi.GetMinecraftEnum().CommandBlockType.CYCLE
isConditional = serverApi.GetMinecraftEnum().ConditionType.UNCONDITIONAL
redstoneMode = serverApi.GetMinecraftEnum().RedstoneModeType.KEEP_ON
print comp.SetCommandBlock((x, y, z), 0, cmd, name, mode, isConditional, redstoneMode)
```



## SetEnableBlockEntityAnimations

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.blockInfoCompClient.BlockInfoComponentClient

- 描述

    设置是否开启自定义方块实体的动画效果，开启之后，自定义实体方块会按照实体文件中animation_controller所定义的动画状态机进行动画播放。关闭之后，则会停止所有动画播放。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块所在位置 |
    | enable | bool | 是否开启自定义方块实体的动画播放 |

- 返回值

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

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateBlockInfo(levelId)
comp.SetEnableBlockEntityAnimations(pos, True)
```



## SetFrameItem

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    设置物品展示框的物品

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块位置 |
    | dimensionId | int | 方块所在维度 |
    | itemDict | dict | 详见<a href="../../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a> |

- 返回值

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

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
itemDict = {
    'itemName': 'minecraft:bow',
    'count': 15,
    'enchantData': [(serverApi.GetMinecraftEnum().EnchantType.BowDamage, 1),],
    'auxValue': 0,
    'customTips':'§c new item §r',
    'extraId': 'abc',
    'userData': { },
}
print comp.SetFrameItem((x, y, z), 0, itemDict)
```



## SetFrameItemDropChange

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    设置点击物品展示框时生成掉落的几率，默认为1

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块位置 |
    | dimensionId | int | 方块所在维度 |
    | change | float | 掉落几率，取值范围为[0,1] |

- 返回值

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

- 备注
    - 展示框只在生存模式下会生成掉落物，该设置只有在展示框内有物品的时候才会存档

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
print comp.SetFrameItemDropChange((x, y, z), 0, 0)
```



## SetFrameRotation

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    设置物品展示框里物品的顺时针旋转角度

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块位置 |
    | dimensionId | int | 方块所在维度 |
    | rot | float | 旋转角度，取值范围[0~360] |

- 返回值

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

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
print comp.SetFrameRotation((x, y, z), 0, 90)
```



## SetHopperSpeed

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

method in mod.server.component.blockEntityCompServer.BlockEntityCompServer

- 描述

    设置漏斗运输一个物品所需的时间（单位：红石刻，1秒10刻），默认值为4刻，该设置存档

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | pos | tuple(int,int,int) | 方块位置 |
    | dimensionId | int | 方块所在维度 |
    | moveTime | int | 运输一个物品所需的时间（单位：刻） |

- 返回值

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

- 备注
    - 该设置会决定漏斗吸取物品和推出物品的速度，即每过一个moveTime，漏斗会从其上方吸取一个物品，同时向连接的容器输送一个物品。

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateBlockEntity(levelId)
print comp.SetHopperSpeed((x, y, z), 0, 1)
```