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 JSON da interface C

O arquivo gdextension_interface.json é a "fonte da verdade" para a API C que o Godot usa para se comunicar com as GDExtensions.

Você pode usar o executável do Godot para extrair o arquivo usando o seguinte comando:

godot --headless --dump-gdextension-interface-json

Este arquivo é destinado a ser usado por bindings de linguagem da GDExtension para gerar código para o uso desta API em qualquer formato que faça mais sentido para essa linguagem.

Nota

Isso não deve ser confundido com o extension_api.json, que também é usado por bindings de linguagem da GDExtension e contém informações sobre as classes e métodos que são expostos pelo Godot. O gdextension_interface.json é mais de baixo nível e é usado para interagir com essas classes e métodos de nível superior.

Para linguagens que podem ser estendidas via C, ou fornecem ferramentas para interagir com código C, também é possível usar o executável do Godot para extrair um arquivo de cabeçalho C gerado:

godot --headless --dump-gdextension-interface

Nota

O arquivo de cabeçalho é compatível com versões anteriores do arquivo de cabeçalho que foram incluídas no Godot 4.5 e versões anteriores, o que significa que ele preserva alguns erros de digitação nos nomes para garantir a compatibilidade.

O objetivo desta página é explicar o formato JSON para os bindings de linguagem da GDExtension que gostariam de fazer sua própria geração de código a partir do JSON.

Estrutura geral

O arquivo JSON é dividido em 3 seções:

O cabeçalho, que inclui algumas informações variadas no nível superior do arquivo JSON.
A chave types, que define todos os tipos usados na interface da GDExtension.
A chave interface, que define todos os ponteiros de função que podem ser carregados por meio do ponteiro de função GDExtensionInterfaceGetProcAddress, que é passado para todas as GDExtensions quando elas são carregadas.

Há um esquema JSON completo incluído no código-fonte do Godot.

Mesmo que possamos adicionar novos tipos e funções de interface a cada versão menor do Godot, nos esforçamos para nunca alterá-los de uma forma incompatível com versões anteriores, ou removê-los. Cada função de interface é rotulada com a versão do Godot em que foi introduzida (a chave since), para que você possa sempre usar a versão mais recente do arquivo e simplesmente abster-se de usar qualquer coisa em versões do Godot que sejam mais recentes do que a versão que você tem como alvo.

Cabeçalho

O "cabeçalho" é composto por 3 chaves variadas no nível superior do arquivo:

_copyright: O texto padrão de direitos autorais e licença que o Godot inclui em todos os arquivos de código-fonte.
$schema: Aponta para o esquema JSON relativo a este arquivo. Pode ser útil colocar o esquema no mesmo diretório se você estiver visualizando-o com um editor de código que entende o esquema JSON.
format_version: Um número inteiro para a versão do formato do arquivo (ou seja, o esquema). No momento, há apenas uma versão de formato (1). Se algum dia alterarmos o formato do arquivo de uma forma incompatível, incrementaremos esse número. Isso não reflete a versão dos dados no arquivo (portanto, não mudará entre as versões do Godot), apenas o seu formato. Esperamos nunca ter que usá-lo, mas permite que os geradores de código apresentem erros logo no início se encontrarem um valor inesperado aqui.

Tipos

A seção types é uma matriz de tipos que serão usados por outros tipos, e as funções de interface que estarão na última seção.

Os tipos devem ser avaliados em ordem. Tipos posteriores podem se referir a tipos anteriores, mas tipos anteriores não se referirão a tipos posteriores.

Existe um pequeno conjunto de tipos integrados que não estão explicitamente listados no JSON:

void
int8_t
uint8_t
int16_t
uint16_t
int32_t
uint32_t
int64_t
uint64_t
size_t (uint32_t em arquiteturas de 32 bits e uint64_t em arquiteturas de 64 bits)
char
char16_t
char32_t
wchar_t
float
double

Estes correspondem aos seus tipos C equivalentes.

Adicionalmente, os tipos podem incluir modificadores como:

* (por exemplo, int8_t*) para indicar um ponteiro para o tipo
const (por exemplo, const int8_t*) para indicar un tipo const

Cada tipo definido no arquivo JSON se enquadra em um dos 5 "tipos" (kinds):

enum
handle
alias
struct
function

Independentemente do "tipo" (kind), todos os tipos podem ter as seguintes chaves:

kind (obrigatório): O "tipo" (kind) do tipo.
name (obrigatório): O nome do tipo, que poderia ser usado como um identificador C válido.
description: Uma matriz de strings documentando o tipo, onde cada string é uma linha de documentação (este formato para description é usado em todo o arquivo JSON).
deprecated: Um objeto com suas próprias chaves para a versão do Godot em que o tipo foi descontinuado (since), uma mensagem explicando a descontinuação (message) e, opcionalmente, um substituto para usar em seu lugar (replacement).

Enumeradores

Os enums são inteiros de 32 bits com um conjunto fixo de valores possíveis. Em C, eles poderiam ser representados como um enum.

Eles possuem as seguintes chaves:

is_bitfield: Se verdadeiro, este enum é um campo de bits (bitfield), onde os valores do enum podem ser combinados por meio de um operador OR bit a bit. É falso por padrão.
values: A matriz de valores fixos para este enum, cada um com um name, value e description.

Um enum deve ser representado como um int32_t, a menos que is_bitfield seja verdadeiro, caso em que um uint32_t deve ser usado.

Exemplo

{
    "name": "GDExtensionInitializationLevel",
    "kind": "enum",
    "values": [
        {
            "name": "GDEXTENSION_INITIALIZATION_CORE",
            "value": 0
        },
        {
            "name": "GDEXTENSION_INITIALIZATION_SERVERS",
            "value": 1
        },
        {
            "name": "GDEXTENSION_INITIALIZATION_SCENE",
            "value": 2
        },
        {
            "name": "GDEXTENSION_INITIALIZATION_EDITOR",
            "value": 3
        },
        {
            "name": "GDEXTENSION_MAX_INITIALIZATION_LEVEL",
            "value": 4
        }
    ]
}

Handles

Handles são ponteiros para structs opacas. Em C, eles poderiam ser representados como void * ou struct{} *.

Eles possuem as seguintes chaves:

is_const: Se verdadeiro, este tipo de handle deve ser tratado como um "ponteiro constante" (const pointer), significando que seus dados internos não serão alterados. É falso por padrão.
is_uninitialized: Se verdadeiro, este tipo de handle deve ser tratado como apontando para memória não inicializada (que pode ser inicializada usando funções de interface). É falso por padrão.
parent: O nome opcional de outro tipo de handle, se este tipo de handle for a versão const ou não inicializada do tipo pai. Isso só faz sentido se is_const ou is_uninitialized for verdadeiro.

Os handles têm o tamanho de ponteiros na arquitetura fornecida (por exemplo, 64 bits em x86_64 e 32 bits em x86_32).

Exemplo

{
    "name": "GDExtensionStringNamePtr",
    "kind": "handle"
}

Aliases

Aliases são nomes alternativos para um tipo. Em C, eles poderiam ser representados como um typedef.

Eles têm apenas uma chave adicional:

type: O tipo para o qual o alias é um nome alternativo. Pode incluir modificadores conforme descrito acima.

Estes devem ser representados usando o mesmo tipo C que o tipo ao qual se referem.

Exemplo

{
    "name": "GDExtensionInt",
    "kind": "alias",
    "type": "int64_t"
}

Structs (Estruturas)

Structs representam structs do C (ou seja, um bloco de memória composto pelos membros fornecidos em ordem) e devem seguir todas as mesmas regras de layout e alinhamento que as structs do C.

Eles têm apenas uma chave adicional:

members: Uma matriz de objetos que possuem um name, type (que pode incluir modificadores) e description.

Exemplo

{
    "name": "GDExtensionCallError",
    "kind": "struct",
    "members": [
        {
            "name": "error",
            "type": "GDExtensionCallErrorType"
        },
        {
            "name": "argument",
            "type": "int32_t"
        },
        {
            "name": "expected",
            "type": "int32_t"
        }
    ]
}

Funções

Functions representam tipos de ponteiros de função C, com uma lista de argumentos e um tipo de retorno, e devem seguir os mesmos requisitos de tamanho e alinhamento que os ponteiros de função C.

Eles possuem os seguintes membros:

return_value: Um objeto que possui um type (que pode incluir modificadores) e description. Se a função não tiver valor de retorno, isso será omitido.
arguments (obrigatório): Uma matriz de argumentos de função, onde cada um possui um type (que pode incluir modificadores), name e description.

Exemplo

{
    "name": "GDExtensionPtrConstructor",
    "kind": "function",
    "arguments": [
        {
            "name": "p_base",
            "type": "GDExtensionUninitializedTypePtr"
        },
        {
            "name": "p_args",
            "type": "const GDExtensionConstTypePtr*"
        }
    ]
}

Interface

A seção interface do arquivo JSON é a lista de funções de interface, que podem ser carregadas pelo name usando o ponteiro de função GDExtensionInterfaceGetProcAddress, que é passado para todas as GDExtensions quando elas são carregadas.

As funções de interface têm algumas das mesmas chaves que os tipos, incluindo name (obrigatório), deprecated e description.

E também possuem return_value e arguments (obrigatório) que têm o mesmo formato que as chaves equivalentes nos tipos de função (conforme descrito na seção anterior).

Existem apenas algumas chaves exclusivas:

since (obrigatório): A versão do Godot que introduziu esta função de interface.
see: Uma matriz de strings que descrevem referências externas com mais informações, por exemplo, nomes de classes ou funções no código-fonte do Godot, ou URLs que apontam para a documentação.
legacy_type_name: O nome legado usado para o tipo de ponteiro de função no cabeçalho gerado pelo Godot, quando o nome legado não corresponde ao padrão usado para esses nomes de tipo. Este campo existe apenas para que possamos gerar o cabeçalho de uma forma que seja compatível com versões anteriores do cabeçalho do Godot 4.5 ou anterior, e não deve ser usado a menos que você também precise manter a compatibilidade com o cabeçalho antigo.

Exemplo

{
    "name": "get_godot_version",
    "arguments": [
        {
            "name": "r_godot_version",
            "type": "GDExtensionGodotVersion*",
            "description": [
                "A pointer to the structure to write the version information into."
            ]
        }
    ],
    "description": [
        "Gets the Godot version that the GDExtension was loaded into."
    ],
    "since": "4.1",
    "deprecated": {
        "since": "4.5",
        "replace_with": "get_godot_version2"
    }
}