Skip to content

Commit 3a1c259

Browse files
dsnopekdsnopek
committed
Add documentation page about gdextension_interface.json 
1 parent 3770ad6 commit 3a1c259

File tree

2 files changed

+345
-0
lines changed

2 files changed

+345
-0
lines changed

‎tutorials/scripting/gdextension/gdextension_interface_json_file.rst‎

Lines changed: 344 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,344 @@
1+
.. _doc_gdextension_interface_json_file:
2+
3+
The gdextension_interface.json file
4+
===================================
5+
6+
The ``gdextension_interface.json`` file is the canonical definition of the C API that
7+
Godot uses to communicate with GDExtensions.
8+
9+
You can use the Godot executable to dump the file by using the following command:
10+
11+
.. code-block:: shell
12+
13+
godot --headless --dump-gdextension-interface-json
14+
15+
This file is intended to be used by GDExtension language bindings to generate code for
16+
using this API in whatever form makes the most sense for that language.
17+
18+
For languages that can be extended via C, or provide tools for interacting with C code,
19+
it's also possible to use the Godot executable to dump a generated C header file:
20+
21+
.. code-block:: shell
22+
23+
godot --headless --dump-gdextension-interface
24+
25+
.. note::
26+
27+
The header file is compatible with earlier versions of the header file that were included
28+
with Godot 4.5 and earlier, which means it preserves some type-o's in names in order to
29+
ensure compatibility. These "legacy names" can be found in the ``legacy_type_name`` key
30+
in the JSON file.
31+
32+
The goal of this page is to explain the JSON format for the GDExtension language bindings that
33+
would like to do their own code generation from the JSON.
34+
35+
Overall structure
36+
-----------------
37+
38+
The JSON file is broken up into 3 sections:
39+
40+
- The header, which includes some miscellaneous information at the top-level of the JSON file.
41+
- The ``types`` key, which defines all the types used in the GDExtension interface.
42+
- The ``interface`` key, which defines all the function pointers that can be loaded via
43+
``GDExtensionInterfaceGetProcAddress`` function pointer, which is passed to all GDExtensions
44+
when they are loaded.
45+
46+
There is a complete `JSON schema <https://github.com/godotengine/godot/blob/master/core/extension/gdextension_interface.schema.json>`__
47+
included in Godot's source code.
48+
49+
Even though we may add a little bit to this file with each minor release of Godot, we strive
50+
to **never** change anything in a backwards incompatible way, or remove anything. Every type
51+
and interface function is labeled with the version of Godot it was introduce in (the ``since``
52+
key), so you can always use the latest version of the file, and simply refrain from using
53+
anything in versions of Godot that are newer than the version you are targeting.
54+
55+
Header
56+
------
57+
58+
The "header" is made up of 3 miscellaneous keys at the top-level of the file:
59+
60+
- ``_copyright``: The standard copyright and license text that Godot includes in all source
61+
code files.
62+
- ``$schema``: Points to the JSON schema relative to this file (it can be useful to place
63+
the schema in the same directory, if you're viewing it with a code editor that understands
64+
JSON schema).
65+
- ``format_version``: An integer for the version of the file format. Right now, there is
66+
only one format version (``1``), if we ever change the file format in an incompatible way,
67+
we will increment this number. This this *doesn't* reflect the version of the data (so it
68+
won't change between Godot versions), only the format of the file. Hopefully, we'll never
69+
have to use it, but it allows code generators to error early if they encounter an unexpected
70+
value here.
71+
72+
Types
73+
-----
74+
75+
The "types" section is an array of types that will be used by other types, and the interface
76+
functions that will be in the last section.
77+
78+
The types should be evaluated in order. Later types may refer to earlier types, but earlier
79+
types will not refer to later types.
80+
81+
There is a small set of built-in types which aren't explicitly listed in the JSON:
82+
83+
- ``void``
84+
- ``int8_t``
85+
- ``uint8_t``
86+
- ``int16_t``
87+
- ``uint16_t``
88+
- ``int32_t``
89+
- ``uint32_t``
90+
- ``int64_t``
91+
- ``uint64_t``
92+
- ``size_t``
93+
- ``char``
94+
- ``char16_t``
95+
- ``char32_t``
96+
- ``wchar_t``
97+
- ``float``
98+
- ``double``
99+
100+
These correspond to their equivalent C types.
101+
102+
Additionally, types can include modifiers such as:
103+
104+
- ``*`` (ex ``int8_t*``) to indicate a pointer to the type
105+
- ``const`` (ex ``const int8_t*``) to indicate a const type
106+
107+
Each type defined in the JSON file falls into one of 5 "kind"s:
108+
109+
- ``enum``
110+
- ``handle``
111+
- ``alias``
112+
- ``struct``
113+
- ``function``
114+
115+
Regardless of the "kind", all types can have the following keys:
116+
117+
- ``name``: The name of the type, which could be used as a valid C identifier.
118+
- ``description``: An array of strings documenting the type, where each string is a line of
119+
documentation (this format for ``description`` is used through out the JSON file).
120+
- ``since``: The Godot version that introduced this type.
121+
- ``deprecated``: An object with its own keys for the Godot version the type was deprecated in
122+
(``since``), a message explaining the deprection (``message``) and optionally a replacement
123+
to use instead (``replacement``).
124+
125+
Enums
126+
~~~~~
127+
128+
Enums are 32-bit integers with a fixed set of possible values. In C, they could be represented
129+
as an ``enum``.
130+
131+
They have the following keys:
132+
133+
- ``is_bitfield``: If true, this enum is a bitfield, where the enum values can be bitwise OR'd together.
134+
It is false by default.
135+
- ``values``: The array of fixed values for this enum, each with a ``name``, ``value`` and ``description``.
136+
137+
An enum should be represented as an ``int32_t``, unless ``is_bitfield`` is true, in which case a ``uint32_t``
138+
should be used.
139+
140+
Example
141+
+++++++
142+
143+
.. code-block:: json
144+
145+
{
146+
"name": "GDExtensionInitializationLevel",
147+
"kind": "enum",
148+
"values": [
149+
{
150+
"name": "GDEXTENSION_INITIALIZATION_CORE",
151+
"value": 0
152+
},
153+
{
154+
"name": "GDEXTENSION_INITIALIZATION_SERVERS",
155+
"value": 1
156+
},
157+
{
158+
"name": "GDEXTENSION_INITIALIZATION_SCENE",
159+
"value": 2
160+
},
161+
{
162+
"name": "GDEXTENSION_INITIALIZATION_EDITOR",
163+
"value": 3
164+
},
165+
{
166+
"name": "GDEXTENSION_MAX_INITIALIZATION_LEVEL",
167+
"value": 4
168+
}
169+
]
170+
}
171+
172+
Handles
173+
~~~~~~~
174+
175+
Handles are pointers to opaque structs. In C, they could be represented as ``void *`` or ``struct{} *``.
176+
177+
They have the following keys:
178+
179+
- ``is_const``: If true, this handle type is to be treated as a "const pointer", meaning it's internal
180+
data will not be changed. It is false by default.
181+
- ``is_uninitialized``: If true, this handle type is to be treated as pointing to uninitialized memory
182+
(which may be initialized using interface functions).
183+
- ``parent``: The optional name of another handle type, if this handle type is the const or uninitialized
184+
version of the parent type.
185+
186+
Handles are the size of pointers on the given architecture (so, 64-bit on x86_64 and 32-bit on x86_32,
187+
for example).
188+
189+
Example
190+
+++++++
191+
192+
.. code-block:: json
193+
194+
{
195+
"name": "GDExtensionStringNamePtr",
196+
"kind": "handle"
197+
}
198+
199+
Aliases
200+
~~~~~~~
201+
202+
Aliases are alternative names for another type. In C, they could be represented with a ``typedef``.
203+
204+
They have only one additional key:
205+
206+
- ``type``: The type the alias is an alternative name for. It may include modifiers as described above.
207+
208+
These should be represented using the same C type as the type they point to, except when a pointer
209+
modifier is used (in which case, they should be represented as pointers).
210+
211+
Example
212+
+++++++
213+
214+
.. code-block:: json
215+
216+
{
217+
"name": "GDExtensionInt",
218+
"kind": "alias",
219+
"type": "int64_t"
220+
}
221+
222+
Structs
223+
~~~~~~~
224+
225+
Structs represent C ``struct``s (aka a block of memory made up the given members in order), and should
226+
follow all the same layout and alignment rules as C structs.
227+
228+
They have only one additional key:
229+
230+
- ``members``: An array of objects which have a ``name``, ``type`` (which may include modifiers) and
231+
``description``.
232+
233+
Example
234+
+++++++
235+
236+
.. code-block:: json
237+
238+
{
239+
"name": "GDExtensionCallError",
240+
"kind": "struct",
241+
"members": [
242+
{
243+
"name": "error",
244+
"type": "GDExtensionCallErrorType"
245+
},
246+
{
247+
"name": "argument",
248+
"type": "int32_t"
249+
},
250+
{
251+
"name": "expected",
252+
"type": "int32_t"
253+
}
254+
]
255+
}
256+
257+
Functions
258+
~~~~~~~~~
259+
260+
Functions represent C function pointer types, with a list of arguments and a return type, and should
261+
follow the same size and alignment requirements as C function pointers.
262+
263+
They have the following members:
264+
265+
- ``return_value``: An object which has a ``type`` (which may include modifiers), and description.
266+
It will always be given, and use ``void`` as the ``type`` if the function returns no value.
267+
- ``arguments``: An array of function arguments which each has a ``type`` (which may include modifiers),
268+
a ``name`` and ``description``.
269+
270+
271+
Example
272+
+++++++
273+
274+
.. code-block:: json
275+
276+
{
277+
"name": "GDExtensionPtrConstructor",
278+
"kind": "function",
279+
"return_value": {
280+
"type": "void"
281+
},
282+
"arguments": [
283+
{
284+
"name": "p_base",
285+
"type": "GDExtensionUninitializedTypePtr"
286+
},
287+
{
288+
"name": "p_args",
289+
"type": "const GDExtensionConstTypePtr*"
290+
}
291+
]
292+
}
293+
294+
Interface
295+
---------
296+
297+
The final section of the JSON file is the list of interface functions, which can be loaded by their
298+
``name`` using the ``GDExtensionInterfaceGetProcAddress`` function pointer, which is passed to all
299+
GDExtensions when they are loaded.
300+
301+
They have some of the same keys as types, including ``name``, ``since``, ``deprecated``, and
302+
``description``.
303+
304+
And they also have ``return_value`` and ``arguments`` that have the same format as the keys of the
305+
same name on function types, as described in the previous section.
306+
307+
There are only a handful of unique, miscellaneous fields:
308+
309+
- ``see``: An array of strings describing external references with more information, for example,
310+
names of classes or functions in the Godot source code, or URLs pointing to documentation.
311+
- ``legacy_type_name``: The legacy name used for the function pointer type in the header generated
312+
by Godot, when the original name used in the didn't match the pattern used for these type names.
313+
The field only exists so that we can generate the header in a way that is backwards compatible
314+
with the header from Godot 4.5 or earlier, and it shouldn't be used unless you also need to
315+
maintain compatibility with the old header.
316+
317+
Example
318+
+++++++
319+
320+
.. code-block:: json
321+
322+
{
323+
"name": "get_godot_version",
324+
"return_value": {
325+
"type": "void"
326+
},
327+
"arguments": [
328+
{
329+
"name": "r_godot_version",
330+
"type": "GDExtensionGodotVersion*",
331+
"description": [
332+
"A pointer to the structure to write the version information into."
333+
]
334+
}
335+
],
336+
"description": [
337+
"Gets the Godot version that the GDExtension was loaded into."
338+
],
339+
"since": "4.1",
340+
"deprecated": {
341+
"since": "4.5",
342+
"replace_with": "get_godot_version2"
343+
}
344+
}

‎tutorials/scripting/gdextension/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,4 @@ articles instead, such as the articles about :ref:`C++ (godot-cpp) <doc_godot_cp
2424
what_is_gdextension
2525
gdextension_file
2626
gdextension_c_example
27+
gdextension_interface_json_file

0 commit comments

Comments
 (0)