Cataclysm Code Guide

It is becoming abundantly clear that most of us, regardless of our programming abilities, want to mod this game into our personal wonderlands.

Basically, this is going to be a “go here to do x” type of guide with each topic, hopefully covering everything from simple JSON editing to the parts of cataclysm that make fully grown men cry. I am going to rely on my fellow, current and former, cata-modders to help make this a near complete guide one day.

Each spoiler of a topic also may, or may not, have a set of FAQs at the very top. These are meant for newer coders and can generally be ignored by people with any coding experience.


*This will not make this item naturally spawn. That will be explained later.
*This is one of the few things that can be done to precompiled code (the stable/experimental releases)
*Custom effects are not created here. They are created elsewhere.

All items can be made available in game by adding a new entry to a relevant JSON. The JSONs can be found in your data/raw/item folder. To add a new item, copy any entry from the middle of the JSON you think it fits best in, paste it just below said entry, and edit the values to fit your new item. The only things you need to watch out for is making sure no other item has the same “id” value (and that your item has no spaces in its id), you never delete any quotes or commas, and that you replace numbers with numbers and letter sentences with sentences.

Some items also have various flags. Several of these exist for each item type, and they give the item special abilities. In the interest of space, I won’t be posting all the flags here, but they can all be found on items in the JSON, and they all have rather descriptive names. Ask me if you aren’t sure about any. Multiple flags can be added by simply placing a comma between each bracketed flag ([FLAG1], [FLAG2]).

[spoiler=“Adding new recipes”]

*This is another thing that can work on an already built game (stable/experimental build download).

Recipes can be added by adding a new entry to the recipe.json found in the data/raw folder. To do this, copy an entry from the middle (preferably one using multiple tools and components), and paste a copy of it below said entry.

place the text in the quotes beside “result” with the id of the item you want to make (remember, no spaces). The id can be the id of any item in any json in the data/raw/items folder.

Add this, without the brackets, to the line below the id if you want it to be uncraftable only: ["id_suffix": "uncraft",].

Category is the tab under which it is shown in the crafting menu (a list of them is at the top of the JSON).

skill_used should be the id of the primary skill (skill ids can be found in the skills.json in the data/raw folder.

requires_skills is the id of the secondary skill(s) also required, and the relevant level. (format is as follows: [ [ "SecondarySkill1id", Secondaryskill1Level], ["SecondarySkill2id", Secondaryskill2Level] ] ).

difficulty is the minimum level in the primary skill needed to attempt the recipe

time is the number of cataclysm turns needed to finish crafting it (be careful with making this too large)

reversible should be set to true if the recipe can be undone to get back the components. Set it to false if you can’t.

autolearn should be set to true if you want your character to learn it when they get the relevant levels. Set it to false if you don’t (note, it is highly recommended to add a way to learn it if you do this)

book_learn should be set with the id of the book you want to learn the recipe from while reading, as well as the skill needed to learn it (format is as follows:

[[ "possibleBook1", PrimarySkillNeededForBook1 ], [ "possibleBook2", PrimarySkillNeededForBook2 ] ]).
The ids can be found in the books.json in data/raw. This is recommended if auto_learn is set to false.

Tools should be the ids of all the tools required for the recipe followed by the charge used in said recipe (tools ids can be found in data/raw/items/tools.json). Recipes have a list of “pick one from this list” inside of their required tools list. Only 1 of these “pick one from this list” for each tool category is needed to complete the recipe. The format probably explains this better.
The format is as follows:

[ [ [ "toolType1Option1Id", toolType1Option1ChargesUsed ], [ "toolType1Option2Id", toolType1Option2ChargesUsed ], [ "toolType1Option3Id", toolType1Option3ChargesUsed ] ], [ [ "toolType2Option1Id", toolType2Option1ChargesUsed ], [ "toolType2Option2Id", toolType2Option2ChargesUsed ], [ "toolType2Option3Id", toolType2Option3ChargesUsed ] ] ],

Note, be careful when adding a charge cost to things like a wrench or tools like such.

Components are the items used up in the recipe. The components can be anything found in any of the jsons inside of the data/raw/items folder. This uses a format similar to tools and with a similar design.
Format is as follows:

[ [ ["item1Option1id", item1Option1ChargesUsed], ["item1Option2id", item1Option2ChargesUsed] ], [ ["item2Option1id", item2Option1ChargesUsed], ["item2Option2id", item2Option2ChargesUsed] ], [ ["item3Option1id", item3Option1ChargesUsed], ["item3Option2id", item3Option2ChargesUsed] ] ]


More will be added




Just a heads up, but there are some (now) useful files in the cod_doc folder concerning modding, including something that gives a useful interpretation of basically every “field” for every .json file in the game (

I was not aware of that. However, considering how many people ask about how to add various things, creating a consolidated page would likely be helpful.