Modding Tutorial 0: Your first mod

[boformer 3,169]

In this tutorial, we will create a basic mod in two different ways: With a simple text editor, and with the Visual Studio IDE.

Cities: Skylines uses the Unity Engine, which is based on Mono, an open source implementation of the .NET framework that runs on Windows, Mac and Linux. That means the same code can be used on all of these platforms. The .NET framework is comparable to Java. It's basically a set of libraries and a virtual machine that runs your .NET applications.

C# is the most common programming language that can be used to create .NET applications and libraries. It's very similar to Java (just better!).

After writing your mod in C#, you have to compile it to create machine readable code. Cities: Skylines comes with an integrated compiler. It works like this:

[.cs files containing raw C# code]   →   [COMPILER]   →   [compiled .dll file]

The .dll file is your compiled mod (what you usually download from the Workshop).

Alternatively, your can use an external compiler like the one provided by Visual Studio (see Method 2).

 

Method 1: Using Notepad, let the game compile

First we will create a mod with the tools provided by the game.

The game searches for mod source folders in the directory C:\Users\<YourName>\AppData\Local\Colossal Order\Cities_Skylines\Addons\Mods.

In this folder, create a new directory named "FirstMod". Inside of the new directory, create another folder named "Source". That's the directory for the .cs files

 

Open Notepad (or your favourite text editor) and enter this code:

// Makes UnityEngine and Cities: Skylines API classes available for use
using ICities;
using UnityEngine;


// the namespace makes the names of your classes unique. 
// Naming: You can just use the name of your mod, it doesn't really matter. Spaces are not allowed.
namespace Tutorial {

  
  // This defines a class that implements IUserMod. 
  // The class defines the name and description displayed in the content manager.
  // The game searches for these classes. Every working mod must contain one class implementing IUserMod.
  // Naming: Just append "Mod" to the name of your mod, like "NetworkSkins" -> "NetworkSkinsMod". Spaces are not allowed.
  public class MyFirstMod : IUserMod {

    
    // this defines the title of your mod displayed in content manager
    public string Name {
      get { return "My First Mod"; }
    }
    

    // this defines the description of your mod displayed in content manager
    public string Description {
      get { return "Hello World, this is my first mod!"; }
    }
  }
}

(Lines starting with "//" are comments. You can add your own or remove them without affecting anything.)

 

Save the file in the "Source" directory. Name it FirstMod.cs (in the file type dropdown, select "All Files").

 

Now just start your game. The game compiles your mod on start up. You will find it in the content manager:

You will also notice a new .dll file in your mod directory. That's your compiled mod:

So far we didn't add functionality to the mod. It only spawns the item in content manager.

The big problem of Notepad and the game compiler is that it is hard to find errors in your code. You will have to restart your game many times. That's where Visual Studio comes into play...

 

Method 2: Using Visual Studio (recommended)

Visual Studio is a specialized IDE for C#/.NET development. It helps you to find errors in your code, and it autocompletes code statements for you, and it compiles your mod much faster than the game. It is also a requirement for advanced modding techniques like detours. The following tutorials will be based on Visual Studio.

First of all, download and install Visual Studio Community 2017 for free.

Make sure that the .NET desktop development feature is checked. Also enable the individual component .NET Framework 3.5 development tools.

Step 1: Project Setup

Create a new project in VS2017:

1. Select File > New > Project
2. On the left, select Templates > Visual C# > Windows Classic Desktop
3. Select "Class Library (.NET Framework)"
4. In the top, select ".NET Framework 3.5" in the dropdown menu (Important!)
5. In the bottom, enter "SecondMod" as the name and solution name. and choose a location for your project files (e.g. your desktop)
6. Press OK

Visual Studio will create a project that looks like this:

On the right, you can see the Solution Explorer with a list of .cs files. Visual Studio created a file named Class1.cs to get us started.

If you want, you can rename the .cs file to match your mod name (Right click in solution explorer > Rename).

 

Step 2: Dependencies

Before we continue, we have to set up two things in the project. You always have to do it when you create a new mod project:

First, we will add the modding API (ICities), UnityEngine, ColossalFramework and the game assembly (Assembly-CSharp) as dependencies.

In the solution explorer, right click the "References" item and select "Add reference..."). Now use the "Browse..." button in the bottom to select the following .dll files. The files are located in the folder: Steam\steamapps\common\Cities_Skylines\Cities_Data\Managed

 

Step 3: Post Build Script

Secondly, we will add a so-called post build script: It automatically puts the compiled dll file into the C:SL mod directory when you compile with Visual Studio:

1. Right-click your project in the Solution Explorer and choose Properties
2. Select Build Events on the left hand side of the property sheet
3. Paste the following in the Post-build event command line:

mkdir "%LOCALAPPDATA%\Colossal Order\Cities_Skylines\Addons\Mods\$(SolutionName)"
del "%LOCALAPPDATA%\Colossal Order\Cities_Skylines\Addons\Mods\$(SolutionName)\$(TargetFileName)"
xcopy /y "$(TargetPath)" "%LOCALAPPDATA%\Colossal Order\Cities_Skylines\Addons\Mods\$(SolutionName)"

 

Step 4: Writing the Mod

Now we are finally ready for the creation of the actual mod.

Replace the contents of Class1.cs with this code:

using ICities;
using UnityEngine;

namespace Tutorial {

  public class MySecondMod : IUserMod {

    public string Name {
      get { return "My Second Mod"; }
    }
    
    public string Description {
      get { return "I made this with VS2017"; }
    }
  }
}

 

Step 5: Compilation

Press F6 (or Build > Build Solution) to compile the mod. The mod should appear in your mod directory.

Now start the game and enjoy the listing of your useless mod in content manager

Happy Coding!

 

Next part:

 

[cmdp123789 710]

Thanks for taking the time! Hopefully.. some people will take this as a first step into the modding world! Thanks a lot!

[Tim The Terrible 586]

This is really cool, can't wait for the more functional parts! Many thanks for sharing your knowledge

[alborzka 66]

Thank you for adding the text editor method! It's great for those of us who use Linux and non-Windows OS

[boformer 3,169]

8 hours ago, alborzka said:

Thank you for adding the text editor method! It's great for those of us who use Linux and non-Windows OS

Not really. You should take a look at MonoDevelop or Rider.

[AnotherAdo 2]

On 5/29/2017 at 8:27 AM, alborzka said:

Thank you for adding the text editor method! It's great for those of us who use Linux and non-Windows OS

Try Visual Studio Code.  https://code.visualstudio.com/

[alborzka 66]

On 2017-05-29 at 7:22 PM, boformer said:

Not really. You should take a look at MonoDevelop or Rider.

Hmm, I'm a physicist and whenever we code (usually in Python tbh) we just use a text editor (like Sublime) and then run the code in the terminal. I guess it's a different approach for C#, and that's why MonoDevelop or Rider are needed?

7 hours ago, AnotherAdo said:

Try Visual Studio Code.  https://code.visualstudio.com/

No idea this existed, nice! Will definitely give this a go

[boformer 3,169]

5 hours ago, alborzka said:

Hmm, I'm a physicist and whenever we code (usually in Python tbh) we just use a text editor (like Sublime) and then run the code in the terminal. I guess it's a different approach for C#, and that's why MonoDevelop or Rider are needed?

No idea this existed, nice! Will definitely give this a go

It doesn't really matter with what editor you write your code.

What matters is that you are using a compiler that supports unsafe code. Unsafe code is required for detours. The compiler built into the game does not allow unsafe code. That means you need an external compiler.

VS, Rider and MonoDevelop are coming with a compiler that supports external code, and it's very convenient. Alternatively, you could also use the command line to compile your .cs files.

[imabzb 1]

Everything works fine if I let the game compile the code, but that exact same code compiled by VS 2017 always gives me an error. I even removed other mods installed but I get the same error (but if I compile that code with the game, that exact same code works fine!). I used the EXACT same VS settings you have here (I followed your instructions to a T, at least 10 times) and copied and pasted your code. I don't get it. I spent 6 hours googling and reading trying to figure out what could be wrong but no luck. Any help would be greatly appreciated.

I get the following error when the game loads:

A Mod caused an error [ModException]

Details:
System.Reflection.ReflectionTypeLoadException: The classes in the module cannot be loaded.
  at (wrapper managed-to-native) System.Reflection.Assembly:GetTypes (bool)
  at System.Reflection.Assembly.GetExportedTypes () [0x00000] in <filename unknown>:0
  at ColossalFramework.Plugins.PluginManager+PluginInfo.GetInstances[IUserMod] () [0x00000] in <filename unknown>:0
  at EntryData.GenerateData () [0x00000] in <filename unknown>:0

 

[rovapasi1 53]

Is it possible you did not add the dependencies?

[imabzb 1]

Thank you for your reply.

No, I followed the instructions very carefully and am familiar with dependencies etc. I have all the References added. I did exactly as the OP did... the exact program/code which is why this is so confusing.

There is clearly something VS is putting in the compiled DLL that the game isn't and that the game doesn't like (maybe a setting in VS that I need to change?), but I can't figure out what that is. I've even loaded the DLL into a hex editor and I don't see anything strange with the class naming. The game appears to be complaining about not being able to load the classes within the DLL (yet it has no issues with those classes in the actual source file when compiling it).

I'm wondering if the latest cities update may have changed something that it doesn't like that VS puts in the DLL (some sort of class declaration tag or something, since the game is complaining that a class cannot be loaded).

Is there any way someone else can test the OP's program with the latest version of cities and the latest version of VS 2017?

I'm hoping someone more familiar with the game than me has encountered and overcome with issue.

 

Again, thank you for your reply.

 

Edit: For the mod that I want to develop it cannot be done with the in-game compiler. So I need to get this working.

 

Edit 2: I notice there must be some difference between the version of VS that the OP is using and I'm using because he can press F6 to build whereas mine does nothing, I have to press control->shift->B. I just did a fresh download and install of VS 2 days ago, so maybe the VS versions are different and one setting in the project is different, I don't know.

[TaradinoC 2]

On 5/27/2017 at 6:25 PM, boformer said:

1. Paste the following in the Post-build event command line:

if not exist "%LOCALAPPDATA%\Colossal Order\Cities_Skylines\Addons\Mods\SecondMod" mkdir "%LOCALAPPDATA%\Colossal Order\Cities_Skylines\Addons\Mods\SecondMod"
del /q /f "%LOCALAPPDATA%\Colossal Order\Cities_Skylines\Addons\Mods\SecondMod\"
xcopy /y "C:\Users\Felix\Desktop\SecondMod\SecondMod\bin\Debug\netstandard1.4\SecondMod.dll" "%LOCALAPPDATA%\Colossal Order\Cities_Skylines\Addons\Mods\SecondMod"

In the third line, replace the path C:\Users\Felix\Desktop\SecondMod\ with your project path.

You can use Visual Studio substitutions like $(TargetPath) in the post-build event so you won't have to customize it. Here's the one I've been using:

mkdir "%LOCALAPPDATA%\Colossal Order\Cities_Skylines\Addons\Mods\$(SolutionName)"
del "%LOCALAPPDATA%\Colossal Order\Cities_Skylines\Addons\Mods\$(SolutionName)\$(TargetFileName)"
xcopy /y "$(TargetPath)" "%LOCALAPPDATA%\Colossal Order\Cities_Skylines\Addons\Mods\$(SolutionName)"

 

[TaradinoC 2]

4 hours ago, imabzb said:

No, I followed the instructions very carefully and am familiar with dependencies etc. I have all the References added. I did exactly as the OP did... the exact program/code which is why this is so confusing.

There is clearly something VS is putting in the compiled DLL that the game isn't and that the game doesn't like (maybe a setting in VS that I need to change?), but I can't figure out what that is. I've even loaded the DLL into a hex editor and I don't see anything strange with the class naming. The game appears to be complaining about not being able to load the classes within the DLL (yet it has no issues with those classes in the actual source file when compiling it).

Double check the target .NET Framework version, on the Application tab of the project properties. It should be set to .NET Framework 3.5. You can also check the Runtime Version property of all your references (even the ones that were added automatically), which should say v2.0.50727.

[imabzb 1]

Hi TaradinoC

 

Thanks for your reply.

1. I'm not sure what version of VS you're using, but the macro names have been broken for some time now as has been reported often in the VS community (I've tried them many times with no luck). The macros report incorrect file paths. If you update VS to 2017 latest version, I suggest you either use $(MSBuildProjectDirectory) or $(MSBuildThisFileDirectory) or better yet, edit the csproj file directly and enter your own target with something like this near the end of the file:

 

<Target Name="MyAfterBuild" AfterTargets="Build">
  <Exec Command="copyFiles.bat" />
</Target>

The latter worked great for me.

 

2. I made certain that the project properties were set to .NET 3.5 when I created the project as instructed by the OP.

 

The SDK->NETStandard.Library files in dependencies all read 4.3 regardless of what I select in the project.

 

On the Project Applications tab I have Target Framework: .NETStandard 1.4 (same as OP). It only goes up to 1.6 (and I've tried them all!), but says you can download others, which I did, but they still never show up in the list. I suspected this may be the problem, but selecting "Install other frameworks" did not give me the option to actually select one (I typically use C++, Jass/jc, and asm for development, so I'm not sure if I have everything installed that is required for C#).

 

Is there an option somewhere to add all the .NET components? Or maybe I'm missing something more specific like a subset.

 

Thanks

 

[TaradinoC 2]

28 minutes ago, imabzb said:

I'm not sure what version of VS you're using, but the macro names have been broken for some time now as has been reported often in the VS community (I've tried them many times with no luck). The macros report incorrect file paths.

Hmm, I haven't had that problem, and I'm using VS 2017...

After searching for it, I see people reporting the problem with .NET Core/Standard specifically. And I just noticed that the OP says to make a .NET Standard project instead of .NET Framework.

Have you tried using the Class Library (.NET Framework) project template instead? It's under Windows Classic Desktop.

I haven't used .NET Core/Standard myself, and I don't know why it'd work for OP but not for you, but it looks like Standard 1.0 corresponds to a minimum Framework version of 4.5, so that might explain the conflict.

  Edited June 4, 2017 by TaradinoC  
link/clarification for macro problem reports

[imabzb 1]

ah... well, I did install and use what OP said ".NET Standard". .NET framework adds a lot more files and adds a bunch of "using" statements, which I left in, assuming each file requires them?

At least now I see .NET 3.5 in my project properties!

In any event, I created a new project with .NET Framework and now I get a new error

 

A Mod caused an error [ModException]

Details:
System.IndexOutOfRangeException: Array index is out of range.
  at EntryData.GenerateData () [0x00000] in <filename unknown>:0

 

I wish the game would be a little bit more informative.

[imabzb 1]

Thank you, TaradinoC! You are a God send!

 

That actually worked. I definitely have to use .NET Framework, not .NET Standard.

The reason for the exception was that when I created a new project I forgot to add : IUserMod lol (I've only be working with C# for a day, but I'll get there lol)

 

Problem solved. Thanks so much. You have no idea how crazy this was driving me for the last 24 hours.

 

[imabzb 1]

You were also right about the macros, they seem to work fine with .NET Framework but not with .NET Standard. Strange that this would be the case. But again, thanks for the info

[boformer 3,169]

1 hour ago, imabzb said:

You were also right about the macros, they seem to work fine with .NET Framework but not with .NET Standard. Strange that this would be the case. But again, thanks for the info

Nice catch. I'm usually using VS2015, but switched to 2017 for this tutorial. The macros with placeholders stopped working in VS2017.

I will edit the tutorial and add this information when I have time.

[Scuwr 0]

On 6/4/2017 at 4:38 AM, imabzb said:

That actually worked. I definitely have to use .NET Framework, not .NET Standard.

I'm in the same boat. I attempted to create a project using .NET Standard instead of .NET Framework, and received the same error. While using the .NET Framework template and CTRL-C everything from my old project, I was able to successfully load the mod to CS.

[Ocram's Razr 964]

Thanks for the tutorial! I can hardly wait the 10 days before Spring Break (because I need to study for my exams and wait to start diving into code).

[boformer 3,169]

I edited the top post. The "classic" .NET Framework is the better choice for this mod.

[boformer 3,169]

I just published the second tutorial:

 

[Codetonium 1]

Also note that if you are working on the Mac and need to locate the assemblies to reference, they are located in the steam folder 
/Users/[UserName]/Library/Application Support/Steam/steamapps/common/Cities_Skylines . In this folder there is a Cities.app file. This is a package file. Right click on the file and choose View Package Contents. This will expand the package. The assemblies (.dll) are in the /Contents/Resources/Data/Managed folder.

And the folder to publish your mod on the mac is /Users/[UserName]//Library/Application Support/Colossal Order/Cities_Skylines/Addons/Mods

[quickslow 0]

Hi, thanks a lot for your tutorial. Things may have changed with the newest VS, because I add dependencies, it says that the dll files are not strong-named. Do I have to go and sign all of these dll files manually?

[quickslow 0]

Nevermind, the files were somehow altered and I had to verify their integrity in steam. Then it worked. Same thing happened with workshop dlls. I had to unsub and resub for them to work.

[icy mccoolname 2]

Heya, does this still work with .NET framework 3.1 or .NET 5.0, using VS 2019? (In other words, how vital is it that one uses .NET Framework 3.5 exactly?)

 

I'm having a strange issue where I follow the instructions (as best I can) for Visual Studio 2019, however the compiled Mod doesn't show the supplied name or description in the Content Manager. Putting the .cs file in the location from the first step works fine("SecondSecondMod" in the image), so I'm wondering if it's the framework I'm using?

//Happy to spin this into it's own thread if modern dev setups are a separate topic :"D

[icy mccoolname 2]

After getting some pointers on the steam forums, I found that as of Visual Studio 2019, you can't change Framework type through the settings UI.

Here's how to setup a new project in Visual Studio 2019 for development of CS Mods:

1. Create a New Project (or take an existing project and skip this step):

   • C# Class Library (language "C#", project type "Library")

   • Project/Solution name and saved location as desired (refer original post)

   • Choose any Target Framework, we'll be changing this in the following steps.

2. Once created, Right click the name of the project in Solution Explorer (eg SecondMod), and select Unload Project

   • This opens the .csproj file for editing.

3. Under <PropertyGroup>, Change <TargetFramework> and add <LangVersion> to match the following:

   <TargetFramework>net35</TargetFramework>
   <LangVersion>preview</LangVersion>

   ^{This gets you off the 'Core' or 'Standard' frameworks and onto the "Framework n.n" frameworks. LangVersion is there to force the program to allow you to use a more current version of C#, which otherwise leads to compilation errors.}
   You may not need LangVersion to compile your code, your mileage will vary on this.

4. Save

5. Right click project ( eg "SecondMod (Unloaded)" in Solution Explorer > Reload Project )

Now if you right click the solution name and select properties, the Target Frameworks should read ".NET Framework 3.5". Other, more recent versions may be available, if you want to use a newer version that should be fine, the point is you can now select these from the UI!

From this point, the remainder of the tutorial remains the same (or close enough) in Visual Studio 2019. Hopefully 2022 doesn't change much beyond this!

--

This is probably bread and butter .NET, but in my defense the last time I used C#, we were still using Visual Studio 2012!

  Edited November 1, 2021 by icy mccoolname  
Added step-by-step instructions for a new project in VS2019

[Ccrancc 0]

I will confirm that the above steps do work in Visual Studio 2022 Community Edition.

[deek0146 0]

Doing this causes an IndexOutOfRangeException in OptionsMainPanel.AddUserMods. I literally just have an empty class like in the OP, and enabling it in the mod menu causes an error popup.

I even tried removing that class, so I just have an empty dll build, and it still gives me the same error!

 

Edit: Nevermind, it was a linking error.