Skip to content

DLL Modding

Nicolas Suarez edited this page Nov 15, 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 Mod

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 (it follows 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.

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 plug-in. 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.

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