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

路径可以是相对路径，也可以是绝对路径（以 res:// 开头）。建议使用相对路径，因为这样设置下，即使扩展程序安装在与路径中指定的文件夹不同的文件夹中，也能继续正常工作。

匹配按条目顺序执行，若两组特性标签可能匹配同一系统，请确保将更具体的标签放在前面：

[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	构建时启用调试功能（编辑器构建版本始终包含调试功能）
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" : ""
}