Skip to main content

C++ Code Compilation

The Sandbox can run C++ code inside it in isolation, but first you need to build the C++ code.

What you'll need​

  • Docker installed and running.

C++ Source Files​

In Godot create a new folder called to put your C++ program inside. Inside it create a new CPPScript, by clicking on the folder and selecting Create New -> Script -> CPPScript.

new script

The default C++ template should look something like this:

#include "api.hpp"

extern "C" Variant public_function(String arg) {
    print("Arguments: ", arg);
    return "Hello from the other side";
}

Now, each time you save this file a C++ compiler will be invoked to produce an .elf executable in the same directory. This file is created by compiling all source files in that directory to a single binary using docker. The image used is libriscv/cpp_compiler.

The name of the program is based on the folder name, hence if the folder is called src the program will be called src.elf. This allows you to have multiple source files, which will all be automatically compiled together into one final program, while also supporting multiple programs separated by folders.

note

If it is not working, you need to set the docker path manually by going to Project -> Project Settings -> editor/script/docker and modifying to the path where you have installed docker. If left blank it will use what it finds in the PATH variable.

The C++ API​

The C++ API tries to mimick godot-cpp when it makes sense to do so, and it otherwise provides the entire GDScript API. You can find the C++ API implementation here, and the C++ API reference here. For everything else, you can refer to the official Godot documentation.

ELF Script​

Once you compiled the source code to a binary, you can investigate it. To do this, click on the .elf file and you should see all the functions that are exported and available to call from Godot. These functions are exported normally and can even be used as targets for signals.

elf file

Demonstration

We maintain a Godot project that demonstrates using C++ for scripting. So, have a look at that to understand how you can use sandboxed C++ in your own Godot projects.