命令行教程¶

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

备注

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

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

命令行参考¶

常规选项

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

运行选项

命令	描述
`-e`, `--editor`	启动编辑器，不运行场景（必须已启用 tools）。
`-p`, `--project-manager`	启动项目管理器, 即使一个项目已经被自动检测到 ( 工具必须处于开启状态).
`-q`, `--quit`	第一次迭代后退出.
`-l <locale>`, `--language <locale>`	使用指定的区域设置（<locale> 是一个两个字母的代码）。详情请参阅区域设置。
`--path <目录>`	项目的路径（<directory> 目录中必须包含一个“project.godot”文件）。
`-u`, `--upwards`	向上扫描文件夹中的“project.godot”文件。
`--main-pack <file>`	要加载的包（.pck）文件的路径。
`--render-thread <模式>`	渲染线程模式('unsafe','safe', 'separate'). 阅读线程模式以获得更多细节.
`--remote-fs <地址>`	远端文件系统 (`<主机名/IP>[:<端口号>]` 地址).
`--audio-driver <驱动>`	音频驱动. 先使用 `--help` 来显示可用的驱动列表.
`--video-driver <驱动>`	视频驱动. 先使用 `--help` 来显示可用的驱动列表.

显示选项

命令	描述
`-f`, `--fullscreen`	请求使用全屏模式.
`-m`, `--maximized`	请求一个最大化了的窗口.
`-w`, `--windowed`	要求窗口模式.
`-t`, `--always-on-top`	请求一个总在最顶的窗口.
`--resolution <W>x<H>`	请求窗口分辨率.
`--position <X>,<Y>`	指定屏幕位置.
`--low-dpi`	强制低解析度模式(仅在macOS 和 Windows 中可用).
`--no-window`	使用不可见窗口运行时，与 `--script` 一起使用，将很有用。

调试选项

备注

调试模式仅仅在编辑器和调试输出模板中起作用(这要求使用 debug 或 release_debug 构建目标, 阅读目标以获得更多信息).

命令	描述
`-d`, `--debug`	调试(本地标准输出调试器).
`-b`, `--breakpoints`	断点列表作为 source::line 逗号分隔对时，没有空格（使用 %%20 代替）。
`--profiling`	在脚本调试器中启用分析.
`--remote-debug <地址>`	远程调试 (`<主机名/IP>:<端口号>` 地址).
`--debug-collisions`	运行场景时显示碰撞框的形状.
`--debug-navigation`	当运行场景时显示多边形导航.
`--frame-delay <ms>`	模拟高 CPU 负载（每帧延迟 <ms> 毫秒）。
`--time-scale <缩放>`	强制时间缩放(值越大, 速度越快,1.0是正常速度).
`--disable-render-loop`	禁用渲染循环, 以便仅在从脚本显式调用时才进行渲染.
`--disable-crash-handler`	当平台代码支持时, 禁用崩溃处理程序.
`--fixed-fps <帧率>`	每秒强制固定数量的帧. 此设置禁用实时同步.
`--print-fps`	打印每秒的帧数到标准输出上.

单独的工具

命令	描述
`-s <script>`, `--script <script>`	运行脚本.
`--check-only`	仅解析错误并退出（与 `--script` 一起使用）。
`--export <平台>`	使用给定的导出平台导出项目. 仅当路径以.pck或.zip结尾时才导出主包(必须启用 tools ).
`--export-debug <平台>`	像 `--export` 一样，但是使用调试模板（必须已启用 tools）。
`--doctool <路径>`	将引擎 API 参考以 XML 格式转储到给定的 <路径> 中，如果发现现有文件则合并（必须已启用 tools）。
`--no-docbase`	禁止转储基本类型(和 `--doctool` 一起使用, 工具必须启用).
`--build-solutions`	构建脚本解决方案(例如用于构建C#项目, 必须启用 tools).
`--gdnative-generate-json-api`	为GDNative绑定生成Godot API的JSON输出(必须启用 tools).
`--test <test>`	运行单元测试. 可以先用 `--help` 显示测试列表.(必须启用 tools).
`--export-pack <预设> <路径>`	像 `--export` 一样，它只会以预设的参数导出游戏包。`<路径>` 决定导出的游戏包文件后缀名为 PCK 或者 ZIP（必须已启用 tools）。

路径¶

建议将Godot二进制文件放在 PATH 环境变量中, 这样可以通过在任何地方键入 godot 来轻松地执行它. 您可以在Linux上通过将Godot二进制文件放在 /usr/local/bin 中, 并确保其名为 godot.

设置项目路径¶

根据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 --path path_to_your_project --export my_export_preset_name game.exe

创建一个项目¶

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

mkdir newgame
cd newgame
touch project.godot

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

运行编辑器¶

运行编辑器是通过用 -e 标志执行Godot来完成的. 必须在项目目录或子目录内完成此操作, 否则该命令将被忽略并显示项目管理器.

godot -e

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

godot -e scene.tscn

删除一个场景¶

Godot对您的文件系统非常友好, 不会创建额外的元数据文件. 只需使用 rm 来删除文件. 确保没有对该场景的引用, 否则在打开时会抛出错误.

rm scene.tscn

运行游戏¶

要运行游戏, 只需在项目目录或子目录中执行 Godot 即可.

godot

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

godot scene.tscn

调试¶

捕捉命令行中的错误可能是一项艰巨的任务, 因为它们一闪而过. 为此, 通过添加 -d 来提供命令行调试器. 它适用于运行游戏或简单的场景.

godot -d

godot -d scene.tscn

导出¶

也支持从命令行导出项目。这对持续集成设置特别有用。无头版本的 Godot（服务器构建，无视频）是理想的选择。

godot --export "Linux/X11" /var/builds/project
godot --export Android /var/builds/project.apk

预设名称必须与项目的 export_presets.cfg 文件中定义的导出预设名称一致. 如果预设名称包含空格或特殊字符(如 "Windows Desktop"), 必须用引号引起来.

要导出游戏的调试版本, 请使用 --export-debug 开关, 而不是 --export. 它们的参数和用法是相同的.

若要仅导出 PCK 文件, 请使用 --export-pack 选项, 而不是 --export, 后跟预设名称和输出路径, 并包含文件扩展名. 输出路径扩展决定包的格式, 即 PCK 或 ZIP.

警告

当指定相对路径作为 --export、--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