Laya 类说明文档

目录

1. 概述
2. 核心属性
3. 静态方法
4. 配置参数
5. 初始化流程
6. 使用示例
7. 最佳实践
8. 常见问题

---

概述

Laya 是 LayaAir 引擎的全局对象引用入口集，提供了对核心全局对象的访问，包括舞台、时间管理器、资源加载器等。所有成员都是静态的。

核心特点

• 全局单例入口：统一的访问入口，避免散乱的全局变量
• 静态成员：所有属性和方法都是静态的
• 大小写敏感：访问时必须注意大小写，如 Laya.stage、Laya.timer
• 必需初始化：使用引擎前必须先调用 Laya.init() 方法。使用IDE的项目，其设置默认生效。

基本用法

// 引擎初始化
Laya.init(1136, 640).then(() => {
    // 访问舞台
    Laya.stage.addChild(sprite);

    // 访问时间管理器
    Laya.timer.loop(1000, this, this.onUpdate);

    // 访问资源加载器
    Laya.loader.load("res/image.png");
});

---

核心属性

全局对象引用

属性	类型	只读	说明
Laya.stage	Laya.Stage	✅	舞台对象引用，所有显示对象的根容器
Laya.timer	Laya.Timer	✅	游戏主时钟，支持时间缩放，用于动画、缓动等
Laya.systemTimer	Laya.Timer	✅	系统时钟，引擎内部使用，不受时间缩放影响
Laya.physicsTimer	Laya.Timer	✅	物理时钟，用于物理引擎模拟
Laya.loader	Laya.Loader	✅	资源加载管理器
Laya.physics2D	Laya.IPhysics2DFactory	❌	2D 物理引擎工厂

三种 Timer 对比

Timer	用途	scale 影响	典型场景
Laya.timer	游戏主时钟	✅ 受影响	游戏逻辑、动画、UI、缓动效果
Laya.systemTimer	系统时钟	❌ 不受影响	倒计时、网络请求超时、引擎内部
Laya.physicsTimer	物理时钟	❌ 不受影响	物理引擎模拟

示例:

// 游戏逻辑 - 可通过 scale 实现快进/慢放
Laya.timer.scale = 0.5;  // 慢放：50%速度
Laya.timer.loop(1000, this, this.onGameUpdate);

// 倒计时 - 不受游戏时间缩放影响
Laya.systemTimer.loop(1000, this, this.onCountDown);

// 物理模拟 - 保持稳定，不受游戏变速影响
// 物理引擎内部自动使用 physicsTimer，通常无需手动调用

---

静态方法

引擎初始化

init()

初始化引擎，使用引擎前必须先调用。

// 方式1: 使用宽高参数
static init(width: number, height: number): Promise<void>

// 方式2: 使用配置对象（推荐）
static init(stageConfig?: IStageConfig): Promise<void>

参数	类型	说明
width	number	舞台宽度
height	number	舞台高度
stageConfig	IStageConfig	舞台配置对象

返回: Promise<void> - 初始化完成后 resolve

示例:

// 方式1: 简单初始化
Laya.init(1136, 640).then(() => {
    console.log("引擎初始化完成");
});

// 方式2: 使用配置对象
Laya.init({
    designWidth: 1136,
    designHeight: 640,
    scaleMode: Laya.Stage.SCALE_FIXED_AUTO,
    alignV: Laya.Stage.ALIGN_MIDDLE,
    alignH: Laya.Stage.ALIGN_CENTER,
    backgroundColor: "#232628"
}).then(() => {
    console.log("引擎初始化完成");
});

---

初始化回调

addBeforeInitCallback()

在引擎初始化前执行自定义逻辑。此时 Stage 尚未创建，可以修改 stageConfig 实现动态舞台配置。

static addBeforeInitCallback(
    callback: (stageConfig: IStageConfig) => void | Promise<void>
): void

使用场景:

• 环境检测（移动端/PC端）
• 动态调整舞台配置
• 平台适配配置

示例:

Laya.addBeforeInitCallback((stageConfig) => {
    console.log("初始化前回调");

    // 检测平台
    if (Laya.Browser.onMobile) {
        // 移动端使用全屏适配
        stageConfig.designWidth = 0;
        stageConfig.designHeight = 0;
        stageConfig.scaleMode = Laya.Stage.SCALE_FIXED_AUTO;
    } else {
        // PC 端使用固定尺寸
        stageConfig.designWidth = 1920;
        stageConfig.designHeight = 1080;
        stageConfig.scaleMode = Laya.Stage.SCALE_SHOWALL;
    }
});

Laya.init({
    designWidth: 1136,
    designHeight: 640
});

---

addAfterInitCallback()

在引擎初始化后执行自定义逻辑。此时 Stage 已创建完成，引擎已就绪。

static addAfterInitCallback(
    callback: () => void | Promise<void>
): void

使用场景:

• 引擎初始化后的配置
• 资源预加载
• 系统初始化

示例:

Laya.addAfterInitCallback(() => {
    console.log("初始化后回调");

    // 设置舞台属性
    Laya.stage.bgColor = "#232628";
    Laya.stage.frameRate = Laya.Stage.FRAME_FAST;

    // 显示性能统计（调试用）
    if (DEBUG) {
        Laya.Stat.show();
    }
});

Laya.init(1136, 640);

---

addInitCallback()

引擎各个模块（如物理、寻路等）的初始化回调。开发者一般不直接使用，主要用于扩展引擎功能。

static addInitCallback(
    callback: () => void | Promise<void>
): void

示例:

// 自定义模块初始化
Laya.addInitCallback(() => {
    return new Promise<void>((resolve) => {
        console.log("初始化自定义模块");
        // 模块初始化逻辑
        resolve();
    });
});

---

错误处理

alertGlobalError()

设置是否捕获全局错误并弹窗显示。

static alertGlobalError(value: boolean): void

参数	类型	说明
value	boolean	true = 捕获并弹窗，false = 不捕获

使用场景:

• 移动设备等不方便调试的环境
• 需要实时发现错误的场景
• 生产环境错误监控

示例:

// 启用全局错误捕获
Laya.alertGlobalError(true);

Laya.init(1136, 640).then(() => {
    console.log("引擎初始化完成");
});

// 当发生未捕获的错误时，会自动弹窗显示错误堆栈

---

_onGlobalError()

全局错误回调函数，当引擎发生错误且 alertGlobalError 设置为 true 时被调用。

static _onGlobalError(ev: ErrorEvent | PromiseRejectionEvent): void

参数	类型	说明
ev	ErrorEvent | PromiseRejectionEvent	错误事件对象

---

其他方法

importNative()

导入原生库（dll/so/dylib）。如果在非 Conch 环境中，此函数返回 null。

static importNative(name: string): any

参数	类型	说明
name	string	库名称

返回: any - 导入的原生库对象，或 null

使用场景:

• LayaNative 原生扩展
• 调用平台原生功能

---

配置参数

IStageConfig 接口

interface IStageConfig {
    // 设计尺寸（必需）
    designWidth: number;      // 设计宽度，0 表示全屏
    designHeight: number;     // 设计高度，0 表示全屏

    // 缩放模式
    scaleMode: string;        // 详见 Stage.scaleMode

    // 屏幕模式
    screenMode: string;       // SCREEN_NONE / SCREEN_HORIZONTAL / SCREEN_VERTICAL

    // 对齐方式
    alignV: string;           // ALIGN_TOP / ALIGN_MIDDLE / ALIGN_BOTTOM
    alignH: string;           // ALIGN_LEFT / ALIGN_CENTER / ALIGN_RIGHT

    // 背景颜色
    backgroundColor: string;  // 支持 "#RRGGBB" 或 "#AARRGGBB" 格式
}

常用配置组合

// 场景1: 移动端游戏 - 全屏自动适配
Laya.init({
    designWidth: 0,
    designHeight: 0,
    scaleMode: Laya.Stage.SCALE_FIXED_AUTO,
    screenMode: Laya.Stage.SCREEN_NONE,
    alignV: Laya.Stage.ALIGN_MIDDLE,
    alignH: Laya.Stage.ALIGN_CENTER,
    backgroundColor: "#232628"
});

// 场景2: 横版动作游戏 - 固定高度
Laya.init({
    designWidth: 1136,
    designHeight: 640,
    scaleMode: Laya.Stage.SCALE_FIXED_HEIGHT,
    screenMode: Laya.Stage.SCREEN_HORIZONTAL,
    alignV: Laya.Stage.ALIGN_MIDDLE,
    alignH: Laya.Stage.ALIGN_CENTER,
    backgroundColor: "#000000"
});

// 场景3: 3D 游戏 - 全屏
Laya.init({
    designWidth: 0,
    designHeight: 0,
    scaleMode: Laya.Stage.SCALE_FULL,
    screenMode: Laya.Stage.SCREEN_NONE,
    backgroundColor: "#000000"
});

// 场景4: PC Web 应用 - 保持设计尺寸
Laya.init({
    designWidth: 1920,
    designHeight: 1080,
    scaleMode: Laya.Stage.SCALE_SHOWALL,
    screenMode: Laya.Stage.SCREEN_NONE,
    alignV: Laya.Stage.ALIGN_TOP,
    alignH: Laya.Stage.ALIGN_CENTER,
    backgroundColor: "#F5F5F5"
});

---

初始化流程

完整执行顺序

// 执行顺序：
// 1. addBeforeInitCallback 注册的回调（按注册顺序）
// 2. Laya.init() 执行引擎初始化
// 3. addInitCallback 注册的回调（并行执行）
// 4. addAfterInitCallback 注册的回调（按注册顺序）
// 5. init() 返回的 Promise resolve

Laya.addBeforeInitCallback(() => console.log("1. 初始化前回调1"));
Laya.addBeforeInitCallback(() => console.log("2. 初始化前回调2"));
Laya.addInitCallback(() => console.log("3. 模块初始化回调"));
Laya.addAfterInitCallback(() => console.log("4. 初始化后回调1"));
Laya.addAfterInitCallback(() => console.log("5. 初始化后回调2"));

Laya.init(1136, 640).then(() => {
    console.log("6. init() Promise 完成");
});

// 输出:
// 1. 初始化前回调1
// 2. 初始化前回调2
// 3. 模块初始化回调
// 6. init() Promise 完成
// 4. 初始化后回调1
// 5. 初始化后回调2

推荐的初始化模式

export class GameMain {
    constructor() {
        this.init();
    }

    private init(): void {
        // 阶段1: 初始化前 - 环境检测和配置
        Laya.addBeforeInitCallback((config) => {
            this.beforeInit(config);
        });

        // 阶段2: 初始化后 - 引擎配置
        Laya.addAfterInitCallback(() => {
            this.afterInit();
        });

        // 阶段3: 自定义模块初始化
        Laya.addInitCallback(() => {
            return this.initPhysics();
        });

        Laya.addInitCallback(() => {
            return this.initAudio();
        });

        // 开始初始化
        Laya.init({
            designWidth: 1136,
            designHeight: 640,
            scaleMode: Laya.Stage.SCALE_FIXED_AUTO,
            backgroundColor: "#232628"
        });
    }

    private beforeInit(config: Laya.IStageConfig): void {
        console.log("环境检测");

        // 平台适配
        if (Laya.Browser.onMobile) {
            config.designWidth = 0;
            config.designHeight = 0;
        }

        // 错误处理
        Laya.alertGlobalError(true);
    }

    private afterInit(): void {
        console.log("引擎配置");

        // 设置舞台属性
        Laya.stage.alignV = Laya.Stage.ALIGN_MIDDLE;
        Laya.stage.alignH = Laya.Stage.ALIGN_CENTER;

        // 性能统计（调试）
        if (DEBUG) {
            Laya.Stat.show();
        }

        // 开始游戏
        this.startGame();
    }

    private async initPhysics(): Promise<void> {
        console.log("初始化物理引擎");
    }

    private async initAudio(): Promise<void> {
        console.log("初始化音频系统");
    }

    private startGame(): void {
        console.log("游戏开始");
    }
}

---

使用示例

示例1: 基础初始化

export class BasicExample {
    constructor() {
        Laya.init(1136, 640).then(() => {
            this.onReady();
        });
    }

    private onReady(): void {
        // 创建精灵
        const sprite = new Laya.Sprite();
        sprite.graphics.drawRect(0, 0, 200, 100, "#FF5722");
        sprite.pos(
            (Laya.stage.width - 200) / 2,
            (Laya.stage.height - 100) / 2
        );
        Laya.stage.addChild(sprite);

        // 使用定时器
        Laya.timer.loop(1000, this, this.onTimer);
    }

    private onTimer(): void {
        console.log("定时器触发");
    }
}

---

示例2: 移动端适配

export class MobileExample {
    constructor() {
        Laya.addBeforeInitCallback((config) => {
            // 移动端全屏适配
            if (Laya.Browser.onMobile) {
                config.designWidth = 0;
                config.designHeight = 0;
                config.scaleMode = Laya.Stage.SCALE_FIXED_AUTO;
            }
        });

        Laya.init({
            designWidth: 1136,
            designHeight: 640,
            scaleMode: Laya.Stage.SCALE_FIXED_AUTO,
            backgroundColor: "#232628"
        }).then(() => {
            this.onReady();
        });
    }

    private onReady(): void {
        // 启用多点触控
        Laya.InputManager.multiTouchEnabled = true;

        // 监听屏幕旋转
        Laya.stage.on(Laya.Event.RESIZE, this, this.onResize);
    }

    private onResize(): void {
        console.log("屏幕尺寸:", Laya.stage.width, Laya.stage.height);
    }
}

---

示例3: 3D 游戏初始化

export class Game3DExample {
    private scene: Laya.Scene3D;
    private camera: Laya.Camera;

    constructor() {
        Laya.init({
            designWidth: 0,
            designHeight: 0,
            scaleMode: Laya.Stage.SCALE_FULL,
            backgroundColor: "#000000"
        }).then(() => {
            this.init3D();
        });
    }

    private init3D(): void {
        // 创建3D场景
        this.scene = new Laya.Scene3D();
        Laya.stage.addChild(this.scene);

        // 创建相机
        this.camera = new Laya.Camera(0, 0.1, 100);
        this.camera.transform.translate(new Laya.Vector3(0, 2, -5));
        this.scene.addChild(this.camera);
    }
}

---

示例4: 微信小游戏适配

export class WeChatGameExample {
    constructor() {
        Laya.addBeforeInitCallback((config) => {
            // 微信小游戏特殊配置
            if (Laya.Browser.onWXMiniGame) {
                config.designWidth = 0;
                config.designHeight = 0;
                config.scaleMode = Laya.Stage.SCALE_FIXED_AUTO;
            }
        });

        Laya.init({
            designWidth: 1136,
            designHeight: 640,
            backgroundColor: "#232628"
        }).then(() => {
            this.onReady();
        });
    }

    private onReady(): void {
        if (Laya.Browser.onWXMiniGame) {
            // 监听焦点变化
            Laya.stage.on(Laya.Event.FOCUS, this, this.onFocus);
            Laya.stage.on(Laya.Event.BLUR, this, this.onBlur);
        }
    }

    private onFocus(): void {
        console.log("获得焦点");
        Laya.timer.scale = 1.0;
    }

    private onBlur(): void {
        console.log("失去焦点");
        Laya.timer.scale = 0; // 暂停游戏
    }
}

---

示例5: 时间控制

export class TimeControlExample {
    constructor() {
        Laya.init(1136, 640).then(() => {
            this.setupTimers();
        });
    }

    private setupTimers(): void {
        // 游戏逻辑定时器 - 受 scale 影响
        Laya.timer.loop(1000, this, this.onGameTimer);
        Laya.timer.scale = 1.0; // 正常速度

        // 倒计时定时器 - 不受 scale 影响
        Laya.systemTimer.loop(1000, this, this.onCountDown);

        // 暂停游戏
        Laya.timer.scale = 0;

        // 慢放效果
        Laya.timer.scale = 0.5;

        // 快进效果
        Laya.timer.scale = 2.0;
    }

    private onGameTimer(): void {
        console.log("游戏逻辑更新，受 scale 影响");
    }

    private onCountDown(): void {
        console.log("倒计时，不受 scale 影响");
    }
}

---

最佳实践

1. 初始化建议

✅ 推荐:

// 使用配置对象初始化
Laya.init({
    designWidth: 1136,
    designHeight: 640,
    scaleMode: Laya.Stage.SCALE_FIXED_AUTO,
    alignV: Laya.Stage.ALIGN_MIDDLE,
    alignH: Laya.Stage.ALIGN_CENTER,
    backgroundColor: "#232628"
}).then(() => {
    // 初始化完成后的逻辑
});

❌ 不推荐:

// 直接使用宽高，不够灵活
Laya.init(1136, 640);

2. 回调注册顺序

// 正确顺序：先注册回调，再初始化
Laya.addBeforeInitCallback((config) => {
    // 配置修改
});

Laya.addAfterInitCallback(() => {
    // 初始化后逻辑
});

Laya.init(config);

3. 错误处理

// 生产环境启用全局错误捕获
Laya.alertGlobalError(true);

Laya.init(config).catch((err) => {
    console.error("初始化失败:", err);
});

4. 访问全局对象

// ✅ 正确：使用 Laya. 前缀
Laya.stage.addChild(sprite);
Laya.timer.loop(1000, this, onUpdate);
Laya.loader.load("res.png");

// ❌ 错误：直接访问（会报错）
stage.addChild(sprite);
timer.loop(1000, this, onUpdate);

5. Timer 使用

// 游戏逻辑 - 使用 timer（可控制时间流速）
Laya.timer.loop(16, this, this.onGameUpdate);

// 倒计时 - 使用 systemTimer（不受时间缩放影响）
Laya.systemTimer.loop(1000, this, this.onCountDown);

// 时间缩放效果
Laya.timer.scale = 0.5; // 慢放
Laya.timer.scale = 2.0; // 快进
Laya.timer.scale = 0;   // 暂停

6. 资源加载

Laya.init().then(() => {
    // 预加载资源
    return Laya.loader.load([
        "res/atlas/game.atlas",
        "res/sounds/bgm.mp3"
    ]);
}).then(() => {
    // 资源加载完成，开始游戏
    this.startGame();
});

---

常见问题

Q1: 为什么要用配置对象初始化？

A: 配置对象更灵活，可以一次性设置多个参数，且易于维护。

// ✅ 推荐：配置对象
Laya.init({
    designWidth: 1136,
    designHeight: 640,
    scaleMode: Laya.Stage.SCALE_FIXED_AUTO
});

// ❌ 不推荐：多次调用
Laya.init(1136, 640);
Laya.stage.scaleMode = Laya.Stage.SCALE_FIXED_AUTO;

Q2: beforeInit 和 afterInit 有什么区别？

A:

• beforeInit: Stage 尚未创建，可以修改配置
• afterInit: Stage 已创建，可以操作舞台对象

Laya.addBeforeInitCallback((config) => {
    // ✅ 可以：修改配置
    config.scaleMode = Laya.Stage.SCALE_FIXED_AUTO;

    // ❌ 不可以：访问 Stage（Stage 不存在）
    // Laya.stage.bgColor = "#000"; // 错误
});

Laya.addAfterInitCallback(() => {
    // ✅ 可以：访问 Stage
    Laya.stage.bgColor = "#000";

    // ❌ 不可以：修改配置（已生效）
    // config.scaleMode = ...; // 无效
});

Q3: timer 和 systemTimer 应该如何选择？

A:

• timer: 游戏逻辑、动画、UI - 需要支持暂停/慢放/快进
• systemTimer: 倒计时、网络超时 - 必须准确实时

// 游戏动画 - 使用 timer
Laya.timer.loop(16, this, this.updateAnimation);

// 技能冷却倒计时 - 使用 systemTimer
Laya.systemTimer.loop(1000, this, this.updateCooldown);

Q4: 如何处理初始化失败？

A: 使用 Promise 的 catch 方法。

Laya.init(config)
    .then(() => {
        console.log("初始化成功");
    })
    .catch((err) => {
        console.error("初始化失败:", err);

        // 显示错误提示
        const tip = new Laya.Text();
        tip.text = "初始化失败，请刷新重试";
        Laya.stage.addChild(tip);
    });

Q5: 如何监听屏幕旋转？

A: 监听 RESIZE 事件。

Laya.init().then(() => {
    // 监听舞台尺寸变化
    Laya.stage.on(Laya.Event.RESIZE, this, this.onResize);
});

private onResize(): void {
    console.log("新尺寸:", Laya.stage.width, Laya.stage.height);
    // 重新布局 UI
}

Q6: 如何实现游戏暂停/继续？

A: 控制 timer.scale。

// 暂停
Laya.timer.scale = 0;

// 继续
Laya.timer.scale = 1.0;

// 慢放
Laya.timer.scale = 0.5;

Q7: 移动端如何适配？

A: 使用 designWidth: 0 和 SCALE_FIXED_AUTO。

Laya.addBeforeInitCallback((config) => {
    if (Laya.Browser.onMobile) {
        config.designWidth = 0;
        config.designHeight = 0;
        config.scaleMode = Laya.Stage.SCALE_FIXED_AUTO;
    }
});

Laya.init(config);

---

总结

关键要点:

1. ✅ 配置对象优先: 推荐使用配置对象初始化，更灵活
2. ✅ 回调顺序: beforeInit → init → initCallback → afterInit
3. ✅ Timer 区分: 游戏逻辑用 timer，倒计时用 systemTimer
4. ✅ 错误处理: 生产环境启用 alertGlobalError(true)
5. ✅ 平台适配: 移动端使用 designWidth: 0
6. ✅ Promise 链: 使用 .then() .catch() 处理异步流程