Create a complete and concise documentation for GDExtension

[nonunknown]

Describe the project you are working on

A G.O.A.P Implementation for Godotengine via GDExtension

Describe the problem or limitation you are having in your project

Me and a lot of users has little to none knowledge about GDNative and C++, now that GDNative is "deprecated" in 4.x we have even less knowledge about such powerful tool, some of them:

• Classes we have access to
• Classes which are not exposed to API but we can use in C++ side

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The documentation will have a "Zero to Hero" subject, where a user with basic knowledge of C++ will learn:

• Getting the necessary files to work on
• What is each file in there does
• Generate the bindings (for each platform, and cross-platform)
• Creating the First Extension
• Differences between GDNative and GDExtension
  • Seems after recent changes to GDExtension, you dont need to use generate_bindings anymore, because everytime you recompile example project it compile Godot classes too, but this need to be confirmed!
  • What you couldnt do before and what you can do now.
  • API differences
• Ref<> and * how and when to use them
• Similarities with the core source code
  • How it works in core, and how to reproduce in GDExtension
  • How to deal with virtuals (overriding a C++ function via GDScript, like _ready())
• About Classes from GodotEngine core we can use in C++ but are not exposed in the API
• Creating a simple game
• Creating a simple multiplayer (server/client) and (P2P)
• Creating an editor plugin
• Overriding/Extending Engine features (if possible)
• Compiling your extensions
• Using GDExtension created stuff in C#
• Advanced Stuff
  • Optimization
  • Debugging
  • File Structure
  • Many More
  • Using external graphical/audio APIs (e.g IMGUI), physics libraries....

I may have forgot some stuff, so if you're reading this, please comment below suggestions

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

A Complete documentation in the docs page

If this enhancement will not be used often, can it be worked around with a few lines of script?

Nope, its a documentation.

Is there a reason why this should be core and not an add-on in the asset library?

this cant be addon, since is GDExtension.

[Gnumaru]

Shouldn't this belong to the other project, godot docs?

https://github.com/godotengine/godot-docs/

[nonunknown]

not sure, there is for bugs and enhacements related to existing documentation, @Calinou can confirm?

[Xrayez]

GDExtension appears to be still work-in-progress. But GDExtension without even preliminary documentation/specification is going to be quite useless, by useless I mean this may prevent adoption by potential developers that would like to improve and build upon GDExtension (like me), and those people who could literally speed up the development. I think GDExtension should get more love and support, so I'd leave this proposal here... 😛

I see no technical specification for how GDExtension should work or supposed to work, not even talking about user documentation. So it's more about lack of specification as I see it.

This could potentially be moved to https://github.com/godotengine/godot-proposals/discussions.

See also proposal of mine:

• https://github.com/godotengine/godot-proposals/issues/3864

[nonunknown]

Yep GDExtension is WIP, which means the best time for thinking about how to present the documentation for end-users is now! Also I dont think GDExtension is "useless" it makes life easier when you need to deal with more advanced stuff, having the benefits of the front-end (godot editor) and back-end (core source code).

[Xrayez]

I dont think GDExtension is "useless" it makes life easier when you need to deal with more advanced stuff, having the benefits of the front-end (godot editor) and back-end (core source code).

See my definition of "useless". If the feature is not documented - nobody knows about it, therefore it cannot be used by most users who are not original developers, hence useless, I should've put "useless" in quotes I guess.

[nonunknown]

yep I got it, but your arfimation "feature is not documented - nobody knows about it" is not true, I know little about C++, also I had little knowledge about GDNative, and even with that I was able to get more or less how GDExtension works, I cant even understand its source code, neither from godot engine. Its all about dedication in the end of the day!

PS: the "example" folder which comes with godot-cpp explain very well how to do basic and advanced stuff.

[azur-wolve]

Who is the developer/contributor responsible of GDExtension?

For now idk what GDExtension will be a part from the GDNative substitution. Its an absolute stranger.

@Xrayez mentioned that GDExtensions could throw some issues for addon/plugin developers (recompilation or something iirc).

So its true that its better discuss GDExtension now before its completion, or we could regret it later..

PS: the "example" folder which comes with godot-cpp explain very well how to do basic and advanced stuff.

Do you mean the "test" folder?

[Xrayez]

@Xrayez mentioned that GDExtensions could throw some issues for addon/plugin developers (recompilation or something iirc).

The difference between GDNative and GDExtension is not substantial in principle. But if GDExtension aims to replicate and/or replace C++ modules development as completely as possible, might as well replicate everything that makes C++ modules development a breeze currently.

Who is the developer/contributor responsible of GDExtension?

I think this is mostly a work by @reduz and @vnen as of now.

[azur-wolve]

Then I understood incorrectly (it was from your discussion to being able to write plugins integrated with the editor on GDScript).

Not sure what was more problematic, if GDNative or Modules. Hopefully GDExtension will solve most of that.

[Xrayez]

Not sure what was more problematic, if GDNative or Modules. Hopefully GDExtension will solve most of that.

Both are equally problematic to be honest, depending on who you ask (user vs developer). Those are actually two different technologies I'd say. See discussion in godotengine/godot-proposals#565 if you really want to delve into this topic more. Ultimately, I think this boils down what kind of approach will be supported the most.

[azur-wolve]

Now I get it:

GDNative → share without re-compile engine, ideal for addons/plugins.

• Can support any language with bindings.
• The bindings can throw problems.

Modules → need re-compile engine, so better if have a high-tier Threadripper, but has not the vulnerabilities of GDNative.

• only support C++
• can be compiled as dynamic library and loaded against the project binary (also can against the Editor?)
• can be compiled as static library within the project binary (release)

Excuse me for asking too much, don't want to bother; There are additional problems with Godot Modules?

[Xrayez]

• can be compiled as dynamic library and loaded against the project binary (also can against the Editor?)

There's some distinction between dynamic/shared libraries with modules, which are in theory doable but those have issues as well (Godot in particular):

• https://github.com/godotengine/godot/issues/56887

[Zireael07]

I still fail to understand how GDExtension works (and the comment above mentioning GDNative has me confused because wasn't GDExtension supposed to be a replacement for GDNative)...

[nonunknown]

@Zireael07 GDExtension is something like GDNative 2.0, the difference is that GDExtension has access to the core of the engine in a "deeper level" (has access to more stuff).

basically GDnative and GDExtension is a compiled DLL,SO,DYLIB which communicates with the engine API, so you can use it to make an entire game like gdscript or only for specific stuff like integrate an new audio engine without recompiling the entire engine!

[azur-wolve]

There are any news/progress regarding GDExtension? Who is the maintainer?

[nonunknown]

here is not place for this, but you can find fresh news here: https://chat.godotengine.org/channel/gdextension

[venilark]

Is GDExtension what I should use to replicate a single GDScript/Node file in C++ (for better performance) or is it for something completely different? From @nonunknown's answer I think it should but confirmation would be appreciated, for a couple of calculation-heavy scripts C++ would be the way to go, only if this new "C++'d Node" can communicate with other nodes written in GDScript

[Calinou]

@venilark Yes, this is exactly what GDExtension is about :slightly_smiling_face:

While a single GDExtension is generally used to power multiple classes, it can also be used with a one-library-per-class approach.

[venilark]

@venilark Yes, this is exactly what GDExtension is about 🙂

While a single GDExtension is generally used to power multiple classes, it can also be used with a one-library-per-class approach.

thank you 🙂

[venilark]

@venilark Yes, this is exactly what GDExtension is about 🙂

While a single GDExtension is generally used to power multiple classes, it can also be used with a one-library-per-class approach.

Another question crossed my mind. If I write a function that returns a Dictionary or any object in the C++ node or GDScript node, can the other one call it and get its result? what if it's a dictionary made of different objects, could this be a problem in C++?

[nathanfranke]

@venilark Yes, this is exactly what GDExtension is about slightly_smiling_face While a single GDExtension is generally used to power multiple classes, it can also be used with a one-library-per-class approach.

Another question crossed my mind. If I write a function that returns a Dictionary or any object in the C++ node or GDScript node, can the other one call it and get its result? what if it's a dictionary made of different objects, could this be a problem in C++?

(IIRC) In order to access C++ methods from GDScript, they need to be registered with the ClassDB. If the function returns or has parameters of any type other than a variant (e.g. floats, Dictionaries, Nodes, Resources, etc.) it will give an error.

[Zireael07]

I find myself needing to rework some stuff in my projects to be better/faster. GDExtension is still missing from the docs so many things are still unclear. E.g. can I call a GDE function/use a GDE data structure from GDScript?

Does it only support C++ now? I'm given to understand c# might be migrating to GDE soon(ish).

[azur-wolve]

I find myself needing to rework some stuff in my projects to be better/faster. GDExtension is still missing from the docs so many things are still unclear. E.g. can I call a GDE function/use a GDE data structure from GDScript?

Does it only support C++ now? I'm given to understand c# might be migrating to GDE soon(ish).

IIRC the implementation of GDExtension was facing certain design problems. Right now dont know which is its state. (I assume that you're using Godot 4 alpha)

the only way to clear those doubts is to ask directly to the devs on RocketChat

[benbot]

WIll the GDExtension api be stable by 4.0 beta?

If so it'd be a great time to start writing documentation! I'd be happy to contribute if at all possible :)

[paddy-exe]

Bump! Hey, so I started already with docs for the GDExtension system. I would be incredibly grateful if anyone wants to help since all the renames (GDNative to GDExtension) themselves are a ton of work. I will mainly focus on C++ first so if anyone wants to have a go at the C example, that would be great. @benbot tagging you since you showed interest

[Frontrider]

@paddy-exe how is it coming along?

[paddy-exe]

@paddy-exe how is it coming along?

I worked out all the feedback in my PR. I need a contributor looking over it. Also someone who knows the underlying system needs to confirm that the information I provided is correct.

[arocull]

Not sure where to ask this, but is there any documentation on the "[dependencies]" portion of .gdextension files? I can't seem to find any info, and the only extensions I can find are tutorial ones which don't require external libraries.

[paddy-exe]

Not sure where to ask this, but is there any documentation on the "[dependencies]" portion of .gdextension files? I can't seem to find any info, and the only extensions I can find are tutorial ones which don't require external libraries.

There are only public GDExtensions where you can see the use. It's not yet in the docs.

[allan-simon]

There are only public GDExtensions where you can see the use. It's not yet in the docs.

However the code inside gdextension.cpp does not seem to use it ?

Do you happen to have a link of a github using it ?