Skip to content

DLL Modding

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

This page is about using doorways functionality to make your own DLL mod. 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. 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 content. 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[(https://visualstudio.microsoft.com/vs/). 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.

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.

Categorical Overview

The doorways namespace sh.monty.doorways is separated into several sub-namespaces each with their own category of utilities. The type of functionality a class exposes will be based on which category it's in:

This is outdated

  • doorways: The root namespace, contains Doorways initialization code, Logging utilities, the Resource Loader, and the Doorways Options Tab manager.
  • doorways.Engine: This module contains implementations for the Doorways JSON mod engine. It will generally be of little use to DLL modders, since all this module does is call into other Doorways modules to implement their functionality for non-DLL Doorways mods.
    • doorways.Engine.Crucible: Bridges with Mothtools at runtime.
  • doorways.CoreExtensions: Allows mods to safely modify how the base game engine works.
  • doorways.UIExtensions: Allows mods to safely modify game UI.
  • doorways.Patches: Most of this module is marked internal, which means your Doorways-enabled DLL mod won't be able to use these classes. It's generally unsafe to use these anyways, since they expose mostly unchecked hooks into the base game's code. All functionality they would expose is exposed more safely by CoreExtensions or UIExtensions, and if you find a use case that they don't cover it's generally better to create a new feature request issue on this repository.
    • doorways.Patches.SecretHistories: Patches that specifically alter game behavior, instead of simply acting as hooks. The single exception is the CoreEvents class, which any other mod may access in order to subscribe to events which will be run at various times in the game.

Core Extensions

There are no stable Core Extensions at this time.

UI Extensions

GameSplash

The GameSplash static class allows mods to change the text shown on the splash screen when the game starts up. In order to change the quote, assign a new string value to GameSplash.Quote. In order to change the advice that appears below it, assign a new string value to GameSplash.Advice.

If either of them are null, then they have not been modified by any other mods and will appear as in the vanilla game. If another mod already overwrote them, then the variables will contain the overwritten version. The text that appears is the text defined by the last mod in the load order to set the text values.

Clone this wiki locally