跳到正文
本頁目錄

🧰 物品對象 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.name 遊戲內顯示的物品名稱 String
it.type 物品標準類型名 String
it.id 物品的遊戲內 id Integer
it.count 這個物品對象堆疊的個數 Integer
it.maxCount 這個物品對象堆疊的最大個數(在 0.16.1 時被加入) Integer
it.aux 物品附加值(如羊毛顏色) Integer
it.damage 物品已消耗耐久 Integer
it.attackDamage 物品攻擊傷害 Integer
it.maxDamage 物品最大耐久 Integer
it.lore 物品 Lore Array<String, String...>
it.isArmorItem 物品是否為盔甲 Boolean
it.isBlock 物品是否為方塊 Boolean
it.isDamageableItem 物品是否可被破壞 Boolean
it.isDamaged 物品耐久是否被消耗 Boolean
it.isEnchanted 物品是否已被附魔 Boolean
it.isEnchantingBook 物品是否為附魔書 Boolean
it.isFireResistant 物品是否防火 Boolean
it.isFullStack 物品是否已堆疊到最大堆疊數 Boolean
it.isGlint 物品是否閃爍 Boolean
it.isHorseArmorItem 物品是否為馬鎧 Boolean
it.isLiquidClipItem 物品是否可以選中液體 Boolean
it.isMusicDiscItem 物品是否為唱片 Boolean
it.isOffhandItem 物品是否可設置到副手 Boolean
it.isPotionItem 物品是否為藥水 Boolean
it.isStackable 物品是否可堆疊 Boolean
it.isWearableItem 物品是否可穿戴 Boolean

這些對象屬性都是隻讀的,無法被修改

物品對象 - 函數

每一個物品對象都包含一些可以執行的成員函數(成員方法)。對於某個特定的物品對象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

Warning

在0.19.1及以後版本中,傳入空數組會清空物品Lore。

設置自定義物品名稱

it.setDisplayName(name)

  • 參數:
  • name : String
    新物品名稱
  • 返回值: 設置物品名稱是否成功
  • 返回值類型: Boolean

獲取自定義物品名稱

Warning

此函數僅在0.19.1及以後版本可用

it.getDisplayName()

  • 返回值: 自定義物品名稱
  • 返回值類型: String

判斷是否為同類物品

it.match(item)

  • 參數:
  • item : Item
    被判斷的物品
  • 返回值: 是否為同類物品
  • 返回值類型: Boolean

增加物品數量

Warning

此函數僅在0.19.1及以後版本可用

it.addCount(count)

  • 參數:
  • count : Integer 要增加的數量
  • 返回值: 是否設置成功
  • 返回值類型: Boolean

減少物品數量

Warning

此函數僅在0.19.1及以後版本可用

it.removeCount(count)

  • 參數:
  • count : Integer 要減少的數量
  • 返回值: 是否設置成功
  • 返回值類型: Boolean

設置物品數量

Warning

此函數僅在0.19.1及以後版本可用

it.setCount(count)

  • 參數:
  • count : Integer 要設置的數量
  • 返回值: 是否設置成功
  • 返回值類型: Boolean