Repository files navigation

C# game template for Godot 4 with debug launch configurations, testing (locally and on CI/CD), code coverage, dependency update checks, and spell check working out-of-the-box!

This template allows you to easily create a C# game for Godot 4. Microsoft'sdotnet tool allows you to easily create, install, and use templates.

# Install this templatedotnet new install Chickensoft.GodotGame# Generate a new project based on this templatedotnet new chickengame --name"MyGameName" --param:author"My Name"cd MyGameNamedotnet build

Is this template broken? Encountering obscure C# build problems? We'll be happy to help you in theChickensoft Discord server.

For the provided debug configurations and test coverage to work correctly, you must setup your development environment correctly. TheChickensoft Setup Docs describe how to setup your Godot and C# development environment, using Chickensoft's best practice recommendations.

This template includes some Visual Studio Code settings in.vscode/settings.json. The settings facilitate terminal environments on Windows (Git Bash, PowerShell, Command Prompt) and macOS (zsh), as well as fixing some syntax colorization issues that Omnisharp suffers from. You'll also find settings that enable editor config support in Omnisharp and the .NET Roslyn analyzers for a more enjoyable coding experience.

Please double-check that the provided VSCode settings don't conflict with your existing settings.

The includedglobal.json specifies the version of the .NET SDK andGodot.NET.Sdk that the game should use. Using aglobal.json file allowsRenovatebot to provide your repository with automatic dependency update pull requests whenever a new version ofGodotSharp is released.

An example test is included intest/src/GameTest.cs that demonstrates how to write a test for your package usingGoDotTest andgodot-test-driver.

GoDotTest is an easy-to-use testing framework for Godot and C# that allows you to run tests from the command line, collect code coverage, and debug tests in VSCode.

Tests run directly inside the game. The.csproj file is already pre-configured to prevent test scripts and test-only package dependencies from being included in release builds of your game!

On CI/CD, software graphics drivers from [mesa] emulate a virtual graphics device for Godot to render to, allowing you to run visual tests in a headless environment.

TheMain.tscn andMain.cs scene and script file are the entry point of your game. In general, you probably won't need to modify these unless you're doing something highly custom.

If the game is running a release build, theMain.cs file will just immediately change the scene tosrc/Game.tscn. If the game is running in debug modeand GoDotTest has received the correct command line arguments to begin testing, the game will switch to the testing scene and hand off control to GoDotTest to run the game's tests.

In general, prefer editingsrc/Game.tscn oversrc/Main.tscn.

The provided debug configurations in.vscode/launch.json allow you to easily debug tests (or just the currently open test, provided its filename matches its class name).

Code coverage requires a fewdotnet global tools to be installed first. You should install these tools from the root of the project directory.

Thenuget.config file in the root of the project allows the correct version ofcoverlet to be installed from the coverlet nightly distributions. Overriding the coverlet version will be requireduntil coverlet releases a stable version with the fixes that allow it to work with Godot 4.

dotnet tool install --global coverlet.consoledotnet tool update --global coverlet.consoledotnet tool install --global dotnet-reportgenerator-globaltooldotnet tool update --global dotnet-reportgenerator-globaltool

Runningdotnet tool update for the global tool is often necessary on Apple Silicon computers to ensure the tools are installed correctly.

You can collect code coverage and generate coverage badges by running the bash scriptcoverage.sh (on Windows, you can use the Git Bash shell that comes with git).

# Must give coverage script permission to run the first time it is used.chmod +x ./coverage.sh# Run code coverage:./coverage.sh

You can also run test coverage through VSCode by opening the command palette and selectingTasks: Run Task and then choosingcoverage.

If you are having trouble withcoverlet finding your .NET runtime on Windows, you can use the PowerShell Scriptcoverage.ps1 instead.

.\coverage.ps1

Several launch profiles are included for Visual Studio Code:

• 🕹Debug Game

  Runs the game in debug mode, allowing you to set breakpoints and inspect variables.

• 🎭Debug Current Scene

  Debugs the game and loads the scene with thesame name andin the same path as the C# file that's actively selected in VSCode: e.g., a scene namedMyScene.tscn must reside in the same directory asMyScene.cs, and you must have selectedMyScene.cs as the active tab in VSCode before running the launch profile.

  If GoDotTest is able to find a.tscn file with the same name in the same location, it will run the game in debug mode and load the scene.

  Naturally, Chickensoft recommends naming scenes after the C# script they use and keeping them in the same directory so that you can take advantage of this launch profile.

  ⚠️ It's very easy to rename a script class but forget to rename the scene file, or vice-versa. When that happens, this launch profile will pass in theexpected name of the scene file based on the script's name, but Godot will fail to find a scene with that name since the script name and scene name are not the same.

• 🧪Debug Tests

  Runs the game in debug mode, specifying the command line flags needed by GoDotTest to run the tests. Debugging works the same as usual, allowing you to set breakpoints within the game's C# test files.

• 🔬Debug Current Test

  Debugs the game and loads the test class with thesame name as the C# file that's actively selected in VSCode: e.g., a test file namedMyTest.cs must contain a test class namedMyTest, and you must have selectedMyTest.cs as the active tab in VSCode before running the launch profile.

  ⚠️ It's very easy to rename a test class but forget to rename the test file, or vice-versa. When that happens, this launch profile will pass in the name of the file but GoDotTest will fail to find a class with that name since the filename and class name are not the same.

Note that each launch profile will trigger a build (see./.vscode/tasks.json) before debugging the game.

⚠️Important: You must setup aGODOT environment variable for the launch configurations above. If you haven't done so already, please see theChickensoft Setup Docs.

This game includes various GitHub Actions workflows to help with development.

You'll want to install [clang-format] and make sure it's available on your systemPATH for automatic shader formatting to work whenever you save a.gdshader or.gdshaderinc file.

• Install on Windows
• On macOS, usehomebrew and runbrew install clang-format. You'll want to make sure that homebrew is able to update your shell'sPATH so that the installedclang-format binary is available globally.
• Linux: you know what to do

This template includes an updated version of the.clang-format file mentioned in theGodot Shaders Style Guide.

For syntax highlighting, we recommend theGodot Tools extension since it provides functionality for other Godot engine features as well.

Tests run directly inside the GitHub runner machine (usingchickensoft-games/setup-godot) on every push to the repository. If the tests fail to pass, the workflow will also fail to pass.

You can configure which simulated graphics environments (vulkan and/oropengl3) you want to run tests on in.github/workflows/visual_tests.yaml.

Currently, tests can only be run from theubuntu runners. If you know how to make the workflow install mesa and a virtual window manager on macOS and Windows, we'd love to hear from you!

Tests are executed by running the Godot test project inChickensoft.GodotGame from the command line and passing in the relevant arguments to Godot so thatGoDotTest can discover and run tests.

A spell check runs on every push to the repository. The spellcheck workflow settings can be configured in.github/workflows/spellcheck.yaml.

TheCode Spell Checker plugin for VSCode is recommended to help you catch typos before you commit them. If you need add a word to the dictionary or ignore a certain path, you can edit the project'scspell.json file.

You can also words to the localcspell.json file from VSCode by hovering over a misspelled word and selectingQuick Fix... and thenAdd "{word}" to config: cspell.json.

The included workflow in.github/workflows/version_change.yaml can be manually dispatched to open a pull request that replaces the version number inChickensoft.GodotGame.csproj with the version you specify in the workflow's inputs.

The included workflow in.github/workflows/publish.yaml can be manually dispatched when you're ready to publish your package to Nuget.

To publish to nuget, you need a repository or organization secret namedNUGET_API_KEY that contains your Nuget API key. TheNUGET_API_KEY must be a GitHub actions secret to keep it safe!

This repository includes arenovate.json configuration for use withRenovatebot. Renovatebot can automatically open pull requests to help you keep your dependencies up to date when it detects new dependency versions have been released. Because Godot has such a rapid release cycle, automating dependency updates can be a huge time saver if you're trying to stay on the latest version of Godot.

Unlike Dependabot, Renovatebot is able to combine all dependency updates into a single pull request — a must-have for Godot C# repositories where each sub-project needs the same Godot.NET.Sdk versions. If dependency version bumps were split across multiple repositories, the builds would fail in CI.

The easiest way to add Renovatebot to your repository is toinstall it from the GitHub Marketplace. Note that you have to grant it access to each organization and repository you want it to monitor.

The includedrenovate.json includes a few configuration options to limit how often Renovatebot can open pull requests as well as regex's to filter out some poorly versioned dependencies to prevent invalid dependency version updates.

🐣 Package generated from a 🐤 Chickensoft Template —https://chickensoft.games