-
Notifications
You must be signed in to change notification settings - Fork 4.2k
Guide to adding new content to CDDA for first time contributors
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.
If you're the kind of person who prefers videos to text, contributor TheMurderUnicorn has a short series of videos on contributing.
- new way to craft an item (a recipe)!
- new item!
- new location!
- better NPC dialogue!
- new NPC!
- new mission or quest!
- new monster!
- new morale effect!
- new vehicle part!
- new vehicle!
- new starting profession!
- new martial art!
- new sprite!
- an item or monster that was almost the same as an existing item or monster (copy-from and abstracts)
- a different version of an existing item or monster (copy-from and modifying existing things)
- new anything else!
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.
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 this guide 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.
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. Using notepad is not recommended because it can add hidden characters to your file that will cause CDDA to fail to load but are extremely hard for people to diagnose because they won't be able to see the hidden characters. On Linux, you can use any text editor that you prefer and most of them have JSON syntax modes.
You can also use conventional text search tools to find things in the JSON directories. notepad++ has a recursive directory search feature that is extremely useful, as do most Linux text editors. You can also use git (see the section on "Getting Started" below, for more information) to do text searches, using the standard git grep command, or the text search feature of your git client. In a pinch, you can also use github.com to search the JSON directories, but github sometimes doesn't search large files so it isn't 100% reliable.
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.
-
trueandfalseare 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.
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.
The short version is that you need to set up a github account and create your own copy of the CDDA data files. AMurkin's illustrated guide will tell you how to do that using Github Desktop, but you should still read the rest of the getting started page for more information.
I wrote this guide to be a overview and introduction to adding content to CDDA. It's not exhaustive and sometimes it's incomplete or out of date. Sometimes you're going to want to do something that this guide doesn't cover and you're not going to know what to do. Here are some suggestions for what to do when you're stuck.
When you have an idea for new content, you have three options for introducing it to the game:
- You can add it to default content in
data/json, - or you can add it as an optional mod included in the CleverRaven repo in
data/mods/, - 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.
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: Dark Skies Above (please add another 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.
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.
The process for getting your new content merged goes like this:
- Fork and clone the repo, develop your new content, test it.
- Use the web linter to make sure your JSON content matches CDDA's JSON style. See below for more on linting.
- Commit your changes and push them to your repo.
- 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.
- 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.
- Repeat step 5 until your PR has a green check mark and a "All checks have passed" line.
- Wait some more. Possibly for 3-4 days.
- 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.
- Repeat steps 7 and 8 until no one is requesting any changes and at least a week has passed since you last updated.
- 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 yet, don't worry! Someone will eventually get to it. If it hasn't been merged for awhile and no one has gotten to it, and you are worried, you can join the discord and ask about it.
- 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.
linting is a programmer's term for checking a program for syntax and format errors. Basically, in order to make it easier to review JSON changes to C:DDA, the developers require that all JSON submissions conform to a specific standard format, and then provide a tool (the linter) so that you can easily reformat your submissions to that standard format.
After you've tested your changes and are happy with them, you need to run them the linter to get all the tabs and spaces in correct places. There are two ways to do this:
- If you're modestly familiar with compilers and have a command line, you can run make style-json in the CDDA root directory of your local repo and that will lint all the JSON files, more information about the formatting tool and it's usage can be found in JSON_STYLE.md.
- Otherwise, you can copy the text of any JSON files you changed, one at a time, into the web linter, hit the lint button, and copy the changed text back into the file. Then commit and submit the file after it has been linted.
As a trivial example, this is working JSON
[ { "test": "example" } ]but it isn't formatted correctly, and after running it through the linter, it looks like this:
[
{
"test": "example"
}
]It's functionally the same JSON, but the linted version looks like all the other JSON in CDDA's data files, and the first version does not.
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.
Mods are very similar to default content, and the process of submitting them is similar. The process of writing them is somewhat different:
- Mod files aren't in
data/json/but indata/mods/. Each mod has its own folder, and then any additional JSON is in that folder, however you want to organize it. - Mods are required to have a
modinfo.jsonfile.
- 3rd party mods need to have a
modinfo.jsonfile in the mod's directory. - You can organize your mod's JSON however you like.
- 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.
Mod curators are contributors who make an effort to maintain a mod. That means that they commit to making an effort to keep the mod up to date and fix any bugs introduced by changes in other parts of the game. For mods that are under active development, the maintainer is also usually the lead contributor.
Mod curators are usually not members of the CleverRaven team, and usually do not have merge permissions. Acknowledged mod curators usually get a great deal of leeway in their decisions regarding the content of their mods, and as long as their content changes do not cause the game to fail to compile or run, those content changes are accepted for the mod, even if similar content would be rejected for the vanilla game.
Mod curators used to called mod maintainers, but calling them curators helps distinguish the role from normal maintainers.
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.
- Developer's FAQ
- Container information
- Guidelines for armor balance, weapon balance, and overall game balance
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.
Minor note: the 'dorf' at the end of my username is part of my actual last name, and not some cutesy spelling of "dwarf". If you ask me a question and claim to have read this guide but refer to me as 'mlangs', then you're either lying because you didn't read this note, or you're trying to offend me, and I will not respond nicely to you. Shortening my username is one of my pet peeves, as is claiming to have read this guide when you've only glanced at it and are thus asking me a question covered by the guide and wasting my time. Just a friendly notice!
Back to the Guide for first time contributors