{"id":13440077,"url":"https://github.com/godotengine/godot-headers","last_synced_at":"2025-04-05T03:07:55.996Z","repository":{"id":41130594,"uuid":"83910633","full_name":"godotengine/godot-headers","owner":"godotengine","description":"Headers for the Godot API supplied by the GDNative module.","archived":false,"fork":false,"pushed_at":"2023-12-12T12:49:38.000Z","size":3391,"stargazers_count":386,"open_issues_count":10,"forks_count":93,"subscribers_count":29,"default_branch":"3.x","last_synced_at":"2025-03-29T02:05:00.081Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/godotengine.png","metadata":{"funding":{"patreon":"godotengine","custom":"https://godotengine.org/donate"},"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}},"created_at":"2017-03-04T17:15:34.000Z","updated_at":"2025-03-27T21:58:50.000Z","dependencies_parsed_at":"2023-11-09T12:46:28.166Z","dependency_job_id":"70f272fd-275c-40f1-a9bc-8515178cc121","html_url":"https://github.com/godotengine/godot-headers","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godotengine%2Fgodot-headers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godotengine%2Fgodot-headers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godotengine%2Fgodot-headers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godotengine%2Fgodot-headers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/godotengine","download_url":"https://codeload.github.com/godotengine/godot-headers/tar.gz/refs/heads/3.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280269,"owners_count":20912967,"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-07-31T03:01:19.602Z","updated_at":"2025-04-05T03:07:55.976Z","avatar_url":"https://github.com/godotengine.png","language":"C","funding_links":["https://patreon.com/godotengine","https://godotengine.org/donate"],"categories":["C"],"sub_categories":[],"readme":"# godot-headers\n\nThis repository contains C headers for\n[**Godot Engine**](https://github.com/godotengine/godot)'s *GDNative* API,\nwhich can be used to write *NativeScripts*.\n\n\u003e `GDNative` enables the use of dynamically linked libraries inside of\n\u003e [**Godot**](https://github.com/godotengine/godot).\n\n\u003e `NativeScript` uses GDNative to implement scripts backed by native code.\n\n- [**Versioning**](#versioning)\n- [**Getting Started**](#getting-started)\n- [**FAQ**](#faq)\n- [**Updating Headers**](#updating-headers)\n\n## Versioning\n\nThis repositories follows the same branch versioning as the main [Godot Engine\nrepository](https://github.com/godotengine/godot):\n\n- `master` tracks the current development branch. As this is a moving target,\n  the headers in this repository may not always be fully in sync with upstream.\n  See [**Updating Headers**](#updating-headers) if you need to bring\n  them up to date.\n- `3.x` tracks the development of the next 3.x minor release. Like `master`, it\n  might not always be fully up-to-date with upstream.\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/godotengine/godot-headers/tags).\n\n**For any project built against a stable release of Godot, we recommend using\nthis repository as a Git submodule, checking out the specific tag matching your\nGodot version.**\n\n## Getting Started\n\n| **Build latest version of Godot** | [**GitHub**](https://github.com/godotengine/godot) | [**Docs**](https://docs.godotengine.org/en/latest/development/compiling/index.html) |\n| --- | --- | --- |\n\n### Clone `godot-headers` into Library\n\nClone `godot-headers` under `SimpleLibrary/`\n\n```bash\ncd SimpleLibrary\ngit clone https://github.com/godotengine/godot-headers\n```\n\nNote that the master branch of this repository contains the headers for the\nlatest Godot `master` branch. See [**Versioning**](#versioning) for details.\nYou can use `-b \u003cversion\u003e` to the above Git clone command to retrieve a specific\nbranch or tag (e.g. `-b 3.x` or `-b godot-3.3.3-stable`).\n\n```bash\n[SimpleLibrary]\n  ├── lib/\n  └── src/\n```\n\n### Create Script\n\nCreate `test.c` under `SimpleLibrary/src/`.\n\n\u003cdetails\u003e\n\n```c\n#include \u003cgdnative/gdnative.h\u003e\n#include \u003cnativescript/godot_nativescript.h\u003e\n\n#include \u003cstdio.h\u003e\n\nvoid *test_constructor(godot_object *obj, void *method_data) {\n\tprintf(\"test.constructor()\\n\");\n\treturn 0;\n}\n\nvoid test_destructor(godot_object *obj, void *method_data, void *user_data) {\n\tprintf(\"test.destructor()\\n\");\n}\n\n/** func _ready() **/\ngodot_variant test_ready(godot_object *obj, void *method_data, void *user_data, int num_args, godot_variant **args) {\n\tgodot_variant ret;\n\tgodot_variant_new_nil(\u0026ret);\n\n\tprintf(\"_ready()\\n\");\n\n\treturn ret;\n}\n\n/** Library entry point **/\nvoid GDN_EXPORT godot_gdnative_init(godot_gdnative_init_options *o) {\n}\n\n/** Library de-initialization **/\nvoid GDN_EXPORT godot_gdnative_terminate(godot_gdnative_terminate_options *o) {\n}\n\n/** Script entry (Registering all the classes and stuff) **/\nvoid GDN_EXPORT godot_nativescript_init(void *desc) {\n\tprintf(\"nativescript init\\n\");\n\n\tgodot_instance_create_func create_func = {\n\t\t.create_func = \u0026test_constructor,\n\t\t.method_data = 0,\n\t\t.free_func   = 0\n\t};\n\n\tgodot_instance_destroy_func destroy_func = {\n\t\t.destroy_func = \u0026test_destructor,\n\t\t.method_data  = 0,\n\t\t.free_func    = 0\n\t};\n\n\tgodot_nativescript_register_class(desc, \"SimpleClass\", \"Node\", create_func, destroy_func);\n\n\t{\n\t\tgodot_instance_method method = {\n\t\t\t.method = \u0026test_ready,\n\t\t\t.method_data = 0,\n\t\t\t.free_func = 0\n\t\t};\n\n\t\tgodot_method_attributes attr = {\n\t\t\t.rpc_type = GODOT_METHOD_RPC_MODE_DISABLED\n\t\t};\n\n\t\tgodot_nativescript_register_method(desc, \"SimpleClass\", \"_ready\", attr, method);\n\t}\n}\n\ngodot_variant GDN_EXPORT some_test_procedure(void *data, godot_array *args) {\n\tgodot_variant ret;\n\tgodot_variant_new_int(\u0026ret, 42);\n\n\tgodot_string s;\n\tgodot_string_new_with_wide_string(\u0026s, L\"Hello World\", 11);\n\tgodot_print(\u0026s);\n\n\tgodot_string_destroy(\u0026s);\n\n\treturn ret;\n}\n```\n\n\u003c/details\u003e\n\nExpand *Details* for example code.\n\n### Compile Library\n\nOn Linux:\n\n```bash\nclang -g -fPIC -c src/test.c -I/path/to/godot/headers/ -o src/test.os\nclang -g -shared src/test.os -o lib/test.so\n```\n\nOn MacOS:\n\n```bash\nclang -g -fPIC -c src/test.c -I/path/to/godot/headers/ -o src/test.os\nclang -g -shared -framework Cocoa -Wl,-undefined,dynamic_lookup src/test.os -o lib/test.dylib\n```\n\n- `-g` is for debugging information.\n- Use `godot_nativescript_*` methods only in the `nativescript_init()` function.\n\n### Create GDNativeLibrary Resource\nThe GDNativeLibrary resource contains links to the libraries for each platform.\n\n1. Create a new resource in memory and edit it.\n2. Select `Resource \u003e GDNativeLibrary`.\n3. Set the library file for your platform inside the inspector.\n4. Save the edited resource as a `.tres`\n\n\u003cdetails\u003e\n\n![](images/faq/dllibrary_create_new_resource.png?raw=true)\n\n![](images/faq/dllibrary_create_new_dllibrary.png?raw=true)\n\n![](images/faq/dllibrary_save_as_resource.png?raw=true)\n\n*Note*: Remember to save `GDNativeLibrary` as `.gdnlib`\n\n\u003c/details\u003e\n\nExpand *Details* for screenshots.\n\n### Using GDNativeLibrary in GDScript\n\n```gdscript\nextends Node\n\nfunc _ready():\n\tvar gdn = GDNative.new()\n\tgdn.library = load(\"res://lib/libtest.tres\")\n\n\tgdn.initialize()\n\n\tvar res = gdn.call_native(\"standard_varcall\", \"some_test_procedure\", [])\n\n\tprint(\"result: \", res)\n\n\tgdn.terminate()\n```\n\n### Attaching GDNativeLibrary to a Node\n\n1. Attach a new script to a node.\n2. In the pop-up dialog, choose NativeScript in the `Language` menu.\n3. Enable built-in script, or create a `.gdn` file, which only contains a name.\n4. Specify the `Class Name`.\n5. Press `Create`.\n\nThe GDNativeLibrary field in a NativeScript is empty by default.\n\n\n\u003cdetails\u003e\n\n![](images/faq/create_dlscript.png?raw=true)\n\n![](images/faq/set_script_dllibrary.png?raw=true)\n\n\u003c/details\u003e\n\nExpand *Details* for screenshots.\n\n## FAQ\n\n**What is the difference between `GDNative` and `NativeScript`?**\n\n`GDNative` is a new class that can call native functions in libraries.\nGDScript / VisualScript / C#, etc, are able to use this class.\n\nGodot treats `NativeScript` as a scripting language, enabling the\nuse of GDNative to implement scripts backed by native code.\n\n**Which languages are binding as a NativeScript?**\n\n[**C++**](https://github.com/godotengine/godot-cpp),\n[**D**](https://github.com/godot-d/godot-d),\n[**Nim**](https://github.com/pragmagic/godot-nim)\n\n**Can you debug NativeScripts?**\n\nYou must compile the library with debug\nsymbols, and then you can use your debugger as usual.\n\n**Can you use one GDNativeLibrary for all NativeScripts?**\n\nYou can! ✨\n\n**What is the reason behind the name \"GDNative\"?**\n\nGDNative was originally named \"cscript\" because it exposes a C API, but people\nmistook a relation to C#, which is sometimes abbreviated as \"cs\". Then named\n\"DLScript\", but that brought up some confusion, so we settled with GDNative. 📖\n\n## Updating Headers\n\nSee [**Versioning**](#versioning) for details on the Godot versions tracked by\neach branch of this repository.\n\nIf the relevant branch is not up-to-date for your needs, or if you want to sync\nthe headers with your own modified version of Godot, here is the update\nprocedure used to sync this repository with upstream releases:\n\n- Compile [Godot Engine](https://github.com/godotengine/godot) at the specific\n  version/commit which you are using.\n- Use the compiled executable to generate the `api.json` file with:\n  `godot --gdnative-generate-json-api api.json`\n- Copy the file `modules/gdnative/gdnative_api.json` to this repository.\n- Copy the files and folders from `modules/gdnative/include` to this repository,\n  overwriting existing content. (To be sure to be in sync, you can delete the\n  folders of this repository first, then copy the upstream folders in place.)\n  Make sure that you compiled the correct Godot version so that the generated\n  `gdnative_api_struct.gen.h` is up-to-date.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodotengine%2Fgodot-headers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgodotengine%2Fgodot-headers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodotengine%2Fgodot-headers/lists"}