视角 API

Perspective API 是一款用于 Minecraft 客户端模组的摄像机视角管理框架。它使用 JOML 库提供标准化接口来处理摄像机状态（位置、旋转、FOV），与 Minecraft 内部逻辑解耦。

主要特性

• 支持翻滚角：摄像机旋转通过四元数指定，完整支持翻滚角
• 平滑过渡：位置、旋转和 FOV 的插值过渡确保视角切换自然流畅
• 基于优先级的覆盖链：高优先级临时视角（例如过场动画、GUI 强制视角）自动覆盖基础视角
• 内置视角循环器：接管原版 F5 切换键，允许玩家循环切换已注册的视角

核心概念

视角

Perspective 定义了一种摄像机行为。每个视角拥有唯一的 Identifier，并通过每帧回调来修改摄像机的位置、旋转和 FOV。它还暴露了生命周期钩子（onActivate / onDeactivate）和可用性检查（isAvailable）。

当 applyTransform 和 applyFov 不做任何修改时，摄像机将回退到由 cameraType() 指定的原版摄像机类型。

视角的进入和退出过渡可分别启用或禁用。

视角注册

视角可以通过 Java SPI 机制（PerspectiveRegistrar 接口）自动发现注册，或通过注册表手动注册。

覆盖链

覆盖链是一种基于优先级的临时摄像机控制评估机制。每个条目提供一个按优先级降序评估的 Supplier<Identifier>。第一个返回有效视角 ID 的条目胜出，并应用该视角。这适用于需要临时接管摄像机的场景，如自定义 GUI 或过场动画。

视角循环器

循环器管理玩家通过原版切换键（F5）遍历的视角列表。它包含三个内置视角，对应原版的第一人称、第三人称背视和第三人称正视图。自定义视角可以添加优先级，决定其在循环中的位置。

循环器本身作为一个低优先级的覆盖条目。如果更高优先级的覆盖处于激活状态，循环器的选择将被暂时忽略。

视角修改器

修改器会在基础视角建立目标状态之后、过渡插值之前，对摄像机状态施加额外的数学变换。这对于需要在任何视角之上叠加效果（如屏幕震动、移动倾斜或载具翻滚）非常有用。

修改器通过键、优先级进行注册，并按优先级升序执行。

执行顺序： 基础视角 → 修改器（按优先级） → 清理 → 过渡

添加依赖

Modrinth Maven

符号格式："maven.modrinth:perspective-api:${version}+${loader}-${minecraft_version}"

repositories {
  exclusiveContent {
    forRepository {
      maven {
        name = "Modrinth"
        url = uri("https://api.modrinth.com/maven")
      }
    }
    filter {
      includeGroup("maven.modrinth")
    }
  }
}

dependencies {
  implementation("maven.modrinth:perspective-api:1.0.0-beta.1+fabric-26.2")
}

演示

请参阅演示模组 Perspective API Demo。