Skip to content

Commit 13b4515

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

13 files changed

+202
-158
lines changed
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: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. _doc_gdextension_docs_system:
1+
.. _doc_godot_cpp_docs_system:
22

33
GDExtension documentation system
44
================================
@@ -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

tutorials/scripting/gdextension/gdextension_cpp_example.rst renamed to tutorials/scripting/godot_cpp/getting_started.rst

Lines changed: 33 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,38 @@
1-
.. _doc_gdextension_cpp_example:
1+
.. _doc_godot_cpp_getting_started:
22

3-
GDExtension C++ example
4-
=======================
3+
Getting Started
4+
===============
55

6-
Introduction
7-
------------
6+
Workflow Overview
7+
-----------------
8+
9+
As a GDExtension language binding, godot-cpp is more complicated to use than :ref:`GDScript <doc_gdscript>` and
10+
:ref:`C# <doc_c_sharp>`. If you decide to work with it, here's what to expect your workflow to look like:
811

9-
The C++ bindings for GDExtension are built on top of the C GDExtension API
10-
and provide a nicer way to "extend" nodes and other built-in classes in Godot using C++.
11-
This new system allows the extension of Godot to nearly the same
12-
level as statically linked C++ modules.
12+
* Create a new godot-cpp project (from the `template <https://github.com/godotengine/godot-cpp-template>`__, or from scratch, as explained below)
13+
* Develop your code with your favorite IDE locally.
14+
* Build and test your code with the earliest compatible Godot version.
15+
* Create builds for all platforms you want to support (e.g. using `GitHub Actions <https://github.com/godotengine/godot-cpp-template/blob/main/.github/workflows/builds.yml>`__).
16+
* Optional: Publish on the `Godot Asset Library <https://godotengine.org/asset-library/asset>`__.
1317

14-
You can download the included example in the test folder of the godot-cpp
15-
repository `on GitHub <https://github.com/godotengine/godot-cpp>`__.
18+
Example Project
19+
---------------
20+
21+
For you first godot-cpp project, we recommend starting with this guide to understand the technology involved with
22+
godot-cpp. After you're done, you can use the
23+
`godot-cpp template <https://github.com/godotengine/godot-cpp-template>`__, which is usually more up to date and has
24+
better coverage of features. However, the template does not explain itself to a high level of detail, which is why
25+
we recommend going through this guide first.
1626

1727
Setting up the project
18-
----------------------
28+
~~~~~~~~~~~~~~~~~~~~~~
1929

2030
There are a few prerequisites you'll need:
2131

22-
- a Godot 4 executable,
23-
- a C++ compiler,
24-
- SCons as a build tool,
25-
- a copy of the `godot-cpp
26-
repository <https://github.com/godotengine/godot-cpp>`__.
32+
- A Godot 4 executable.
33+
- A C++ compiler.
34+
- SCons as a build tool.
35+
- A copy of the `godot-cpp repository <https://github.com/godotengine/godot-cpp>`__.
2736

2837
See also :ref:`Configuring an IDE <toc-devel-configuring_an_ide>`
2938
and :ref:`Compiling <toc-devel-compiling>` as the build tools are identical
@@ -91,7 +100,7 @@ following commands:
91100
This will initialize the repository in your project folder.
92101

93102
Building the C++ bindings
94-
-------------------------
103+
~~~~~~~~~~~~~~~~~~~~~~~~~
95104

96105
Now that we've downloaded our prerequisites, it is time to build the C++
97106
bindings.
@@ -129,7 +138,7 @@ libraries that can be compiled into your project stored in ``godot-cpp/bin/``.
129138
You may need to add ``bits=64`` to the command on Windows or Linux.
130139

131140
Creating a simple plugin
132-
------------------------
141+
~~~~~~~~~~~~~~~~~~~~~~~~
133142

134143
Now it's time to build an actual plugin. We'll start by creating an empty Godot
135144
project in which we'll place a few files.
@@ -327,7 +336,7 @@ At last, we need the header file for the ``register_types.cpp`` named
327336
328337
329338
Compiling the plugin
330-
--------------------
339+
~~~~~~~~~~~~~~~~~~~~
331340

332341
To compile the project we need to define how SCons using should compile it
333342
using a ``SConstruct`` file which references the one in ``godot-cpp``.
@@ -371,7 +380,7 @@ following commands to do so:
371380
``target=template_release`` switch.
372381

373382
Using the GDExtension module
374-
----------------------------
383+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
375384

376385
Before we jump back into Godot, we need to create one more file in
377386
``demo/bin/``.
@@ -476,7 +485,7 @@ We're finally ready to run the project:
476485
:align: default
477486

478487
Adding properties
479-
-----------------
488+
~~~~~~~~~~~~~~~~~
480489

481490
GDScript allows you to add properties to your script using the ``export``
482491
keyword. In GDExtension you have to register the properties with a getter and
@@ -610,7 +619,7 @@ The first two arguments are the minimum and maximum value and the third is the s
610619
further configure how properties are displayed and set on the Godot side.
611620

612621
Signals
613-
-------
622+
~~~~~~~
614623

615624
Last but not least, signals fully work in GDExtension as well. Having your extension
616625
react to a signal given out by another object requires you to call ``connect``
@@ -717,7 +726,7 @@ our main node and implemented our signal like this:
717726
Every second, we output our position to the console.
718727

719728
Next steps
720-
----------
729+
~~~~~~~~~~
721730

722731
We hope the above example showed you the basics. You can
723732
build upon this example to create full-fledged scripts to control nodes in Godot

0 commit comments

Comments
 (0)