ChaEngine 相机脚本动作 ​

这组动作让 ChaUI 页面在真实运行时调用服务器上的 ChaEngine 相机系统。它适合在打开页面时切换视角、应用相机预设、播放场景镜头，并在页面关闭时恢复相机。

ChaEngine 是可选依赖：没有安装或没有启用时，页面仍然可以保存和打开，只有相机动作会被跳过。

可用动作 ​

ChaEngine_ 是固定前缀，中英文写法都必须保留，不能翻译或省略。

视角参数 ​

视角与 ID 都必须写成带引号的字符串字面量，不能直接传入页面变量。locked 只能写布尔字面量 true 或 false，省略时默认为 false。

ChaEngine_cameraPerspective("first")
ChaEngine_cameraPerspective("third_back", true)
ChaEngine_相机视角("second", false)

可直接复制的页面示例 ​

下面的页面会在打开时应用 combat-shoulder 预设，在关闭时重置相机。把预设 ID 改成你在 ChaEngine 中实际配置的 ID。

id: camera_demo
version: 1
title: "相机演示"
size:
  width: window.width
  height: window.height
coordinateMode: absolute
display:
  mode: screen
  allowEscClose: true
  screen:
    dimBackground: false
vars: {}
papi:
  refreshTicks: 20
  values: {}
events:
  open: |
    ChaEngine_cameraPreset("combat-shoulder")
  close: |
    ChaEngine_cameraReset()
methods: {}
elements: []

执行结果：页面真实打开后请求应用预设；页面关闭时请求恢复相机。编辑器的隔离预览不会调用 ChaEngine，也不会显示依赖缺失提示。

预设与场景 ​

预设适合固定的肩位、距离和输入方式：

ChaEngine_cameraPreset("combat-shoulder")
ChaEngine_相机预设("combat-shoulder")

场景适合开场、Boss 登场或剧情镜头：

ChaEngine_cameraScene("intro")
ChaEngine_相机场景("intro")

完成后可以用任一重置写法恢复：

ChaEngine_cameraReset()
ChaEngine_相机重置()

缺失与失败时会怎样 ​

• ChaEngine 未安装或未启用时，同一玩家的每个页面会话只提示一次，之后的相机动作静默跳过。
• 页面脚本检查与保存不依赖 ChaEngine 是否正在运行，因此不会因为可选依赖缺失而失败。
• 单个 ChaEngine API 请求失败时只提示并跳过当前动作，后续脚本继续执行，已经完成的页面状态不会回滚。
• 隔离预览不调用、不发包，也不显示缺失提示。

为什么参数不能使用变量 ​

客户端只上报实际执行到的稳定动作 ID。服务端会从当前页面会话对应的已保存脚本重新找到同一动作，并恢复受信任的参数，再调用 ChaEngine。这样客户端不能伪造预设 ID、场景 ID 或视角参数。

因此下面的写法会在脚本检查阶段被拒绝：

ChaEngine_cameraPerspective(vars.mode)
ChaEngine_cameraPreset(vars.preset)
ChaEngine_cameraReset("extra")

常见问题 ​

保存成功，但相机没有变化

确认服务端已经安装并启用 ChaEngine，客户端也支持对应相机功能，并检查预设或场景 ID 是否存在。

为什么预览里没有相机效果？

预览是隔离环境，不会执行服务端授权动作。请保存页面后在真实运行页面中验证。

能否把这些动作放进独立 task 的延迟后半段？

不能。本兼容能力不扩大独立任务的延迟后动作范围，请在普通页面事件或组件事件中调用。