Developer Guide
How to set up you IDE for OpenCiv3 development and other useful things for OpenCiv3 developers.
OpenCiv3 is powered by the Godot game engine. Some 90% of OpenCiv3 code is in C#, as both the OpenCiv3 core and the Godot integrations are mostly in C#. As such, having a good C# development environment set up is essential.
The team has tried different IDE setups of the years, each of which have their advantages and disadvantages. JetBrains Rider is current recommended option for OpenCiv3 development. If you prefer a more lightweight option, VS Code is a great alternative to get started.
OpenCiv3 was originally called "C7" and this name persists in many places in the source code. You may encounter the name in the codebase, in documentation, here in the wiki, etc.
Regardless of the IDE you'll be using, you'll first need to install a .NET SDK. You'll want the version that matches the project files, currently .NET 8.0. Later versions of the .NET runtime should be fine for running the release build, but you'll want the matching SDK, if you are looking to work on the codebase.
Next, you'll need to download the Godot game engine itself, the Godot Editor. Be sure to download the .NET version (with C# support) that matches the one we use for OpenCiv3, currently Godot 4.4. (Either 64-bit or 32-bit will work, and contrary to Godot's website, the 32-bit version does work on 64-bit Windows.) Later versions of Godot will be able open to project, but may treat project files in different ways, resulting in confusion and incompatibility: by using the same tools we avoid many of these issues.
Technically you can do all your work in the Godot Editor, but the C# editing and refactoring capabilities in Godot are not that great, so it's strongly recommended that you choose a more full-fledged C# IDE as your main OpenCiv3 development environment. Godot Editor is useful for tasks such as wiring up Godot events on the front end and creating UI elements, but the vast majority of development can be done outside the Godot Editor.
For any work done directly in Godot, you will need to use the Godot Editor. You can build and run the project inside the Editor context.
IDEs like Rider can be configured in such a way that you can run Godot from the IDE context, so you can have a really quick development iteration loop even without keeping the Godot Editor open. You can use the Godot binary as an IDE build target or call it from the command line to build to build the game from source without and IDE -- we use this Godot build functionality as part of our build pipelines, including the OpenCiv3 release process.
The first time you check out OpenCiv3, you will need to tell Godot about the project. From the Godot Project Manager click Import and select the location of C7/project.godot. Godot will automatically build the project before running it.
Note that there is an outstanding issue with the Godot 4.4 editor misbehaving after building the project. If you rebuild the project while running the editor, you'll likely need to restart the editor afterward.
Rider is arguably the best IDE for developing with C# and Godot. It has strong C# support, including refactoring, and supports debugging Godot projects with very little manual setup. Rider (and other JetBrains products) also have, IMO, the best Git merge resolution tool in the industry. As of 2024, Rider is available under a free non-commercial license that covers open source development.
Rider configuration
Once Rider is installed, go to the Plugins area, and install the "Godot Support" plugin (the GDScript plugin is not required, nor is the Godot Theme plugin). This will let you run Godot projects from Rider, and even better it will auto-detect the correct configuration so long as Godot is also installed.
Once you have Rider installed, open C7.sln, which lives in the C7 folder of the Prototype repository.
Then, set your Run/Debug configurations to be equivalent to the following, making sure the paths are correct locally. These will likely default to the correct values:
Note: This is for Godot 3.5. For Godot 4, it is the same configuration, but a ".NET Executable" configuration type, rather than "Start and Debug". For the Runtime on Godot 4, ".NET/.NET Core" works as expected
You can optionally rename the "Player" configuration, but it is the one you will want to launch. You should now be able to debug OpenCiv3 from Rider.
For additional discussion of Rider, please see thread about it at CFC.
If Rider fails to load the projects, you most likely forgot to install the .NET SDK, or installed the wrong one. Make sure you restart everything after installing the runtime.
You may run into an error: [MSB4236] The SDK 'Microsoft.NET.Sdk' specified could not be found. D:\Development\Civ Related Projects\Prototype\C7Engine\C7Engine.csproj at (0:0) when you open C7.sln in Rider.
We believe the solution to this is in the "Build, Execution, Deployment" -> "Toolset and Build" section of the Rider settings, but need to do some comparisons of working and non-working installs to have any certainty of how to fix it.
Once VSCode is installed, open the "Prototype" folder to which you downloaded this repository. Next, install the C# for Visual Studio Code plugin from the marketplace to add syntax highlighting, IntelliSense, Find References, and other IDE-like features for C#.
Visual Studio Code configuration
Finally, set up code formatting. For Visual Studio Code, formatting is done with OmniSharp and configured by the .editorconfig file. In order to configure OmniSharp, do the following:
- In your home directory, create
~/.omnisharp/omnisharp.jsonwith the following contents
{
"RoslynExtensionsOptions": {
"enableAnalyzersSupport": true,
},
"FormattingOptions": {
"enableEditorConfigSupport": true,
}
}
- Add the following options to your VS Code
settings.json(either workspace settings or your user level settings)
"omnisharp.enableMsBuildLoadProjectsOnDemand": true,
"omnisharp.enableEditorConfigSupport": true,
"omnisharp.enableRoslynAnalyzers": true,
- Optionally but recommended, add this option to your VS Code
settings.jsonto enable formatting on save
"[csharp]": {
"editor.formatOnSave": true,
}
- If Linting or IntelliSense are completely broken
- try adding
"omnisharp.useGlobalMono": "always"tosettings.json - you may need to rebuild the entire project through the Godot IDE
- try adding
The project can be built from the Godot editor or from the command line. It is important to note that, an initial build from the Godot editor is required (ie. when first cloning the project) in order to build from the command line. This is because building from the command line will only build and update C# scripts, but will not include changes made via the Godot editor. Similarly, the project should be built via the editor after making changes in the editor.
Running OpenCiv3 can be done by invoking Godot from the command line. You must first add the folder where Godot is installed to your system path. Then, invoking godot in the C7 folder will run the application:
cd C7 && godot MainMenu.tscn
Project unit tests are currently xUnit based. You can run dotnet test in any project folder containing an xUnit project. Do configure --logger values as below to ensure the status and name of each test being run is logged to the console.
cd EngineTests
dotnet test --logger "console;verbosity=detailed"
Please note that this will change after #259 is completed.
Logs are configured in the LogManager class, which is part of the C7 project. There is a section that explains how this works; the code looks like this:
Log.Logger = new LoggerConfiguration()
.WriteTo.GodotSink(formatter: consoleTemplate)
.Filter.ByIncludingOnly("(@l = 'Fatal' OR @l = 'Error' OR @l = 'Warning' OR @l = 'Information')") //suggested: OR SourceContext like 'C7Engine.AI.%' (insert the namespace you need to debug)
.MinimumLevel.Debug()
.CreateLogger();
Above the code, you'll see details on how to configure it. By default, it is configured to show 'Information' level or higher logs, and also to show debug or higher logs for any namespace you add as an approved filter for all log levels to the Filter.ByIncludingOnly line.
You can configure this to show debug or verbose logs for only the module you are debugging, to show only warnings and higher for other modules but debug or higher for your module, or any number of other ways.
Please note that our knowledge of Serilog is evolving, so there may be more up-to-date comments about the recommended way to configure logs in LogManager than what you are reading here.