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 設計成對這些開發者友善，下面列舉了所有讓你完全在命令列中作業的步驟。由於引擎幾乎不以來外部函式庫，所以啟動時間非常快速，便讓 Godot 也很適合在這種工作流程中使用。

備註

在 Windows 和 Linux 上，您可以通過指定其相對或絕對路徑在終端中運作 Godot 可執行檔。

在 macOS 上，由於 Godot 被封裝在 .app 套件中（它是 資料夾 ，不是單一檔案），流程有所不同。若要從終端機執行 Godot，可先切換（cd）到 Godot 應用程式套件所在的資料夾，然後執行 Godot.app/Contents/MacOS/Godot ，後面再接上命令列參數。若你已將應用程式套件從 Godot 重新命名為其他名稱，請相應調整這行指令。

命令列參照說明

圖例解釋

• |release|可用於編輯器版本、偵錯匯出範本和發布匯出模板。

• |debug|僅在編輯器建置和除錯匯出模板中可用。

• Only available in editor builds, and export templates compiled with disable_path_overrides=false.

• |editor|僅在編輯器版本中可用。

請注意，未知的命令列參數不會產生任何影響。當命令列中使用了不存在的建構型別時，引擎不會發出警告。

通用選項

命令	說明
-h, --help, /?	顯示所有可用的命令列選項。
--version	顯示版本資訊。
-v, --verbose	使用詳細標準輸出 (Stdout) 模式。
-q, --quit	靜默模式，不輸出任何標準輸出 (Stdout) 訊息。仍會顯示錯誤。
--no-header	啟動時不要列印引擎版本與繪圖後端標頭 。

執行選項

命令	說明
-q, --quit	|release|使用者提供的參數的分隔符號。以下參數不被引擎使用，但可以從“OS.get_cmdline_user_args()”讀取。
-e, --editor	|editor|啟動編輯器而不是運作場景。
-p, --project-manager	|editor|即使自動偵測到專案，也要啟動專案管理器。
--recovery-mode	以復原模式啟動編輯器，此模式會停用可能導致啟動當機的功能，例如工具腳本、編輯器外掛、GDExtension 外掛等 。
--video-driver <driver>	|editor|啟動編輯器除錯伺服器（<protocol>://<host/IP>[:<port>]，例如``tcp://127.0.0.1:6007``）'
--dap-port <連接埠>	指定 GDScript Debug Adapter Protocol 使用的連接埠。建議範圍為 [1024, 49151] 。
--lsp-port <連接埠>	指定 GDScript Language Server Protocol 使用的連接埠。建議範圍為 [1024, 49151] 。
--quiet	首次迭代後退出。
--quiet	|release|在給定的迭代次數後退出。設定為 0 以停用。
-l <locale>, --language <locale>	|release|使用特定的區域設定。 <locale> 遵循格式 language_Script_COUNTRY_VARIANT ，其中 language 是小寫的 2 或 3 個字母的語言程式碼，其餘部分是可選的。請參閱 本地坐標 以了解更多詳細資訊。
--path <directory>	Path to a project (<directory> must contain a "project.godot" file).
--scene <path>	Path or UID of a scene in the project that should be started.
--main-pack <file>	Path to a pack (.pck) file to load.
--render-thread <mode>	Render thread mode ("unsafe", "safe", "separate"). See Thread Model for more details.
--remote-fs <address>	遠端檔案系統（ <host/IP>[:<port>] 位址）。
--remote-fs <address>	遠端檔案系統密碼。
--audio-driver <driver>	音效驅動程式。先指定 --help 以顯示所有可用的驅動程式。
--audio-driver <driver>	視訊驅動程式。先指定 --help 以顯示所有可用的驅動程式。
--audio-output-latency <ms>	Override audio output latency in milliseconds (default is 15 ms). Lower values make sound playback more reactive but increase CPU usage, and may result in audio cracking if the CPU can't keep up.
--render-thread <mode>	Renderer name. Valid values are forward_plus, mobile, and gl_compatibility. Requires driver support.
--audio-driver <driver>	視訊驅動程式。先指定 --help 以顯示所有可用的驅動程式。
--gpu-index <裝置索引>	Use a specific GPU (only available on the Forward+/Mobile renderers; run with --verbose to get available device list).
--video-driver <driver>	|release|文字驅動程式（字形、BiDi、整形）。
--audio-driver <driver>	|release|手寫板輸入驅動程式。
--remote-fs <address>	|release|啟用無頭模式（--display-driver headless --audio-driver Dummy）。對於伺服器和“--script”很有用。
--log-file	Write output/error log to the specified path instead of the default location defined by the project. <file> path should be absolute or relative to the project directory.
--main-pack <file>	以電影寫入的方式執行引擎（通常使用 .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>	指定視窗位置。
--frame-delay <ms>	指定視窗解析度。
--no-window	|release|使用單一視窗（沒有單獨的子視窗）。
--render-thread <mode>	Select XR mode ("default", "off", "on").
--wid <window_id>	要求將視窗隸屬於指定的父視窗 。
--accessibility <mode>	Select accessibility mode ['auto" (when screen reader is running, default), "always", "disabled'].

偵錯選項

命令	說明
-d, --debug	除錯（本機標準輸出 (Stdout) 除錯工具）。
-b, --breakpoints	以 source::line，逗號分隔配對，無空白（顯示 %%20）來列出中斷點。
--ignore-error-breaks	若偵錯器已連線，則避免傳送錯誤中斷點 。
--profiling	在腳本除錯工具中啟用分析。
--profiling	|release|顯示影格算繪期間花費最多時間的工作的 GPU 設定檔。
--debug-navigation	|release|啟用圖形 API 驗證層 進行除錯。
--quiet	|debug|在 GPU 錯誤（通常是驗證層錯誤）時中止，可能有助於在系統凍結時發現問題。
--generate-spirv-debug-info	產生 SPIR-V 除錯資訊。可配合 RenderDoc 進行著色器原始碼層級的除錯 。
--extra-gpu-memory-tracking	啟用額外的記憶體追蹤（詳見類別參考中的 RenderingDevice.get_driver_and_device_memory_report() 及相關方法） 。目前僅在 Vulkan 上實作。由於驅動或 Vulkan Loader 的問題，在部分系統上啟用此功能可能導致當機。請參考 https://github.com/godotengine/godot/issues/95967
--accurate-breadcrumbs	在 breadcrumbs 之間強制加入 barrier。 可用於縮小導致 GPU 重置的命令範圍。 目前僅在 Vulkan 上實作。
--remote-debug <address>	|release|遠端偵錯（<協定>://<主機/IP>[:<連接埠>]，例如``tcp://127.0.0.1:6007``）。
--render-thread <mode>	|release|場景樹以單執行緒模式運作。子線程組被禁用並在主線程上運作。
--debug-collisions	執行場景時顯示碰撞區域。
--debug-navigation	執行場景時顯示碰撞區域。
--debug-navigation	執行場景時顯示導覽多邊形。
--debug-navigation	執行場景時顯示導覽多邊形。
--debug-collisions	|debug|當引擎退出時，將所有 StringName 分配列印到標準輸出。
--debug-canvas-item-redraw	每當畫布項目請求重繪時顯示一個矩形 （在低處理器模式下除錯很有用）。
--max-fps <fps>	設定最高每秒影格數（可用於限制耗電）。 數值為 0 代表不限制幀率。
--frame-delay <ms>	Simulate high CPU load (delay each frame by <ms> milliseconds). Do not use as a FPS limiter; use --max-fps instead.
--time-scale <scale>	強制時間縮放（值越早則越快，1.0 為正常速度）。
--disable-crash-handler	強制停用垂直同步, 即使專案設定中已啟用. 不會覆寫驅動程式層級的垂直同步強制設定.
--disable-render-loop	禁用算繪循環，將只在腳本內明確呼叫時才進行算繪。
--disable-crash-handler	若平台程式碼支援，禁用 Crash Handler。
--fixed-fps <fps>	強制固定數 FPS。該設定將禁用即時同步。
--delta-smoothing <啟用>	Enable or disable frame delta smoothing ("enable", "disable").
--print-fps	在標準輸出上印出 FPS。
--editor-pseudolocalization	為編輯器與專案管理員啟用偽本地化。

獨立工具

命令	說明
-s <script>, --script <script>	Run a script. <script> must be a resource path relative to the project (myscript.gd will be interpreted as res://my_script.gd) or an absolute filesystem path (for example, on Windows: C:/tmp/my_script.gd).
--main-loop <main_loop_name>	Run a MainLoop specified by its global class name.
--check-only	Only parse for errors and quit (use with --script).
--import	啟動編輯器, 等待所有資源匯入完成，然後結束。表示包含 --editor 和 --quit.
--export-pack <preset> <path>	Export the project in release mode using the given preset and output path. 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 must exist.
--export-pack <preset> <path>	類似 --export-release, 但使用除錯範本. 包含 --import 的效果.
--export-pack <preset> <path>	類似 --export-release, 但僅匯出指定預設的遊戲包. <路徑> 的副檔名決定了格式為 PCK 或 ZIP。隱含 --import.
--export-patch <preset> <path>	Export pack with changed files only. See --export-pack description for other considerations.
--patches <paths>	List of patches to use with --export-patch. The list is comma-separated.
--install-android-build-template	Install the Android build template. Used in conjunction with --export-release or --export-debug.
--convert-3to4 [<最大檔案kb值>] [<最大行數>]	將專案從 Godot 3.x 轉換為 Godot 4.x。
--validate-conversion-3to4 [<最大檔案kb值>] [<最大行數>]	顯示將專案從 Godot 3.x 轉換到 Godot 4.x 時會重新命名的元素.
--doctool <path>	將引擎 API 參考以 XML 格式傾印至指定的 <path>, 如果找到現有檔案則合併.
--no-docbase	禁止傾印基礎型別（與 --doctool 搭配使用）。
--gdextension-docs	Rather than dumping the engine API, generate API reference from all the GDExtensions loaded in the current project (used with --doctool).
--doctool <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	建置腳本解決方案（例如 C# 專案）. 包含 --editor 並需要一個可編輯的有效專案.
--dump-gdextension-interface	Generate GDExtension header file "gdextension_interface.h" in the current folder. This file is the base file required to implement a GDExtension.
--dump-gdextension-interface-json	Generate a JSON dump of the GDExtension interface named "gdextension_interface.json" in the current folder.
--gdnative-generate-json-api	Generate JSON dump of the Godot API for GDExtension bindings named "extension_api.json" in the current folder.
--dump-extension-api-with-docs	Generate JSON dump of the Godot API like the previous option, but including documentation.
--gdnative-generate-json-api	驗證從舊版引擎傾印（使用上述選項）的擴充功能 API 檔案, 以確保 API 相容性. 如果偵測到不相容或錯誤，回傳碼將為非零.
--benchmark	|editor|對運作時間進行基準測試並將其列印到控制台。
--doctool <path>	|editor|對運作時間進行基準測試並將其以 JSON 格式儲存到給定檔案中。該路徑應該是絕對的。
--test [--help]	Run unit tests (requires compiling the engine with tests=yes). Use --test --help for more information.

路徑

建議將 Godot 二進位執行檔放置於 PATH 環境變數內，這樣在任何地方就只需要輸入 godot 即可執行。在 Linux 中可以將 Godot 二進位執行檔放在 /usr/local/bin 並確保該檔案命名為 godot 。

要在 Windows 或 macOS 上輕鬆實作這一目標，可以使用 Scoop <https://scoop.sh>`__（在 Windows 上）或 `Homebrew <https://brew.sh>`__（在 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

匯出

Godot 亦支援自命令列匯出專案。對於 CI 環境（持續整合, Continuous Integration）設定特別有用。無周邊版本的 Godot （伺服器建置，無視訊功能）亦是最佳選擇。

備註

在沒有 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 。其參數與用法皆相同。

如果只要匯出 PCK 檔案，可以將 --export 改成 --export-pack 選項，然後接上匯出預設設定的名稱與輸出路徑，並加上副檔名。輸出路徑的副檔名是依據套件格式判斷的，必須為 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 ）。

腳本路徑將會被解釋為相對於專案的資源路徑，在這裡為 res://sayhello.gd。 您可以改用絕對檔案系統路徑，如果腳本位於專案目錄外，這會很有用。

在上方 sayhello.gd 範例中的第一行就是我們一般稱為 Shebang 的東西。若 Godot 的二進位執行檔有在 PATH 中，並且名稱為 godot 的話，則這行 Shebang 就能讓腳本在現代 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