# godot-cpp

**Repository Path**: mirrors_godotengine/godot-cpp

## Basic Information

- **Project Name**: godot-cpp
- **Description**: C++ bindings for the Godot script API
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2021-10-09
- **Last Updated**: 2026-01-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# godot-cpp

> [!NOTE]
>
> For GDNative (Godot 3.x), switch to the [`3.x`](https://github.com/godotengine/godot-cpp/tree/3.x)
> or the [`3.6`](https://github.com/godotengine/godot-cpp/tree/3.6) branch.

This repository contains the  *C++ bindings* for the [**Godot Engine**](https://github.com/godotengine/godot)'s GDExtensions API.

- [**Versioning**](#versioning)
- [**Compatibility**](#compatibility)
- [**Contributing**](#contributing)
- [**Getting started**](#getting-started)
- [**Examples and templates**](#examples-and-templates)

## Versioning

> [!WARNING]
>
> The master branch of godot-cpp (version 10.x) is currently in Beta. You may prefer to choose a previous version to build on top of instead:
> - [`4.5`](https://github.com/godotengine/godot-cpp/tree/4.5)
> - [`godot-4.5-stable`](https://github.com/godotengine/godot-cpp/tree/godot-4.5-stable)
> - [`3.x`](https://github.com/godotengine/godot-cpp/tree/3.x)

Starting with version 10.x, godot-cpp is versioned independently from Godot. The godot-cpp version you
choose has no bearing on which Godot versions it is compatible with.

Until we have a stable release branch, you can use the `master` branch, or choose any of the previous
version branches and tags for your project.

## Compatibility

GDExtensions targeting an earlier version of Godot should work in later minor versions,
but not vice-versa. For example, a GDExtension targeting Godot 4.3 should work just fine
in Godot 4.4, but one targeting Godot 4.4 won't work in Godot 4.3.

You can specify which version you are targeting with the `api_version` option:

```
scons api_version=4.3
```

... or by providing a custom `extension_api.json` generated by the Godot version you are
targeting:

```
godot --dump-extension-api
scons custom_api_file=extension_api.json
```

If you don't provide `api_version` or `custom_api_file`, then, by default, godot-cpp will
target the latest stable Godot version that it's aware of.

## Contributing

We greatly appreciate help in maintaining and extending this project. If you
wish to help out, please visit the [godot-cpp section of the Contributing docs](https://contributing.godotengine.org/en/latest/other/godot-cpp.html).

## Getting started

You need the same C++ pre-requisites installed that are required for the `godot` repository. Follow the [official build instructions for your target platform](https://docs.godotengine.org/en/latest/engine_details/development/compiling/index.html).

Building your extension will create a shared library. To use this in your Godot project you'll need a `.gdextension`
file, for example:

```ini
[configuration]

entry_symbol = "example_library_init"
compatibility_minimum = "4.1"

[libraries]

macos.debug = "res://bin/libgdexample.macos.debug.framework"
macos.release = "res://bin/libgdexample.macos.release.framework"
windows.debug.x86_64 = "res://bin/libgdexample.windows.debug.x86_64.dll"
windows.release.x86_64 = "res://bin/libgdexample.windows.release.x86_64.dll"
linux.debug.x86_64 = "res://bin/libgdexample.linux.debug.x86_64.so"
linux.release.x86_64 = "res://bin/libgdexample.linux.release.x86_64.so"
# Repeat for other architectures to support arm64, rv64, etc.
```

See the [example.gdextension](https://github.com/godotengine/godot-cpp-template/blob/main/demo/bin/example.gdextension)
used in the template project for a complete example.

The `entry_symbol` is the name of the function that initializes your library, for example:

```cpp
extern "C" {

// Initialization.

GDExtensionBool GDE_EXPORT example_library_init(GDExtensionInterfaceGetProcAddress p_get_proc_address, GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
	godot::GDExtensionBinding::InitObject init_obj(p_get_proc_address, p_library, r_initialization);

	init_obj.register_initializer(initialize_example_module);
	init_obj.register_terminator(uninitialize_example_module);
	init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

	return init_obj.init();
}
}
```

The `initialize_example_module()` should register the classes in ClassDB, similar to a Godot module:

```cpp
using namespace godot;
void initialize_example_module(ModuleInitializationLevel p_level) {
	if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) {
		return;
	}
	GDREGISTER_CLASS(Example);
}
```

Any node and resource you register will be available in the corresponding `Create...` dialog.
Any class will be available to scripting as well.

## Examples and templates

See the [godot-cpp-template](https://github.com/godotengine/godot-cpp-template) project for a
generic reusable template.

Or checkout the code for the [Summator example](https://github.com/paddy-exe/GDExtensionSummator)
as shown in the [official documentation](https://docs.godotengine.org/en/latest/tutorials/scripting/cpp/gdextension_cpp_example.html).