【Laya】Scene3D 介绍

Laya.Scene3D

概述

Laya.Scene3D 是 LayaAir 3D 引擎中的场景类，继承自 Sprite，是 3D 场景的根节点容器。所有 3D 对象（相机、灯光、模型等）都需要添加到 Scene3D 中才能被渲染和管理。

继承关系

EventDispatcher → Node → Sprite → Scene3D

命名空间约定

必须使用 Laya. 前缀访问所有引擎类。

// ✅ 正确
const scene = new Laya.Scene3D();
Laya.stage.addChild(scene);

// ❌ 错误
const scene = new Scene3D();

构造函数

constructor()

创建一个 Scene3D 实例。

const scene = new Laya.Scene3D();
Laya.stage.addChild(scene);

// 注意：新创建的 Scene3D 必须添加摄像机才能看到内容
const camera = new Laya.Camera(0, 0.1, 100);
scene.addChild(camera);

静态属性

physicsSettings

static physicsSettings: PhysicsSettings

物理引擎设置。

场景 Uniform 属性 ID

以下属性用于着色器变量绑定（内部使用）：

属性	类型	描述
FOGCOLOR	number	雾颜色
FOGPARAMS	number	雾参数
AMBIENTCOLOR	number	环境光颜色
TIME	number	场景时间

静态方法

load()

已弃用 ：加载场景请先预加载后使用 Laya.Loader.createNodes(url)

加载场景文件（不缓存）。

static load(url: string, complete: Handler): void

regManager()

注册场景组件管理器。

static regManager(type: string, cla: new () => IElementComponentManager): void

实例属性

环境光

ambientColor

get ambientColor(): Color
set ambientColor(value: Color)

固定颜色环境光。

scene.ambientColor = new Laya.Color(0.5, 0.5, 0.5, 1.0);

ambientMode

get ambientMode(): AmbientMode
set ambientMode(value: AmbientMode)

环境光模式。

• AmbientMode.SolidColor - 固定颜色模式
• AmbientMode.SphericalHarmonics - 球谐函数模式

ambientIntensity

get ambientIntensity(): number
set ambientIntensity(value: number)

环境光强度。

scene.ambientIntensity = 0.8;

雾效

enableFog

get enableFog(): boolean
set enableFog(value: boolean)

是否启用雾化效果。

scene.enableFog = true;

fogMode

get fogMode(): FogMode
set fogMode(value: FogMode)

雾化模式。

• FogMode.Linear - 线性雾
• FogMode.Exp - 指数雾
• FogMode.Exp2 - 平方指数雾

fogColor

get fogColor(): Color
set fogColor(value: Color)

雾化颜色。

scene.fogColor = new Laya.Color(0.8, 0.9, 1.0, 1.0);

fogStart / fogEnd / fogRange / fogDensity

get fogStart(): number
set fogStart(value: number)

get fogEnd(): number
set fogEnd(value: number)

get fogRange(): number
set fogRange(value: number)

get fogDensity(): number
set fogDensity(value: number)

雾化参数。

// 线性雾
scene.fogMode = Laya.FogMode.Linear;
scene.fogStart = 10;
scene.fogEnd = 100;

// 指数雾
scene.fogMode = Laya.FogMode.Exp;
scene.fogDensity = 0.02;

渲染相关

skyRenderer

get skyRenderer(): SkyRenderer

天空渲染器，用于设置天空盒或天空穹顶。

scene.skyRenderer.mesh = Laya.SkyDome.instance;
// 需要提前创建或加载天空材质

physicsSimulation

get physicsSimulation(): IPhysicsManager

物理模拟器。

timer

get timer(): Timer
set timer(value: Timer)

场景时钟。

光照贴图

lightmaps

get lightmaps(): Lightmap[]
set lightmaps(value: Lightmap[])

光照贴图数组。

scene.lightmaps = [lightmap1, lightmap2];

反射

reflectionIntensity

get reflectionIntensity(): number
set reflectionIntensity(value: number)

反射探针强度。

场景关联

scene2D

get scene2D(): Scene

Scene3D 所属的 2D 场景（使用 IDE 编辑的场景载入后具有此属性）。

实例方法

destroy()

销毁场景及其资源。

destroy(destroyChild: boolean = true): void

参数	类型	默认值	描述
destroyChild	boolean	true	是否销毁子节点

scene.destroy();

setGlobalShaderValue()

设置全局渲染数据。

setGlobalShaderValue(name: string, type: ShaderDataType, value: ShaderDataItem): void

getlightmaps() / setlightmaps()

获取/设置光照贴图。

getlightmaps(): Texture2D[]
setlightmaps(value: Texture2D[]): void

使用示例

创建基础 3D 场景

export async function main() {
    await Laya.init(0, 0);

    // 创建 3D 场景
    const scene = new Laya.Scene3D();
    Laya.stage.addChild(scene);

    // 必须添加摄像机才能看到内容
    const camera = new Laya.Camera(0, 0.1, 100);
    camera.transform.position = new Laya.Vector3(0, 3, 10);
    camera.transform.lookAt(new Laya.Vector3(0, 0, 0), new Laya.Vector3(0, 1, 0));
    scene.addChild(camera);

    // 设置环境光
    scene.ambientColor = new Laya.Color(0.5, 0.5, 0.5, 1.0);
    scene.ambientIntensity = 0.8;
}

添加相机和灯光

export async function main() {
    await Laya.init(0, 0);

    const scene = new Laya.Scene3D();
    Laya.stage.addChild(scene);

    // 添加相机
    const camera = new Laya.Camera(0, 0.1, 100);
    camera.transform.position = new Laya.Vector3(0, 5, 10);
    camera.transform.lookAt(new Laya.Vector3(0, 0, 0), new Laya.Vector3(0, 1, 0));
    scene.addChild(camera);

    // 添加方向光
    const light = new Laya.Sprite3D();
    const lightCom = light.addComponent(Laya.DirectionLightCom);
    lightCom.color = new Laya.Color(1, 1, 1, 1);
    light.transform.rotate(new Laya.Vector3(-45, 0, 0), false, false);
    scene.addChild(light);
}

设置雾效

export async function main() {
    await Laya.init(0, 0);

    const scene = new Laya.Scene3D();
    Laya.stage.addChild(scene);

    // 启用雾效
    scene.enableFog = true;

    // 设置线性雾
    scene.fogMode = Laya.FogMode.Linear;
    scene.fogColor = new Laya.Color(0.8, 0.9, 1.0, 1.0);
    scene.fogStart = 10;
    scene.fogEnd = 50;
}

设置天空盒

export async function main() {
    await Laya.init(0, 0);

    const scene = new Laya.Scene3D();
    Laya.stage.addChild(scene);

    // 设置天空盒
    scene.skyRenderer.mesh = Laya.SkyBox.instance;
    scene.skyRenderer.material = skyMaterial;
}

注意：skyMaterial 需要提前创建或加载天空盒材质。

获取现有 Scene3D

// 方法1: 通过名称获取
const scene = Laya.stage.getChildByName("Scene3D") as Laya.Scene3D;

// 方法2: 从 owner 获取（在 Script 组件中，owner 就是 Scene3D）
const scene = this.owner as unknown as Laya.Scene3D;

场景文件格式

.ls 格式（场景文件）

.ls 是 LayaAir 的场景文件格式，包含场景的完整信息。

// 先预加载，再创建场景
await Laya.loader.load("path/to/scene.ls", Laya.Loader.HIERARCHY);
const scene = Laya.Loader.createNodes("path/to/scene.ls") as Laya.Scene3D;
Laya.stage.addChild(scene);

.lh 格式（预制体）

.lh 是预制体文件格式，也可以作为场景加载。

// 先预加载，再创建场景
await Laya.loader.load("path/to/prefab.lh", Laya.Loader.HIERARCHY);
const scene = Laya.Loader.createNodes("path/to/prefab.lh") as Laya.Scene3D;
Laya.stage.addChild(scene);

常见问题

Q: 新建 Scene3D 后看不到任何内容？

A: 新创建的 Scene3D 必须添加摄像机才能渲染显示：

const scene = new Laya.Scene3D();
Laya.stage.addChild(scene);

// 必须添加摄像机
const camera = new Laya.Camera(0, 0.1, 100);
scene.addChild(camera);

Q: Scene3D 与 Scene 的区别？

A:

• Scene3D 是 3D 场景类，继承自 Sprite，用于 3D 渲染
• Scene 是 2D 场景类，用于 2D 界面和游戏逻辑
• 在 3D 项目中，使用 Scene3D 作为场景根节点

Q: 如何获取当前活动的 Scene3D？

A: 根据你的场景结构选择：

// 如果 Scene3D 直接在 stage 下
const scene = Laya.stage.getChildByName("Scene3D") as Laya.Scene3D;

// 如果在 Script 组件中且 owner 就是 Scene3D
const scene = this.owner as unknown as Laya.Scene3D;

// 遍历查找
let scene: Laya.Scene3D | null = null;
for (let i = 0; i < Laya.stage.numChildren; i++) {
    const child = Laya.stage.getChildAt(i);
    if (child instanceof Laya.Scene3D) {
        scene = child;
        break;
    }
}

Q: 如何设置场景背景颜色？

A: 通过相机的 clearColor 设置：

const camera = scene.getChildByName("Main Camera") as Laya.Camera;
camera.clearColor = new Laya.Color(0.2, 0.2, 0.2, 1.0);

Q: 静态属性 vs 实例属性？

A: 静态属性（如 physicsSettings）是全局的，影响所有场景。实例属性（如 ambientColor）只影响当前场景实例。

---

版本 : v3.3.7
文档生成时间: 2026-01-19