Skip to content

DLL Modding

Jump to bottom
Nicolas Suarez edited this page Nov 25, 2022 · 22 revisions

This page is about using doorways functionality to make your own DLL mod. For information on how to create a JSON mod utilizing Doorways features, see JSON Modding with Doorways. For information on how Doorways is internally laid out, read the Doorways Internals Documentation page.

Creating a Cultist Simulator DLL Mod

Standard Cultist Simulator DLL mods can leverage Doorways' features simply by adding a reference to Doorways.dll in your own mod project and you'll be able to leverage the entire Doorways API. Make sure the "Copy Local" or equivalent setting is disabled! Your mod shouldn't need to supply Doorways on its own - it will be automatically added to the game's code-space if Doorways is itself enabled as its own mod.

The easiest way to get started with creating your own vanilla game DLL mod is to read Creating a Vanilla CultSim DLL Mod.

Creating a Doorways DLL Plugin

Doorways provides its own mechanism you can use to load your mod's code. This is recommended over creating your own DLL mod because unlike the vanilla CultSim modding API, Doorways' own API is stable (following Semantic Versioning rules), which means doorways-loaded mods will be much less likely to break themselves, crash the game, or break other mods.

Doorways mods are most easily made in Visual Studio 2022. You can find a configuration file with all required VS components importable to the Visual Studio Installer at this Gist.

Plugins vs Mods

Cultist Simulator introduces the concept of Mods as all-or-nothing packs of content; you enable one in the mod manager menu, and the game will try to load it all as one big chunk. Doorways extends this with the concept of Plugins. Mods can define multiple plugin DLLs, and Doorways will load each one as its own individual module. This provides a tangible benefit to mod authors in that two distinct features need not live in the same assembly, and bugs in one will not implicitly break the other. Additionally, this allows for simple drag-and-drop patch behavior; you can easily distribute small or even large changes in your mod by simply omitting or including a Plugin in your distribution as needed, rather than needing to recompile your project or handle some kind of manual loading scenario.

Setting up the Project

Create a new .NET 4.8 Project wherever you'd like. Add a reference to Doorways.dll in your project, and ensure "Copy Local" is set to false.

Next, add a new line at the bottom of your AssemblyInfo.cs file:

[assembly: Doorways]

This registers your DLL as a Doorways plugin. From here, you can make use of the entire Doorways API. For this tutorial, let's just have our mod say "Hello, Mansus!" in the logs when the game starts up.

Create a new class in your mod project, we'll call it Main.cs. In it, create an init function (name it whatever you like) and tag it as your init method:

using Doorways;

namespace DoorwaysSampleMod
{
    public static class Main
    {
        public static readonly Logger Log = new Logger();

        [DoorwaysInit]
        public static void Init()
        {
            var _span = Log.Span();
            _span.Info("Hello, Mansus!");
        }
    }
}

Testing the Project

Before you can perform this step, you'll need to make sure you've got a Doorways-Enabled Mod set up and enabled in-game.

Once you've written your poetic hello, build the project and place the resultant DLL in your mod's Content folder:

image

If both your mod DLL and your Synopsis.json are properly tagged as doorways entities, then Doorways will automatically load and run your mod on startup, and you should see something similar to the following lines in your game log:

>>>>>>>> [Doorways:<LoadDoorwaysPluginsForMod>d__3.LoadDoorwaysPluginsForMod]Debug: Loading Doorways Plug-in 'DoorwaysSampleMod' for 'DoorwaysSampleMod'.
> [Doorways Sample Mod:Main.Init]Info: Hello, Mansus!
>>>>>>>> [Doorways:DoorwaysMod.RegisterPlugin]Debug: Loaded Plugin 'Doorways Sample Mod' for mod 'Doorways Sample Mod' as 'dsm'
> [Doorways:ModLoader.PostLoadMod]Info: Loaded Doorways mod Doorways Sample Mod in 26ms

Loading Unity Asset Bundles with Doorways

For the most advanced kinds of mods that wish to make use of the entire Unity editor, Doorways provides a package that can be included into a Unity project and summarily included into your mod directory.

This allows your mod to easily interact with Unity itself, and manage prefabs, create or overhaul UI, or even make entirely new game scenes. This is the most advanced kind of content you can make with Doorways, however, there are some limitations that must be worked around.

Getting Started

To start, download Unity and make sure you have version 2021.2.5f1 installed.

If you want to make use of base game code and resources, clone https://github.com/weatherfactory/cultistsimulator-visible. Otherwise, just create a new Unity Project.

Clone this wiki locally