{%hackmd theme-dark %}

# CobaltCoreModBuildConfig

`Shockah.CobaltCoreModBuildConfig` is a NuGet package, which helps with setting up a project for Cobalt Core mod development.

Its main features are:
1. Automatically setting up references to common libraries used by the game and/or the modloader, without any unnecessary files:
* CobaltCore.dll
* CobaltCoreModding.Definitions.dll
* Microsoft.Extensions.Logging.Abstractions
* MonoGame
* Harmony
* Newtonsoft (Json NET)
2. Enabling running and debugging straight from the IDE, by just hitting the "Run" button.
3. Automatically copying the required files into a common Mods folder.
4. Automatically preparing a ZIP file including only the required files, ready to share with other people.

# Installation

As a prerequisite, you need to have the "classic" modloader from here: https://github.com/Ewanderer/CobaltCoreModLoader/releases.

To start using the package, install the `Shockah.CobaltCoreModBuildConfig` NuGet package via your IDE's GUI, or add this entry to your `.csproj` file:

`<PackageReference Include="Shockah.CobaltCoreModBuildConfig" Version="2.0.0" />`

# Adding extra files

A lot of mods will require some extra files to function properly -- for example assets. The package by default only looks at files in the output directory (`bin`). To add an extra folder, say, called `assets`, add it like this:

`<IncludedModProjectPaths>assets</IncludedModProjectPaths>`

# Advanced configuration

There are several properties you can configure when using the package:

* `ModLoaderPath` -- the path to the folder containing the "classic" modloader.
Defaults to one of these, in order:
* `$(USERPROFILE)\CobaltCoreModLauncher`
* `$(USERPROFILE)\Downloads\CobaltCoreModLauncher`
* `GameDllPath` -- the path to the CobaltCore.dll file.
Defaults to `$(ModLoaderPath)\CobaltCore.dll`.
* `ModName` -- the name of the mod. This is used for the name of the mod's folder, as well as the ZIP name. Defaults to the project's name.
* `ModVersion` -- the current version of the mod. Only relevant for ZIP naming purposes.
* `EnableModDeploy` -- whether deploying mods to the ModLibrary folder is enabled. Defaults to `True`.
* `ModDeployModsPath` -- the path to the folder to deploy mods to when built.
Defaults to `$(ModLoaderPath)\ModLibrary`.
* `EnableModZip` -- whether creating a ZIP file on deploy is enabled. Defaults to `True` in the `Release` configuration, `False` otherwise.
* `ModZipPath` -- the path to the ZIP file that should be created for publishing purposes.
Defaults to `$(MSBuildProjectDirectory)\.release\$(ModName)-$(ModVersion).zip`.
* `IncludedModProjectPaths` -- semicolon-separated additional paths to deploy/ZIP, relative to the project's folder.
* `EnableGameDebugging` -- whether the "Run" button debugging should be enabled. Defaults to `True`. Currently only applicable to Windows machines.

# Stable enum definitions

The NuGet package also comes with a reference to EnumByNameSourceGenerator, which automatically generates accessors utilizing the `Enum<T>.Parse(string)` method under hood. This is very important in Cobalt Core modding for accessing enums like `Spr` and `UK`, because they are auto-generated and often change between game builds. For example, when using `Spr` enum cases directly, a mod may suddenly start using a different sprite on another game build, or crash in the worst case.

To start using this technique, create a class like this:

using Nanoray.EnumByNameSourceGenerator;

namespace YourName.ModName
{
    [EnumByName(typeof(Spr))]
    internal static partial class StableSpr { }
}

Now, instead of using `Spr` directly, use `StableSpr`. For example, if you were to use `Spr.icons_ace`, use `StableSpr.icons_ace` instead.