tutorials/scripting/gdextension/gdextension_cpp_example

[giscus[bot]]

tutorials/scripting/gdextension/gdextension_cpp_example

Introduction: The C++ bindings for GDExtension are built on top of the C GDExtension API and provide a nicer way to "extend" nodes and other built-in classes in Godot using C++. This new system all...

https://docs.godotengine.org/en/latest/tutorials/scripting/gdextension/gdextension_cpp_example.html

[Dimon4eg]

Here is how to create Visual Studio solution to build, code and debug GDExtension
https://godotforums.org/d/32073-debug-c-gdextension/16

[flcoder]

Quick correction... take out "GDExample" here...

ADD_PROPERTY("GDExample", PropertyInfo(Variant::FLOAT, "speed", PROPERTY_HINT_RANGE, "0,20,0.01"), "set_speed", "get_speed");

[Calinou]

• Fixed: Fix ADD_PROPERTY() calls in GDExtension C++ example to use correct syntax godot-docs#9918

[Kaizu-r]

do i need my project to be inside GD extension for this to work? or do i have to repeat the same process in a different folder (for ex i want to have my project inside an external drive)?

[RichmarIII]

No. just make sure that

env.Append(CPPPATH=["src/"])
sources = Glob("src/*.cpp")

in your SConstruct file point to your GDExtension source code folder.

[RichmarIII]

And make sure that

env = SConscript("../../godot-src/godot-cpp/SConstruct")

in your SConstruct file point the the godot-cpp SConstruct file

[Kaizu-r]

How do I connect a signal from Godot(ex: area_entered) to my C++ source code?

[danny1235]

Do I have to use the same compiler that was used to compile Godot? Or does GDExtension work with any C++ compiler?

[Calinou]

You need to compile against the same ABI as used for Godot itself, as different compilers may have incompatible ABIs.

In practice, this means that:

• On Windows, you should compile with MinGW if using official Godot binaries (since these are also compiled with MinGW). If using self-compiled Godot binaries with MSVC, then the GDExtension should also be compiled using MSVC.
• On all other platforms, you can use any supported compiler since there is generally only one ABI to choose from.

[danny1235]

I have seen many tutorials where they used Visual Studio / MSVC. Is this only possible with a self compiled version of godot?

[EdwardChanCH]

We call the function register_class for each of our classes in our library.

Where is register_class called? It is not mentioned anywhere else in this page, except GDREGISTER_CLASS(GDExample) in register_types.cpp .

[bruvzg]

It is outdated, register_class is old GDNative (3.x) method, for GDExtension (4.x) use GDREGISTER_CLASS instead.

[Calinou]

Pull request opened:

• Fix outdated reference to register_class function in GDExtension C++ example godot-docs#9975

[Archytas79]

Running into an issue where .hpp files don't get created at all - been following the guide word for word for godot 4.3 linux and it has nothing on this at all.
Clarification: I can't include "godot_cpp/core/class_db.hpp" as it doesn't exist

[onadrog]

I ran the same issue here's what worked for me ( using linux and neovim with clangd as lsp):
create a .clangd file in your root directory project and paste this:

CompileFlags:
  Add: [
      "-I<path to your project>/", # relative path didn't work
      "-I<path to your project>/godot-cpp/gen/include",
      "-I<path to your project>/godot-cpp/include",
      "-I<path to your project>/godot-cpp/gdextension",
      "-I<path to your project>/src",
    ]

Or if you're using VSC maybe take a look a this GDExtension-Summator
Maybe this step should be documented.
Hope this help

[bobby-the-epic]

@onadrog You don't have to do all of that. The SCons file has a compiledb build flag that can build the compile_commands.json file for you. All you have to do is add compiledb=yes to the scons command. Also if you use clangd, you might want to build with the clang compiler so that you don't get weird diagnostic messages (use_llvm=yes). Clang setup instructions: Using Clang and LLD for faster development.

[onadrog]

@bobby-the-epic Oh everything work just fine, thanks!

[praetortuicu]

@onadrog Adding the .clangd file at the root of my project directory did not work for me. When compiling the engine with scons platform=linuxbsd use_llvm=yes linker=lld I encountered clang: error: invalid linker name in argument '-fuse-ld=lld'. Why I tried clang and not the 'default' version from the beginning: I am having an issue with the #include <godot_cpp/classes/sprite2d.hpp>, part (so pretty much at the beginning of the tutorial), namely an error is thrown: sprite2d.hpp file not found. So I checked the paths, apparently building godot-cpp with scons platform=linux ... creates all the .hpp files in /path/godot-cpp/gen/include/godot-cpp/classes/ but doesn't put them in godot-cpp/include/godot_cpp/classes (I only have 3 .hpp files in the latter: editor_plugin_registration.hpp ref.hpp wrapped.hpp). After a lot of searching around I found the godot-headers repo which I also tried including in the project following its' own set of instructions, didn't work. First of all I got confused because I found this extra repository with headers which isn't referenced in this documentation page at all. Second of all I tried copying everything from godot-cpp/gen/include/godot_cpp/classes/ into godot-cpp/include/godot_cpp/classes and updating SConstruct by adding env.Append(CPPPATH=["/path/to/godot-cpp/include/godot_cpp/classes"]) as well as env.Append(CPPPATH=["/path/to/godot-cpp/gen/include/godot_cpp/classes"]). I followed the exact steps from top to bottom multiple times and still nothing. I also haven't really seen anyone else mention my problem so maybe it's got something to do with my machine?
All three repos have been cloned from master and I've also tried the 4.3 branches on godot and godot-cpp, same issue.
Debian 12, up to date, thanks in advance for any help :D

[onadrog]

@praetortuicu I don't know here's with what I came from finally and works for me:
Using the solution just above #36
everything works perfectly for me, meaning using LLVM or GCC the linker=ldd does not work if I'm not mistaken.
For the branch i have used the 4.3 since the master branch refers to the Godot master so stick with the 4.3 when you git clone it.

So try using just:

scons compiledb=yes

For example here is my Makefile after the command above done once:

release: debug
	scons target=template_release symbols_visibility=hidden optimize=speed generate_bindings=yes precision=double

debug:
	scons target=template_debug symbols_visibility=visible optimize=debug generate_bindings=yes precision=double

PS: check scons --help for all the args and their default values.

[d-eisenga]

What's the proper way to extend GDExample in GDScript? When I put a _process function in my GDExampleSubclass.gd, the one from GDExample no longer gets called, but Godot also won't let me call super._process(delta) :

SCRIPT ERROR: Parse Error: Cannot call the parent class' virtual function "_process()" because it hasn't been defined.

[addmix]

This is a pretty important functionality. Have you found a solution yet?

[addmix]

I found out that the rest of Godot does it like this:

void GDExample::_notification(int p_notification) {
	switch (p_notification)
	{
	case NOTIFICATION_ENTER_TREE:
		break;
	case NOTIFICATION_READY:
		break;
	case NOTIFICATION_PROCESS:
		break;
	case NOTIFICATION_PHYSICS_PROCESS:
		break;	
	}
}

It's not a way to extend/override GDExtension code, but it works for those cases where extension is absolutely necessary.

[d-eisenga]

Thank you for your responses. I think that's the way to do it, yes. A few other things some might find useful to know:

1. When a class doesn't override the _process method (in either C++ or GDScript, or C# I suppose), you may need to call set_process(true) in the ready method. Likewise for _physics_process and set_physics_process(true).
2. If your class has a _notification method and you make a child class that itself also has a _notification method, you do not need to bother with virtual and override keywords, nor call the parent method from the child class. Godot already calls the method for each class on a node.

[looak]

I've gone through this tutorial step by step a few times with different versions but I keep getting this error:

  core/extension/gdextension_library_loader.cpp:271 - Error loading GDExtension configuration file: res://bin/gdexample.gdextension
  Can't open GDExtension dynamic library: res://bin/gdexample.gdextension
  core/io/config_file.cpp:304 - ConfigFile parse error at res://bin/gdexample.gdextension:1: Expected value, got EOF..
  core/extension/gdextension_library_loader.cpp:271 - Error loading GDExtension configuration file: res://bin/gdexample.gdextension
  Can't open GDExtension dynamic library: res://bin/gdexample.gdextension

versions of godot I've tried

• Godot_v4.2.2-stable_win64.exe
• Godot_v4.3-stable_win64.exe
• Godot_v4.4-dev2_win64.exe

[d-eisenga]

It sounds like you might not have put a gdexample.gdextension file in your res://bin folder, or the file otherwise can't be read.

ConfigFile parse error at res://bin/gdexample.gdextension:1: Expected value, got EOF seems to me like it means the file isn't there, or is empty, or is maybe improperly formatted.

[looak]

Yea, I would agree with your assessment, more leaning to the formating issue. That said, the file is their, and it is identical to the one in the tutorial. It's not readonly or any other reading/writing limitations. I even tried to run godot as administrator to work around any potential access issues.

Thanks for your reply though!

[looak]

The file had been saved as utf-16 LE encoding, I resaved it as utf-8 and it solved the issue.

[LukasEin]

Hi, I am having problems with the properties and the signal. I fully followed the tutorial and I get no errors and the sprite is moving according to the _process() function.

However, none of the properties or signals added in _bind_methods() show up when I open the project in GoDot.

All properties of the parent nodes are shown in the inspector, however none of the new properties show up there.

This is how my _bind_methods() looks like

void GDExample::_bind_methods() {
    ClassDB::bind_method(D_METHOD("get_amplitude"), &GDExample::get_amplitude);
	ClassDB::bind_method(D_METHOD("set_amplitude", "p_amplitude"), &GDExample::set_amplitude);
	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "amplitude"), "set_amplitude", "get_amplitude");

    ClassDB::bind_method(D_METHOD("get_speed"), &GDExample::get_speed);
    ClassDB::bind_method(D_METHOD("set_speed", "p_speed"), &GDExample::set_speed);
    ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "speed", PROPERTY_HINT_RANGE, "0,20,0.01"), "set_speed", "get_speed");

    ADD_SIGNAL(MethodInfo("position_changed", PropertyInfo(Variant::OBJECT, "node"), PropertyInfo(Variant::VECTOR2, "new_pos")));
}

This is the info about my system and the version

Godot Engine v4.3.stable.official.77dcf97d8 - https://godotengine.org
OpenGL API 4.1 Metal - 88 - Compatibility - Using Device: Apple - Apple M3 Pro

Anyone have an idea what I am missing?

[alex-l-zhou]

hi, have you solved this?

[maiconpintoabreu]

Try to double check if the get_speed and set_speed methods are public.

[maiconpintoabreu]

Same for amplitude

[adney11]

Hi, is there a way to hot-reload newly compiled changes made to a GDExtension source file? Currently, I have to close and re-open the editor in order for the changes to be visible. (macOS, C++)

[Calinou]

Yes, you need to make some changes to the extension code for this to be possible: godotengine/godot#80284

[Structed]

If you are seeing scons failures like the below, make sure you do not only have Visual Studio Preview installed. Scons seems to have issues with the preview toolchain. Just install regular, non-preview, Visual Studio toolchain.

scons
Auto-detected 16 CPU cores available for build parallelism. Using 15 cores by default. You can override it with the -j argument.
Building for architecture x86_64 on platform windows
['src\\Log.cpp', 'src\\NetworkStateChangeManager.cpp']
Generating godot-cpp\gen\include\godot_cpp\core\ext_wrappers.gen.inc ...
Built-in type config: float_64
Compiling godot-cpp\src\core\memory.cpp ...
Compiling shared src\Log.cpp ...
scons: *** [godot-cpp\src\core\memory.windows.template_debug.x86_64.o] The system cannot find the file specified

[zukas97]

i can't find the sprite2d.hpp header.

[d-eisenga]

It's godot_cpp/classes/sprite2d.hpp

[maiconpintoabreu]

If you still cannot find it, it is because you did not compile the godot-cpp.

[IgnacioRassol]

I had to compile the whole project (not just the bindings) before CLion recognized that include. Maybe he is running into something similar.

[Ev01]

For me it's in godot-cpp/gen/include/godot_cpp/classes

[IgnacioRassol]

I don't understand why the code to move the sprite executes in the editor and not just when the scene is running. How do I change that?

[maiconpintoabreu]

GDextension is always if it was flagged with @tool, if you dont want to run the method on edit you can do like @adney11 said if you want to set defaults on editor and the other part of the code to run only when in game you can do a if else like:

void MyNode::_ready() {
    // Check if the game is running in the editor or in a deployed build.
    if (Engine::get_singleton()->is_editor_hint()) {
        // Code to execute ONLY in the editor.
        // You can disable certain functionalities or set default values.
        set_process(false); // Example: Disable processing in the editor.
        set_physics_process(false);
        set_process_input(false);
    } else {
        // Code to execute ONLY in the game (not in the editor).
        // Your main game logic goes here.
    }
}```

[IgnacioRassol]

Thanks for the explanation!

[stan220]

Guys, btw, how can you use Engine::? In repo https://github.com/godotengine/godot-cpp there is no "core/config/engine.h"? could you plz share a guide?

[maiconpintoabreu]

Hi @stan220 it should be inside godotcpp.h and it ready to use if you are using Godot namespace. I cannot confirm it as I am not working in any gdextension project at the moment.

[stan220]

Thx! engine.h appears after compilation in gen folder

[IgnacioRassol]

Could someone explain when I need to use Ref<> in gdextensions and why? I was trying to generate a mesh using surfacetool in a gdextension, and I figured through trial and error that I needed to return a Ref instead of a Mesh for it to work. But I don't understand why, and I couldn't find resources explaining that.

[maiconpintoabreu]

I cannot explain about the Ref at the moment but it is a best practice in cpp to keep track of how many other objects are using this resource and free it when not needed.
If you return as Ref should work.

[maiconpintoabreu]

Btw there are some YouTube videos going deep on refcount topic

[IgnacioRassol]

I understand how memory management works in C++, and I'm familiar with the concept of reference counting. My question was more concerned with why I can only return Ref<> and in which case that is necessary.
But saying that out lout I'm starting to see why. It should be mentioned in this example. Thanks for the response!

[RonYanDaik]

You use Ref<> for all classes that are derivative from RefCounted and Resourse.
Its Godot version of shared pointer class.

Assigning variables of this class only copies pointer to the data.
for example:

Ref a1;
a.instantiate(); //allocate memory for A
Ref a2;
a2 = a1; //a2 will be pointing to same memory cluster as a1
//now if you change value in a2 it will be changed in a1 because it same physical memory
a2->a_value = 1;
print(a1->a_value); //will print "1"

[KvaGram]

I'm playing around with coding my own implementation of this hexagon system. ( www.redblobgames.com/grids/hexagons/ )
I'm rusty in c++, so this is a good exercise. This is my first time attempting to build an extension.

when implementing the QRS cube coordinate system, only the q and r values are to be stored. So they are implemented as full properties with setters and getters. However the s property only have a getter, it can't have a setter. Still, it should show as a property.

Is there a procedure for this? Or is my only workaround to bind a get_s() function?

Separate issue, but related.
Operators. Is there a way to implement them for classes or structures in an extension? I would want to type in a simple c = a + b on my coordinate objects.

[Calinou]

However the s property only have a getter, it can't have a setter. Still, it should show as a property.

Is there a procedure for this? Or is my only workaround to bind a get_s() function?

Godot does not have a "proper" way to bind read-only properties (although you could bind a setter that does nothing and prints an error when used). Instead, we prefer to only expose the getter method, which makes the code more self-explanatory when you read it. Properties are reserved for things that can be both read and written to.

Operators. Is there a way to implement them for classes or structures in an extension? I would want to type in a simple c = a + b on my coordinate objects.

Operator overloads can't be exposed to scripting yet, so GDExtension does not support them either. You can however use operator overloading in your own C++ code.

[KvaGram]

Thanks for the reply. Is there an open ticket for adding operator overloads to scripting and GDExtension?
If so, please link it, so I can follow any progress.

[Calinou]

• Allow custom classes to define their own operator behavior (operator overloading) godot-proposals#8383

[codywohlers]

When it says "Time to jump back into Godot." How does the project (or the Main.tscn) know about the .gdextension file? Where/how do you add it to the project as a resource?

[Swarkin]

Im stuck on this too.

[KvaGram]

Godot regularly scan the working directory for new and changed files.
You should not need to manually add a .gdextension file to a godot project. It should only need to be in the project directory, or in a subdirectory. As far as I understand it, anyway.

[ridilculous]

To avoid recompiling godot-cpp every time you build your GDExtension, add the argument build_library=no to your scons invocation.

Make sure to prebuild godot-cpp for all your build targets.

[ridilculous]

To select the target C++ language standard from the SConstruct file of your GDExtension, add the following lines before the last line of the example "SConstruct file we prepared" and adapt the standard as you like:

env["CXXFLAGS"] = [
    flag for flag in env.get("CXXFLAGS", []) 
    if not any(s in flag for s in ["/std:c++", "-std=c++"])
]
if env["platform"] == "windows":
    env.Append(CXXFLAGS=["/std:c++20"])
else:
    env.Append(CXXFLAGS=["-std=c++20"])

The initial clearing is needed to remove the hardcoded values which are added by godot-cpp\tools\common_compiler_flags.py in def generate(env)

[mariaarna]

I always get this error and I do not know how to fix it.

src/register_types.cpp:16:30: error: 'GDExample' does not refer to a value
    GDREGISTER_RUNTIME_CLASS(GDExample);  // Register the GDExample class
                             ^
src/gdexample.h:8:7: note: declared here
class GDExample : public Sprite2D {
      ^
1 error generated.

Compiling godot-cpp

[goatchurchprime]

If Godot crashes/segfaults/core-dumps on quit it's a sign that your GDExtension is set to the wrong ModuleInitializationLevel. Godot's Main::cleanup() function deinitializes the extensions in batches at the appropriate initialization level while it is closing down its processes.

For example, if your GDExtension has an AudioEffect class on an Audio Bus it must be set to the level MODULE_INITIALIZATION_LEVEL_SERVERS so that its destructor hasn't been unloaded by the time the AudioServer is deleted. goatchurchprime/two-voip-godot-4#49 (comment)