Bastiaan Olij
GitHub
commit
e97e866483
267
README.md
267
README.md
|
|
@ -1,5 +1,6 @@
|
|||
# godot-cpp
|
||||
C++ bindings for the Godot script API
|
||||
|
||||
**C++ bindings for the Godot script API.**
|
||||
|
||||
The instructions below feature the new NativeScript 1.1 class structure and will only work for modules created for Godot 3.1 and later. Use the following branches for older implementations:
|
||||
|
||||
|
|
@ -8,18 +9,22 @@ Version | Branch
|
|||
**Godot 3.0 Nativescript 1.0** | [3.0](https://github.com/GodotNativeTools/godot-cpp/tree/3.0)
|
||||
**Godot 3.1 Nativescript 1.0** | [nativescript-1.0](https://github.com/GodotNativeTools/godot-cpp/tree/nativescript-1.0)
|
||||
|
||||
Index:
|
||||
- [**Contributing**](#contributing)
|
||||
- [**Getting Started**](#getting-started)
|
||||
- [**Creating a simple class**](#creating-a-simple-class)
|
||||
## Table of contents
|
||||
|
||||
- [**Contributing**](#contributing)
|
||||
- [**Getting Started**](#getting-started)
|
||||
- [**Creating a simple class**](#creating-a-simple-class)
|
||||
|
||||
## 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 the this repo.
|
||||
Rémi "Akien" Verschelde wrote an excellent bit of documentation for the main Godot project on this:
|
||||
https://docs.godotengine.org/en/3.0/community/contributing/pr_workflow.html
|
||||
|
||||
It is advisible to also install clang-format and copy the files in `misc/hooks` into `.git/hooks` so format checking is done before your changes are submitted.
|
||||
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/3.0/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
|
||||
|
||||
|
|
@ -28,29 +33,36 @@ It is advisible to also install clang-format and copy the files in `misc/hooks`
|
|||
|
||||
### Setting up a new project
|
||||
|
||||
We recommend using git for managing your project and the instructions below assume so. Alternatively you can download the source code directly from GitHub in which case you need to download both [godot-cpp](https://github.com/GodotNativeTools/godot-cpp) and [godot_headers](https://github.com/GodotNativeTools/godot_headers).
|
||||
We recommend using Git for managing your project. The instructions below assume
|
||||
you're using Git. Alternatively, you can download the source code directly from
|
||||
GitHub. In this case, you need to download both
|
||||
[godot-cpp](https://github.com/GodotNativeTools/godot-cpp) and
|
||||
[godot_headers](https://github.com/GodotNativeTools/godot_headers).
|
||||
|
||||
```
|
||||
$ mkdir SimpleLibrary
|
||||
$ cd SimpleLibrary
|
||||
$ mkdir bin
|
||||
$ mkdir src
|
||||
$ git clone --recursive https://github.com/GodotNativeTools/godot-cpp
|
||||
```bash
|
||||
mkdir SimpleLibrary
|
||||
cd SimpleLibrary
|
||||
mkdir bin
|
||||
mkdir src
|
||||
git clone --recursive https://github.com/GodotNativeTools/godot-cpp
|
||||
```
|
||||
|
||||
Note that if you wish to use a specific branch, add the -b option to the clone command:
|
||||
```
|
||||
$ git clone --recursive https://github.com/GodotNativeTools/godot-cpp -b 3.0
|
||||
If you wish to use a specific branch, add the -b option to the clone command:
|
||||
|
||||
```bash
|
||||
git clone --recursive https://github.com/GodotNativeTools/godot-cpp -b 3.0
|
||||
```
|
||||
|
||||
If your project is an existing repository, use git submodule instead:
|
||||
```
|
||||
$ git submodule add https://github.com/GodotNativeTools/godot-cpp
|
||||
$ git submodule update --init --recursive
|
||||
If your project is an existing repository, use a Git submodule instead:
|
||||
|
||||
```bash
|
||||
git submodule add https://github.com/GodotNativeTools/godot-cpp
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
Right now our directory structure should look like this:
|
||||
```
|
||||
Right now, our directory structure should look like this:
|
||||
|
||||
```text
|
||||
SimpleLibrary/
|
||||
├─godot-cpp/
|
||||
| └─godot_headers/
|
||||
|
|
@ -58,46 +70,77 @@ SimpleLibrary/
|
|||
└─src/
|
||||
```
|
||||
|
||||
### Updating the api.json
|
||||
Our api.json file contains meta data of all the classes that are part of the Godot core and are needed to generate the C++ binding classes for use in GDNative modules.
|
||||
### Updating the `api.json` file
|
||||
|
||||
This file is supplied with our godot_headers repository for your convinience but if you are running a custom build of Godot and need access to classes that have recent changes a new api.json file must be generated. You do this by starting your Godot executable with the following parameters:
|
||||
Our `api.json` file contains metadata for all the classes that are part of the
|
||||
Godot core. This metadata is required to generate the C++ binding classes for
|
||||
use in GDNative modules.
|
||||
|
||||
```
|
||||
$ godot --gdnative-generate-json-api api.json
|
||||
This file is supplied with our
|
||||
[godot_headers](https://github.com/GodotNativeTools/godot_headers) repository
|
||||
for your convenience. However, if you're running a custom build of Godot and
|
||||
need access to classes that have recent changes, you must generate a new
|
||||
`api.json` file. You do this by starting your Godot executable with the
|
||||
following parameters:
|
||||
|
||||
```bash
|
||||
godot --gdnative-generate-json-api api.json
|
||||
```
|
||||
|
||||
Now copy the api.json file into your folder structure so its easy to access. **Note** the remark below for the extra ```custom_api_file``` command line parameter needed to tell scons where to find your file.
|
||||
Now copy the `api.json` file into your folder structure to make it easier to
|
||||
access.
|
||||
|
||||
### Compiling the cpp bindings library
|
||||
The final step is to compile our cpp bindings library:
|
||||
See the remark below for the extra ```custom_api_file``` SCons argument, which
|
||||
is required to tell SCons where to find your file.
|
||||
|
||||
### Compiling the C++ bindings library
|
||||
|
||||
The final step is to compile our C++ bindings library:
|
||||
|
||||
```bash
|
||||
cd godot-cpp
|
||||
scons platform=<your platform> generate_bindings=yes
|
||||
cd ..
|
||||
```
|
||||
$ cd godot-cpp
|
||||
$ scons platform=<your platform> generate_bindings=yes
|
||||
$ cd ..
|
||||
|
||||
Replace `<your platform>` with either `windows`, `linux`, `osx` or `android`. If
|
||||
you leave out `platform`, the target platform will automatically be detected
|
||||
from the host platform.
|
||||
|
||||
The resulting library will be created in `godot-cpp/bin/`, take note of its name
|
||||
as it'll differ depending on the target platform.
|
||||
|
||||
#### Compiling for Android
|
||||
|
||||
Download the latest [Android NDK](https://developer.android.com/ndk/downloads)
|
||||
and set the NDK path.
|
||||
|
||||
```bash
|
||||
scons platform=android generate_bindings=yes ANDROID_NDK_ROOT="/PATH-TO-ANDROID-NDK/" android_arch=<arch>
|
||||
```
|
||||
For android:
|
||||
Download the latest [Android NDK](https://developer.android.com/ndk/downloads) from the official website and set NDK path.
|
||||
```
|
||||
$ scons platform=android generate_bindings=yes ANDROID_NDK_ROOT="/PATH-TO-ANDROID-NDK/" android_arch=< >
|
||||
```
|
||||
`android_arch` can be `armv7, arm64v8, x86, x86_64`.
|
||||
`ANDROID_NDK_ROOT` can also be set in the environment variables of your computer if you do not want to include it in your Scons call.
|
||||
|
||||
The value of `android_arch` can be `armv7, arm64v8, x86, x86_64`. Most Android
|
||||
devices in use nowadays use an ARM architecture, so compiling for `armv7` and
|
||||
`arm64v8` is often enough when distributing an application.
|
||||
|
||||
> Replace `<your platform>` with either `windows`, `linux`, `osx` or `android`.
|
||||
`ANDROID_NDK_ROOT` can also be set in the environment variables of your PC if
|
||||
you don't want to include it in your SCons call.
|
||||
|
||||
> Include `use_llvm=yes` for using clang++
|
||||
#### Compilation options
|
||||
|
||||
> Include `target=runtime` to build a runtime build (windows only at the moment)
|
||||
You can optionally add the following options to the SCons command line:
|
||||
|
||||
> The resulting library will be created in `godot-cpp/bin/`, take note of its name as it will be different depending on platform.
|
||||
|
||||
> If you want to use an alternative api.json file add `use_custom_api_file=yes custom_api_file=../api.json`, be sure to specify the correct location of where you placed your file.
|
||||
- When targeting Linux, add `use_llvm=yes` to use Clang instead of GCC.
|
||||
- When targeting Windows, add `use_mingw=yes` to use MinGW instead of MSVC.
|
||||
- When targeting Windows, include `target=runtime` to build a runtime build.
|
||||
- To use an alternative `api.json` file, add `use_custom_api_file=yes
|
||||
custom_api_file=../api.json`. Be sure to specify the correct location where
|
||||
you placed your file (it can be a relative or absolute path).
|
||||
|
||||
## Creating a simple class
|
||||
|
||||
Create `init.cpp` under `SimpleLibrary/src/` and add the following code
|
||||
Create `init.cpp` under `SimpleLibrary/src/` and add the following code:
|
||||
|
||||
```cpp
|
||||
#include <Godot.hpp>
|
||||
#include <Reference.hpp>
|
||||
|
|
@ -109,7 +152,7 @@ class SimpleClass : public Reference {
|
|||
public:
|
||||
SimpleClass() { }
|
||||
|
||||
/* _init must exist as it is called by Godot */
|
||||
/** `_init` must exist as it is called by Godot. */
|
||||
void _init() { }
|
||||
|
||||
void test_void_method() {
|
||||
|
|
@ -127,15 +170,15 @@ public:
|
|||
register_method("method", &SimpleClass::method);
|
||||
|
||||
/**
|
||||
* How to register exports like gdscript
|
||||
* export var _name = "SimpleClass"
|
||||
* The line below is equivalent to the following GDScript export:
|
||||
* export var _name = "SimpleClass"
|
||||
**/
|
||||
register_property<SimpleClass, String>("base/name", &SimpleClass::_name, String("SimpleClass"));
|
||||
|
||||
/* or alternatively with getter and setter methods */
|
||||
/** Alternatively, with getter and setter methods: */
|
||||
register_property<SimpleClass, int>("base/value", &SimpleClass::set_value, &SimpleClass::get_value, 0);
|
||||
|
||||
/** For registering signal **/
|
||||
/** Registering a signal: **/
|
||||
// register_signal<SimpleClass>("signal_name");
|
||||
// register_signal<SimpleClass>("signal_name", "string_argument", GODOT_VARIANT_TYPE_STRING)
|
||||
}
|
||||
|
|
@ -170,84 +213,131 @@ extern "C" void GDN_EXPORT godot_nativescript_init(void *handle) {
|
|||
}
|
||||
```
|
||||
|
||||
### Compiling
|
||||
### Compiling the GDNative library
|
||||
|
||||
*Linux*
|
||||
Once you've compiled the GDNative C++ bindings (see above), you can compile the GDNative library we've just created.
|
||||
|
||||
#### Linux
|
||||
|
||||
```bash
|
||||
cd SimpleLibrary
|
||||
clang -fPIC -o src/init.os -c src/init.cpp -g -O3 -std=c++14 -Igodot-cpp/include -Igodot-cpp/include/core -Igodot-cpp/include/gen -Igodot-cpp/godot_headers
|
||||
clang -o bin/libtest.so -shared src/init.os -Lgodot-cpp/bin -l<name of the godot-cpp>
|
||||
```
|
||||
$ cd SimpleLibrary
|
||||
$ clang -fPIC -o src/init.os -c src/init.cpp -g -O3 -std=c++14 -Igodot-cpp/include -Igodot-cpp/include/core -Igodot-cpp/include/gen -Igodot-cpp/godot_headers
|
||||
$ clang -o bin/libtest.so -shared src/init.os -Lgodot-cpp/bin -l<name of the godot-cpp>
|
||||
|
||||
You'll need to replace `<name of the godot-cpp>` with the file that was created in [**Compiling the cpp bindings library**](#compiling-the-cpp-bindings-library).
|
||||
|
||||
This creates the file `libtest.so` in your `SimpleLibrary/bin` directory.
|
||||
|
||||
#### Windows
|
||||
|
||||
```bash
|
||||
cd SimpleLibrary
|
||||
cl /Fosrc/init.obj /c src/init.cpp /nologo -EHsc -DNDEBUG /MDd /Igodot-cpp\include /Igodot-cpp\include\core /Igodot-cpp\include\gen /Igodot-cpp\godot_headers
|
||||
link /nologo /dll /out:bin\libtest.dll /implib:bin\libsimple.lib src\init.obj godot-cpp\bin\<name of the godot-cpp>
|
||||
```
|
||||
> This creates the file `libtest.so` in your `SimpleLibrary/bin` directory.
|
||||
|
||||
> You will need to replace `<name of the godot-cpp>` with the file that was created in [**Compiling the cpp bindings library**](#compiling-the-cpp-bindings-library)
|
||||
You'll need to replace `<name of the godot-cpp>` with the file that was created
|
||||
in [**Compiling the cpp bindingslibrary**](#compiling-the-cpp-bindings-library).
|
||||
Replace `/MDd` with `/MD` to create a release build, which will run faster and
|
||||
be smaller.
|
||||
|
||||
*Windows*
|
||||
This creates the file `libtest.dll` in your `SimpleLibrary/bin` directory.
|
||||
|
||||
#### macOS
|
||||
|
||||
For macOS, you'll need to find out which compiler flags need to be used. These
|
||||
are likely similar to Linux when using Clang, but may not be identical.
|
||||
|
||||
If you find suitable compiler flags for this example library, feel free to
|
||||
submit a pull request :slightly_smiling_face:
|
||||
|
||||
#### Android
|
||||
|
||||
```bash
|
||||
cd SimpleLibrary
|
||||
aarch64-linux-android29-clang -fPIC -o src/init.os -c src/init.cpp -g -O3 -std=c++14 -Igodot-cpp/include -Igodot-cpp/include/core -Igodot-cpp/include/gen -Igodot-cpp/godot_headers
|
||||
aarch64-linux-android29-clang -o bin/libtest.so -shared src/init.os -Lgodot-cpp/bin -l<name of the godot-cpp>
|
||||
```
|
||||
$ cd SimpleLibrary
|
||||
$ cl /Fosrc/init.obj /c src/init.cpp /nologo -EHsc -DNDEBUG /MDd /Igodot-cpp\include /Igodot-cpp\include\core /Igodot-cpp\include\gen /Igodot-cpp\godot_headers
|
||||
$ link /nologo /dll /out:bin\libtest.dll /implib:bin\libsimple.lib src\init.obj godot-cpp\bin\<name of the godot-cpp>
|
||||
```
|
||||
> This creates the file `libtest.dll` in your `SimpleLibrary/bin` directory.
|
||||
|
||||
> You will need to replace `<name of the godot-cpp>` with the file that was created in [**Compiling the cpp bindings library**](#compiling-the-cpp-bindings-library)
|
||||
You'll need to replace `<name of the godot-cpp>` with the file that was created in [**Compiling the cpp bindings library**](#compiling-the-cpp-bindings-library). The command above targets `arm64v8`. To target `armv7`, use `armv7a-linux-androideabi29-clang` instead of `aarch64-linux-android29-clang`.
|
||||
|
||||
> Finally replace `/MDd` with `/MD` if you're generated a runtime build.
|
||||
This creates the file `libtest.so` in your `SimpleLibrary/bin` directory.
|
||||
|
||||
*macOS*
|
||||
For OSX you need to find out what compiler flags need to be used.
|
||||
#### iOS
|
||||
|
||||
*Android*
|
||||
```
|
||||
$ cd SimpleLibrary
|
||||
$ aarch64-linux-android29-clang -fPIC -o src/init.os -c src/init.cpp -g -O3 -std=c++14 -Igodot-cpp/include -Igodot-cpp/include/core -Igodot-cpp/include/gen -Igodot-cpp/godot_headers
|
||||
$ aarch64-linux-android29-clang -o bin/libtest.so -shared src/init.os -Lgodot-cpp/bin -l<name of the godot-cpp>
|
||||
```
|
||||
> use `armv7a-linux-androideabi29-clang` for 32 bit armeabi-v7a library
|
||||
GDNative isn't supported on iOS yet. This is because iOS only allows linking
|
||||
static libraries, not dynamic libraries. In theory, it would be possible to link
|
||||
a GDNative library statically, but some of GDNative's convenience would be lost
|
||||
in the process as one would have to recompile the engine on every change. See
|
||||
[issue #30](https://github.com/GodotNativeTools/godot_headers/issues/30) in the
|
||||
Godot headers repository for more information.
|
||||
|
||||
> This creates the file `libtest.so` in your `SimpleLibrary/bin` directory.
|
||||
|
||||
> You will need to replace `<name of the godot-cpp>` with the file that was created in [**Compiling the cpp bindings library**](#compiling-the-cpp-bindings-library)
|
||||
#### HTML5
|
||||
|
||||
GDNative isn't supported on the HTML5 platform yet. Support is being tracked on
|
||||
[issue #12243](https://github.com/godotengine/godot/issues/12243) in the main
|
||||
Godot repository.
|
||||
|
||||
### Creating `.gdnlib` and `.gdns` files
|
||||
follow [godot_header/README.md](https://github.com/GodotNativeTools/godot_headers/blob/master/README.md#how-do-i-use-native-scripts-from-the-editor) to create the `.gdns`
|
||||
|
||||
### Implementing with gdscript
|
||||
Follow the instructions in
|
||||
[godot_header/README.md](https://github.com/GodotNativeTools/godot_headers/blob/master/README.md#how-do-i-use-native-scripts-from-the-editor)
|
||||
to create the `.gdns` file. This file contains paths to GDNative libraries for
|
||||
various platforms. This makes the library usable from Godot in a
|
||||
platform-independent manner.
|
||||
|
||||
### Implementing with GDScript
|
||||
|
||||
Once your GDNative library is compiled and referenced in a `.gdns` file, you can use it in GDScript or C#. Here's an example with GDScript:
|
||||
|
||||
```gdscript
|
||||
var simpleclass = load("res://simpleclass.gdns").new();
|
||||
simpleclass.method("Test argument");
|
||||
```
|
||||
|
||||
### Using Godot classes in C++
|
||||
|
||||
Godot expects you to manage its classes the same way the engine does. These rules apply to all Godot classes, including your NativeScripts, but not to any normal C++ classes used in your library.
|
||||
|
||||
- Instantiate Objects using `_new()`, not C++'s `new` operator.
|
||||
|
||||
```cpp
|
||||
Sprite *sprite = Sprite::_new();
|
||||
```
|
||||
|
||||
- Destroy Nodes using `queue_free()`, not C++'s `delete` operator.
|
||||
|
||||
```cpp
|
||||
some_old_node->queue_free();
|
||||
```
|
||||
- Wrap References in `Ref` instead of passing around raw pointers. They are ref-counted and do not need to be freed manually.
|
||||
|
||||
- Wrap References in `Ref` instead of passing around raw pointers. They are reference-counted and don't need to be freed manually.
|
||||
|
||||
```cpp
|
||||
Ref<Texture> texture = resource_loader->load("res://icon.png");
|
||||
```
|
||||
|
||||
- Pass core types that do *not* inherit Object by value. The containers (Array, Dictionary, PoolArray, String) manage their own memory and do not need to be explicitly initialized or freed.
|
||||
|
||||
```cpp
|
||||
Array ints;
|
||||
ints.append(123);
|
||||
return ints;
|
||||
```
|
||||
|
||||
- Initialize your NativeScript classes in their `_init()` method, not their constructor. The constructor can't access the base class's methods.
|
||||
|
||||
- Cast objects using `Object::cast_to`, not unsafe C-style casts or `static_cast`.
|
||||
|
||||
```cpp
|
||||
MeshInstance *m = Object::cast_to<MeshInstance>(get_node("ChildNode"));
|
||||
// m will be null if it's not a MeshInstance
|
||||
// `m` will be null if it's not a MeshInstance
|
||||
if (m) { ... }
|
||||
```
|
||||
- Never use Godot types in static or global variables. The Godot API is not loaded until after their constructors are called.
|
||||
|
||||
- **Never** use Godot types in static or global variables. The Godot API isn't loaded until after their constructors are called.
|
||||
|
||||
```cpp
|
||||
String s; // crashes
|
||||
class SomeClass {
|
||||
|
|
@ -257,4 +347,3 @@ class SomeClass {
|
|||
static Node *node_b = Node::_new(); // crashes
|
||||
};
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue