Skip to content

Guide to adding new content to CDDA for first time contributors

Mark Langsdorf edited this page Jun 11, 2019 · 7 revisions

This guide is meant to provide a quick, accessible overview of how to add specific features to CDDA. It's intended for people who want to add a thing, but don't know where to start. It mostly deals with changing the game's data files, aside from a bit on C++ programming.

Hey, what if CDDA had a

All of these can be added to the game by editing text files, because they're data files and most of CDDA's data is stored in a text file format called JSON.

A brief intro to JSON

CDDA's data files are stored in a text format called JSON. JSON looks complicated and intimidating when you first start, but it is just text. You can learn to read it and understand it, and then it isn't mysterious.

True story - the author of these guides has been a professional programmer for more than 20 years. When he first started dealing with JSON a couple of years ago, he thought it was complicated, mysterious, and intimidating. But he learned a bit about and now he can write JSON and even write guides telling other people about JSON.

Why should you care about JSON?

JSON defines that game's data. If you add JSON to the game that matches the game's expectations about what a bit of JSON should look like, you can add new content to the game.

You can edit JSON with a text editor, like notepad++ on Windows. Notepad++ has a syntax highlighting mode that understands JSON, so it will help highlight possible mistakes. On Linux, you can use any text editor that you prefer and most of them have JSON syntax modes.

JSON Overview

CDDA's data files are stored in data/json inside the game's folder. Each JSON file has content that looks something like this:

[
  {
    "id": "sig_40",
    "type": "GUN",
    "reload_noise_volume": 10,
    "name": "SIG Pro .40",
    "name_plural": "SIG Pro .40",
    "description": "Originally marketed as a lightweight and compact alternative to older SIG handguns, the Pro .40 is popular among European police forces.",
    "weight": 680,
    "volume": 2,
    "price": 75000,
    "to_hit": -2,
    "bashing": 8,
    "material": [ "steel", "plastic" ]
  }
]

JSON has 5 types of things in it:

  • lists are collections of other things, and are enclosed in brackets like this [ "thing", "other thing" ]. items in a list are separated by commas.
  • objects are also collections of other things, but each item in an object consists of a key and a value, like this "volume": 2, . Again, items are separated by commas, and the entire object is enclosed in braces likes this { "sample_object": "value" }
  • strings are words or sentences, and are always enclosed in quotes like this "string". the keys of an object are strings.
  • numbers are numbers, and aren't enclosed in quotes.
  • true and false are special words that are never enclosed in quotes. they're referred to as booleans.

So the sample bit of JSON above is a list with a single object in it. that object has several keys, some of which have string values, others have number values, and one has a list value and that list is made up of string values.

About file locations

All files locations referenced in these guides in the game's folder. So if your game is in C:\Users\bob\Cataclysm, then data/json/items/gun/50.json is at C:\Users\bob\Catacylsm\data\json\items\gun\50.json. They use the Linux style to separate folders so if you're on Windows, you'll need to convert the guide's "/" to Windows-style "\".

Also, although the game stores certain JSON objects in certain files or folders, it's the content of the objects that matter, not the location. Even though 7.62mm rifles are normally defined in data/json/items/gun/762,json, you can define one in data/json/skills.json and it will still work.

Continued in getting started

Read the section on getting started to learn how to make a copy of the CDDA code that you can edit.

Vanilla, CleverRaven mod, or external mod

When you have an idea for new content, you have three options for introducing it to the game:

  1. You can add it to default content in data/json ,
  2. or you can add it as an optional mod included in the CleverRaven repo in data/mods/ ,
  3. or you can add it as an optional mod hosted by a 3rd party.

This guides assumes that you are going to add default content, because that's what you probably should do.

Why not a mod?

A lot of stuff gets added to the game via mods. Adding content through mods makes a lot of sense when dealing with a commercial, closed source, game. But CDDA is open source, and welcomes contribution. Content that's in a mod gets updated haphazardly at best, and sometimes mods get broken when the mainline game changes underneath them. Default content is much more likely to get updated when the game changes.

You should add new content to a mod if, and only if, your new content wouldn't be the kind of thing that most players would want to see. If you want to add a new mission chain where the Old Guard rep sends you out to assassinate rival faction leaders (please add a mission chain like this!), that should be in mainline. If you want to add a total overhaul of the game around an alien invasion called Cataclysm: Enemy Unknown (please add a total overhaul of the game like this!), that content should be in a mod.

In general, there's very few good reasons to add content via a mod and lots of reasons not to.

CleverRaven or 3rd Party?

If your content isn't suitable for default content, it needs to be in a mod. Some mods are included in the CleverRaven repo, often for historical reasons. Other mods are not, and are hosted on some third party server. There are benefits and drawbacks to having a mod included in the CleverRaven repo, and benefits and drawbacks to having a 3rd party mod.

It is more work up front to get a mod included in CleverRaven. You have to deal with GitHub, your mod will be reviewed, and the maintainers may require changes before they'll accept your mod. However, mods that are included in the CleverRaven repo get more exposure, and there is slightly more effort made to make sure that changes to the CDDA C++ code don't break included mods.

3rd party mods are not controlled at all by the CleverRaven maintainers. If you have a mod that includes content that won't be accepted into CDDA, your only choice is have someone else host your mod. 3rd party mods are not reviewed by CleverRaven maintainers, which gives you more freedom. 3rd party mods are also not tested by developers, and code changes may break 3rd party mods. If there's a substantial change to the code, such as the recent change to 1 second turn, you may have to do a lot of work to get a 3rd party mod to function properly again.

Getting your content merged as part of default

The process for getting your new content merged goes like this:

  1. Fork and clone the repo, develop your new content, test it.
  2. Use the web linter to make sure your JSON content matches CDDA's JSON style.
  3. Commit your changes and push them to your repo.
  4. Go to https://github.com/CleverRaven/Cataclysm-DDA/pulls and open a new pull request. Read the instructions in the pull request and format your summary line correctly.
  5. Wait an hour or so, and then review your pull request. If there's a line toward the bottom that says "Some checks were not successful" then the automatic tests failed and your new content will not be added until the tests pass. There's 3 lines below that, for "continuous-integration/travis-ci/pr", "continuous-integration/appveyor/pr", and "gorgon-ghprb" and all 3 have a "Details" link next to them. Find the tests that is failing, click on the "Details" link, and read every single word and link on that page until you find out why your test is failing. Then fix it and push a new set of changes.
  6. Repeat step 5 until your PR has a green check mark and a "All checks have passed" line.
  7. Wait some more. Possibly for 3-4 days.
  8. At some point, someone who isn't a first time contributor will review your PR and request that you make changes. Make them. There's a slight chance that the reviewer is requesting a nonsense change, and if so, defend your content, but most likely they know more than you do and you should make the requested changes.
  9. Repeat steps 7 and 8 until no one is requesting any changes and at least a week has passed since you last updated.
  10. At this point - when your PR passes all tests, you've made all the requested changes, and you've waited at a week - and not sooner, if your PR hasn't been merged, then you should get on the CDDA discord and ask what needs to be done to get your PR merged.
  11. At some point, your PR will be merged. Bask in the glory of contributing to CDDA, and then get started on your next PR.

I may have made the process of submitting a PR sound difficult, but the CDDA community is friendly and welcoming to new content. There's just a process that you need to go through, because there are a lot more people who want to add new content than there are people who can review content for inclusion. Be patient, ask for advice, and soon you'll have a "Great contributor" tag after your name on Discourse.

Contributors, developers, maintainers, and Kevin

CDDA is an open source game with an active development community. That means anyone can contribute, and this guide was written to encourage more people to contribute and help them do so. But like any community, there are people with more knowledge of the community.

Developers are contributors who successfully contributed multiple times. Because of their successful record of contribution, they have a little more influence on the direction of the game. They also have a little more knowledge of the game and its internals, and can help answer questions from new contributors. CDDA welcomes contributions, and becoming a developer is a matter of contributing successfully, being willing to help, and advertising yourself as a developer. The author of this guide, for instance, is just a developer who decided that one of his contributions needed to be a guide for new contributors.

Maintainers are some selected, veteran developers who have demonstrated good judgment and can merge PRs. They are Members of the CleverRaven team. If a maintainer replies to highlight technical issues with your submission or requests changes pay extra close attention as these concerns are very likely blocking it from being included.

Please respect that the maintainers oversee all contributions so they will not always have the time to reply in full detail or provide step-by-step instructions. Even when you want it, you may not get extensive feedback. Please accept the feedback you get in good faith. If you need to defend your concept or design, do it politely and be prepared to lose with good grace. Even if you are convinced that you are right and a maintainer is wrong, excessive arguing will not get your changes accepted. It's better to make a change that you're not fond of and move on.

Kevin (aka KevinGranade or ActuallyThatKevin) is the CleverRaven project lead and CDDA maintainer. He has final say over what does and does not go into CDDA. He has a reputation for being hard to work with, but he also does a lot of fairly thankless work in the background to make sure that CDDA is a fun, high-quality game. If Kevin comments on your PR or requests changes, read what he wrote and try to do it. If you take that approach, you will rarely have too much trouble. I am not saying that you will always agree with Kevin's decisions or the changes he wants you to make - I've had to make changes I didn't like to get a PR accepted - but it's better to contribute something that you mostly like than to contribute nothing.

Getting your content merged as mod in the CleverRaven repo

Mods are very similar to default content, and the process of submitting them is similar. The process of writing them is somewhat different:

  1. Mod files aren't in data/json/ but in data/mods/. Each mod has its own folder, and then any additional JSON is in that folder, however you want to organize it.
  2. Mods are required to have a modinfo.json file.

3rd Party Mods

  1. 3rd party mods need to have a modinfo.json file in the mod's directory.
  2. You can organize your mod's JSON however you like.
  3. 3rd party mods are by definition outside of CleverRaven. I'd recommend using GitHub or GitLab for hosting, because grabbing a mod from one of those circumstances is less scary than downloading some random zipfile off a dropbox. Beyond that, you're on your own.

Additional Info

The CDDA developer's wiki (the site you're reading this at) has some more files. Some of these are old and may be of questionable utility, but they might answer a question you have.

Final Thoughts

I hope this guide helps. Please PM mlangsdorf (Mark Langsdorf) on the CDDA Discord, discourse.cataclysmdda.org, or https://www.reddit.com/r/cataclysmdda/ (I'm mlangsdorf just about everywhere) if you have questions or need some help.

Clone this wiki locally
You can’t perform that action at this time.