Modding Toolchain - Cities Skylines 2 Wiki (2024)

Cities Skylines II enables the creation of Code Mods to add-on to or modify existing gameplay using the Modding Toolchain.

You do not need to install the Modding Toolchain if you only want to download and use mods from Paradox Mods

The Basics

Modding Launch Parameters

Add the following launch parameters to activate different modes to help with mod development.

• --developerMode
  • Allows you to access the developer menu by pressing ⇆Tab
  • Allows you to access the add object panel in game by pressing 🏠 Home

See also: Developer mode

• --uiDeveloperMode
  • Allows you to access the UI debugger http://localhost:9444/

Modding Options

The Modding section of the Options menu assists the modder in setting up the Modding Toolchain; the necessary environment to develop mods - minimizing the amount of software installation hunting required by users.

The toolchain acts as a minimalistic SDK and allows you to build mods, both C# and UI for Cities: Skylines II when all the entries show a green checkbox.

The user flow is intuitive - if a dependency is missing, you can install it, if it is installed you can uninstall it, if it is outdated or corrupted, you can upgrade or repair it. Additionally, the toolchain will use the main menu notification panel to inform the players of tasks that require attention.

Requirements

IDE

The Modding toolchain does not install any IDE for you, if you are not already familiar with one, you must download and install, and try to find which is the best fit for you.

• Jetbrains Rider
• Microsoft Visual Studio 2022 (Pro or Community)
• Visual studio Code

A supported IDE is mandatory in order to execute the needed steps to build functional CSII mods.

For C# mods:Microsoft Visual Studio 2022 (17.8) or Jetbrains Rider (2021.3.3) are the minimum versions supported.You can use either one.Note: it may also be possible to use other software or earlier versions in some cases, but the source code generation feature from Visual studio 2022 and Rider 2021.3.3 is mandatory to successfully compile Entities and Burst code. Additionally, the template projects to start modding may not be compatible with earlier versions or other software.

For UI mods:Microsoft Visual Studio Code (1.86) or Jetbrains Rider (2021.3.3) are the minimum versions supported.You can use either one.Note 1: it may also be possible to use other software or earlier versions in some cases. These IDEs just act as convenience on top of Node.js npm and webpack.Note 2: the game UI is written in html, css and js. It is more or less a standard react project using typescript. Labs user interface library is used to execute javascript and render the UI. While it is quite close to web standards, it is important to remember some css features are not supported in a standard way.

Unity Editor & License

The Unity editor version 2022.3.7f1 is required to be installed.It acts more or less like an SDK and you do not have to use it but you must have it installed with at least a valid personal or commercial license if you have one already you wish to use.

The version of the editor must be updated to the same version used by the game with future updates. The toolchain will detect outdated versions.The license is a legal requirement we can not automate, so you must create a Unity account in the installation process and activate it in Unity hub. The toolchain will download the correct version of Unity from the official download link and silently run the installer with default settings.

Unity Mod Project

Unity alone does not install all the required dependencies in order to compile C# mods, it is also necessary to acquire packages such as Entities and Burst. The toolchain will copy a template Unity project to the user persistent folder and open it. This step will start Unity and open that project, it takes a while but needs to be done only once per version.

Once imported, the project will close itself and the dependency be marked as installed.

This mod project step will enable our compilation pipeline to access the Burst compiler, IL post processors and the source code generators required, as well as allow mods to reference Unity assemblies needed to compile the mods.

.Net SDK

.Net SDK is used for various things, tooling and helpers. The minimum version supported is 6 but 8 is recommended.

The toolchain will download .Net 8 from the official download link and install it in the background silently.Note: As .Net can be installed in several different ways, this dependency may fail to be uninstalled through the toolchain if it was, for example; installed as a Visual Studio installer package.

Node.js

Node.js is only necessary for UI mods development. Minimum supported version is 18.

The toolchain will download Node.js 20.11 from the official download link and install it in the background silently.Node.js runs as a background service so if you have it installed prior to running the toolchain, it is good to remember processes that are already started will not inherit new environment variables. Some dependencies will modify the user environment variables so if you have node.js previously installed, you may get errors about missing environment variables until the computer or at least the node processes restarted.

C# Mod Project Template

Understanding the Template

This template is embedded into the game installation. It is a nuget package deployed using dotnet new install/uninstall tooling. Once installed, it will enable both Visual Studio and Rider to create an empty solution compatible with CSII mods.

This project will set the following environment variables used with the tooling downstream. In some cases when using non-standard folders, you may have to edit some of these manually. While it appears some could easily be coalesced into less variables, they are split this way intentionally with future proofness in mind.

Project Variables

Important to note

When creating a new mod project from a template, there are a few important things to know:

You may be prompted to select a PDX account path if the IDE UI supports it, you can edit that path in YourProject.csproj later. It will default to a file called pdx_account.txt placed on your current user Desktop. Edit that path if necessary. The format of the file expects your Paradox Account username on the first line and your password on the second line. This file is used to identify you when you publish a mod on Paradox Mods.

<PDXAccountDataPath>$(USERPROFILE)\Desktop\pdx_account.txt</PDXAccountDataPath>

Mod.props and Mod.targets are automatically added to your solution and shared between all your solutions. Those are generic configurations that are aligned with the previously set environment variables. You should never have to manually edit the content of those files.

PublishConfiguration.xml – this is the file used to specific properties uploaded to Paradox Mods along with your mod. Edit this file according to your wishes.

The LongDescription and ChangeLog field supports multi-line and subset of markdown (headings, bullet lists and bold text), as the example below demonstrates:

 <LongDescription># Title## Subtitle* Bullet 1* Bullet 2**Bold thanks** </LongDescription>

Beware text editors are stubborn and will try to reformat your file with indentation. You must ensure there are no spaces at the beginning of the multi-line entries to avoid issues.

Building the Mod

Building a mod follows the standard MSBuild process, compilation is performed using Roslyn C# compiler, using the standard compiler mechanics for source generation and executes an AfterBuild step that will run ModPostProcessor.exe on the compiled assembly.

All build output goes to the usual console in your IDE.

ModPostProcessor interfaces with the Unity project that was previously installed to run various IL Post Processors on the assembly, patches method calls for source generation and finally executes the Burst compiler for you so that code marked as Burst gets compiled to native and heavily optimized.This will result in your assembly and 3 extra native dll next to it, one for Windows, one for Linux and one for Mac. Linux and Mac are currently unused, but shall Mac and Linux support come out one day, already existing mods will just work so we still compile to these platforms even if the game is not released there at this time.

At this point, your mod should be able to load in the game and will be copied to CSII_LOCALMODSPATH as a last step. (C:\Users\<username>\AppData\LocalLow\Colossal Order\Cities Skylines II\Mods\).

Upon starting the game, your mod will be executed after the builtin game world has been created.

Mods subscribed through Paradox are delay-loaded to when the login is viable, for consistency, local mods are also delayed to about the same time. Due to this behaviour, you can not inject mod code super early in the game initialization process, while this may feel like a limitation, injection prior to that time would be rather unsafe and most of the time avoidable.

How to publish a Code Mod

Publishing a Code Mod to Paradox Mods is done directly through the mod project:You need to right click on your main mod project and select Publish (VS2022 only) or select the configuration from the top bar (Rider). This step will read the data from PublishConfiguration.xml and execute the helper tool ModPublisher.exe to upload the mod.

You are offered 3 options:

PublishNewModThis configuration uploads a new mod. At the end of the upload, the console log will show a ModID guid (typically 6 digit number).At this point you should copy that ModId into the PublishConfiguration.xml ModID field as it will be required for the 2 other publishing modes.

PublishNewVersionThis configuration updates an existing mod to a new version. This expects a new version number and a change log.

UpdatePublishedConfigurationThis configuration updates the metadata found in PublishConfiguration.xml on the server.

UI Mod Project Template

This template is embedded into the game installation. Once installed, it is an npx template and can be deployed using npx create-csii-ui-mod'. It is added to your global node modules registry when installed using npm link.

The project will download the required dependencies and can be opened in your IDE using code <Project name> or rider <Project name>/

Rider and VSCode work roughly the same, index.tsx is used to define the injection points of your UI mod in the react DOM. Writing UI is much like writing react components.

You can use UI or shell to compile your mod:

• npm run build will create a production build of the mod.
• npm run dev will run the watch mode, used in parallel with –-uiDeveloperMode argument when starting the game, you can get the UI hot reload in the game as you change it. When the game is started with -–uiDeveloperMode, you can connect the Chrome Debugger using http://localhost:9444.

You will then be able to inspect the DOM, see the console and access pretty much all the dev tools you need to develop your UI mod.

Local Mods Location

For both UI and C# mods, the default output after compiling a project is in the user persistent folder under the Mods/ModName path: C:\Users\<username>\AppData\LocalLow\Colossal Order\Cities Skylines II\Mods

The game will load local mods automatically. You can disable a mod temporarily by adding a "." before the folder name and start the game. E.g. Mods/.MyMod and it will be ignored.

External Documentation

Here are some relevant links that may help modders with the new game infrastructure.

• Entities documentation
• Burst
• Unity
• Coherent Gameface