Add documentation page about gdextension_interface.json
#11551
Conversation
dsnopek
force-pushed
the
gdextension-interface-json
branch
from
3a1c259 to
9541b14
Compare
dsnopek
changed the title
gdextension_interface.jsongdextension_interface.json
dsnopek
force-pushed
the
gdextension-interface-json
branch
from
9541b14 to
6cc4e3a
Compare
dsnopek
force-pushed
the
gdextension-interface-json
branch
from
6cc4e3a to
2070544
Compare
|
This page needs a shorter title, because it gets weird line breaks currently: 
Any suggestions? It could be "GDExtension interface JSON" maybe? |
Bromeon
left a comment
Bromeon
left a comment
There was a problem hiding this comment.
Great writeup, thanks a lot 👍 I especially like the examples after each section, they clarify a lot!
| The ``gdextension_interface.json`` file is the canonical definition of 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: | ||
|
|
||
| .. code-block:: shell | ||
| 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. |
There was a problem hiding this comment.
Maybe we should briefly mention that there's also extension_api.json, and how the two differ? Especially since there are a lot of existing references to "the API JSON", which can now become ambiguous.
There was a problem hiding this comment.
(On that topic, see also my other comment #11551 (comment))
| 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 type-o's in names in order to | ||
| ensure compatibility. These "legacy names" can be found in the ``legacy_type_name`` key | ||
| in the JSON file. |
There was a problem hiding this comment.
I've never seen this spelling of "type-o", always "typo" 🙂 does it not come from "typographical error"?
|
|
||
| Even though we may add a little bit to this file with each minor release of Godot, we strive | ||
| to **never** change anything in a backwards incompatible way, or remove anything. Every type | ||
| and interface function is labeled with the version of Godot it was introduce in (the ``since`` |
There was a problem hiding this comment.
| and interface function is labeled with the version of Godot it was introduce in (the ``since`` | |
| and interface function is labeled with the version of Godot it was introduced in (the ``since`` |
| Even though we may add a little bit to this file with each minor release of Godot, we strive | ||
| to **never** change anything in a backwards incompatible way, or remove anything. Every type | ||
| and interface function is labeled with the version of Godot it was introduce 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. |
There was a problem hiding this comment.
This slightly contradicts the format_version just specified below, which foresees breaking changes (even if unlikely). Maybe it should be referenced here, or maybe it's OK since the format_version is explained pretty much afterwards?
| Types | ||
| ----- | ||
|
|
||
| The "types" section is an array of types that will be used by other types, and the interface |
There was a problem hiding this comment.
| The "types" section is an array of types that will be used by other types, and the interface | |
| The ``types`` section is an array of types that will be used by other types, and the interface |
Clarifies that the JSON key is verbatim types.
| - ``uint32_t`` | ||
| - ``int64_t`` | ||
| - ``uint64_t`` | ||
| - ``size_t`` |
There was a problem hiding this comment.
Should the size of size_t be specified? Does it vary between Godot-supported platforms?
| Regardless of the "kind", all types can have the following keys: | ||
|
|
||
| - ``name``: 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 through out the JSON file). | ||
| - ``since``: The Godot version that introduced this type. | ||
| - ``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``). |
There was a problem hiding this comment.
Maybe it should be explicitly mentioned that kind is one of the JSON keys.
Should we document that name/kind are required and the others are optional? Or is it enough if that's part of the JSON schema?
| ``name`` using the ``GDExtensionInterfaceGetProcAddress`` function pointer, which is passed to all | ||
| GDExtensions when they are loaded. | ||
|
|
||
| They have some of the same keys as types, including ``name``, ``since``, ``deprecated``, and |
There was a problem hiding this comment.
"They" is slightly ambiguous, as you mentioned "GDExtensions" last.
| They have some of the same keys as types, including ``name``, ``since``, ``deprecated``, and | |
| Interface functions have some of the same keys as types, including ``name``, ``since``, ``deprecated``, and |
| And they also have ``return_value`` and ``arguments`` that have the same format as the keys of the | ||
| same name on function types, as described in the previous section. |
There was a problem hiding this comment.
Maybe it's my non-native English, but "as .. of .. on .. as" is a bit heavy to digest here
| And they also have ``return_value`` and ``arguments`` that have the same format as the keys of the | |
| same name on function types, as described in the previous section. | |
| And they also have ``return_value`` and ``arguments`` that have the same format as the equivalent keys | |
| on function types, as described in the previous section. |
Or maybe "corresponding" or "same-named" or so. Or put the "as described..." part in parentheses -- many ways to break it up a bit.
In the future, there might be a section about the I'm not sure if "interface JSON" and "API JSON" are clear enough because the "I" in "API" is also "interface". Would a different term make sense here? In Rust I will likely keep using "header", which isn't very precise, but at least distinct enough for all practical purposes. One defines the actual C interface (or FFI), while the other is more a specification/definition of concrete engine symbols (classes, enums, etc.)... Maybe some inspiration here? |
2 participants
This adds documentation on the
gdextension_interface.jsonfile that was added in PR godotengine/godot#107845It attempts to address the remaining issues brought up on godotengine/godot#113732
cc @Bromeon
Fixes godotengine/godot#113732