Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

命令行教程

一些开发人员喜欢广泛使用命令行。Godot 被设计为对他们友好，因此本文介绍了完全通过命令行工作的方法。由于引擎几乎不依赖外部库，初始化时间非常快，非常适合这种工作流程。

备注

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

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

命令行参考

图例说明

• 在编辑器构建版本、调试导出模板和发布导出模板中可用。

• 仅在编辑器构建版本和调试导出模板中可用。

• 仅在编辑器构建版本和在编译时设置了 disable_path_overrides=false 的导出模板中可用。

• 仅在编辑器构建版本中可用。

请注意，未知的命令行参数没有任何作用。当使用给定构建类型不存在的命令行参数时，引擎不会发出警告。

常规选项

命令	描述
-h, --help	显示命令行选项列表。
--version	显示版本字符串。
-v, --verbose	使用详细标准输出模式。
-q, --quiet	安静模式，静默标准输出的信息，但错误信息仍会显示。
--no-header	启动时不打印引擎版本和渲染方法的标题信息。

运行选项

命令	描述
--, ++	用户提供参数时使用的分隔符。引擎不会使用这些参数，但可以通过 OS.get_cmdline_user_args() 读取到。
-e, --editor	启动编辑器而不是运行场景。
-p, --project-manager	即使已经自动检测到项目，仍然启动项目管理器。
--recovery-mode	在恢复模式下启动编辑器，该模式将禁用可能导致启动崩溃的功能，如工具脚本、编辑器插件、GDExtension 扩展等。
--debug-server <uri>	启动编辑器调试服务器（<协议>://<主机/IP>[:<端口>]，例如 tcp://127.0.0.1:6007）
--dap-port <port>	为 GDScript 调试适配器协议使用指定端口。推荐端口范围为 [1024, 49151]。
--lsp-port <port>	为 GDScript 语言服务器协议使用指定端口。推荐端口范围为 [1024, 49151]。
--quit	第一次迭代后退出。
--quit-after	指定迭代次数后退出。设置为 0 则禁用。
-l <locale>, --language <locale>	使用指定的区域设置。<locale> 格式为 language_Script_COUNTRY_VARIANT，其中 language 为小写的 2 或 3 个字母组成的语言代码，其余为可选项。详情见 区域设置代码。
--path <directory>	项目的路径（<directory> 必须包含“project.godot”文件）。
--scene <path>	项目中应启动的场景的路径或 UID。
--main-pack <file>	要加载的包（.pck）文件的路径。
--render-thread <mode>	渲染线程模式（“unsafe”、“safe”、“separate”）。详见线程模型。
--remote-fs <address>	远程文件系统（<主机名/IP>[:<端口号>] 地址）。
--remote-fs-password <password>	远程文件系统的密码。
--audio-driver <driver>	音频驱动。可先使用 --help 显示可用驱动列表。
--display-driver <driver>	显示驱动（及渲染驱动）。可先使用 --help 显示可用驱动列表。
--audio-output-latency <ms>	以毫秒为单位覆盖音频输出延迟（默认为 15 毫秒）。数值越低声音播放响应越快，但会增加 CPU 占用，若 CPU 性能不足可能导致音频爆音。
--rendering-method <renderer>	渲染器名称。可选的有效值为 forward_plus 、mobile 和 gl_compatibility。该设置需要驱动程序的底层支持。
--rendering-driver <driver>	渲染驱动（依赖于显示驱动）。可先使用 --help 查看可用驱动列表。
--gpu-index <device_index>	指定使用某一块特定的 GPU（该功能仅在 Forward+/Mobile 渲染器下可用；请在启动时加上 --verbose 参数来获取可用的设备列表）。
--text-driver <driver>	文本驱动程序（字体、BiDi、塑形）。
--tablet-driver <driver>	手写板输入驱动程序。
--headless	启用无头模式（--display-driver headless --audio-driver Dummy）。适用于服务器和 --script。
--log-file	将输出/错误日志写入指定路径（替代项目定义的默认位置）。<file> 路径需为绝对路径或相对于项目目录的路径。
--write-movie <file>	以写入影片（通常以 .avi 或 .png 为扩展名）的方式运行引擎。启用时 --fixed-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 模式（“default”、“off”、“on”）。
--wid <window_id>	请求附加到窗口。
--accessibility <mode>	选择无障碍模式 [“auto”（当屏幕阅读器运行时，默认值）、“always”、“disabled”]。

调试选项

命令	描述
-d, --debug	调试（本地标准输出调试器）。
-b, --breakpoints	断点列表，形式为英文逗号分隔的“源文件::行号”，不带空格（空格用 %20 代替）。
--ignore-error-breaks	调试器连接时禁用错误断点发送。
--profiling	在脚本调试器中启用分析功能。
--gpu-profile	显示帧渲染过程中耗时最长任务的 GPU 分析。
--gpu-validation	启用图形 API 验证层进行调试。
--gpu-abort	在 GPU 出错时终止（通常是验证层错误），这有助于在系统冻结时发现问题。
--generate-spirv-debug-info	生成 SPIR-V 调试信息（支持通过 RenderDoc 进行着色器源码级调试）。
--extra-gpu-memory-tracking	启用额外内存追踪（参见 RenderingDevice.get_driver_and_device_memory_report() 及相关方法的类参考）。当前仅 Vulkan 后端支持。由于驱动或 Vulkan 加载器的潜在缺陷，启用此功能可能导致部分系统崩溃。详见 https://github.com/godotengine/godot/issues/95967
--accurate-breadcrumbs	强制在 breadcrumbs 间插入屏障（用于定位导致 GPU 重置的具体指令，当前仅 Vulkan 实现）。
--remote-debug <uri>	远程调试（<协议>://<主机/IP>[:<端口>]，例如 tcp://127.0.0.1:6007）。
--single-threaded-scene	场景树以单线程模式运行。子线程组被禁用，在主线程上运行。
--debug-collisions	运行场景时显示碰撞体形状。
--debug-paths	运行场景时显示路径线条。
--debug-navigation	运行场景时显示导航多边形。
--debug-avoidance	运行场景时显示导航规避调试视图。
--debug-stringnames	当引擎退出时，将所有 StringName 分配打印到标准输出。
--debug-canvas-item-redraw	每当画布项请求重绘时，显示一个矩形（有助于排查低处理器模式下的问题）。
--max-fps <fps>	设置每秒渲染的最大帧数（可用于限制功耗）。值为 0 表示帧率无限制。
--frame-delay <ms>	模拟高 CPU 负载（将每帧延迟 <ms> 毫秒）。请勿将其用作帧率限制器；应使用 --max-fps 替代。
--time-scale <scale>	强制时间缩放（值越大速度越快，1.0 是正常速度）。
--disable-vsync	强制禁用垂直同步，即使项目设置中已启用。但不会覆盖驱动程序级别的垂直同步强制设置。
--disable-render-loop	禁用渲染循环，以便仅在从脚本显式调用时才进行渲染。
--disable-crash-handler	当平台代码支持时，禁用崩溃处理程序。
--fixed-fps <fps>	强制设定固定的每秒帧数。此设置会禁用实时同步功能。
--delta-smoothing <enable>	启用或禁用帧间隔平滑（“enable”、“disable”）。
--print-fps	将每秒帧数打印到标准输出。
--editor-pseudolocalization	为编辑器和项目管理器启用伪本地化。

独立工具

命令	描述
-s, --script <script>	运行脚本。<script> 必须是相对于项目的资源路径（myscript.gd 会被解释为 res://myscript.gd）或绝对文件系统路径（例如 Windows 上的 C:/tmp/myscript.gd）。
--main-loop <main_loop_name>	运行由全局类名指定的主循环。
--check-only	仅进行错误解析并退出（需与 --script 参数一同使用）。
--import	启动编辑器，等待加载一切资源，然后退出。隐含 --editor 及 --quit。
--export-release <preset> <path>	使用指定的预设和输出路径以发布模式导出项目。预设名称应与“export_presets.cfg”中定义的名称一致。<path> 应为绝对路径或相对于项目目录的路径，且需包含输出可执行文件的文件名（例如 “builds/game.exe”）。目标目录必须已存在。
--export-debug <preset> <path>	与 --export-release 类似，但使用调试模板。隐含 --import。
--export-pack <preset> <path>	与 --export-release 类似，但只会以预设参数导出游戏包。<path> 的扩展名决定它是 PCK 还是 ZIP 格式。隐含 --import。
--export-patch <preset> <path>	仅导出已更改文件的包。其他注意事项请参见 --export-pack 说明。
--patches <paths>	与 --export-patch 配合使用的补丁列表。该列表以逗号分隔。
--install-android-build-template	安装 Android 构建模板。通常配合 --export-release 或 --export-debug 参数一起使用。
--convert-3to4 [<max_file_kb>] [<max_line_size>]	将项目从 Godot 3.x 转换到 Godot 4.x。
--validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]	显示把项目从 Godot 3.x 转换到 Godot 4.x 时将重命名哪些元素。
--doctool [<path>]	将引擎 API 参考以 XML 格式转储到给定的 <path> 中，如果路径已有文件则进行合并。
--no-docbase	禁止转储基本类型（与 --doctool 一起使用）。
--gdextension-docs	不转储引擎 API，而是根据当前项目加载的所有 GDExtensions 生成 API 参考（与 --doctool 一起使用）。
--gdscript-docs <path>	不转储引擎 API，而是根据 <path> 内的 GDScript 文件的内联文档生成 API 参考（与 --doctool 一起使用）。
--build-solutions	构建脚本解决方案（例如 C# 项目）。隐含 --editor 并需要一个有效的项目来编辑。
--dump-gdextension-interface	在当前文件夹中生成 GDExtension 头文件 “gdnative_interface.h”。该文件是实现 GDExtension 所需的基础文件。
--dump-gdextension-interface-json	在当前文件夹中生成 GDExtension 接口的 JSON 转储，其名为“gdextension_interface.json” 。
--dump-extension-api	在当前文件夹中生成 GDExtension 绑定的 Godot API 的 JSON 转储，其名为“extension_api.json” 。
--dump-extension-api-with-docs	和前一个选项一样，在当前文件夹中生成 Godot API 的 JSON 转储，但是包括文档。
--validate-extension-api <path>	验证从上一版本引擎转储（使用上述选项）的扩展 API 文件，以确保 API 的兼容性。如果检测到不兼容或错误，返回代码将为非零。
--benchmark	对运行时间进行基准测试，并将其打印到控制台。
--benchmark-file <path>	对运行时间进行基准测试，并以 JSON 格式保存到指定文件。路径应为绝对路径。
--test [--help]	运行 单元测试（需要用 tests=yes 编译引擎）。使用 --test --help 获取更多信息。

路径

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

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

WindowsmacOS

# Add "Extras" bucket
scoop bucket add extras

# Standard editor:
scoop install godot

# Editor with C# support (will be available as `godot-mono` in `PATH`):
scoop 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-debug。输出路径扩展名决定了包的格式，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）。

脚本路径将被解释为相对于项目的资源路径，这里是 res://sayhello.gd。你也可以使用绝对文件系统路径，这在脚本位于项目目录之外时很有用。

上面 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