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 的方法的指令，这些指令分别位于不同的区域。此页面会让你快速了解不同的可用选项。若要学习如何开始制作 GDExtension，请参阅 GDExtension C++ 示例。

配置部分

属性	类型	描述
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。该部分的每一行内容均由上至下进行评估。

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

[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"

下表列出了一些可用的内置选项（更多选项见特性标签）：

运行系统

标志	描述
windows	Windows 操作系统
macos	Mac 操作系统
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 乘 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" : ""
}