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 的二進位執行檔放置位置以及目前工作目錄的不同,可能需要為下列指令設定專案路徑才可正確執行。

可以通過為第一個參數指定專案 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

匯出

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 腳本。對於大型專案來說特別有用,如大量的素材轉換或自定匯入/匯出。

該腳本必須繼承 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 的話,則這行 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