Laya.Sprite3D

概述

Laya.Sprite3D 是 LayaAir 3D 引擎中的基础显示对象类，所有 3D 场景中的对象都继承自此类。它继承自 Node，是 3D 场景树的节点，可以包含子节点并管理 3D 变换。

继承关系

EventDispatcher → Node → Sprite3D
                              ↓
        ┌─────────────────────┼─────────────────────┐
        ↓                     ↓                     ↓
   BaseCamera        RenderableSprite3D      LightSprite

命名空间约定

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

// ✅ 正确
const sprite = new Laya.Sprite3D();
Laya.Sprite3D.instantiate(sprite);

// ❌ 错误
const sprite = new Sprite3D();

构造函数

constructor(name?: string, isStatic?: boolean)

参数	类型	默认值	描述
name	string	undefined	精灵名称
isStatic	boolean	undefined	是否为静态对象

// 创建命名精灵
const sprite = new Laya.Sprite3D("MySprite");

// 创建静态精灵（用于静态批处理优化）
const staticSprite = new Laya.Sprite3D("Ground", true);

静态属性

WORLDMATRIX

static readonly WORLDMATRIX: number

着色器变量名，用于世界矩阵。

WORLDINVERTFRONT

static readonly WORLDINVERTFRONT: number

正面朝向标识。-1 表示翻转背面，1 表示正常情况。

静态方法

instantiate()

创建精灵的克隆实例。

static instantiate(
    original: Sprite3D,
    parent?: Node,
    worldPositionStays?: boolean,
    position?: Vector3,
    rotation?: Quaternion
): Sprite3D

参数	类型	默认值	描述
original	Sprite3D	-	原始精灵
parent	Node	null	父节点
worldPositionStays	boolean	true	是否保持自身世界变换
position	Vector3	null	世界位置（worldPositionStays 为 false 时生效）
rotation	Quaternion	null	世界旋转（worldPositionStays 为 false 时生效）

const original = new Laya.Sprite3D("Original");
scene.addChild(original);

// 克隆并保持世界变换
const clone1 = Laya.Sprite3D.instantiate(original, scene, true);

// 克隆并指定新位置
const clone2 = Laya.Sprite3D.instantiate(
    original,
    scene,
    false,
    new Laya.Vector3(10, 0, 0),
    new Laya.Quaternion()
);

load()

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

加载网格模板（已弃用）。

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

实例属性

id

get id(): number

唯一标识 ID（只读）。

layer

get layer(): number
set layer(value: number)

蒙版层，用于摄像机渲染过滤。

sprite.layer = 1;

isStatic

get isStatic(): boolean
set isStatic(value: boolean)  // IDE only

是否为静态对象。静态对象可参与静态批处理优化。

transform

get transform(): Transform3D

精灵变换组件，用于控制位置、旋转和缩放。

sprite.transform.position = new Laya.Vector3(0, 1, 0);
sprite.transform.rotation = new Laya.Quaternion();
sprite.transform.setWorldLossyScale(new Laya.Vector3(1, 1, 1));

scene

get scene(): Scene3D

获取精灵所属的场景（只读）。

实例方法

clone()

克隆当前精灵。

clone(): Sprite3D

const original = new Laya.Sprite3D("Original");
const clone = original.clone();
clone.name = "Clone";
scene.addChild(clone);

destroy()

销毁精灵。

destroy(destroyChild?: boolean): void

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

// 销毁精灵及其所有子节点
sprite.destroy();

// 销毁精灵但保留子节点
sprite.destroy(false);

使用示例

创建基础 Sprite3D

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, 3, 10);
    scene.addChild(camera);

    // 创建基础 Sprite3D
    const sprite = new Laya.Sprite3D("MySprite");
    scene.addChild(sprite);

    // 设置位置
    sprite.transform.position = new Laya.Vector3(0, 0, 5);
}

加载 3D 预制体

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, 3, 10);
    scene.addChild(camera);

    // 先预加载，再创建预制体
    await Laya.loader.load("path/to/model.lh", Laya.Loader.HIERARCHY);
    const sprite = Laya.Loader.createNodes("path/to/model.lh") as Laya.Sprite3D;
    scene.addChild(sprite);
}

使用 Transform3D 进行变换

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, 3, 10);
    scene.addChild(camera);

    const sprite = new Laya.Sprite3D("TransformSprite");
    scene.addChild(sprite);

    // 位置变换
    sprite.transform.position = new Laya.Vector3(10, 5, 0);

    // 旋转变换（使用欧拉角）
    sprite.transform.rotationEuler = new Laya.Vector3(45, 0, 0);

    // 缩放变换
    sprite.transform.setWorldLossyScale(new Laya.Vector3(2, 2, 2));

    // 平移变换
    sprite.transform.translate(new Laya.Vector3(1, 0, 0), false);

    // 旋转变换
    sprite.transform.rotate(new Laya.Vector3(0, 1, 0), true, false);
}

克隆实例

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, 3, 10);
    scene.addChild(camera);

    // 创建原始对象
    const original = new Laya.Sprite3D("Original");
    scene.addChild(original);

    // 方法1: 使用 instantiate 静态方法
    const clone1 = Laya.Sprite3D.instantiate(original, scene);

    // 方法2: 使用 clone 实例方法
    const clone2 = original.clone();
    scene.addChild(clone2);
}

节点层级管理

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, 3, 10);
    scene.addChild(camera);

    // 创建父节点
    const parent = new Laya.Sprite3D("Parent");
    scene.addChild(parent);

    // 创建子节点
    const child1 = new Laya.Sprite3D("Child1");
    const child2 = new Laya.Sprite3D("Child2");
    parent.addChild(child1);
    parent.addChild(child2);

    // 获取子节点数量
    console.log(parent.numChildren); // 2

    // 获取子节点
    const firstChild = parent.getChildAt(0) as Laya.Sprite3D;
    console.log(firstChild.name); // Child1

    // 查找子节点
    const found = parent.getChildByName("Child2") as Laya.Sprite3D;
    console.log(found ? "找到 Child2" : "未找到");

    // 移除子节点
    parent.removeChild(child1);

    // 移除自身
    child2.removeSelf();
}

子类说明

RenderableSprite3D

可渲染的 3D 精灵基类，包含 MeshRenderer 等渲染组件。

注意: MeshSprite3D 和 SkinnedMeshSprite3D 已弃用，请使用 Sprite3D + MeshFilter + MeshRenderer 组件方式创建网格对象。

使用组件创建网格对象

推荐使用 Sprite3D 配合 MeshFilter 和 MeshRenderer 组件来创建可渲染的 3D 对象：

// 创建球体网格
const sphere = new Laya.Sprite3D();
const meshFilter = sphere.addComponent(Laya.MeshFilter);
meshFilter.sharedMesh = Laya.PrimitiveMesh.createSphere(1);
const meshRenderer = sphere.addComponent(Laya.MeshRenderer);
scene.addChild(sphere);

// 创建材质
const material = new Laya.BlinnPhongMaterial();
meshRenderer.material = material;
material.albedoColor = new Laya.Color(1, 0, 0, 1);

BaseCamera

摄像机基类。

• Camera - 主摄像机

LightSprite

灯光精灵基类。

• DirectionLight - 平行光
• PointLight - 点光源
• SpotLight - 聚光灯

常见问题

Q: 新建 Scene3D 后看不到 Sprite3D？

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

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

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

Q: Sprite3D 与 Node 的区别？

A: Sprite3D 继承自 Node，增加了 3D 特定的功能：

• Transform3D 变换组件
• 3D 场景管理
• 静态批处理支持
• Layer 蒙版层功能

Q: 如何创建可渲染的 3D 网格对象？

A: MeshSprite3D 已弃用，请使用组件方式：

// ✅ 正确方式（v3.3.7+）
const sphere = new Laya.Sprite3D();
const meshFilter = sphere.addComponent(Laya.MeshFilter);
meshFilter.sharedMesh = Laya.PrimitiveMesh.createSphere(1);
const meshRenderer = sphere.addComponent(Laya.MeshRenderer);
scene.addChild(sphere);

// ❌ 旧方式（已弃用）
// const sphere = new Laya.MeshSprite3D(Laya.PrimitiveMesh.createSphere(1));

Q: 如何判断两个精灵是否在同一层？

A: 使用 layer 属性进行比较：

if (sprite1.layer === sprite2.layer) {
    console.log("在同一层");
}

Q: 静态精灵(isStatic)有什么优势？

A: 静态精灵可以参与静态批处理，减少 DrawCall，提高渲染性能。适合场景中不会移动、旋转、缩放的对象。

---

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