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

The C interface JSON file

The gdextension_interface.json file is the "source of truth" for the C API that Godot uses to communicate with GDExtensions.

You can use the Godot executable to dump the file by using the following command:

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.

Note

This is not to be confused with the extension_api.json, which is also used by GDExtension language bindings, and contains information about the classes and methods that are exposed by Godot. The gdextension_interface.json is more low-level, and is used to interact with those higher-level classes and methods.

For languages that can be extended via C, or provide tools for interacting with C code, it's also possible to use the Godot executable to dump a generated C header file:

godot --headless --dump-gdextension-interface

Note

The header file is compatible with earlier versions of the header file that were included with Godot 4.5 and earlier, which means it preserves some typos in names in order to ensure compatibility.

The goal of this page is to explain the JSON format for the GDExtension language bindings that would like to do their own code generation from the JSON.

Overall structure

The JSON file is broken up into 3 sections:

The header, which includes some miscellaneous information at the top-level of the JSON file.
The types key, which defines all the types used in the GDExtension interface.
The interface key, which defines all the function pointers that can be loaded via the GDExtensionInterfaceGetProcAddress function pointer, which is passed to all GDExtensions when they are loaded.

There is a complete JSON schema included in Godot's source code.

Even though we may add new types and interface functions with each minor release of Godot, we strive to never change them in a backwards incompatible way, or remove them. Every interface function is labeled with the version of Godot it was introduced in (the since key), so you can always use the latest version of the file, and simply refrain from using anything in versions of Godot that are newer than the version you are targeting.

Header

The "header" is made up of 3 miscellaneous keys at the top-level of the file:

_copyright: The standard copyright and license text that Godot includes in all source code files.
$schema: Points to the JSON schema relative to this file. It can be useful to place the schema in the same directory, if you're viewing it with a code editor that understands JSON schema.
format_version: An integer for the version of the file format (meaning the schema). Right now, there is only one format version (1). If we ever change the file format in an incompatible way, we will increment this number. This doesn't reflect the version of the data in the file (so it won't change between Godot versions), only its format. Hopefully, we'll never have to use it, but it allows code generators to error early if they encounter an unexpected value here.

Types

The types section is an array of types that will be used by other types, and the interface functions that will be in the last section.

The types should be evaluated in order. Later types may refer to earlier types, but earlier types will not refer to later types.

There is a small set of built-in types which aren't explicitly listed in the JSON:

void
int8_t
uint8_t
int16_t
uint16_t
int32_t
uint32_t
int64_t
uint64_t
size_t (uint32_t on 32-bit architectures, and uint64_t on 64-bit architectures)
char
char16_t
char32_t
wchar_t
float
double

These correspond to their equivalent C types.

Additionally, types can include modifiers such as:

* (e.g. int8_t*) to indicate a pointer to the type
const (e.g. const int8_t*) to indicate a const type

Each type defined in the JSON file falls into one of 5 "kinds":

enum
handle
alias
struct
function

Regardless of the "kind", all types can have the following keys:

kind (required): The type's "kind".
name (required): The name of the type, which could be used as a valid C identifier.
description: An array of strings documenting the type, where each string is a line of documentation (this format for description is used throughout the JSON file).
deprecated: An object with its own keys for the Godot version the type was deprecated in (since), a message explaining the deprecation (message), and optionally a replacement to use instead (replacement).

Enums

Enums are 32-bit integers with a fixed set of possible values. In C, they could be represented as an enum.

They have the following keys:

is_bitfield: If true, this enum is a bitfield, where the enum values can be bitwise OR'd together. It is false by default.
values: The array of fixed values for this enum, each with a name, value, and description.

An enum should be represented as an int32_t, unless is_bitfield is true, in which case a uint32_t should be used.

Example

{
    "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 are pointers to opaque structs. In C, they could be represented as void * or struct{} *.

They have the following keys:

is_const: If true, this handle type is to be treated as a "const pointer", meaning its internal data will not be changed. It is false by default.
is_uninitialized: If true, this handle type is to be treated as pointing to uninitialized memory (which may be initialized using interface functions). It is false by default.
parent: The optional name of another handle type, if this handle type is the const or uninitialized version of the parent type. This only makes sense if either is_const or is_uninitialized is true.

Handles are the size of pointers on the given architecture (so, 64-bit on x86_64 and 32-bit on x86_32, for example).

Example

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

Aliases

Aliases are alternative names for a type. In C, they could be represented as a typedef.

They have only one additional key:

type: The type the alias is an alternative name for. It may include modifiers as described above.

These should be represented using the same C type as the type they refer to.

Example

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

Structs

Structs represent C structs (aka a block of memory made up of the given members in order), and should follow all the same layout and alignment rules as C structs.

They have only one additional key:

members: An array of objects which have a name, type (which may include modifiers), and description.

Example

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

Functions

Functions represent C function pointer types, with a list of arguments and a return type, and should follow the same size and alignment requirements as C function pointers.

They have the following members:

return_value: An object which has a type (which may include modifiers) and description. If the function has no return value, this will be omitted.
arguments (required): An array of function arguments which each has a type (which may include modifiers), name, and description.

Example

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

Interface

The interface section of the JSON file is the list of interface functions, which can be loaded by name using the GDExtensionInterfaceGetProcAddress function pointer, which is passed to all GDExtensions when they are loaded.

Interface functions have some of the same keys as types, including name (required), deprecated, and description.

And they also have return_value and arguments (required) that have the same format as the equivalent keys on function types (as described in the previous section).

There are only a handful of unique keys:

since (required): The Godot version that introduced this interface function.
see: An array of strings describing external references with more information, for example, names of classes or functions in the Godot source code, or URLs pointing to documentation.
legacy_type_name: The legacy name used for the function pointer type in the header generated by Godot, when the legacy name doesn't match the pattern used for these type names. This field only exists so that we can generate the header in a way that is backwards compatible with the header from Godot 4.5 or earlier, and it shouldn't be used unless you also need to maintain compatibility with the old header.

Example

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