Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/asmaloney/gdextensiontemplate

📜 A template project for building Godot 4 GDExtensions using CMake
https://github.com/asmaloney/gdextensiontemplate

extension gdextension godot godot-engine godot4 template

Last synced: about 13 hours ago
JSON representation

📜 A template project for building Godot 4 GDExtensions using CMake

Host: GitHub
URL: https://github.com/asmaloney/gdextensiontemplate
Owner: asmaloney
License: unlicense
Created: 2022-12-05T22:06:15.000Z (almost 2 years ago)
Default Branch: master
Last Pushed: 2023-12-28T21:03:50.000Z (11 months ago)
Last Synced: 2024-05-01T21:03:21.232Z (7 months ago)
Topics: extension, gdextension, godot, godot-engine, godot4, template
Language: C++
Homepage:
Size: 120 KB
Stars: 185
Watchers: 4
Forks: 13
Open Issues: 10
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md

Awesome Lists containing this project

README

[![GitHub](https://img.shields.io/github/license/asmaloney/GDExtensionTemplate)](LICENSE) ![Build](https://github.com/asmaloney/GDExtensionTemplate/actions/workflows/main.yml/badge.svg)

# GDExtensionTemplate

This project is meant as a starting point for creating new C++/CMake-based Godot 4 extensions. The goal is to lower the barrier to entry to building a GDExtension using [CMake](https://cmake.org).

It is currently set up to work with the **[Godot 4.2](https://github.com/godotengine/godot/releases/tag/4.2-stable)** release (see [tags](https://github.com/asmaloney/GDExtensionTemplate/tags) for previous versions).

Since the majority of C++ open source projects use CMake, I wanted to offer an alternative to the _scons_ system for building Godot extensions (if you use _scons_, check out Nathan Franke's [gdextension](https://github.com/nathanfranke/gdextension) template or Patrick's [GDExtensionSummator](https://github.com/paddy-exe/GDExtensionSummator) template).

> **Note:** This project is not meant to be a dependency. It is intended to be copied (not forked) and made into your own project. Git itself doesn't provide a nice way to do this (as far as I can tell), but GitHub provides a **Use this template** button (beside where you clone a repo). This will [create a copy for you](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) without all the history.

## Features

This template project sets up a lot of the build details so you can get started and focus on your code:

- includes **[godot-cpp](https://github.com/godotengine/godot-cpp) as a submodule** and links it statically to your shared library
- creates `.gdextension` files based on your project name
- copies over any support files from the `support_files` directory into your extension directory
- includes example of adding custom icons to your classes/nodes ([see below](#custom-node-icons))
- automatically generates a _**Version.h**_ header file which:
- includes a preprocessor macro for conditional compilation
```cpp
#if GDEXTENSIONTEMPLATE_VERSION < GDEXTENSIONTEMPLATE_VERSION_CHECK(2, 1, 0)
// do stuff
#endif
```
- includes git information in the version strings (e.g. `GDExtensionTemplate v1.0.1-gf6446f8`)
- includes an example which exposes the version string to GDScript so you can call it like this
```py
print( GDExtensionTemplate.version() )
```
- keeps itself up-to-date when the git branch/tag/HEAD changes
- uses **[ccache](https://ccache.dev/)** (if available) for faster rebuilds
- builds **universal library** (x86_64 and arm64) on macOS
- provides **cmake targets**:
- _install_: install all files with the correct structure to `CMAKE_INSTALL_PREFIX`
- _clang-format_: runs `clang-format` on all sources
- includes **GitHub workflows** (CI) for:
- building the extension on **Linux x86_64** (gcc), **macOS universal** (clang), and **Windows x86_64** (MSVC)
- generating debug & release packages on each commit
- using `ccache` to improve CI build times when available
- checking code formatting using `clang-format`

## Prerequisites

To use this locally on your machine, you will need the following:

- **[CMake](https://cmake.org/)** v3.22+
- C++ Compiler with at least **C++17** support (any recent compiler)
- (optional) **[ccache](https://ccache.dev/)** for faster rebuilds
- (optional) **[clang-format](https://clang.llvm.org/docs/ClangFormat.html)** for linting and automatic code formatting (CI uses clang-format version 15)

The GitHub actions (CI) are set up to include all of these tools. To see how to download them on your platform, take a look at the [workflow](.github/workflows/main.yml) file.

## How To Use

### Setup

To use this for your own project:

- _copy_ this repository and rename the directory to the name of your extension
> GitHub provides a **Use this template** button (beside where you clone a repo). This will [create a copy for you](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) without all the history.
- in _CMakeLists.txt_, change `GDExtensionTemplate` in the `project` macro to the name of your extension
```cmake
project(
LANGUAGES
CXX
VERSION
0.1.0
)
```
If you also have plain C files in your project, add `C` to the languages.
- replace the example code in `src` with your own (I would suggest keeping _RegisterExtension.cpp_ and using it to register your classes)
> **Note:** If you change the entry symbol (`GDExtensionInit`) in _RegisterExtension.cpp_, you will need to update your `templates/*.gdextension.in` files.
- replace `CHANGELOG.md` with your own (I would encourage adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and the use of [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) )
- replace this `README.md` with your own
- replace custom node icon ([see below](#custom-node-icons))

Optional:

- [contribute to the project](#how-to-contribute) (it's not just 💰!)
- change the platforms/architectures you want to support:
- edit the gdextension templates (`templates/*.gdextension.in`)
- change the GitHub workflows to build the right stuff
- change the `.clang-format` config file to fit your C++ style ([option documentation](https://clang.llvm.org/docs/ClangFormatStyleOptions.html))
- change the compiler warnings you want to enforce (see [CompilerWarnings.cmake](cmake/CompilerWarnings.cmake))
- change the LICENSE

### Custom Node Icons

I have included a custom icon for the `Example` node (icon is [CC0](https://creativecommons.org/public-domain/cc0/) from [SVGRepo](https://www.svgrepo.com/svg/207485/gardening-autumn)), so you will want to remove or modify it for your own classes/nodes.

The icon itself is in `support_files/icons` it is referenced in the `templates/*.gdextension.in` files.

To add an icon for your custom node:

- add the icon file to `support_files/icons` and name it after your node (e.g. `MyNode.svg`)
- in each of the `templates/*.gdextension.in` files add an entry for your node in the `[icons]` section:
```
MyNode = "icons/MyNode.svg"
```

Everything in the `support_files` directory is copied into your extension, so if you don't want to use icons, remove that directory and remove the `[icons]` section from the `templates/*.gdextension.in` files.

### Build & Install

Here's an example of how to build & install a release version (use the terminal to run the following commands in the parent directory of this repo):

#### Not MSVC

```sh
$ cmake -B GDExtensionTemplate-build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=GDExtensionTemplate-install GDExtensionTemplate
$ cmake --build GDExtensionTemplate-build --parallel
$ cmake --install GDExtensionTemplate-build
```

#### MSVC

```sh
$ cmake -B GDExtensionTemplate-build -G"Visual Studio 17 2022" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=GDExtensionTemplate-install GDExtensionTemplate
$ cmake --build GDExtensionTemplate-build --config Release
$ cmake --install GDExtensionTemplate-build
```

This tells CMake to use `Visual Studio 2022`. There is a list of Visual Studio generators [on the CMake site](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators) - pick the one you are using.

### Cmake Options

This template defines the following additional CMake options:

| Option | Description | Default |
| ------------------------------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `CCACHE_PROGRAM` | Path to `ccache` for faster rebuilds | This is automatically set **ON** if `ccache` is found. If you do not want to use it, set this to "". |
| `CLANG_FORMAT_PROGRAM` | Path to `clang-format` for code formatting. | This is automatically set **ON** if `clang-format` is on. If you do not want to use it, set this to "". |
| `${PROJECT_NAME_UPPERCASE}_WARN_EVERYTHING` (e.g. FOO_WARN_EVERYTHING) | Turns on all warnings. (Not available for MSVC.) | **OFF** (too noisy, but can be useful sometimes) |
| `${PROJECT_NAME_UPPERCASE}_WARNING_AS_ERROR` (e.g. FOO_WARNING_AS_ERROR) | Turns warnings into errors. | **ON** |

## Ongoing Updates

Once your project is up and running you might want to keep up with newer versions of Godot & godot-cpp.

The key thing is that the version of _godot-cpp_ must match the version of Godot you are using (see the [godot-cpp Versioning section](https://github.com/godotengine/godot-cpp#versioning)). So if you want to use _Godot 4.0 stable_, then you need to match that with the [correct tag in godot-cpp](https://github.com/godotengine/godot-cpp/tags).

Once you know the correct version of godot-cpp, change the submodule (_extern/godot-cpp_) in your extension to point at that version.

Updating the submodule and making any necessary changes to your code due to changes in the API are the only things you need to pin to a specific version of Godot.

## How To Contribute

These are some of the things you can do to contribute to the project:

### ✍ Write About The Project

If you find the project useful, spread the word! Articles, mastodon posts, tweets, blog posts, instagram photos - whatever you're into.

### ⭐️ Add a Star

If you found this project useful, please consider starring it! It helps me gauge how useful this project is.

### ☝ Raise Issues

If you run into something which doesn't work as expected, raising [an issue](https://github.com/asmaloney/GDExtensionTemplate/issues) with all the relevant information to reproduce it would be helpful.

### 🐞 Bug Fixes & 🧪 New Things

I am happy to review any [pull requests](https://github.com/asmaloney/GDExtensionTemplate/pulls). Please keep them as short as possible. Each pull request should be atomic and only address one issue. This helps with the review process.

Note that I will not accept everything, but I welcome discussion. If you are proposing a big change, please raise it as [an issue](https://github.com/asmaloney/GDExtensionTemplate/issues) first for discussion.

### 💰 Financial

Given that I'm an independent developer without funding, financial support is always appreciated. If you would like to support the project financially, you can use [GitHub sponsors](https://github.com/sponsors/asmaloney) or [Ko-fi](https://ko-fi.com/asmaloney) for one-off or recurring support. Thank you!