Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

.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 旗標時才會載入。區段中的每一行會自上而下依序判斷。

範例：

; A comment line starts with a semicolon. This line is ignored by the engine.
[libraries]

macos.debug = "./bin/libgdexample.macos.template_debug.dylib" ; Inline comments are also allowed.
macos.release = "./bin/libgdexample.macos.template_release.dylib"
windows.debug.x86_32 = "./bin/libgdexample.windows.template_debug.x86_32.dll"
windows.release.x86_32 = "./bin/libgdexample.windows.template_release.x86_32.dll"
windows.debug.x86_64 = "./bin/libgdexample.windows.template_debug.x86_64.dll"
windows.release.x86_64 = "./bin/libgdexample.windows.template_release.x86_64.dll"
linux.debug.x86_64 = "./bin/libgdexample.linux.template_debug.x86_64.so"
linux.release.x86_64 = "./bin/libgdexample.linux.template_release.x86_64.so"
linux.debug.arm64 = "./bin/libgdexample.linux.template_debug.arm64.so"
linux.release.arm64 = "./bin/libgdexample.linux.template_release.arm64.so"
linux.debug.rv64 = "./bin/libgdexample.linux.template_debug.rv64.so"
linux.release.rv64 = "./bin/libgdexample.linux.template_release.rv64.so"

Paths can be relative or absolute (starting with res://). Relative paths are recommended, as they allow the extension to keep working if it's installed to a different folder than what's specified in the path.

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

[libraries]

linux.release.editor.x86_64 = "./bin/libgdexample.linux.template_release.x86_64.so"
linux.release.x86_64 = "./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	Build with debugging features (editor builds always have debugging features)
release	Optimized build without debugging features
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"

The path should point to a 16×16 pixel SVG image, with two options enabled on the image in the Import dock:

Editor > Scale with Editor Scale.
Editor > Convert Colors with Editor Theme.

Enabling both options ensures the icon behaves as closely as possible to the stock editor icons. Read the guide for creating icons for more information.

相依性區段

In this section, you set the paths of the GDExtension dependencies. This is used internally to export the dependencies when exporting your game executable. You are able to set which dependency is loaded depending on the feature flags of the exported executable. In addition, you are able to set an optional subdirectory to move your dependencies into. If no path is supplied, Godot will move the libraries into the same directory as your game executable.

警告

On macOS, it is necessary to have shared libraries inside a folder called Frameworks with a directory structure like this: 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" : ""
}