.gdextension 文件

前言

The .gdextension file in your project contains the instructions for how to load the GDExtension. The instructions are separated into specific sections. This page should give you a quick overview of the different options available to you. For an introduction how to get started with C++ (godot-cpp), take a look at the GDExtension C++ Example.

配置部分

属性	类型	描述
entry_symbol	字符串	入口函数的名称，用于初始化 GDExtension。使用 godot-cpp 时，该函数应在 register_types.cpp 中定义。添加后扩展才能正常工作。
compatibility_minimum	字符串	最低兼容版本。较旧版本的 Godot 不会加载依赖较新版本 Godot 功能的扩展。仅 Godot 4.1 及后续版本支持
compatibility_maximum	字符串	最高兼容版本。较新版本的 Godot 不会加载该扩展。仅 Godot 4.3 及后续版本支持
reloadable	Boolean	重新编译后重新加载该扩展。Godot 4.2 及后续版本支持 godot-cpp 绑定的重新加载。其他语言的绑定可能支持也可能不支持。该标志应主要用于扩展的开发和调试。
android_aar_plugin	Boolean	该 GDExtension 属于某个 v2 Android 插件。导出时，该标志会告诉编辑器该 GDExtension 原生共享库由 Android 插件 AAR 二进制文件导出。

库部分

在该部分，你可以设置路径来指向你编译好的 GDExtension 二进制库文件，可以通过指定功能标志，并根据功能标志的活动状态来过滤应加载和导出游戏的版本。每个功能标志都必须与 Godot 的功能标志或自定义导出标志相匹配，才能在导出的游戏中加载。例如，macos.debug 表示如果 Godot 同时具有 macos 和 debug 标志，则将加载该 GDExtension。该部分的每一行内容均由上至下进行评估。

下面是库部分的内容示例：

; 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.

Entries are matched in order, so if two sets of feature tags could match the same system, be sure to put the more specific ones first:

[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	Mac 操作系统
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" : ""
}