猹件开发组

Appearance

On this page

相机预设 ​

相机预设用于保存一套可重复应用的视角、第三人称偏移、FOV、输入、碰撞、可见性和过渡配置。服务端文件放在 plugins/ChaEngine/camera/presets/，支持子目录；预设 ID 是相对于该目录且不含 .yml 的路径，例如 combat-shoulder.yml 的 ID 为 combat-shoulder。

完整配置 ​

yaml
# plugins/ChaEngine/camera/presets/combat-shoulder.yml
perspective: third_back                    # first_person、third_back、third_front 或 detached
transform:
  pivot-x: 0.0                             # 观察点向玩家局部右侧偏移
  pivot-y: 0.15                            # 观察点向上偏移
  pivot-z: 0.0                             # 观察点向玩家局部后方偏移
  shoulder-x: -0.7                         # 相机左右肩偏移；负值和正值位于不同侧
  shoulder-y: 0.1                          # 相机上下肩位偏移
  distance: 4.5                            # 相机到观察点的距离，范围 0.05～128
  yaw-offset: 0.0                          # 水平旋转附加角度
  pitch-offset: 4.0                        # 俯仰附加角度
  roll: 0.0                                # 镜头滚转角度
  fov-mode: keep                           # keep、absolute 或 multiplier
  fov-value: 1.0                           # absolute 时为 1～170；multiplier 时必须大于 0
input:
  perspective-locked: true                 # 禁止玩家主动切换视角
  look-mode: camera_orbit                  # player、camera_orbit 或 locked
  movement-mode: allow                     # allow 或 block
  movement-reference: camera_yaw           # player_body 或 camera_yaw
  recenter-mode: smooth                    # none、immediate 或 smooth
collision: clamp                           # clamp 防穿墙；ignore 忽略方块碰撞
visibility:
  render-player: true                      # 是否渲染本地玩家模型
  render-hand: false                       # 是否渲染第一人称手部
  hud: keep                                # keep 保留 HUD；hide 隐藏 HUD
cinematic: [0.12, 0.12, 0.0, 0.0]         # [上, 下, 左, 右] 黑边比例，范围均为 0～0.5
transition:
  duration-ms: 350                         # 切换到预设所需毫秒数；0 表示立即切换
  bezier: [0.25, 0.1, 0.25, 1.0]          # 三次贝塞尔曲线 x1、y1、x2、y2

cinematic 始终按 [top, bottom, left, right]，也就是 [上, 下, 左, 右] 的顺序填写。四个值是相对于当前画面宽高的比例，不是像素；[0.12, 0.12, 0.0, 0.0] 会在上下各遮住画面高度的 12%。不需要黑边时填写 [0.0, 0.0, 0.0, 0.0]。

黑边与镜头位置、旋转和 FOV 共用同一段 transition。从普通视角进入预设时，黑边会随镜头逐渐展开；停止预设时，镜头先移动回原视角位置，黑边同时收起。第一人称切到第三人称会从第一人称眼睛位置向外展开；恢复第一人称则先移动到眼睛位置，再切回第一人称显示。

变换顺序 ​

相机先以玩家或目标锚点计算观察点，再应用肩位与距离，随后处理旋转和碰撞，最后应用 FOV。这样同一套参数在六个客户端版本中含义一致。

  • pivot-* 改变相机注视的中心；X 为局部右，Y 为上，Z 为局部后。
  • shoulder-* 改变镜头相对于观察方向的肩位，不会改变观察点。
  • distance 只表示向后拉开的距离，不与另一套 Z 距离重复叠加。
  • yaw-offset、pitch-offset、roll 是附加旋转，单位为度。

FOV 模式 ​

模式fov-value 含义
keep保持客户端原本计算出的 FOV；值通常保留为 1.0
absolute直接使用指定视野角，范围 1～170
multiplier把原本 FOV 乘以指定正数

碰撞与可见性 ​

第三人称常规玩法推荐 collision: clamp，镜头靠墙时会缩短距离，避免穿墙。只有路径已经人工验证的固定演出镜头才建议使用 ignore。

隐藏 HUD 不会隐藏暂停菜单、聊天和必要的恢复入口。第一人称预设通常让 render-hand 保持开启；脱离镜头或第三人称预设通常关闭手部并按需要显示玩家模型。

应用与替换 ​

重载 ChaEngine 后，新调用使用最新预设。已经生效的会话使用启动时的快照，不会在播放中途突然跳到修改后的参数。

管理员可对在线玩家应用指定相机预设，也可以重置该玩家相机。业务插件应优先通过 ChaEngineCameraAPI.applyPreset 调用，并保存成功结果返回的会话 ID，以便只停止自己创建的会话。

常见问题 ​

预设找不到：检查文件是否位于 camera/presets/、扩展名是否为 .yml，调用时使用不带扩展名的相对路径 ID。

重载后预设全部未更新：任意预设或场景配置非法时，本次相机配置重载会保留上一份有效快照。查看服务端日志中的具体文件和字段。

镜头穿墙：把 collision 改为 clamp，并同时检查 distance 与肩位偏移是否过大。

鼠标转动带着玩家一起转：使用 look-mode: camera_orbit；player 保留的是原版观察行为。

移动方向不跟镜头：在 movement-mode: allow 时设置 movement-reference: camera_yaw。

相关文档 ​