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

C 接口 JSON 文件

gdextension_interface.json 文件是 Godot 用于与 GDExtensions 通信的 C API 的“真理之源”。

你可以通过以下命令，使用 Godot 可执行文件来转储文件：

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

此文件旨在供 GDExtension 语言绑定使用，以生成使用此 API 的代码，并以最适合该语言的形式呈现。

备注

请勿将此文件与 extension_api.json 混淆，后者也由 GDExtension 语言绑定使用，其中包含 Godot 公开的类和方法的相关信息。 gdextension_interface.json 更底层 ，用于与这些更高级别的类和方法进行交互。

对于可以通过 C 语言扩展或提供与 C 代码交互工具的语言，也可以使用 Godot 可执行文件来转储生成的 C 语言的头文件：

godot --headless --dump-gdextension-interface

备注

该头文件与 Godot 4.5 及更早版本中所包含的头文件兼容，这意味着它保留了一些名称拼写错误以确保兼容性 。

本页的目标是解释 GDExtension 语言绑定的 JSON 格式，以便它们能够根据 JSON 生成自己的代码。

整体结构

JSON 文件分为 3 个部分：

  • 头部信息，其中包含 JSON 文件顶层的一些杂项信息。

  • types 键定义了 GDExtension 接口中使用的所有类型。

  • interface 键定义了所有可以通过 GDExtensionInterfaceGetProcAddress 函数指针加载的函数指针，该函数指针会在加载所有 GDExtension 时传递给它们。

Godot 的源代码中包含一个完整的 JSON schema 。

尽管我们可能会在 Godot 的每个小版本更新中添加新的类型和接口函数，但我们力求绝不以不兼容的方式更改或移除它们。每个接口函数都标有引入它的 Godot 版本（since 键），因此你可以始终使用文件的最新版本，只需避免使用比目标版本更新的 Godot 版本中的任何内容即可。

类型

types 部分是一个类型数组，其将被其他类型以及在最后一节出现的接口函数使用。

这些类型应当按顺序求值。后面的类型可以引用前面的类型，但前面的类型不能引用后面的类型。

有一小部分内置类型没有在 JSON 中明确列出：

  • void

  • int8_t

  • uint8_t

  • int16_t

  • uint16_t

  • int32_t

  • uint32_t

  • int64_t

  • uint64_t

  • size_t（32 位架构为 uint32_t，64 位架构为 uint64_t）

  • char

  • char16_t

  • char32_t

  • wchar_t

  • float

  • double

这些与它们对应的 C 类型相对应。

此外，类型还可以包含以下修饰符：

  • *（例如 int8_t*）表示指向该类型的指针

  • const（例如 const int8_t*）表示常量类型

在 JSON 文件中定义的每一个类型都属于五种“类别”之一：

  • enum

  • handle

  • alias

  • struct

  • function

无论是何种“类别”，所有的类型均可包含以下键：

  • kind（必填）：该类型的“类别”。

  • name（必填）：该类型的名称，可作为有效的 C 标识符。

  • description：一个描述该类型的字符串数组，每个字符串为文档的一行（此 description 格式在整个 JSON 文件中通用）。

  • deprecated：一个包含以下键的对象：该类型被弃用时的 Godot 版本号（since），弃用原因（message），以及选填的替代项（replacement）。

枚举

枚举是所有可能取值在固定集合内的 32 位整数。在 C 语言中，它们可以表示为 enum。

它们有以下键：

  • is_bitfield：如果为 true，则此枚举是一个位域，其枚举值可以用位或组合。默认为 false。

  • values：此枚举的所有固定取值组成的数组。每个取值包含名称（name）、值（value）以及说明（description）。

枚举类型应当表示为 int32_t；但如果 is_bitfield 为 true，则应使用 uint32_t。

示例

{
    "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）是指向不透明结构体（opaque structs）的指针。在 C 语言中，它们可以被表示为 void * 或者 struct{} * 。

它们有以下键：

  • is_const：如果为 true，则此句柄类型将被视为“常量指针”，意味着其内部数据不会被更改。默认情况下为 false。

  • is_uninitialized\ ：如果为 true，则此句柄类型应被视为指向未初始化的内存（可以使用接口函数初始化）。默认值为 false。

  • parent：选填，父句柄类型的名称，当此句柄类型是父类型的常量或未初始化版本时使用。只有当 is_const 或 is_uninitialized 为 true 时，此键才有意义。

句柄的大小与给定架构上的指针大小相同（例如，在 x86_64 上为 64 位，在 x86_32 上为 32 位）。

示例

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

别名

别名是一种类型的替代名称。在 C 语言中，它可以表示为 typedef。

它们仅有一个额外的键：

  • type：别名所替代的原始类型。它可以包含前文描述的修饰符。

它们应当使用与所对应原始类型相同的 C 类型来表示。

示例

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

结构体

结构体表示 C 的 struct（也就是由给定成员按顺序组成的一块内存），并且应遵循所有与 C 结构体相同的布局和对齐规则。

它们仅有一个额外的键：

  • members （成员）：一个对象数组，每个对象都包含 name （名称）、 type （类型，可能包含修饰符）以及 description （描述）。

示例

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

函数

函数（Functions）代表 C 语言的函数指针类型，它包含一个参数列表和一个返回类型，并且应当遵循与 C 语言函数指针相同的大小和对齐要求。

它们含有如下成员：

  • return_value （返回值）：一个包含 type （类型，可能包含修饰符）和 description （描述）的对象。如果该函数没有返回值，则省略此项。

  • arguments （必需）：一个由函数参数组成的数组，每个参数都包含 type （类型，可能包含修饰符）、 name （名称）和 description （描述）。

示例

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

接口

JSON 文件中的 interface 部分是一系列接口函数的列表。你可以通过 name （函数名）来加载这些函数，而加载时所使用的 GDExtensionInterfaceGetProcAddress 函数指针，会在所有 GDExtension 扩展被加载时传递进来。

接口函数（Interface functions）拥有一些与类型（types）相同的键（keys），其中包括 name （名称，必填项）、 deprecated （已弃用）以及 description （描述）。

而且，它们还包含 return_value （返回值）和 arguments （参数，必填项），这两者的格式与函数类型中对应的键完全相同（正如上一节所描述的那样）。

只有少量的几个唯一键：

  • since （必填项）：引入该接口函数的 Godot 版本。

  • see ：一个字符串数组，用于描述包含更多信息的外部引用。例如，Godot 源代码中的类名或函数名，或者是指向相关文档的网址（URL）。

  • legacy_type_name ：当函数指针类型的旧名称不符合当前类型名称的命名模式时，Godot 生成的头文件中会使用这个旧名称。该字段存在的唯一目的，是为了让我们能够以向后兼容的方式生成头文件，使其与 Godot 4.5 或更早版本的头文件保持一致。除非你也需要维护与旧版头文件的兼容性，否则不应使用此字段。

示例

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