Cultist Simulator

Cultist Simulator

View Stats:
Cultist Simulator > Mods > Topic Details
 This topic has been pinned, so it's probably important
Lyrositor  [developer] May 23 @ 5:04am
Modding Cultist Simulator
The latest version of Cultist Simulator on gateofhorn has added modding capabilities based on the Frangiclave Mod Manager[] (the now-unmaintained tool I created prior to joining Weather Factory). This small guide will help you modify your game to your heart's content.

Example Mod: Demo Mod[]

Installing a Mod

tl:dr; Mods come as ZIP files; you need to copy them to the /mods directory in the game. Read on for more details.


Mods are distributed as ordinary ZIP files containing the modification's code. You can find them in this forum or on the Frangiclave Mod Repository[].

Once you have downloaded the mod, extract the ZIP to a folder on your computer, then copy that folder to the game's "mods" directory. The exact location of the "mods" directory depends on your OS; the easiest way to find it is to start your game, open the Options menu and click on "VIEW SAVE FILE". This should open your file explorer, and you should see a folder called "mods" (if you don't see it, go ahead and create it).

Then, start the game (or restart it if it is open) and navigate to the Transfigurations menu. You should now see your downloaded mod listed. Hit "Enable" to activate it. Your game is now modded!

Note: For the most part, any mod developed for the Frangiclave Mod Manager should continue to work with Cultist Simulator's new mod support, but some old Frangiclave mods may be incompatible with the new system, particularly if they added new endings (small syntax changes), used multiplayer functionality (no longer possible) or added new Mansus maps (no longer possible).

Creating a Mod

With the Cultist Simulator modding framework you can currently add new content, edit or remove the existing content, and add or replace images. While this post will not cover how to actually write content in Cultist Simulator's DSL, it will provide an overview of the tools the modding framework offers you.

The general structure of a mod is as follows:
  • manifest.json: a JSON file providing some meta information about your mod, such as its title and description.
  • content/: a directory that can contain content files (decks, elements, endings, legacies, recipes and verbs), with any number of subdirectories.
  • images/: a directory that can contain game images. The subdirectory an image is in will affect where it is used. The currently supported subdirectories are: "burnImages/" (for those fading background images some recipes produce), "cardBacks/" (for overriding certain cards' back images), "elementArt/" (for card art), "elementArt/anim/" (for card art animations), "endingArt/" (for end screen images), "icons40/aspects/" (for aspect art), "icons100/legacies/" (for legacy images in the legacy selection screen), "icons100/verbs/" (for verb token icons).

More detailed explanations are provided below.

You are also encouraged to look at the demo mod for an example of these mechanisms in action.

If you encounter problems while working on your mod, always check your game's "output_log.txt" first! You can find it next to your save file.


The general format of a "manifest.json" file is as follows:

{ "name": "Mod Name", "author": "Mod Author", "version": "1.0.0", "description": "Mod Description, shown in-game.", "description_long": "Long Mod Description, show on the Frangiclave Mod Repository. Supports Markdown." }

The version number should follow semantic versioning[] rules, for consistency with other mods. The long description is only shown on the Frangiclave Mod Repository web-site, if you choose to publish your mod there.


A mod's content files work just like the base game's content files, with the following caveats:
  • Mod files are always loaded after the base game's "core/" and "more/" folders.
  • Mod files can contain multiple entity types in one files (e.g. you can list two decks and one element in the same file; see the demo mod for an example).
  • Mod entities can extend, delete or overwrite base game entities.

The last part is what will matter most to modders extending the base game, so let's go into a bit more detail:

Overwriting an entity: Any entity that uses the same ID as a base game entity will overwrite that entity.

Extending an entity: By adding the property "extends", you can tell Cultist Simulator that this entity should inherit from a list of base game entities, e.g.:
{ "id": "my_new_entity", "extends": ["my_old_entity_a", "my_old_entity_b", "my_old_entity_c"] }
You can combine this with overwriting to make some tweaks to an existing base game entity, like changing an aspect's value.

Per-property extending: Sometimes when extending you just need to make a small change, like adding an entry to a deck spec or incrementing a number. This is where property operations come into play. When using "extend", you can specify some properties with the format "property_name$operation" to apply "$operation" to "property_name", where "$operation" is one of the following:
  • "$append": appends a list of items to the original list property.
  • "$prepend": prepends a list of items to the original list property.
  • "$plus": adds the specified number to the original number property.
  • "$minus": subtracts the specified number from the original number property.
  • "$extend": extends a dictionary with the specified properties.
  • "$remove": removes each element in the list from the original property, which can either be a list or a dictionary.
For example, if you wanted to increment a follower's aspects, you could do something like this:
{ "id": "neville_d", "extends": ["neville_d"], "aspects$extend": { "knock": 77 } }
This will set Neville, a Key's Knock aspect to 77 instead of its base 10.

Deleting entities: Sometimes you may need to completely remove a base entity from the game. You can do this using the "deleted" keyword. For example, to remove Saliba, a Cyprian:
{ "id": "saliba_d", "deleted": true, }


My mod is crashing the game/not working as intended, how can I see what's going wrong?

Navigate to your game's save file and look for a file called "output_log.txt", then read it carefully for any helpful messages.

I don't understand something this guide covers, where can I find more information?

The Cultist Simulator Discord has a dedicated #modding[] channel for helping people mod the game, and the Cultist Simulator Mods forum is there to help people with modding. Feel free to ask the community for help.

Additionally, while this guide does not aim to be a complete reference, if you think a section is unclear or could use some improvement, feel free to suggest it in the comments.
Last edited by Lyrositor; May 23 @ 6:12am
Cultist Simulator > Mods > Topic Details