Godot GDExtension: спроектируйте нативную границу и поставляйте нужную библиотеку

Выберите чёткую нативную ответственность

GDExtension позволяет использовать нативные библиотеки, не компилируя этот код внутрь движка Godot. Официальные привязки C++ — godot-cpp. Они поддерживают игровую логику и подключение нативных библиотек, а модули движка остаются уместны при необходимости более глубокого доступа. Указанный процесс документирован для Godot 4.6. [1]

Выберите задачу с ясными входом и выходом, например вычислительное ядро или адаптер существующей библиотеки. Перенос кода через языковую границу — архитектурное решение, требующее оснований; одна нативная компиляция не доказывает полезного ускорения.

Зарегистрируйте интерфейс, видимый движку

Пример C++ наследует класс от типа движка, использует GDCLASS и регистрирует класс при инициализации расширения. Функция _bind_methods объявляет методы и свойства, доступные через систему привязок Godot. Скомпилированная функция-член C++ не становится автоматически API для скриптов лишь потому, что существует в библиотеке. [2]

Держите внешний интерфейс небольшим и документируйте смысл аргументов, допустимые диапазоны, возвращаемые значения и поведение при ошибке. Отделяйте численную реализацию от адаптера движка, чтобы у каждой стороны была понятная ответственность.

Определите пример пакетной операции

Представьте расширение для создания пещер с проектным методом sample_density. Вызывающая сторона передаёт 1000 позиций выборки и получает соответствующую плотность для каждой. Определите сохранение порядка входных данных, обработку некорректного ввода и владельца временной нативной памяти.

Пакетный интерфейс позволяет не проектировать отдельный переход из скрипта в нативный код для каждого отсчёта, но его реальную пользу нужно измерять. Включайте в измерение преобразование, выделение памяти и копирование. Пусть логика проекта решает, когда результаты изменяют сцену; вычисление не должно молча предполагать, что определённое выделение редактора или узел сцены ещё существуют при использовании результата.

Явно опишите загрузку бинарных файлов

Файл .gdextension задаёт точку инициализации через entry_symbol и перечисляет скомпилированные библиотеки, выбираемые по тегам возможностей. Поэтому платформа, архитектура и конфигурация сборки относятся к поставке, а не только к локальной настройке компилятора. Записи зависимостей могут включать нативные библиотеки, необходимые экспортированным проектам. [3]

Проверьте наличие указанного входного символа и выбор правильного файла для каждой целевой конфигурации. Успешная загрузка в редакторе на одном компьютере не доказывает наличия нужных бинарных файлов для другой архитектуры или экспортированной релизной сборки.

Ограничивайте совместимость, не превращая её в обещание

Документация ожидает, что расширения для более ранней минорной версии Godot должны работать в последующих минорных версиях; выбор нового API не обеспечивает обратную совместимость. Расширения для 4.0 — явное исключение: они не работают с 4.1 и новее. Точность чисел с плавающей точкой у движка и расширения тоже должна совпадать. [1]

Выберите самый ранний целевой API с нужными функциями, объявите соответствующий минимум совместимости и изучите документированные требования выбранных привязок. Проверяйте самый ранний поддерживаемый движок и репрезентативные экспорты для каждой нужной платформы. Это предлагаемые проверки совместимости; успешная сборка или межплатформенные испытания здесь не заявляются. [2][3]

Источники

1. About godot-cpp — Godot Engine contributors.
2. Getting started with godot-cpp — Godot Engine contributors.
3. The .gdextension file — Godot Engine contributors.