🎨 基础游戏 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)