Skip to content

Commit

Permalink
Try #1011:
Browse files Browse the repository at this point in the history
  • Loading branch information
@bors
bors[bot] authored Jan 21, 2023
2 parents a2a85e1 + caa76a4 commit b983ee2
Show file tree
Hide file tree
Showing 38 changed files with 536 additions and 230 deletions.
1 change: 1 addition & 0 deletions gdnative-sys/build.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -446,6 +446,7 @@ mod api_wrapper {
("ANDROID", 1, 0) => format_ident!("godot_gdnative_ext_android_api_struct"),
("ANDROID", 1, 1) => format_ident!("godot_gdnative_ext_android_api_struct"),
("ARVR", 1, 1) => format_ident!("godot_gdnative_ext_arvr_api_struct"),
("ARVR", 1, 2) => format_ident!("godot_gdnative_ext_arvr_1_2_api_struct"),
("VIDEODECODER", 0, 1) => format_ident!("godot_gdnative_ext_videodecoder_api_struct"),
("NET", 3, 1) => format_ident!("godot_gdnative_ext_net_api_struct"),
("NET", maj, min) => format_ident!("godot_gdnative_ext_net_{}_{}_api_struct", maj, min),
Expand Down
2 changes: 1 addition & 1 deletion gdnative-sys/godot_headers/LICENSE.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# MIT License

Copyright (c) 2017-2020 GodotNativeTools
Copyright (c) 2017-2022 Godot Engine contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
203 changes: 119 additions & 84 deletions gdnative-sys/godot_headers/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,43 +1,58 @@
# godot_headers
#### `GDNative / NativeScript`
# godot-headers

> `GDNative` enables the use of dynamically linked libraries inside of [**Godot**](https://github.com/godotengine/godot).
This repository contains C headers for
[**Godot Engine**](https://github.com/godotengine/godot)'s *GDNative* API,
which can be used to write *NativeScripts*.

> `GDNative` enables the use of dynamically linked libraries inside of
> [**Godot**](https://github.com/godotengine/godot).
> `NativeScript` uses GDNative to implement scripts backed by native code.
- [**Branches**](#branches)
- [**Getting Started**](#getting-started)
- [**FAQ**](#faq)
- [**Versioning**](#versioning)
- [**Getting Started**](#getting-started)
- [**FAQ**](#faq)
- [**Updating Headers**](#updating-headers)

## Versioning

## Branches
This repositories follows the same branch versioning as the main [Godot Engine
repository](https://github.com/godotengine/godot):

We maintain branches on this repo that relate directly to the main builds of Godot.
Make sure you use the correct branch for the version of Godot you are using!
- `master` tracks the current development branch. As this is a moving target,
the headers in this repository may not always be fully in sync with upstream.
See [**Updating Headers**](#updating-headers) if you need to bring
them up to date.
- `3.x` tracks the development of the next 3.x minor release. Like `master`, it
might not always be fully up-to-date with upstream.
- Other versioned branches (e.g. `3.3`, `3.2`) track the latest stable release
in the corresponding branch.

| Branch | Version of Godot |
| --- | --- |
| [master](https://github.com/GodotNativeTools/godot_headers) | Godot master |
| [3.2](https://github.com/GodotNativeTools/godot_headers/tree/3.2) | Godot 3.2.x |
| [3.1](https://github.com/GodotNativeTools/godot_headers/tree/3.1) | Godot 3.1.x |
| [3.0](https://github.com/GodotNativeTools/godot_headers/tree/3.0) | Godot 3.0.x |
Stable releases are also tagged on this repository:
[**Tags**](https://github.com/godotengine/godot-headers/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.**

## Getting Started

| **Build latest version of Godot** | [**GitHub**](https://github.com/godotengine/godot) | [**Docs**](https://godot.readthedocs.io/en/latest/development/compiling/index.html) |
| **Build latest version of Godot** | [**GitHub**](https://github.com/godotengine/godot) | [**Docs**](https://docs.godotengine.org/en/latest/development/compiling/index.html) |
| --- | --- | --- |

### Clone godot_headers into Library
### Clone `godot-headers` into Library

Clone `godot_headers` under `SimpleLibrary/`
Clone `godot-headers` under `SimpleLibrary/`

```bash
cd SimpleLibrary
git clone https://github.com/GodotNativeTools/godot_headers
git clone https://github.com/godotengine/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.
Note that the master branch of this repository contains the headers for the
latest Godot `master` branch. See [**Versioning**](#versioning) for details.
You can use `-b <version>` to the above Git clone command to retrieve a specific
branch or tag (e.g. `-b 3.x` or `-b godot-3.3.3-stable`).

```bash
[SimpleLibrary]
Expand All @@ -47,7 +62,7 @@ git clone https://github.com/GodotNativeTools/godot_headers

### Create Script

Create `test.c` under `SimpleLibrary/src/`
Create `test.c` under `SimpleLibrary/src/`.

<details>

Expand All @@ -58,22 +73,22 @@ Create `test.c` under `SimpleLibrary/src/`
#include <stdio.h>

void *test_constructor(godot_object *obj, void *method_data) {
printf("test.constructor()\n");
return 0;
printf("test.constructor()\n");
return 0;
}

void test_destructor(godot_object *obj, void *method_data, void *user_data) {
printf("test.destructor()\n");
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);
godot_variant ret;
godot_variant_new_nil(&ret);

printf("_ready()\n");
printf("_ready()\n");

return ret;
return ret;
}

/** Library entry point **/
Expand All @@ -90,64 +105,64 @@ void GDN_EXPORT godot_nativescript_init(void *desc) {

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);
}
.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_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 s;
godot_string_new_with_wide_string(&s, L"Hello World", 11);
godot_print(&s);

godot_string_destroy(&s);
godot_string_destroy(&s);

return ret;
return ret;
}
```
</details>
`Expand details for example code.`
Expand *Details* for example code.
### Compile Library
On Linux:
```bash
clang -g -fPIC -std=c99 -c src/test.c -I/path/to/godot/headers/ -o src/test.os
clang -g -fPIC -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:

```bash
clang -g -fPIC -std=c99 -c src/test.c -I/path/to/godot/headers/ -o src/test.os
clang -g -fPIC -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
```

Expand All @@ -158,9 +173,9 @@ clang -g -shared -framework Cocoa -Wl,-undefined,dynamic_lookup src/test.os -o l
The GDNativeLibrary resource contains links to the libraries for each platform.

1. Create a new resource in memory and edit it.
1. Select `Resource > GDNativeLibrary`.
1. Set the library file for your platform inside the inspector.
1. Save the edited resource as a `.tres`
2. Select `Resource > GDNativeLibrary`.
3. Set the library file for your platform inside the inspector.
4. Save the edited resource as a `.tres`

<details>

Expand All @@ -174,33 +189,33 @@ The GDNativeLibrary resource contains links to the libraries for each platform.

</details>

`Expand details for screenshots.`
Expand *Details* for screenshots.

### Using GDNativeLibrary in GDScript

```gdscript
extends Node
func _ready():
var gdn = GDNative.new()
gdn.library = load("res://lib/libtest.tres")
var gdn = GDNative.new()
gdn.library = load("res://lib/libtest.tres")
gdn.initialize()
gdn.initialize()
var res = gdn.call_native("standard_varcall", "some_test_procedure", [])
var res = gdn.call_native("standard_varcall", "some_test_procedure", [])
print("result: ", res)
print("result: ", res)
gdn.terminate()
gdn.terminate()
```

### Attaching GDNativeLibrary to a Node

1. Attach a new script to a node.
1. In the pop-up dialog, choose NativeScript in the `Language` menu.
1. Enable built-in script, or create a `.gdn` file, which only contains a name.
1. Specify the `Class Name`.
1. Press `Create`.
2. In the pop-up dialog, choose NativeScript in the `Language` menu.
3. Enable built-in script, or create a `.gdn` file, which only contains a name.
4. Specify the `Class Name`.
5. Press `Create`.

The GDNativeLibrary field in a NativeScript is empty by default.

Expand All @@ -213,7 +228,7 @@ The GDNativeLibrary field in a NativeScript is empty by default.

</details>

`Expand details for screenshots.`
Expand *Details* for screenshots.

## FAQ

Expand All @@ -227,8 +242,8 @@ use of GDNative to implement scripts backed by native code.

**Which languages are binding as a NativeScript?**

[**C++**](https://github.com/GodotNativeTools/cpp_bindings),
[**D**](https://github.com/GodotNativeTools/d_bindings),
[**C++**](https://github.com/godotengine/godot-cpp),
[**D**](https://github.com/godot-d/godot-d),
[**Nim**](https://github.com/pragmagic/godot-nim)

**Can you debug NativeScripts?**
Expand All @@ -243,5 +258,25 @@ 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. 📖
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. 📖

## Updating Headers

See [**Versioning**](#versioning) for details on the Godot versions tracked by
each branch of this repository.

If the relevant branch is not up-to-date for your needs, or if you want to sync
the headers with your own modified version of Godot, here is the update
procedure used to sync this repository with upstream releases:

- Compile [Godot Engine](https://github.com/godotengine/godot) at the specific
version/commit which you are using.
- Use the compiled executable to generate the `api.json` file with:
`godot --gdnative-generate-json-api api.json`
- Copy the file `modules/gdnative/gdnative_api.json` to this repository.
- Copy the files and folders from `modules/gdnative/include` to this repository,
overwriting existing content. (To be sure to be in sync, you can delete the
folders of this repository first, then copy the upstream folders in place.)
Make sure that you compiled the correct Godot version so that the generated
`gdnative_api_struct.gen.h` is up-to-date.
10 changes: 5 additions & 5 deletions gdnative-sys/godot_headers/android/godot_android.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
/* GODOT ENGINE */
/* https://godotengine.org */
/*************************************************************************/
/* Copyright (c) 2007-2020 Juan Linietsky, Ariel Manzur. */
/* Copyright (c) 2014-2020 Godot Engine contributors (cf. AUTHORS.md). */
/* Copyright (c) 2007-2022 Juan Linietsky, Ariel Manzur. */
/* Copyright (c) 2014-2022 Godot Engine contributors (cf. AUTHORS.md). */
/* */
/* Permission is hereby granted, free of charge, to any person obtaining */
/* a copy of this software and associated documentation files (the */
Expand All @@ -28,8 +28,8 @@
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
/*************************************************************************/

#ifndef GODOT_ANDROID_GDN_H
#define GODOT_ANDROID_GDN_H
#ifndef GODOT_ANDROID_H
#define GODOT_ANDROID_H

#include <gdnative/gdnative.h>

Expand All @@ -53,4 +53,4 @@ bool GDAPI godot_android_is_activity_resumed();
}
#endif

#endif /* !GODOT_ANDROID_GDN_H */
#endif // GODOT_ANDROID_H
Loading

0 comments on commit b983ee2

Please sign in to comment.