Guide to modding the Cataclysm! (WIP)

–This thread is meant to give a (hopefully) good reference to those who wish the mod C:DDA. I’m still learn a lot myself, so don’t expect it to be perfect, but I’ve learned quite a lot of things so far. There is a lot to say, so dropdown menus are very much needed.
–Hopefully you can easily navigate the dropdown menus to better find out how to make weapons, armor, food and more! And I’ll update this part of the thread as I learn more of how the game works.

BASICS and BEGINNING

You can choose to make a backup of the entire game itself, but that’s only necessary if you alter the .json of the game itself. In this tutorial we won’t actually be altering the base code at any point, just what is in your mod folder.

Making your mod folder!

You probably want your mod to be in it’s own folder, right? Go to the game directory > data > mods. Copy the modinfo.json from any of the existing mod folders and add it inside your own. Name the folder whatever your mod is going to be called (I’m not certain but an _ might be needed if you have a space). Inside modinfo.json (the one in your own mod folder) you’ll find something along the lines of

THIS

[
{
“type”: “MOD_INFO”,
“ident”: “Red’s Odd Additions”,
“name”: “Red’s Odd Additions”,
“authors”: [ “redxlaser15” ],
“description”: “Adds some rather odd items, creatures, and such to the game.”,
“category”: “misc”,
“dependencies”: [ “dda” ],
“obsolete”: false
}
]

WARNING: DO NOT CHANGE THE “type”: “MOD_INFO”! KEEP QUOTATION MARKS AND SUCH!
Remember when editing this stuff remember to only edit the stuff inside the second quotation marks. For example “description”: “WHAT YOU EDIT”
Ident is used to identify mods in the modlist for a save file. Try to make it simple, or possibly just the name of you mod. Change author to your name (Or I guess whatever you want). Put inside description a description of your mod. I can’ manage to get categories to work, but it won’t create too big of a problem. Make sure obsolete is false, and that you have “dda” as a dependency.

Now you have your own mod folder!

It is highly recommended to make seperate .json folders inside your mod folder for different categories. For example: melee.json could be for melee weapons ranged.json could be for ranged weapons.
Each .json always needs to start with [ and ] at the end. You’ll put your different items, armor, and various other things inside { }. Each time you make a seperate item (or something similar) you need to add a different { }. Ensure you add a , behind the previous } for the game to properly recognize that this is a different thing!

Remember to select your mod whenever you begin a new world! And as you go only, don’t be surprised if plenty of DEBUG errors come along, it’s all part of the learning process!
It is quite possible that at some point you might new a new world to avoid incompatibilities with your mod and what currently exist in the game. Example: You can an item in the world and you change the .json ID to something else. That means the current item will be bugged and useless. That isn’t strictly game-breaking, but it’ll be weird.

For the game to recognize new changes to the code you need to exit the world you are currently in and then go right back in. You don’t need to exit all the way out of the game!

Always remember to TEST OUT YOUR CODE after each little bit you alter in the .json and try your best to avoid typos! If you have an error when entering the world the DEBUG thing will pop up, it’s usually pretty useful and can really help to point out little typos and such.

Remember, just because you are learning from this DOES NOT mean you shouldn’t use the .json from the game itself to use as a reference too! Some things can be a bit hard to find, but it is in there somewhere!

It is a good idea to use the DEBUG menu (I think it you need to set the keybind in settings) ingame to help you test out items and such in the game.

Most likely you’ll typically look at .json that you can locate in the files at Directory > data > json to reference ingame code and (to access your mod like before) Directory > data > mods ‘your mod’
I think that’s it for the overall basics of this whole thing. If I miss something I’ll add it ASAP :blush:



Personally, I feel like making a new item is the best first step you can ever make. It’s (in my opinion) the easiest thing you can do when you are starting off. So here we go!

MAKING ITEMS

I’ll use the reference I first used when making an item. We’ll simplify it down so it’s no weaponised for now, however. Directory > data > json > items> melee.json

You’ll see at the very top inside the .json the item Mjolnir. I recommend copying all the info from mjolnir to a .json in your mod folder rather than doing it from scratch. It’s easier and reduces typos. Remember, the info for Mjolnir goes from the original { to the }, at the end. DO NOT INCLUDE THE COMMA! That will break it if you have no other item under it.

For now, let’s not mess around with the item type. Keep it as GENERIC.

The id is super important. That’s what the files use to recognize the item and help you use the item again for things like crafting and such. Don’t put spaces within the id, I believe that will mess it up. Instead use _ for spaces. Always try to keep it simple and memorable; The id of Mjolnir is literally mjolnir. I’m not certain, but I think you need to have the id all lower cases. I’ve always made the lower cases since I’ve never seen any ids uppercase. You can try it yourself if you want to.

The name is simple, just name your item what you want. Unlike the id, this can include caps and spaces (this is obvious if you are actually referencing mjolnir. But just in case).

Replace the stuff inside the description with whatever you want. I believe you can make it as long as you desire.

Weight is how heavy the item is. I have trouble properly balancing weight to my desire, and I highly recommend you try out different amounts for your item till you get roughly what you want. MAKING AND ITEM 0 WEIGHT BREAKS IT!

Color is the color of the item as it lays on the ground. Some color options you may want are not available (such as orange :expressionless:). Try using a reference and/or experiment to see what works.

Symbol is, of course, the symbol of the item as it lays on the ground. DO NOT USE THIS SYMBOL: \ You can use the other version like this, / but otherwise it breaks. (I learned the hard way).

If a tileset is used on this item (which is unlikely for now unless you make your own), then neither color nor symbol is relevant.

Material is what the item is made out of. This defines its resistances and such to various things. Like bashing damage, cutting damage, fire damage, and so on. You can find all the different types of materials inside of materials.json (Directory > data > json). Later on I’ll teach you how to make your own materials! Remember that the id of the material you are looking at is what you put inside [ “Right here!” ] If you want something to be made out of multiple materials, add a comma after each quote inside the [ ] and use more quotations. (Mjolnir uses [ “wood”, “steel” ]

Techniques we won’t mess around with for now, but in short these are the melee abilities that can trigger when using the item in combat. For now, just delete it all. ( “techniques”: [“BRUTAL”, “WIDE”], )

Flags define various different attributes for different things. Remember that flags need to be in all caps. Mjolnir is NONCONDUCTIVE, which means that it does not conduct electricity. Let’s keep that for now. There are a lot of different kinds of flags. Some flags only work on certain things. (You can’t make a flag for a monster work for an item.) I don’t know the whole list of various flags, but I recommend searching around the .json for different ones to experiment which what does what. Let’s keep that flag for now.

Volume is how much space it takes up in your inventory. 1 volume is equal to 0.25 inventory space I believe. I’m not certain how to lower it further down than that (0.01 volume).

Bashing is damage related. Let’s get rid of that for now.

Price is how expensive and item is. For it to be one dollar you need the price to be set at 100. Setting the price of an item to 1 means it is worth one cent.

Qualities relates to what sort of abilities it has for use in crafting. Mjolnir has hammering 1 (similar to a basic rock). Whether you change that or not is up to you. I’ll bring this a bit more in depth later

Remember that there CANNOT be a comma right before the ending } otherwise it will break!

There you go! The basics of how to create an item. I encourage you to play around with various settings and such and use references from other objects in .json to learn what you can and can’t do!



MAKING MELEE WEAPONS

This is effectively a continuation of MAKING ITEMS but focuses around creating an actual (melee) weapon itself.

Now, let’s take another look at Mjolnir! ( data > json > melee.json ) You can either read along, alter the game’s direct code (unrecommended), continue to alter the item you made in MAKING ITEMS, or copy and past the stats for Mjolnir into your own mod folder.
You’ll see that it has bashing: 9999, which is a lot. The damage you put on the weapon in the json is directly and exactly what it is ingame. So if you get Mjolnir ingame it will deal 9999 bashing. Cutting damage works just the same. if you replace ‘bashing’ with ‘cutting’ on mjonir’s stats, it would instead deal 9999 cutting damage! Remember that you can easily do both at the same time!

You may be wondering: How do I deal piercing damage? It’s a bit different for that. You need to use the flag STAB, ( Like this: “flags”: [“STAB”] ) which replaces cutting damage with piercing. In the json you’ll still use the term ‘cutting,’ but ingame that will be replaced with piercing damage instead.

Techniques can be pretty important: it defines the ‘special abilities’ you can use with your weapon. Mjolnir has the techniques BRUTAL and WIDE. Ingame you can see better details of what each ability does. You can find them all in data > json > techniques.json. I’m still learning the details of how to change and make techniques are sadly, but this will at least show you the options!

Weight can be important when making weapons, as it defines how long it takes to swing said weapon; The heavier the weapon, the slower the weapon.
Whether the item is conductive or not can be pretty important for a weapon (and armor). If a weapon is conductive, you could get shocked when attacking with it. Be sure to use the flag “NONCONDUCTIVE” if you don’t want to get zapped!

There are other flags that are weapon specific, such as REACH_ATTACK or SHEATH_SWORD.



If i’m not mistaken, what you refer to as “type” is generally called Syntax.

Making a full copy of your entire directory probably isn’t necessary. In fact, unless you’re modifying vanilla JSON files, you don’t need to backup anything.

Ident is used to identify mods in the modlist for a save file. Making it something simple and easy to remember is a very good idea.

A good way to delete bugged items ingame is to throw them somewhere on the ground and debug spawn an amoebic mold on top. It’ll destroy the item instantly.

Category is just what the mod is filed under in the modlist you can pick from when you make a new world. Make it one of the categories in the list and it should work fine.

–Well, for a just-in-case scenario, I prefer a whole new directory. But in retrospect I guess you have a good point.
–Ah, I see. I’m pretty sure that’s one of the things I see when the game is loading up; when it goes the list of mods it mentions mine at the bottom
–Huh, that’s a good idea to use a amoebic mold for that. It might be a good idea to kill it afterwards one way or another tho…
–I tried that with the category. It didn’t seem like it felt like working for me :frowning: I guess it might have been a typo, but I couldn’t figure out how else to get it to work. I want it in the MISC category BTW.

It’s not really necessary to make a copy of the entire game directory before doing anything. C:DDA is already distributed via git, which means it’s under revision control. You can delete all the files you want and then reset everything with git reset --hard HEAD. Or reset to a particular commit instead of HEAD if you have a bunch of changes already committed.

Good practice is create a local branch for you own changes, and then add and commit your changes periodically when you get things working. ie,

git checkout -b milk_from_sheep master
edit data/json/monsters.json
git add data/json/monsters.json
git commit -m “Sheep can be tamed with cattle fodder and produce 0.5L milk/day”
edit data/json/monsters.json
git add data/json/monsters.json
git commit -m “Horses can be tamed with cattle fodder but don’t produce any milk”

At this point, I tested my changes, discovered that giving horses 0 milk ammo caused the game to crash, and reverted that change with git reset.*

  • Not my actual workflow, but a good example for newbies.

When you’re just starting out Github is probably overkill for a JSON mod. Not a bad idea to transfer over if your mod gets popular/really big though.

Ident is basically only important when you’re adding a new mod to an existing save. So… not very often. And not for long.

The category has to be in lowercase with underscores for spaces, e.g:
"category": "items",
or
"category": "misc_additions",
or
"category": "vehicles",

I’d say that even if you don’t expect to have a popular mod, getting a github account is free and forking the repository is a very short process, and then you’re set up to be able to mainline your mod if you decide that’s what you want to do. While if you just clone the main repository and then decide to submit parts of your mod, it is slightly more tricky to set up the branches and remotes properly.

–It somewhat amuses me that this was mostly meant to teach others and I’m learning from it too :smiley:
–How do I delete or replace previous no-longer-needed ‘junk’ from Github though? I accidently added stuff to it incorrectly (Hello World only helped so much) and I want it to go away since it is useless and clogging ‘master’ up.
–Wow, I’ve already made 10 edits so far! That’s no too surprising I guess.

Is there a place where I can find a description for each flag and tag that items can have as well as the math behind the firearm durability stat?

Flags are mostly documented in doc/JSON_FLAGS.md (https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/JSON_FLAGS.md). Fields/tags are somewhat described in doc/JSON_INFO.md (https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/JSON_INFO.md), though some things (martial arts, monsters, etc) have their own .md files.

I think the gun durability stat is documented in doc/GAME_BALANCE.md (https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/GAME_BALANCE.md) under Range Weapons: Reliability - at least, guns have a durability stat that seems to be scaled to the values described in that section and they don’t have a Reliability stat.

clearing stuff out of github isn’t hard, but it’s not trivial either. I really recommend getting a good book on git (the O’Reilly book is what I used) but I can walk you through the basics. I’m not saying this is the only way to do things, either - this is just the way I would handle it and other people might have different/better ways.

Your local git repository is basically a collection of commits (specific changes to specific files) and branches (collections of sequential set of commits). What you want to do is remove a bunch of commits from the master branch and then do git push --force to make the github copy of the repository match your local branch.

First, best development practice: don’t develop on your master branch. Checkout a new branch when you start developing or at least, before you commit a set of changes.

So here’s what I would do:

  • from your current master branch, do “git checkout -b my_mod” - replace my_mod with whatever you want to name the branch. This will preserve a copy of your current branch in a new branch called my_mod.
  • then do “git checkout master” to return your repository to your master branch.
  • then do “get reset --hard origin/master” which will reset your current (ie, master) branch to match the commit history of github repository.[1] This will clear out all your changes.
  • then do “git checkout my_mod” to return your repository to your my_mod branch.
  • then do “git rebase -i master” which will open up an interactive rebase session. you’ll see all the commits in the my_mod branch, the most recent one at top, and ending just before the first shared commit with your master branch. There are instructions at the bottom, but you’ll just want to delete the lines for the commits you don’t want. Git will then reapply the remaining commits, starting from the top of the master branch.
  • depending on what commits you removed, git may not be able to automatically apply the commits (ie, if you had commits a13, b24, and c35 that all touch the same lines in data/json/items.json and you don’t re-apply b24, then c35 will want to change a line that doesn’t match the result a13). Sorting out a broken rebase is even more complicated, but basically you want to use “git status” to see which files aren’t working, edit them until they’re right, and then use “git add” and “git rebase --continue” to effectively commit the change and continue.[2]

if all goes well, when the rebase is done, you’ll have a new my_mod branch that only contains the commits you want.

[1] if you’ve already pushed your bad master branch to github, you’ll need to git a clean copy from somewhere else. assuming you don’t already have Kevin’s repository as a remote, you’ll do “git remote add upstream https://github.com/CleverRaven/Cataclysm-DDA.git” then “git fetch upstream” then “git checkout -b upstream-master upstream/master” - which ends up creating a local branch called upstream-master which matches Kevin Granade’s github branch. Then do “git checkout master” to return to your local master branch, “git reset --hard upstream-master” to reset your master to match his, and “git push --force” to make your github verison match your local version.

[2] If you have access to git-gui or a similar smart commit tool, one trick I like to use when I have a messed up series of commits is to rebase -i against a reference point (like the master branch), squash/fixup all my commits into a single commit, open up git-gui, amend the last commit, remove all my changes from it so my working directory contains the net changes between the final result and the reference point, and then start adding the changes in logical chunks, each as a separate commit. But that’s a little advanced so please get a good book or something!

GitKraken is a decent (also free) choice for newbies if the commandline/terminal intimidates you, it has a pretty intuitive design and can let you undo changes with the click of a button.

–So um, where exactly do you find this ‘git checkout -b my_mod’ and so on? I don’t see anything like that anywhere. Neither do I see any ‘checkout master,’ nor do I understand what you mean under the [1]
–I really don’t get any of this at all. Here is what I see:

So what do I do on this page? Or is it irrelevant?
–Should we just make a new thread relating to Github instead of going on here? It might be a better idea.

You run those commands from your terminal/commandline

Where is that? I don’t see a button for that anywhere! Also, let’s continue this conversion here:

So there’s a huge difference in our workflows and use of github, and I think I accidentally gave you good information that you can’t really use.

I’m going to move over to the other thread to continue this, but the short version is that I run git from the command line as Linus intended, and I gave you instructions assuming you did to. I can’t figure out how to get github to allow you to rebase through the web interface, so you may be stuck with your commit history.

(assuming) He only needs his json files so deleting his repository and starting over wont be an issue provided he backs those up. provided he hasnt touched the code.

So it just occurred to me while looking at the Reds-Odds-Additions repository that I may have been answering a much more advanced question than was asked.

Hey, redxlaser15 - were you asking how you can delete a specific entry from the json files in your repository? For instance, did you decide that the giant axe was not to your liking and you want to remove it? Because if so, I gave you the wrong answer.

If you just want to remove stuff from your existing files, go to your repository page under github, hit the “code” button, navigate to the file in question, hit the little pencil icon to open an editor session, make your changes, and commit them. I just removed the giant axe from my fork of your repository (https://github.com/mlangsdorf/Reds-Odd-Additions) and you can do that as much as you want to add or remove json entries that aren’t working for you.

Most of my “mod” ideas involve variants of starting scenarios. For instance, the School start only allows janitors, even though there are a ton of starting characters it would make sense for – Otaku, Punk, Rude Boy, etc.

That’s pretty easy to mod in (I think). You create a new scenario with the same ID, use the copy-from instruction to get all the old data, and extend the professions line.

ie,
{
“ident”: “schools_out”,
“copy_from”: “schools_out”,
“extend”: { “professions”: [“otaku”, “rude_boy”, “punk”] }
}

the mod more_classes_and_scenarios already does this to several scenarios, so it’s a good place to start.

(also, the school start allows a lot of professions by default, and the janitor profession isn’t one of them, because it’s a profession added by the more_classes_and_scenarios mod.)

Where are all the electronics item like antenna, power converter, amplifier etc, defined ? I’d like to add a new electronics component but I can’t find the relevant json file U_U