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

Il file JSON dell'interfaccia C

Il file gdextension_interface.json è la "fonte di verità" per l'API di C che Godot utilizza per comunicare con le GDExtension.

È possibile utilizzare l'eseguibile di Godot per estrarre il contenuto del file tramite il seguente comando:

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

This file is intended to be used by GDExtension language bindings to generate code for using this API in whatever form makes the most sense for that language.

Nota

Da non confondere con extension_api.json, che è utilizzato anche dai binding di linguaggio per GDExtension e contiene informazioni sulle classi e sui metodi esposti da Godot. Il file gdextension_interface.json è di livello più basso e serve per interagire con classi e metodi di livello superiore.

Per i linguaggi che si possono estendere tramite C, o che forniscono strumenti per interagire con il codice C, è anche possibile utilizzare l'eseguibile di Godot per generare un file di intestazione C:

godot --headless --dump-gdextension-interface

Nota

Il file di intestazione è compatibile con le versioni precedenti del file di intestazione che erano incluse in Godot 4.5 e versioni precedenti, il che significa che mantiene alcuni errori di battitura nei nomi per garantire la compatibilità.

L'obiettivo di questa pagina è spiegare il formato JSON per i binding di linguaggio per GDExtension che desiderano generare autonomamente il loro codice dal JSON.

Struttura generale

Il file JSON è suddiviso in 3 sezioni:

L'intestazione, che include alcune informazioni varie al livello superiore del file JSON.
La chiave types, che definisce tutti i tipi utilizzati nell'interfaccia GDExtension.
La chiave interface, che definisce tutti i puntatori delle funzioni che è possibile caricare tramite il puntatore di funzione GDExtensionInterfaceGetProcAddress, che è passato a tutte le GDExtension quando sono caricate.

È presente uno schema JSON completo: incluso nel codice sorgente di Godot.

Anche se potremmo aggiungere nuovi tipi e funzioni di interfaccia con ogni versione minore di Godot, ci impegniamo a non modificarli mai in modo incompatibile con le versioni precedenti, né a rimuoverli. Ogni funzione di interfaccia è etichettata con la versione di Godot in cui è stata introdotta (la chiave since), quindi è sempre possibile utilizzare la versione più recente del file ed evitare di utilizzare elementi presenti in versioni di Godot successive a quella di destinazione.

Intestazione

L'intestazione ("header") è composta da 3 chiavi diverse al livello superiore del file:

_copyright: Il testo standard relativo al copyright e alla licenza che Godot include in tutti i file del codice sorgente.
$schema: punta allo schema JSON relativo a questo file. Può essere utile posizionare lo schema nella stessa cartella, se lo si visualizza con un editor di codice che supporta gli schemi JSON.
format_version: un numero intero che indica la versione del formato del file (ovvero lo schema). Al momento, esiste una sola versione del formato (1). Se dovessimo modificare il formato del file in modo incompatibile, questo numero sarà incrementato. Questo non riflette la versione dei dati nel file (quindi non cambierà tra le diverse versioni di Godot), ma solo il suo formato. Speriamo di non doverlo mai utilizzare, ma permette ai generatori di codice di segnalare un errore precoce se incontrano un valore inaspettato.

Tipi

La sezione types è un array di tipi che saranno utilizzati da altri tipi e dalle funzioni di interfaccia che saranno presenti nell'ultima sezione.

I tipi devono essere valutati in ordine. I tipi successivi possono fare riferimento a tipi precedenti, ma i tipi precedenti non faranno riferimento a tipi successivi.

Esiste un piccolo insieme di tipi predefiniti che non sono esplicitamente elencati nel JSON:

void
int8_t
uint8_t
int16_t
uint16_t
int32_t
uint32_t
int64_t
uint64_t
size_t (uint32_t su architetture a 32 bit e uint64_t su architetture a 64 bit)
char
char16_t
char32_t
wchar_t
float
double

Questi corrispondo al loro tipo C# equivalente.

Inoltre, i tipi possono includere modificatori come:

* (ad esempio int8_t*) per indicare un puntatore al tipo
const (ad esempio const int8_t*) per indicare un tipo costante

Ciascun tipo definito nel file JSON rientra in una di 5 "categorie":

enum
handle
alias
struct
function

A prescindere dalla "categoria", tutti i tipi possono avere le seguenti chiavi:

kind (obbligatorio): la "categoria" del tipo.
name (obbligatorio): il nome del tipo, che si può utilizzare come identificatore valido in C.
description: un array di stringhe che documentano il tipo, dove ogni stringa è una riga di documentazione (tale formato per description è utilizzato in tutto il file JSON).
deprecated: un oggetto con le proprie chiavi per la versione di Godot in cui il tipo è stato deprecato (since), un messaggio che spiega la deprecazione (message) e, facoltativamente, un sostituto da utilizzare al suo posto (replacement).

Enumerazioni

Gli enum sono numeri interi a 32 bit con un insieme fisso di valori possibili. In C, si potrebbero rappresentare come un enum.

Hanno le seguenti chiavi:

is_bitfield: se true, questo enum è un campo di bit, in cui è possibile combinare i suoi valori tramite OR bit a bit. Predefinito su false.
values: l'array di valori fissi per questo enum, ciascuno con un nome (name), un valore (value) e una descrizione (description).

Un'enumerazione si dovrebbe rappresentare come un int32_t, a meno che is_bitfield non sia true, nel qual caso si dovrebbe utilizzare un uint32_t.

Esempio

{
    "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
        }
    ]
}

Handle

Gli handle sono puntatori a struct opachi. In C, si potrebbero rappresentare come void * o struct{} *.

Hanno le seguenti chiavi:

is_const: se true, questo tipo di handle deve essere trattato come un "puntatore costante", il che significa che i suoi dati interni non saranno modificati. Il valore predefinito è false.
is_uninitialized: se true, questo tipo di handle deve essere trattato come puntatore a memoria non inizializzata (che può essere inizializzata tramite funzioni di interfaccia). Il valore predefinito è false.
parent: il nome facoltativo di un altro tipo di handle, se questo tipo di handle è la versione const o non inizializzata del tipo padre. Ciò ha senso solo se is_const o is_uninitialized sono true.

Gli handle sono grandi quanto i puntatori su una specifica architettura (ad esempio, 64 bit su x86_64 e 32 bit su x86_32).

Esempio

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

Alias

Gli alias sono nomi alternativi per un tipo. In C, si potrebbero rappresentare come un typedef.

Hanno solo una chiave in più:

type: il tipo per cui l'alias è un nome alternativo. Può includere modificatori come descritto sopra.

Questi si dovrebbero rappresentare utilizzando lo stesso tipo C del tipo a cui fanno riferimento.

Esempio

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

Struct

Le struct rappresentano le structs del linguaggio C (ovvero blocchi di memoria composti dai membri specificati nell'ordine indicato) e devono seguire tutte le stesse regole di disposizione e allineamento delle struct nel linguaggio C.

Hanno solo una chiave in più:

members: un array di oggetti che hanno un nome (name), un tipo (type) (che può includere modificatori) e una descrizione (description).

Esempio

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

Funzioni

Le funzioni rappresentano tipi di puntatore a funzioni C, con un elenco di argomenti e un tipo restituito, e devono rispettare gli stessi requisiti di dimensione e allineamento dei puntatori a funzioni C.

Hanno i seguenti membri:

return_value: un oggetto che ha un tipo (type) (che può includere modificatori) e una descrizione (description). Se la funzione non ha un valore restituito, questo sarà omesso.
arguments (obbligatorio): un array di argomenti di funzione, ognuno dei quali ha un tipo (type) (che può includere modificatori), un nome (name) e una descrizione (description).

Esempio

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

Interfaccia

La sezione interface del file JSON è l'elenco delle funzioni di interfaccia, che si possono caricare per nome (name) attraverso il puntatore a funzione GDExtensionInterfaceGetProcAddress, che è passato a tutte le GDExtension al momento del loro caricamento.

Le funzioni di interfaccia condividono alcune chiavi con i tipi, tra cui name (obbligatorio), deprecated e description.

Inoltre, includono return_value e arguments (obbligatori) che hanno lo stesso formato delle chiavi equivalenti sui tipi di funzione (come descritto nella sezione precedente).

Esiste solo qualche unica chiave:

since (obbligatorio): la versione di Godot che ha introdotto questa funzione di interfaccia.
see: un array di stringhe che descrivono riferimenti esterni con maggiori informazioni, ad esempio, nomi di classi o funzioni nel codice sorgente di Godot, oppure URL che puntano alla documentazione.
legacy_type_name: Il nome legacy utilizzato per il tipo di puntatore a funzione nell'intestazione generata da Godot, quando il nome legacy non corrisponde allo schema utilizzato per questi nomi di tipo. Questo campo esiste solo per poter generare l'intestazione in modo che sia retrocompatibile con l'intestazione di Godot 4.5 o precedenti, e non si dovrebbe utilizzare a meno che non sia necessario mantenere la compatibilità anche con la vecchia intestazione.

Esempio

{
    "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"
    }
}