GDNative
enables the use of dynamically linked libraries inside of Godot.
NativeScript
uses GDNative to implement scripts backed by native code.
Build latest version of Godot | GitHub | Docs |
---|
Clone godot_headers
under SimpleLibrary/
cd SimpleLibrary
git clone https://github.com/GodotNativeTools/godot_headers
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.
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.
[SimpleLibrary]
├── lib/
└── src/
Create test.c
under SimpleLibrary/src/
#include <gdnative/gdnative.h>
#include <nativescript/godot_nativescript.h>
#include <stdio.h>
void *test_constructor(godot_object *obj, void *method_data) {
printf("test.constructor()\n");
return 0;
}
void test_destructor(godot_object *obj, void *method_data, void *user_data) {
printf("test.destructor()\n");
}
/** func _ready() **/
godot_variant test_ready(godot_object *obj, void *method_data, void *user_data, int num_args, godot_variant **args) {
godot_variant ret;
godot_variant_new_nil(&ret);
printf("_ready()\n");
return ret;
}
/** Library entry point **/
void GDN_EXPORT godot_gdnative_init(godot_gdnative_init_options *o) {
}
/** Library de-initialization **/
void GDN_EXPORT godot_gdnative_terminate(godot_gdnative_terminate_options *o) {
}
/** Script entry (Registering all the classes and stuff) **/
void GDN_EXPORT godot_nativescript_init(void *desc) {
printf("nativescript init\n");
godot_instance_create_func create_func = {
.create_func = &test_constructor,
.method_data = 0,
.free_func = 0
};
godot_instance_destroy_func destroy_func = {
.destroy_func = &test_destructor,
.method_data = 0,
.free_func = 0
};
godot_nativescript_register_class(desc, "SimpleClass", "Node", create_func, destroy_func);
{
godot_instance_method method = {
.method = &test_ready,
.method_data = 0,
.free_func = 0
};
godot_method_attributes attr = {
.rpc_type = GODOT_METHOD_RPC_MODE_DISABLED
};
godot_nativescript_register_method(desc, "SimpleClass", "_ready", attr, method);
}
}
godot_variant GDN_EXPORT some_test_procedure(void *data, godot_array *args) {
godot_variant ret;
godot_variant_new_int(&ret, 42);
godot_string s;
godot_string_new_unicode_data(&s, L"Hello World", 11);
godot_print(&s);
godot_string_destroy(&s);
return ret;
}
Expand details for example code.
On Linux:
clang -g -fPIC -std=c99 -c src/test.c -I/path/to/godot/headers/ -o src/test.os
clang -g -shared src/test.os -o lib/test.so
On MacOS:
clang -g -fPIC -std=c99 -c src/test.c -I/path/to/godot/headers/ -o src/test.os
clang -g -shared -framework Cocoa -Wl,-undefined,dynamic_lookup src/test.os -o lib/test.dylib
-g
is for debugging information.- Use
godot_nativescript_*
methods only in thenativescript_init()
function.
The GDNativeLibrary resource contains links to the libraries for each platform.
- Create a new resource in memory and edit it.
- Select
Resource > GDNativeLibrary
. - Set the library file for your platform inside the inspector.
- Save the edited resource as a
.tres
Expand details for screenshots.
extends Node
func _ready():
var gdn = GDNative.new()
gdn.library = load("res://lib/libtest.tres")
gdn.initialize()
var res = gdn.call_native("standard_varcall", "some_test_procedure", [])
print("result: ", res)
gdn.terminate()
- Attach a new script to a node.
- In the pop-up dialog, choose NativeScript in the
Language
menu. - Enable built-in script, or create a
.gdn
file, which only contains a name. - Specify the
Class Name
. - Press
Create
.
The GDNativeLibrary field in a NativeScript is empty by default.
Expand details for screenshots.
What is the difference between GDNative
and NativeScript
?
GDNative
is a new class that can call native functions in libraries.
GDScript / VisualScript / C#, etc, are able to use this class.
Godot treats NativeScript
as a scripting language, enabling the
use of GDNative to implement scripts backed by native code.
Which languages are binding as a NativeScript?
Can you debug NativeScripts?
You must compile the library with debug symbols, and then you can use your debugger as usual.
Are NativeScripts in Godot 3.0?
They are! 🎉
Can you use one GDNativeLibrary for all NativeScripts?
You can! ✨
What is the reason behind the name "GDNative"?
GDNative was originally named "cscript" because it exposes a C API, but people mistook a relation to C#, which is sometimes abbreviated as "cs". Then named "DLScript", but that brought up some confusion, so we settled with GDNative. 📖