Starting with mods

Hello, I’m fairly new and I would like to know how to make a mod or just simply implement a new gun into the game.

I’ve already downloaded Git and Notepad++ just in case I need them.

I would like to know which steps I have to follow to create something from the scratch from items to buildings all the way to new mechanics. I’ve got a friend that could help me with the code if it’s too difficult.

(Sorry for my English if it’s not that good)

Thanks for your time and attention. :smiley:

To add or modify guns you’ll need to get to know the .json files. They’re in the json folder in the data folder in your Cataclysm folder. Those are just simple text editing, no need to hardcode or recompile or any of that fun stuff. Also check out this thread, it has lots of helpful information about modding.

Good Luck!

You’re in a good shape.

Start by cloning the repository, creating a branch to track upstream, and creating a new branch for your work.

To add a new gun to the game, you want to edit one of the files in data/json/items/guns/ - they’re sorted by ammo type.

To add a new gun to the game in a mod, you’ll want to take the JSON object that you added and add it to a .json file in the data/mods/ directory. Poke around the structure of the existing mods to get an idea how that works.

1 Like

Thanks for the info!

I’ve written down some specifications about the weapon but I’m sure I’m missing some key things. I would appreciate if you could mark out what’s missing. I’m trying to go with a bolt action sniper rifle, the M24. I would like to see it implemented in the mainline. :slight_smile:

“id”: “M24”,
“type”: “GUN”,
“reload_noise_volume”: 10,
“name”: “M24”,
“description”: “M24 being the model name assigned by the U.S. Army after adoption as their standard bolt action sniper rifle in 1988.The M24 is referred to as a ‘weapon system’ because it consists of not only a rifle, but also a detachable telescopic sight and other accessories.”,
“weight”: 5400,
“volume”: 10,
“price”: 350000,
“to_hit”: -1,
“bashing”: 12,
“material”: [ “steel”, “plastic” ],
“symbol”: “)”,
“color”: “blue”,
“ammo”: “762”,
“skill”: “rifle”,
“dispersion”: 80,
“durability”: 8,
“barrel_length”: 2,
“clip_size”: 5,
“valid_mod_locations”: [ [ “accessories”, 4 ], [ “barrel”, 1 ], [ “mechanism”, 4 ], [ “muzzle”, 1 ], [ “sights”, 1 ] ],
“magazines”: [ [“762Rx54”],[“762Rx54_clip”] ]
“flags”: [ “RELOAD_ONE” ]
Should this go into the 762R.json ?

After creating the weapon itself, do I have to implement it to the itemgroup.json as well so it can spawn naturally in the world?

On a different note, I’m a little bit confused with Git , I’ve forked the repository downloaded it through Git , made a branch called ‘M24’ but from this point on I’m lost. I don’t quite understand what I have to do with it nor how to modify the files I want.

762R.json is the file for guns using the 7.62x54mmR cartridge round - aka “Russian” 7.62. ANd 762.json is for guns using 7.62x39mm - Russian “short” round used in AK-47. You want 308.json, for NATO 7.62x51mm and .308 Winchester guns.

Ammo should be “308”, symbol should probably be “(”. Weight seems high - 5.4 kg for the basic rifle? Magazines should be [ [ “308”, [ “m14mag”, “m14smallmag” ] ] ] and you shouldn’t have a clip size because it uses box magazines, not an internal one (I think - M24s are a Remington 700 derivative, aren’t they?).

I’m surprised the stock isn’t a valid mod location.

I’d look at the existing savage_111f as a basic, really. But you’re 90% of the way there.

git is a little tricky, but I’ll give you 5 minute course:
git doesn’t care how you edit files. So just open up the files in notepad++ and type away.

when you are satisfied with your changes, tell git that you want to add those changes to your next commit
git add $FILENAME
where $FILENAME is the path relative to the base directory. So for your M24, that would data/json/items/gun/308.json. You can add multiple files with the same git add command, or at different times.
adding a file to a commit doesn’t really do anything except tell git that you’ll want to commit it later. You can keep editing it, and add the new changes to the existing commit by running git add again.

when you’re completely satisfied with your changes and have added all the changes you want to make to this commit, type
git commit
this will spawn an editor window, which gives you the option to describe your changes. when you’re done editing the description, git will commit the changes.

a git commit is a collection of changes grouped together. you can see the list of all the commits in your repository with
git log
which puts out something that looks like this:

commit 920230300571fcc8d716c4e8f1d976780ec5275f
Author: Mark Langsdorf <>
Date:   Wed Jul 25 13:10:28 2018 -0500

vehicle part descriptions: more scrolling fixes, always display if possible

limit the maximum amount of scroll based on the size of the w_msg, prevent
accumulation of scroll passed the maximum or minimum amount, and always
display the vehicle part descriptions if the w_msg isn't being used to
display something else.

commit 464ada3c482463c863f01874d66e1bb110ff39cf
Author: Mark Langsdorf <>
Date:   Wed Jul 25 11:45:20 2018 -0500

vehicle part descriptions: fix typos in engineering.json

which are the two most recent commits I’ve added. The weird long string of gibberish after commit is the commit ID, and you can use
git show $COMMIT_ID
to see the changes attached to any particular commit.

A bunch of commits are a branch - you’ve already created one, and each commit you make will be added to your working branch. You can change your working branch with
git checkout $BRANCH_NAME
which you might do when you’re working on two different sets of independent changes. For instance, that was the log from my more_veh_descriptions branch, but I’ve also got a blazemod_descriptions branch for some other changes I’ve made.

git push
sends your most recent set of commits up to your repository on github. You can then go to the C:DDA master repository on github and create a pull request (PR), which means you want the C:DDA maintainers to add your commits to the main project.
ie, this is my more_veh_descriptions branch on github:
and this is the PR to the main tree

and this is a PR that’s been merged into C:DDA

Anyway, I hope some of that helps. Feel free to ask more, or look up git tutorials on the web - there’s a lot of them, and they can go into more detail about what a commit is, what a branch is, and how pushing to a remote repository works.

Indeed my friend! I’ve changed some numbers and corrected the type of ammunition , also I’ve written it down in the 308.json.
The next questions I have , leaving Git aside, are: Do I have to implement the gun inside guns.json inside of itemgroups folder so it can be found in a world in Cata DDA, like being spawned inside a military base or a police office?
And, how do I test my weapon in my own game , for example I want to try and shoot some zombies with my M24 equipped with some accesories in a specific scenario as well as a test to find out if it’s balanced enough to be in the game?

And last but not least many thanks for all this support! I’m thrilled to have the possibility of modding this amazing game! I’ve got some ideas that could actually make it or at least I think they could be interesting! :smiley:

I’ll be taking a look at Git later this night! Again thanks very much , you are inspiring me a lot man!

Now it looks like this:
“id”: “M24”,
“type”: “GUN”,
“reload_noise_volume”: 10,
“name”: “M24”,
“description”: “M24 being the model name assigned by the U.S. Army after adoption as their standard bolt action sniper rifle in 1988.The M24 is referred to as a ‘weapon system’ because it consists of not only a rifle, but also a detachable telescopic sight and other accessories.”,
“weight”: 4500,
“volume”: 10,
“price”: 350000,
“to_hit”: -1,
“bashing”: 12,
“material”: [ “steel”, “plastic” ],
“symbol”: “(”,
“color”: “blue”,
“ammo”: “308”,
“skill”: “rifle”,
“dispersion”: 80,
“durability”: 9,
“barrel_length”: 2,
“valid_mod_locations”: [ [ “accessories”, 4 ], [ “barrel”, 1 ], [ “mechanism”, 4 ], [ “muzzle”, 1 ], [ “sights”, 1 ], [ “stock”, 1 ] ],
“magazines”: [ [ “308”, [ “m14mag”, “m14smallmag” ] ] ]
“flags”: [ “RELOAD_ONE” ]

Right, to make the gun spawn randomly in the world, you would need to add a line in data/json/itemgroups/gun.mod, inside guns_rifle_rare (or whatever other item group you want), like this:
[ "M24", 15 ],
I’d put it after the m14ebr entry. The first thing in the list is the id of the item, the second is the “weight” of the item - higher numbers make it more likely to spawn, lower numbers less, but the exact math is complicated and I’m not sure of it myself.
(BTW, this is a case where commits are useful: you wouldn’t want someone to get the new itemgroups definition before they got the M24 definition in 308.json, and you want anyone who has the M24 definition in 308.json to have the itemgroup definition change so the gun will randomly spawn in the game.)

To test your new gun, just start the game and load a save game or start a new PC. Since you didn’t make the M24 into a mod, it’s in the game’s data files and the game will just read it when starting a new game. You’ll get error messages if you screwed anything up. It happens. Just fix them and try again until you fix all the errors.

After you have valid json and can load/start a game, you can use the debug menu ( to wish for an M24, and immediately start rocking out with your new gun.

The mods of C:DDA are generally friendly about new content: I got the hide bags in with very little pushback, though the initial implementation was buggy. Same with vehicle descriptions. The closer you get to the game core, the more you’ll deal with strict review, but a lot of small stuff gets in pretty easily.

Okay, so now I’m getting to know a little bit more Git , I’m starting to understand how it works , at least the commands you’ve told me so after putting ‘git show’ it shows me all this , which I think it’s in order to then proceed towards the next step right?

Git console

commit 4b82d474b7d105c0326484a26a25f34e4e8b9177 (HEAD -> M24)
Author: Jownky
Date: Thu Jul 26 00:09:48 2018 +0200

Implementation of M24

diff --git a/data/json/itemgroups/guns.json b/data/json/itemgroups/guns.json
index 6abc773a58…1732cbb4c4 100644
— a/data/json/itemgroups/guns.json
+++ b/data/json/itemgroups/guns.json
@@ -167,6 +167,7 @@
[ “l_dsr_223”, 5 ],
[ “l_long_45”, 30 ],
[ “m14ebr”, 15 ],

  •     [ "M24", 15 ],
     [ "m4a1", 45 ],
     [ "m1903", 15 ],
     [ "m1918", 30 ],

diff --git a/data/json/items/gun/308.json b/data/json/items/gun/308.json
index 80312d6601…3fdd272f92 100644
— a/data/json/items/gun/308.json
+++ b/data/json/items/gun/308.json
@@ -232,5 +232,29 @@
“ammo”: “308”,
“ranged_damage”: -3,
“magazine_well”: 1

  • },
  • {
  •   "id": "M24",
  •   "type": "GUN",
  •   "reload_noise_volume": 9,
  •   "name": "M24",
  •   "name_plural": "M24",
  •   "description": "M24 being the model name assigned by the U.S. Army after adoption as their standard bolt action sniper rifle in 1988.The M24 is referred to as a 'weapon system' because it consists of not only a rifle, but also a detachable telescopic sight and other accessories.",
  •   "weight": 4500,

What I don’t get is why is this code like messed up , I mean like disorganized.

And this might be a silly question but ,exactly, where is the executable of Cataclysm DDA in the fork that I’ve downloaded so I can test the new weapon?

git was originally written by Linus Torvalds, of Linux kernel fame, for use by kernel developers. For historical reasons, Linux kernel developers send each other code changes in the form of unified diffs, which is what you are looking at.

Basically, each change that you make gets seperated out as a stanza. Each stanza has some line numbers to tell you where in the original file and the new file the change occurred, then some of the unchanged lines in the area of the change to provide context. Finally, each line that was deleted from the original file is reprinted with a - in front of it, and each new line is reprinted with a + in front of it.

When you get used to reading a unified diff, its a pretty tidy little format. The line numbers and context even allow you to guess where a change should go if you apply a commit to a different version of the original file. For instance, if you submit your M24 change for 308.json at the same time as I submit my AR-10 change, there’s a good chance that both diffs will apply without conflict. When there are dozens of people suggesting changes to the same set of files, the ability to easily apply multiple changes to the same file is really helpful. The diff format isn’t the only way to arrange that, but it works and Torvalds was familiar with it.

You just downloaded the raw code and data files.

You could compile the executable yourself, but doing that is a hassle. What I do on my Windows machine is download a recent compiled version and copy the executable into my git directory. Then you just double click on the executable and the game will start.

The next step after that is to set up the master repository as a remote repo, track its master branch, and periodically rebase your changes on top of it. But that’s even more advanced stuff and can wait.

So my only ways to compile my own version of CDDA according to ‘’ are:

  • Visual Studio Guide
  • MinGW Guide
  • Rough guide to building with only MSYS2

(Because my OS is Windows)

Which one is the best or the most efficient/easiest to do?

I can’t help you there. Like I wrote, I don’t compile on Windows. Compiling on Linux is a breeze, ao that’s where I do my code development.

I’d try Visual Studio if you have it, mingw otherwise.

I had another question in mind , I just wanted to know what are ‘tags’ exactly used for and what could be done with them in the long term?

Like for example I imagine that the one that I used on the M24 was [“RELOAD_ONE”], which I would imagine that , since it’s a bolt-action sniper rifle, It would reloas / use the bolt each time is shot with the weapon.
Is that right or is it at least near of what it is actually?

That’s actually a flag, not a tag, though I’m not 100% clear on the distinction.
Flags are supposed to be documented in doc/
RELOAD_ONE is the correct flag to use with manual action firearms.

Okay , I’ve compiled and followed all the needed steps, then got the executable which first when I entered and selected play now! it popped up an error due to me forgetting about a ‘,’ in the .json file , so I went and changed it, and I looked at the description and characteristics of the gun (In-Game) and it sowed that had a ‘fire-mode: semi-auto’ and the M24 doesn’t have that so i wanted to know how to modify that.

I think it’s almost ready , moving on, I think I’ll add a new gunmod for the stock named ‘Cheek Pad’ for the vast majority of sniper rifles and maybe some DMRs and some specific rifles as well. (Just to get practice coding with .json)