Modding

Modding Cultist Simulator is fairly straightforward, as most of the game's files are in a plain text .json format, which can be edited with any text editing program, like notepad, although it can be helpful to use one that is designed for coding, like Notepad++. The possibilities for modding range from simple gameplay tweaks, custom stories to whole total conversion mods.

To help with testing your mod, check out the debugging console.

= Debugging =

If your game gets stuck in a black screen on the main menu, it is very likely that you forgot a character somewhere in your code. Most likely a ',' is missing at the end of a line or a bracket wasn't closed with ']' or '}'. It is highly suggested that modders follow strict JSON double quote requirements to use automated syntax checkers. More on this may be found in the Double quotation marks section.

To see the error messages you either need to activate the console and toggle on the log, or navigate to this file to read them outside the game (searching the file for "broke" will find the common problems):


 * \AppData\LocalLow\Weather Factory\Cultist Simulator\output_log.txt

The "Update Content" button in the console is also very useful because it lets you test changes while the game is running.

= Modding game files =

The official documentation on how to mod game files is located here: https://steamcommunity.com/app/718670/discussions/1/1652171126120841074/

Location of the base game's files:


 * \Cultist Simulator\cultistsimulator_Data\StreamingAssets\content

The base game's files are within the 'core' folder.

User mods are placed within the 'mods' folder located here on Windows:


 * %appdata%\..\LocalLow\Weather Factory\Cultist Simulator\mods

Other operating systems may locate their mod folder location by opening the game and selecting "View Save File" from the options menu, then selecting the "mods" folder.

Mod folder structure
Mods are structured as a normal folder. This folder contains up to three items:


 * synopsis.json - a JSON file that provides some information about the mod, such as the title and description.
 * A folder named "content" - This is a folder where the JSON files that change game entities will be located.
 * (Optional) A folder named "images" - This folder may contain a number of optional folders, each of which is used to hold uploaded images for use by a mod.

The list of folders that can currently be placed within the "images" folder along with their uses is as follows (some cases involve a folder within another folder, and have been marked with '\' to designate this):
 * "burnimages" - For the fading background images some recipes produce
 * "cardBacks" - For overriding certain card's back images
 * "elementArt" - For card artwork
 * "elementArt\anim" - For card artwork animation images
 * "endingArt" - For ending screen images
 * "icons40\aspects" - For aspect artwork
 * "icons100\legacies" - For legacy images at the legacy selection screen
 * "icons100\verbs" - For verb token icon images
 * "ui" - For table (background) images and the mansus map image
 * "statusbaricons" - For icons for the stats shown in the statusbar on the bottom of the screen

Adding images
Images are added to the game by adding it to one of the folders located above. In most cases game entries and their matching images are linked by matching the filename of the image with the "id" of the desired entry. Images usually match a specific size or aspect ratio, though further testing is required to if any issues are caused by surpassing these limits.

synopsis.json
The contents of synopsis.json is formatted as follows:

{    "name": "Mod Name", "author": "Mod Author", "version": "1.0.0", "description": "Mod Description, shown in-game.", "description_long": "Not used in-game. May be used at some point in the future." } Note: synopsis.json was previously called manifest.json.

Mod file json structure
The json files that are used to modify the game are located in the "content" folder. The structure of these can vary, but in general they appear similar to this:

{ "recipes": [    {         ...     },     {         ...     } ], "decks": [    {         ...     } ] }

The exact formatting of the properties that may be placed in each ... entity location may be found in their respective sections below.

Double quotation marks
Cultist Simulator is not strict about its JSON formatting, and thus will accept files that lack double quotes around their values. For example Cultist Simulator will accept the following entry as valid:

{    id: "example_follower", label: "Carl", aspects: {mortal: 1, acquaintance:1, follower_lustsensation:1}, description: "Carl wishes he could mod.", animFrames: 1, xtriggers: {recruiting: carl, killmortal:corpse, derangemortal:lunatic}, unique: true }

However it is suggested that modders instead format all their entries with the strict double quotes around any property besides true/false and numbers. The same example with this strict formatting would appear as so:

{    "id": "example_follower", "label": "Carl", "aspects": {"mortal": 1, "acquaintance":1, "follower_lustsensation":1}, "description": "Carl wishes he could mod.", "animFrames": 1, "xtriggers": {"recruiting": "carl", "killmortal":"corpse", "derangemortal":"lunatic"}, "unique": true }

By doing this modders can first copy and paste their mod files into a JSON syntax checker such as https://jsonlint.com/ prior to attempting to load them into the game. Given that mod files may be hundreds of lines long and something as tiny as a single missing comma can cause Cultist Simulator to boot to a black screen on startup, it is highly suggested for modders to format mod files in such a way that an automated checker can find syntax errors for them.

Modifying entities
Some of the best capabilities of modding Cultist Simulator lies in the ability to overwrite, delete, or extend game entities. This allows modders to alter nearly any part of the vanilla game.

Overwriting entities
Any entity listed in the mods folders that uses the same "id" as a base game entity will completely overwrite that entity. This can be used in combination with the "extends" property to allow for edits that will remain compatible even through potential other mod or base game changes, or it can be used to make larger changes as needed.

Deleting entities
Entities may be deleted by specifying "deleted": true while overwriting them. For example:

{    "id": "saliba_d", "deleted": true, }

will delete Saliba, a Cyprian, from the game. Note that deleting entities can potentially cause errors if other entities that depend on them are not modified accordingly to adjust for their absence.

Direct extensions
Extending entities is potentially the strongest ability for modders of Cultist Simulator and, when used properly, can result in mods that are much more compatible while requiring less work to create and maintain. Extending an entity works by adding the "extends": ["entity1", "entity2"] property to an entity. This copies all values from the listed entities into the modified entity, not overwriting any values that are specifically listed. This is most useful in allowing for editing only parts of base game entities. For example:

{    "id": "saliba_d", "extends": ["saliba_d"], "description": "Definitely not the best follower" }

Will only overwrite the description of Saliba, without changing any other values. This then should mean that if another mod also edits Saliba in the same fashion then the two no longer will cause conflicts (assuming they both don't alter his description, in which case the second mod should take precedence).

Alternatively if you want to make duplicate entities you can do the same process only with a new "id" value. This text will create two more Saliba triplets that are absolutely identical to him except for their description.

{    "id": "saliba_d_triplet1", "extends": ["saliba_d"], "description": "Saliba's first mysterious triplet brother." }, {    "id": "saliba_d_triplet2", "extends": ["saliba_d"], "description": "Saliba's second mysterious triplet brother." }

A few notes:
 * While the two example triplet's would be identical to Saliba, they will not be able to be used in recipes that specifically target Saliba unless those recipes were also altered. Simply creating a new entity is not enough, the new entity must also be connected through recipes to the rest of the game.
 * Uniqueness groups are copied over as well! Without overwriting this property only one of the three mysterious Saliba triplets could be present on the board at once.
 * Care should be taken with extensions to not accidentally create infinite reference loops. For example if a recipe extends a recipe to which it is an alternativerecipe, this creates an infinite loop (original recipe -> alternate recipe -> alternate recipe -> alternate recipe -> ...) and can cause Cultist Simulator to crash. This can be solved simply by overwriting the looping properties in the extended recipe.
 * Recipe connections do not appear to properly transfer across extensions that involve an ID change. More on this is stated in the templating section below.

Per-property extensions
Modders may also perform per-property extensions, which allows for an even finer degree of control. This is done by adding an operation to the end of a given property in an extended entity. For example:

{    "id": "saliba_d", "extends": ["saliba_d"], "aspects$extend": {"resentment": 10} }

Will add the "resentment" aspect to Saliba at a strength of 10 without changing any other properties. The current list of property operations is as follows:
 * $append - appends a list of items to the target list property
 * $prepend - prepends a list of items to the target list property
 * $plus - adds the specified number to the target number property
 * $minus - subtracts the specified number from the target number property
 * $extend - adds the specified properties to the target dictionary
 * $remove - removes each element in a list of items from the target list or dictionary property

For those not familiar with the JSON format, properties that are located within square brackets "[]" are "lists" while properties that are located within curly braces "{}" are "dictionaries". Using the wrong operation, for example $append on a dictionary, will cause there to be no effect.

Text formatting
Text can be found almost everywhere in the game files and it can be affected by these formatting commands. Most of the tags listed on this website also work: http://digitalnativestudios.com/textmeshpro/docs/rich-text/

Order of effects
The effects of a recipe happen in an order. This means that for example you can't first obtain a card using a deckeffect and then transform it using an xtrigger in the same recipe, but the other way around it will work. (Might require more testing.)


 * "requirements for alternative/additional recipes are checked" -> "mutations" -> "xtriggers" -> "induces" -> "deckeffect" -> "effects" -> "requirements for linked recipes are checked" -> "expulsion"

As you can see, the main difference between alternative/additional recipes and linked ones is that the first are checked for before any of the effects of the original recipe happen and the second are checked for after almost all of the original recipe's effects have happened. If the requirements for an alternative recipe are met, none of the original recipe's effects will happen because they will be replaced by the alternative's (including the check for additional recipes).

It's possible for a linked recipe (or an alternate recipe of a linked recipe) to start even though its required cards have been expulsed, but this causes weird behavior as there will be an invisible ghost copy of the card, and its aspects, left behind in the recipe. The ghost copy weirdness only seems to happen with linked recipes. This may be avoided by adding a recipe step between the expelling step and the requirements step.

Entity formatting
These sections describe the individual properties that can be used in an entity, and what their purposes are.

Elements
Elements can be cards or aspects.

Verbs
Verb tiles are the objects in which recipes are executed.

If you say that a recipe goes in a verb that doesn’t exist on the board, then trigger that recipe via linking from another recipe, it will spawn the verb to put the recipe in. If the verb is defined in a JSON file, it will stick around; otherwise it will disappear when its contents are removed. (e.g. Time Passing is added from certain verbs and sticks around because it is defined, whereas the season verbs are not defined and just spawn new ones)

Recipes
Recipes are powerful tools that utilise verb tiles and cards to cause all sorts of different effects.

Linked/alternative recipes are given priority by order. If it doesn’t fire (either due to chance or precondition failure) then the next recipe will evaluate its own chance/preconditions. Expeditions make heavy use of this. The chance variable is a probability out of 100. So, for instance, if you want a ⅓ chance for each of three options, you would have to give the first one 33, the second one 50 (because, if the first one fails, then it should have a 50% chance of doing the second one and a 50% chance of doing the third one), and the third one 100 (because if the first and second fail, then it should do the third one).

Expeditions
Expeditions are recipes.

Creating custom expeditions/obstacles requires you to change the core file explore_vaultentry, specifically explorevaulttick and explorevaultsuccess to include the obstacle’s starting recipe and the expedition’s success recipe respectively. Your expedition will end the moment you run into a custom obstacle/bypass all the obstacles if explore_vaultentry isn’t modified to include your custom recipes.

Slots
Slots can be inserted into elements, verbs and recipes.

Decks
Decks contain a list of card elements and are used for randomisation. The save file keeps track of which cards remain in a deck. When a unique card is drawn from a deck, cards with the same uniqueness group will be removed from all other decks at the same time.

Legacies
Legacies are starting scenarios.

Endings
Endings are the ways that a Cultist Simulator run ends.

Special LEVER cards
Certain special cards are defined based on previous playthroughs. These are most commonly used as "effects" results in the early recipes for various legacies. Further testing is needed to determine the exact limitations and functionality of these card IDs.

= Mod download links =

New and current modders are suggested to upload their mods to either
 * Moddb Website: https://www.moddb.com/games/cultist-simulator/mods
 * Discord Modding Channel: https://discord.gg/ub2tE6Y
 * Another location and link to it from this google spreadsheet: https://docs.google.com/spreadsheets/d/16qnXiwg5Vvkv6cASS1vys78QHkfN1SjU7r1OOOUQLeo/
 * Another location and link to it from the steam discussion page for modding: https://steamcommunity.com/app/718670/discussions/1/

= Modding save files =

Location of save files on Windows:


 * \AppData\LocalLow\Weather Factory\Cultist Simulator

Save files may also be located by selecting "View Save File" from the options menu.

Save files are stored in a plain text JSON format, and can be opened in any text editor and altered. To alter a specific item, such as increasing the quantity, lengthening the timeout duration, or transforming it into another item type; one should search for the given "elementId" of the desired item and then alter the desired properties. For example to give yourself more funds you should search for "funds" in your save file and alter the "quantity" value to a higher number.

It is not currently known how to add entries to the table. If you wish to create cards it's suggested to create them by either increasing the quantity of a current stack of the desired card or by editing the "elementId" of another card on the table to match the desired card. Note that if you are transforming a card with a timer to a card without you will also need to alter the "lifetimeRemaining" value as well.