3D 场景与模型

scene 用来在 ChaUI 页面中放置一个真正的 3D 视口，scene_model 则是视口中的模型节点。多个模型会在同一个场景内按真实前后关系遮挡；而整个场景仍是普通页面组件，因此可以把文字、按钮、图片等 2D 组件放到它前面或后面。

这套能力适合做立体菜单、角色或物品展示台、可点击的模型入口，以及带镜头切换的剧情式界面。页面 YAML 是唯一保存来源；编辑器只是帮助你选择模型、调整位置并生成同样的配置。

使用前准备

目录模型需要客户端存在可用的 ChaEngine 模型资源和对应能力。直接资源模型同样由 ChaEngine 读取模型、动画和材质文件。缺少资源或模型能力不可用时，不能加载的模型会被跳过，但页面中的其他模型和 2D 组件仍会继续工作。

3D 编辑器、场景后处理、阴影编辑和视口交互已经同步到当前全部 ChaUIMod 客户端适配。ChaEngine 模型渲染还需要同版本的 ChaEngineMod；当前可用组合为 Forge 1.16.5、Forge 1.20.1，以及 NeoForge 1.21.1、1.21.4、1.21.8、1.21.11。这些组合均包含 ChaUISceneModelProviderV4 并返回 API_VERSION=4；仍使用 V1、V2 或 V3 provider 的旧 ChaEngineMod 会明确禁用场景模型，不会退回旧固定光照。

模型选择、视口操作和镜头状态记录的具体步骤，参见 3D 场景编辑器。

先理解层级

一个场景由一个 scene 和零个或多个 scene_model 组成：

text

页面
└─ scene（3D 视口）
   ├─ scene_model（模型 A）
   ├─ scene_model（模型 B）
   └─ scene_model（模型 C）

scene_model 必须是 scene 的直接子组件。它不能放在页面根级，也不能挂在普通布局组件下面。模型的 sceneModel.x/y/z、旋转和缩放决定其在 3D 空间中的样子；不要把模型的 layout.x/y/width/height 当作三维坐标使用。

页面层级与场景内深度是两件事：

scene 自己的根级 z 决定整个 3D 视口与页面上 2D 组件的前后关系；较小的 z 可以作为后景，较大的 z 可以覆盖在普通组件上方。
同一 scene 内的 scene_model 使用共享深度关系，模型前后的遮挡由 sceneModel.x/y/z、相机和实际几何决定，不需要手工排“渲染顺序”。
第一版不承诺半透明模型之间的全局排序。普通不透明菜单模型最稳定；需要半透明特效时，应在实际画面中检查效果。

场景组件：`scene`

先创建一个 scene，它的 layout 就是 3D 视口在页面上的位置和尺寸。下面是场景专属字段；数值字段可以写有限数字，也可以写合法的 ChaUI 数值公式。镜头状态中的九个数字例外，必须直接写有限数字。

配置项	默认值	说明
`scene.projection`	`perspective`	投影方式：`perspective` 为透视投影，有近大远小；`orthographic` 为正交投影，前后不会因距离缩放。
`scene.fov`	`45`	透视视野角，必须大于 `0` 且小于 `180`。值更大时画面更广、透视更明显。
`scene.orthographicHeight`	`2`	正交投影的可见高度，必须大于 `0`。值更大时画面缩小、可看见的范围更多。
`scene.near`	`0.01`	近平面距离，必须大于 `0`。过大时离镜头太近的模型会被裁掉。
`scene.far`	`100`	远平面距离，必须大于 `near`。过小时远处模型会被裁掉。
`scene.cameraX/Y/Z`	`0 / 0 / 8`	镜头位置。
`scene.targetX/Y/Z`	`0 / 0 / 0`	镜头看向的位置。它不能与镜头位置完全相同。
`scene.upX/Y/Z`	`0 / 1 / 0`	镜头向上的方向。它不能与视线完全平行。通常保持 `0 / 1 / 0` 即可。
`scene.lightingEnabled`	`true`	是否使用工作室光照；设为 `false` 时直接显示纹理原色、顶点 tint、overlay 与原 alpha，不再受其他场景光照字段影响。
`scene.ambientLight`	`0.55`	环境亮度，范围为 `0.0` 至 `2.0`，主要抬高背光面与暗部。
`scene.exposure`	`1.25`	曝光，范围为 `0.1` 至 `4.0`，在色调映射前调整整体明暗。
`scene.keyLightX/Y/Z`	`0.2 / 1 / -0.7`	表面指向主光的方向，三个值不能同时为 `0`。
`scene.fillLightX/Y/Z`	`-0.2 / 1 / 0.7`	补光方向，三个值不能同时为 `0`。
`scene.shadowEnabled`	旧页面 `false`；新建场景 `true`	是否让主光生成实时阴影。`lightingEnabled: false` 时该开关不会执行阴影。
`scene.shadowStrength`	`0.55`	阴影强度，范围为 `0.0` 至 `1.0`。`0` 不压暗主光，`1` 使用完整阴影强度。
`scene.shadowSoftness`	`1.5`	阴影边缘柔和度，范围为 `0.0` 至 `4.0`。数值越大，边缘越柔和。
`scene.shadowBias`	`0.0015`	阴影偏移，范围为 `0.0` 至 `0.02`。用于减轻模型表面的条纹或闪烁，过大可能让阴影与模型分离。
`scene.shadowMapSize`	`1024`	阴影质量，只能填写 `512`、`1024` 或 `2048`。分辨率越高，边缘越清晰，显存与渲染开销也越高。
`scene.toneMappingEnabled`	`true`	是否启用色调映射。关闭后仍可单独使用下面的颜色调整和效果。
`scene.toneMapping`	`aces`	色调映射方式：`linear`、`reinhard`、`filmic` 或 `aces`。
`scene.brightness`	`0`	亮度调整，范围为 `-0.5` 至 `0.5`。
`scene.contrast`	`0`	对比度调整，范围为 `-1.0` 至 `1.0`。
`scene.saturation`	`1`	饱和度，范围为 `0.0` 至 `2.0`；`0` 为灰度，`1` 保持原饱和度。
`scene.vignetteEnabled`	`false`	是否启用暗角。
`scene.vignetteAmount`	`0.5`	暗角程度，范围为 `0.0` 至 `1.5`。
`scene.vignetteHardness`	`1.5`	暗角硬度，范围为 `0.5` 至 `3.0`。
`scene.chromaticAberrationEnabled`	`false`	是否启用边缘色差。
`scene.chromaticAberration`	`0.003`	色差系数，范围为 `0.0` 至 `0.02`。
`scene.sharpenEnabled`	`false`	是否启用锐化。
`scene.sharpenStrength`	`0.3`	锐化强度，范围为 `0.0` 至 `1.0`。
`scene.colorBalanceEnabled`	`false`	是否启用暗部、中间调和高光的色彩平衡。
`scene.colorBalanceShadowsR/G/B`	`0 / 0 / 0`	暗部红、绿、蓝调整量，每项范围为 `-0.3` 至 `0.3`。
`scene.colorBalanceMidtonesR/G/B`	`0 / 0 / 0`	中间调红、绿、蓝调整量，每项范围为 `-0.3` 至 `0.3`。
`scene.colorBalanceHighlightsR/G/B`	`0 / 0 / 0`	高光红、绿、蓝调整量，每项范围为 `-0.3` 至 `0.3`。
`scene.cameraStates`	不保存状态	具名镜头状态表，用于记录镜头和供脚本平滑切换。

主光和补光填写的是方向，不是世界里的光源坐标。keyLightX/Y/Z 表示模型表面指向主光的方向；长度不会改变亮度，系统会先归一化再使用它们。环境亮度负责暗部基础照明，主光和补光保留模型体积，曝光与 ACES filmic 色调映射避免简单增亮后高光一片发白。该专用 Shader 只影响经过 ChaUI 场景 provider 提交的模型，不改变 ChaEngine 的普通世界模型。

只有主光会生成阴影，环境光和补光不会。拥有有效模型范围的可见节点会参与计算，因此同一场景中的模型可以彼此投射并接收阴影；阴影不会跨到另一个场景或 Minecraft 世界中。透明材质采用二值阴影：完全透明的空洞不会投影，但半透明区域不会产生按透明度渐变的彩色或半透明影子。

shadowMapSize 的 512 / 1024 / 2048 分别适合较小视口、常规菜单和需要更清晰边缘的展示画面，通常先用默认 1024。如果模型资源尚未准备好有效范围，当前帧会先显示无阴影工作室光照；阴影目标或资源失败时也会安全降级到无阴影工作室光照，不会让模型和页面消失。

编辑器新建场景会显式默认开启阴影，旧页面没有 shadowEnabled 时则默认关闭，并且只加载不会自动改写 YAML。旧页面没有 ambientLight 与 exposure 时会直接采用新默认值变亮。关闭工作室光照时，模型先按纹理原色和自发光绘制；已启用的场景后处理仍会作用于最终画面。当前材质只提供基础金属度、粗糙度和自发光，不包含环境贴图、Bloom、SSAO、真实次表面散射、光源颜色或距离衰减。

透视还是正交

透视模式适合有明显纵深的菜单：近处模型会更大，移动镜头时更有空间感。正交模式适合展示柜、卡牌式模型或需要固定比例的构图；切换到正交后，应使用 orthographicHeight 调整镜头远近感，而不是只改 cameraZ。

切换投影后如果画面突然很大或很小，先检查 orthographicHeight。它和透视的 fov 不是同一种单位，通常需要重新取景。

光照示例

yaml

scene:
  lightingEnabled: true # 开启工作室光照
  ambientLight: 0.55    # 暗部基础亮度，范围 0.0 至 2.0
  exposure: 1.25        # 整体曝光，范围 0.1 至 4.0
  keyLightX: 0.2        # 主光从右上前方照来
  keyLightY: 1.0
  keyLightZ: -0.7
  fillLightX: -0.2      # 补光从左上后方照来，避免背面全黑
  fillLightY: 1.0
  fillLightZ: 0.7
  shadowEnabled: true   # 只让主光生成实时阴影
  shadowStrength: 0.55  # 阴影强度，范围 0.0 至 1.0
  shadowSoftness: 1.5   # 边缘柔和度，范围 0.0 至 4.0
  shadowBias: 0.0015    # 表面偏移，范围 0.0 至 0.02
  shadowMapSize: 1024   # 质量只能选 512、1024 或 2048

后处理示例

yaml

scene:
  toneMappingEnabled: true
  toneMapping: aces             # linear / reinhard / filmic / aces
  brightness: 0.0
  contrast: 0.0
  saturation: 1.0
  vignetteEnabled: false
  vignetteAmount: 0.5
  vignetteHardness: 1.5
  chromaticAberrationEnabled: false
  chromaticAberration: 0.003
  sharpenEnabled: false
  sharpenStrength: 0.3
  colorBalanceEnabled: false
  colorBalanceShadowsR: 0.0
  colorBalanceShadowsG: 0.0
  colorBalanceShadowsB: 0.0
  colorBalanceMidtonesR: 0.0
  colorBalanceMidtonesG: 0.0
  colorBalanceMidtonesB: 0.0
  colorBalanceHighlightsR: 0.0
  colorBalanceHighlightsG: 0.0
  colorBalanceHighlightsB: 0.0

所有效果参数都可以先保存，再单独开关对应效果。色调映射默认使用 aces；其余值默认关闭或保持中性，因此旧页面不会突然出现暗角、色差、锐化或偏色。

模型组件：`scene_model`

每个 scene_model 是一个独立模型实例。即使两个节点引用同一个模型 ID，它们的动画、位置和生命周期也互不影响。模型节点需要常规组件字段（id、parent、visible、enabled、pointerEvents、layout、events 等），再加上 sceneModel 数据块。

通用变换与动画

配置项	默认值	说明
`sceneModel.x/Y/Z`	`0 / 0 / 0`	模型相对于场景原点的位置；这是三维位置，不是页面像素坐标。
`sceneModel.rotationX/Y/Z`	`0 / 0 / 0`	绕各轴旋转的角度，单位为度。
`sceneModel.scale`	`1`	统一缩放比例，必须大于 `0`。
`sceneModel.animation`	空	要播放的动画名。目录模型从模型已有动画中选择；直接资源模型填写动画资源相对路径，留空表示不指定动画。
`sceneModel.animationLoop`	`true`	动画是否循环。必须写 YAML 布尔值 `true` 或 `false`，不要加引号。
`sceneModel.metalness`	`0`	金属度，范围为 `0.0` 至 `1.0`。接近 `1` 时反射颜色更多来自模型本身。
`sceneModel.roughness`	`0.5`	粗糙度，范围为 `0.0` 至 `1.0`。值越小，高光越集中；值越大，高光越宽且柔和。
`sceneModel.emissiveColor`	`#FFFFFF`	自发光颜色，只接受完整的 `#RRGGBB`。
`sceneModel.emissiveStrength`	`0`	自发光强度，范围为 `0.0` 至 `2.0`；`0` 表示关闭自发光。

模型节点也必须保留一个合法的 layout。对于 3D 模型，它主要用于组件树、可见性和公式上下文；模型本身的位置、旋转和大小始终由 sceneModel 的变换字段控制。通常可保留 x: 0、y: 0、width: 1、height: 1。

四种模型来源

`source`	还要填写	适用场景
`entity`	`catalog: entity`、`modelId`	从 ChaEngine 实体模型目录选择已有模型。
`block`	`catalog: block`、`modelId`	从 ChaEngine 方块模型目录选择已有模型。
`item`	`catalog: item`、`modelId`	从 ChaEngine 物品模型目录选择已有三维模型，不包含纯平面贴图物品。
`custom`	`model`、`texture`，可选 `animation`	直接渲染一组模型、材质和动画资源，不依托方块或实体名称。
`custom_entity`	`model`、`texture`、`entityType`，可选 `animation`	直接资源模型，并带一个 Mod 实体类型标识。适合自定义生物模型展示。

目录来源必须让 source 与 catalog 相同：实体模型写 entity，方块模型写 block，物品模型写 item。modelId 必须是目录中实际存在的 ID；首次显示相关属性时自动读取目录，也可在来源下拉框中搜索、选择和刷新。物品模型需要同时更新 ChaUIMod 与 ChaEngineMod。

直接资源来源的 model 和 texture 必填，animation 可选。路径相对于 ChaEngine 模型资源根目录，使用 / 分隔；不能写绝对路径、Windows 盘符、反斜杠、空段、. 或 ..。custom_entity.entityType 必须是命名空间 ID，例如 some_mod:crystal_beast。

custom_entity 不会在游戏世界中额外生成生物，不会带来 AI、碰撞、掉落或网络实体同步；它只是场景中的独立 3D 模型。如果你的目标是显示当前世界里已经存在的某个 Mod 生物，请使用普通的实体渲染组件按实体来源显示它。

目录模型示例

yaml

- id: guardian
  type: scene_model
  parent: stage               # 必须直接指向 scene 组件 ID
  visible: true
  enabled: true
  pointerEvents: auto         # 允许模型接收点击事件
  layout:
    x: 0                      # 模型不靠这些字段定位
    y: 0
    width: 1
    height: 1
  sceneModel:
    source: entity            # 目录来源
    catalog: entity           # 必须和 source 一致
    modelId: example:guardian # 替换成目录中的实际模型 ID
    x: 0
    y: 0
    z: 0
    rotationX: 0
    rotationY: 25
    rotationZ: 0
    scale: 1
    animation: idle
    animationLoop: true
    metalness: 0.15
    roughness: 0.65
    emissiveColor: "#FFFFFF"
    emissiveStrength: 0.0
  events:
    leftClick: |-
      component("stage").scene.moveTo("menu_focus", 800)

`custom` 直接资源模型示例

yaml

- id: custom_guardian
  type: scene_model
  parent: stage
  visible: true
  enabled: true
  pointerEvents: auto
  layout:
    x: 0
    y: 0
    width: 1
    height: 1
  sceneModel:
    source: custom
    model: models/menu/guardian.geo.json
    animation: animations/menu/guardian.animation.json # 不需要动画时可删除这一行
    texture: textures/menu/guardian.png
    x: -1.2
    y: 0
    z: 0
    rotationX: 0
    rotationY: -20
    rotationZ: 0
    scale: 0.9
    animationLoop: true
    metalness: 0.0
    roughness: 0.5
    emissiveColor: "#66FFFF"
    emissiveStrength: 0.25

`custom_entity` 自定义生物模型示例

yaml

- id: crystal_beast
  type: scene_model
  parent: stage
  visible: true
  enabled: true
  pointerEvents: auto
  layout:
    x: 0
    y: 0
    width: 1
    height: 1
  sceneModel:
    source: custom_entity
    model: models/creatures/crystal_beast.geo.json
    animation: animations/creatures/crystal_beast.animation.json
    texture: textures/creatures/crystal_beast.png
    entityType: some_mod:crystal_beast
    x: 1.3
    y: 0
    z: -0.6
    rotationX: 0
    rotationY: 160
    rotationZ: 0
    scale: 0.8
    animationLoop: true

不要把目录引用的 catalog + modelId 与直接资源的 model + texture 混在同一个节点里。先在编辑器中切换来源，再填写该来源需要的字段即可。

完整页面配置

下面的页面可以直接作为结构参考：场景中有两个目录模型，一个可点击模型会平滑移动镜头；所有场景字段都明确写出，便于从这里开始修改。

yaml

id: three_d_menu_demo
version: 1
title: 3D 菜单示例
size:
  width: 640
  height: 360
coordinateMode: absolute
display:
  mode: screen
elements:
  - id: stage
    type: scene
    z: 10                         # 整个 3D 视口相对于 2D 组件的层级
    visible: true
    enabled: true
    layout:
      x: 80
      y: 40
      width: 480
      height: 280
    scene:
      projection: perspective
      fov: 45
      orthographicHeight: 2       # 仅 projection=orthographic 时决定取景大小
      near: 0.01
      far: 100
      cameraX: 0
      cameraY: 1.2
      cameraZ: 8
      targetX: 0
      targetY: 1
      targetZ: 0
      upX: 0
      upY: 1
      upZ: 0
      lightingEnabled: true
      ambientLight: 0.55
      exposure: 1.25
      keyLightX: 0.2
      keyLightY: 1.0
      keyLightZ: -0.7
      fillLightX: -0.2
      fillLightY: 1.0
      fillLightZ: 0.7
      shadowEnabled: true
      shadowStrength: 0.55
      shadowSoftness: 1.5
      shadowBias: 0.0015
      shadowMapSize: 1024
      toneMappingEnabled: true
      toneMapping: aces
      brightness: 0.0
      contrast: 0.0
      saturation: 1.0
      vignetteEnabled: false
      vignetteAmount: 0.5
      vignetteHardness: 1.5
      chromaticAberrationEnabled: false
      chromaticAberration: 0.003
      sharpenEnabled: false
      sharpenStrength: 0.3
      colorBalanceEnabled: false
      colorBalanceShadowsR: 0.0
      colorBalanceShadowsG: 0.0
      colorBalanceShadowsB: 0.0
      colorBalanceMidtonesR: 0.0
      colorBalanceMidtonesG: 0.0
      colorBalanceMidtonesB: 0.0
      colorBalanceHighlightsR: 0.0
      colorBalanceHighlightsG: 0.0
      colorBalanceHighlightsB: 0.0
      cameraStates:
        menu_focus:               # 镜头状态 ID：可使用中英文、数字、_、-
          cameraX: 0
          cameraY: 1.2
          cameraZ: 8
          targetX: 0
          targetY: 1
          targetZ: 0
          upX: 0
          upY: 1
          upZ: 0
        detail_focus:
          cameraX: 1.4
          cameraY: 1.5
          cameraZ: 4.2
          targetX: 0
          targetY: 1
          targetZ: 0
          upX: 0
          upY: 1
          upZ: 0

  - id: guardian
    type: scene_model
    parent: stage
    visible: true
    enabled: true
    pointerEvents: auto
    layout:
      x: 0
      y: 0
      width: 1
      height: 1
    sceneModel:
      source: entity
      catalog: entity
      modelId: example:guardian
      x: -1.15
      y: 0
      z: 0
      rotationX: 0
      rotationY: 20
      rotationZ: 0
      scale: 0.95
      animation: idle
      animationLoop: true
      metalness: 0.15
      roughness: 0.65
      emissiveColor: "#FFFFFF"
      emissiveStrength: 0.0
    events:
      leftClick: |-
        component("stage").scene.moveTo("detail_focus", 600)

  - id: pedestal
    type: scene_model
    parent: stage
    visible: true
    enabled: false              # 仍会渲染，但不接收点击
    pointerEvents: pass
    layout:
      x: 0
      y: 0
      width: 1
      height: 1
    sceneModel:
      source: block
      catalog: block
      modelId: example:pedestal
      x: 0
      y: -1.1
      z: 0.35
      rotationX: 0
      rotationY: 0
      rotationZ: 0
      scale: 1
      animation: ""
      animationLoop: true

其中的 example:guardian 与 example:pedestal 只是占位 ID，必须替换成你的模型目录实际返回的 ID。若要使用直接资源模型，把其中任意一个 sceneModel 数据块替换为上一节的 custom 或 custom_entity 完整写法。

点击模型与脚本控制

模型无需手工配置碰撞盒。模型第一次成功渲染后，系统会依据它的实际几何生成整体范围；点击到这个范围时，普通组件事件会照常触发。为可点击模型保留 enabled: true 和 pointerEvents: auto，再在 events.leftClick、events.rightClick、events.middleClick 或悬浮事件中写 ChaUI Script。

第一版的“点击模型”是整体模型点击，不支持骨骼、part、单个三角形或像素级点击。想让模型不同部位分别触发功能时，应拆成多个 scene_model 节点，或者在场景前面放置对应的透明 2D 交互组件。

模型的变换也可以在脚本中修改。例如：

component("guardian").sceneModel.rotationY = 180
component("guardian").sceneModel.scale = 1.15

这类修改只作用于当前玩家当前次页面运行，不会自动改写服务器上的页面 YAML。需要长期保存的初始位置和动画，应在编辑器中调整后点击保存。

用脚本播放指定动画

如果模型已经成功加载，可以在任意组件事件中调用 sceneModel.playAnimation，让该模型从动画的 0 秒位置开始播放：

component("guardian").sceneModel.playAnimation("attack", false)

第一个参数是动画名称，第二个参数是是否循环；第二个参数可以省略，默认值为 true。动画名称必须是非空字符串，模型不支持该动画或 ChaEngine provider 不可用时，本次动作会记录脚本错误，但不会中断同一脚本后面的语句。该动作只改变当前页面会话的运行时模型，不会回写页面 YAML；如果希望固定初始动画，请直接在 sceneModel.animation 与 sceneModel.animationLoop 中配置并保存。

例如点击模型后切换到一次性的攻击动画，再移动镜头：

yaml

events:
  leftClick: |-
    component("guardian").sceneModel.playAnimation("attack", false)
    component("stage").scene.moveTo("detail_focus", 600)

也支持中文别名 组件("guardian").场景模型.播放动画("attack", false)。动画名需要以 provider 返回的实际动画名为准；编辑器动画面板可以用来查看可用名称。播放动作不提供逐帧时间、暂停或停止参数，需在编辑器或模型自身动画配置中完成这类预览控制。

镜头状态与平滑切换

cameraStates 为一个场景保存多个取景。每个状态必须完整写出以下九个数：

yaml

cameraStates:
  menu_focus:
    cameraX: 0
    cameraY: 1.2
    cameraZ: 8
    targetX: 0
    targetY: 1
    targetZ: 0
    upX: 0
    upY: 1
    upZ: 0

在编辑器里先用临时相机找到构图，再点击“打开镜头记录”，输入状态 ID 并记录，就不需要手抄这些数值。对话框里的“加载”只更新当前临时镜头，“删除”支持撤销/重做；“还原镜头”恢复场景默认相机但不会删除记录。状态只保存这九项，不保存投影、FOV、正交高度、裁剪距离和光照，主光、补光与 lightingEnabled 始终独立配置。

在事件脚本中调用下面的方法即可从当前实际镜头平滑移动到目标状态：

component("stage").scene.moveTo("menu_focus", 800)

第二个参数单位是毫秒：0 立即切换，非零值可为 1 到 3600000。移动使用首尾速度和加速度都归零的五次 smoothstep 缓入缓出曲线；客户端在每个渲染帧重新采样，因此不会被 20Hz 游戏 tick 限制。重复调用会从镜头已经移动到的位置继续；如果随后直接修改任一 cameraX/Y/Z、targetX/Y/Z 或 upX/Y/Z，当前移动会停止并采用新值。镜头记录对话框的“复制”按钮会按场景组件 ID、状态 ID 和持续时间自动生成这行调用并复制到剪贴板，默认持续时间是 800 毫秒。镜头移动也是当前页面会话的临时状态，关闭页面、reload 或删除场景后会自动清理。

编辑器中能做什么

3D 场景编辑器可用于：

从 entity、block、item 目录搜索和下拉选择模型，并用刷新按钮重新读取目录；
直接填写 custom、custom_entity 的模型、动画、材质和实体类型；
用 Q / V / R / E 切换选择、移动、旋转、缩放工具；
中键环绕、Shift + 中键 平移、滚轮缩放临时编辑相机；
选择模型已有动画、播放或暂停、循环预览和拖动时间；
在“镜头记录”二级对话框中记录、加载、删除状态，并用“复制”按钮生成 scene.moveTo 脚本；记录和删除可通过撤销、重做恢复。

鼠标手势、播放状态、预览循环和预览时间都只是编辑会话中的临时状态。只有明确修改属性或记录镜头状态，再点击保存后，内容才会进入页面 YAML。

常见问题

模型显示不出来

先确认模型资源已经在客户端可用。目录模型要检查 source、catalog、modelId 是否完全匹配目录；直接资源模型要检查 model 和 texture 是否存在且使用相对路径。模型能力缺失或版本不匹配时会安全降级，不会让整个页面无法打开。

点击不到模型

模型只有首次成功渲染并生成整体范围后才可点击。还要确认它没有被 visible: false、enabled: false 或 pointerEvents: pass 关闭交互。若模型前方有同层或更高层的 2D 组件，点击会优先交给前方组件。

正交模式下模型异常放大

正交模式用 orthographicHeight 控制取景范围，不使用 fov。把 orthographicHeight 调大后，画面会缩小并显示更多范围；然后再用镜头状态记录满意的构图。

保存时提示字段未知或模型来源不匹配

scene 和 sceneModel 只接受文档列出的字段。目录模型必须让 source 与 catalog 同为 entity、block 或 item；直接资源模型则填写 custom / custom_entity 所需的路径字段，不要混用两种引用方式。

想点击模型的某个部位

当前不支持 part、骨骼或三角形精确点击。把可交互部分拆成独立模型节点，是最直接且可控的做法。

3D 场景与模型 ​

先理解层级 ​

场景组件：scene ​

透视还是正交 ​

光照示例 ​

后处理示例 ​

模型组件：scene_model ​

通用变换与动画 ​

四种模型来源 ​

目录模型示例 ​

custom 直接资源模型示例 ​

custom_entity 自定义生物模型示例 ​

完整页面配置 ​

点击模型与脚本控制 ​

用脚本播放指定动画 ​

镜头状态与平滑切换 ​

编辑器中能做什么 ​

常见问题 ​

模型显示不出来 ​

点击不到模型 ​

正交模式下模型异常放大 ​

保存时提示字段未知或模型来源不匹配 ​

想点击模型的某个部位 ​

3D 场景与模型

先理解层级

场景组件：`scene`

透视还是正交

光照示例

后处理示例

模型组件：`scene_model`

通用变换与动画

四种模型来源

目录模型示例

`custom` 直接资源模型示例

`custom_entity` 自定义生物模型示例

完整页面配置

点击模型与脚本控制

用脚本播放指定动画

镜头状态与平滑切换

编辑器中能做什么

常见问题

模型显示不出来

点击不到模型

正交模式下模型异常放大

保存时提示字段未知或模型来源不匹配

想点击模型的某个部位