|
| 1 | +# godot_headers |
| 2 | +#### `GDNative / NativeScript` |
| 3 | + |
| 4 | +> `GDNative` enables the use of dynamically linked libraries inside of [**Godot**](https://github.com/godotengine/godot). |
| 5 | +
|
| 6 | +> `NativeScript` uses GDNative to implement scripts backed by native code. |
| 7 | +
|
| 8 | +- [**Branches**](#branches) |
| 9 | +- [**Getting Started**](#getting-started) |
| 10 | +- [**FAQ**](#faq) |
| 11 | + |
| 12 | +## Branches |
| 13 | + |
| 14 | +We maintain branches on this repo that relate directly to the main builds of Godot. |
| 15 | +Make sure you use the correct branch for the version of Godot you are using! |
| 16 | + |
| 17 | +| Branch | Version of Godot | |
| 18 | +| --- | --- | |
| 19 | +| [master](https://github.com/GodotNativeTools/godot_headers) | Godot master | |
| 20 | +| [3.2](https://github.com/GodotNativeTools/godot_headers/tree/3.2) | Godot 3.2.x | |
| 21 | +| [3.1](https://github.com/GodotNativeTools/godot_headers/tree/3.1) | Godot 3.1.x | |
| 22 | +| [3.0](https://github.com/GodotNativeTools/godot_headers/tree/3.0) | Godot 3.0.x | |
| 23 | + |
| 24 | +## Getting Started |
| 25 | + |
| 26 | +| **Build latest version of Godot** | [**GitHub**](https://github.com/godotengine/godot) | [**Docs**](https://godot.readthedocs.io/en/latest/development/compiling/index.html) | |
| 27 | +| --- | --- | --- | |
| 28 | + |
| 29 | +### Clone godot_headers into Library |
| 30 | + |
| 31 | +Clone `godot_headers` under `SimpleLibrary/` |
| 32 | + |
| 33 | +```bash |
| 34 | +cd SimpleLibrary |
| 35 | +git clone https://github.com/GodotNativeTools/godot_headers |
| 36 | +``` |
| 37 | + |
| 38 | +> Note that the master branch of this repository contains the header for the latest Godot master. If you want to build GDNative modules for older versions of Godot add `-b <version>` to the git clone command above. i.e. `git clone https://github.com/GodotNativeTools/godot_headers -b 3.0` will retrieve headers compatible with Godot 3.0. |
| 39 | +
|
| 40 | +> With the exception of a breaking change in the ARVR module between 3.0 and 3.1, GDNative plugins written for an older version of Godot will work in newer versions. |
| 41 | +
|
| 42 | +```bash |
| 43 | +[SimpleLibrary] |
| 44 | + ├── lib/ |
| 45 | + └── src/ |
| 46 | +``` |
| 47 | + |
| 48 | +### Create Script |
| 49 | + |
| 50 | +Create `test.c` under `SimpleLibrary/src/` |
| 51 | + |
| 52 | +<details> |
| 53 | + |
| 54 | +```c |
| 55 | +#include <gdnative/gdnative.h> |
| 56 | +#include <nativescript/godot_nativescript.h> |
| 57 | + |
| 58 | +#include <stdio.h> |
| 59 | + |
| 60 | +void *test_constructor(godot_object *obj, void *method_data) { |
| 61 | + printf("test.constructor()\n"); |
| 62 | + return 0; |
| 63 | +} |
| 64 | + |
| 65 | +void test_destructor(godot_object *obj, void *method_data, void *user_data) { |
| 66 | + printf("test.destructor()\n"); |
| 67 | +} |
| 68 | + |
| 69 | +/** func _ready() **/ |
| 70 | +godot_variant test_ready(godot_object *obj, void *method_data, void *user_data, int num_args, godot_variant **args) { |
| 71 | + godot_variant ret; |
| 72 | + godot_variant_new_nil(&ret); |
| 73 | + |
| 74 | + printf("_ready()\n"); |
| 75 | + |
| 76 | + return ret; |
| 77 | +} |
| 78 | + |
| 79 | +/** Library entry point **/ |
| 80 | +void GDN_EXPORT godot_gdnative_init(godot_gdnative_init_options *o) { |
| 81 | +} |
| 82 | + |
| 83 | +/** Library de-initialization **/ |
| 84 | +void GDN_EXPORT godot_gdnative_terminate(godot_gdnative_terminate_options *o) { |
| 85 | +} |
| 86 | + |
| 87 | +/** Script entry (Registering all the classes and stuff) **/ |
| 88 | +void GDN_EXPORT godot_nativescript_init(void *desc) { |
| 89 | + printf("nativescript init\n"); |
| 90 | + |
| 91 | + godot_instance_create_func create_func = { |
| 92 | + .create_func = &test_constructor, |
| 93 | + .method_data = 0, |
| 94 | + .free_func = 0 |
| 95 | + }; |
| 96 | + |
| 97 | + godot_instance_destroy_func destroy_func = { |
| 98 | + .destroy_func = &test_destructor, |
| 99 | + .method_data = 0, |
| 100 | + .free_func = 0 |
| 101 | + }; |
| 102 | + |
| 103 | + godot_nativescript_register_class(desc, "SimpleClass", "Node", create_func, destroy_func); |
| 104 | + |
| 105 | + { |
| 106 | + godot_instance_method method = { |
| 107 | + .method = &test_ready, |
| 108 | + .method_data = 0, |
| 109 | + .free_func = 0 |
| 110 | + }; |
| 111 | + |
| 112 | + godot_method_attributes attr = { |
| 113 | + .rpc_type = GODOT_METHOD_RPC_MODE_DISABLED |
| 114 | + }; |
| 115 | + |
| 116 | + godot_nativescript_register_method(desc, "SimpleClass", "_ready", attr, method); |
| 117 | + } |
| 118 | +} |
| 119 | + |
| 120 | +godot_variant GDN_EXPORT some_test_procedure(void *data, godot_array *args) { |
| 121 | + godot_variant ret; |
| 122 | + godot_variant_new_int(&ret, 42); |
| 123 | + |
| 124 | + godot_string s; |
| 125 | + godot_string_new_unicode_data(&s, L"Hello World", 11); |
| 126 | + godot_print(&s); |
| 127 | + |
| 128 | + godot_string_destroy(&s); |
| 129 | + |
| 130 | + return ret; |
| 131 | +} |
| 132 | +``` |
| 133 | +
|
| 134 | +</details> |
| 135 | +
|
| 136 | +`Expand details for example code.` |
| 137 | +
|
| 138 | +### Compile Library |
| 139 | +
|
| 140 | +On Linux: |
| 141 | +
|
| 142 | +```bash |
| 143 | +clang -g -fPIC -std=c99 -c src/test.c -I/path/to/godot/headers/ -o src/test.os |
| 144 | +clang -g -shared src/test.os -o lib/test.so |
| 145 | +``` |
| 146 | + |
| 147 | +On MacOS: |
| 148 | + |
| 149 | +```bash |
| 150 | +clang -g -fPIC -std=c99 -c src/test.c -I/path/to/godot/headers/ -o src/test.os |
| 151 | +clang -g -shared -framework Cocoa -Wl,-undefined,dynamic_lookup src/test.os -o lib/test.dylib |
| 152 | +``` |
| 153 | + |
| 154 | +- `-g` is for debugging information. |
| 155 | +- Use `godot_nativescript_*` methods only in the `nativescript_init()` function. |
| 156 | + |
| 157 | +### Create GDNativeLibrary Resource |
| 158 | +The GDNativeLibrary resource contains links to the libraries for each platform. |
| 159 | + |
| 160 | +1. Create a new resource in memory and edit it. |
| 161 | +1. Select `Resource > GDNativeLibrary`. |
| 162 | +1. Set the library file for your platform inside the inspector. |
| 163 | +1. Save the edited resource as a `.tres` |
| 164 | + |
| 165 | +<details> |
| 166 | + |
| 167 | + |
| 168 | + |
| 169 | + |
| 170 | + |
| 171 | + |
| 172 | + |
| 173 | +*Note*: Remember to save `GDNativeLibrary` as `.gdnlib` |
| 174 | + |
| 175 | +</details> |
| 176 | + |
| 177 | +`Expand details for screenshots.` |
| 178 | + |
| 179 | +### Using GDNativeLibrary in GDScript |
| 180 | + |
| 181 | +```gdscript |
| 182 | +extends Node |
| 183 | +
|
| 184 | +func _ready(): |
| 185 | + var gdn = GDNative.new() |
| 186 | + gdn.library = load("res://lib/libtest.tres") |
| 187 | +
|
| 188 | + gdn.initialize() |
| 189 | +
|
| 190 | + var res = gdn.call_native("standard_varcall", "some_test_procedure", []) |
| 191 | +
|
| 192 | + print("result: ", res) |
| 193 | +
|
| 194 | + gdn.terminate() |
| 195 | +``` |
| 196 | + |
| 197 | +### Attaching GDNativeLibrary to a Node |
| 198 | + |
| 199 | +1. Attach a new script to a node. |
| 200 | +1. In the pop-up dialog, choose NativeScript in the `Language` menu. |
| 201 | +1. Enable built-in script, or create a `.gdn` file, which only contains a name. |
| 202 | +1. Specify the `Class Name`. |
| 203 | +1. Press `Create`. |
| 204 | + |
| 205 | +The GDNativeLibrary field in a NativeScript is empty by default. |
| 206 | + |
| 207 | + |
| 208 | +<details> |
| 209 | + |
| 210 | + |
| 211 | + |
| 212 | + |
| 213 | + |
| 214 | +</details> |
| 215 | + |
| 216 | +`Expand details for screenshots.` |
| 217 | + |
| 218 | +## FAQ |
| 219 | + |
| 220 | +**What is the difference between `GDNative` and `NativeScript`?** |
| 221 | + |
| 222 | +`GDNative` is a new class that can call native functions in libraries. |
| 223 | +GDScript / VisualScript / C#, etc, are able to use this class. |
| 224 | + |
| 225 | +Godot treats `NativeScript` as a scripting language, enabling the |
| 226 | +use of GDNative to implement scripts backed by native code. |
| 227 | + |
| 228 | +**Which languages are binding as a NativeScript?** |
| 229 | + |
| 230 | +[**C++**](https://github.com/GodotNativeTools/cpp_bindings), |
| 231 | +[**D**](https://github.com/GodotNativeTools/d_bindings), |
| 232 | +[**Nim**](https://github.com/pragmagic/godot-nim) |
| 233 | + |
| 234 | +**Can you debug NativeScripts?** |
| 235 | + |
| 236 | +You must compile the library with debug |
| 237 | +symbols, and then you can use your debugger as usual. |
| 238 | + |
| 239 | +**Can you use one GDNativeLibrary for all NativeScripts?** |
| 240 | + |
| 241 | +You can! ✨ |
| 242 | + |
| 243 | +**What is the reason behind the name "GDNative"?** |
| 244 | + |
| 245 | +GDNative was originally named "cscript" because it exposes a C API, but people |
| 246 | +mistook a relation to C#, which is sometimes abbreviated as "cs". Then named "DLScript", but that brought up some confusion, so we settled with |
| 247 | +GDNative. 📖 |
0 commit comments