游戏引擎 / 系统课时

Godot 工程运行首个场景

Godot 工程运行首个场景

这一课使用 Godot 4.6 标准版和 GDScript,从空工程制作一个能够显示文字、执行脚本并输出日志的 2D 场景。完成后,你将能区分运行当前场景与运行整个项目,并独立排查场景未保存、主场景未设置和节点引用错误等常见问题。

学习目标

  • 创建 Godot 4.6 工程,保存第一个 .tscn 场景并挂载 GDScript。
  • 验证 _ready() 执行、游戏窗口显示和 Output 日志结果。
  • 区分运行当前场景与运行项目的入口,解决最常见的首次启动问题。

准备 Godot 4.6 标准版工程

本次练习固定使用 Godot 4.6 Standard 版本和内置的 GDScript,不需要安装 .NET SDK,也不需要准备第三方插件、美术资源或外部代码编辑器。

可以从 Godot 4.6 Stable 官方下载页面 获取对应操作系统的标准版。注意选择 Standard,而不是为了 C# 开发准备的 .NET 版本。

启动 Godot 后,先在项目管理器中完成工程创建:

  1. 选择新建项目(Create),将项目命名为 GodotScenePractice。
  2. 选择一个可写的空目录作为工程路径;如果使用自动创建文件夹功能,应确认最终目录正确。
  3. 渲染器可以选择 Compatibility,它足以完成本次简单 2D 练习,对图形设备的要求也较低。
  4. 确认项目名称、路径和渲染器后创建项目,并进入编辑器。

进入编辑器后,先确认左侧能够看到 Scene 场景面板和 FileSystem 文件系统面板,中央为场景编辑区,右侧为 Inspector 属性检查器。

Godot 工程目录下的 project.godot 保存项目设置。编辑器使用 res:// 指代工程资源根目录,它不是磁盘上的另一个独立文件夹。

创建并保存第一个节点场景

我们要制作一个极简结果:游戏窗口显示“首个场景运行成功”,同时在编辑器的 Output 面板打印场景名称。

先建立两个资源目录,便于区分场景文件与脚本文件。在 FileSystem 面板中右键项目根目录 res://,分别创建 scenes 和 scripts 文件夹。

然后创建入口场景:

  1. 在空场景界面选择创建 2D 场景,得到类型为 Node2D 的根节点。
  2. 将根节点重命名为 Main。
  3. 选中 Main,添加一个 Label 子节点,命名为 StatusLabel。
  4. 在 2D 编辑区将 StatusLabel 放在游戏可见区域内,例如局部坐标 (40, 40)。
  5. 在 Inspector 中将 Label 的 Text 属性暂时设置为“等待启动”。
  6. 保存当前场景为 res://scenes/main.tscn。

这里选择 Node2D 而不是普通 Node,是为了让后续的二维子节点能够处于清晰的空间坐标体系中;使用 Label 则是因为它能直接绘制文字,不需要额外纹理资源。

保存完成后,FileSystem 面板中应该能够看到 scenes/main.tscn。场景保存的是节点结构和属性,并不等于已经执行其中的脚本。

挂载 GDScript 并显示运行结果

选中 Main 根节点,点击场景面板中的附加脚本(Attach Script)按钮。在创建脚本时选择 GDScript,继承类型保持为 Node2D,脚本路径设置为 res://scripts/main.gd。

如果编辑器生成了默认模板,可以直接替换为下面的完整脚本:

gdscript
extends Node2D

@onready var status_label: Label = $StatusLabel

func _ready() -> void:
    # 子节点准备完成后,更新窗口文字并记录启动信息。
    status_label.text = "首个场景运行成功"
    print("场景已就绪:", name)

这段脚本只使用 Godot 4.6 的内置 API,不需要额外导入依赖。

extends Node2D 声明脚本的节点基类。@onready 会在节点进入就绪阶段时初始化变量,因此适合获取已经存在的子节点。$StatusLabel 是获取相对子节点的简写形式,节点名称必须与场景树完全一致。

_ready() 会在节点首次完成就绪时调用。这里修改 Label.text 以产生可见结果,再用 print() 将场景名称写入编辑器的 Output 面板。

保存脚本和场景,运行后预期输出:

text
场景已就绪:Main

预期页面效果:游戏窗口中原本的“等待启动”被替换成“首个场景运行成功”,文字显示在刚才设置的位置。

这两个结果分别证明不同的事情:窗口文字说明节点存在且属性更新成功;Output 日志说明 Main 的脚本已经加载并执行到 _ready()。

验证当前场景和项目入口

Godot 提供两种容易混淆的运行方式:运行当前场景和运行整个项目。它们的区别不是窗口样式,而是选择启动哪个场景。

Godot 4.6 编辑器中场景面板与运行按钮的位置

先验证运行当前场景:

  1. 打开并选中 main.tscn 对应的场景标签。
  2. 点击编辑器右上角的运行当前场景(Run Current Scene),或在 Windows、Linux 上按 F6。
  3. 如果编辑器提示保存修改,先保存再继续运行。
  4. 确认游戏窗口出现指定文字,并检查 Output 面板是否打印场景名称。
  5. 关闭运行窗口,或者在编辑器中按 F8 停止运行。

这一操作以当前打开的场景为入口。即使项目尚未指定主场景,保存后的当前场景仍然可以通过这种方式进行测试。

再验证运行整个项目:

  1. 点击运行项目(Run Project),或在 Windows、Linux 上按 F5。
  2. 如果这是首次运行项目,Godot 通常会提示选择主场景。
  3. 在文件选择界面中选择 res://scenes/main.tscn,确认其成为项目主场景。
  4. 再次使用 F5 运行,确认窗口显示和 Output 日志与前一次一致。

在 macOS 上,官方默认快捷键对应为运行当前场景 Cmd+R、运行项目 Cmd+B;如果已自定义快捷键,应以当前编辑器设置为准。

主场景选择会保存在项目配置中。后续即使编辑器打开了另一个场景,使用 F5 仍会从已设置的主场景启动,而 F6 会运行当前编辑的场景。

还可以在 FileSystem 面板中右键 main.tscn,选择 Set As Main Scene,将它直接设置为主场景。

首次运行失败时怎样定位

第一次运行失败通常不需要重新安装 Godot。先按照“场景资源是否存在、入口是否正确、脚本是否成功执行、节点是否能找到”的顺序检查。

现象 优先检查 修复方式
运行时要求保存场景 当前场景尚未保存 将场景保存为 main.tscn 后重试
F6 正常但 F5 不能进入预期场景 项目主场景未设置或设置错误 重新选择 main.tscn 为主场景
游戏窗口打开但没有文字 Label 位置、可见性或脚本执行状态 检查 StatusLabel、位置以及 Debugger 错误
提示找不到 StatusLabel 节点名称或父子关系不匹配 确认 StatusLabel 是 Main 的直接子节点
脚本无法运行 GDScript 语法、缩进或挂载位置错误 查看错误行,确认脚本挂载在 Main
Output 没有预期日志 运行入口不对或脚本未执行 核对当前场景、主场景以及根节点的脚本图标

其中最容易出现的是节点路径错误。比如把节点命名为 Statuslabel,却在脚本中使用 $StatusLabel,Godot 不会自动纠正大小写。

另一个常见问题是 Label 已经创建,但被放在游戏窗口可视区域之外。此时脚本可能完全正确,Output 也能打印日志,只是玩家看不到文字。可以把 Label 的局部位置恢复到 (40, 40) 后再运行。

如果编辑器底部出现红色错误信息,应优先打开 Debugger 查看实际错误,而不是只凭游戏窗口有没有出现内容判断脚本是否成功。

检查工程是否真正跑通

完成操作后,可以按照下面的条件验收:

  • 工程根目录中存在 project.godot。
  • res://scenes/main.tscn 能被重新打开,包含 Main 和 StatusLabel 两个节点。
  • Main 正确挂载 res://scripts/main.gd。
  • 使用 F6 能看到“首个场景运行成功”,并输出“场景已就绪:Main”。
  • 使用 F5 能从项目主场景进入并得到相同结果。
  • 停止运行后,再次启动仍能复现结果,不依赖上一次的临时状态。

可以再做一个小验证:把脚本中的显示文字改成“第二次运行成功”,保存后重新使用 F6 运行。预期结果是窗口文字改变,而 Output 中的场景名称仍为 Main。这说明脚本资源、场景资源与运行入口之间的关系已经建立正确。

到这里,工程已经具备了一个可保存、可加载、可执行、可重复验证的最小 Godot 场景。后续增加角色、关卡和 UI 时,仍然可以采用相同的保存、运行和检查流程来确认每个场景是否正常工作。

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

目录与阅读设置

阅读设置

17

记录一个想法

Godot 工程运行首个场景

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

登录哪都通