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

O arquivo .gdextension

Introdução

O arquivo .gdextension no seu projeto contém as instruções de como carregar a GDExtension. As instruções são separadas em seções específicas. Esta página deve lhe dar uma visão geral rápida das diferentes opções disponíveis para você. Para uma introdução sobre como começar com C++ (godot-cpp), dê uma olhada no Exemplo de C++ para GDExtension.

Seção de configuração

Propriedade	Tipo	Descrição
entry_symbol	String	Nome da função de entrada para inicializar a GDExtension. Esta função deve ser definida no arquivo `register_types.cpp` ao usar o godot-cpp. Adicionar isso é necessário para que a extensão funcione.
compatibility_minimum	String	Versão mínima compatível. Isso impede que versões mais antigas do Godot carreguem extensões que dependem de recursos de versões mais novas do Godot. Suportado apenas no Godot 4.1 ou posterior
compatibility_maximum	String	Versão máxima compatível. Isso impede que versões mais novas do Godot carreguem a extensão. Suportado apenas no Godot 4.3 ou posterior
reloadable	Booleano	Recarrega a extensão após a recompilação. O recarregamento (reloading) é suportado para o binding godot-cpp no Godot 4.2 ou posterior. Outros bindings de linguagem podem ou não suportá-lo também. Esta flag deve ser usada principalmente para desenvolver ou depurar uma extensão.
android_aar_plugin	Booleano	A GDExtension faz parte de um plugin Android v2. Durante a exportação, esta flag indicará ao editor que as bibliotecas compartilhadas nativas da GDExtension são exportadas pelos binários AAR do plugin Android.

Seção de bibliotecas

Nesta seção, você pode definir os caminhos para os binários compilados das suas bibliotecas GDExtension. Ao especificar flags de recursos (feature flags), você pode filtrar qual versão deve ser carregada e exportada com o seu jogo, dependendo de quais flags de recursos estão ativas. Cada flag de recurso deve corresponder às flags de recursos do Godot ou às suas flags de exportação personalizadas para ser carregada em um jogo exportado. Por exemplo, macos.debug significa que ela será carregada se o Godot tiver as flags macos e debug ativas. Cada linha da seção é avaliada de cima para baixo.

Aqui está um exemplo de como isso pode parecer:

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

Os caminhos podem ser relativos ou absolutos (começando com res://). Caminhos relativos são recomendados, pois permitem que a extensão continue funcionando se for instalada em uma pasta diferente daquela especificada no caminho.

As entradas são correspondidas na ordem, portanto, se dois conjuntos de tags de recursos puderem corresponder ao mesmo sistema, certifique-se de colocar os mais específicos primeiro:

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

Aqui estão listas de algumas das opções integradas disponíveis (para mais, veja as tags de recursos / feature tags):

Sistema em execução

Flag	Descrição
windows	Sistema operacional Windows
macos	Sistema operacional Mac
linux	Sistema operacional Linux
bsd	Sistema operacional BSD
linuxbsd	Sistema operacional Linux ou BSD
android	Sistema operacional Android
ios	Sistema operacional iOS
web	Navegador

Build

Flag	Descrição
debug	Compilar com recursos de depuração (as compilações do editor sempre têm recursos de depuração)
release	Compilação otimizada sem recursos de depuração
editor	Build do editor

Arquitetura

Flag	Descrição
dobro	Build de dupla precisão
único	Build de precisão única
x86_64	Build x86 de 64 bits
arm64	Build ARM de 64 bits
rv64	Build RISC-V de 64 bits
riscv	Build RISC-V (qualquer bitagem)
wasm32	Build do WebAssembly de 32 bits

Seção de ícones

Por padrão, o Godot usa o ícone do Node no painel de cena para nós GDExtension. Um ícone personalizado pode ser definido fazendo referência ao seu nome e ao caminho do recurso de um arquivo SVG.

Por exemplo:

[icons]

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

O caminho deve apontar para uma imagem SVG de 16×16 pixels, com duas opções ativadas para a imagem no painel de Importação:

Editor > Escalonar com Escala do Editor.
Editor > Converter Cores com Tema do Editor.

A ativação de ambas as opções garante que o ícone se comporte o mais próximo possível dos ícones padrão do editor. Leia o guia para criar ícones para mais informações.

Seção de dependências

Nesta seção, você define os caminhos das dependências da GDExtension. Isso é usado internamente para exportar as dependências ao exportar o executável do seu jogo. Você pode definir qual dependência será carregada dependendo das flags de recursos do executável exportado. Além disso, você pode definir um subdiretório opcional para mover suas dependências. Se nenhum caminho for fornecido, o Godot moverá as bibliotecas para o mesmo diretório do executável do seu jogo.

Aviso

No macOS, é necessário ter bibliotecas compartilhadas dentro de uma pasta chamada Frameworks com uma estrutura de diretórios como esta: 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" : ""
}