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

JSON-файл інтерфейсу C

Файл gdextension_interface.json є «джерелом достовірності» для C API, який Godot використовує для зв'язку з GDExtensions.

Ви можете скористатися виконуваним файлом 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 та попередніх версій, що означає, що він зберігає деякі друкарські помилки в іменах, щоб забезпечити сумісність.

Мета цієї сторінки — пояснити формат JSON для мовних прив'язок GDExtension, які бажають самостійно генерувати код з JSON.

Загальна структура

JSON-файл розділений на 3 частини:

Заголовок, який містить деяку різноманітну інформацію на верхньому рівні JSON-файлу.
Ключ types, який визначає всі типи, що використовуються в інтерфейсі GDExtension.
Ключ interface, який визначає всі вказівники на функції, що можуть бути завантажені через вказівник функції GDExtensionInterfaceGetProcAddress, що передається всім GDExtensions під час їх завантаження.

У вихідному коді Godot є повна JSON-схема.

Навіть попри те, що ми можемо додавати нові типи та функції інтерфейсу з кожним незначним випуском Godot, ми прагнемо ніколи не змінювати їх у зворотній спосіб, несумісний зі стандартною версією, або видаляти їх. Кожна функція інтерфейсу позначена версією Godot, у якій вона була введена (ключ since), тому ви завжди можете використовувати останню версію файлу та просто утримуватися від використання будь-чого у версіях Godot, новіших за ту, на яку ви орієнтуєтесь.

Заголовок

«Заголовок» складається з 3 різних ключів на верхньому рівні файлу:

_copyright: Стандартний текст авторських прав та ліцензії, який Godot включає до всіх файлів вихідного коду.
$schema: Вказує на схему JSON відносно цього файлу. Може бути корисним розмістити схему в тому ж каталозі, якщо ви переглядаєте її за допомогою редактора коду, який розуміє схему JSON.
format_version: Ціле число для версії формату файлу (тобто схеми). Наразі існує лише одна версія формату (1). Якщо ми коли-небудь змінимо формат файлу несумісним чином, ми збільшимо це число. Це не відображає версію даних у файлі (тому він не змінюватиметься між версіями Godot), лише його формат. Сподіваємося, нам ніколи не доведеться це використовувати, але це дозволяє генераторам коду видавати помилки завчасно, якщо вони зіткнуться з неочікуваним значенням тут.

Типи

Розділ types — це масив типів, які будуть використовуватися іншими типами, та функції інтерфейсу, які будуть в останньому розділі.

Типи слід оцінювати по порядку. Пізніші типи можуть посилатися на попередні типи, але попередні типи не посилатимуться на пізніші типи.

Існує невеликий набір вбудованих типів, які явно не перелічені в JSON:

void
int8_t
uint8_t
int16_t
uint16_t
int32_t
uint32_t
int64_t
uint64_t
size_t (uint32_t на 32-бітних архітектурах та uint64_t на 64-бітних архітектурах)
char
char16_t
char32_t
wchar_t
float
double

Вони відповідають еквівалентним типам C.

Крім того, типи можуть містити модифікатори, такі як:

* (наприклад, int8_t*) для позначення вказівника на тип
const (наприклад, const int8_t*) для позначення константного типу

Кожен тип, визначений у JSON-файлі, належить до одного з 5 «видів»:

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

Ручки

Десктопи — це вказівники на непрозорі структури. У C їх можна представити як void * або struct{} *.

Вони мають такі ключі:

is_const: Якщо значення true, цей тип дескриптора слід розглядати як «константний вказівник», тобто його внутрішні дані не будуть змінені. За замовчуванням значення false.
is_uninitialized: Якщо значення true, цей тип дескриптора слід розглядати як вказівник на неініціалізовану пам'ять (яку можна ініціалізувати за допомогою функцій інтерфейсу). За замовчуванням значення false.
parent: Необов'язкова назва іншого типу дескриптора, якщо цей тип дескриптора є константною або неініціалізованою версією батьківського типу. Це має сенс лише тоді, коли is_const або is_uninitialized мають значення true.

Десктопи – це розмір вказівників на заданій архітектурі (наприклад, 64-бітна на x86_64 та 32-бітна на x86_32).

Приклад

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

Псевдоніми

Псевдоніми – це альтернативні назви для типу. У C їх можна представити як typedef.

У них є лише один додатковий ключ:

type: Тип, для якого псевдонім є альтернативною назвою. Він може містити модифікатори, як описано вище.

Вони повинні бути представлені з використанням того ж типу C, що й тип, на який вони посилаються.

Приклад

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

Структури

Структури представляють собою C-structs (тобто блок пам'яті, що складається з заданих членів по порядку) і повинні дотримуватися тих самих правил розміщення та вирівнювання, що й C-структури.

У них є лише один додатковий ключ:

члени: Масив об'єктів, що мають ім'я, тип (який може включати модифікатори) та опис.

Приклад

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

Функції

Функції представляють типи вказівників на функції C зі списком аргументів та типом повернення, і повинні відповідати тим самим вимогам до розміру та вирівнювання, що й вказівники на функції C.

Вони мають таких членів:

return_value: Об'єкт, який має type (який може включати модифікатори) та description. Якщо функція не має повертаного значення, це буде пропущено.
аргументи (обов'язково): Масив аргументів функції, кожен з яких має тип (який може включати модифікатори), назва та опис.

Приклад

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

Інтерфейс

Розділ interface JSON-файлу — це список функцій інтерфейсу, які можна завантажити за допомогою name, використовуючи вказівник функції GDExtensionInterfaceGetProcAddress, який передається всім GDExtensions під час їх завантаження.

Функції інтерфейсу мають деякі з тих самих ключів, що й типи, зокрема 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"
    }
}