游戏引擎 / 系统课时

给角色挂载第一个脚本

给角色挂载第一个脚本

本课把 TypeScript 文件变成真正运行在 3D 角色节点上的组件,并用控制台日志确认初始化、启用、逐帧更新与停用的时机。完成后,你能判断脚本为何没有执行,也能避免把一次性初始化误写成每帧工作。

学习目标

  • 创建 TypeScript 组件,并将它挂载到场景中的角色节点。
  • 区分 onLoad、onEnable、start、update、onDisable 与 onDestroy。
  • 通过预览日志和组件启用状态验证生命周期。

创建脚本并挂到角色上

在 Cocos Creator 3.8 中,脚本文件是资源;只有作为组件挂到节点上,并满足相应激活条件,相关生命周期回调才会运行。先确保场景里已有一个摄像机可见的 3D 节点,例如将 Cube 重命名为 Player。

  1. 在资源管理器中选定存放脚本的文件夹,右键选择 TypeScript → NewComponent,命名为 RoleHeartbeat。
  2. 双击 RoleHeartbeat.ts,将自动生成的模板替换为下方完整代码并保存。
  3. 返回编辑器,选中层级管理器中的 Player,将脚本资源拖入属性检查器;也可通过“添加组件”搜索 RoleHeartbeat。
  4. 确认节点处于激活状态,组件的 Enabled 已勾选,保存场景后再预览。

@ccclass('RoleHeartbeat') 用于注册组件类;@property 让 intervalSeconds 出现在属性检查器中。文件名、类名和注册名最好保持一致,便于定位脚本;不要在同一项目里重复注册同名组件类。

让生命周期留下可验证的日志

ts
import { _decorator, Component } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('RoleHeartbeat')
export class RoleHeartbeat extends Component {
    @property
    intervalSeconds = 1;

    private elapsed = 0;

    onLoad() {
        console.log('RoleHeartbeat: onLoad');
    }

    onEnable() {
        // 重新启用后从零开始计时。
        this.elapsed = 0;
        console.log('RoleHeartbeat: onEnable');
    }

    start() {
        console.log('RoleHeartbeat: start');
    }

    update(deltaTime: number) {
        // deltaTime 以秒为单位,避免按帧数计时。
        this.elapsed += deltaTime;
        if (this.elapsed >= Math.max(0.1, this.intervalSeconds)) {
            this.elapsed = 0;
            console.log('RoleHeartbeat: tick');
        }
    }

    onDisable() {
        console.log('RoleHeartbeat: onDisable');
    }

    onDestroy() {
        console.log('RoleHeartbeat: onDestroy');
    }
}

预期输出(首次预览并运行至少约一秒,控制台中的主要顺序):

text
RoleHeartbeat: onLoad
RoleHeartbeat: onEnable
RoleHeartbeat: start
RoleHeartbeat: tick

tick 会在启用期间约每秒继续出现一次,具体间隔受帧更新影响;它不是引擎自带日志,而是代码主动打印的。首次激活时 onLoad、onEnable、start 依次触发;update 在后续帧持续执行。停用再启用时不会重跑 onLoad 和 start。

角色脚本首次启用、逐帧执行、停用和销毁的生命周期关系

验证启停并排除无响应

先保持组件启用并预览,确认控制台出现预期顺序。停止预览后取消组件的 Enabled 勾选,再启动一次预览:组件不会执行 onEnable、start 和 update,因此不会打印 tick。重新勾选并再次预览,就能恢复正常运行。

当运行中的其他脚本把组件的 enabled 设为 false,或把节点的 active 设为 false 时,会触发 onDisable;恢复启用后触发 onEnable。只有组件或其节点在运行时真正销毁,才会触发 onDestroy,不宜只凭停止预览判断销毁回调。

若完全没有日志,先检查脚本是否编译报错、是否挂在当前运行场景的 Player 上,以及节点和组件是否均被启用。若日志出现但节点没有可见变化,这是正常的:本示例只验证脚本执行与计时,并未修改角色位置。

什么时候使用这些回调

onLoad 适合读取组件引用和建立初始状态,start 适合首次运行前的准备,update 适合连续变化的逻辑。不要把只需执行一次的初始化放进 update,否则每帧都会重复处理。

onEnable 和 onDisable 应成对管理临时资源,例如全局输入监听、运行期间才需要的事件订阅。onDestroy 则适合处理随组件永久结束的清理工作。这样角色被隐藏、重新启用或切换场景时,脚本行为才容易预测和排查。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

给角色挂载第一个脚本

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通