Skip to main content
This guide walks you through every step from a fresh clone of the repository to a running ChroMapper plugin.
The build system reads the ChroMapperDir environment variable to locate ChroMapper’s assemblies and to copy your DLL after a successful build. Make sure it is set before you open your IDE or run any build commands. See Prerequisites for setup instructions.
1

Set the ChroMapperDir environment variable

If you have not done this yet, set ChroMapperDir to the full path of your ChroMapper installation directory — the folder that contains ChroMapper_Data\Managed\.
# Current session only
$env:ChroMapperDir = "C:\Program Files\ChroMapper"
For a permanent setting, see Prerequisites.
2

Install the template

Clone the repository, then run dotnet new install from the repository root to register the template with your local .NET CLI:
dotnet new install ./ChroMapperPluginTemplate
You should see output confirming the template was installed:
Success: Vainstains.ChroMapperPluginTemplate::1.0.0 installed the following templates:
Template Name          Short Name          Language  Tags
---------------------  ------------------  --------  ------------------
ChroMapper C# Plugin   chromapperplugin    [C#]      ChroMapper/Plugin/C#
3

Create a new plugin project

Run dotnet new chromapperplugin with the -o flag to set the output directory and --Author to stamp your name into the generated code:
dotnet new chromapperplugin -o MyPlugin --Author YourName
This creates a MyPlugin\ directory containing a ready-to-build C# project.
The --Author parameter replaces the YourName placeholder in the generated Plugin.cs and the computed plugin ID. Use a short identifier with no spaces — for example, your GitHub username.
4

Open the project in your IDE

Open the generated .csproj file in Visual Studio or Rider:
# Visual Studio — open the solution or project file directly
start MyPlugin\MyPlugin.csproj

# Rider
rider MyPlugin\MyPlugin.csproj
Once loaded, your IDE resolves all ChroMapper and Unity references from $(ChroMapperDir)\ChroMapper_Data\Managed\. If any references show as unresolved, double-check that ChroMapperDir is set and that your IDE was launched after the variable was set.
5

Review the generated entry point

Your project contains a single source file, Plugin.cs, with this content (with YourName replaced by whatever you passed to --Author):
Plugin.cs
using System.Reflection;
using UnityEngine;
using HarmonyLib;

namespace ChroMapperPluginTemplate;

[Plugin(Name)]
public class Plugin
{
    public const string Author = "YourName";
    public const string Name = "ChroMapperPluginTemplate";
    public const string ID = $"com.{Author}.{Name}";

    [Init]
    private void Init()
    {
        new Harmony(ID)
            .PatchAll(Assembly.GetExecutingAssembly());
        
        Debug.Log($"Hello from {Name}!");
    }
}
Key points:
  • [Plugin(Name)] registers the class with ChroMapper’s plugin loader.
  • [Init] marks the method ChroMapper calls when it initialises your plugin.
  • Harmony.PatchAll scans your assembly and applies every [HarmonyPatch] class you add.
6

Build the project

Build using your IDE’s build command, or from the command line:
dotnet build
After a successful build, MSBuild runs a post-build step that copies your DLL directly into ChroMapper’s Plugins directory:
<Target Name="PostBuild" AfterTargets="PostBuildEvent">
    <Exec Command="xcopy /Y /F &quot;$(ProjectDir)bin\$(Configuration)\$(TargetName).dll&quot; &quot;$(ChroMapperDir)\Plugins\&quot;" />
</Target>
You do not need to copy the file manually. Check your ChroMapper Plugins\ folder — your DLL should be there.
7

Launch ChroMapper and verify

Start ChroMapper normally. It scans the Plugins\ directory at startup and initialises any plugins it finds.To confirm your plugin loaded, check ChroMapper’s Unity log file. Look for the line printed by Plugin.cs:
Hello from ChroMapperPluginTemplate!
The log file is typically located at:
%APPDATA%\..\LocalLow\BinaryElement\ChroMapper\Player.log
On a Debug build, the .pdb file is also copied to the Plugins\ directory alongside the DLL, giving you symbol information if you attach a debugger.

​
Next steps

Your plugin is running. From here you can start extending ChroMapper:

Harmony patching

Intercept and modify ChroMapper methods at runtime

Unity integration

Work with GameObjects, UI, and the Unity event system

Project structure

Understand the generated files and how they fit together

Build and deploy

Configure Debug vs Release builds and the auto-deploy step

Build docs developers (and LLMs) love

Get started for freeTalk to us