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

Файл .gextension

Введение

Файл .gdextension в вашем проекте содержит инструкции по загрузке GDExtension. Инструкции разделены на отдельные разделы. Эта страница даст вам краткий обзор различных доступных вам возможностей. Для получения вводной информации о начале работы с C++ (godot-cpp) ознакомьтесь с GDExtension C++ Example.

Раздел конфигурации

Свойство	Тип	Описание
entry_symbol	Строка	Имя функции входа для инициализации GDExtension. Эта функция должна быть определена в файле `register_types.cpp` при использовании godot-cpp. Добавление этой функции необходимо для работы расширения.
compatibility_minimum	Строка	Минимальная совместимая версия. Это предотвращает загрузку расширений, зависящих от функций более новых версий Godot. Поддерживается только в Godot 4.1 и более поздних версиях
compatibility_maximum	Строка	Максимальная совместимая версия. Это предотвращает загрузку расширения в более новых версиях Godot. Поддерживается только в Godot 4.3 и более поздних версиях
reloadable	Boolean	Перезагружает расширение при перекомпиляции. Перезагрузка поддерживается для привязки godot-cpp в Godot 4.2 и более поздних версиях. Привязки других языков также могут поддерживать её, а могут и не поддерживать. Этот флаг следует использовать в основном для разработки или отладки расширения.
android_aar_plugin	Boolean	GDExtension является частью v2 Android plugin. При экспорте этот флаг укажет редактору, что собственные общие библиотеки GDExtension экспортируются двоичными файлами AAR плагина Android.

Раздел библиотек

В этом разделе можно указать пути к скомпилированным двоичным файлам библиотек 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"

Пути могут быть относительными или абсолютными (начинающимися с 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"

Вот списки некоторых доступных встроенных опций (для получения более подробной информации см. feature tags):

Running system (Ходовая система)

Flag (Флаг)	Описание
windows	Операционная система Windows
macOS	Операционная система Mac
linux	Операционная система Linux
bsd	Операционная система BSD
linux-bsd	Операционная система Linux или BSD
android	Операционная система Android
ios	Операционная система iOS
web	Web-браузер

Build (сборка)

Flag (Флаг)	Описание
debug	Сборка с отладочными функциями (сборки редактора всегда имеют отладочные функции)
release	Оптимизированная сборка без отладочных функций
editor	Редактор сборки

Архитектура

Flag (Флаг)	Описание
double (двойной)	сборка с двойной точностью
single (одинарный)	сборка с одинарной точностью
x86_64	64-битная сборка x86
arm64	64-битная сборка ARM
rv64	64-битная сборка RISC-V
risc-v	Сборка RISC-V (любой разрядности)
wasm-32	32-битная сборка WebAssembly

Раздел иконок

По умолчанию Godot использует значок Node в панели сцен для узлов GDExtension. Пользовательский значок можно задать, указав его имя и путь к ресурсу в SVG-файле.

Например:

[icons]

GDExample = "res://icons/gd_example.svg"

Путь должен указывать на SVG-изображение размером 16x16 пикселей, с двумя включёнными опциями на изображении в доке Import:

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

Включение обеих опций обеспечивает максимально близкое поведение значка к стандартным значкам редактора. Для получения дополнительной информации прочитайте руководство по созданию значков.

Раздел зависимостей

В этом разделе вы задаёте пути к зависимостям 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" : ""
}