godot-cpp-marbles

KO | EN

gitlite — search

#database #codex #electron #postgresql #cpp #php #react #gpt #llm #macos

godot-cpp-marbles

(★ 9)

No description available.

File Explorer

ZIP Download

- c_cpp_properties.json
- settings.json
- - cmake.check_cache
  - cmake.verify_globs
  - CMakeConfigureLog.yaml
  - InstallScripts.json
  - rules.ninja
  - TargetDirectories.txt
  - VerifyGlobs.cmake
- build.ninja
- cmake_install.cmake
- CMakeCache.txt
- compile_commands.json
- - marble_physics.gdextension
  - marble_physics.gdextension.uid
  - marble_physics.windows.template_debug.x86_64.dll
  - marble_physics.windows.template_debug.x86_64.exp
  - marble_physics.windows.template_debug.x86_64.lib
  - ~marble_physics.windows.template_debug.x86_64.dll
- .editorconfig
- .gitattributes
- .gitignore
- .gitmodules
- game_board.tscn
- game_board.tscn467619386.tmp
- icon.svg
- icon.svg.import
- new_marble_stats.tres
- physics_solver.gd
- physics_solver.gd.uid
- project.godot
- shooter.gd
- shooter.gd.uid
- Marble.cpp
- Marble.h
- Marble.windows.template_debug.x86_64.obj
- MarbleMod.hpp
- MarbleOrchestrator.hpp
- MarblePhysicsState.cpp
- MarblePhysicsState.h
- MarblePhysicsState.windows.template_debug.x86_64.obj
- MarbleStateBundle.hpp
- MarbleStats.cpp
- MarbleStats.h
- MarbleStats.windows.template_debug.x86_64.obj
- PhysicsEvent.hpp
- PhysicsInputEvent.hpp
- PhysicsProjection.cpp
- PhysicsProjection.h
- PhysicsProjection.windows.template_debug.x86_64.obj
- register_types.cpp
- register_types.h
- register_types.windows.template_debug.x86_64.obj
- TickState.hpp
.sconsign.dblite
godot-cpp
LICENSE.md
README.md
SConstruct

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

This repo is a small project that serves as an example and reference for using GDExtension with Godot CPP. I found that there aren't good references for GDExtension projects that aren't completely trivial, and a lot of the APIs you need to use in order to get these projects to work are difficult to find and understand.

With this project, you can see a working, non-trivial example of just about every major pattern you would need in order to implement something in GDExtension:

- Creating signals for nodes
- Connecting to signals
- Exposing public methods to GDScript
- Exposing virtual methods to GDScript
- Calling GDScript virtual methods in c++
- Exposing c++ enums to GDScript
- Exposing static methods to GDScript
- How to handle RefCounted objects
- Exposing c++ properties in the editor
- Custom c++ Resources
- Taking input from GDScript
- Multithreading in c++
- Semaphores in c++
- Using your GDExtension objects in GDScript

Additionally, the code is overly commented in order to explain in detail the purpose of the code and useful tricks to work with GDExtension more efficiently. To supplement the comments, more general commentary is provided at the bottom of this README as a more general overview.

# Getting Started

Start by cloning this repo:

```bash
git clone https://github.com/jnlongnecker/godot-cpp-marbles
cd godot-cpp-marbles
```

Add the project in the Godot project launcher (found in godot-cpp-marbles/project/project.godot), then run the project with the play button in the editor.

# Setup for Editing

Run the following commands to build the GDExtension and make edits to the code:

```bash
rmdir godot-cpp
git clone -b 4.4 https://github.com/godotengine/godot-cpp
cd godot-cpp
scons
cd ../
scons
```

> Not sure why godot-cpp isn't properly submoduled, so the directory will need to be removed and the branch cloned

# Tutorial

GDExtension allows you to write non GDScript code for Godot. This project shows you how to utilize godot-cpp to write c++ code as a GDExtension project. You can find what Godot has to say about godot-cpp [here](https://docs.godotengine.org/en/stable/tutorials/scripting/cpp/gdextension_cpp_example.html), so if you run into anything that I don't cover here, be sure to check out that link.

## Setup, Sconstruct & register_types

The structure of this project is also the structure recommended for making GDExtension projects with godot-cpp: A root directory with your `Sconstruct` file, `godot-cpp` as a submodule, `src` directory for your c++ code, and a `project` directory for your actual Godot project. While this project doesn't do so, you're more than welcome to organize your c++ files into subdirectories, but located in the `src` directory should be the `register_types.h` and `register_types.cpp` files. These files are here to tell GDExtension what to expose to GDScript; basically all you need to do here is use the `GDREGISTER_CLASS` macro to register all the classes you want to expose to Godot.

You can name the two functions here whatever you want, just make sure the one that runs the `GDREGISTER_CLASS` macro is specified in the `GDE_EXPORT` marked function with `init_obj.register_initializer(your_function_name);`. See [src/register_types.cpp](src/register_types.cpp) as reference.

Similarly, you can name this `GDE_EXPORT` function whatever you want, but you'll need to update the `.gdextension` file found in `project/bin`. In this file at the top, there is the `entry_symbol` property. This needs to be a string of the name of that `GDE_EXPORT` function. This file gets generated by `Sconstruct` when you run the `scons` command. In the `Sconstruct` file, there's a line that writes the `lib_filename` (line 23). This is where the name of that `.gdextension` file is specified.

## About C++

If you know about c++ already, then you can skip this section (next section [here](#gdextension-tips--tricks)).

C++ differs from GDScript in a number of ways that make it seem more intimidating. I won't be explaining all there is to know about c++, as I neither am a c++ expert nor do you need to know a ton about c++ in order to write cool GDExtensions. I will be explaining enough for you to be able to understand the code found in this repository and write similar code yourself.

### Variables

C++ is a statically typed language, which means we have to specify the type of every variable we use when we declare it. In GDScript, this is optional to do, but we *have* to do it in C++. For example, let's compare declaring an integer in GDScript to c++:

```cpp
int my_int = 3;
```

```gdscript
var my_int = 3
# OR
var my_int: Integer = 3
```

Notice that we don't use the keyword `var` in c++, and the variable declaration starts with the type.

### Files

GDScript uses files with the `.gd` extension, while c++ uses the `.h`, `.cpp`, and `.hpp` extensions. Let's talk about each individual one:

*.h*

The `.h` file is the "header" file. Typically in a header file all you have is the declaration of any class(es), functions, or variables you want, but not the implementation. Additionally, you'll notice that these files begin with the line `#pragma once`. This is a preprocessor directive, which is just a flag for when files are getting linked and compiled. This tells the compiler that it should only include this file a single time during compilation. This speeds up compilation times and removes issues of naming collisions that you used to have to write some boilerplate to avoid.

*.cpp*

The `.cpp` file is the implementation file, where you write out the implementations of all your functions. This file will always start by `#include`-ing the `.h` file, since that's the place where everything we're going to implement is declared.

Something to note is that even though this is the convention, you *can* have implementation in the `.h` file if you want to (or need to). They're separated out like this for a few reasons, but the one that's relevant nowadays is that it's very clean and you can get an idea of what a class does by just reading the `.h` file without all the implementation cluttering things up. If you need the details, you can just go to the `.cpp`.

*.hpp*

The `.hpp` file is basically just like the `.h` file, but it's more specific to c++. `.h` files come from c, while `.hpp` is unique to c++ and tells the compiler that you might be using some special c++ syntax.

### Classes

In GDScript, each script you create is technically its own class, even though you don't actually have to give it a name. In c++, classes have to be named, and you can include the definition of multiple classes in a single file. A class is declared like so:

```cpp
class MyClass : public BaseClass {};
```

After the `:` is the base class. In GDScript, this would be like the `extends Node` line that appears at the top of a script. Technically, you don't have to include a base class here, but unless you know what you're doing you probably should extend a godot-cpp class when you're making a class of your own. We use the `public` keyword in front of the base class so that c++ doesn't hide all the methods that are available in the base class. If we omitted `public` or used `private` instead, all the members of the base class would be hidden.

The above class is empty and not useful, so we can look at a more concrete example:

```cpp
class MyClass : public Node 
{
private:
    int private_value;

public:
    void method_no_return();
    bool method_bool_return();
    void method_with_parameter(float delta);

protected:
    static void _bind_methods();
};
```

Our class members are separated by these `private`, `public` and `protected` keywords. Members that are `private` cannot be accessed outside of the class. In GDScript, this is not possible! The convention in GDScript is to mark these members with `_` to convey that they shouldn't be used, but in c++ we can enforce this by simply making them `private`. Members that are `public` are accessible outside the class, and members that are `static` are accessible without an instance of the class.

Members that are `protected` are accessible only within the class, or any of its children (so other classes that extend this class). The most common `protected` method you will see is the `_bind_methods()` method, which tells Godot how GDScript should access the methods of our class. This method only does something if you inherit from one of the Godot engine classes, like `Node`, `RefCounted`, or `Object`.

### Namespaces

A namespace is like a container for the names of data (structs, classes, variables). It's helpful if you want to make sure that the names of your classes don't conflict with the names of other classes. For example, Godot has a class called `Color`. If you *also* wanted a class called `Color`, you couldn't because that name is already taken. However, if you put that class in a namespace, now *other* namespaces can have the `Color` class and we can distinguish between them.

Let's put our class in a namespace:

```cpp
namespace MyNamespace {

class MyClass : public Node 
    {
    private:
        int private_value;

public:
        void method_no_return();
        bool method_bool_return();
        void method_with_parameter(float delta);

protected:
        static void _bind_methods();
    };
}
```

Now, the proper way to refer to `MyClass` from outside the `MyNamespace` namespace is the following: `MyNamespace::MyClass`; we specify the name of the namespace, then after `::` we can specify the member of the namespace. We use this `::` syntax to specify the "member" of something; we use the same syntax if we refer to the method of a particular class. For example, if we wanted to call `_bind_methods()` we would write `MyNamespace::MyClass::_bind_methods()`.

This only works because `_bind_methods()` is static and doesn't need an instance. We use `.` to access a member of an instance, like so:

```cpp
MyClass my_instance = MyClass();
my_instance.method_no_return();
```

Back to our example, I was unfortunately cheating a bit. You see, all of the Godot classes are in the `godot` namespace, so we need to add to our example a bit to make it correct:

```cpp
namespace MyNamespace {

class MyClass : public godot::Node 
    {
    private:
        int private_value;

public:
        void method_no_return();
        bool method_bool_return();
        void method_with_parameter(float delta);

protected:
        static void _bind_methods();
    };
}
```

In the c++ world, this is generally the proper form: always specify the namespace that something comes from. This is to help distinguish where all the various bits of code live and help other programmers know that this `Node` class you're using comes from the `godot` namespace. However, if you want to avoid having to write the `godot` namespace all the time, you can add this line:

```cpp
using namespace godot;
```

This will tell the compiler that it should look for every type in either the current namespace or in the `godot` namespace to find the definition for each type. However, if both namespaces defined a member with the same name, we'd get an error telling us that the type was ambiguous. In this instance, we'd have to specify the namespace for the type we actually wanted to use.

### Includes

Often times, the code you want to reference lives in different files. You need to specify what file contains the code that you want to use with the line `#include`. This one's pretty simple: after the `#include` should be a path to the file that has the code you want. If it's a file you wrote, write it in `""` quotation marks. If it's a file from the standard library or from Godot, write it in `<>` angular brackets. Let's update our file:

```cpp
#include <godot_cpp/classes/node.hpp>

namespace MyNamespace {

class MyClass : public godot::Node 
    {
    private:
        int private_value;

public:
        void method_no_return();
        bool method_bool_return();
        void method_with_parameter(float delta);

protected:
        static void _bind_methods();
    };
}
```

### Constructors & Destructors

A constructor is a method that gets ran when you create a new instance of an object, and a destructor is a method that gets ran when you destroy or de-allocate the memory for that object. They look like this:

```cpp
class MyClass
{
public:
    MyClass(); // No parameter constructor
    ~MyClass(); // Destructor
};
```

The constructor can have any number of parameters in case you want to create an object using specific values to do so. The destructor should be used to clean up anything that the class has that wouldn't get cleaned up by normally destroying the object (which would call the destructor for any object contained within it). In Godot, you probably won't have anything that needs a destructor, but the common use case is closing file readers so no memory leaks.

The constructor can also specify values to use for the class members as a shorthand like this:

```cpp
class MyClass
{
    int my_value;
public:
    MyClass() : my_value(10);
};
```

When the constructor is called, it will set `my_value` to 10 before any code in the constructor is run. If you have multiple class members you want to set, you separate them with a comma `,`.

### Macros

A macro is a bit of text-replacement code. You write the name of the macro, and it replaces all instances where the name is written with whatever you have defined in the macro. These often times look a lot like functions, but macros from Godot will always be in all-caps (as is the convention with macros). I won't touch on writing macros here, but just know if you see some code that looks like this: `GDCLASS(_, _);`, just know that `GDCLASS` is a macro and it's acting as a shorthand for some special Godot boilerplate.

In this specific instance, `GDCLASS` tells Godot that a class you write is extending a Godot engine class. If we apply our earlier example, it would look like this:

```cpp
#include <godot_cpp/classes/node.hpp>

namespace MyNamespace {

class MyClass : public godot::Node 
    {
        GDCLASS(MyClass, godot::Node);
    private:
        int private_value;

public:
        void method_no_return();
        bool method_bool_return();
        void method_with_parameter(float delta);

protected:
        static void _bind_methods();
    };
}
```

### Pointers

In GDScript, certain values are copied when they're passed to a method or assigned to a variable. These are the primitives: boolean, integer, float, etc. Objects (like Nodes, Resources, etc.) are instead passed using a reference. This means that two variables refer to the same underlying data instead of their own individual copy.

In c++, it's not quite so simple. Instead, you need to be the one to specify whether something should copy itself or only be a reference. References to data are called pointers. A pointer is *not* the data, it is a *reference* to the data.

The syntax of a pointer looks like this:

```cpp
int five = 5;
int *five_pointer = &five;
int *also_five_pointer = five_pointer;
five = 6;

godot::print_line(*five_pointer); // prints 6
godot::print_line(*also_five_pointer); // prints 6
godot::print_line(five); // prints 6
```

The first line is a normal variable like we saw before. The second line is a pointer to the data stored in the variable `five`. We specify that we want the reference to the value instead of the value with the `&` symbol, and we specify a variable is a pointer by using the `*` symbol in front of the variable name. Since `five_pointer` is a pointer, we can set `also_five_pointer` equal to `five_pointer` since they're the same data type (that type being a pointer to an `int`). This means the reference to `five` is copied from `five_pointer` to `also_five_pointer`, so both pointers are referring to the same data. When that data changes, all pointers know it. When we're printing out, we use the `*` symbol in front of the variable name to de-reference the pointer, or in other words to say to c++ that we want the value that the pointer is referencing. This is why it prints out 6 instead of the memory address.

When we have a pointer to an object and we want to reference one of its members, the syntax changes a bit. Instead of `.`, we now use `->`. This is a shorthand to tell c++ that we want the member of the class that is referenced by the pointer, because otherwise just using `.` would tell c++ to try to access a member of a pointer, which doesn't exist!

---

This crash course in c++ should technically be sufficient for you to understand the code found in this repository. If this is your very first time looking at c++, or if you're new to coding in general, I'd recommend taking some extra time to let all this sink in. If you want to look at some examples, make it easy on yourself and look at some of the simpler ones in this repository.

If most of this went over your head or you're feeling overwhelmed, try making some very simple c++ programs outside of GDExtension. GDExtension is an advanced topic, so don't feel bad if things were confusing.

## GDExtension Tips & Tricks

This section assumes you are knowledgeable in c++ and want to learn about some of the do's, don'ts, hazards and pitfalls of writing c++ GDExtensions.

### RefCounted

`RefCounted` is a smart pointer that counts the number of references it gives out. When the reference count hits zero, it is automatically de-allocated. If you use a class that extends `RefCounted`, you *must* use it in a very specific way.

First, any class that extends `RefCounted` *must* have its no parameter constructor public. When you create a new instance of a `RefCounted` object, you must do so via the `.instantiate()` method, which calls the no parameter constructor. From there, you can set the members as you see fit.

Since this is the only and proper way of creating a `RefCounted` instance, if you want to have a `RefCounted` class that *does* accept some parameters, it's recommended to create a static builder method with the parameters you want that constructs the instance, populates the members, and returns the instance.

### Objects from GDScript

If you have a method that is exposed to GDScript, you need to follow the GDScript convention that is being used under the hood. Specifically, this means that primitives can be passed by value just fine, but non-primitives should be passed by reference. All `RefCounted` objects must be wrapped with `Ref<>`, and all other objects should be behind a pointer.

### Signals

Signals are handled entirely through `StringName`s. Since you can't declare a signal like you would in GDScript as a proper construct, it's recommended to have the names of all your signals as constants in your class. That way, when you are connecting a signal to a class you don't risk misspelling the name of either the signal or the handler in multiple different places, and if the names should change you can change it in one place instead of many.

One gotcha with this method is that you can't use a `StringName` type as a constant because the value must be constructed before your GDExtension actually has access to the Godot engine, which causes an error. Instead, you should construct the signal name as a c-string (an array of `char`; i.e. `char *`). This is because you can pass a c-string where a `StringName` is expected and a `StringName` can be trivially constructed from the c-string.

### TypedArray vs std::vector

The `TypedArray` class is honestly fairly awful to work with due to the fact that you still get a `Variant` type when accessing its members. If you're taking input commonly from GDScript, then you'll have to work with it. However, if you need to hold onto a list of data that doesn't move back and forth between c++ and GDScript often, do yourself a favor and just put it in a `std::vector`.

The exception is if you're working with primitives that can be easily cast from a `Variant`, like int's and float's. Then it's not such a pain to work with as it's trivial to just get the type you want.

godot-cpp-marbles

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

godot-cpp-marbles

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README