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.stageLaya.Stage✅舞台对象引用，所有显示对象的根容器
Laya.timerLaya.Timer✅游戏主时钟，支持时间缩放，用于动画、缓动等
Laya.systemTimerLaya.Timer✅系统时钟，引擎内部使用，不受时间缩放影响
Laya.physicsTimerLaya.Timer✅物理时钟，用于物理引擎模拟
Laya.loaderLaya.Loader✅资源加载管理器
Laya.physics2DLaya.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>
参数类型说明
widthnumber舞台宽度
heightnumber舞台高度
stageConfigIStageConfig舞台配置对象

返回: 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
参数类型说明
valuebooleantrue = 捕获并弹窗，false = 不捕获

使用场景:

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

示例:

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

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

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

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

static _onGlobalError(ev: ErrorEvent | PromiseRejectionEvent): void
参数类型说明
evErrorEvent | PromiseRejectionEvent错误事件对象

其他方法

importNative()

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

static importNative(name: string): any
参数类型说明
namestring库名称

返回: 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() 处理异步流程
# 游戏引擎 # 游戏程序 # typescript
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

项目拆解（二）：模型输出是‘野‘的——三层兜底+重分析，把AI变成可靠零件

前两层都过了，数据入库了，最后一步是上屏。但这里还有坑——模型在"无风险"时会返回什么？真机实测：它返回了[""]，甚至[" "]（带空格的空串）。前端直接渲染，用户看到一个红色的空警告框，吓一跳。?${esc">无，这段代码挺干净</span>'">无，这段代码挺干净</span>'先t.trim()再。只挡不住[" "]（带空格的字符串是真值），必须先清空格再过滤。这是真机踩出来的：第一次只写

avatar 2048 AI社区
cover

风电场风力发电机数据集10203张：YOLO26 训练实录

avatar 2048 AI社区
cover

2026年10月AI监测工具推荐榜：从RAG引用漏斗到GEO工具选型

avatar 2048 AI社区