.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" : ""
}