Add example of GDExtension written pure C #8751

vnen · 2024-01-11T16:20:46Z

This is the same code as the C++ example, but written without any bindings using the GDExtension API directly. It is somewhat long because it needs to touch a lot of aspects and create boilerplate that would normally come from the bindings.

I also want to point out that the GDExtension API is not meant to be used directly like this, so it is more of a reference for people who wants to create their own bindings.

Production edit: closes godotengine/godot-roadmap#77

dsnopek

Wow! George, this is truly monumental work! Great job :-)

dsnopek · 2024-01-11T19:08:45Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+File structure
+--------------
+
+To organize our files, we're gonna split in mainly two folders:


Suggested change

To organize our files, we're gonna split in mainly two folders:

To organize our files, we're gonna split into mainly two folders:

dsnopek · 2024-01-11T19:09:26Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+
+Lastly, there's another source of information we need to refer to, which is the JSON
+file with the Godot API reference. This file won't be used by the code directly, we
+will only use to extract some information manually.


Suggested change

will only use to extract some information manually.

will only use it to extract some information manually.

dsnopek · 2024-01-11T19:10:29Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+
+The following ``SConstruct`` file is a simple one that will build your extension
+to the current platform that you are using, be it Linux, macOS, or Windows. This
+will be a non-optimized build for debugging purposes. It also assumes a 64-bits


Suggested change

will be a non-optimized build for debugging purposes. It also assumes a 64-bits

will be a non-optimized build for debugging purposes. It also assumes a 64-bit

dsnopek · 2024-01-11T19:11:26Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+Initializing the extension
+--------------------------
+
+The first bit of code will be responsible to initialize the extension. This is


Suggested change

The first bit of code will be responsible to initialize the extension. This is

The first bit of code will be responsible for initializing the extension. This is

dsnopek · 2024-01-11T19:13:42Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+needed. It also sets the initialization level which varies per extension. Since
+we plan to add a custom node, the ``SCENE`` level is enough.
+
+We will fill the ``initialize`` function later to register our custom class.


I feel like this would be easier to understand with the full name of the function in this example (as opposed to the field on the struct):

Suggested change

We will fill the ``initialize`` function later to register our custom class.

We will fill the ``initialize_gdexample_module`` function later to register our custom class.

dsnopek · 2024-01-11T19:53:36Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+Variant can cause crashes.
+
+Then it proceeds to extract the argument using the constructor we setup before.
+The one with no arguments instead set the return value after calling the


Suggested change

The one with no arguments instead set the return value after calling the

The one with no arguments instead sets the return value after calling the

dsnopek · 2024-01-11T19:56:42Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+    }
+
+Since this function is already being called by the initialization process, we
+can stop here. This function is much straightforward after we created all the


Suggested change

can stop here. This function is much straightforward after we created all the

can stop here. This function is much more straightforward after we created all the

dsnopek · 2024-01-11T19:57:54Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+        bind_property("GDExample", "speed", GDEXTENSION_VARIANT_TYPE_FLOAT, "get_speed", "set_speed");
+    }
+
+If you build the extension with ``SCons``, you'll see in the Godot editor the new property shown


Seems odd upper case, because the command would be all lower case.

Suggested change

If you build the extension with ``SCons``, you'll see in the Godot editor the new property shown

If you build the extension with ``scons``, you'll see in the Godot editor the new property shown

dsnopek · 2024-01-11T19:58:43Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+For now it will do nothing but update the private field we created. We'll come
+back to this after the method is properly bound.
+
+Virtual methods are a bit different for the regular bindings. Instead of


Suggested change

Virtual methods are a bit different for the regular bindings. Instead of

Virtual methods are a bit different from the regular bindings. Instead of

dsnopek · 2024-01-11T20:05:36Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+calling the functions (such as wrong arguments). For the sake of simplicity
+we're not gonna handle that here.
+
+At then end we need to destruct the Variants we created. While technically the


Suggested change

At then end we need to destruct the Variants we created. While technically the

At the end we need to destruct the Variants we created. While technically the

AThousandShips

Will try do a grammar and language review in the next few days, but looks very interesting!

AThousandShips · 2024-01-11T21:01:09Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+    #include "init.h"
+
+    void initialize_gdexample_module(void *p_userdata, GDExtensionInitializationLevel p_level)
+    {


I'd suggest following the code style for this code as well, with brackets on the declaration

AThousandShips · 2024-01-11T21:01:49Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+class, but it makes clearer to separate the concerns and let our class register
+its own metadata.
+
+The  ``object`` field is necessary because our class will inherit a Godot class.


Suggested change

The ``object`` field is necessary because our class will inherit a Godot class.

The ``object`` field is necessary because our class will inherit a Godot class.

paddy-exe

Left some minor comments on grammar and suggestions for improvements. Phenomenal work on this!

paddy-exe · 2024-01-13T00:02:09Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+
+    #endif // INIT_H
+
+The functions declared here have the signature expected by the GDExtension API.


Suggested change

The functions declared here have the signature expected by the GDExtension API.

The functions declared here has the expected signature by the GDExtension API.

paddy-exe · 2024-01-13T00:04:08Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+In order to make an actual node, first we'll create a C struct to hold data and
+functions that will act as methods. The plan is to make this a custom node that
+inherits from :ref:`Sprite2D <class_Sprite2D>`.


Suggested change

In order to make an actual node, first we'll create a C struct to hold data and

functions that will act as methods. The plan is to make this a custom node that

inherits from :ref:`Sprite2D <class_Sprite2D>`.

In order to make an actual Node, first we'll create a C struct to hold data and

functions that will act as methods. The plan is to make this a custom Node that

inherits from :ref:`Sprite2D <class_Sprite2D>`.

paddy-exe · 2024-01-13T00:06:27Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+The only things special here are the ``object`` field, which holds a pointer to
+the Godot object, and the ``gdexample_bind_methods`` function, which will
+register the metadata of our custom class (properties, methods, and signals).


Suggested change

The only things special here are the ``object`` field, which holds a pointer to

the Godot object, and the ``gdexample_bind_methods`` function, which will

register the metadata of our custom class (properties, methods, and signals).

Noteworthy here is the ``object`` field, which holds a pointer to

the Godot object, and the ``gdexample_bind_methods`` function, which will

register the metadata of our custom class (properties, methods, and signals).

paddy-exe · 2024-01-13T00:07:18Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+reference to such objects when calling methods on the parent class, for
+instance.
+
+Let's create the source counterpart of this header. Make the file


Suggested change

Let's create the source counterpart of this header. Make the file

Let's create the source counterpart of this header. Create the file

paddy-exe · 2024-01-13T00:08:31Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+Very boring stuff as for now we don't have anything to do with those functions, so
+they'll stay empty for a while.
+


Suggested change

Very boring stuff as for now we don't have anything to do with those functions, so

they'll stay empty for a while.

As we don't have anything to do with those functions yet, they'll stay empty

for a while.

paddy-exe · 2024-01-13T01:11:33Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+In order to make our node do stuff, we'll need to call Godot methods. Not only
+the GDExtension API functions as we've being doing so far, but actual engine
+methods, as we would do with scripting. This naturally require some extra setup.


Suggested change

In order to make our node do stuff, we'll need to call Godot methods. Not only

the GDExtension API functions as we've being doing so far, but actual engine

methods, as we would do with scripting. This naturally require some extra setup.

In order to make our Node do stuff, we'll need to call Godot methods. Not only

the GDExtension API functions as we've being doing so far, but actual engine

methods, as we would do with scripting. This naturally requires some extra setup.

paddy-exe · 2024-01-13T01:13:01Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+        ...
+    }
+
+The only special thing here is the ``Vector2`` constructor, which we request the


Suggested change

The only special thing here is the ``Vector2`` constructor, which we request the

The only noteworthy part here is the ``Vector2`` constructor, in which we request the

paddy-exe · 2024-01-13T01:14:23Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+name. This index can be retrieved from the ``extension_api.json`` file. Note we
+also need a new local helper to get it.
+
+Note that we don't get anything for the methods struct here. This is because


Suggested change

Note that we don't get anything for the methods struct here. This is because

Be aware that we don't get anything for the methods struct here. This is because

Instead of Note since that was just used for the prior sentence

paddy-exe · 2024-01-13T01:18:54Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+        destruct_property(&args_info[0]);
+    }
+
+This one is very similar to the function to bind methods. The main difference is


Suggested change

This one is very similar to the function to bind methods. The main difference is

This implementation is very similar to the function to bind methods. The main difference is

paddy-exe · 2024-01-13T01:20:51Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+        destructors.variant_destroy(&ret);
+    }
+
+This helper has some boilerplate but is quite straightforward. It sets up the


Suggested change

This helper has some boilerplate but is quite straightforward. It sets up the

This helper function has some boilerplate code but is quite straightforward. It sets up the

quite straightforward should also be avoided as it sounds like it's trivial to understand. Perhaps just end the sentence after boilerplate

31

I've only skimmed it so far, but this looks amazing. Was just about to try to work through how to use these APIs on my own (based on what I think godot-cpp is doing), glad it took me long enough to get to it that I noticed this PR first. 😄

An overall wish I would have if it's feasible is a TOC (and/or multiple pages) so it's easier to understand the scope of what's being provided and poke around.

31 · 2024-01-15T04:51:53Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+The complete version is more involved. First, it creates ``String``s and
+``StringName``s for the needed fields, by allocating memory and calling their


I think the s is making rendering mess up? Looks like this on my local build (cherry-picked on top of a63a33a in master):

31 · 2024-01-15T04:54:04Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+        ...
+    }
+
+Here we create ``StringName``s for the class and method we want to get, then use


Another ``s rendering weird.

vnen · 2024-01-15T13:01:26Z

BTW, thanks for all the reviews. I did kind of forget this during weekend (on purpose to rest) but in the next few days I'll address all the issues pointed out.

rburing · 2024-01-19T11:19:29Z

tutorials/scripting/gdextension/gdextension_c_example.rst

+    void gdexample_call_virtual_with_data(GDExtensionClassInstancePtr p_instance, GDExtensionConstStringNamePtr p_name, void *p_virtual_call_userdata, const GDExtensionConstTypePtr *p_args, GDExtensionTypePtr r_ret)
+    {
+        // If it is the "_process" method, call it with a helper.
+        if (is_string_name_equal(p_name, "_process"))


This is re-creating the StringName "_process" every process frame, isn't it? It would be nice to avoid that here.

Edit: Comparing p_virtual_call_userdata to &gdexample_process would be fast.

Add example of GDExtension written pure C

ca0910a

vnen added enhancement content:new page Issues and PRs related to creation of new documentation pages for new or undocumented features area:manual Issues and PRs related to the Manual/Tutorials section of the documentation topic:gdextension labels Jan 11, 2024

dsnopek reviewed Jan 11, 2024

View reviewed changes

AThousandShips reviewed Jan 11, 2024

View reviewed changes

paddy-exe reviewed Jan 13, 2024

View reviewed changes

31 reviewed Jan 15, 2024

View reviewed changes

rburing reviewed Jan 19, 2024

View reviewed changes

mhilbrunner added the needs work Needs additional work by the original author, someone else or in another repo. label Jan 24, 2024

dsnopek mentioned this pull request May 18, 2024

Segfault in Object::clear_internal_extension, reproducable on GDExtension hot reload. godotengine/godot#92063

Closed

dsnopek mentioned this pull request Jun 14, 2024

GDExtension: pointer parameters of type real are declared as float* in JSON godotengine/godot#93132

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add example of GDExtension written pure C #8751

Add example of GDExtension written pure C #8751

vnen commented Jan 11, 2024 •

edited by adamscott

Loading

dsnopek left a comment

dsnopek Jan 11, 2024

dsnopek Jan 11, 2024

dsnopek Jan 11, 2024

dsnopek Jan 11, 2024

dsnopek Jan 11, 2024

dsnopek Jan 11, 2024

dsnopek Jan 11, 2024

dsnopek Jan 11, 2024

dsnopek Jan 11, 2024

dsnopek Jan 11, 2024

AThousandShips left a comment

AThousandShips Jan 11, 2024

AThousandShips Jan 11, 2024

paddy-exe left a comment •

edited

Loading

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

paddy-exe Jan 13, 2024

31 left a comment •

edited

Loading

31 Jan 15, 2024

31 Jan 15, 2024

vnen commented Jan 15, 2024

rburing Jan 19, 2024 •

edited

Loading

	To organize our files, we're gonna split in mainly two folders:
	To organize our files, we're gonna split into mainly two folders:

	will only use to extract some information manually.
	will only use it to extract some information manually.

	will be a non-optimized build for debugging purposes. It also assumes a 64-bits
	will be a non-optimized build for debugging purposes. It also assumes a 64-bit

	The first bit of code will be responsible to initialize the extension. This is
	The first bit of code will be responsible for initializing the extension. This is

	We will fill the ``initialize`` function later to register our custom class.
	We will fill the ``initialize_gdexample_module`` function later to register our custom class.

	The one with no arguments instead set the return value after calling the
	The one with no arguments instead sets the return value after calling the

	can stop here. This function is much straightforward after we created all the
	can stop here. This function is much more straightforward after we created all the

	If you build the extension with ``SCons``, you'll see in the Godot editor the new property shown
	If you build the extension with ``scons``, you'll see in the Godot editor the new property shown

	Virtual methods are a bit different for the regular bindings. Instead of
	Virtual methods are a bit different from the regular bindings. Instead of

	At then end we need to destruct the Variants we created. While technically the
	At the end we need to destruct the Variants we created. While technically the

	The ``object`` field is necessary because our class will inherit a Godot class.
	The ``object`` field is necessary because our class will inherit a Godot class.


		#endif // INIT_H

		The functions declared here have the signature expected by the GDExtension API.

	The functions declared here have the signature expected by the GDExtension API.
	The functions declared here has the expected signature by the GDExtension API.

	Let's create the source counterpart of this header. Make the file
	Let's create the source counterpart of this header. Create the file

		Very boring stuff as for now we don't have anything to do with those functions, so
		they'll stay empty for a while.

	The only special thing here is the ``Vector2`` constructor, which we request the
	The only noteworthy part here is the ``Vector2`` constructor, in which we request the

	Note that we don't get anything for the methods struct here. This is because
	Be aware that we don't get anything for the methods struct here. This is because

	This one is very similar to the function to bind methods. The main difference is
	This implementation is very similar to the function to bind methods. The main difference is

	This helper has some boilerplate but is quite straightforward. It sets up the
	This helper function has some boilerplate code but is quite straightforward. It sets up the

		The complete version is more involved. First, it creates ``String``s and
		``StringName``s for the needed fields, by allocating memory and calling their

Add example of GDExtension written pure C #8751

Are you sure you want to change the base?

Add example of GDExtension written pure C #8751

Conversation

vnen commented Jan 11, 2024 • edited by adamscott Loading

dsnopek left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AThousandShips left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paddy-exe left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

31 left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vnen commented Jan 15, 2024

rburing Jan 19, 2024 • edited Loading

Choose a reason for hiding this comment

vnen commented Jan 11, 2024 •

edited by adamscott

Loading

paddy-exe left a comment •

edited

Loading

31 left a comment •

edited

Loading

rburing Jan 19, 2024 •

edited

Loading