Making a mod

Overview

What follows is a very barebones, and frankly not very useful plugin class, even as a starting point, but it should be enough to give a decent idea of how to do quick upgrades of existing mods for those who want to.

using System;
using IPA;
using IPA.Logging;

namespace Demo
{
    [Plugin(RuntimeOptions.SingleStartInit)]
    internal class Plugin
    {
        public static Logger log { get; private set; }

        [Init]
        public Plugin(Logger logger)
        {
            log = logger;
            log.Debug("Basic plugin running!");

            // setup that does not require game code
            // this is only called once ever, so do once-ever initialization
        }

        [OnStart]
        public void OnStart()
        {
            // setup that requires game code
        }

        [OnExit]
        public void OnExit()
        {
            // teardown
        }
    }
}

There are basically 4 major concepts here:

  1. Logger, the logging system.
  2. PluginAttribute, which declares that this class is a plugin and how it should behave.
  3. InitAttribute, which declares the constructor (and optionally other methods) as being used for initialization.
  4. The lifecycle event attributes OnStartAttribute and OnExitAttribute.

I reccommend you read the docs for each of those to get an idea for what they do.

It is worth noting that this example is of a mod that cannot be enabled and disabled at runtime, as marked by RuntimeOptions.SingleStartInit.

What can be changed

Before we go adding more functionality, its worth mentioning that that is not the only way to have a plugin set up.

For starters, we can add another method marked [Init], and it will be called after the constructor, with the same injected parameters, if those are applicable.

[Init]
public void Init(Logger logger)
{
    // logger will be the same instance as log currently is
}

If you only had a method marked [Init], and no constructors marked [Init], then the plugin type must expose a public default constructor. If multiple constructors are marked [Init], only the one with the most parameters will be called.

You may also mark as many methods as you wish with [Init] and all of them will be called, in no well-defined order on initialization. The same is true for [OnStart] and [OnExit], respectively.

From Scratch

If you are starting from scratch, you will need one other thing to get your plugin up and running: a manifest.

A basic manifest for that might look a little like this:

{
  "author": "ExampleMan",
  "description": [
    "A demo plugin written for the BSIPA basic tutorial."
  ],
  "gameVersion": "1.6.0",
  "id": null,
  "name": "Demo Plugin",
  "version": "0.0.1",
  "features": [
  ],
  "links": {
    "project-home": "https://example.com/demo-plugin",
    "project-source": "https://github.com/exampleman/demo-plugin/",
    "donate": "https://ko-fi.com/exampleman"
  },
}

There is a lot going on there, but most of it should be decently obvious. Among the things that aren't immediately obvious, are

  • id: This represents a unique identifier for the mod, for use by package managers such as BeatMods. It may be null if the mod chooses not to support those.
  • features: Don't worry about this for now, this is a not-very-simple thing that will be touched on later.

In addition, there are a few gatchas with it:

  • description: This can be either a string or an array representing different lines. Markdown formatting is permitted.
  • gameVersion: This should match exactly with the application version of the game being targeted. While this is not enforced by BSIPA, mod repositories like BeatMods may require it match, and it is good practice regardless.
  • version: This must be a valid SemVer version number for your mod.

In order for your plugin to load, the manifest must be embedded into the plugin DLL as an embedded resource. This can be set in the Visual Studio file properties panel under Build Action, or in the .csproj like so:

<ItemGroup>
  <EmbeddedResource Include="manifest.json" />
</ItemGroup>

At this point, if the main plugin source file and the manifest are in the same source location, and the plugin class is using the project's default namespace, the plugin will load just fine. However, this is somewhat difficult both to explain and verify, so I recommend you use the the misc.plugin-hint field in your manifest. It can be used like so:

"misc": {
  "plugin-hint": "Demo.Plugin"
}

With this, you can set plugin-hint to the full typename of your plugin type, and it will correctly load. This is a hint though, and will also try it as a namespace if it fails to find the plugin type. If that fails, it will then fall back to using the manifest's embedded namespace.

A less painful description

If you want to have a relatively long or well-formatted description for your mod, it may start to become painful to embed it in a list of JSON strings in the manifest. Luckily, there is a way to handle this.

The first step is to create another embedded file, but this time it should be a Markdown file, perhaps description.md. It may contain something like this:

# Demo Plugin

A little demo for the BSIPA modding introduction.

---

WE CAN USE MARKDOWN!!!

Then, in your manifest description, have the first line be something look like this, but replacing Demo.description.md with the fully namespaced name of the resource:

"#![Demo.description.md]",

Now, when loaded into memory, if anything reads your description metadata, they get the content of that file instead of the content of the manifest key.

Configuring your plugin

Something that many plugins want and need is configuration. Fortunately, BSIPA provides a fairly powerful configuration system out of the box. To start using it, first create a config class of some kind. Lets take a look at a fairly simple example of this:

namespace Demo
{
    public class PluginConfig
    {
        public static PluginConfig Instance { get; set; }

        public int IntValue { get; set; } = 42;

        public float FloatValue { get; set; } = 3.14159f;
    }
}

Notice how the class is both marked public and is not marked sealed. For the moment, both of these are necessary. Also notice that all of the members are properties. While this doesn't change much now, it will be significant in the near future.

Now, how do we get this object off of disk? Simple. Back in your plugin class, change your [Init] constructor to look like this:

[Init]
public Plugin(Logger logger, Config conf)
{
    log = logger;
    PluginConfig.Instance = conf.Generated<PluginConfig>();
    log.Debug("Config loaded");

    // setup that does not require game code
}

For this to compile, though, we will need to add a few usings:

using IPA.Config;
using IPA.Config.Stores;

With just this, you have your config automatically loading from disk! It's even reloaded when it gets changed mid-game! You can now access it from anywhere by simply accessing PluginConfig.Instance. Make sure you don't accidentally reassign this though, as then you will loose your only interaction with the user's preferences.

By default, it will be named the same as is in your plugin's manifest's name field, and will use the built-in json provider. This means that the file that will be loaded from will be UserData/Demo Plugin.json for our demo plugin. You can, however, control both of those by applying attributes to the Config parameter, namely Config.NameAttribute to control the name, and Config.PreferAttribute to control the type. If the type preferences aren't registered though, it will just fall back to JSON.

But what about more complex types than just int and float? What if you want sub-objects?

Those are supported natively, and so are very easy to set up. We just add this to the config class:

public class SubThingsObject
{
    public double DoubleValue { get; set; } = 2.718281828459045;
}

public SubThingsObject SubThings { get; set; } = new SubThingsObject();

Now this object will be automatically read from disk too.

But there is one caveat to this: because SubThingsObject is a reference type, SubThings can be null.

This is often undesireable. The obvious solution may be to simply change it to a struct, but that is both not supported and potentially undesirable for other reasons we'll get to later.

Instead, you can use NonNullableAttribute. Change the definition of SubThings to this:

[NonNullable]
public SubThingsObject SubThings { get; set; } = new SubThingsObject();

And add this to the usings:

using IPA.Config.Stores.Attributes;

This attribute tells the serializer that null is an invalid value for the config object. This does, however, require that you take extra care ensure that it never becomes null in code, as that will break the serializer.

What about collection types?

Well, you can use those too, but you have to use something new: a converter.

You may be familiar with them if you have used something like the popular Newtonsoft.Json library before. In BSIPA, they lie in the IPA.Config.Stores.Converters namespace. All converters either implement IValueConverter or derive from ValueConverter<T>. You will mostly use them with an UseConverterAttribute.

To use them, we'll want to import them:

using System.Collections.Generic;
using IPA.Config.Stores;
using IPA.Config.Stores.Converters;

Then add a field, for example a list field:

[UseConverter(typeof(ListConverter<string>))]
public List<string> ListValue { get; set; } = new List<string>();

This uses a converter that is provided with BSIPA for List<T>s specifically. It converts the list to an ordered array, which is then written to disk as a JSON array.

We could also potentially want use something like a HashSet<T>. Lets start by looking at the definition for such a member, then deciphering what exactly it means:

[UseConverter(typeof(CollectionConverter<string, HashSet<string>>))]
public HashSet<string> SetValue { get; set; } = new HashSet<string>();

The converter we're using here is CollectionConverter<T, TCollection>, a base type for converters of all kinds of collections. In fact, the ListConverter<T> is derived from this, and uses it for most of its implementation. If a type implements ICollection<T>, CollectionConverter<T, TCollection> can convert it.

It, like most other BSIPA provided aggregate converters, provides a type argument overload CollectionConverter<T, TCollection, TConverter> to compose other converters with it to handle unusual element types.