Manual: 3DBackground

[Moonling]

Overview

BackgroundLayer3D is a node that allows you to load and use 3D models as background elements.

The game screen where Visual Scripts run remains fundamentally 2D, and 3D content functions only as a background. However, it can operate as a parallax background synchronized with 2D gameplay elements, such as following the movement of the 2D camera.

When a BackgroundLayer3D node is added, related nodes required for displaying and controlling the 3D background are automatically added as child nodes. These include a SubViewport for rendering the 3D scene and a BackgroundCamera3D for controlling the camera within the 3D space.

Technical Overview

BackgroundLayer3D is a custom node based on CanvasLayer. It provides the same functionality as CanvasLayer, while adding properties for enabling/disabling 3D functionality and loading/placing 3D models.

BackgroundCamera3D is a custom node based on Camera3D. In addition to the standard Camera3D features, it can automatically reference the active camera in the GameScene and follow its movement.

Using a 3D Background

1. In the GameScene, add a BackgroundLayer3D node using Add Node.

2. Select BackgroundLayer3D, then enable Enable 3D View in the Inspector.
   (At this point, a 3D View tab will be added to the top editor tabs.)

3. In the BackgroundLayer3D Inspector, use Load 3D Map to import a 3D model.
   (Any 3D model in .glb or .gltf format can be loaded.)

4. Once the model has been loaded successfully, select BackgroundCamera3D and adjust the camera position using the viewport handles. You can check the camera’s view in the Inspector.

5. Select DirectionalLight3D (sunlight) and adjust its direction using the viewport handles.

6. Setup is now complete. If you no longer need to edit the 3D scene, select BackgroundLayer3D and disable Enable 3D View in the Inspector.