godot-cpp/README.md

104 lines
3.7 KiB
Markdown
Raw Normal View History

# godot-cpp
2021-09-27 11:41:56 +00:00
This repository contains the *C++ bindings* for the [**Godot Engine**](https://github.com/godotengine/godot)'s GDExtensions API.
2021-09-27 11:41:56 +00:00
- [**Versioning**](#versioning)
- [**Contributing**](#contributing)
- [**Getting Started**](#getting-started)
- [**Included Example**](#included-example)
Nativescript 1.1 implemented instance binding data usage This commit changes the way C++ wrapper classes work. Previously, wrapper classes were merely wrapper *interfaces*. They used the `this` pointer to store the actual foreign Godot Object. With the NativeScript 1.1 extension it is now possible to have low-overhead language binding data attached to Objects. The C++ bindings use that feature to implement *proper* wrappers and enable regular C++ inheritance usage that way. Some things might still be buggy and untested, but the C++ SimpleDemo works with those changes. new and free change, custom free will crash engine, be wary fix exporting of non-object types fix free() crash with custom resources added type tags and safe object casting fix global type registration order fix cast_to changed build system to be more self contained updated .gitignore use typeid() for type tags now fix indentation in bindings generator remove accidentally added files fix gitignore Fixed up registering tool and updated godot_headers Fix crash when calling String::split/split_floats Was casting to the wrong object type. Also adds parse_ints function to String with the same logic Better warning/error macros Change gitignore so we get our gen folders New documentation based on nativescript 1.1 Fixed GODOT_SUBCLASS macro Preventing crash when function returned null ptr Adds needed include <typeinfo> Solves this issue #168 due to not having the include of typeinfo Fix compile error of 'WARN_PRINT' and 'ERR_PRINT'. cannot pass non-trivial object of type 'godot::String' to variadic function; expected type from format string was 'char *' [-Wnon-pod-varargs] update vector3::distance_to Remove godot_api.json as its now in the godot_headers submodule (api.json)
2018-02-11 14:50:01 +00:00
2021-09-27 11:41:56 +00:00
## Versioning
2021-09-27 09:48:49 +00:00
2021-09-27 11:41:56 +00:00
This repositories follows the same branch versioning as the main [Godot Engine
repository](https://github.com/godotengine/godot):
2021-09-27 09:48:49 +00:00
2021-09-27 11:41:56 +00:00
- `master` tracks the current development branch.
- `3.x` tracks the development of the next 3.x minor release.
- Other versioned branches (e.g. `3.3`, `3.2`) track the latest stable release
in the corresponding branch.
2021-09-27 09:48:49 +00:00
2021-09-27 11:41:56 +00:00
Stable releases are also tagged on this repository:
[**Tags**](https://github.com/godotengine/godot-cpp/tags).
**For any project built against a stable release of Godot, we recommend using
this repository as a Git submodule, checking out the specific tag matching your
Godot version.**
> As the `master` and `3.x` branches are constantly getting updates, if you are
> using `godot-cpp` against a more current version of Godot, see the instructions
> in [**godot-headers**](https://github.com/godotengine/godot-headers) for
> updating the relevant files.
## Contributing
We greatly appreciate help in maintaining and extending this project. If you
wish to help out, ensure you have an account on GitHub and create a "fork" of
this repository. Rémi "Akien" Verschelde wrote an excellent bit of documentation
for the main Godot project on this:
[Pull request workflow](https://docs.godotengine.org/en/stable/community/contributing/pr_workflow.html)
Please install clang-format and copy the files in `misc/hooks` into `.git/hooks`
so formatting is done before your changes are submitted.
## Getting Started
It's a bit similar to what it was for 3.x but also a bit different.
This new approach is much more akin to how core Godot modules are structured.
2021-09-27 09:48:49 +00:00
2021-08-19 23:25:36 +00:00
Compiling this repository generates a static library to be linked with your shared lib,
just like before.
2021-09-27 09:48:49 +00:00
To use the shared lib in your Godot project you'll need a `.gdextension`
file, which replaces what was the `.gdnlib` before.
Follow [the example](test/demo/example.gdextension):
2021-09-27 09:48:49 +00:00
2021-08-19 23:25:36 +00:00
```ini
[configuration]
2021-08-19 23:25:36 +00:00
entry_symbol = "example_library_init"
2021-08-19 23:25:36 +00:00
[libraries]
macos.debug = "bin/libgdexample.osx.debug.framework"
macos.release = "bin/libgdexample.osx.release.framework"
windows.debug.x86_64 = "bin/libgdexample.windows.debug.x86_64.dll"
windows.release.x86_64 = "bin/libgdexample.windows.release.x86_64.dll"
linux.debug.x86_64 = "bin/libgdexample.linux.debug.x86_64.so"
linux.release.x86_64 = "bin/libgdexample.linux.release.x86_64.so"
# Repeat for other architectures to support arm64, rv64, etc.
```
The `entry_symbol` is the name of the function that initializes
your library. It should be similar to following layout:
2018-01-29 22:05:42 +00:00
```cpp
2021-08-19 23:25:36 +00:00
extern "C" {
2021-09-27 11:41:56 +00:00
// Initialization.
2021-08-19 23:25:36 +00:00
GDNativeBool GDN_EXPORT example_library_init(const GDNativeInterface *p_interface, const GDNativeExtensionClassLibraryPtr p_library, GDNativeInitialization *r_initialization) {
2021-09-27 11:41:56 +00:00
godot::GDExtensionBinding::InitObject init_obj(p_interface, p_library, r_initialization);
Nativescript 1.1 implemented instance binding data usage This commit changes the way C++ wrapper classes work. Previously, wrapper classes were merely wrapper *interfaces*. They used the `this` pointer to store the actual foreign Godot Object. With the NativeScript 1.1 extension it is now possible to have low-overhead language binding data attached to Objects. The C++ bindings use that feature to implement *proper* wrappers and enable regular C++ inheritance usage that way. Some things might still be buggy and untested, but the C++ SimpleDemo works with those changes. new and free change, custom free will crash engine, be wary fix exporting of non-object types fix free() crash with custom resources added type tags and safe object casting fix global type registration order fix cast_to changed build system to be more self contained updated .gitignore use typeid() for type tags now fix indentation in bindings generator remove accidentally added files fix gitignore Fixed up registering tool and updated godot_headers Fix crash when calling String::split/split_floats Was casting to the wrong object type. Also adds parse_ints function to String with the same logic Better warning/error macros Change gitignore so we get our gen folders New documentation based on nativescript 1.1 Fixed GODOT_SUBCLASS macro Preventing crash when function returned null ptr Adds needed include <typeinfo> Solves this issue #168 due to not having the include of typeinfo Fix compile error of 'WARN_PRINT' and 'ERR_PRINT'. cannot pass non-trivial object of type 'godot::String' to variadic function; expected type from format string was 'char *' [-Wnon-pod-varargs] update vector3::distance_to Remove godot_api.json as its now in the godot_headers submodule (api.json)
2018-02-11 14:50:01 +00:00
2021-09-27 11:41:56 +00:00
init_obj.register_scene_initializer(register_example_types);
init_obj.register_scene_terminator(unregister_example_types);
Nativescript 1.1 implemented instance binding data usage This commit changes the way C++ wrapper classes work. Previously, wrapper classes were merely wrapper *interfaces*. They used the `this` pointer to store the actual foreign Godot Object. With the NativeScript 1.1 extension it is now possible to have low-overhead language binding data attached to Objects. The C++ bindings use that feature to implement *proper* wrappers and enable regular C++ inheritance usage that way. Some things might still be buggy and untested, but the C++ SimpleDemo works with those changes. new and free change, custom free will crash engine, be wary fix exporting of non-object types fix free() crash with custom resources added type tags and safe object casting fix global type registration order fix cast_to changed build system to be more self contained updated .gitignore use typeid() for type tags now fix indentation in bindings generator remove accidentally added files fix gitignore Fixed up registering tool and updated godot_headers Fix crash when calling String::split/split_floats Was casting to the wrong object type. Also adds parse_ints function to String with the same logic Better warning/error macros Change gitignore so we get our gen folders New documentation based on nativescript 1.1 Fixed GODOT_SUBCLASS macro Preventing crash when function returned null ptr Adds needed include <typeinfo> Solves this issue #168 due to not having the include of typeinfo Fix compile error of 'WARN_PRINT' and 'ERR_PRINT'. cannot pass non-trivial object of type 'godot::String' to variadic function; expected type from format string was 'char *' [-Wnon-pod-varargs] update vector3::distance_to Remove godot_api.json as its now in the godot_headers submodule (api.json)
2018-02-11 14:50:01 +00:00
2021-09-27 11:41:56 +00:00
return init_obj.init();
2017-07-25 09:54:55 +00:00
}
2017-05-18 02:14:18 +00:00
}
```
2021-08-19 23:25:36 +00:00
The `register_example_types()` should register the classes in ClassDB, very like a Godot module would do.
```cpp
2021-08-19 23:25:36 +00:00
using namespace godot;
void register_example_types() {
ClassDB::register_class<Example>();
}
```
2021-08-19 23:25:36 +00:00
Any node and resource you register will be available in the corresponding `Create...` dialog. Any class will be available to scripting as well.
2021-09-27 11:41:56 +00:00
## Included Example
2021-08-19 23:25:36 +00:00
Check the project in the `test` folder for an example on how to use and register different things.