🎨 基礎遊戲 API

下列這些API，提供了對遊戲內容進行修改和擴展的能力。

顯然，遊戲元素接口處於整個插件體系中的核心位置，關乎到對遊戲內容的控制和擴展能力。
腳本引擎提供了豐富強大的遊戲元素接口，為你發揮創意提供方便。

🔮 遊戲元素對象

對於遊戲元素的索引，腳本引擎使用專門類型的變量來跟蹤每一個遊戲元素，並稱其為「xx對象」，如「玩家對象」或者「方塊對象」。
你可以將其理解為遊戲元素的唯一標識符。

目前，腳本引擎擁有的遊戲元素對象如下：

在後續的文檔中，你會頻繁地接觸到他們。

在遊戲中，數量眾多的 API 都需要提供座標。
引擎採用 IntPos 和 FloatPos 類型的對象來標示座標，稱之為「座標對象」。座標對象的各個成員都是可讀寫的。

其中，維度ID 屬性的取值為：0 代表主世界，1 代表下界，2 代表末地 維度文字名 屬性的取值分別為："主世界"，"下界"，"末地"

如果某種情況下維度無效，或者無法獲取，你會發現dimid的值為-1

FloatPos對象它的成員均為浮點數，多用來表示實體座標等用無法用整數表示的位置
對於某個 FloatPos 類型變量 pos，有如下這些成員：

其中，維度ID 屬性的取值為：0 代表主世界，1 代表下界，2 代表末地 維度文字名 屬性的取值分別為："主世界"，"下界"，"末地"

如果某種情況下維度無效，或者無法獲取，你會發現dimid的值為-1

對於自然支持面向對象的腳本語言，你可以直接構造座標對象，並傳入x, y, z, dimid參數
對於某些對面向對象支持一般的語言，腳本引擎也提供了輔助接口，幫助更方便地生成一個座標對象

[JavaScript] new IntPos(x,y,z,dimid)
[Lua] IntPos(x,y,z,dimid)

[JavaScript] new FloatPos(x,y,z,dimid)
[Lua] FloatPos(x,y,z,dimid)

引擎採用 DirectionAngle 對象來標示一個歐拉角，稱之為「方向角對象」。
它的兩個成員均為浮點數，多用來表示實體的朝向等方向數據方向角對象的各個成員都是可讀寫的。

對於某個 DirectionAngle 類型變量 ang，有如下這些成員：

成員	含義	類型
ang.pitch	俯仰角（-90° ~ 90°）	`Float`
ang.yaw	偏航角（旋轉角）	`Float`

由於MC的實體系統不存在自轉的概念，所以沒有翻滾角相關數據

[JavaScript] new DirectionAngle(pitch, yaw)
[Lua] DirectionAngle(pitch, yaw)

ang.toFacing()

返回值為0-3，代表 北東南西 四個基本朝向。用於快速確定實體面向的大致方向

mc.getStructure(pos1, pos2, ignoreBlocks = false, ignoreEntities = false)

mc.setStructure(nbt, pos, mirror = 0, rotation = 0)