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 改名为其他名称,则需相应地编辑这个命令行。

命令行参考

图例解释

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

  • debug 仅适用于编辑器构建和调试导出模板。

  • editor 仅适用于编辑器构建。

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

常规选项

命令

描述

-h, --help

release 显示命令行选项列表。

--version

release 显示版本字符串。

-v, --verbose

release 使用冗长标准输出模式。

-q, --quiet

release 安静模式,静默标准输出的信息。但错误仍然会显示。

运行选项

命令

描述

--, ++

release 用户提供参数时使用的分隔符。引擎不会使用这些参数,但可以通过 OS.get_cmdline_user_args() 读取到。

-e, --editor

editor 启动编辑器而不是运行场景。

-p, --project-manager

editor 即使已经自动检测到项目,仍然启动项目管理器。

--debug-server <uri>

editor 启动编辑器调试服务器( <protocol>://<host/IP>[:<port>],例如, tcp://127.0.0.1:6007

--quit

第一次迭代后退出.

--quit-after

release 指定迭代次数后退出。设置为 0 则禁用。

-l <locale>, --language <locale>

release 使用特定本地语言。 <locale> 格式为 language_Script_COUNTRY_VARIANT,其中 language 为小写的 2 或 3 个字母组成的语言代码,其余为可选项。详情请参见 区域设置代码

--path <目录>

release 项目的路径(<directory> 目录中必须包含一个“project.godot”文件)。

-u, --upwards

release 向上扫描文件夹中的“project.godot”文件。

--main-pack <file>

release 要加载的包(.pck)文件的路径。

--render-thread <模式>

release 渲染线程模式('unsafe'、'safe'、'separate')。详见线程模型

--remote-fs <地址>

release 远程文件系统(FTP 地址)。

--remote-fs-password <password>

release 远程文件系统的密码。

--audio-driver <驱动>

release 音频驱动。使用 --help 来显示可用驱动列表。

--display-driver <driver>

视频驱动。使用 --help 来显示可用驱动列表。

--rendering-method <renderer>

release 渲染器名称。需要驱动程序支持。

--rendering-driver <driver>

视频驱动。使用 --help 来显示可用驱动列表。

--gpu-index <设备索引>

release 使用特定 GPU(使用 --verbose 运行以获取可用设备列表)。

--text-driver <driver>

release 文本驱动程序(字体、BiDi、整形)。

--tablet-driver <driver>

release 手写板输入驱动程序。

--headless

release 启用无头模式(--display-driver headless --audio-driver Dummy)。适用于服务器和 --script

--write-movie <file>

release 以写入影片(通常以 .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

release 使用单个窗口(没有单独的子窗口)。

--xr-mode <mode>

release 选择 XR 模式("默认"、"关闭"、"打开")。

调试选项

命令

描述

-d, --debug

调试(本地 stdout 调试器)。

-b, --breakpoints

release 断点列表,形式为英文逗号分隔的“源文件::行号”,不带空格(空格用 %20 代替)。

--profiling

在脚本调试器中启用分析。

--gpu-profile

release 显示帧渲染过程中耗时最长任务的 GPU 分析。

--gpu-validation

release 启用图形 API 验证层 以进行调试。

--gpu-abort

debug 在 GPU 出错时终止(通常是验证层错误),这有助于在系统冻结时发现问题。

--remote-debug <uri>

release 远程调试( <protocol>://<host/IP>[:<port>],例如 tcp://127.0.0.1:6007)。

--single-threaded-scene

release 场景树以单线程模式运行。子线程组被禁用,在主线程上运行。

--debug-collisions

运行场景时显示碰撞框形状。

--debug-paths

运行场景时显示路径。

--debug-navigation

运行场景时显示多边形导航。

--debug-avoidance

当运行场景时显示多边形导航.

--debug-stringnames

debug 当引擎退出时,将所有 StringName 分配打印到 stdout。

--frame-delay <ms>

release 模拟高 CPU 负载(每帧延迟 <ms> 毫秒)。

--time-scale <缩放>

release 强制时间缩放(值越大速度越快,1.0是正常速度)。

--disable-vsync

release 即使在项目设置中启用,也会强制禁用垂直同步。不会覆盖驱动程序级的 V-Sync 执行。

--disable-render-loop

release 禁用渲染循环,以便仅在从脚本显式调用时才进行渲染。

--disable-crash-handler

release 当平台代码支持时,禁用崩溃处理程序。

--fixed-fps <帧率>

每秒强制固定数量的帧。此设置禁用实时同步。

--delta-smoothing <启用>

release 启用或禁用帧间隔平滑("启用"、"禁用")。

--print-fps

release 将每秒帧数打印到标准输出上。

单独的工具

命令

描述

-s, --script <script>

release 运行脚本。

--check-only

release 仅解析错误并退出(与 --script 一起使用)。

--export-release <preset> <path>

editor 使用给定的预设和匹配的发布模板导出项目。预设名称应与 export_presets.cfg 中定义的名称一致。 <路径> 应为项目目录的绝对或相对路径,并包含二进制文件的文件名(例如 “builds/game.exe”)。并且目标目录应该存在。

--export-debug <preset> <path>

editor--export-release 类似,但使用调试模板。

--export-pack <预设> <路径>

editor--export-release 类似,但只会以预设参数导出游戏包。<path> 的扩展名决定它是 PCK 还是 ZIP 格式。

--convert-3to4 [<最大文件kb值>] [<最大行数>]

editor 将项目从 Godot 3.x 转换到 Godot 4.x。

--validate-conversion-3to4 [<最大文件kb值>] [<最大行数>]

editor 显示把项目从 Godot 3.x 转换到 Godot 4.x 时将重命名哪些元素。

--doctool [<path>]

editor 将引擎 API 参考以 XML 格式转储到给定的 <path> 中,如果路径已有文件则进行合并。

--no-docbase

editor 禁止转储基本类型(与 --doctool 一起使用)。

--gdscript-docs <路径>

editor 不转储引擎 API,而是从 <路径> 找到 GDScript 文件(与 --doctool 一起使用)的内联文档生成 API 引用。

--build-solutions

editor 构建脚本解决方案(例如 C# 项目)。隐含 --editor 并需要一个有效的项目来编辑。

--dump-gdextension-interface

editor 在当前文件夹下生成 GDExtension 头文件 “gdnative_interface.h”。该文件是实现 GDExtension 所需的基础文件。

--dump-extension-api

editor 在当前文件夹中生成 GDExtension 绑定的 Godot API ,其名为“extension_api.json” 的JSON 转储。

--validate-extension-api <路径>

editor 验证从上一版本引擎转储(使用上述选项)的扩展 API 文件,以确保 API 的兼容性。如果检测到不兼容或错误,返回代码将为非零。

--benchmark

editor 对运行时间进行基准测试,并将其打印到控制台。

--benchmark-file <路径>

editor 对运行时间进行基准测试,并以 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

设置项目路径

根据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

创建一个项目

要通过命令行创建项目,可以将 shell 导航至所需位置并创建 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

导出

也支持从命令行导出项目。这对持续集成设置特别有用。

备注

在没有 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 脚本。此功能在大型项目中特别有用,例如,用于资产的批量转换或自定义导入/导出。

该脚本必须继承自 SceneTreeMainLoop

下面的 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