Well, the intent behind CataModder is to make it nice and easy to add new items to the game, so this is the right place! I’ll try to give you a full rundown of how it works here (probably other people would benefit from this, too):
Cataclysm’s item data is stored in files with the extension “.json”. They are located in the Cataclysm folder under “data/raw”.
These files just contain text that is formatted a certain way so the game can read it. You can even open the files in Notepad and see all the data. CataModder lets you open these files and edit this data without worrying about getting all the formatting right - it does that for you.
[hr]
To start, you run the program, then click “File->Open Raws”. The program will ask you to select a folder on your computer. Find the “Cataclysm/data/raw” folder I mentioned before. Select it and press okay.
CataModder loads all of the JSON files in that folder you selected. You can changed which of these files you’re looking at from the dropdown marked “File:” in the top-left (not to be confused with the File menu). It will probably say “bionics.json” to start. Guns are typically stored in the “items/ranged.json” file, so select that one. Note that there are a lot of other files, including others that start with “items/”, which contain the game’s other items (tools, armor, etc.), and you can edit these too using the same steps I give here.
Now, in box marked “Entries” on the left, you see a list of all the ranged items in the game. You’ll also see a lot of text fields and check boxes in the main part of the window. These display all of the information the game has to describe how a “gun” item works. When you select a different entry in the Entries box, you’ll see the info for that item instead.
There are a lot of numbers here, and even I don’t know exactly what they all do (though if you click on any of the numbers or boxes, you will see a short help text at the very bottom-left of the screen). Therefore, the best way to make a new gun is to start with a gun that’s already in the game that’s similar to the one you want to make.
For example, if I wanted to make a new pistol, I’d find a pistol (like, say, the Ruger Redhawk, listed in the Entries list as “ruger_redhawk”) and select it (you should see its information on the left). Then, press the “Duplicate” button at the bottom of the Entires box. This will create a brand new gun, and it will copy all of the information from the Ruger Redhawk into it. So now you have a new gun that’s identical to the Redhawk, but you can now change the name, description, and any of the other values you to make it into a brand new gun. I might change the name of mine to “BMac’s Awesome Pistol”. I’ll also change the “Id”, which is currently “ruger_redhawk1”, to something more relevant (like “bmac_pistol”). This text “bmac_pistol” will never appear in the game, but we will need to use it later to refer to our gun so the game knows which one we’re talking about.
Now click File->Save All to save your work. Next time you run the game, your item will be included.
[hr]
Unfortunately, if you stop here your new item will not actually spawn in the game, unless you give it to yourself with the Debug menu. This is because you need to add it to one of the lists the game uses to generate loot.
You can do this in CataModder by selecting the file “item_groups.json” in the File box. When you do this, you will now see a list of item groups in the entries box (it probably starts with “child_items”). Each of these “item groups” contains a list of items. When the game wants to create some loot, it looks at a particular one of these lists to choose which item to spawn. For example, in forests in Cataclysm, you often see sticks and rocks, and the occasional mushroom or berry. If you look at the list named “forest”, you can see these items listed.
So say I wanted my gun to spawn in houses. I see that there is an item group called “homeguns”, which are guns that can be sometimes found in houses (if you type “homeguns” in the box labeled “Quicksearch” above the Entries box, you can find it easily). I select that group, then press the “New” button on the right (not the button under the Entires box, which would create a new Item Group) to put a new item in that item group.
You’ll see that a new entry is added that says “null (0)”. You can edit this entry now using the two boxes below the Item Group list box. The one marked “Item Id” shows the id of the item you want to spawn. Note that this is not the name of your gun (“Ruger Redhawk”), but the id (“ruger_redhawk”). So I need to change it from “null” to my gun’s id (“bmac_pistol”). You’ll see another box that says “Frequency”. That controls how often your item will be used over other items in the list. If you leave it at zero, your item will never appear. I notice that most of the other pistols in the list have frequencies between 2 and 7. So I might give my gun a frequency of 5. If I gave it a frequency of 100, it would spawn very commonly wherever Cataclysm decided to spawn the “homeguns” loot group.
Now File->Save All again, and you just might find your gun in somebody’s house next time your generate a world.
This is a lot of text, I realize, and I apologize for the lack of pictures. Do ask away if you have any problems getting things to load or work!
