{"id":18048275,"url":"https://github.com/relintai/gdnative_cpp","last_synced_at":"2025-04-05T05:16:23.624Z","repository":{"id":171304734,"uuid":"644508505","full_name":"Relintai/gdnative_cpp","owner":"Relintai","description":"C++ bindings for Pandemonium's GDNative module's script API","archived":false,"fork":false,"pushed_at":"2023-10-24T19:32:21.000Z","size":731,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-10T13:14:04.784Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Relintai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-23T17:00:13.000Z","updated_at":"2023-05-23T17:02:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"949ed2a5-9729-4fa2-a850-1983c2d9094c","html_url":"https://github.com/Relintai/gdnative_cpp","commit_stats":null,"previous_names":["relintai/gdnative_cpp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fgdnative_cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fgdnative_cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fgdnative_cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Relintai%2Fgdnative_cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Relintai","download_url":"https://codeload.github.com/Relintai/gdnative_cpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289431,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-30T20:12:17.105Z","updated_at":"2025-04-05T05:16:23.603Z","avatar_url":"https://github.com/Relintai.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pandemonium-cpp\n\nThis repository contains the  *C++ bindings* for the [**Pandemonium Engine**](https://github.com/pandemoniumengine/pandemonium)'s GDNative API.\n\n- [**Versioning**](#versioning)\n- [**Contributing**](#contributing)\n- [**Getting Started**](#getting-started)\n- [**Creating a simple class**](#creating-a-simple-class)\n\n## Versioning\n\nThis repositories follows the same branch versioning as the main [Pandemonium Engine\nrepository](https://github.com/pandemoniumengine/pandemonium):\n\n- `master` tracks the current development branch.\n- `3.x` tracks the development of the next 3.x minor release.\n- Other versioned branches (e.g. `3.3`, `3.2`) track the latest stable release\n  in the corresponding branch.\n\nStable releases are also tagged on this repository:\n[**Tags**](https://github.com/pandemoniumengine/pandemonium-cpp/tags).\n\n**For any project built against a stable release of Pandemonium, we recommend using\nthis repository as a Git submodule, checking out the specific tag matching your\nPandemonium version.**\n\n\u003e As the `master` and `3.x` branches are constantly getting updates, if you are\n\u003e using `pandemonium-cpp` against a more current version of Pandemonium, see the instructions\n\u003e in [**pandemonium_headers**](https://github.com/pandemoniumengine/pandemonium_headers) for\n\u003e updating the relevant files.\n\n## Contributing\n\nWe greatly appreciate help in maintaining and extending this project. If you\nwish to help out, ensure you have an account on GitHub and create a \"fork\" of\nthis repository. Rémi \"Akien\" Verschelde wrote an excellent bit of documentation\nfor the main Pandemonium project on this:\n[Pull request workflow](https://docs.pandemoniumengine.org/en/stable/community/contributing/pr_workflow.html)\n\nPlease install clang-format and copy the files in `misc/hooks` into `.git/hooks`\nso formatting is done before your changes are submitted.\n\n## Getting Started\n\n| **Build latest version of Pandemonium** | [**GitHub**](https://github.com/pandemoniumengine/pandemonium) | [**Docs**](https://pandemonium.readthedocs.io/en/latest/development/compiling/index.html) |\n| --- | --- | --- |\n\n### Setting up a new project\n\nWe recommend using Git for managing your project. The instructions below assume\nyou're using Git. Alternatively, you can download the source code directly from\nGitHub. In this case, you need to download both\n[pandemonium-cpp](https://github.com/pandemoniumengine/pandemonium-cpp) and\n[pandemonium_headers](https://github.com/pandemoniumengine/pandemonium_headers).\n\n```bash\nmkdir SimpleLibrary\ncd SimpleLibrary\nmkdir bin\nmkdir src\ngit clone --recursive https://github.com/pandemoniumengine/pandemonium-cpp\n```\n\nIf you wish to use a specific branch, add the -b option to the clone command:\n\n```bash\ngit clone --recursive https://github.com/pandemoniumengine/pandemonium-cpp -b 3.0\n```\n\nIf your project is an existing repository, use a Git submodule instead:\n\n```bash\ngit submodule add https://github.com/pandemoniumengine/pandemonium-cpp\ngit submodule update --init --recursive\n```\n\nRight now, our directory structure should look like this:\n\n```text\nSimpleLibrary/\n├─pandemonium-cpp/\n| └─pandemonium_headers/\n├─bin/\n└─src/\n```\n\n### Updating the `api.json` file\n\nOur `api.json` file contains metadata for all the classes that are part of the\nPandemonium core. This metadata is required to generate the C++ binding classes for\nuse in GDNative modules.\n\nThis file is supplied with our\n[pandemonium_headers](https://github.com/pandemoniumengine/pandemonium_headers) repository\nfor your convenience. However, if you're running a custom build of Pandemonium and\nneed access to classes that have recent changes, you must generate a new\n`api.json` file. You do this by starting your Pandemonium executable with the\nfollowing parameters:\n\n```bash\npandemonium --gdnative-generate-json-api api.json\n```\n\nNow copy the `api.json` file into your folder structure to make it easier to\naccess.\n\nSee the remark below for the extra ```custom_api_file``` SCons argument, which\nis required to tell SCons where to find your file.\n\n### Compiling the C++ bindings library\n\nThe final step is to compile our C++ bindings library:\n\n```bash\ncd pandemonium-cpp\nscons platform=\u003cyour platform\u003e generate_bindings=yes\ncd ..\n```\n\nReplace `\u003cyour platform\u003e` with either `windows`, `linux`, `osx` or `android`. If\nyou leave out `platform`, the target platform will automatically be detected\nfrom the host platform.\n\nThe resulting library will be created in `pandemonium-cpp/bin/`, take note of its name\nas it'll differ depending on the target platform.\n\n#### Compiling for Android\n\nDownload the latest [Android NDK](https://developer.android.com/ndk/downloads)\nand set the NDK path.\n\n```bash\nscons platform=android generate_bindings=yes ANDROID_NDK_ROOT=\"/PATH-TO-ANDROID-NDK/\" android_arch=\u003carch\u003e\n```\n\nThe value of `android_arch` can be `armv7, arm64v8, x86, x86_64`. Most Android\ndevices in use nowadays use an ARM architecture, so compiling for `armv7` and\n`arm64v8` is often enough when distributing an application.\n\n`ANDROID_NDK_ROOT` can also be set in the environment variables of your PC if\nyou don't want to include it in your SCons call.\n\n#### Compilation options\n\nYou can optionally add the following options to the SCons command line:\n\n- When targeting Linux, add `use_llvm=yes` to use Clang instead of GCC.\n- When targeting Windows, add `use_mingw=yes` to use MinGW instead of MSVC.\n- When targeting Windows, include `target=runtime` to build a runtime build.\n- To use an alternative `api.json` file, add `use_custom_api_file=yes\n  custom_api_file=../api.json`. Be sure to specify the correct location where\n  you placed your file (it can be a relative or absolute path).\n\n## Creating a simple class\n\nCreate `init.cpp` under `SimpleLibrary/src/` and add the following code:\n\n```cpp\n#include \u003cpandemonium.h\u003e\n#include \u003cReference.h\u003e\n\n\n\nclass SimpleClass : public Reference {\n    GDCLASS(SimpleClass, Reference);\npublic:\n    SimpleClass() { }\n\n    /** `_init` must exist as it is called by Pandemonium. */\n    void _init() { }\n\n    void test_void_method() {\n        Pandemonium::print(\"This is test\");\n    }\n\n    Variant method(Variant arg) {\n        Variant ret;\n        ret = arg;\n\n        return ret;\n    }\n\n    static void _register_methods() {\n        register_method(\"method\", \u0026SimpleClass::method);\n\n        /**\n         * The line below is equivalent to the following GDScript export:\n         *     export var _name = \"SimpleClass\"\n         **/\n        register_property\u003cSimpleClass, String\u003e(\"base/name\", \u0026SimpleClass::_name, String(\"SimpleClass\"));\n\n        /** Alternatively, with getter and setter methods: */\n        register_property\u003cSimpleClass, int\u003e(\"base/value\", \u0026SimpleClass::set_value, \u0026SimpleClass::get_value, 0);\n\n        /** Registering a signal: **/\n        // register_signal\u003cSimpleClass\u003e(\"signal_name\");\n        // register_signal\u003cSimpleClass\u003e(\"signal_name\", \"string_argument\", PANDEMONIUM_VARIANT_TYPE_STRING)\n    }\n\n    String _name;\n    int _value;\n\n    void set_value(int p_value) {\n        _value = p_value;\n    }\n\n    int get_value() const {\n        return _value;\n    }\n};\n\n/** GDNative Initialize **/\nextern \"C\" void GDN_EXPORT pandemonium_gdnative_init(pandemonium_gdnative_init_options *o) {\n    Pandemonium::gdnative_init(o);\n}\n\n/** GDNative Terminate **/\nextern \"C\" void GDN_EXPORT pandemonium_gdnative_terminate(pandemonium_gdnative_terminate_options *o) {\n    Pandemonium::gdnative_terminate(o);\n}\n\n/** NativeScript Initialize **/\nextern \"C\" void GDN_EXPORT pandemonium_nativescript_init(void *handle) {\n    Pandemonium::nativescript_init(handle);\n\n    Pandemonium::register_class\u003cSimpleClass\u003e();\n}\n```\n\n### Compiling the GDNative library\n\nOnce you've compiled the GDNative C++ bindings (see above), you can compile the GDNative library we've just created.\n\n#### Linux\n\n```bash\ncd SimpleLibrary\nclang++ -fPIC -o src/init.o -c src/init.cpp -g -O3 -std=c++14 -Ipandemonium-cpp/include -Ipandemonium-cpp/include/core -Ipandemonium-cpp/include/gen -Ipandemonium-cpp/pandemonium_headers\nclang++ -o bin/libtest.so -shared src/init.o -Lpandemonium-cpp/bin -l\u003cname of the pandemonium-cpp\u003e\n```\n\nYou'll need to replace `\u003cname of the pandemonium-cpp\u003e` with the file that was created in [**Compiling the cpp bindings library**](#compiling-the-cpp-bindings-library).\n\nThis creates the file `libtest.so` in your `SimpleLibrary/bin` directory.\n\n#### Windows\n\n```bash\ncd SimpleLibrary\ncl /Fosrc/init.obj /c src/init.cpp /nologo -EHsc -DNDEBUG /MDd /Ipandemonium-cpp\\include /Ipandemonium-cpp\\include\\core /Ipandemonium-cpp\\include\\gen /Ipandemonium-cpp\\pandemonium_headers\nlink /nologo /dll /out:bin\\libtest.dll /implib:bin\\libsimple.lib src\\init.obj pandemonium-cpp\\bin\\\u003cname of the pandemonium-cpp\u003e\n```\n\nYou'll need to replace `\u003cname of the pandemonium-cpp\u003e` with the file that was created\nin [**Compiling the cpp bindingslibrary**](#compiling-the-cpp-bindings-library).\nReplace `/MDd` with `/MD` to create a release build, which will run faster and\nbe smaller.\n\nThis creates the file `libtest.dll` in your `SimpleLibrary/bin` directory.\n\n#### macOS\n\nFor macOS, you'll need to find out which compiler flags need to be used. These\nare likely similar to Linux when using Clang, but may not be identical.\n\nIf you find suitable compiler flags for this example library, feel free to\nsubmit a pull request :slightly_smiling_face:\n\n#### Android\n\n```bash\ncd SimpleLibrary\naarch64-linux-android29-clang++ -fPIC -o src/init.o -c src/init.cpp -g -O3 -std=c++14 -Ipandemonium-cpp/include -Ipandemonium-cpp/include/core -Ipandemonium-cpp/include/gen -Ipandemonium-cpp/pandemonium_headers\naarch64-linux-android29-clang++ -o bin/libtest.so -shared src/init.o -Lpandemonium-cpp/bin -l\u003cname of the pandemonium-cpp\u003e\n```\n\nYou'll need to replace `\u003cname of the pandemonium-cpp\u003e` 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++`.\n\nThis creates the file `libtest.so` in your `SimpleLibrary/bin` directory.\n\n#### iOS\n\nGDNative isn't supported on iOS yet. This is because iOS only allows linking\nstatic libraries, not dynamic libraries. In theory, it would be possible to link\na GDNative library statically, but some of GDNative's convenience would be lost\nin the process as one would have to recompile the engine on every change. See\n[issue #30](https://github.com/pandemoniumengine/pandemonium_headers/issues/30) in the\nPandemonium headers repository for more information.\n\n#### HTML5\n\nGDNative is supported on [specific exports](https://docs.pandemoniumengine.org/en/latest/tutorials/export/exporting_for_web.html#export-options) for the HTML5 platform since Pandemonium `3.3`. Linking webassembly modules is currently underspecified in the standard, but [emscripten](https://emscripten.org/), which Pandemonium uses to build the HTML5 version, implements its own linking system.\n\nTo build GDNative libraries, you will need a recent version of [Emscripten](https://emscripten.org/).\n\n```bash\ncd SimpleLibrary\nemcc  -o bin/libtest.wasm -g -O3 -s SIDE_MODULE=1 src/init.cpp pandemonium-cpp/bin/\u003cname of the pandemonium-cpp\u003e -Ipandemonium-cpp/include -Ipandemonium-cpp/include/core -Ipandemonium-cpp/include/gen -Ipandemonium-cpp/pandemonium_headers\n```\n\nYou'll need to replace `\u003cname of the pandemonium-cpp\u003e` with the file that was created in [**Compiling the cpp bindings library**](#compiling-the-cpp-bindings-library).\n\nThis creates the file `libtest.so` in your `SimpleLibrary/bin` directory.\n\n### Creating `.gdnlib` and `.gdns` files\n\nFollow the instructions in\n[pandemonium_headers/README.md](https://github.com/pandemoniumengine/pandemonium_headers/blob/master/README.md#how-do-i-use-native-scripts-from-the-editor)\nto create the `.gdns` file. This file contains paths to GDNative libraries for\nvarious platforms. This makes the library usable from Pandemonium in a\nplatform-independent manner.\n\n### Implementing with GDScript\n\nOnce 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:\n\n```gdscript\nvar simpleclass = load(\"res://simpleclass.gdns\").new()\nsimpleclass.method(\"Test argument\")\n```\n\n### Using Pandemonium classes in C++\n\nPandemonium expects you to manage its classes the same way the engine does. These rules apply to all Pandemonium classes, including your NativeScripts, but not to any normal C++ classes used in your library.\n\n- Instantiate Objects using `_new()`, not C++'s `new` operator.\n\n```cpp\nSprite *sprite = Sprite::_new();\n```\n\n- Destroy Nodes using `queue_free()`, not C++'s `delete` operator.\n\n```cpp\nsome_old_node-\u003equeue_free();\n```\n\n- Wrap References in `Ref` instead of passing around raw pointers. They are reference-counted and don't need to be freed manually.\n\n```cpp\nRef\u003cTexture\u003e texture = resource_loader-\u003eload(\"res://icon.png\");\n```\n\n- 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.\n\n```cpp\nArray ints;\nints.append(123);\nreturn ints;\n```\n\n- Initialize your NativeScript classes in their `_init()` method, not their constructor. The constructor can't access the base class's methods.\n\n- Cast objects using `Object::cast_to`, not unsafe C-style casts or `static_cast`.\n\n```cpp\nMeshInstance *m = Object::cast_to\u003cMeshInstance\u003e(get_node(\"ChildNode\"));\n// `m` will be null if it's not a MeshInstance\nif (m) { ... }\n```\n\n- **Never** use Pandemonium types in static or global variables. The Pandemonium API isn't loaded until after their constructors are called.\n\n```cpp\nString s; // crashes\nclass SomeClass {\n    static Dictionary d; // crashes\n\n    static Node *node_a = NULL; // fine, it's just a pointer\n    static Node *node_b = Node::_new(); // crashes\n};\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frelintai%2Fgdnative_cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frelintai%2Fgdnative_cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frelintai%2Fgdnative_cpp/lists"}