This repository provides a template for create GDExtensions. This template provides a basic layout including a demo project which can be used to test your extension. It also provides a small file (build.py) which can generate a template.gdextension file for you. This file should automatically enable your extension within the editor.

This project uses Redot 26.1 as the basis for creating extensions. In the future, there will probably be branches dedicated to future versions of Redot. This repository is based on the official GDExtension tutorial.

Using this template

To set up a repository using this template, simply click the "Use this template" button in the top right of this repository. You will then be presented with a new repository wizard that will guide you through the remaining setup steps.

Cloning the repository

This template uses a [git submodule][3] to make it easier to use the correct version of the Redog GDExtension API. As a result, you must use a slightly different process for cloning repositories generated with this template. If you haven't cloned the repo yet, you can use the following command to get the submodules automatically:

git clone --recurse-submodules <YOUR_REPO_URL>

If you have already cloned the repo, you can initialize the submodules by running the following two commands:

git submodule init
git submodule update

Or by running the combined command:

git submodule update --init

Building the extension.

To build projects created with this template, you will need to run scons. If you have not already setup your system for developing Redot extensions or extending the core editor, you can find instructions for doing so here. These steps are designed to help you build the entire Redot project, but you will need an understanding of how to do that in order to build extensions.

I also strongly recommend that you read the guide on C++ GDExtensions if you have not already done so to get the fullest picture of how GDExtensions are intended to work.

Once you have setup your repository and cloned it to your local machine, you can build the extension by running:

scons

If you would like to build your extension with the help of an IDE, you may want to have scons generate a build_commands.json file by building your project with the compiledb=yes option as below:

scons compiledb=yes

Customizing your build artifact name

By default, this project is configured to output a shared library titled libgdextension_template, however you can easily change this by modifying the PROJECT_NAME property in the build.py file. scons will automatically incorporate this variable into your compilation artifact.

Generating a template.gdextension file

This repository comes with a simple Python script that will generate a *.gdextension file and place it in the demo directory. Redot requires this file to load your GDExtension, so using this script will get you started quickly.

python build.py

The script will also read the value of the PROJECT_NAME property so that the *.gdextension file will reflect the name of your extension.