猹件开发组

Appearance

On this page

相机系统 ​

ChaEngine 相机系统允许服务端为指定玩家切换视角、锁定视角、应用第三人称镜头预设，或播放一段声明式场景镜头。客户端按实际渲染帧平滑处理移动、旋转、缩放、电影黑边和输入限制；服务端不逐帧发送位置，也不会让客户端执行任意脚本。

三种玩家视角 ​

API 名称配置/管理参数含义
FIRST_PERSONfirst / first_person第一人称
THIRD_BACKthird_back背面第三人称
THIRD_FRONTthird_front / second正面第三人称，也就是本功能中的“第二人称”

DETACHED 是场景系统使用的脱离玩家镜头，不参与玩家原版视角循环，也不作为强制切换视角的参数。

管理员可以为在线玩家设置上述视角，并决定是否开启视角锁定。锁定后，玩家不能通过原版视角切换键改变当前模式；重置相机或会话结束后恢复正常切换。

输入能力是分开控制的 ​

相机不会用一个总开关同时决定所有操作，而是把输入拆成独立策略：

配置可选值作用
perspective-lockedtrue / false是否禁止玩家主动切换第一/第三人称
look-modeplayer鼠标保持原版行为，同时改变玩家朝向
look-modecamera_orbit鼠标只环绕相机，不改变玩家朝向
look-modelocked锁定游戏内观察方向
movement-modeallow / block允许移动，或阻止移动、跳跃、冲刺和潜行
movement-referenceplayer_body / camera_yaw按玩家身体或相机水平朝向解释移动方向
recenter-modenone / immediate / smooth自由环绕结束后不回中、立即回中或平滑回中

movement-reference 只在允许移动时有意义。移动或观察被限制时，暂停菜单、聊天和恢复入口仍可使用；可跳过的场景也允许玩家按 Esc 退出。

预设与场景怎么选 ​

  • 只需要固定的肩位、距离、FOV 和输入方式时，使用相机预设。适合战斗肩射、对话近景、载具视角。
  • 需要多个关键帧连续运动时，使用场景镜头。适合开场、传送演出、Boss 登场和剧情过场。
  • 只需要临时强制第一/第三人称时，直接调用视角切换 API 或对应管理操作，不必创建预设。

场景的优先级高于普通视角控制和预设。场景结束后会恢复下层预设；最后一个远程相机会话结束后，恢复玩家进入相机控制前的原版视角与输入。

第一人称进入第三人称时，镜头从眼睛位置向外移动；恢复第一人称时，镜头先回到眼睛位置，再切换第一人称显示。场景可为进入、自然退出和主动打断分别配置过渡，并可让四边电影黑边随镜头一起展开或收起。

安全恢复 ​

以下情况会停止相关镜头并恢复可操作状态：

  • 正常播放结束或管理员停止；
  • 玩家跳过允许跳过的场景；
  • 必需的实体锚点消失或维度失效；
  • 玩家断开服务器、切换世界，或连接失去相机能力；
  • 服务端执行相机重置或插件停用。

API 返回“已发送”只表示请求已经提交，不等于客户端已经开始或完成。需要确认结果时监听 CameraStatusEvent，详见 Java API。

兼容范围 ​

相机协议、配置含义和恢复行为在 Forge 1.16.5、Forge 1.20.1，以及 NeoForge 1.21.1、1.21.4、1.21.8、1.21.11 保持一致。旧版本只在底层相机与输入接口上采用兼容实现。

相关文档 ​