命令行教程

一些开发人员喜欢广泛使用命令行.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 文件的路径作为第一个参数给出来完成, 如下所示:

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

或者通过使用 --path 参数:

  1. godot --path path_to_your_project [other] [commands] [and] [args]

例如, 用于导出游戏的完整命令(如下所述)可能如下所示:

  1. godot --path path_to_your_project --export my_export_preset_name game.exe

创建一个项目

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

  1. mkdir newgame
  2. cd newgame
  3. touch project.godot

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

运行编辑器

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

  1. godot -e

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

  1. godot -e scene.tscn

删除一个场景

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

  1. rm scene.tscn

运行游戏

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

  1. godot

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

  1. godot scene.tscn

调试

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

  1. godot -d
  1. godot -d scene.tscn

导出

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

  1. godot --export "Linux/X11" /var/builds/project
  2. 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 是一个简单的用法示例：

  1. #!/usr/bin/env -S godot -s
  2. extends SceneTree
  4. func _init():
  5.     print("Hello!")
  6.     quit()

以及如何运行它：

  1. # Prints "Hello!" to standard output.
  2. godot -s sayhello.gd

如果路径中不存在 project.godot，则假定当前路径为当前工作目录（除非指定了 --path）。

以上 sayhello.gd 的第一行通常被称为 shebang。如果 Godot 二进制文件在您的 PATH 中，名为 godot，则它允许您在现代 Linux 发行版以及 macOS 中按以下方式运行脚本：

  1. # Mark script as executable.
  2. chmod +x sayhello.gd
  3. # Prints "Hello!" to standard output.
  4. ./sayhello.gd

如果上述方法在你当前版本的 Linux 或 macOS 中不起作用，你可以随时让 shebang 直接从它所在的位置运行 Godot：

  1. #!/usr/bin/godot -s