78 lines
3.3 KiB
Markdown
78 lines
3.3 KiB
Markdown
# Redot GDExtension Template
|
|
|
|
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][1].
|
|
|
|
## 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:
|
|
```sh
|
|
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:
|
|
```sh
|
|
git submodule init
|
|
git submodule update
|
|
```
|
|
|
|
Or by running the combined command:
|
|
```sh
|
|
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](https://docs.redotengine.org/contributing/development/compiling/). 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][2]
|
|
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:
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|
|
|
|
```sh
|
|
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.
|
|
|
|
[1]: https://docs.redotengine.org/tutorials/scripting/gdextension/
|
|
[2]: https://docs.redotengine.org/tutorials/scripting/gdextension/ |