---
sidebarDepth: 1
---
# 物品

# 索引

包括物品属性的接口，物品的生成与获取见[玩家/背包](玩家/索引.md#背包)，[实体/背包](实体/索引.md#背包)，[方块/容器](方块/索引.md#容器)，物品实体的生成与获取见[世界/实体管理](世界/索引.md#实体管理)

---

| 接口 | <div style="width: 3em"></div> | 描述 |
| --- | --- | --- |
| [CancelShearsDestoryBlockSpeed](物品.md#cancelshearsdestoryblockspeed) | <span style="display:inline;color:#ff5555">服务端</span> |  取消剪刀对某一方块的破坏速度设置 |
| [CancelShearsDestoryBlockSpeedAll](物品.md#cancelshearsdestoryblockspeedall) | <span style="display:inline;color:#ff5555">服务端</span> |  取消剪刀对全部方块的破坏速度设置 |
| [ChangeArmorTextures](物品.md#changearmortextures) | <span style="display:inline;color:#7575f9">客户端</span> | 修改盔甲在场景中显示和在UI中显示的贴图 |
| [ChangeItemTexture](物品.md#changeitemtexture) | <span style="display:inline;color:#7575f9">客户端</span> | 替换物品的贴图，修改后所有用到该贴图的物品都会被改变，后续创建的此类物品也会被改变。会同时修改物品在UI界面上的显示，手持时候的显示与场景掉落的显示。 |
| [GetCustomName](物品.md#getcustomname) | <span style="display:inline;color:#ff5555">服务端</span> | 获取物品的自定义名称，与铁砧修改的名称一致 |
| [GetItemBasicInfo](物品.md#getitembasicinfo) | <span style="display:inline;color:#ff5555">服务端</span> | 获取物品的基础信息 |
| [GetItemBasicInfo](物品.md#getitembasicinfo) | <span style="display:inline;color:#7575f9">客户端</span> | 获取物品的基础信息 |
| [GetItemDefenceAngle](物品.md#getitemdefenceangle) | <span style="display:inline;color:#ff5555">服务端</span> | 获取盾牌物品的抵挡角度范围 |
| [GetItemDurability](物品.md#getitemdurability) | <span style="display:inline;color:#ff5555">服务端</span> | 获取指定槽位的物品耐久 |
| [GetItemEffectName](物品.md#getitemeffectname) | <span style="display:inline;color:#7575f9">客户端</span> | 获取物品的状态描述，如：§7保护 0§r |
| [GetItemFormattedHoverText](物品.md#getitemformattedhovertext) | <span style="display:inline;color:#7575f9">客户端</span> | 获取物品的格式化hover文本，如：§f灾厄旗帜§r |
| [GetItemHoverName](物品.md#getitemhovername) | <span style="display:inline;color:#7575f9">客户端</span> | 获取物品的hover名称，如：灾厄旗帜§r |
| [GetItemMaxDurability](物品.md#getitemmaxdurability) | <span style="display:inline;color:#ff5555">服务端</span> | 获取指定槽位的物品耐最大耐久 |
| [GetUserDataInEvent](物品.md#getuserdatainevent) | <span style="display:inline;color:#ff5555">服务端</span> | 使物品相关服务端事件的<a href="../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a>参数带有userData。在mod初始化时调用即可 |
| [GetUserDataInEvent](物品.md#getuserdatainevent) | <span style="display:inline;color:#7575f9">客户端</span> | 使物品相关客户端事件的<a href="../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a>参数带有userData。在mod初始化时调用即可 |
| [LookupItemByName](物品.md#lookupitembyname) | <span style="display:inline;color:#ff5555">服务端</span> | 判定指定identifier的物品是否存在 |
| [SetAttackDamage](物品.md#setattackdamage) | <span style="display:inline;color:#ff5555">服务端</span> |  设置物品的攻击伤害值 |
| [SetCustomName](物品.md#setcustomname) | <span style="display:inline;color:#ff5555">服务端</span> | 设置物品的自定义名称，与使用铁砧重命名一致 |
| [SetItemDefenceAngle](物品.md#setitemdefenceangle) | <span style="display:inline;color:#ff5555">服务端</span> | 设置盾牌物品的抵挡角度范围 |
| [SetItemDurability](物品.md#setitemdurability) | <span style="display:inline;color:#ff5555">服务端</span> | 设置物品的耐久值 |
| [SetItemMaxDurability](物品.md#setitemmaxdurability) | <span style="display:inline;color:#ff5555">服务端</span> | 设置物品的最大耐久值 |
| [SetItemTierLevel](物品.md#setitemtierlevel) | <span style="display:inline;color:#ff5555">服务端</span> |  设置工具类物品的挖掘等级 |
| [SetItemTierSpeed](物品.md#setitemtierspeed) | <span style="display:inline;color:#ff5555">服务端</span> |  设置工具类物品的挖掘速度 |
| [SetMaxStackSize](物品.md#setmaxstacksize) | <span style="display:inline;color:#ff5555">服务端</span> |  设置物品的最大堆叠数量（存档） |
| [SetShearsDestoryBlockSpeed](物品.md#setshearsdestoryblockspeed) | <span style="display:inline;color:#ff5555">服务端</span> |  设置剪刀对某一方块的破坏速度 |

## CancelShearsDestoryBlockSpeed

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

     取消剪刀对某一方块的破坏速度设置

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | blockName | str | 方块名称,包含命名空间 |

- 返回值

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

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(entityId)
comp.CancelShearsDestoryBlockSpeed("minecraft:obsidian")
```



## CancelShearsDestoryBlockSpeedAll

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

     取消剪刀对全部方块的破坏速度设置

- 参数

    无

- 返回值

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

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(entityId)
comp.CancelShearsDestoryBlockSpeedAll()
```



## ChangeArmorTextures

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

method in mod.client.component.actorRenderCompClient.ActorRenderCompClient

- 描述

    修改盔甲在场景中显示和在UI中显示的贴图

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | armorIdentifier | str | 盔甲标识符，格式[namespace:name:auxvalue]，auxvalue默认为0 |
    | texturesDict | dict | 场景中目标贴图的映射表，格式可参考"definitions/attachables/diamond_helmet.json"配置 |
    | uiIconTexture | str | 盔甲UI图标的贴图, 为None或者""的话表示不修改UI上的图标 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 修改是否成功（因为采用延迟加载，此处返回成功不代表参数中的贴图路径正确，路径错误会导致渲染时贴图丢失显示异常） |

- 备注
    - 无法跟物品的贴图动画同时使用
    - 有一定性能消耗，不建议频繁调用

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateActorRender(levelId)
# 修改钻石头盔的显示为黄金头盔
textureDict = {
    "default": "textures/models/armor/gold_1",
    "enchanted": "textures/misc/enchanted_item_glint"
}
print(comp.ChangeArmorTextures("minecraft:diamond_helmet", textureDict, "textures/items/gold_helmet"))
```



## ChangeItemTexture

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

method in mod.client.component.itemCompClient.ItemCompClient

- 描述

    替换物品的贴图，修改后所有用到该贴图的物品都会被改变，后续创建的此类物品也会被改变。会同时修改物品在UI界面上的显示，手持时候的显示与场景掉落的显示。

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | identifier | str | 物品标识符，格式[namespace:name:auxvalue]，auxvalue默认为0 |
    | texturePath | str | 贴图路径 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 是否修改成功（因为采用延迟加载，此处返回成功不代表贴图路径正确，路径错误会导致渲染时贴图丢失显示异常） |

- 备注
    - 因为会同时修改用到此贴图的所有物品，所以使用的时候尽量谨慎，不建议改原版的物品，建议只用于修改用到自已定义的新贴图的物品。
    - 序列帧贴图物品暂不支持动态修改贴图
    - 部分物品有特殊逻辑无法修改：箱子，旗帜，生物头颅，盾牌，三叉戟，鱼杆

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateItem(levelId)
print(comp.ChangeItemTexture("mytool:hatchet_1:0", "textures/items/hatchet_1"))
```



## GetCustomName

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

    获取物品的自定义名称，与铁砧修改的名称一致

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemDict | dict | <a href="../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a>。如果是接口获取的itemDict，应该包含userData，即getUserData应该为True |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | str | 自定义名称 |

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
itemDict = comp.GetPlayerItem(serverApi.GetMinecraftEnum().ItemPosType.CARRIED, 0, True)
name = comp.GetCustomName(itemDict)
```



## GetItemBasicInfo

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

### 服务端接口

<span id="s0"></span>
method in mod.server.component.itemCompServer.ItemCompServer

- 描述

    获取物品的基础信息

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemName | str | item的identifier |
    | auxValue | int | 物品的附加值auxvalue，默认为0 |
    | isEnchanted | bool | 是否附魔，默认为False。用于返回的id_Aux |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | dict | 基础信息，详见备注 |

- 备注
    - auxValue默认值是0，可以不设置。如果物品不存在，返回值为None
        | 关键字     | 数据类型              | 说明     |
        | ----------| --------------------- | ---------|
        | itemName       | str | 本地化的物品名字 |
        | maxStackSize |int| 物品最大堆叠数目 |
        | maxDurability |int| 物品最大耐久值 |
        | id_Aux |int| 主要用于客户端的ui绑定，详见客户端接口 |
        | tierDict |dict| 自定义方块定义的挖掘相关的属性 netease:tier,没有设置时返回None |
        | itemCategory |str| 创造栏分类 |
        | itemType |str| 物品类型 |
        | itemTierLevel |int| 工具等级 |
        | fuelDuration |float| 燃料时长 |
        | foodNutrition |int| 食物营养值 |
        | foodSaturation |float| 食物饱食度 |
        | weaponDamage |int| 武器攻击力 |
        | armorDefense |int| 防具防御力 |
    - 部分原版物品较为特殊，获取不到个别字段的返回值
        方块类燃料获取不到燃料时长，弓、驽、三叉戟获取不到武器攻击力，蛋糕获取不到营养值和饱食度，马铠获取不到防具防御力，上述物品获取对应字段返回值为0
    - 创造栏分类说明
        | 创造栏分类 | 意义 |
        | --------- | -----|
        | construction | 建筑 |
        | nature | 自然 |
        | equipment | 装备 |
        | items | 物品 |
        | custom | 自定义 |
        | 空字符串 | 不在创造栏 |
    - 物品类型，值为空字符串或者下列类型名之一:
        | 类型名 | 意义 |
        | ----- | ----- |
        | book | 书 |
        | sword | 剑 |
        | shears | 剪刀 |
        | axe | 斧头 |
        | clock | 时钟 |
        | bucket | 桶 |
        | fishing_rod | 钓鱼竿 |
        | hoe | 锄头 |
        | shovel | 锹 |
        | pickaxe | 镐 |
        | dye | 骨粉 |
    - 工具等级代表不同的材质，没有工具等级时为值-1，工具等级与材质对应关系如下
        | 工具等级 | 材质 |
        | ------- | ---- |
        | 0 | 木制/金制工具 |
        | 1 | 石制工具 |
        | 2 | 铁制工具 |
        | 3 | 钻石工具 |

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(levelId)
comp.GetItemBasicInfo("minecraft:bow")
```



### 客户端接口

<span id="c0"></span>
method in mod.client.component.itemCompClient.ItemCompClient

- 描述

    获取物品的基础信息

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemName | str | item的identifier |
    | auxValue | int | 物品的附加值auxvalue，默认为0 |
    | isEnchanted | bool | 是否附魔，默认为False。用于返回的id_Aux |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | dict | 基础信息字典，见备注 |

- 备注
    - auxValue默认值是0，可以不设置。如果物品不存在，返回值为None
        | 关键字     | 数据类型              | 说明     |
        | ----------| --------------------- | ---------|
        | itemName       | str | 本地化的物品名字 |
        | maxStackSize |int| 物品最大堆叠数目 |
        | maxDurability |int| 物品最大耐久值 |
        | id_Aux |int| 用于给UI的inventory_item_renderer类型控件绑定#item_id_aux字段，详见备注 |
        | tierDict |dict| 自定义方块定义的挖掘相关的属性 netease:tier,没有设置时返回None |
        | itemCategory |str| 创造栏分类 |
        | itemType |str| 物品类型 |
        | itemTierLevel |int| 工具等级 |
        | fuelDuration |float| 燃料时长 |
        | foodNutrition |int| 食物营养值 |
        | foodSaturation |float| 食物饱食度 |
        | weaponDamage |int| 武器攻击力 |
        | armorDefense |int| 防具防御力 |
    - 部分原版物品较为特殊，获取不到个别字段的返回值
        方块类燃料获取不到燃料时长，弓、驽、三叉戟获取不到武器攻击力，蛋糕获取不到营养值和饱食度，马铠获取不到防具防御力，上述物品获取对应字段返回值为0
    - id_Aux字段的示例：
        在ui中添加一个inventory_item_renderer控件以及#item_id_aux的绑定
        ```json
        "my_item_renderer": {
            "type": "custom",
            "renderer": "inventory_item_renderer",
            "size": [ 160, 160 ],
            "bindings" : [
                {
                    "binding_condition" : "always_when_visible",
                    "binding_name" : "#GetItemIdAux",
                    "binding_name_override" : "#item_id_aux"
                }
            ]
        }
        ```
        
        然后在python中添加绑定回调
        ```python
        @ViewBinder.binding(ViewBinder.BF_BindInt, "#GetItemIdAux")
        def OnStarkGridResize(self):
            comp = clientApi.GetEngineCompFactory().CreateItem(levelId)
            info = comp.GetItemBasicInfo("minecraft:bow", 0, True)
            return info['id_aux']
        ```
    - 创造栏分类说明
        | 创造栏分类 | 意义 |
        | --------- | -----|
        | construction | 建筑 |
        | nature | 自然 |
        | equipment | 装备 |
        | items | 物品 |
        | custom | 自定义 |
    - 物品类型，值为空字符串或者下列类型名之一:
        | 类型名 | 意义 |
        | ----- | ----- |
        | book | 书 |
        | sword | 剑 |
        | shears | 剪刀 |
        | axe | 斧头 |
        | clock | 时钟 |
        | bucket | 桶 |
        | fishing_rod | 钓鱼竿 |
        | hoe | 锄头 |
        | shovel | 锹 |
        | pickaxe | 镐 |
        | dye | 骨粉 |
    - 工具等级代表不同的材质，没有工具等级时为值-1，工具等级与材质对应关系如下
        | 工具等级 | 材质 |
        | ------- | ---- |
        | 0 | 木制/金制工具 |
        | 1 | 石制工具 |
        | 2 | 铁制工具 |
        | 3 | 钻石工具 |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateItem(levelId)
comp.GetItemBasicInfo("minecraft:bow")
```



## GetItemDefenceAngle

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

    获取盾牌物品的抵挡角度范围

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | posType | int | [ItemPosType枚举](../枚举值/ItemPosType.md) |
    | slotPos | int | 槽位 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | list(float) | 角度范围 |

- 备注
    - 当传入的玩家id不正确，玩家手里没手持盾牌，传入不存在的槽位时，会返回空列表

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
comp.GetItemDefenceAngle(serverApi.GetMinecraftEnum().ItemPosType.INVENTORY, 0)
```



## GetItemDurability

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

    获取指定槽位的物品耐久

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | posType | int | [ItemPosType枚举](../枚举值/ItemPosType.md) |
    | slotPos | int | 槽位，当posType为ItemPosType.INVENTORY或ItemPosType.ARMOR时才有意义 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | int | 物品的耐久值 |

- 备注
    - posType设置成serverApi.GetMinecraftEnum().ItemPosType.INVENTORY可替代GetInvItemDurability；posType设置成serverApi.GetMinecraftEnum().ItemPosType.ARMOR可替代GetEquItemDurability；

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
comp.GetItemDurability(serverApi.GetMinecraftEnum().ItemPosType.INVENTORY, 1)

#替代GetInvItemDurability的方法
comp.GetItemDurability(serverApi.GetMinecraftEnum().ItemPosType.INVENTORY, 1)

#替代GetEquItemDurability的方法
comp.GetItemDurability(serverApi.GetMinecraftEnum().ItemPosType.ARMOR, 1)
```



## GetItemEffectName

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

method in mod.client.component.itemCompClient.ItemCompClient

- 描述

    获取物品的状态描述，如：§7保护 0§r

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemName | str | item的identifier |
    | auxValue | int | 物品的附加值auxValue，默认为不指定auxValue（0） |
    | userData | dict | 物品userData，默认为None |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | str | 物品的状态描述 |

- 示例

```python
# 灾厄旗帜
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateItem(levelId)
comp.GetItemEffectName("minecraft:banner", 15, {'Type': 1})
```



## GetItemFormattedHoverText

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

method in mod.client.component.itemCompClient.ItemCompClient

- 描述

    获取物品的格式化hover文本，如：§f灾厄旗帜§r

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemName | str | item的identifier |
    | auxValue | int | 物品的附加值auxValue，默认为不指定auxValue（0） |
    | showCategory | bool | 是否包括item的类别信息，默认False |
    | userData | dict | 物品userData，默认为None |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | str | 物品的格式化hover文本 |

- 示例

```python
# 灾厄旗帜
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateItem(levelId)
comp.GetItemFormattedHoverText("minecraft:banner", 15, True, {'Type': 1})
```



## GetItemHoverName

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

method in mod.client.component.itemCompClient.ItemCompClient

- 描述

    获取物品的hover名称，如：灾厄旗帜§r

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemName | str | item的identifier |
    | auxValue | int | 物品的附加值auxValue，默认为不指定auxValue（0） |
    | userData | dict | 物品userData，默认为None |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | str | 物品hover名称 |

- 示例

```python
# 灾厄旗帜
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateItem(levelId)
comp.GetItemHoverName("minecraft:banner", 15, {'Type': 1})
```



## GetItemMaxDurability

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

    获取指定槽位的物品耐最大耐久

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | posType | int | [ItemPosType枚举](../枚举值/ItemPosType.md) |
    | slotPos | int | 槽位，当posType为ItemPosType.INVENTORY或ItemPosType.ARMOR时才有意义 |
    | isUserData | bool | 如果为True，则只尝试获取该物品userData特殊设置的值，没有特殊设置过则返回0。如果为False，则会先尝试获取userData中的值，没有的话获取该类物品通用值。 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | int | 物品的最大耐久 |

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
comp.GetItemMaxDurability(serverApi.GetMinecraftEnum().ItemPosType.INVENTORY, 1, False)
```



## GetUserDataInEvent

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

### 服务端接口

<span id="s0"></span>
method in mod.server.component.itemCompServer.ItemCompServer

- 描述

    使物品相关服务端事件的<a href="../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a>参数带有userData。在mod初始化时调用即可

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | eventName | str | 引擎事件名 |

- 返回值

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

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(levelId)
# 这样调用之后，PlayerEatFoodServerEvent事件的itemDict参数会带有userData字段
comp.GetUserDataInEvent("PlayerEatFoodServerEvent")
```



### 客户端接口

<span id="c0"></span>
method in mod.client.component.itemCompClient.ItemCompClient

- 描述

    使物品相关客户端事件的<a href="../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a>参数带有userData。在mod初始化时调用即可

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | eventName | str | 引擎事件名 |

- 返回值

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

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateItem(levelId)
# 这样调用之后，ActorAcquiredItemClientEvent事件的itemDict参数会带有userData字段
comp.GetUserDataInEvent("ActorAcquiredItemClientEvent")
```



## LookupItemByName

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

method in mod.server.component.gameCompServer.GameComponentServer

- 描述

    判定指定identifier的物品是否存在

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemName | str | 物品的identifier。类似"minecraft:bed"，支持自定义物品 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | exist True为对应的物品存在，False为对应物品不存在 |

- 示例

```python
import mod.server.extraServerApi as serverApi
gameComp = serverApi.GetEngineCompFactory().CreateGame(levelId)
exist = gameComp.LookupItemByName("minecraft:bed")
```



## SetAttackDamage

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

     设置物品的攻击伤害值

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemDict | dict | <a href="../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a> |
    | attackDamage | int | 攻击伤害值 |

- 返回值

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

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
itemDict = comp.GetPlayerItem(serverApi.GetMinecraftEnum().ItemPosType.CARRIED, 0, True)
success = comp.SetAttackDamage(itemDict, 5)
if success:
    comp.SpawnItemToPlayerCarried(itemDict, playerId)
```



## SetCustomName

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

    设置物品的自定义名称，与使用铁砧重命名一致

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemDict | dict | <a href="../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a> |
    | name | str | 物品名称。支持unicode |

- 返回值

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

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
itemDict = comp.GetPlayerItem(serverApi.GetMinecraftEnum().ItemPosType.CARRIED, 0, True)
comp.SetCustomName(itemDict, '史蒂夫')
comp.SpawnItemToPlayerCarried(itemDict, playerId)
```



## SetItemDefenceAngle

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

    设置盾牌物品的抵挡角度范围

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | posType | int | [ItemPosType枚举](../枚举值/ItemPosType.md) |
    | slotPos | int | 槽位 |
    | angleLeft | float | 左边的范围，不想设置左范围传None,取值范围是[-180,180] |
    | angleRight | float | 右边的范围，不想设置右范围传None,取值范围是[-180,180],且angleLeft<angleRight |

- 返回值

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

- 备注
    - 当设置的物品不是盾牌物品时，返回False；原生盾牌会返回True但是仍然走原生的逻辑

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
comp.SetItemDefenceAngle(serverApi.GetMinecraftEnum().ItemPosType.INVENTORY, 0, -60, 70)
```



## SetItemDurability

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

    设置物品的耐久值

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | posType | int | [ItemPosType枚举](../枚举值/ItemPosType.md) |
    | slotPos | int | 槽位，当posType为ItemPosType.INVENTORY或ItemPosType.ARMOR时才有意义 |
    | durability | int | 耐久值 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 设置结果 |

- 备注
    - 设置的耐久值超过物品的最大耐久值时，使用最大耐久值；最小耐久值为0。
    - posType设置成serverApi.GetMinecraftEnum().ItemPosType.INVENTORY时可以代替SetInvItemDurability；posType设置成serverApi.GetMinecraftEnum().ItemPosType.ARMOR时可以代替SetEquItemDurability；

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
comp.SetItemDurability(serverApi.GetMinecraftEnum().ItemPosType.INVENTORY, 0, 5)

#替代SetInvItemDurability的方法
comp.SetItemDurability(serverApi.GetMinecraftEnum().ItemPosType.INVENTORY, 0, 5)
#替代SetEquItemDurability的方法
comp.SetItemDurability(serverApi.GetMinecraftEnum().ItemPosType.ARMOR, 0, 5)
```



## SetItemMaxDurability

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

    设置物品的最大耐久值

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | posType | int | [ItemPosType枚举](../枚举值/ItemPosType.md) |
    | slotPos | int | 槽位，当posType为ItemPosType.INVENTORY或ItemPosType.ARMOR时才有意义 |
    | maxDurability | int | 最大耐久值，可设为0~32767 |
    | isUserData | bool | 如果为True，则该设置只对指定物品生效，如果为False，则对同一类所有物品生效 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 设置结果 |

- 备注
    - 若物品堆叠数量大于1时，耐久度的变更对整一叠的物品生效。并且耐久度为0后，每次消耗耐久度的行为会使数量减一
    - 为物品设置的userData最大耐久度在计算时优先级最高，userData数据存盘。
    - 在砂轮或背包合并时，若两个物品都有userData，只会保留其中一个。在铁砧中修复时，最大耐久取被修复物品的耐久。
    - 当最大耐久值被更改时，当前耐久度也会按比例修复。
    - 对同一类所有物品设置的最大耐久度不存盘，每次重启世界都会重新初始化，可以通过对应item json的`minecraft:max_damage`组件设置初始化最大耐久度
    - 如果设置的是背包物品，当slot值为-1时，设置左手物品的最大耐久值

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
comp.SetItemMaxDurability(serverApi.GetMinecraftEnum().ItemPosType.INVENTORY, 0, 5, False)
```



## SetItemTierLevel

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

     设置工具类物品的挖掘等级

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemDict | dict | <a href="../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a> |
    | level | int | 挖掘等级 |

- 返回值

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

- 备注
    - 对于不总是可以破坏的方块（包括方块材质为Stone，Metal，TopSnow，Snow，Web），需要使用不同挖掘等级（level）的工具才能破坏并产生掉落物。
        | level | 类型 |
        | ----- | ---- |
        | 0     | 木   |
        | 1     | 石   |
        | 2     | 铁   |
        | 3     | 钻石 |
        | 4     | 下界 |
    - 剑和剪刀都可以对蜘蛛网进行破坏并产生掉落物；
        铲可以对雪和顶层雪进行破坏并产生掉落物；
        镐是否可以破坏判断：
        1）对于黑曜石、下界类方块、远古残骸，需要Level大于等于3的镐才能破坏并产生掉落物；
        2）对于钻石块、钻石矿石、绿宝石块、绿宝石矿石、金块、金矿石、红石矿石、发光的红石矿石，需要Level大于等于2的镐才能破坏并产生掉落物；
        3）对于铁块、铁矿石、青金石块、青金石矿石，需要Level大于等于1的镐才能破坏并产生掉落物；
        4）对于其他Stone和Metal材质的方块，需要Level大于等于0的镐才能破坏并产生掉落物。

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
itemDict = comp.GetPlayerItem(serverApi.GetMinecraftEnum().ItemPosType.CARRIED, 0, True)
success = comp.SetItemTierLevel(itemDict, 5)
if success:
    comp.SpawnItemToPlayerCarried(itemDict, playerId)
```



## SetItemTierSpeed

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

     设置工具类物品的挖掘速度

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemDict | dict | <a href="../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a> |
    | speed | float | 挖掘速度 |

- 返回值

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

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
itemDict = comp.GetPlayerItem(serverApi.GetMinecraftEnum().ItemPosType.CARRIED, 0, True)
success = comp.SetItemTierSpeed(itemDict, 32)
if success:
    comp.SpawnItemToPlayerCarried(itemDict, playerId)
```



## SetMaxStackSize

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

     设置物品的最大堆叠数量（存档）

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | itemDict | dict | <a href="../../../mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.html#物品信息字典#物品信息字典">物品信息字典</a> |
    | maxStackSize | int | 最大堆叠数量，不能超过64，如果该值小于物品的堆叠数量，会返回失败 |

- 返回值

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

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(playerId)
itemDict = comp.GetPlayerItem(serverApi.GetMinecraftEnum().ItemPosType.CARRIED, 0, True)
success = comp.SetMaxStackSize(itemDict, 32)
if success:
    comp.SpawnItemToPlayerCarried(itemDict, playerId)
```



## SetShearsDestoryBlockSpeed

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

method in mod.server.component.itemCompServer.ItemCompServer

- 描述

     设置剪刀对某一方块的破坏速度

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | blockName | str | 方块名称,包含命名空间 |
    | speed | float | 破坏速度 |

- 返回值

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

- 备注
    - 设置的速度最终会加上剪刀的附魔：效率计算
    - 原版剪刀对蜘蛛网的破坏速度为15，羊毛的破坏速度为5，也可以用该接口重写对这两个方块的破坏速度
    - 设置的速度必须大于1，否则该接口返回False

- 示例

```python
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateItem(entityId)
comp.SetShearsDestoryBlockSpeed("minecraft:obsidian", 100)
```