游戏引擎 / 系统课时

运行并调试第一个场景

运行并调试第一个场景

本课用一个可见的 Label 和一条可搜索的日志,确认 Cocos Creator 3.8 场景已经真正运行,再在 Chrome 中给 TypeScript 脚本设置断点,检查组件引用和执行顺序。完成后,你能区分场景显示问题、脚本挂载问题与运行时报错。

学习目标

  • 使用浏览器预览确认场景画面和脚本日志。
  • 用 Console 与 Sources 定位组件运行位置并设置断点。
  • 按可见现象排查空白画面、缺失引用和断点未命中。

准备可见且可记录的测试场景

打开一个已保存的 2D 场景;没有 Canvas 就先创建。接着在 Canvas 下创建一个 UI Label 节点并命名为 Status,保持它位于画面可见区域;再创建一个空节点 Probe。两者分别承担显示测试结果和运行脚本的职责。

在资源管理器中右键选择 TypeScript → NewComponent,创建 SceneProbe.ts,写入以下代码。statusLabel 是可在属性检查器中拖拽绑定的 Label 组件引用。

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

@ccclass('SceneProbe')
export class SceneProbe extends Component {
    @property({ type: Label })
    public statusLabel: Label | null = null;

    start(): void {
        const message = '场景运行正常';
        // 先输出日志,便于区分未执行与未显示。
        console.log(`[SceneProbe] ${message}`);
        if (!this.statusLabel) {
            console.warn('[SceneProbe] Status Label 未绑定');
            return;
        }
        // 修改的是场景中已绑定的 Label 组件。
        this.statusLabel.string = message;
    }
}

预期输出:将 SceneProbe 挂到 Probe,把 Status 节点拖进组件的 Status Label 属性并预览后,浏览器 Console 出现:

text
[SceneProbe] 场景运行正常

同时,画面中的 Status 文字显示为“场景运行正常”。如果忘记绑定,日志仍会输出,另有 [SceneProbe] Status Label 未绑定 警告,但标签文字不会更新。这正好能区分“脚本没执行”和“节点引用没配置”。

要完成绑定,需要在层级管理器选中 Probe,确认属性检查器中已经挂载 SceneProbe 组件,再把 Status 节点拖到 Status Label 字段中。因为属性声明使用的是 Label 类型,编辑器会引用该节点上的 Label 组件,而不只是保存一个节点名称字符串。

通过浏览器预览核对场景

保存脚本与场景,等待编辑器完成编译;在顶部工具栏选择 浏览器 预览方式,场景选择 当前场景,再点击预览。浏览器会打开当前场景对应的运行页面。

第一次验证时,重点观察三个结果:

  1. 浏览器页面能否正常显示场景中的 Label。
  2. Label 内容能否从原始文字变成“场景运行正常”。
  3. 控制台能否找到 [SceneProbe] 场景运行正常。

在打开的预览浏览器页面按 F12,或使用 Ctrl+Shift+I 调出该页面的开发者工具,切换到 Console,搜索 [SceneProbe]。

浏览器的开发者工具负责调试网页预览。不要误把 Cocos Creator 编辑器自身的开发者工具当成预览页面的 Console,因为两者的执行上下文不同。

场景画面正确但没有日志时,先检查控制台过滤条件。已经出现日志但画面不变时,优先检查 Status Label 绑定是否完整,以及 Label 是否被其他 UI 遮挡、处于不可见状态。

在 Sources 中设置并命中断点

控制台日志只能告诉我们代码是否执行过,断点则可以让运行中的程序停在指定语句前,直接检查当时的变量、组件引用和调用位置。

本次把断点设在修改 Label 文字的语句上,目的是确认引擎已经运行到 start(),并且 statusLabel 在赋值之前确实引用了场景中的组件。

  1. 保持预览页面及其开发者工具打开,切换到 Sources。用文件搜索查找 SceneProbe.ts;若显示的是编译后代码,可搜索 SceneProbe 并在对应的运行代码处定位。
  2. 在 this.statusLabel.string = message; 所在行左侧单击设置断点。若脚本在页面打开时已经执行过,刷新预览页面以重新触发 start()。
  3. 暂停后在 Scope 查看 message 和 this.statusLabel。在当前暂停调用帧的求值上下文中检查 this.node.name,应得到 Probe;同时确认 statusLabel 不为 null。
  4. 使用单步越过该赋值语句,再继续运行。若赋值已执行,屏幕文字应更新;调试结束后移除断点,避免后续刷新反复暂停。

Chrome 浏览器 Sources 断点调试区域

首次进入 start() 时,message 应为字符串“场景运行正常”。如果在执行赋值前检查画面,Label 仍可能显示原始文字;单步执行赋值后,组件中的 string 属性就会变成新值。渲染画面通常需要在继续运行后才刷新,因此不要把断点暂停期间尚未重绘的画面误判为赋值失败。

如果 Sources 没有显示原始 TypeScript 文件,可能是源码映射尚未生效。可以先在 Sources 中定位到包含 SceneProbe 的实际执行脚本,再对对应的 JavaScript 语句设置断点。此时仍能调试执行逻辑,只是源码展示位置可能不同。

按现象缩小故障范围

现象 优先检查 验证动作
浏览器画面空白 当前场景、Canvas、Label 可见性 在编辑器中选中 Status,确认启用并保存后刷新
无 [SceneProbe] 日志 组件是否挂载、Probe 是否激活、脚本编译状态 检查组件启用勾选和编辑器错误信息
有日志但文字没变化 Status Label 是否绑定、Label 是否被遮挡 拖入 Status 后重新预览
断点未命中 DevTools 是否属于当前预览页、代码映射是否正确 设置断点后刷新,必要时在生成的脚本中设断点

排查时先保持场景和脚本尽量简单。不要同时改动相机、UI 布局、组件生命周期和预览配置,否则很难判断哪项修改真正修复了问题。

如果控制台出现错误,应先阅读第一条与自己脚本有关的异常,查看对应文件、行号和调用栈,再定位到代码处理。对于本例,statusLabel 未绑定已经通过空值检查转换成明确警告,比直接访问空引用后抛出异常更容易判断原因。

可以再做一次故意失败的验证:清空 Probe 上的 Status Label 属性并重新预览,确认 Console 输出未绑定警告;随后恢复引用,确认画面重新显示正确文字。这样就形成了“制造问题 → 观察证据 → 修复配置 → 再次验证”的完整调试过程。

在这次测试中,看到画面只能证明渲染链路可用;同时获得预期日志和可命中的断点,才说明场景加载、组件运行与调试入口全部贯通。

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

目录与阅读设置

阅读设置

17

记录一个想法

运行并调试第一个场景

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

登录哪都通