.gdextension 檔案

前言

專案中的 .gdextension 檔案包含如何載入 GDExtension 的指示。這些指示被分成多個特定區段。本頁會快速總覽你可用的不同選項。若要了解如何開始使用 C++（godot-cpp），請參閱 GDExtension C++ 範例。

設定區段

屬性	型別	說明
entry_symbol	字串	初始化 GDExtension 的進入點函式名稱。使用 godot-cpp 時，此函式應定義於 register_types.cpp 檔案中。若未設定，擴充功能將無法正常運作。
compatibility_minimum	字串	最低相容版本。此設定可避免舊版 Godot 嘗試載入需要新版功能的擴充功能。僅支援於 Godot 4.1 或更新版本
compatibility_maximum	字串	最高相容版本。此設定可避免新版 Godot 嘗試載入本擴充功能。僅支援於 Godot 4.3 或更新版本
reloadable	布林	重新編譯時自動重新載入擴充功能。於 Godot 4.2 或更新版本的 godot-cpp 綁定支援此功能。其他語言綁定可能不支援。此旗標主要用於擴充功能的開發與除錯階段。
android_aar_plugin	布林	此 GDExtension 屬於 v2 Android 外掛 的一部分。匯出時，此旗標會通知編輯器該 GDExtension 的原生共享函式庫由 Android 外掛的 AAR 檔案負責匯出。

函式庫區段

在本區段中，你可以設定 GDExtension 函式庫的編譯二進位檔路徑。透過指定功能旗標，可以依據目前啟用的旗標，決定要載入與匯出哪個版本。每個功能旗標必須與 Godot 的功能旗標或自訂匯出旗標相符，才能在匯出遊戲時正確載入。例如 macos.debug 表示只有在 Godot 啟用 macos 與 debug 旗標時才會載入。區段中的每一行會自上而下依序判斷。

範例：

[libraries]

macos.debug = "res://bin/libgdexample.macos.template_debug.framework"
macos.release = "res://bin/libgdexample.macos.template_release.framework"
windows.debug.x86_32 = "res://bin/libgdexample.windows.template_debug.x86_32.dll"
windows.release.x86_32 = "res://bin/libgdexample.windows.template_release.x86_32.dll"
windows.debug.x86_64 = "res://bin/libgdexample.windows.template_debug.x86_64.dll"
windows.release.x86_64 = "res://bin/libgdexample.windows.template_release.x86_64.dll"
linux.debug.x86_64 = "res://bin/libgdexample.linux.template_debug.x86_64.so"
linux.release.x86_64 = "res://bin/libgdexample.linux.template_release.x86_64.so"
linux.debug.arm64 = "res://bin/libgdexample.linux.template_debug.arm64.so"
linux.release.arm64 = "res://bin/libgdexample.linux.template_release.arm64.so"
linux.debug.rv64 = "res://bin/libgdexample.linux.template_debug.rv64.so"
linux.release.rv64 = "res://bin/libgdexample.linux.template_release.rv64.so"

項目會依序匹配；因此若兩組功能標籤都可能符合同一系統，請將較具體的組合放在前面：

[libraries]

linux.release.editor.x86_64 = "res://bin/libgdexample.linux.template_release.x86_64.so"
linux.release.x86_64 = "res://bin/libgdexample.linux.noeditor.template_release.x86_64.so"

以下列出部分可用的內建選項（詳情請參閱 功能標籤）：

執行系統

旗標	說明
Windows	Windows 作業系統
macos	macOS 作業系統
linux	Linux 作業系統
bsd	BSD 作業系統
linuxbsd	Linux 或 BSD 作業系統
android	Android 作業系統
ios	iOS 作業系統
web	網頁瀏覽器

建構

旗標	說明
debug	包含除錯符號的建構
release	最佳化建構（不含除錯符號）
editor	編輯器建構

架構

旗標	說明
double	雙精度建構
single	單精度建構
x86_64	64 位元 x86 建構
arm64	64 位元 ARM 建構
rv64	64 位元 RISC-V 建構
riscv	RISC-V 建構（不限位元數）
wasm32	32 位元 WebAssembly 建構

圖示區段

預設情況下，Godot 會在場景面板中為 GDExtension 節點使用 Node 節點圖示。你可以透過指定 SVG 檔案的名稱與資源路徑來設定自訂圖示。

例如：

[icons]

GDExample = "res://icons/gd_example.svg"

路徑應指向一張 16 x 16 像素的 SVG 圖像。如需更多資訊，請參閱 建立圖示 指南。

相依性區段

在本區段中你可以設定 GDExtension 所需相依檔案的路徑。這些設定會在匯出遊戲執行檔時自動包含相依檔案。你也可以根據匯出執行檔的功能旗標，設定要載入哪個相依檔案。此外，可選擇性地指定將相依檔案移動到的子目錄。如果未指定路徑，Godot 會將這些函式庫移到與遊戲執行檔相同的資料夾。

警告

於 macOS 上，必須將共享函式庫放在名為 Frameworks 的資料夾內，目錄結構應為：Game.app/Contents/Frameworks。

[dependencies]

macos.debug = {
    "res://bin/libdependency.macos.template_debug.framework" : "Contents/Frameworks"
}
macos.release = {
    "res://bin/libdependency.macos.template_release.framework" : "Contents/Frameworks"
}
windows.debug = {
    "res://bin/libdependency.windows.template_debug.x86_64.dll" : "",
    "res://bin/libdependency.windows.template_debug.x86_32.dll" : ""
}
windows.release = {
    "res://bin/libdependency.windows.template_release.x86_64.dll" : "",
    "res://bin/libdependency.windows.template_release.x86_32.dll" : ""
}
linux.debug = {
    "res://bin/libdependency.linux.template_debug.x86_64.so" : "",
    "res://bin/libdependency.linux.template_debug.arm64.so" : "",
    "res://bin/libdependency.linux.template_debug.rv64.so" : ""
}
linux.release = {
    "res://bin/libdependency.linux.template_release.x86_64.so" : "",
    "res://bin/libdependency.linux.template_release.arm64.so" : "",
    "res://bin/libdependency.linux.template_release.rv64.so" : ""
}