📦 方塊對象 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