Skip to main content

​
What is ChroMapper?

ChroMapper is a community-built Beat Saber map editor built on Unity. It runs as a standalone Unity application and exposes a plugin system that lets you extend its functionality with custom C# assemblies. Plugins are loaded at startup from the Plugins directory inside your ChroMapper installation.

​
What this template provides

The ChroMapper Plugin Template is a dotnet new project template that scaffolds a fully working ChroMapper plugin project in seconds. You run one command and you get a C# class library pre-wired with everything you need:

HarmonyLib patching

HarmonyLib is already referenced. You can start writing [HarmonyPatch] classes the moment your project opens.

Unity engine references

All common Unity modules (CoreModule, UI, TextMeshPro, InputSystem, and more) are referenced directly from your ChroMapperDir.

Auto-deploy on build

A post-build MSBuild target runs xcopy to copy your compiled DLL straight into $(ChroMapperDir)\Plugins\ after every successful build.

Krafs.Publicizer

The Krafs.Publicizer NuGet package is included so you can access internal ChroMapper members without reflection boilerplate.

​
Template identity

When you install this template, the .NET CLI recognises it by the following identity:
FieldValue
Short namechromapperplugin
Full nameChroMapper C# Plugin
IdentityVainstains.ChroMapperPluginTemplate
ClassificationsChroMapper, Plugin, C#
LanguageC#
Target framework.NET Framework 4.8

​
What a plugin looks like

Every plugin scaffolded from this template starts with a single entry-point file, Plugin.cs. This is the real code the template generates:
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}!");
    }
}
Here is what each part does:
  • [Plugin(Name)] — marks the class as a ChroMapper plugin and registers it under the given name. ChroMapper discovers this attribute at startup.
  • [Init] — marks the method that ChroMapper calls when it initialises your plugin. This is your entry point, equivalent to Awake or Start in a Unity MonoBehaviour.
  • new Harmony(ID).PatchAll(...) — creates a Harmony instance identified by your plugin’s reverse-domain ID and applies every [HarmonyPatch] class in your assembly at once.
  • Debug.Log(...) — writes a message to ChroMapper’s Unity log so you can confirm the plugin loaded.
When you create a project with --Author YourName, the YourName string is substituted throughout the project, including the Author constant and the computed ID.

​
Next steps

Prerequisites

Check what you need installed before running the template

Quickstart

Install the template and create your first plugin

Build docs developers (and LLMs) love

Get started for freeTalk to us