手册：3D背景功能（BackgroundLayer3D）

[Moonling]

概述

BackgroundLayer3D 是一个用于加载并使用 3D 模型作为背景的节点。

需要注意的是，运行可视化脚本（Visual Script）的游戏画面本质上仍然是 2D 的，而 3D 内容仅作为背景显示。不过，它能够与 2D 相机联动，例如根据 2D 相机的移动自动产生视差效果，从而实现与 2D 游戏内容同步的动态背景表现。

添加 BackgroundLayer3D 后，系统会自动创建用于显示和控制 3D 背景的相关子节点，包括用于渲染 3D 场景的 SubViewport，以及用于控制 3D 空间内部相机的 BackgroundCamera3D 等节点。

技术概述

BackgroundLayer3D 是基于 CanvasLayer 的自定义节点。

其基本功能与 CanvasLayer 相同，但额外提供了用于启用/禁用 3D 功能的属性，以及用于加载和放置 3D 模型的属性。

BackgroundCamera3D 是基于 Camera3D 的自定义节点。

除了 Camera3D 原有的功能外，它还能够自动获取 GameScene 中当前激活的相机，并根据其运动自动进行跟随。

使用 3D 背景

1. 在 GameScene 中，通过 添加节点（Add Node） 添加 BackgroundLayer3D。

2. 选中 BackgroundLayer3D，然后在检查器（Inspector）中启用 启用 3D 视图（Enable 3D View）。
   （此时，编辑器顶部会新增一个 3D View 标签页。）

3. 在 BackgroundLayer3D 的检查器中，使用 加载 3D 地图（Load 3D Map） 功能导入 3D 模型。
   （支持加载任意 .glb 或 .gltf 格式的 3D 模型。）

4. 模型成功加载后，选中 BackgroundCamera3D，通过视口中的控制手柄调整相机位置。
   可以在检查器中查看相机当前的显示效果。

5. 选中 DirectionalLight3D（平行光/太阳光），通过控制手柄调整光照方向。

6. 至此设置完成。
   如果之后不再需要编辑 3D 场景，建议重新选中 BackgroundLayer3D，并在检查器中关闭 启用 3D 视图（Enable 3D View）。