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

Sobre o godot-cpp

O godot-cpp representa as vinculações oficiais de C++ para GDExtension, mantidas como parte do projeto Godot.

O godot-cpp é construído com o sistema GDExtension, que permite o acesso ao Godot quase da mesma forma que os módulos: uma grande parte do código do motor pode ser utilizada no seu projeto godot-cpp quase exatamente como ele é.

Em especial, o godot-cpp tem acesso a todas as funções que o GDScript e o C# possuem, além de acesso adicional a mais algumas funções para acesso rápido de baixo nível aos dados ou para uma integração mais profunda com o Godot.

Diferenças entre godot-cpp e módulos C++

Você pode usar tanto o godot-cpp quanto módulos C++ para executar código C ou C++ em um projeto Godot.

Ambos também permitem integrar bibliotecas de terceiros ao Godot. A escolha de qual utilizar depende das suas necessidades.

Vantagens do godot-cpp

Unlike modules, godot-cpp (and GDExtensions, in general) don't require compiling the engine's source code, making it easier to distribute your work. It gives you access to most of the API available to GDScript and C#, allowing you to code game logic with full control regarding performance. It's ideal if you need high-performance code you'd like to distribute as an add-on in the Asset Store.

Também:

Você pode usar a mesma biblioteca godot-cpp compilada tanto no editor quanto no projeto exportado. Com módulos C++, você precisa recompilar todos os modelos de exportação (export templates) que planeja usar caso precise de sua funcionalidade em tempo de execução.
O godot-cpp exige apenas que você compile a sua biblioteca, não o motor inteiro. Isso é diferente dos módulos C++, que são compilados estaticamente dentro do motor. Cada vez que você altera um módulo, precisa recompilar o motor. Mesmo com compilações incrementais, esse processo é mais lento do que usar o godot-cpp.

Vantagens dos módulos C++

Recomendamos módulos C++ nos casos em que o godot-cpp (ou outro sistema GDExtension) não for suficiente:

Os módulos C++ fornecem uma integração mais profunda com o motor. O acesso da GDExtension não é tão profundo quanto o dos módulos estáticos.
Você pode usar módulos C++ para fornecer recursos adicionais em um projeto sem a necessidade de carregar arquivos de biblioteca nativa por aí. Isso se estende aos projetos exportados.

Nota

Se você notar que sistemas específicos não estão acessíveis via godot-cpp, mas estão via módulos personalizados, sinta-se à vontade para abrir uma issue no repositório do godot-cpp para discutir opções de implementação para expor a funcionalidade ausente.

Compatibilidade de versões

GDExtensions destinadas a uma versão anterior do Godot devem funcionar em versões menores (minor) posteriores, mas não o contrário. Por exemplo, uma GDExtension destinada ao Godot 4.2 deve funcionar perfeitamente no Godot 4.3, mas uma destinada ao Godot 4.3 não funcionará no Godot 4.2.

Por esse motivo, ao criar GDExtensions, você pode preferir focar na versão mais baixa do Godot que possua os recursos de que você precisa, e não na versão mais recente do Godot. Isso pode evitar que você precise criar múltiplas compilações para diferentes versões do Godot.

Há uma exceção a isso: extensões destinadas ao Godot 4.0 não funcionarão com o Godot 4.1 e posteriores (veja Atualizando seu GDExtension para 4.1).

As GDExtensions também só são compatíveis com compilações do motor que utilizem o mesmo nível de precisão de ponto flutuante para o qual a extensão foi compilada. Isso significa que, se você usar uma compilação do motor com floats de precisão dupla, a extensão também deve ser compilada para floats de precisão dupla e usar um arquivo extension_api.json gerado pela sua compilação personalizada do motor. Veja Coordenadas de mundo grande para mais detalhes.

De modo geral, se você construir uma versão personalizada do Godot, deve gerar um extension_api.json a partir dela para as suas GDExtensions, pois ela pode apresentar algumas diferenças em relação às compilações oficiais do Godot. Você pode aprender mais sobre o processo de uso de arquivos extension_api.json personalizados na seção do sistema de compilação.