旋转的表示方式

在本模组的公共接口中，旋转的表示方式始终一致，与 Minecraft 版本无关。

欧拉角

当用向量表示欧拉角时，各维度含义如下：

维度	含义	正方向
x	俯仰角 pitch	向下转动
y	偏航角 yaw	从上方俯视时是顺时针旋转
z	滚转角 roll	绕视线方向顺时针旋转，也就是让画面逆时针旋转

如果使用二维向量，则将 z 视为 0。

零点

零欧拉角 (pitch, yaw, roll) = (0, 0, 0) 表示的朝向：

方向	方向向量
Forward	(0, 0, 1)
Up	(0, 1, 0)
Left	(-1, 0, 0)

TIP

本 API 的欧拉角约定与当前 Minecraft 实体和相机使用的欧拉角一致。即使未来原版内部实现改变，公共 API 仍保持这里定义的约定。

四元数

零点

恒等四元数（虚部为 0、实部为 1）表示的朝向与零欧拉角一致：

方向	方向向量
Forward	(0, 0, 1)
Up	(0, 1, 0)
Left	(-1, 0, 0)

一律使用单位四元数。

TIP

Minecraft 相机内部的恒等四元数朝向会随版本变化。Perspective API 会在桥接层处理这种差异，接入 API 的模组不应自行补偿。原版细节见 Minecraft 旋转约定。

本 API 固定采用 +Z 作为初始旋转的朝向，以对齐欧拉角零点约定。

旋转顺序

从欧拉角构造四元数时采用 Y-X-Z 旋转顺序。建议使用 PerspectiveMath.eulerDegToQuat 或 PerspectiveMath.eulerRadToQuat，避免重复实现转换细节。

单位向量

从起点指向终点的单位向量可以表示朝向，但无法表示滚转角。

从欧拉角或四元数转换为方向向量时会丢失 roll 信息。

标识符命名约定

表示角度的参数和变量必须用后缀标明单位：

• Deg 表示角度，例如 fovDeg、yawDeg
• Rad 表示弧度，例如 rollRad