Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

命令行教學

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

備註

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

在 macOS 上，由於 Godot 包含在 .app 包中，它是一個 資料夾，而不是檔，因此運作過程有所不同。要從 macOS 的終端運作 Godot 可執行檔，您必須 cd 到 Godot 應用套裝程式所在的資料夾，然後運作 Godot.app/Contents/MacOS/Godot，並在後面加上相關命令列參數。如果你把應用包從 Godot 改名為其他名稱，則需相應地編輯這個命令列。

命令列參照說明

圖例解釋

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

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

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

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

通用選項

Command

說明

-h, --help, /?

顯示所有可用的命令列選項。

--version

顯示版本資訊。

-v, --verbose

使用詳細標準輸出 (Stdout) 模式。

-q, --quit

靜默模式，不輸出任何標準輸出 (Stdout) 訊息。仍會顯示錯誤。

執行選項

Command

說明

-q, --quit

|release|使用者提供的參數的分隔符號。以下參數不被引擎使用，但可以從“OS.get_cmdline_user_args()”讀取。

-e, --editor

|editor|啟動編輯器而不是運作場景。

-p, --project-manager

|editor|即使自動偵測到專案，也要啟動專案管理器。

--video-driver <driver>

|editor|啟動編輯器除錯伺服器（<protocol>://<host/IP>[:<port>]，例如``tcp://127.0.0.1:6007``）'

--quiet

首次迭代後退出。

--quiet

|release|在給定的迭代次數後退出。設定為 0 以停用。

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

|release|使用特定的區域設定。 <locale> 遵循格式 language_Script_COUNTRY_VARIANT ，其中 language 是小寫的 2 或 3 個字母的語言程式碼，其餘部分是可選的。請參閱 本地坐標 以了解更多詳細資訊。

--path <directory>

專案路徑（<directory> 內必須包含一個「project.godot」檔案）。

-u, --upwards

向上層資料夾搜尋「project.godot」檔案。

--main-pack <file>

欲載入之 Pack (.pck) 檔。

--render-thread <mode>

算繪器執行緒模式（「unsafe」、「safe」、「separate」）。詳細請參考 執行緒模型 。

--remote-fs <address>

遠端檔案系統（ <host/IP>[:<port>] 位址）。

--remote-fs <address>

|release|遠端檔案系統的密碼。

--audio-driver <driver>

音效驅動程式。先指定 --help 以顯示所有可用的驅動程式。

--audio-driver <driver>

視訊驅動程式。先指定 --help 以顯示所有可用的驅動程式。

--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”很有用。

--main-pack <file>

|release|以電影編寫的方式運作引擎（通常帶有 .avi 或 .png 副檔名）。 --fixed-fps 在啟用時被強制，但可用於更改電影 FPS。 --disable-vsync 可以加快電影寫入速度，但會使互動變得更加困難。 “--quit-after” 可用來指定要寫入的訊框數。

顯示選項

Command

說明

-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 模式（“預設”、“關閉”、“開啟”）。

偵錯選項

Command

說明

-d, --debug

除錯（本機標準輸出 (Stdout) 除錯工具）。

-b, --breakpoints

以 source::line，逗號分隔配對，無空白（顯示 %%20）來列出中斷點。

--profiling

在腳本除錯工具中啟用分析。

--profiling

|release|顯示影格算繪期間花費最多時間的工作的 GPU 設定檔。

--debug-navigation

|release|啟用圖形 API 驗證層 進行除錯。

--quiet

|debug|在 GPU 錯誤（通常是驗證層錯誤）時中止，可能有助於在系統凍結時發現問題。

--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 分配列印到標準輸出。

--frame-delay <ms>

模擬 CPU 高負載（每影格延遲 <ms> 毫秒）。

--time-scale <scale>

強制時間縮放（值越早則越快，1.0 為正常速度）。

--disable-crash-handler

|release|強制停用垂直同步，即使在專案設定中啟用也是如此。不會覆蓋驅動程式層級的垂直同步強制。

--disable-render-loop

禁用算繪循環，將只在腳本內明確呼叫時才進行算繪。

--disable-crash-handler

若平台程式碼支援，禁用 Crash Handler。

--fixed-fps <fps>

強制固定數 FPS。該設定將禁用即時同步。

--delta-smoothing <啟用>

|release|啟用或停用影格差異量平滑（「啟用」、「停用」）。

--print-fps

在標準輸出上印出 FPS。

獨立工具

Command

說明

-s <script>, --script <script>

執行腳本。

--check-only

僅解析錯誤並退出（與 --script 一起使用）。

--export-pack <preset> <path>

|editor|使用給定的預設和配對的發布模板匯出專案。預設名稱應與export_presets.cfg 中定義的名稱相符。 <path> 應該是絕對路徑或相對於專案目錄的路徑，並包含二進位檔案的檔案名稱（例如「builds/game.exe」）。目標目錄應該存在。

--export-pack <preset> <path>

|editor|類似於“--export-release”，但使用除錯模板。

--export-pack <preset> <path>

與 --export 相同，但會使用給定的預設設定來匯出遊戲打包。會依照 <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>

將引擎的 API 參照文件以 XML 格式傾印至指定的 <path> 路徑，若檔案存在則合併（必須啟用 工具 ）。

--no-docbase

|editor|禁止轉儲基本型別（與“--doctool”一起使用）。

--doctool <path>

|editor|不是轉儲引擎 API，而是從 <path> 找到的 GDScript 檔案中的行內檔案產生 API 引用（與「--doctool」一起使用）。

--build-solutions

|editor|建置腳本解決方案（例如，針對 C# 專案）。暗示“--editor”並且需要一個有效的專案來編輯。

--dump-gdextension-interface

|editor|在目前資料夾中產生GDExtension頭檔'gdnative_interface.h'。該檔案是實作 GDExtension 所需的基本檔案。

--gdnative-generate-json-api

|editor|在目前資料夾中為名為「extension_api.json」的 GDExtension 綁定產生 Godot API 的 JSON 轉儲。

--gdnative-generate-json-api

|editor|驗證從先前版本的引擎轉儲的擴充 API 檔案（使用上面的選項）以確保 API 相容性。如果偵測到不相容或錯誤，回傳程式碼將不為零。

--benchmark

|editor|對運作時間進行基準測試並將其列印到控制台。

--doctool <path>

|editor|對運作時間進行基準測試並將其以 JSON 格式儲存到給定檔案中。該路徑應該是絕對的。

路徑

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

要在 Windows 或 macOS 上輕鬆實作這一目標，可以使用 Scoop <https://scoop.sh>`__（在 Windows 上）或 `Homebrew <https://brew.sh>`__（在 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 的二進位執行檔放置位置以及目前工作目錄的不同，可能需要為下列指令設定專案路徑才可正確執行。

When running the editor, this can be done by giving the path to the project.godot file of your project as either the first argument, like this:

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

For all commands, this can be done by using the --path argument:

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

When starting from a subdirectory of your project, use the --upwards argument for Godot to automatically find the project.godot file by recursively searching the parent directories.

For example, running a scene (as explained below) nested in a subdirectory might look like this when your working directory is in the same path:

godot --upwards nested_scene.tscn

建立專案

可以通過將 Shell 導覽至欲建立專案的位置並建立 project.godot 檔案來在命令列中建立專案。

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 by setting the project path as explained above, otherwise the command is ignored and the Project Manager appears.

godot -e

When passing in the full path to the project.godot file, the -e flag may be omitted.

若已有建立並保存場景，則之後可使用相同的指令並以該場景作為參數來編輯。

godot -e scene.tscn

清除場景

Godot 對檔案系統友善，且不會建立額外的後設資料檔案。可使用 rm 來清除專案檔案。請確保沒有其他東西參照到該場景，否則開啟時會拋出錯誤。

rm scene.tscn

執行遊戲

To run the game, execute Godot within the project directory or with the project path as explained above.

godot

Note that passing in the project.godot file will always run the editor instead of running the game.

若需要測試特定的場景，則可將該場景傳入命令行。

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 ）。

在上方 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