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

О godot-cpp

godot-cpp являются официальными привязками C++ GDExtension, поддерживаемыми как часть проекта Godot.

godot-cpp собран с использованием GDExtension system, которая позволяет получить доступ к Godot почти таким же образом, как modules: большую часть кода движка можно использовать в вашем проекте godot-cpp почти так же, как он есть.

В частности, godot-cpp имеет доступ ко всем функциям, которые есть в GDScript и C#, а также дополнительный доступ к нескольким другим для быстрого низкоуровневого доступа к данным или более глубокой интеграции с Godot.

Различия между модулями godot-cpp и C++

Вы можете использовать как godot-cpp, так и C++ modules для запуска кода C или C++ в проекте Godot.

Они также позволяют интегрировать в Godot библиотеки сторонних разработчиков. Выбор того или иного варианта зависит от ваших потребностей.

Преимущества godot-cpp

В отличие от модулей, godot-cpp (и GDExtensions в целом) не требует компиляции исходного кода движка, что упрощает распространение вашей работы. Он предоставляет доступ к большей части API, доступных для GDScript и C#, позволяя программировать игровую логику с полным контролем производительности. Он идеально подходит, если вам нужен высокопроизводительный код, который вы хотели бы распространять как дополнение в библиотеке asset library.

А также:

  • Вы можете использовать одну и ту же скомпилированную библиотеку godot-cpp в редакторе и экспортированном проекте. При использовании модулей C++ вам потребуется перекомпилировать все шаблоны экспорта, которые вы планируете использовать, если вам потребуется их функциональность во время выполнения.

  • godot-cpp требует компиляции только вашей библиотеки, а не всего движка. В отличие от модулей C++, которые статически компилируются в движок. Каждый раз при изменении модуля необходимо перекомпилировать движок. Даже при инкрементальной сборке этот процесс медленнее, чем при использовании godot-cpp.

Преимущества модулей C++

Мы рекомендуем C++ modules в случаях, когда godot-cpp (или другой системы GDExtension) недостаточно:

  • Модули C++ обеспечивают более глубокую интеграцию с движком. GDExtension не обладает такой же глубиной доступа, как статические модули.

  • Вы можете использовать модули C++ для реализации дополнительных функций в проекте без необходимости переносить с собой файлы собственных библиотек. Это также распространяется на экспортированные проекты.

Примечание

Если вы заметили, что определенные системы недоступны через godot-cpp, но доступны через пользовательские модули, не стесняйтесь открыть вопрос в репозитории godot-cpp, чтобы обсудить варианты реализации для предоставления отсутствующей функциональности.

Совместимость версий

Расширения GDExtensions, предназначенные для более ранних версий Godot, должны работать в более поздних младших версиях, но не наоборот. Например, расширение GDExtension, предназначенное для Godot 4.2, должно работать без проблем в Godot 4.3, но расширение, предназначенное для Godot 4.3, не будет работать в Godot 4.2.

По этой причине при создании GDExtensions вы можете ориентироваться на самую раннюю версию Godot, содержащую необходимые вам функции, а не на самую последнюю. Это избавит вас от необходимости создавать несколько сборок для разных версий Godot.

Из этого правила есть одно исключение: расширения, предназначенные для Godot 4.0, не будут работать с Godot 4.1 и более поздними версиями (см. Обновление ваших GDExtension на 4.1).

Расширения GDExtensions также совместимы только со сборками движка, использующими тот же уровень точности чисел с плавающей запятой, для которого было скомпилировано расширение. Это означает, что если вы используете сборку движка с числами с плавающей запятой двойной точности, расширение также должно быть скомпилировано для чисел с плавающей запятой двойной точности и использовать файл extension_api.json, сгенерированный вашей сборкой движка. Подробности см. в Большие мировые координаты.

Generally speaking, if you build a custom version of Godot, you should generate an extension_api.json from it for your GDExtensions, because it may have some differences from official Godot builds. You can learn more about the process of using custom extension_api.json files in the build system section.