游戏引擎 / 系统课时
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 后,先在项目管理器中完成工程创建:
- 选择新建项目(Create),将项目命名为
GodotScenePractice。 - 选择一个可写的空目录作为工程路径;如果使用自动创建文件夹功能,应确认最终目录正确。
- 渲染器可以选择
Compatibility,它足以完成本次简单 2D 练习,对图形设备的要求也较低。 - 确认项目名称、路径和渲染器后创建项目,并进入编辑器。
进入编辑器后,先确认左侧能够看到 Scene 场景面板和 FileSystem 文件系统面板,中央为场景编辑区,右侧为 Inspector 属性检查器。
Godot 工程目录下的 project.godot 保存项目设置。编辑器使用 res:// 指代工程资源根目录,它不是磁盘上的另一个独立文件夹。
创建并保存第一个节点场景
我们要制作一个极简结果:游戏窗口显示“首个场景运行成功”,同时在编辑器的 Output 面板打印场景名称。
先建立两个资源目录,便于区分场景文件与脚本文件。在 FileSystem 面板中右键项目根目录 res://,分别创建 scenes 和 scripts 文件夹。
然后创建入口场景:
- 在空场景界面选择创建 2D 场景,得到类型为
Node2D的根节点。 - 将根节点重命名为
Main。 - 选中
Main,添加一个Label子节点,命名为StatusLabel。 - 在 2D 编辑区将
StatusLabel放在游戏可见区域内,例如局部坐标(40, 40)。 - 在 Inspector 中将
Label的Text属性暂时设置为“等待启动”。 - 保存当前场景为
res://scenes/main.tscn。
这里选择 Node2D 而不是普通 Node,是为了让后续的二维子节点能够处于清晰的空间坐标体系中;使用 Label 则是因为它能直接绘制文字,不需要额外纹理资源。
保存完成后,FileSystem 面板中应该能够看到 scenes/main.tscn。场景保存的是节点结构和属性,并不等于已经执行其中的脚本。
挂载 GDScript 并显示运行结果
选中 Main 根节点,点击场景面板中的附加脚本(Attach Script)按钮。在创建脚本时选择 GDScript,继承类型保持为 Node2D,脚本路径设置为 res://scripts/main.gd。
如果编辑器生成了默认模板,可以直接替换为下面的完整脚本:
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 面板。
保存脚本和场景,运行后预期输出:
场景已就绪:Main预期页面效果:游戏窗口中原本的“等待启动”被替换成“首个场景运行成功”,文字显示在刚才设置的位置。
这两个结果分别证明不同的事情:窗口文字说明节点存在且属性更新成功;Output 日志说明 Main 的脚本已经加载并执行到 _ready()。
验证当前场景和项目入口
Godot 提供两种容易混淆的运行方式:运行当前场景和运行整个项目。它们的区别不是窗口样式,而是选择启动哪个场景。

先验证运行当前场景:
- 打开并选中
main.tscn对应的场景标签。 - 点击编辑器右上角的运行当前场景(Run Current Scene),或在 Windows、Linux 上按
F6。 - 如果编辑器提示保存修改,先保存再继续运行。
- 确认游戏窗口出现指定文字,并检查 Output 面板是否打印场景名称。
- 关闭运行窗口,或者在编辑器中按
F8停止运行。
这一操作以当前打开的场景为入口。即使项目尚未指定主场景,保存后的当前场景仍然可以通过这种方式进行测试。
再验证运行整个项目:
- 点击运行项目(Run Project),或在 Windows、Linux 上按
F5。 - 如果这是首次运行项目,Godot 通常会提示选择主场景。
- 在文件选择界面中选择
res://scenes/main.tscn,确认其成为项目主场景。 - 再次使用
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 时,仍然可以采用相同的保存、运行和检查流程来确认每个场景是否正常工作。