New Contributors Guide Troubleshooting

I wrote the guide to be an overview and introduction. It doesn't cover every type of content in CDDA and it doesn't cover most types of content in a lot of detail. A lot of time, you're going to want to something, and not have a clear and definite answer on how to do it, and feel like you're stuck until you get an answer. Here's are some steps to take to get that answer:

1. Read: This guide isn't comprehensive, but it does have a lot of valuable information. Sometimes the answer to your question is where you think it should be, but it is somewhere else in the guide, or it is where you think it should be, but you skimmed over it thinking you already knew how to do something. If you're stuck, reread the guide. Read the docs it links to. Read carefully and thoroughly.
2. Examine: The existing JSON data files contain a huge amount of information. Look through them and see if there's something similar to what you want to do that is already in the game, and see how that thing is done and if you can do something similar.
3. Experiment: This is probably the most important step to trying to get an answer. Take your best guess and try something. Write some JSON, load up a test world, and see if it works. If you get an error message, read the error message thoroughly and try to figure out how to solve it. If you don't get an error message and the game loads but you didn't achieve what you wanted, try to figure out why. There is no cost except your time and patience to experimenting. No one else will ever know, and it's impossible to so badly mess up the JSON of the data files that the game itself will be damaged. If your experiment doesn't work at all, just clear out all your changes (git makes this easy to do) and your game will be playable again.
4. Try again: If your experiments didn't work, repeat steps 1-3 a couple of times. Maybe something in how your experiments failed will give you some insight about what something you read really meant, or point you toward something you overlooked in the game's data files.
5. Explain it to a rubber duck: This is a well known programmers' technique. Imagine a rubber duck that can solve your problem if you can only explain it in detail to the duck. Then explain your problem to the rubber duck in detail: what you are trying to achieve, what you have done, what isn't working, and the things you have tried to solve the problem. Often, the act of formalizing your goal and experiments so you can explain them to the rubber duck will lead to an insight that helps you solve the problem. (Yes, I know this may sound weird, but the rubber duck solution is an actual programmers' technique for achieving insight, so it may be weird but it works.) If explaining it to the rubber duck fails, it also prepares you for the next step.
6. Ask someone else: Get on discord, or discourse, or reddit, and ask, using that explanation you thought up for the rubber duck that clearly lays out what you are trying to achieve, what you've done, and the problem you're having. Often, someone else will have a solution, or at least suggestions for other things you can try.

How NOT to solve a problem

1. Constantly spam questions: There is no shame in asking a question after you've done your best to solve your problem yourself, and there's no need to go to the ends of the earth to solve something. But you should try to solve things yourself, and only ask questions when you're genuinely stumped. Other developers and contributors have things to do with their time, and don't want to answer "is this okay? well, then how about this?" every 5 minutes. If you want to know if something is okay, write it and experiment and find out for yourself.
2. Give up immediately: Learning anything new can be hard and frustrating. Adding new content to CDDA often requires learning new things and sometimes requires figuring things out on your own. If you quit in frustration as soon as you have to do something that isn't explicitly covered by the guide, you will never get anywhere. Just remember that everyone, even the best developers and contributors, has been stuck at one point or another and had to experiment and learn to resolve the problem that was blocking them.

Frequent JSON problems

Here's some frequently occurring JSON issues to watch out for. A text editor with JSON syntax highlighting such as notepad++ can help a lot here, as a lot of these are very subtle.

• missing }, ], or " : every object is enclosed by { }, every list by [ ], and every string by " ". Always make sure that if you start with a { you end with a }, if you start with a [, you end with a ], and if you start a " you end with a ".
• • This can be especially difficult when you have a list inside a list, or a list inside a list inside a list, so look closely to make sure you have [ [ [ "catfood", 1 ], [ "can", 1 ] ] ] and not [ [ [ "catfood", 1 ], [ "can", 1 ] ] or [ [ [ "catfood", 1, [ "can", 1 ] ] ].
• • special characters like { } or [ ] are ignored inside of strings, so forgetting to end a string with a " will make all the JSON after that become invalid in very weird ways. { "id": "new_thing", "type": "talk_topic" } is very different from { "id": "new_thing, "type": "talk_topic" } and only the first version is correct.
• • strings end at the next ", so you can't use " inside a string. { "description": "When I say "jump", you say "how high!" } will cause all kinds of problems, so do { "description": "When I say 'jump', you say 'how high!'" } instead.
• missing : : inside an object, every key-value pair needs to be a key and a value separated by :. You want { "id": "new_thing" } and not { "id" "new_thing" }
• missing , : inside an object or a list, every element needs to be separated by ,. You want { "id": "new_thing", "type": "talk_topic" } and not { "id": "new_thing" "type": "talk_topic" }

A special note for C++ contributors

C++ is tricky, and if you decide to contribute C++ code, you're expected to know the basics of C++ programming and debugging. If you don't know how to program and debug at all, the CDDA developer community is not a free university to teach you. If you need help with the specifics of the CDDA codebase or some tricky bit of C++ coding, people can help, but you need to know the basics yourself.