命令行教學

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

命令列參照說明

通用選項

指令

說明

-h, --help, /?

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

--version

顯示版本資訊。

-v, --verbose

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

--quiet

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

執行選項

指令

說明

-e, --editor

開啟編輯器而非執行場景(必須啟用 工具 )。

-p, --project-manager

開啟專案管理員,即使已自動偵測到專案(必須啟用 工具 )。

-q, --quit

首次迭代後退出。

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

使用指定的區域代碼(<locale> 為兩個字母的代碼)。詳細請參考 Locales

--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>] 位址)。

--audio-driver <driver>

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

--video-driver <driver>

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

顯示選項

指令

說明

-f, --fullscreen

指定全螢幕模式。

-m, --maximized

指定視窗最大化。

-w, --windowed

指定視窗模式。

-t, --always-on-top

指定永遠顯示於最上層之視窗。

--resolution <W>x<H>

指定視窗解析度。

--position <X>,<Y>

指定視窗位置。

--low-dpi

強制低 DPI 模式(僅限 macOS 與 Windows)。

--no-window

關閉視窗建立(僅限 Windows)。適合與 --script 一起使用。

偵錯選項

備註

偵錯選項僅適用於編輯器與匯出樣板(但必須使用 debugrelease_debug 來建置目標,詳細請參考 目標 )。

指令

說明

-d, --debug

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

-b, --breakpoints

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

--profiling

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

--remote-debug <address>

遠端除錯( <host/IP>:<port> 位址)。

--debug-collisions

執行場景時顯示碰撞區域。

--debug-navigation

執行場景時顯示導航多邊形。

--frame-delay <ms>

模擬 CPU 高負載(每幀延遲 <ms> 毫秒)。

--time-scale <scale>

強制時間縮放(值越早則越快,1.0 為正常速度)。

--disable-render-loop

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

--disable-crash-handler

若平台代碼支援,禁用 Crash Handler。

--fixed-fps <fps>

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

--print-fps

在標準輸出上印出 FPS。

獨立工具

指令

說明

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

執行腳本。

--check-only

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

--export <target>

使用指定的匯出目標來匯出專案。若路徑以 .pck 或 .zip 結尾則只匯出 Main Pack(必須啟用 工具 )。

--export-debug <target>

--export 相同,但使用除錯樣板(必須啟用 工具 )。

--doctool <path>

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

--no-docbase

禁用傾印基礎型別(與 --doctool 一起使用,必須啟用 工具 )。

--build-solutions

建置腳本解決方案 (Solution)(如用於 C# 專案,必須啟用 工具 )。

--gdnative-generate-json-api

產生用於 GDNative 綁定的 Godot API JSON 傾印(必須啟用 工具 )。

--test <test>

指定單元測試。先使用 --help 以列出所有測試。(必須啟用 工具 )。

--export-pack <preset> <path>

--export 相同,但會使用給定的預設設定來匯出遊戲打包。會依照 <path> 的副檔名來判斷匯出的格式是 PCK 還是 ZIP。(必須啟用 工具 )。

路徑

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

設定專案路徑

依據 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 --path path_to_your_project --export 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 (伺服器建置,無視訊功能)亦是最佳選擇。

godot --export "Linux/X11" /var/builds/project
godot --export Android /var/builds/project.apk

The preset name must match the name of an export preset defined in the project's export_presets.cfg file. If the preset name contains spaces or special characters (such as "Windows Desktop"), it must be surrounded with quotes.

欲匯出除錯版本的遊戲,請使用 --export-debug 而非 --export 。其參數與用法皆相同。

如果只要匯出 PCK 檔案,可以將 --export 改成 --export-pack 選項,然後接上匯出預設設定的名稱與輸出路徑,並加上副檔名。輸出路徑的副檔名是依據套件格式判斷的,必須為 PCK 或 ZIP 其一。

警告

When specifying a relative path as the path for --export, --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.

執行腳本

可欲命令列中執行簡單的 .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