-
-
Notifications
You must be signed in to change notification settings - Fork 21.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Allow creating GDExtension plugins from inside the Godot editor #90979
base: master
Are you sure you want to change the base?
Conversation
bac4e56
to
b0ffd5f
Compare
Wow, this looks great! I wonder, does this also resolve godotengine/godot-proposals#9306 ? It looks like the same problem IMO. |
This looks great, but I also definitely think its worthwhile to consider support for other build systems beyond scons. There has been a tremendous amount of work put into the cmake build in godot-cpp, and I think its at least worthwhile for supporting that build system if someone picks "GDExtension C++ only". |
This looks wonderful as I've been annoying with handling the preparation of making GDExtension manually for days.
See? There are two
As the direct placement of folder |
@Naros The big question I have is what would this feature look like? Should cmake be included as one of the supported options out of the box? Should it be plugable? If so how? I guess plugins should add more options to the dropdown menu, so we would have "GDExtension C++ only (scons)" and "GDExtension C++ only (cmake)"? Or is it worth refactoring this menu to have a more generalized "GDExtension" option and a second dropdown for "C++ SCons", "C++ CMake", etc? @Lazy-Rabbit-2001 I agree, but there are some technical challenges when trying to make the plugins share
I would need some help from the build system gurus to make this work. |
editor/plugins/gdextension/cpp_template/addon/library_name.gdextension
Outdated
Show resolved
Hide resolved
editor/plugins/gdextension/cpp_template/addon/library_name.gdextension
Outdated
Show resolved
Hide resolved
Thanks for taking this on! It looks really cool :-) I did a quick test of the PR, and the "Compile on" checkbox didn't seem to work for me. It detected scons and git, but it encountered an error when trying to run it:
If I change the It looks like this creates a However, GDExtensions are quite different from plugins in many ways. It may make sense for GDExtensions to have their own tab distinct from "Plugins"? And, if so, then the UI here should probably be disentangled from the "Create New Plugin" form and process. Anyway, this is a great start! |
So first, I think David is right, we should completely separate GDExtension from GDScript plug-ins here, 💯 . An independent UI has several benefits:
On the GDExtension create dialog, I could imagine this being a bit similar to Project Settings with a tree on the left, and a panel on the right where we display context-specific options based on the choice on the left. The left panel tree might look like this:
The Under the The And circling back to Limbo's idea of a shared
I'm just not sure I like the idea of embedding the C++ code into the Godot project, but I'm not 100% sold either way. But now I do question if some of these settings belong configurable in the Project Settings and not in the "Create Extension" dialog 🤔 |
Bit of a question about this Draft PR will this trigger a compile after the GDExtention is created or do will we have to do that manually? |
@HeadClot It attempts a compile for you, but this may fail if Git, SCons, or a C++ compiler/linker/etc are missing. |
Got it thank you for the info :) |
I think it probably makes sense to make this pluggable via an editor plugin, similar to the Also, it could make sense to include the C++ support in a |
3199f9a
to
6d83772
Compare
I overhauled the entire UI frontend of this PR. Instead of using the same dialog as GDScript plugins, now there is an entirely separate tab with 2 dialogs for creating and editing GDExtensions. I have updated the OP, please read that for a summary of how the workflow looks like. In addition to what's in the OP, here is a short description of what the classes are:
This should be fixed now. It will now add arch_suffix if it's missing.
This is gone now.
The create dialog now allows specifying any path. You can use |
6d83772
to
8f4b938
Compare
EDIT:
godot.windows.editor.dev.x86_64_WmCRfH6YBH.mp4EDIT:
Despite these minor problems, the extension is created correctly and is usable out-of-the-box, which is very nice. |
46fac1f
to
77bbbfb
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Tested locally (rebased on top of master
), it works as expected.
Some feedback:
-
SCons' stdout appears in the terminal but not in the editor Output panel. With the new process management classes, would it be possible to display it in the editor Output panel? Add colored header output #92209 will take care of the ANSI escape codes from the colored prints.
-
Should the Library Name field use the
is_valid_identifier()
method to check for validity? Its tooltip says it must be a valid identifier on its own, unlike Base Name. I believe most programming languages are aligned on GDScript's requirements for identifiers, so enforcing this probably makes sense. Note thatis_valid_identifier()
allows non-ASCII characters, so another method must be used as well to check whether only ASCII characters were entered (if this is required). -
Adding multiple extensions in the same project with this dialog will result in errors:
-
Attempt to register extension class 'ExampleNode', which appears to be already registered.
-
Attempt to register extension method 'hello' for unexisting class 'ExampleNode'.`
-
To avoid this, I suggest using the plugin path as a suffix to the the node name created by the extension numeric suffix (e.g. ExampleNodeExtensionDemo
for an add-on in the extension_demo
folder).
-
The example extension code should probably print something in its constructor (or
NOTIFICATION_READY
), so you see it having an effect right away when it's added to the scene tree. Also, itshello()
method should either print text directly (and returnvoid
), or be renamed to something likeget_greeting_text()
as it currently doesn't print and returns a String instead. -
The line "Both Git and SCons were found." should also tell you that you need a C++17-compatible compiler (GCC, Clang or MSVC). The "or MSVC" part should only be displayed on Windows. Something like this:
-
Both Git and SCons were found. You will also need a C++17-compatible compiler such as (GCC or Clang|GCC, Clang or MSVC).
-
-
When using the C++ as GDExtension or engine module option, the last line of the creation dialog should be yellow, as it's a warning:
- The form considers it valid to use non-digit characters in the compatibility minimum/maximum version fields. Also, using a minimum version (
4.4
) greater than the current editor version (4.3
) is currently not prevented. This leads to an error if you confirm the dialog.
-
We should figure out how to handle this in the Flatpak, as there won't be a C++ compiler, Git or SCons available for it to run. I suppose the Flatpak will need a patch to run these tools using flatpak-spawn from the host system.
-
On the Android and web editors, this functionality should be disabled as there's no way the user can run a C++ compiler toolchain on those (due to sandboxing restrictions).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Haven't tested but the code looks good to me
77bbbfb
to
faac3d4
Compare
This is intentional. There is no reason to prevent users from naming their extension with non-ASCII characters. If some languages support it, the dialog shouldn't prevent it. If a language doesn't support a character in an identifier, the users should just not use that character (it's easy enough to just delete and recreate the addon in the unlikely event that happens)
This makes sense, but I really want to avoid misleading users into thinking that putting the plugin name in the class names is necessary, or mislead them into thinking it's a good practice. I updated the PR to use numeric discriminators instead (ExampleNode, ExampleNode2, ExampleNode3, etc).
Just to clarify, the node should do this, not the extension?
I think the dialog should not prevent this. GDExtension currently accepts strings such as
Should there be an editor-wide define for if we're on a platform that can compile or not? I'd rather not hard-code something like Actually, is there a reason to disable creating GDExtensions on those platforms? Or do we just need to disable the compile checkbox? You already can't continue with the checkbox enabled if Git or SCons can't be found. While it may not be useful, I don't see any specific reason why we need to disable creating an uncompiled GDExtension. |
faac3d4
to
05a86b6
Compare
05a86b6
to
069cd33
Compare
069cd33
to
6effb6d
Compare
6effb6d
to
534c3c8
Compare
534c3c8
to
9ba618d
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, this is looking really awesome! This provides a great base to build even more functionality on top of.
I tested it a bunch locally, and reviewed the code in the "cpp_scons" template in detail, but only really skimmed the editor code. All looks good to me :-)
9ba618d
to
87c864a
Compare
For the record, the functionality looks good overall, and I tested it and it works fine. But I'm a bit concerned about the complexity added by the
CC @Faless |
87c864a
to
f16b2e0
Compare
f16b2e0
to
bfe12ab
Compare
This user was able to use C++ on Android using Termux, Clang, and a custom Android NDK: https://www.reddit.com/r/godot/comments/1g50mlq/c_vs_gdscript_performance_with_large_for_loops/ls88qcn/ |
For supporting both addons and modules, I propose godotengine/godot-cpp#1415 (if it gets merged). With this you can use just However I believe too that this should support just GDExtension and not modules. Also, would be nice if this would offer option to create more than just C++ projects (eg. godot-rust, etc.) |
Following this one. |
This PR implements godotengine/godot-proposals#3367 and godotengine/godot-proposals#9306 (not exactly as the proposals describe, but solves the same problem).
The status quo for GDExtension development is really unfortunate. For the most part the only easy way to get started is to copy-paste an existing GDExtension project and use it as a template. If you don't do this, you'd need to follow the documentation, which is a massive behemoth that manually explains to the user how to create each file from scratch, and it would take a user hours to follow this guide.
Really, I believe it should be as simple as making a GDScript plugin:
This is what this PR implements. Just go into Project Settings -> GDExtension:
Next, click Create GDExtension, type in a base name, click "Create", and then it will create and compile an extension.
The library name and path are optional. If you do not specify these, they will be determined automatically.
The dialog includes hover tooltips if you hover over the boxes, which explain what each field is and what the values you write in it should be.
The language system is designed to be completely language-agnostic. The dialogs have no clue about the existence of C++ or SCons. All of the C++ and SCons specific code is isolated in one class, and in the future we can allow editor plugins to extend this. It's not exposed as of this PR in case we want to iterate on the internal code first, but we can expose it whenever, either in this PR or in a future PR.
As mentioned by proposal godotengine/godot-proposals#3367, this sets up the build system with a build command (
scons
), the.gitignore
files, the.gdextension
file, the type registration boilerplate, and it evengit clone
sgodot-cpp
. By default, it will also initiatescons
to compile the extension, but this does take awhile, so you can skip this step by unchecking the "Compile now?" box.Note that this PR does not include setting up system-level dependencies, such as installing a C++ compiler, installing Git, installing SCons, etc. This varies widely by operating system and it would be a slippery slope to try and have that. This PR is purely focused on the files that go in your project, not the system-wide dependencies. This PR does not try to detect a C++ compiler, but it will warn the user if either Git or SCons is not found on their system.
When you create a GDExtension plugin with this PR, one example node is provided called
ExampleNode
. Like the Blender default cube, this is expected to be replaced by users as soon as possible. However, its existence is useful to both new and experienced users, since it serves 2 functions: 1) As a reference for how to make a node type, including the code, registration, docs, icon, etc, and 2) A minimal test to check if your GDExtension plugin works (don't see it in the editor? It's not working).Assuming you have the system-wide dependencies installed, and you leave the "Compile now?" checkbox enabled, and you wait for it to finish, the extension immediately works. No fuss, the example node is just there.
Assuming it was compiled, it will show up in a list of GDExtensions. This list will contain every loaded GDExtension, regardless of whether it was been created by the create dialog. It gets this list from GDExtensionManager, so it will not include any non-compiled or otherwise broken extensions.
If you change the code, you just need to run
scons
in either the extension folder or the project root. A future idea would be to detect this in projects and provide a "Build" button in the editor UI like we already do for C#, but that is technically separate from what this PR does.The files look like this:
The
SConstruct
at the project root is extremely barebones, it is only one line to call into another SConstruct. It is designed to be simple enough so that more GDExtension plugins can be added to the same Godot project with no manual work. The_ensure_file_contains
helper function in this PR completely handles the merging of more calls into this file. Except for deleting the first plugin'sExampleNode
, you can just make 2 plugins back-to-back with no conflicts. If you want to have 20 GDExtension plugins, this PR will let you do that just fine, with one call toscons
in the root folder able to compile all of them at once.This PR provides 2 options for making a GDExtension plugin: "C++ with SCons, GDExtension only" or "C++ with SCons, GDExtension and engine module". The former creates a standalone GDExtension C++ plugin, with the only files stored in the root of the project being a
.gitignore
and barebonesSConstruct
.The engine module option provides a few more files like
SCsub
andconfig.py
, provides lots of#ifdef
directives to support both GDExtensions and modules, and places most of the C++ code in the root of the folder, which is more suitable for making a Godot engine module. This way if users want to target both GDExtension and modules with one codebase, they can do this as easily as selecting it from the dropdown. This option turns the project's root folder into a module, so only one module is allowed per project.When in this mode, you can either compile for GDExtension the same as with the "only" option, or you can copy-paste the entire Godot project into the engine modules folder, naming the folder the same as the addon folder name, and it works.
The source files are designed to handle the extension+module case, but are automatically simplified by this PR's project generator when making a non-module extension, including by looking at the
#if
preprocessor directives to determine which lines of code to exclude.In the extension list, you can click the pencil button on any of these items to open a menu to edit the GDExtension.
Like the create dialog, the dialog includes hover tooltips which describe each field. However, for the Libraries and Icons fields, the hover tooltips are placed on the Label nodes instead of the Dictionary editors.
EDIT: This PR has changed a lot since first opening. For the record, here's the old PR description:
This PR implements godotengine/godot-proposals#3367 (not exactly as that proposal describes, but solves the same problem).
The status quo for GDExtension development is really unfortunate. For the most part the only easy way to get started is to copy-paste an existing GDExtension project and use it as a template. If you don't do this, you'd need to follow the documentation, which is a massive behemoth that manually explains to the user how to create each file from scratch, and it would take a user hours to follow this guide.
Really, I believe it should be as simple as making a GDScript plugin:
This is what this PR implements. Just go into Project Settings -> Plugins, click Create New Plugin, and select GDExtension.
As mentioned by proposal godotengine/godot-proposals#3367, this sets up the build system with a build command (
scons
), the.gitignore
files, the.gdextension
file, the type registration boilerplate, and it evengit clone
sgodot-cpp
. By default, it will also initiatescons
to compile the extension, but this does take awhile, so you can skip this step by unchecking the "Compile now? (slow)" box.Note that this PR does not include setting up system-level dependencies, such as installing a C++ compiler, installing Git, installing SCons, etc. This varies widely by operating system and it would be a slippery slope to try and have that. This PR is purely focused on the files that go in your project, not the system-wide dependencies. This PR does not try to detect a C++ compiler, but it will warn the user if either Git or SCons is not found on their system.
When you create a GDExtension plugin with this PR, one example node is provided called
ExampleNode
. Like the Blender default cube, this is expected to be replaced by users as soon as possible. However, its existence is useful to both new and experienced users, since it serves 2 functions: 1) As a reference for how to make a node type, including the code, registration, docs, icon, etc, and 2) A minimal test to check if your GDExtension plugin works (don't see it in the editor? It's not working).Assuming you have the system-wide dependencies installed, and you leave the "Compile now?" checkbox enabled, and you wait for it to finish, the extension immediately works. No fuss, the example node is just there:
If you change the code, you just need to run
scons
in the root. A future idea would be to detect this in projects and provide a "Build" button in the editor UI like we already do for C#, but that is technically separate from what this PR does.The files look like this:
The
SConstruct
at the root is extremely barebones, it is only one line to call into another SConstruct. It is designed to be simple enough so that more GDExtension plugins can be added to the same Godot project with no manual work. The_ensure_file_contains
helper function in this PR completely handles the merging of more calls into this file. Except for deleting the first plugin'sExampleNode
, you can pretty much just make 2 plugins back-to-back with no conflicts. If you want to have 20 GDExtension plugins, this PR will let you do that just fine, with one call toscons
in the root folder able to compile all of them at once.This PR provides 2 options for making a GDExtension plugin: "GDExtension C++ only" or "GDExtension C++ and engine module". The former creates a standalone GDExtension C++ plugin, with the only files stored in the root of the project being a
.gitignore
and barebonesSConstruct
.The engine module option provides a few more files like
SCsub
andconfig.py
, provides lots of#ifdef
directives to support both GDExtensions and modules, and places most of the C++ code in the root of the folder, which is more suitable for making a Godot engine module. This way if users want to target both GDExtension and modules with one codebase, they can do this as easily as selecting it from the dropdown. This option turns the project's root folder into a module, so only one module is allowed per project:When in this mode, you can either compile for GDExtension the same as with the "only" option, or you can copy-paste the entire Godot project into the engine modules folder, naming the folder the same as the base name (the first name you entered in the Create GDExtension dialog), and it works.
The source files are designed to handle the extension+module case, but are automatically simplified by this PR's project generator when making a non-module extension, including by looking at the
#if
preprocessor directives to determine which lines of code to exclude.TODO list before undrafting this PR:
is_ascii_char
tois_ascii_alphabet_char
#90931