游戏引擎 / 系统课时
给角色挂载第一个脚本
给角色挂载第一个脚本
本课把 TypeScript 文件变成真正运行在 3D 角色节点上的组件,并用控制台日志确认初始化、启用、逐帧更新与停用的时机。完成后,你能判断脚本为何没有执行,也能避免把一次性初始化误写成每帧工作。
学习目标
- 创建 TypeScript 组件,并将它挂载到场景中的角色节点。
- 区分
onLoad、onEnable、start、update、onDisable与onDestroy。 - 通过预览日志和组件启用状态验证生命周期。
创建脚本并挂到角色上
在 Cocos Creator 3.8 中,脚本文件是资源;只有作为组件挂到节点上,并满足相应激活条件,相关生命周期回调才会运行。先确保场景里已有一个摄像机可见的 3D 节点,例如将 Cube 重命名为 Player。
- 在资源管理器中选定存放脚本的文件夹,右键选择
TypeScript → NewComponent,命名为RoleHeartbeat。 - 双击
RoleHeartbeat.ts,将自动生成的模板替换为下方完整代码并保存。 - 返回编辑器,选中层级管理器中的
Player,将脚本资源拖入属性检查器;也可通过“添加组件”搜索RoleHeartbeat。 - 确认节点处于激活状态,组件的
Enabled已勾选,保存场景后再预览。
@ccclass('RoleHeartbeat') 用于注册组件类;@property 让 intervalSeconds 出现在属性检查器中。文件名、类名和注册名最好保持一致,便于定位脚本;不要在同一项目里重复注册同名组件类。
让生命周期留下可验证的日志
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');
}
}预期输出(首次预览并运行至少约一秒,控制台中的主要顺序):
RoleHeartbeat: onLoad
RoleHeartbeat: onEnable
RoleHeartbeat: start
RoleHeartbeat: ticktick 会在启用期间约每秒继续出现一次,具体间隔受帧更新影响;它不是引擎自带日志,而是代码主动打印的。首次激活时 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 则适合处理随组件永久结束的清理工作。这样角色被隐藏、重新启用或切换场景时,脚本行为才容易预测和排查。