Skip to content

Home

Jump to bottom
PixelRain edited this page Mar 6, 2024 · 39 revisions

Godot Roguelite - C++ gdextension template:

This gdextension project supports linux and windows. The linux development environment is set up to use VSCode, and the Windows development environment is set up to use Visual Studio 2022 Community Edition.

In-depth setup topics:

Windows 10 - How to install all of the required dependencies

Visual Studio Community - Building the gdextension

Visual Studio Community - Running and debugging

CMake - System layout/setup

CMake - Linking 3rd party libraries

Folder hierarchy and root folder key files

Templating - Referencing godot‐roguelite as a template for your own project

Updating an installed setup to newer godot versions (godot-roguelite & custom template)

Common issues/troubleshooting

Orlac's quick overview:

Install Dependencies

To ensure everything works as it should for the project setup/configuration/build, you'll want to install the following deps. If you're working on windows using something like chocolatey to install all dependencies is probably easiest. On linux these should all be available in the default package manager.

  1. gcc
  2. gdb
  3. lldb
  4. llvm
  5. clang
    • Note: if you want to use clang-format to autoformat your C++ code automatically, the existing .clang-format config file requires clang-format >= v16.0. If the latest version you're able to install is <= v16.0, you will need to comment out this line for the .clang-format config to be compatible with clang-format versions older than 16.0
  6. cmake
  7. ninja
    • might be called ninjabuild or ninja-build on certain distros/platforms
  8. python
  9. scons
    • If scons isn't available as a standalone package, install it with pip once you have the python package installed: pip install scons

Linux Setup

  1. Install VSCode
    • VSCodium should also work, but I haven't personally tested it.
  2. Clone this repo and open it as a folder in VSCode.
  3. This config file in the .vscode/ directory should prompt VSCode to ask you to install recommended workspace packages when you open the folder. Not all are required, but you will need the C++ extension, CMake tools extension. The clang-format and output-colorizer extensions are highly recommended (for clang-format autoformatting support and colored cmake build output respectively to spot errors easier).
  4. Once the required extensions are installed, hit Ctrl + Shift + P and type in "CMake" to view all cmake options. For your first want to select the "CMake: configure" option or "CMake: delete cache and configure" if it's available to invoke the CMakeLists.txt build script. This should invoke the CMake configuration of the project. See CMake Configuration below for an overview of the configuration process and environment setup.

Windows Setup

  1. Install Visual Studio 2022 Community Edition with the following installer options. If you already have VS2022 installed but are missing some of these IDE features/options, you can modify the installation using the program "Visual Studio Installer" to add any features/extensions that are missing from this list:
    1. MSVC C++ toolset
    2. CMake tools add-on
    3. Clang tools add-on
  2. Clone this repo and open it from VS2022 AS A FOLDER. This project is set up to use cmake with VS2022 rather than vcxproj/sln based projects.
  3. Go to "Project"->"Configure " or "Project"->"Delete cache and reconfigure" if that option exists to invoke the CMake configuration process.

CMake Configuration

Once configuration begins, the cmake script will:

  1. Initialize and update all submodules: extern/godot-engine, extern/godot-cpp, and extern/vcpkg
  2. Configure the vcpkg package manager (only if it isn't already configured)
  3. Build the godot engine in a configuration with good debugger support (debug symbols, no LTO, etc)
    • Note: this build only happens once. The script will only invoke the build if it can't find the debug build of the engine in the godot-engine submodule.
  4. Build all 3rd party libraries/deps using vcpkg (it will download sources, cache intermediates, and build static libraries)
  5. Configure the engine's sources as a library for better code browsing and intellisense in VSCode.
    • Note: the godot engine library does not get built, it's added using CMake's EXCLUDE_FROM_ALL option so it only gathers header/source files in the lib and exports those so the IDE knows about them: add_library(godot_engine EXCLUDE_FROM_ALL ${godot_engine_sources})
  6. Builds the gdextension project along with the godot-cpp sources
  7. Statically links all dependencies into the gdextension binary.
  8. Outputs the gdextension library in the project/bin folder (where godot expects to find it by default).

Debugging

Both VSCode and VS2022 project configurations have 2 included debugger launch commands. One will launch the project from the editor, the other will launch the project standalone.

You can easily alter the command being invoked from either of those files.

The project is set up so the debugger will launch the gdextension code along with the debug build of the engine so you can debug your code as well as any all code within the godot engine/editor.

Adding 3rd party libraries/deps:

  • all deps are managed by the vcpkg package manager using this file: vcpkg.json
  • vcpkg supports thousands of C++ libraries, you can browse them here

Adding a new dependency

  1. Add the package name to the list in the vcpkg.json file.

  2. When you save that file, both VSCode and VS2022 should automatically invoke a configuration of the project.

    • Towards the end of the configuration step, you should see vcpkg output some basic instructions on how to add the dependency to the CMakeLists.txt file. image

    When you see the output for the library you just added, just copy those same lines into the CMakeLists.txt file for package discovery around here and library linkage here

CMake presets

  • You can add new compiler options or build configurations so your editor/IDE will present you with additional options by modifying the CMakePresets.json file.
    • You can change the generator (currently uses Ninja) to something like Unix Makefiles, Ninja MultiConfiguration, or Visual Studio project file.
    • You can add customized code build options (verbose mode, clean & build, etc) by filling in the "buildConfigurations" section. All details about CMakePreset.json can be found in the CMake docs here

First Time Startup - READ ME! DON'T SKIP

  • One slightly annoying requirement that I haven't figured out how to get around yet is that the project must be opened in the editor once before it's able to be launched as a standalone project without running the full editor. This seems to be because the editor will process and package the resource files into cached/compact template files that are probably more efficient to load from disk.
    • This just means the first time you launch the debugger on any platform, you have to invoke the gdextension (editor) launch configuration at least once. After it starts up, you can just close the editor and switch over to the gdextension (console) launch configuration and the project should load fine.

Additional Notes

If you're using the vscode project on linux and prefer using clang++ over gcc, it's probably worth changing this line in the vscode cpp properties config file to "intelliSenseMode": "linux-clang-x64" so intellisense is consistent with the compiler used and should end up working better.

Clone this wiki locally