liko
    Preparing search index...

    Class Script<T>

    游戏对象行为脚本基类,提供完整的事件处理和生命周期管理

    继承自 BaseScript,为游戏对象添加丰富的事件响应能力,包括:

    • 指针事件(点击、按下、抬起、移动)
    • 物理碰撞事件(开始碰撞、结束碰撞)
    • 场景间通信事件(signal)
    • 全局输入事件(键盘按键)
    • 舞台级别事件(全局指针事件)
    // 创建一个基础的游戏脚本
    class PlayerScript extends Script<Player> {
    onAwake() {
    console.log('玩家对象已唤醒');
    }

    onClick(e: LikoPointerEvent) {
    console.log('玩家被点击了');
    this.target.position.x += 10;
    }

    onCollisionStart(collision: ICollision) {
    console.log('玩家撞到了:', collision.other);
    // 根据碰撞法线计算反弹
    const normal = collision.contact.normal;
    this.target.velocity.x = -normal.x * 100;
    }

    onKeyDown(e: KeyboardEvent) {
    if (e.key === 'Space') {
    this.target.jump();
    }
    }

    onSignal(type: string, params?: Record<string, unknown>) {
    if (type === 'gameOver') {
    this.target.visible = false;
    }
    }
    }

    // 将脚本附加到游戏对象
    const player = new Player();
    const script = new PlayerScript();
    player.addScript(script);
    • 所有事件处理方法都是可选的,只需重写需要的方法即可
    • 事件系统采用自动注册机制,无需手动绑定事件
    • 物理碰撞事件需要对象具有刚体组件才能触发
    • 信号事件在整个场景范围内有效,可用于跨对象通信
    • 舞台事件是全局的,不受对象层级影响

    Type Parameters

    Hierarchy (View Summary)

    Index

    Constructors

    Properties

    id: string = ''

    脚本唯一标识符,通常由编辑器指定

    label: string = ''

    脚本标签,用于快速识别和查找

    Accessors

    • get awaked(): boolean

      脚本是否已被激活(添加到场景后触发)

      Returns boolean

    • get destroyed(): boolean

      脚本是否已被销毁

      Returns boolean

    • get enabled(): boolean

      脚本是否启用,禁用时不执行更新且触发 onDisable

      Returns boolean

    • set enabled(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get scene(): undefined | IScene

      目标节点所在的场景引用(建议缓存为局部变量以提高性能)

      Returns undefined | IScene

    • get target(): T

      脚本挂载的目标节点,设置后触发 onCreate

      Returns T

    • set target(value: T): void

      Parameters

      • value: T

      Returns void

    Methods

    • 销毁脚本实例

      Returns void

      销毁后脚本将不再可用,系统会自动:

      • 触发 onDestroy 回调
      • 清除在 target、scene、stage、timer 上的所有监听
      • 解除与目标节点的关联
      • 设置 destroyed 状态为 true
      • 设置 enabled 状态为 false

      注意: 如果使用了 Timer.system 的监听,需要在 onDestroy 中手动清除

    • 脚本第一次被激活时触发的回调函数

      Returns void

      只会触发一次,此时:

      • target 已经添加到场景中
      • 可以安全访问 scene 和 stage
      • 适合进行初始化设置和事件监听
    • 当绑定的目标对象被点击时触发

      Parameters

      Returns void

      • 只有当对象可交互且未被遮挡时才会触发
      • 可以通过事件对象获取点击的屏幕坐标和世界坐标
    • 当目标对象结束与其他刚体的物理碰撞时触发

      Parameters

      • collision: ICollision

        碰撞信息对象,包含分离的碰撞对象信息

      Returns void

      • 与 onCollisionStart 成对出现
      • 适用于碰撞状态重置、离开触发器等场景
      • 可用于停止碰撞相关的持续效果
    • 当目标对象开始与其他刚体发生物理碰撞时触发

      Parameters

      • collision: ICollision

        碰撞信息对象,包含碰撞对象和接触点信息

      Returns void

      • 需要目标对象具有 RigidBody 组件才能触发
      • 适用于碰撞检测、触发器响应、伤害计算等场景
      • 碰撞法线可用于计算反弹方向和力度
    • 当脚本的 target 被设置时触发的回调函数

      Returns void

      生命周期中的第一个回调,此时:

      • target 已经设置完成
      • 可以访问 target 的属性和方法
      • 但 scene 和 stage 可能还未初始化
    • 脚本被销毁时触发的回调函数

      Returns void

      用于清理资源和释放引用,如:

      • 移除事件监听
      • 清理定时器
      • 释放对象引用

      注意: 系统会自动清理大部分监听,但使用 Timer.system 的监听需要手动清除

    • 当键盘按键被按下时触发

      Parameters

      • e: KeyboardEvent

        标准键盘事件对象,包含按键信息、修饰键状态等

      Returns void

      • 全局键盘事件,不受对象焦点影响
      • 适用于游戏控制、快捷键响应、输入处理等场景
      • 可以通过 e.key、e.code、e.keyCode 获取按键信息
      • 支持修饰键检测:e.ctrlKey、e.shiftKey、e.altKey
    • 当键盘按键被抬起时触发

      Parameters

      • e: KeyboardEvent

        标准键盘事件对象,包含按键信息、修饰键状态等

      Returns void

      • 与 onKeyDown 成对出现
      • 适用于按键释放检测、组合键处理、输入完成等场景
      • 对于需要持续响应的按键,建议使用输入管理器而非键盘事件
    • 当指针在目标对象上按下时触发

      Parameters

      • e: LikoPointerEvent

        指针事件对象,包含按下位置、按钮类型等信息

      Returns void

      • 在 onClick 事件之前触发
      • 适用于拖拽开始、长按检测等场景
      • 支持鼠标左键、右键、中键的区分
    • 当指针在目标对象上移动时触发

      Parameters

      • e: LikoPointerEvent

        指针事件对象,包含移动位置、移动增量等信息

      Returns void

      • 高频触发事件,注意性能优化
      • 适用于鼠标悬停效果、拖拽移动、实时跟踪等场景
      • 可以通过事件对象获取移动的增量值
    • 当指针在目标对象上抬起时触发

      Parameters

      • e: LikoPointerEvent

        指针事件对象,包含抬起位置、按钮类型等信息

      Returns void

      • 适用于拖拽结束、按钮释放等场景
    • 当场景中的其他对象发送信号时触发

      Parameters

      • type: string

        信号类型标识符,用于区分不同的信号

      • Optionalparams: Record<string, unknown>

        可选的信号参数对象,用于传递额外数据

      Returns void

      • 用于跨对象、跨脚本的通信
      • 信号在整个场景范围内广播
      • 适用于游戏状态变化、全局事件通知等场景
      • 发送信号使用:this.scene.emit(EventType.signal, type, params)
    • 当舞台(全局画布)被点击时触发

      Parameters

      Returns void

      • 全局事件,不受对象层级限制
      • 即使点击空白区域也会触发
      • 适用于全局UI交互、背景点击处理等场景
    • 当在舞台(全局画布)上按下指针时触发

      Parameters

      Returns void

      • 全局事件,不受对象层级限制
      • 适用于全局拖拽开始、右键菜单等场景
    • 当在舞台(全局画布)上移动指针时触发

      Parameters

      Returns void

      • 高频全局事件,注意性能优化
      • 适用于全局鼠标跟踪、十字准星、全局UI响应等场景
    • 当在舞台(全局画布)上抬起指针时触发

      Parameters

      Returns void

      • 全局事件,不受对象层级限制
      • 适用于全局拖拽结束、右键菜单关闭等场景
    • 每帧更新时触发的回调函数

      Parameters

      • delta: number

        距离上一帧的时间间隔(毫秒)

      Returns void

      用于实现脚本的主要逻辑,如:

      • 移动和动画
      • 状态检查和更新
      • 输入处理
      • 物理计算等
    • 批量设置脚本属性

      Parameters

      • Optionalprops: Record<string, unknown>

        要设置的属性键值对

      Returns this

      当前实例,支持链式调用

    • 向同场景的其他脚本发送信号

      Parameters

      • key: string

        信号类型标识符

      • Optionalparams: Record<string, any>

        可选的信号参数对象

      Returns void

      发送的信号可以在同场景其他脚本的 onSignal 方法中被监听到,用于脚本间通信。

      注意:

      • 必须在脚本销毁前发送信号,否则无法正确触发
      • 信号只能在同一场景内传递
      • key 不区分大小写
    • 执行脚本的更新逻辑

      Parameters

      • delta: number

        距离上一帧的时间间隔(毫秒)

      Returns void

      系统每帧调用一次,用于更新脚本状态。

      执行条件:

      • 脚本必须处于启用状态(enabled = true)
      • 脚本必须已经激活(awaked = true)
      • 如果是首次执行,会先触发 onAwake