Skip to content

Commit ac0584d

Browse files
committed
Split C++ (godot-cpp) and GDExtension system info into separate categories, children of Scripting.
1 parent cb0009a commit ac0584d

15 files changed

+206
-162
lines changed

tutorials/scripting/gdextension/gdextension_c_example.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2162,5 +2162,5 @@ quite straightforward and not very verbose.
21622162

21632163
If you want to create actual extensions, it is preferred to use the C++ bindings
21642164
instead, as it takes away all of the boilerplate from your code. Check the
2165-
:ref:`GDExtension C++ example <doc_gdextension_cpp_example>` to see how you can
2165+
:ref:`GDExtension C++ example <doc_godot_cpp_getting_started>` to see how you can
21662166
do this.

tutorials/scripting/gdextension/gdextension_file.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Introduction
99
The ``.gdextension`` file in your project contains the instructions for how to load
1010
the GDExtension. The instructions are separated into specific sections. This page
1111
should give you a quick overview of the different options available to you. For an introduction
12-
how to get started with GDExtensions take a look at the :ref:`GDExtension C++ Example <doc_gdextension_cpp_example>`.
12+
how to get started with the C++ (godot-cpp), take a look at the :ref:`GDExtension C++ Example <doc_godot_cpp_getting_started>`.
1313

1414
Configuration section
1515
---------------------
Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,26 @@
11
:allow_comments: False
22

3-
GDExtension
4-
===========
3+
.. _doc_gdextension:
4+
5+
The GDExtension system
6+
======================
7+
8+
**GDExtension** is a Godot-specific technology that lets the engine interact with
9+
native `shared libraries <https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries>`__
10+
at runtime. You can use it to run native code without compiling it with the engine.
11+
12+
.. note:: GDExtension is *not* a scripting language and has no relation to
13+
:ref:`GDScript <doc_gdscript>`.
14+
15+
This section describes how GDExtension works, and is generally aimed at people wanting to make a GDExtension from
16+
scratch, for example to create language bindings. If you want to use existing language bindings, please refer to other
17+
articles instead, such as the articles about :ref:`C++ (godot-cpp) <doc_godot_cpp>` or one of the
18+
:ref:`community-made ones <doc_what_is_gdnative_third_party_bindings>`.
519

620
.. toctree::
721
:maxdepth: 1
8-
:name: toc-tutorials-gdnative
22+
:name: toc-tutorials-gdextension
923

1024
what_is_gdextension
11-
gdextension_cpp_example
12-
gdextension_c_example
1325
gdextension_file
14-
gdextension_docs_system
26+
gdextension_c_example

tutorials/scripting/gdextension/what_is_gdextension.rst

Lines changed: 1 addition & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -3,129 +3,4 @@
33
What is GDExtension?
44
====================
55

6-
Introduction
7-
------------
8-
9-
**GDExtension** is a Godot-specific technology that lets the engine interact with
10-
native `shared libraries <https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries>`__
11-
at runtime. You can use it to run native code without compiling it with the engine.
12-
13-
.. note:: GDExtension is *not* a scripting language and has no relation to
14-
:ref:`GDScript <doc_gdscript>`.
15-
16-
Differences between GDExtension and C++ modules
17-
-----------------------------------------------
18-
19-
You can use both GDExtension and :ref:`C++ modules <doc_custom_modules_in_cpp>` to
20-
run C or C++ code in a Godot project.
21-
22-
They also both allow you to integrate third-party libraries into Godot. The one
23-
you should choose depends on your needs.
24-
25-
.. warning::
26-
27-
GDExtension is currently *experimental*, which means that we may
28-
break compatibility in order to fix major bugs or include critical features.
29-
30-
Advantages of GDExtension
31-
~~~~~~~~~~~~~~~~~~~~~~~~~
32-
33-
Unlike modules, GDExtension doesn't require compiling the engine's source code,
34-
making it easier to distribute your work. It gives you access to most of the API
35-
available to GDScript and C#, allowing you to code game logic with full control
36-
regarding performance. It's ideal if you need high-performance code you'd like
37-
to distribute as an add-on in the :ref:`asset library <doc_what_is_assetlib>`.
38-
39-
Also:
40-
41-
- GDExtension is not limited to C and C++. Thanks to :ref:`third-party bindings
42-
<doc_what_is_gdnative_third_party_bindings>`, you can use it with many other
43-
languages.
44-
- You can use the same compiled GDExtension library in the editor and exported
45-
project. With C++ modules, you have to recompile all the export templates you
46-
plan to use if you require its functionality at runtime.
47-
- GDExtension only requires you to compile your library, not the whole engine.
48-
That's unlike C++ modules, which are statically compiled into the engine.
49-
Every time you change a module, you need to recompile the engine. Even with
50-
incremental builds, this process is slower than using GDExtension.
51-
52-
Advantages of C++ modules
53-
~~~~~~~~~~~~~~~~~~~~~~~~~
54-
55-
We recommend :ref:`C++ modules <doc_custom_modules_in_cpp>` in cases where
56-
GDExtension isn't enough:
57-
58-
- C++ modules provide deeper integration into the engine. GDExtension's access
59-
is not as deep as static modules.
60-
- You can use C++ modules to provide additional features in a project without
61-
carrying native library files around. This extends to exported projects.
62-
63-
.. note::
64-
65-
If you notice that specific systems are not accessible via GDExtension
66-
but are via custom modules, feel free to open an issue on the
67-
`godot-cpp repository <https://github.com/godotengine/godot-cpp>`__
68-
to discuss implementation options for exposing the missing functionality.
69-
70-
Supported languages
71-
-------------------
72-
73-
The Godot developers officially support the following language bindings for
74-
GDExtension:
75-
76-
- C++ :ref:`(tutorial) <doc_gdextension_cpp_example>`
77-
78-
.. note::
79-
80-
There are no plans to support additional languages with GDExtension officially.
81-
That said, the community offers several bindings for other languages (see
82-
below).
83-
84-
.. _doc_what_is_gdnative_third_party_bindings:
85-
86-
The bindings below are developed and maintained by the community:
87-
88-
.. Binding developers: Feel free to open a pull request to add your binding if it's well-developed enough to be used in a project.
89-
.. Please keep languages sorted in alphabetical order.
90-
91-
- `D <https://github.com/godot-dlang/godot-dlang>`__
92-
- `Go <https://github.com/grow-graphics/gd>`__
93-
- `Nim <https://github.com/godot-nim/gdext-nim>`__
94-
- `Rust <https://github.com/godot-rust/gdext>`__
95-
- `Swift <https://github.com/migueldeicaza/SwiftGodot>`__
96-
97-
.. note::
98-
99-
Not all bindings mentioned here may be production-ready. Make sure to
100-
research options thoroughly before starting a project with one of those.
101-
Also, double-check whether the binding is compatible with the Godot version
102-
you're using.
103-
104-
.. _doc_what_is_gdextension_version_compatibility:
105-
106-
Version compatibility
107-
---------------------
108-
109-
Usually, GDExtensions targeting an earlier version of Godot will work in later
110-
minor versions, but not vice-versa. For example, a GDExtension targeting Godot 4.2
111-
should work just fine in Godot 4.3, but one targeting Godot 4.3 won't work in Godot 4.2.
112-
113-
For this reason, when creating GDExtensions, you may want to target the lowest version of
114-
Godot that has the features you need, *not* the most recent version of Godot. This can
115-
save you from needing to create multiple builds for different versions of Godot.
116-
117-
However, GDExtension is currently *experimental*, which means that we may
118-
break compatibility in order to fix major bugs or include critical features.
119-
For example, GDExtensions created for Godot 4.0 aren't compatible with Godot
120-
4.1 (see :ref:`updating_your_gdextension_for_godot_4_1`).
121-
122-
GDExtensions are also only compatible with engine builds that use the same
123-
level of floating-point precision the extension was compiled for. This means
124-
that if you use an engine build with double-precision floats, the extension must
125-
also be compiled for double-precision floats and use an ``extension_api.json``
126-
file generated by your custom engine build. See :ref:`doc_large_world_coordinates`
127-
for details.
128-
129-
Generally speaking, if you build a custom version of Godot, you should generate an
130-
``extension_api.json`` from it for your GDExtensions, because it may have some differences
131-
from official Godot builds.
6+
Placeholder.
Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
.. _doc_about_godot_cpp:
2+
3+
About godot-cpp
4+
===============
5+
6+
`godot-cpp <https://github.com/godotengine/godot-cpp>`__ are the official C++ GDExtension bindings, maintained
7+
as part of the Godot project.
8+
9+
godot-cpp is built with the :ref:`GDExtension system <doc_gdextension>`, which allows access to Godot in almost the
10+
same way as :ref:`modules <doc_custom_modules_in_cpp>`: A lot of `engine code <https://github.com/godotengine/godot>`__
11+
can be used in your godot-cpp project almost verbatim.
12+
13+
In particular, godot-cpp has access to all functions that :ref:`GDScript <doc_gdscript>` and :ref:`C# <doc_c_sharp>`
14+
have, and additional access to a few more which are provided for fast low-level access of data.
15+
16+
Differences between godot-cpp and C++ modules
17+
-----------------------------------------------
18+
19+
You can use both `godot-cpp <https://github.com/godotengine/godot-cpp>`__
20+
and :ref:`C++ modules <doc_custom_modules_in_cpp>` to run C or C++ code in a Godot project.
21+
22+
They also both allow you to integrate third-party libraries into Godot. The one
23+
you should choose depends on your needs.
24+
25+
.. warning::
26+
27+
godot-cpp is currently *experimental*, which means that we may
28+
break compatibility in order to fix major bugs or include critical features.
29+
30+
31+
Advantages of godot-cpp
32+
~~~~~~~~~~~~~~~~~~~~~~~
33+
34+
Unlike modules, godot-cpp (and GDExtension systems in general) don't require
35+
compiling the engine's source code, making it easier to distribute your work.
36+
It gives you access to most of the API available to GDScript and C#, allowing
37+
you to code game logic with full control regarding performance. It's ideal if
38+
you need high-performance code you'd like to distribute as an add-on in the
39+
:ref:`asset library <doc_what_is_assetlib>`.
40+
41+
Also:
42+
43+
- You can use the same compiled godot-cpp library in the editor and exported
44+
project. With C++ modules, you have to recompile all the export templates you
45+
plan to use if you require its functionality at runtime.
46+
- godot-cpp only requires you to compile your library, not the whole engine.
47+
That's unlike C++ modules, which are statically compiled into the engine.
48+
Every time you change a module, you need to recompile the engine. Even with
49+
incremental builds, this process is slower than using godot-cpp.
50+
51+
Advantages of C++ modules
52+
~~~~~~~~~~~~~~~~~~~~~~~~~
53+
54+
We recommend :ref:`C++ modules <doc_custom_modules_in_cpp>` in cases where
55+
godot-cpp (or another GDExtension system) isn't enough:
56+
57+
- C++ modules provide deeper integration into the engine. GDExtension's access
58+
is not as deep as static modules.
59+
- You can use C++ modules to provide additional features in a project without
60+
carrying native library files around. This extends to exported projects.
61+
62+
.. note::
63+
64+
If you notice that specific systems are not accessible via GDExtension
65+
but are via custom modules, feel free to open an issue on the
66+
`godot-cpp repository <https://github.com/godotengine/godot-cpp>`__
67+
to discuss implementation options for exposing the missing functionality.
68+
69+
.. _doc_what_is_gdextension_version_compatibility:
70+
71+
Version compatibility
72+
---------------------
73+
74+
Usually, GDExtensions targeting an earlier version of Godot will work in later
75+
minor versions, but not vice-versa. For example, a GDExtension targeting Godot 4.2
76+
should work just fine in Godot 4.3, but one targeting Godot 4.3 won't work in Godot 4.2.
77+
78+
For this reason, when creating GDExtensions, you may want to target the lowest version of
79+
Godot that has the features you need, *not* the most recent version of Godot. This can
80+
save you from needing to create multiple builds for different versions of Godot.
81+
82+
However, GDExtension is currently *experimental*, which means that we may
83+
break compatibility in order to fix major bugs or include critical features.
84+
For example, GDExtensions created for Godot 4.0 aren't compatible with Godot
85+
4.1 (see :ref:`updating_your_gdextension_for_godot_4_1`).
86+
87+
GDExtensions are also only compatible with engine builds that use the same
88+
level of floating-point precision the extension was compiled for. This means
89+
that if you use an engine build with double-precision floats, the extension must
90+
also be compiled for double-precision floats and use an ``extension_api.json``
91+
file generated by your custom engine build. See :ref:`doc_large_world_coordinates`
92+
for details.
93+
94+
Generally speaking, if you build a custom version of Godot, you should generate an
95+
``extension_api.json`` from it for your GDExtensions, because it may have some differences
96+
from official Godot builds.

tutorials/scripting/gdextension/gdextension_docs_system.rst renamed to tutorials/scripting/godot_cpp/docs_system.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
.. _doc_gdextension_docs_system:
1+
.. _doc_godot_cpp_docs_system:
22

3-
GDExtension documentation system
4-
================================
3+
Adding documentation
4+
====================
55

66
.. note::
77

@@ -15,7 +15,7 @@ XML files (one per class) to document the exposed constructors, properties, meth
1515

1616
.. note::
1717

18-
We are assuming you are using the project files explained in the :ref:`GDExtension C++ Example <doc_gdextension_cpp_example>`
18+
We are assuming you are using the project files explained in the :ref:`GDExtension C++ Example <doc_godot_cpp_getting_started>`
1919
with the following structure:
2020

2121
.. code-block:: none

0 commit comments

Comments
 (0)