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.

See the stable version of this documentation page instead.

命令行教程

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

备注

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

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

命令行参考

Legend

• Available in editor builds, debug export templates and release export templates.

• Available in editor builds and debug export templates only.

• Only available in editor builds.

Note that unknown command line arguments have no effect whatsoever. The engine will not warn you when using a command line argument that doesn't exist with a given build type.

常规选项

命令	描述
-h, --help	Display the list of command line options.
--version	Display the version string.
-v, --verbose	Use verbose stdout mode.
-q, --quiet	Quiet mode, silences stdout messages. Errors are still displayed.

运行选项

命令	描述
--, ++	Separator for user-provided arguments. Following arguments are not used by the engine, but can be read from OS.get_cmdline_user_args().
-e, --editor	Start the editor instead of running the scene.
-p, --project-manager	Start the Project Manager, even if a project is auto-detected.
--debug-server <uri>	Start the editor debug server (<protocol>://<host/IP>[:<port>], e.g. tcp://127.0.0.1:6007)
--quit	Quit after the first iteration.
--quit-after	Quit after the given number of iterations. Set to 0 to disable.
-l, --language <locale>	Use a specific locale. <locale> follows the format language_Script_COUNTRY_VARIANT where language is a 2 or 3-letter language code in lowercase and the rest is optional. See Locale codes for more details.
--path <目录>	Path to a project (<directory> must contain a 'project.godot' file).
-u, --upwards	Scan folders upwards for 'project.godot' file.
--main-pack <file>	Path to a pack (.pck) file to load.
--render-thread <模式>	Render thread mode ('unsafe', 'safe', 'separate'). See Thread Model for more details.
--remote-fs <地址>	Remote filesystem (<host/IP>[:<port>] address).
--remote-fs-password <password>	Password for remote filesystem.
--audio-driver <驱动>	Audio driver. Use --help first to display the list of available drivers.
--display-driver <driver>	Display driver (and rendering driver). Use --help first to display the list of available drivers.
--rendering-method <renderer>	Renderer name. Requires driver support.
--rendering-driver <driver>	Rendering driver (depends on display driver). Use --help first to display the list of available drivers.
--gpu-index <device_index>	Use a specific GPU (run with --verbose to get available device list).
--text-driver <driver>	Text driver (Fonts, BiDi, shaping).
--tablet-driver <driver>	Pen tablet input driver.
--headless	Enable headless mode (--display-driver headless --audio-driver Dummy). Useful for servers and with --script.
--write-movie <file>	Run the engine in a way that a movie is written (usually with .avi or .png extension). --fixed-fps is forced when enabled, but can be used to change movie FPS. --disable-vsync can speed up movie writing but makes interaction more difficult. --quit-after can be used to specify the number of frames to write.

显示选项

命令	描述
-f, --fullscreen	Request fullscreen mode.
-m, --maximized	Request a maximized window.
-w, --windowed	Request windowed mode.
-t, --always-on-top	Request an always-on-top window.
--resolution <W>x<H>	Request window resolution.
--position <X>,<Y>	Request window position.
--screen <N>	Request window screen.
--single-window	Use a single window (no separate subwindows).
--xr-mode <mode>	Select XR mode ('default', 'off', 'on').

调试选项

命令	描述
-d, --debug	Debug (local stdout debugger).
-b, --breakpoints	Breakpoint list as source::line comma-separated pairs, no spaces (use %20 instead).
--profiling	Enable profiling in the script debugger.
--gpu-profile	Show a GPU profile of the tasks that took the most time during frame rendering.
--gpu-validation	Enable graphics API validation layers for debugging.
--gpu-abort	Abort on GPU errors (usually validation layer errors), may help see the problem if your system freezes.
--remote-debug <uri>	Remote debug (<protocol>://<host/IP>[:<port>], e.g. tcp://127.0.0.1:6007).
--single-threaded-scene	Scene tree runs in single-threaded mode. Sub-thread groups are disabled and run on the main thread.
--debug-collisions	Show collision shapes when running the scene.
--debug-paths	Show path lines when running the scene.
--debug-navigation	Show navigation polygons when running the scene.
--debug-avoidance	Show navigation avoidance debug visuals when running the scene.
--debug-stringnames	Print all StringName allocations to stdout when the engine quits.
--frame-delay <ms>	Simulate high CPU load (delay each frame by <ms> milliseconds).
--time-scale <缩放>	Force time scale (higher values are faster, 1.0 is normal speed).
--disable-vsync	Forces disabling of vertical synchronization, even if enabled in the project settings. Does not override driver-level V-Sync enforcement.
--disable-render-loop	Disable render loop so rendering only occurs when called explicitly from script.
--disable-crash-handler	Disable crash handler when supported by the platform code.
--fixed-fps <帧率>	Force a fixed number of frames per second. This setting disables real-time synchronization.
--delta-smoothing <enable>	Enable or disable frame delta smoothing ('enable', 'disable').
--print-fps	Print the frames per second to the stdout.

单独的工具

命令	描述
-s, --script <script>	Run a script.
--check-only	Only parse for errors and quit (use with --script).
--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.
--export-debug <preset> <path>	Like --export-release, but use debug template.
--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.
--convert-3to4 [<max_file_kb>] [<max_line_size>]	Convert project from Godot 3.x to Godot 4.x.
--validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]	Show what elements will be renamed when converting project from Godot 3.x to Godot 4.x.
--doctool [<path>]	Dump the engine API reference to the given <path> in XML format, merging if existing files are found.
--no-docbase	Disallow dumping the base types (used with --doctool).
--gdscript-docs <path>	Rather than dumping the engine API, generate API reference from the inline documentation in the GDScript files found in <path> (used with --doctool).
--build-solutions	Build the scripting solutions (e.g. for C# projects). Implies --editor and requires a valid project to edit.
--dump-gdextension-interface	Generate GDExtension header file 'gdnative_interface.h' in the current folder. This file is the base file required to implement a GDExtension.
--dump-extension-api	Generate JSON dump of the Godot API for GDExtension bindings named 'extension_api.json' in the current folder.
--validate-extension-api <path>	Validate an extension API file dumped (with the option above) from a previous version of the engine to ensure API compatibility. If incompatibilities or errors are detected, the return code will be non-zero.
--benchmark	Benchmark the run time and print it to console.
--benchmark-file <path>	Benchmark the run time and save it to a given file in JSON format. The path should be absolute.

路径

It is recommended to place your Godot editor binary in your PATH environment variable, so it can be executed easily from any place by typing godot. You can do so on Linux by placing the Godot binary in /usr/local/bin and making sure it is called godot (case-sensitive).

To achieve this on Windows or macOS easily, you can install Godot using Scoop (on Windows) or Homebrew (on macOS). This will automatically make the copy of Godot installed available in the PATH:

WindowsmacOS

# 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

创建一个项目

Creating a project from the command line can be done by navigating the shell to the desired place and making a project.godot file.

mkdir newgame
cd newgame
touch project.godot

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

运行编辑器

Running the editor is done by executing Godot with the -e flag. This must be done from within the project directory or a subdirectory, otherwise the command is ignored and the Project Manager appears.

godot -e

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

godot -e scene.tscn

删除一个场景

Godot is friends with your filesystem and will not create extra metadata files. Use rm to erase a scene file. Make sure nothing references that scene. Otherwise, an error will be thrown upon opening the project.

rm scene.tscn

运行游戏

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

godot

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

godot scene.tscn

调试

Catching errors in the command line can be a difficult task because they scroll quickly. For this, a command line debugger is provided by adding -d. It works for running either the game or a single scene.

godot -d

godot -d scene.tscn

导出

Exporting the project from the command line is also supported. This is especially useful for continuous integration setups.

备注

Using the --headless command line argument is required on platforms that do not have GPU access (such as continuous integration). On platforms with GPU access, --headless prevents a window from spawning while the project is exporting.

# `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"), 必须用引号引起来.

To export a debug version of the game, use the --export-debug switch instead of --export-release. Their parameters and usage are the same.

To export only a PCK file, use the --export-pack option followed by the preset name and output path, with the file extension, instead of --export-release or --export-debug. The output path extension determines the package's format, either PCK or ZIP.

警告

When specifying a relative path as the path for --export-release, --export-debug or --export-pack, the path will be relative to the directory containing the project.godot file, not relative to the current working directory.

运行脚本

It is possible to run a .gd script from the command line. This feature is especially useful in large projects, e.g. for batch conversion of assets or custom import/export.

该脚本必须继承自 SceneTree 或 MainLoop。

Here is an example sayhello.gd, showing how it works:

#!/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