API 参考 / judge 包：判定管线

TrackPose 与 CameraPose

位姿调整器链的可变传阅对象，由宿主每帧复用构造（零分配）。TrackPose 表示轨道区位姿（整轨平移 + 3D 倾斜 + 有序 op），CameraPose 表示相机位姿（位置 + 姿态 + FOV）。两者都只在链回调期间有效，禁止跨帧持有引用。

方法速览

方法	用途
`TrackPose.getOffsetX()` / `setOffsetX(double)`	读/写整轨水平偏移（画布像素，正值右移）
`TrackPose.getOffsetY()` / `setOffsetY(double)`	读/写整轨垂直偏移（画布像素，正值下移）
`TrackPose.getTiltDeg()` / `setTiltDeg(double)`	读/写轨道 3D 倾斜（度，正值顶部向后倒）
`TrackPose.translate(double, double)`	原地叠加整轨平移，返回 `this`
`TrackPose.tilt(double)`	原地叠加 3D 倾斜，返回 `this`
`TrackPose.bindOps(PoseOps)`	宿主绑定 op 追加口（模组不要调用）
`TrackPose.rotateZ(double, double, double)`	追加绕 Z 轴旋转 op
`TrackPose.rotateX(double, double, double)`	追加绕 X 轴旋转 op
`TrackPose.rotateY(double, double, double)`	追加绕 Y 轴旋转 op
`TrackPose.translate3D(double, double, double)`	追加三轴平移 op
`TrackPose.scale(double, double, double, double)`	追加以本地圆心缩放的 op
`TrackPose.toString()`	调试字符串
`CameraPose.FOV_AUTO`	fov 哨兵（`Double.NaN`，表示宿主现行推导）
`CameraPose.getX()` / `setX(double)`	读/写相机 x（内容坐标像素）
`CameraPose.getY()` / `setY(double)`	读/写相机 y（内容坐标像素，y 向下）
`CameraPose.getZ()` / `setZ(double)`	读/写相机 z（内容坐标像素，+z 向屏幕内）
`CameraPose.getYawDeg()` / `setYawDeg(double)`	读/写偏航（度，正值向右转）
`CameraPose.getPitchDeg()` / `setPitchDeg(double)`	读/写俯仰（度，正值视线上抬）
`CameraPose.getFovDeg()` / `setFovDeg(double)`	读/写垂直视场角（度）
`CameraPose.isFovAuto()`	fov 是否为 `FOV_AUTO`
`CameraPose.toString()`	调试字符串

完整签名

java

public final class TrackPose {

    public TrackPose();

    public TrackPose(double offsetX, double offsetY, double tiltDeg);

    public double getOffsetX();

    public void setOffsetX(double offsetX);

    public double getOffsetY();

    public void setOffsetY(double offsetY);

    public double getTiltDeg();

    public void setTiltDeg(double tiltDeg);

    public TrackPose translate(double dx, double dy);

    public TrackPose tilt(double deg);

    public void bindOps(PoseOps ops);

    public TrackPose rotateZ(double degrees, double pivotX, double pivotY);

    public TrackPose rotateX(double degrees, double pivotY, double pivotZ);

    public TrackPose rotateY(double degrees, double pivotX, double pivotZ);

    public TrackPose translate3D(double dx, double dy, double dz);

    public TrackPose scale(double sx, double sy, double pivotX, double pivotY);

    public String toString();
}

public final class CameraPose {

    public static final double FOV_AUTO = Double.NaN;

    public CameraPose();

    public CameraPose(double x, double y, double z, double yawDeg, double pitchDeg, double fovDeg);

    public double getX();

    public void setX(double x);

    public double getY();

    public void setY(double y);

    public double getZ();

    public void setZ(double z);

    public double getYawDeg();

    public void setYawDeg(double yawDeg);

    public double getPitchDeg();

    public void setPitchDeg(double pitchDeg);

    public double getFovDeg();

    public void setFovDeg(double fovDeg);

    public boolean isFovAuto();

    public String toString();
}

合成口径（TrackPose）：标量 offsetX/offsetY 的平移先施加（标量之间是可交换加法），再按 op 列表顺序逐项右乘；所有圆心/轴点一律写实体本地坐标（对轨道即布局量：laneX / 判定线 / 轨道区矩形），不是世界坐标，也不是「执行后」坐标。净语义：每个 op 绕「前序 op 之后，该特征所在的位置」转。

坐标与单位（CameraPose）：x/y/z 为内容坐标（画布逻辑像素），y 向下、+z 向屏幕内，默认相机在内容平面正前方（z 为负）；yawDeg/pitchDeg 单位为度（与 setTrackTilt3D 一致，注意与 MatrixStack 3D 原语的弧度口径区分）；fovDeg 为垂直视场角，传 FOV_AUTO 表示宿主现行推导（d = 内容高 × 0.5）。

TrackPose.getOffsetX()

签名：

java

double getOffsetX();

行为：当前链上的整轨水平偏移（画布像素，正值右移）。链首为既有 setter / 谱面动画的合成值，链上读到的是前一调整器改写后的值。

示例：

java

double dx = pose.getOffsetX();

TrackPose.setOffsetX(double)

签名：

java

void setOffsetX(double offsetX);

行为：绝对写入水平偏移（覆盖当前值，不是增量）。纯视觉，不影响判定。

示例：

java

pose.setOffsetX(120.0);

TrackPose.getOffsetY()

签名：

java

double getOffsetY();

行为：当前整轨垂直偏移（画布像素，正值下移）。

示例：

java

double dy = pose.getOffsetY();

TrackPose.setOffsetY(double)

签名：

java

void setOffsetY(double offsetY);

行为：绝对写入垂直偏移（覆盖当前值）。纯视觉。

示例：

java

pose.setOffsetY(-36.0);

TrackPose.getTiltDeg()

签名：

java

double getTiltDeg();

行为：当前轨道 3D 倾斜（度，正值顶部向后倒）。链尾值交给相机位姿推导；未接管时归一为相机 pitch。

示例：

java

double tilt = pose.getTiltDeg();

TrackPose.setTiltDeg(double)

签名：

java

void setTiltDeg(double tiltDeg);

行为：绝对写入 3D 倾斜（度），与 GameStateAccess#setTrackTilt3D 同语义同单位。既有 setter 通道自身把 tilt 钳制到 ±89°；adjuster 链上的写入不做二次钳制，建议自行保持在 ±89° 内。

示例：

java

pose.setTiltDeg(12.0);

TrackPose.translate(double, double)

签名：

java

TrackPose translate(double dx, double dy);

行为：在当前偏移上叠加 (dx, dy)（画布像素），返回 this 便于链式书写。多个调整器的平移自然累加。

示例：

java

pose.translate(10.0, -4.0);

TrackPose.tilt(double)

签名：

java

TrackPose tilt(double deg);

行为：在当前倾斜上叠加 deg（度），返回 this。

示例：

java

pose.tilt(2.5);

TrackPose.bindOps(PoseOps)

签名：

java

void bindOps(PoseOps ops);

行为：绑定 op 追加口（宿主内部调用）。宿主在每帧执行链前绑定、链结束后解绑；传 null 表示解绑。模组不需要也不应调用——自行改写会绕过宿主的变换栈。解绑期间 op 方法为空操作并返回 this，标量方法不受影响。

示例（宿主行为，模组不要模仿）：

java

pose.bindOps(null);   // 链结束后解绑

TrackPose.rotateZ(double, double, double)

签名：

java

TrackPose rotateZ(double degrees, double pivotX, double pivotY);

行为：追加「绕平行 Z 轴旋转」op（画布平面内，度；正值 = 屏幕顺时针，y 轴向下）。pivotX/pivotY 为实体本地坐标。op 列表保序，返回 this；回调期外为空操作。

示例：

java

pose.rotateZ(15.0, 0.0, 0.0);

TrackPose.rotateX(double, double, double)

签名：

java

TrackPose rotateX(double degrees, double pivotY, double pivotZ);

行为：追加「绕平行 X 轴旋转」op（度，轴过本地 (任意 x, pivotY, pivotZ)）。op 保序，返回 this；回调期外为空操作。

示例：

java

pose.rotateX(-8.0, 0.0, 0.0);

TrackPose.rotateY(double, double, double)

签名：

java

TrackPose rotateY(double degrees, double pivotX, double pivotZ);

行为：追加「绕平行 Y 轴旋转」op（度，轴过本地 (pivotX, 任意 y, pivotZ)）。op 保序，返回 this；回调期外为空操作。

示例：

java

pose.rotateY(5.0, 0.0, 0.0);

TrackPose.translate3D(double, double, double)

签名：

java

TrackPose translate3D(double dx, double dy, double dz);

行为：追加三轴平移 op（像素，+z 向屏幕内；在标量 translate 之外、进 op 列表并保序）。返回 this；回调期外为空操作。

示例：

java

pose.translate3D(0.0, 0.0, 40.0);

TrackPose.scale(double, double, double, double)

签名：

java

TrackPose scale(double sx, double sy, double pivotX, double pivotY);

行为：追加「以本地圆心缩放」op，等价于 translate(p) · scale(sx, sy) · translate(-p)；pivotX/pivotY 为实体本地坐标。op 保序，返回 this；回调期外为空操作。

示例：

java

pose.scale(1.02, 1.02, 0.0, 0.0);

TrackPose.toString()

签名：

java

String toString();

行为：返回调试用字符串（含 offsetX / offsetY / tilt）。不要在每帧热路径拼接它。

示例：

java

String dbg = pose.toString();

CameraPose.FOV_AUTO

签名：

java

public static final double FOV_AUTO = Double.NaN;

行为：fov 哨兵。setFovDeg(FOV_AUTO) 或新构造的 CameraPose 默认使用宿主现行推导（d = 内容高 × 0.5，z=0 平面映射与正交恒等）。用 isFovAuto() 判断，不要直接比较 NaN。

示例：

java

pose.setFovDeg(CameraPose.FOV_AUTO);

CameraPose.getX()

签名：

java

double getX();

行为：相机位置 x（内容坐标，像素）。

示例：

java

double x = pose.getX();

CameraPose.setX(double)

签名：

java

void setX(double x);

行为：绝对写入相机 x（内容坐标，像素）。纯视觉。

示例：

java

pose.setX(640.0);

CameraPose.getY()

签名：

java

double getY();

行为：相机位置 y（内容坐标，像素，y 向下）。

示例：

java

double y = pose.getY();

CameraPose.setY(double)

签名：

java

void setY(double y);

行为：绝对写入相机 y（内容坐标，像素，y 向下）。

示例：

java

pose.setY(360.0);

CameraPose.getZ()

签名：

java

double getZ();

行为：相机位置 z（内容坐标，像素，+z 向屏幕内）。默认相机为负值（内容平面正前方）。

示例：

java

double z = pose.getZ();

CameraPose.setZ(double)

签名：

java

void setZ(double z);

行为：绝对写入相机 z。有效范围约 |z| ≤ 2000；把几何挪到近裁剪面以内会被裁掉（近裁剪面 = d/3）。

示例：

java

pose.setZ(-900.0);

CameraPose.getYawDeg()

签名：

java

double getYawDeg();

行为：偏航角（度，正值向右转）。

示例：

java

double yaw = pose.getYawDeg();

CameraPose.setYawDeg(double)

签名：

java

void setYawDeg(double yawDeg);

行为：绝对写入偏航角（度，正值向右转）。

示例：

java

pose.setYawDeg(10.0);

CameraPose.getPitchDeg()

签名：

java

double getPitchDeg();

行为：俯仰角（度，正值视线上抬）。

示例：

java

double pitch = pose.getPitchDeg();

CameraPose.setPitchDeg(double)

签名：

java

void setPitchDeg(double pitchDeg);

行为：绝对写入俯仰角（度，正值视线上抬）。

示例：

java

pose.setPitchDeg(-5.0);

CameraPose.getFovDeg()

签名：

java

double getFovDeg();

行为：垂直视场角（度）。返回 Double.NaN 表示 FOV_AUTO；读取前先用 isFovAuto() 判断。

示例：

java

double fov = pose.isFovAuto() ? 70.0 : pose.getFovDeg();

CameraPose.setFovDeg(double)

签名：

java

void setFovDeg(double fovDeg);

行为：绝对写入垂直视场角（度）；传 CameraPose.FOV_AUTO 恢复宿主推导。

示例：

java

pose.setFovDeg(75.0);

CameraPose.isFovAuto()

签名：

java

boolean isFovAuto();

行为：fov 是否为 FOV_AUTO 哨兵（Double.isNaN(fovDeg)）。NaN 语义只在此收口，调用方不要自行比较 NaN。

示例：

java

if (pose.isFovAuto()) {
    pose.setFovDeg(70.0);
}

CameraPose.toString()

签名：

java

String toString();

行为：返回调试用字符串；fov 为 AUTO 时输出 AUTO，否则输出数值。不要在每帧热路径拼接。

示例：

java

String dbg = pose.toString();

线程：仅宿主调用链上使用（渲染线程）；两者都不是线程安全对象，也不得跨帧持有。

稳定性：2026-10-11 新增（2.0 起）：2.x 内只增不破。

上一页CameraPoseAdjuster 下一页SceneEntity 与 EntityPose