{"id":16209274,"url":"https://github.com/gilzoide/high-level-gdnative","last_synced_at":"2025-11-01T04:04:28.026Z","repository":{"id":70590402,"uuid":"378157475","full_name":"gilzoide/high-level-gdnative","owner":"gilzoide","description":"Single header GDNative high level API for C/C++","archived":false,"fork":false,"pushed_at":"2022-12-19T22:14:14.000Z","size":574,"stargazers_count":20,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-17T05:11:24.777Z","etag":null,"topics":["gdnative","godot","godot-engine","single-file","single-header","single-header-lib"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gilzoide.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"gilzoide","tidelift":null,"community_bridge":null,"liberapay":"gilzoide","issuehunt":null,"otechie":null,"custom":["https://www.buymeacoffee.com/gilzoide"]}},"created_at":"2021-06-18T13:22:18.000Z","updated_at":"2025-01-07T05:26:40.000Z","dependencies_parsed_at":"2023-04-25T22:02:16.515Z","dependency_job_id":null,"html_url":"https://github.com/gilzoide/high-level-gdnative","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gilzoide%2Fhigh-level-gdnative","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gilzoide%2Fhigh-level-gdnative/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gilzoide%2Fhigh-level-gdnative/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gilzoide%2Fhigh-level-gdnative/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gilzoide","download_url":"https://codeload.github.com/gilzoide/high-level-gdnative/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244389792,"owners_count":20445002,"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":["gdnative","godot","godot-engine","single-file","single-header","single-header-lib"],"created_at":"2024-10-10T10:28:59.742Z","updated_at":"2025-11-01T04:04:27.997Z","avatar_url":"https://github.com/gilzoide.png","language":"C++","funding_links":["https://ko-fi.com/gilzoide","https://liberapay.com/gilzoide","https://www.buymeacoffee.com/gilzoide"],"categories":[],"sub_categories":[],"readme":"# High level GDNative C/C++ API (HGDN)\nSingle header [GDNative](https://docs.godotengine.org/en/stable/tutorials/plugins/gdnative/gdnative-c-example.html)\nhigh level API for C/C++.\n\n- Single header: just copy `hgdn.h` to your project, put `#define HGDN_IMPLEMENTATION`\n  in a single C/C++ source file before `#include`ing it and compile.\n- Depends only on [godot-headers](https://github.com/godotengine/godot-headers),\n  so GDNative libraries can be built with a single compiler invocation.\n  No need to generate Godot API bindings if you only use core GDNative stuff.\n- `hgdn_gdnative_init` fetches all current GDNative APIs.\n- Useful definitions for all math types, including Vector2, Vector3 and Color.\n- Wrappers around strings and pool arrays with pointer and size available.\n- Functions to get values from method arguments or native calls\n  argument arrays.\n- Functions to create Variants, Strings, Arrays, Pool Arrays and Dictionaries\n  in single calls.\n- Overloaded macro/functions to create Variants, available in C11 and C++.\n- Macros to assert arguments preconditions, like expected argument count and\n  (TODO) expected argument types.\n\n\n## Documentation\nCode is documented using [Doxygen](https://www.doxygen.nl) and is available [online here](https://gilzoide.github.io/high-level-gdnative/).\n\n\n## Usage example\nFor a working example with full Godot project, check out the\n[high-level-gdnative-example](https://github.com/gilzoide/high-level-gdnative-example)\nrepository.\n\n```c\n// example.c\n\n// 1) #define HGDN_IMPLEMENTATION on exactly one C/C++ file and include hgdn.h\n// Optionally #define other compile-time options, check out hgdn.h for documentation\n#define HGDN_STATIC\n#define HGDN_IMPLEMENTATION\n#include \"hgdn.h\"\n\n// 2.a) Declare native functions to be used by script code, if there are any\n//      Any function with prototype `godot_variant (godot_array *)` can be called in script with\n//      `gdnative_instance.call_native(\"standard_varcall\", \"\u003cname of your C function\", [\"some\", \"arguments\", \"...\"])`\nGDN_EXPORT godot_variant get_message(godot_array *args) {\n    // `hgdn_new_variant` is type-aware using C11 _Generic/C++ overloads\n    // In this case, it calls `hgdn_new_cstring_variant`\n    return hgdn_new_variant(\"Hello world!\");\n}\n\nGDN_EXPORT godot_variant square(godot_array *args) {\n    // returns null and prints an error if array size \u003c 1\n    HGDN_ASSERT_ARRAY_SIZE(args, 1);\n    godot_real x = hgdn_array_get_real(args, 0);\n    // Overloaded to `hgdn_new_real_variant(x * x)`\n    return hgdn_new_variant(x * x);\n}\n\nGDN_EXPORT godot_variant sum_ints(godot_array *args) {\n    HGDN_ASSERT_ARRAY_SIZE(args, 1);\n    hgdn_int_array int_array = hgdn_array_get_int_array(args, 0);\n    int sum = 0;\n    for (int i = 0; i \u003c int_array.size; i++) {\n        sum += int_array.ptr[i];\n    }\n    // Overloaded to `hgdn_new_int_variant(sum)`\n    return hgdn_new_variant(sum);\n}\n\n// 2.b) Declare NativeScript methods, if there are any (TODO)\n\n\n// 3.a) Add `godot_gdnative_init`, the function that will be called when Godot\n// initializes this GDNativeLibrary, and call `hgdn_gdnative_init` from it.\nGDN_EXPORT void godot_gdnative_init(godot_gdnative_init_options *options) {\n    // `hgdn_gdnative_init` needs to be called before any other HGDN call,\n    // as it populates the global API pointers from options\n    hgdn_gdnative_init(options);\n    // `hgdn_print` uses `printf` formatted values\n    hgdn_print(\"GDNative initialized%s\", options-\u003ein_editor ? \" in editor\" : \"\");\n}\n\n// 3.b) Add `godot_gdnative_terminate`, the function that will be called when Godot\n// unloads this GDNativeLibrary, and call `hgdn_gdnative_terminate` from it.\nGDN_EXPORT void godot_gdnative_terminate(godot_gdnative_terminate_options *options) {\n    hgdn_gdnative_terminate(options);\n}\n\n// 4) Add `godot_nativescript_init`, the function that will be called when Godot\n// initializes a NativeScript with this GDNativeLibrary, and register classes,\n// if there are any.\nGDN_EXPORT void godot_nativescript_init(void *desc) {\n    // TODO\n}\n```\n\n```gdscript\n# example.gd\nextends Reference\n\nfunc _ready() -\u003e void:\n\tvar example = GDNative.new()\n\texample.library = preload(\"res://path_to_gdnativelibrary.gdnlib\")\n\texample.initialize()  # --\u003e \"GDNative initialized\"\n\tprint(example.call_native(\"standard_varcall\", \"get_message\", []))  # --\u003e \"Hello world!\"\n\tprint(example.call_native(\"standard_varcall\", \"square\", [5]))  # --\u003e 25\n\tprint(example.call_native(\"standard_varcall\", \"sum_ints\", [[1, 2.5, 3]]))  # --\u003e 6\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgilzoide%2Fhigh-level-gdnative","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgilzoide%2Fhigh-level-gdnative","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgilzoide%2Fhigh-level-gdnative/lists"}