命令列教學

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

備註

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

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

命令列參照說明

圖例解釋

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

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

• |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>	專案路徑（<directory> 內必須包含一個「project.godot」檔案）。
scene <path>	要啟動的專案場景之路徑或 UID 。
-u, --upwards	向上層資料夾搜尋「project.godot」檔案。
--main-pack <file>	欲載入之 Pack (.pck) 檔。
--render-thread <mode>	算繪執行緒模式（「unsafe」、「safe」、「separate」）。詳見 Thread Model 以取得更多資訊。
--remote-fs <address>	遠端檔案系統（ <host/IP>[:<port>] 位址）。
--remote-fs <address>	遠端檔案系統密碼。
--audio-driver <driver>	音效驅動程式。先指定 --help 以顯示所有可用的驅動程式。
--audio-driver <driver>	視訊驅動程式。先指定 --help 以顯示所有可用的驅動程式。
--audio-output-latency <ms>	覆寫音訊輸出延遲（毫秒，預設為 15 ms）。較低的數值可提升回應性，但會增加 CPU 使用率；若 CPU 無法負荷，可能導致聲音破音
--render-thread <mode>	|release|算繪器名稱。需要驅動程式支援。
--audio-driver <driver>	視訊驅動程式。先指定 --help 以顯示所有可用的驅動程式。
--gpu-index <裝置索引>	|release|使用特定的 GPU（使用“--verbose”運作以取得可用裝置列表）。
--video-driver <driver>	|release|文字驅動程式（字形、BiDi、整形）。
--audio-driver <driver>	|release|手寫板輸入驅動程式。
--remote-fs <address>	|release|啟用無頭模式（--display-driver headless --audio-driver Dummy）。對於伺服器和“--script”很有用。
--log-file	將輸出/錯誤日誌寫入指定路徑，而非專案預設位置。<file> 路徑可為絕對路徑或相對於專案目錄的路徑 。
--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>	|release|選擇 XR 模式（“預設”、“關閉”、“開啟”）。
--wid <window_id>	要求將視窗隸屬於指定的父視窗 。
--accessibility <mode>	選擇無障礙模式 ['auto'（當螢幕報讀程式執行時，預設）、'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>	模擬高 CPU 負載（每個影格延遲 <ms> 毫秒）。 請勿用作 FPS 限制器；若要限制請使用 --max-fps。
--time-scale <scale>	強制時間縮放（值越早則越快，1.0 為正常速度）。
--disable-crash-handler	強制停用垂直同步, 即使專案設定中已啟用. 不會覆寫驅動程式層級的垂直同步強制設定.
--disable-render-loop	禁用算繪循環，將只在腳本內明確呼叫時才進行算繪。
--disable-crash-handler	若平台程式碼支援，禁用 Crash Handler。
--fixed-fps <fps>	強制固定數 FPS。該設定將禁用即時同步。
--delta-smoothing <啟用>	啟用或停用幀差平滑化 ('enable', 'disable')。
--print-fps	在標準輸出上印出 FPS。
--editor-pseudolocalization	為編輯器與專案管理員啟用偽本地化。

獨立工具

命令	說明
-s <script>, --script <script>	執行腳本。 <script> 必須是相對於專案的資源路徑 (myscript.gd 將會被解釋為 res://myscript.gd)，或是絕對檔案系統路徑 (例如在 Windows 上為 C:/tmp/myscript.gd)
--main-loop <main_loop_name>	以全域類別名稱執行指定的 MainLoop.
--check-only	僅解析錯誤並退出（與 --script 一起使用）。
--import	啟動編輯器, 等待所有資源匯入完成，然後結束。表示包含 --editor 和 --quit.
--export-pack <preset> <path>	使用指定的預設與輸出路徑，以 release 模式匯出專案。 預設名稱需與 'export_presets.cfg' 中定義的相符。 <path> 應為絕對路徑或相對於專案目錄的路徑，且需包含產出二進位的檔名（例如 'builds/game.exe'）。 目標目錄必須已存在。
--export-pack <preset> <path>	類似 --export-release, 但使用除錯範本. 包含 --import 的效果.
--export-pack <preset> <path>	類似 --export-release, 但僅匯出指定預設的遊戲包. <路徑> 的副檔名決定了格式為 PCK 或 ZIP。隱含 --import.
--export-patch <preset> <path>	只匯出變更過的檔案作為資料包。 其他注意事項請參考 --export-pack 的說明。
--patches <paths>	與 --export-patch 一起使用的補丁列表，以逗號分隔.
--install-android-build-template	安裝 Android 建置範本。 可與 --export-release 或 --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 搭配使用）。
--doctool <path>	不要傾印引擎 API，而是從 <path> 中 GDScript 檔案的內聯文件產生 API 參考（搭配 --doctool 使用）.
--build-solutions	建置腳本解決方案（例如 C# 專案）. 包含 --editor 並需要一個可編輯的有效專案.
--dump-gdextension-interface	在目前資料夾產生 GDExtension 標頭檔 'gdnative_interface.h'. 這個檔案是實作 GDExtension 所需的基礎檔案.
--gdnative-generate-json-api	在目前資料夾產生名為 'extension_api.json' 的 Godot API JSON 傾印, 用於 GDExtension 綁定.
--gdnative-generate-json-api	驗證從舊版引擎傾印（使用上述選項）的擴充功能 API 檔案, 以確保 API 相容性. 如果偵測到不相容或錯誤，回傳碼將為非零.
--benchmark	|editor|對運作時間進行基準測試並將其列印到控制台。
--doctool <path>	|editor|對運作時間進行基準測試並將其以 JSON 格式儲存到給定檔案中。該路徑應該是絕對的。
--test [--help]	執行單元測試。 使用 --test --help 以取得更多資訊。

路徑

建議將 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