跳到正文
本頁目錄

📦 方塊對象 API

在腳本引擎中,使用「方塊對象」來操作和獲取某一類方塊的相關信息。

獲取一個方塊對象

從事件或API獲取

通過註冊事件監聽函數,或者調用某些返回方塊對象的函數,獲取到BDS給出的與相關事件有關的方塊對象
詳見 事件監聽文檔 - EventAPI

通過方塊座標獲取

通過此函數來手動生成對象,注意,你要獲取的方塊必須處於已被加載的範圍中,否則會出現問題

mc.getBlock(pos)
mc.getBlock(x,y,z,dimid)

  • 參數:
  • pos : IntPos
    方塊所在座標(或者使用x, y, z, dimid來確定方塊位置)
  • 返回值:生成的方塊對象
  • 返回值類型:Block
  • 如返回值為 Null 則表示獲取方塊失敗

注意:不要長期保存一個方塊對象
當方塊對象對應的方塊被銷燬時,對應的方塊對象將同時釋放。因此,如果有長期操作某個方塊的需要,請通過上述途徑獲取實時的方塊對象

方塊對象 - 屬性

每一個方塊對象都包含一些固定的對象屬性。對於某個特定的方塊對象bl,有以下這些屬性

屬性 含義 類型
bl.name 遊戲內顯示的方塊名稱 String
bl.type 方塊標準類型名 String
bl.id 方塊的遊戲內id Integer
bl.pos 方塊所在座標 IntPos
bl.tileData 方塊數據值 Integer
bl.variant The block variant Integer
bl.translucency 方塊透明度 Integer
bl.thickness 方塊厚度 Integer
bl.isAir 方塊是否為空氣 Boolean
bl.isBounceBlock 是否為可彈跳方塊 Boolean
bl.isButtonBlock 是否為按鈕方塊 Boolean
bl.isCropBlock 是否為農作物方塊 Boolean
bl.isDoorBlock 是否為門方塊 Boolean
bl.isFenceBlock 是否為柵欄方塊 Boolean
bl.isFenceGateBlock 是否為柵欄門方塊 Boolean
bl.isThinFenceBlock 是否為細柵欄方塊 Boolean
bl.isHeavyBlock 是否為重的方塊 Boolean
bl.isStemBlock 是否為幹方塊 Boolean
bl.isSlabBlock 是否為半轉方塊 Boolean
bl.isUnbreakable 方塊是否為不可破壞 Boolean
bl.isWaterBlockingBlock 方塊是否可阻擋水 Boolean

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

方塊對象 - 函數

每一個方塊對象都包含一些可以執行的成員函數(成員方法)。對於某個特定的方塊對象bl,可以通過以下這些函數對這個方塊進行一些操作

破壞方塊

bl.destroy(drop)

  • 參數:
  • drop : Boolean
    是否生成掉落物
  • 返回值:是否成功破壞
  • 返回值類型:Boolean

獲取方塊對應的NBT對象

bl.getNbt()

  • 返回值:方塊的NBT對象
  • 返回值類型:NbtCompound

寫入方塊對應的NBT對象

bl.setNbt(nbt)

  • 參數:
  • nbt : NbtCompound
    NBT對象
  • 返回值:是否成功寫入
  • 返回值類型:Boolean

關於NBT對象的更多使用,請參考 NBT接口文檔 注意:慎重使用此api,請考慮使用 mc.setBlock() 代替

獲取方塊的BlockState

bl.getBlockState()

  • 返回值:方塊的BlockState
  • 返回值類型:Object

方便函數,協助解析方塊BlockState並轉換為Object,方便讀取與解析
等價於腳本執行block.getNbt().getTag("states").toObject()

判斷方塊是否擁有容器

bl.hasContainer()

  • 返回值:這個方塊是否擁有容器
  • 返回值類型:Boolean

如箱子、桶等容器,他們各自擁有一個屬於自己的容器對象

獲取方塊所擁有的容器對象

bl.getContainer()

  • 返回值:這個方塊所擁有的容器對象
  • 返回值類型:Container

關於容器對象的更多使用,請參考 容器對象 API文檔

判斷方塊是否擁有方塊實體

bl.hasBlockEntity()

  • 返回值:這個方塊是否擁有方塊實體
  • 返回值類型:Boolean

獲取方塊所擁有的方塊實體

bl.getBlockEntity()

  • 返回值:這個方塊所擁有的方塊實體
  • 返回值類型:BlockEntity

刪除方塊所擁有的方塊實體

bl.removeBlockEntity()

  • 返回值:是否成功刪除
  • 返回值類型:Boolean

關於方塊實體對象的更多使用,請參考 方塊實體對象 API文檔

其他方塊函數 API

下面這些API提供了與遊戲中指定位置方塊互動的API

設置指定位置的方塊

mc.setBlock(pos, blockObject)
mc.setBlock(pos, blockString, tileData)
mc.setBlock(x, y, z, dimId, blockObject)
mc.setBlock(x, y, z, dimId, blockString, tileData)

  • 參數:

  • pos: IntPos 或 FloatPos
    目標方塊位置(或者使用 x、y、z、dimId 來確定方塊位置)

  • blockObject: Block 或 NbtCompound
    要設置成的方塊對象或方塊 NBT 數據

  • blockString:String
    方塊標準類型名(如minecraft:stone)

  • tileData:Integer
    方塊狀態值,同原版 /setBlock 指令的 tileData,默認為0,僅通過方塊類型名放置方塊時有效

  • 返回值:是否成功設置

  • 返回值類型:Boolean

通過此函數,將一個座標對應的方塊設置成另一個,類似於命令 /setblock

在指定位置生成粒子效果

mc.spawnParticle(pos,type)
mc.spawnParticle(x,y,z,dimid,type)

  • 參數:
  • pos : IntPos / FloatPos
    目標生成位置(或者使用x, y, z, dimid來確定方塊位置)
  • type : String
    要生成的粒子效果名稱(可查閱wiki得知)
  • 返回值:是否成功生成
  • 返回值類型:Boolean

粒子效果名稱可以查閱Minecraft Wiki得知,在傳入參數的時候不要忘記命名空間前綴。類似於 minecraft:heart_particle