命令行教程

命令行教程

一些开发人员喜欢广泛使用命令行.Godot被设计为对他们友好, 所以这里是完全用命令行工作的步骤. 由于引擎几乎不依赖外部库, 因此初始化时间非常快, 使其适合此工作流程.

备注

在 Windows 和 Linux 上，你可以通过指定其相对或绝对路径在终端中运行 Godot 可执行文件。

在 macOS 上，由于 Godot 包含在 .app 包中，它是一个 文件夹，而不是文件，因此运行过程有所不同。要从 macOS 的终端运行 Godot 可执行文件，你必须 cd 到 Godot 应用程序包所在的文件夹，然后运行 Godot.app/Contents/MacOS/Godot，并在后面加上相关命令行参数。如果你把应用包从 Godot 改名为其他名称，则需相应地编辑这个命令行。

命令行参考

图例解释

仅适用于编辑器构建、调试导出模板和发布导出模板中。
仅适用于编辑器构建和调试导出模板。
仅适用于编辑器构建。

请注意，未知的命令行参数不会产生任何影响。当命令行中使用了不存在的构建类型时，引擎不会发出警告。

常规选项

命令	描述
`-h`, `—help`	显示命令行选项列表。
`—version`	显示版本字符串。
`-v`, `—verbose`	使用冗长标准输出模式。
`-q`, `—quiet`	安静模式，静默标准输出的信息。但错误仍然会显示。

运行选项

命令	描述
`—`, `++`	用户提供参数时使用的分隔符。引擎不会使用这些参数，但可以通过 `OS.get_cmdline_user_args()` 读取到。
`-e`, `—editor`	启动编辑器而不是运行场景。
`-p`, `—project-manager`	即使已经自动检测到项目，仍然启动项目管理器。
`—debug-server <uri>`	启动编辑器调试服务器（ `<protocol>://<host/IP>[:<port>]`，例如， `tcp://127.0.0.1:6007`）
`—quit`	第一次迭代后退出.
`—quit-after`	指定迭代次数后退出。设置为 0 则禁用。
`-l <locale>`, `—language <locale>`	使用特定本地语言。 `<locale>` 格式为 `language_Script_COUNTRY_VARIANT`，其中 language 为小写的 2 或 3 个字母组成的语言代码，其余为可选项。详情请参见区域设置代码。
`—path <目录>`	项目的路径（<directory> 目录中必须包含一个“project.godot”文件）。
`-u`, `—upwards`	向上扫描文件夹中的“project.godot”文件。
`—main-pack <file>`	要加载的包（.pck）文件的路径。
`—render-thread <模式>`	渲染线程模式（’unsafe’、’safe’、’separate’）。详见线程模型。
`—remote-fs <地址>`	远程文件系统（`<主机名/IP>[:<端口号>]` 地址）。
`—remote-fs-password <password>`	远程文件系统的密码。
`—audio-driver <驱动>`	音频驱动。使用 `—help` 来显示可用驱动列表。
`—display-driver <driver>`	视频驱动。使用 `—help` 来显示可用驱动列表。
`—rendering-method <renderer>`	渲染器名称。需要驱动程序支持。
`—rendering-driver <driver>`	视频驱动。使用 `—help` 来显示可用驱动列表。
`—gpu-index <设备索引>`	使用特定 GPU（使用 `—verbose` 运行以获取可用设备列表）。
`—text-driver <driver>`	文本驱动程序（字体、BiDi、整形）。
`—tablet-driver <driver>`	手写板输入驱动程序。
`—headless`	启用无头模式（—display-driver headless —audio-driver Dummy）。适用于服务器和 `—script`。
`—write-movie <file>`	以写入影片（通常以 .avi 或 .png 为扩展名）的方式运行引擎。 `-fixed-fps` 在启用时是强制的，但可以用来改变影片的 FPS。 `disable-vsync` 可以加快影片的写入速度，但会增加交互难度。 `—quit-after` 可以用来指定要写入的帧数。

显示选项

命令	描述
`-f`, `—fullscreen`	尝试使用全屏模式.
`-m`, `—maximized`	尝试最大化窗口。
`-w`, `—windowed`	使用窗口模式。
`-t`, `—always-on-top`	请求一个置顶窗口.
`—resolution <W>x<H>`	窗口分辨率。
`—position <X>,<Y>`	指定屏幕位置.
`—screen <N>`	请求窗口分辨率。
`—single-window`	使用单个窗口（没有单独的子窗口）。
`—xr-mode <mode>`	选择 XR 模式（”默认”、”关闭”、”打开”）。

调试选项

命令	描述
`-d`, `—debug`	调试(本地 stdout 调试器)。
`-b`, `—breakpoints`	断点列表，形式为英文逗号分隔的“源文件::行号”，不带空格（空格用 `%20` 代替）。
`—profiling`	在脚本调试器中启用分析。
`—gpu-profile`	显示帧渲染过程中耗时最长任务的 GPU 分析。
`—gpu-validation`	启用图形 API 验证层以进行调试。
`—gpu-abort`	在 GPU 出错时终止（通常是验证层错误），这有助于在系统冻结时发现问题。
`—remote-debug <uri>`	远程调试（ `<protocol>://<host/IP>[:<port>]`，例如 `tcp://127.0.0.1:6007`）。
`—single-threaded-scene`	场景树以单线程模式运行。子线程组被禁用，在主线程上运行。
`—debug-collisions`	运行场景时显示碰撞框形状。
`—debug-paths`	运行场景时显示路径。
`—debug-navigation`	运行场景时显示多边形导航。
`—debug-avoidance`	当运行场景时显示多边形导航.
`—debug-stringnames`	当引擎退出时，将所有 StringName 分配打印到 stdout。
`—frame-delay <ms>`	模拟高 CPU 负载（每帧延迟 <ms> 毫秒）。
`—time-scale <缩放>`	强制时间缩放（值越大速度越快，1.0是正常速度）。
`—disable-vsync`	即使在项目设置中启用，也会强制禁用垂直同步。不会覆盖驱动程序级的 V-Sync 执行。
`—disable-render-loop`	禁用渲染循环，以便仅在从脚本显式调用时才进行渲染。
`—disable-crash-handler`	当平台代码支持时，禁用崩溃处理程序。
`—fixed-fps <帧率>`	每秒强制固定数量的帧。此设置禁用实时同步。
`—delta-smoothing <启用>`	启用或禁用帧间隔平滑（”启用”、”禁用”）。
`—print-fps`	将每秒帧数打印到标准输出上。

单独的工具

命令	描述
`-s`, `—script <script>`	运行脚本。
`—check-only`	仅解析错误并退出（与 `—script` 一起使用）。
`—import`	Starts the editor, waits for any resources to be imported, and then quits. Implies `—editor` and `—quit`.
`—export-release <preset> <path>`	Export the project using the given preset and matching release template. The preset name should match one defined in export_presets.cfg. `<path>` should be absolute or relative to the project directory, and include the filename for the binary (e.g. ‘builds/game.exe’). The target directory should exist. Implies `—import`.
`—export-debug <preset> <path>`	Like `—export-release`, but use debug template. Implies `—import`.
`—export-pack <预设> <路径>`	Like `—export-release`, but only export the game pack for the given preset. The `<path>` extension determines whether it will be in PCK or ZIP format. Implies `—import`.
`—convert-3to4 [<最大文件kb值>] [<最大行数>]`	将项目从 Godot 3.x 转换到 Godot 4.x。
`—validate-conversion-3to4 [<最大文件kb值>] [<最大行数>]`	显示把项目从 Godot 3.x 转换到 Godot 4.x 时将重命名哪些元素。
`—doctool [<path>]`	将引擎 API 参考以 XML 格式转储到给定的 `<path>` 中，如果路径已有文件则进行合并。
`—no-docbase`	禁止转储基本类型（与 `—doctool` 一起使用）。
`—gdscript-docs <路径>`	不转储引擎 API，而是从 <路径> 找到 GDScript 文件（与 `—doctool` 一起使用）的内联文档生成 API 引用。
`—build-solutions`	构建脚本解决方案（例如 C# 项目）。隐含 `—editor` 并需要一个有效的项目来编辑。
`—dump-gdextension-interface`	在当前文件夹下生成 GDExtension 头文件 “gdnative_interface.h”。该文件是实现 GDExtension 所需的基础文件。
`—dump-extension-api`	在当前文件夹中生成 GDExtension 绑定的 Godot API ，其名为“extension_api.json” 的JSON 转储。
`—validate-extension-api <路径>`	验证从上一版本引擎转储（使用上述选项）的扩展 API 文件，以确保 API 的兼容性。如果检测到不兼容或错误，返回代码将为非零。
`—benchmark`	对运行时间进行基准测试，并将其打印到控制台。
`—benchmark-file <路径>`	对运行时间进行基准测试，并以 JSON 格式保存到指定文件。路径应为绝对路径。

路径

建议将 Godot 编辑器的二进制文件放在 PATH 环境变量中，这样就可以通过在任何地方键入 godot 来轻松地执行。在 Linux 上，就可以将 Godot 二进制文件放在 /usr/local/bin 中，请确保文件名为 godot（注意大小写）。

要在 Windows 或 macOS 上轻松实现这一目标，可以使用 Scoop（在 Windows 上）或 Homebrew（在 macOS 上）安装 Godot。这将自动在 PATH 中提供已安装的 Godot 副本：

WindowsmacOS

# 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二进制文件的位置以及当前的工作目录, 你可能需要设置项目的路径, 以下任何命令才能正常工作.

在运行编辑器时，这可以通过将项目的 project.godot 文件路径作为第一个参数来完成, 如下所示:

godot path_to_your_project/project.godot [other] [commands] [and] [args]

对于所有的指令，这可以通过使用 --path 参数来完成:

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

当从你的项目都子目录启动时，使用 --upwards 参数使 Godot 可以通过递归搜索父目录来自动地找到 project.godot 文件。

举个例子，当你的工作目录在相同的路径下时，运行一个嵌套在子目录中场景（如下所述）的命令可能看起来像这样：

godot --upwards nested_scene.tscn

创建一个项目

要通过命令行创建项目，可以将 shell 导航至所需位置并创建 project.godot 文件。

mkdir newgame
cd newgame
touch project.godot

现在可以使用Godot打开该项目.

运行编辑器

通过使用 -e 参数启动 Godot 来运行编辑器。必须在项目目录内，或按照前文所述的方法设置项目路径，才能完成此操作，否则该命令将被忽略并显示项目管理器。

godot -e

在传入 project.godot 文件的完整路径时，参数 -e 可以被省略。

如果已经创建并保存了场景, 则可以稍后以该场景作为参数运行相同的代码来对其进行编辑.

godot -e scene.tscn

删除一个场景

Godot对你的文件系统非常友好，不会创建额外的元数据文件。你可以使用 rm 来删除场景文件，但是在这之前需要确定该场景被引用的情况，否则再打开该项目时会抛出错误。

rm scene.tscn

运行游戏

要运行游戏，只需按前述方法在项目目录中或带项目路径执行 Godot 即可。

godot

请注意，传入 project.godot 文件将总是运行编辑器，而不会运行游戏。

当需要测试特定场景时, 将该场景传递给命令行.

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