🧰 物品对象 API

在脚本引擎中，使用「物品对象」来操作和获取某一个物品栏物品的相关信息。

获取一个物品对象

从事件或API获取

通过注册事件监听函数，或者调用某些返回物品对象的函数，来获取到BDS给出的物品对象
详见 事件监听文档 - EventAPI

生成新的物品对象

通过此函数，根据给出的信息生成一个新的物品对象

mc.newItem(name,count)

• 参数：
• name : String
  物品的标准类型名，如minecraft:bread
• count : Integer
  物品堆叠数量，由于 unsigned __int8，最大值为 64
• 返回值：生成的物品对象
• 返回值类型：Item
• 如返回值为 Null 则表示生成失败

从现有的物品对象克隆

通过此函数，根据某个现有的物品对象克隆一个新的物品对象
新的物品对象与旧的对象并无关联关系
对于一个已经存在的物品对象item，有函数：

item.clone()

• 返回值：生成的新物品对象
• 返回值类型：Item
• 如返回值为 Null 则表示生成失败

通过 NBT 生成物品对象

通过此函数，根据某个NBT生成一个新的物品对象

mc.newItem(nbt)

• 参数：
• nbt : NbtCompound
  生成物品对象所使用的物品NBT
• 返回值：生成的物品对象
• 返回值类型：Item
• 如返回值为 Null 则表示生成失败

注意：不要长期保存一个物品对象
当物品对象对应的物品被销毁时，对应的物品对象将同时释放。因此，如果有长期操作某个物品的需要，请通过上述途径获取实时的物品对象

物品对象 - 属性

每一个物品对象都包含一些固定的对象属性。对于某个特定的物品对象it，有以下这些属性

这些对象属性都是只读的，无法被修改

物品对象 - 函数

每一个物品对象都包含一些可以执行的成员函数（成员方法）。对于某个特定的物品对象it，可以通过以下这些函数对这个物品进行一些操作

注意，在修改完玩家物品栏对应的物品之后，不要忘记使用玩家对象的成员函数pl.refreshItems，刷新客户端显示的玩家物品栏

判断物品对象是否为空

it.isNull()

比如说当某个格子没有任何物品的时候，你获取到的物品对象即是空

• 返回值：这个物品对象是否为空
• 返回值类型： Boolean

将此物品对象置为空（删除物品）

it.setNull()

• 返回值：是否删除成功
• 返回值类型： Boolean

将此物品对象设置为另一个物品

it.set(item)

• 参数：
• item : Item
  要赋值的物品对象
• 返回值：是否赋值成功
• 返回值类型： Boolean

设置物品耐久度

it.setDamage(damage)

• 参数:
• damage : Integer
  耐久度
• 返回值: 是否设置成功
• 返回值类型: Boolean

设置物品的附加值

it.setAux(aux)

• 参数：
• aux : Integer
  物品附加值
• 返回值：是否设置成功
• 返回值类型： Boolean

根据物品对象生成掉落物实体

通过此函数，根据物品对象，在指定的位置生成一个同样内容的掉落物实体

mc.spawnItem(item,pos)
mc.spawnItem(item,x,y,z,dimid)

• 参数：
• item : Item
  生成掉落物实体所使用的物品对象
• pos : IntPos/ FloatPos
  生成掉落物实体的位置的坐标对象（或者使用x, y, z, dimid来确定生成位置）
• 返回值：生成的掉落物实体对象
• 返回值类型：Entity
• 如返回值为 Null 则表示生成失败

获取物品对应的NBT对象

it.getNbt()

• 返回值：物品的NBT对象
• 返回值类型：NbtCompound

写入物品对应的NBT对象

it.setNbt(nbt)

• 参数：
• nbt : NbtCompound
  NBT对象
• 返回值：是否成功写入
• 返回值类型：Boolean

关于NBT对象的更多使用，请参考 NBT接口文档

设置自定义Lore

it.setLore(names)

• 参数：
• names : Array<String,String,...>
  要设置的Lore字符串的数组
• 返回值：是否设置成功
• 返回值类型： Boolean

设置自定义物品名称

it.setDisplayName(name)

• 参数:
• name : String
  新物品名称
• 返回值: 设置物品名称是否成功
• 返回值类型: Boolean

获取自定义物品名称

it.getDisplayName()

• 返回值: 自定义物品名称
• 返回值类型: String

判断是否为同类物品

it.match(item)

• 参数:
• item : Item
  被判断的物品
• 返回值: 是否为同类物品
• 返回值类型: Boolean

增加物品数量

it.addCount(count)

• 参数:
• count : Integer 要增加的数量
• 返回值: 是否设置成功
• 返回值类型: Boolean

减少物品数量

it.removeCount(count)

• 参数:
• count : Integer 要减少的数量
• 返回值: 是否设置成功
• 返回值类型: Boolean

设置物品数量

it.setCount(count)

• 参数:
• count : Integer 要设置的数量
• 返回值: 是否设置成功
• 返回值类型: Boolean