Up to date
This page is up to date for Godot 4.2
.
If you still find outdated information, please open an issue.
命令行教程¶
一些开发人员喜欢广泛使用命令行.Godot被设计为对他们友好, 所以这里是完全用命令行工作的步骤. 由于引擎几乎不依赖外部库, 因此初始化时间非常快, 使其适合此工作流程.
备注
在 Windows 和 Linux 上,你可以通过指定其相对或绝对路径在终端中运行 Godot 可执行文件。
在 macOS 上,由于 Godot 包含在 .app
包中,它是一个 文件夹,而不是文件,因此运行过程有所不同。要从 macOS 的终端运行 Godot 可执行文件,你必须 cd
到 Godot 应用程序包所在的文件夹,然后运行 Godot.app/Contents/MacOS/Godot
,并在后面加上相关命令行参数。如果你把应用包从 Godot
改名为其他名称,则需相应地编辑这个命令行。
命令行参考¶
图例解释
仅适用于编辑器构建、调试导出模板和发布导出模板中。
仅适用于编辑器构建和调试导出模板。
仅适用于编辑器构建。
请注意,未知的命令行参数不会产生任何影响。当命令行中使用了不存在的构建类型时,引擎不会发出警告。
常规选项
命令 |
描述 |
|
显示命令行选项列表。 |
|
显示版本字符串。 |
|
使用冗长标准输出模式。 |
|
安静模式,静默标准输出的信息。但错误仍然会显示。 |
运行选项
命令 |
描述 |
|
用户提供参数时使用的分隔符。引擎不会使用这些参数,但可以通过 |
|
启动编辑器而不是运行场景。 |
|
即使已经自动检测到项目,仍然启动项目管理器。 |
|
启动编辑器调试服务器( |
|
第一次迭代后退出. |
|
指定迭代次数后退出。设置为 0 则禁用。 |
|
使用特定本地语言。 |
|
项目的路径(<directory> 目录中必须包含一个“project.godot”文件)。 |
|
向上扫描文件夹中的“project.godot”文件。 |
|
要加载的包(.pck)文件的路径。 |
|
渲染线程模式('unsafe'、'safe'、'separate')。详见线程模型。 |
|
远程文件系统( |
|
远程文件系统的密码。 |
|
音频驱动。使用 |
|
视频驱动。使用 |
|
渲染器名称。需要驱动程序支持。 |
|
视频驱动。使用 |
|
使用特定 GPU(使用 |
|
文本驱动程序(字体、BiDi、整形)。 |
|
手写板输入驱动程序。 |
|
启用无头模式(--display-driver headless --audio-driver Dummy)。适用于服务器和 |
|
以写入影片(通常以 .avi 或 .png 为扩展名)的方式运行引擎。 |
显示选项
命令 |
描述 |
|
尝试使用全屏模式. |
|
尝试最大化窗口。 |
|
使用窗口模式。 |
|
请求一个置顶窗口. |
|
窗口分辨率。 |
|
指定屏幕位置. |
|
请求窗口分辨率。 |
|
使用单个窗口(没有单独的子窗口)。 |
|
选择 XR 模式("默认"、"关闭"、"打开")。 |
调试选项
命令 |
描述 |
|
调试(本地 stdout 调试器)。 |
|
断点列表,形式为英文逗号分隔的“源文件::行号”,不带空格(空格用 |
|
在脚本调试器中启用分析。 |
|
显示帧渲染过程中耗时最长任务的 GPU 分析。 |
|
启用图形 API 验证层 以进行调试。 |
|
在 GPU 出错时终止(通常是验证层错误),这有助于在系统冻结时发现问题。 |
|
远程调试( |
|
场景树以单线程模式运行。子线程组被禁用,在主线程上运行。 |
|
运行场景时显示碰撞框形状。 |
|
运行场景时显示路径。 |
|
运行场景时显示多边形导航。 |
|
当运行场景时显示多边形导航. |
|
当引擎退出时,将所有 StringName 分配打印到 stdout。 |
|
模拟高 CPU 负载(每帧延迟 <ms> 毫秒)。 |
|
强制时间缩放(值越大速度越快,1.0是正常速度)。 |
|
即使在项目设置中启用,也会强制禁用垂直同步。不会覆盖驱动程序级的 V-Sync 执行。 |
|
禁用渲染循环,以便仅在从脚本显式调用时才进行渲染。 |
|
当平台代码支持时,禁用崩溃处理程序。 |
|
每秒强制固定数量的帧。此设置禁用实时同步。 |
|
启用或禁用帧间隔平滑("启用"、"禁用")。 |
|
将每秒帧数打印到标准输出上。 |
单独的工具
命令 |
描述 |
|
运行脚本。 |
|
仅解析错误并退出(与 |
|
使用给定的预设和匹配的发布模板导出项目。预设名称应与 export_presets.cfg 中定义的名称一致。 |
|
与 |
|
与 |
|
将项目从 Godot 3.x 转换到 Godot 4.x。 |
|
显示把项目从 Godot 3.x 转换到 Godot 4.x 时将重命名哪些元素。 |
|
将引擎 API 参考以 XML 格式转储到给定的 |
|
禁止转储基本类型(与 |
|
不转储引擎 API,而是从 <路径> 找到 GDScript 文件(与 |
|
构建脚本解决方案(例如 C# 项目)。隐含 |
|
在当前文件夹下生成 GDExtension 头文件 “gdnative_interface.h”。该文件是实现 GDExtension 所需的基础文件。 |
|
在当前文件夹中生成 GDExtension 绑定的 Godot API ,其名为“extension_api.json” 的JSON 转储。 |
|
验证从上一版本引擎转储(使用上述选项)的扩展 API 文件,以确保 API 的兼容性。如果检测到不兼容或错误,返回代码将为非零。 |
|
对运行时间进行基准测试,并将其打印到控制台。 |
|
对运行时间进行基准测试,并以 JSON 格式保存到指定文件。路径应为绝对路径。 |
路径¶
建议将 Godot 编辑器的二进制文件放在 PATH
环境变量中,这样就可以通过在任何地方键入 godot
来轻松地执行。在 Linux 上,就可以将 Godot 二进制文件放在 /usr/local/bin
中,请确保文件名为 godot
(注意大小写)。
要在 Windows 或 macOS 上轻松实现这一目标,可以使用 Scoop(在 Windows 上)或 Homebrew(在 macOS 上)安装 Godot。这将自动在 PATH
中提供已安装的 Godot 副本:
# Standard editor:
scoop install godot
# Editor with C# support (will be available as `godot-mono` in `PATH`):
scoop install godot-mono
# Standard editor:
brew install godot
# Editor with C# support (will be available as `godot-mono` in `PATH`):
brew install godot-mono
设置项目路径¶
根据Godot二进制文件的位置以及当前的工作目录, 你可能需要设置项目的路径, 以下任何命令才能正常工作.
When running the editor, this can be done by giving the path to the project.godot
file
of your project as either the first argument, like this:
godot path_to_your_project/project.godot [other] [commands] [and] [args]
For all commands, this can be done by using the --path
argument:
godot --path path_to_your_project [other] [commands] [and] [args]
例如, 用于导出游戏的完整命令(如下所述)可能如下所示:
godot --headless --path path_to_your_project --export-release my_export_preset_name game.exe
When starting from a subdirectory of your project, use the --upwards
argument for Godot to
automatically find the project.godot
file by recursively searching the parent directories.
For example, running a scene (as explained below) nested in a subdirectory might look like this when your working directory is in the same path:
godot --upwards nested_scene.tscn
创建一个项目¶
要通过命令行创建项目,可以将 shell 导航至所需位置并创建 project.godot
文件。
mkdir newgame
cd newgame
touch project.godot
现在可以使用Godot打开该项目.
运行编辑器¶
Running the editor is done by executing Godot with the -e
flag. This
must be done from within the project directory or by setting the project path as explained above,
otherwise the command is ignored and the Project Manager appears.
godot -e
When passing in the full path to the project.godot
file, the -e
flag may be omitted.
如果已经创建并保存了场景, 则可以稍后以该场景作为参数运行相同的代码来对其进行编辑.
godot -e scene.tscn
删除一个场景¶
Godot对你的文件系统非常友好,不会创建额外的元数据文件。你可以使用 rm
来删除场景文件,但是在这之前需要确定该场景被引用的情况,否则再打开该项目时会抛出错误。
rm scene.tscn
运行游戏¶
To run the game, execute Godot within the project directory or with the project path as explained above.
godot
Note that passing in the project.godot
file will always run the editor instead of running the game.
当需要测试特定场景时, 将该场景传递给命令行.
godot scene.tscn
调试¶
捕获命令行中的错误可能是一项艰巨的任务,因为它们滚动得很快。为此,使用 -d
来启动命令行调试器。它适用于运行游戏或单个场景。
godot -d
godot -d scene.tscn
导出¶
也支持从命令行导出项目。这对持续集成设置特别有用。
备注
在没有 GPU 访问权限的平台上(如持续集成),必须使用 --headless
命令行参数。在有 GPU 访问权限的平台上, --headless
可阻止在导出项目时生成窗口。
# `godot` must be a Godot editor binary, not an export template.
# Also, export templates must be installed for the editor
# (or a valid custom export template must be defined in the export preset).
godot --headless --export-release "Linux/X11" /var/builds/project
godot --headless --export-release Android /var/builds/project.apk
预设名称必须与项目的 export_presets.cfg
文件中定义的导出预设名称一致. 如果预设名称包含空格或特殊字符(如 "Windows Desktop"), 必须用引号引起来.
要导出游戏的调试版本,请使用 --export-debug
开关,而不是 --export-release
。它们的参数和用法是相同的。
要仅导出 PCK 文件,请使用“--export-pack”选项,后跟预设名称和输出路径以及文件扩展名,而不是“--export-release”或“--export” -调试``。 输出路径扩展名决定包的格式:PCK 或ZIP。
警告
当指定相对路径作为“--export-release”、“--export-debug”或“--export-pack”的路径时,该路径将相对于包含“ project.godot` 文件, 而,不,是,相对于当前工作目录。
运行脚本¶
可以从命令行运行 .gd
脚本。此功能在大型项目中特别有用,例如,用于资产的批量转换或自定义导入/导出。
该脚本必须继承自 SceneTree
或 MainLoop
。
下面的 sayhello.gd
是一个简单的用法示例:
#!/usr/bin/env -S godot -s
extends SceneTree
func _init():
print("Hello!")
quit()
以及如何运行它:
# Prints "Hello!" to standard output.
godot -s sayhello.gd
如果路径中不存在 project.godot
,则假定当前路径为当前工作目录(除非指定了 --path
)。
以上 sayhello.gd
的第一行通常被称为 shebang。如果 Godot 二进制文件在你的 PATH
中,名为 godot
,则它允许你在现代 Linux 发行版以及 macOS 中按以下方式运行脚本:
# Mark script as executable.
chmod +x sayhello.gd
# Prints "Hello!" to standard output.
./sayhello.gd
如果上述方法在你当前版本的 Linux 或 macOS 中不起作用,你可以随时让 shebang 直接从它所在的位置运行 Godot:
#!/usr/bin/godot -s