"offer": "Although we are an agricultural outpost, we are restricted to growing plants that are compatible with the New England climate during the warmer months. The easiest way to work around that is to build green houses to supplement our external fields. There isn't going to be an easy way to build these, we are going to need a massive number of glass sheets to enclose the frames. The first house will need 30 sheets of glass if you are still interested.",
In a Collection each entry is chosen independently from the other entries. Therefor the probability associated with each entry is absolute, in the range of 0...1. In the json files it is implemented as percentage with values from 0 to 100.
In a Collection each entry is chosen independently from the other entries. Therefore the probability associated with each entry is absolute, in the range of 0...1. In the json files it is implemented as percentage with values from 0 to 100.
A probability of 0 (or negative) means the entry is never chosen, a probability of 100% means its always chosen. The default is 100, because it's the most useful value. Default 0 would mean the entry can be removed anyway.
A Distribution is a weighted list like the current system. Exactly one entry is chosen from it. The probability of each entry is relative to the probability of the other entries. A probability of 0 (or negative) means it is never chosen.
An example: Suppose item A has a probability of 30 and item B has a probability of 20. Then the probabilities of the 4 combinations of A and B are:
Combination | Collection | Distribution
---------------------------------------
Neither A nor B | 56% | 0%
Only A | 24% | 60%
Only B | 14% | 40%
Both A and B | 6% | 0%
2. Format:
====
| Combination | Collection | Distribution |
| ----------------|------------|------------- |
| Neither A nor B | 56% | 0% |
| Only A | 24% | 60% |
| Only B | 14% | 40% |
| Both A and B | 6% | 0% |
##Format
The format is this:
```
```json
{
"type": "item_group",
"subtype": "<subtype>",
@@ -34,39 +33,43 @@ The format is this:
}
```
`subtype` is optional. It can be "collection" or "distribution". If unspecified, it defaults to `old`,
which denotes that this item group uses the old format (which is technically a distribution).
`subtype` is optional. It can be `collection` or `distribution`. If unspecified, it defaults to `old`, which denotes that this item group uses the old format (which is technically a distribution).
There are some caveats to watch out for when using `ammo` or `magazine`; see Section 4.
There are [some caveats](#ammo-and-magazines) to watch out for when using `ammo` or `magazine`.
3. The Entries Array
====
###Entries array
The `entries` list contains entries, each entry can be one of the following:
```
{ "item": "<item-id>", ... }
```
or
```
{ "group": "<group-id>", ... }
```
or
```
{ "distribution": [
"An array of entries, each of which can match any of these 4 formats"
] }
```
or
```
{ "collection": [
"An array of entries, each of which can match any of these 4 formats"
] }
```
The `entries` list contains entries, each of which can be one of the following:
1. Item
```json
{ "item": "<item-id>", ... }
```
2. Group
``` json
{ "group": "<group-id>", ... }
```
3. Distribution
```json
{ "distribution": [
"An array of entries, each of which can match any of these 4 formats"
] }
```
4. Collection
```json
{ "collection": [
"An array of entries, each of which can match any of these 4 formats"
] }
```
The game decides based on the existence of either the `item` or the `group` value if the entry denotes a item or a reference to another item group.
Each entry can have more values (shown above as `...`). They allow further properties of the item(s):
```
```json
"damage": <number>|<array>,
"damage-min": <number>,
"damage-max": <number>,
@@ -83,72 +86,74 @@ Each entry can have more values (shown above as `...`). They allow further prope
"container-item": "<container-item-id>",
"container-group": "<group-id>",
```
`contents` is added as contents of the created item. It is not checked if they can be put into the item. This allows water, that contains a book, that contains a steel frame, that contains a corpse.
`count` makes the item spawn repeat to create more items, each time creating a new item.
```
```json
"damage-min": 0,
"damage-max": 3,
"count": 4
"charges": [10, 100]
```
This will create 4 items, they can have different damage levels as the damage value is rolled separately for each of these items. Each item has charges (AKA ammo) in the range of 10 to 100 (inclusive); if the item needs a magazine before it can have charges, that will be taken care of for you. Using an array (which must have 2 entries) for charges/count/damage is equivalent to writing explicit min and max values. In other words `"count": [a,b]` is the same as `"count-min": a, "count-max": b`.
The container is checked and the item is put inside the container, and the charges of the item are capped/increased to match the size of the container.
4. Ammo and Magazines
====
###Ammo and Magazines
Here are some ways to make items spawn with/without ammo/magazines (note that `ammo-item` can
be specified for guns and magazines in the entries array to use a non-default ammo type):
A)
Specify an ammo/magazine chance (introduced in Section 2) for the entire item group.
`ammo` specifies the percent chance that the entries will spawn fully loaded (if it needs a magazine, it will be added for you).
`magazine` specifies the percent chance that the entries will spawn with a magazine.
Both of these default to 0 if unspecified.
* Secify an ammo/magazine chance (introduced in Section 2) for the entire item group.
`ammo` specifies the percent chance that the entries will spawn fully loaded (if it needs a magazine, it will be added for you).
`magazine` specifies the percent chance that the entries will spawn with a magazine.
Both of these default to 0 if unspecified.
Note that `ammo` and `magazine` only apply to tools, guns, and magazines. Furthermore, they don't apply to tools whose entry explicitly specifies
how much ammo (charges) to spawn with, or to tools whose JSON item definition specifies a random amount or a fixed, nonzero amount of
initial charges.
Note that `ammo` and `magazine` only apply to tools, guns, and magazines. Furthermore, they don't apply to tools whose entry explicitly specifies how much ammo (charges) to spawn with, or to tools whose JSON item definition specifies a random amount or a fixed, nonzero amount of initial charges.
If any item groups are referenced from your item group, then their ammo/magazine chances are
ignored, and yours are used instead.
If any item groups are referenced from your item group, then their ammo/magazine chances are ignored, and yours are used instead.
B)
Use `charges`, `charges-min`, or `charges-max` in the entries array. A default magazine will be
added for you if needed.
* Use `charges`, `charges-min`, or `charges-max` in the entries array. A default magazine will be added for you if needed.
In other words: a single string denotes an item id, an array (which must contain a string and a number) denotes an item id and a probability.
Similar for groups:
```
This is true for groups as well:
```json
"groups": [ "<id-1>", [ "<id-2>", 10 ] ]
```
This format does not support further properties of the created items, the probability is only optional for entries of collections!
This format does not support further properties of the created items - the probability is only optional for entries of collections!
The content of "entries", "items" and "groups" are all added if those members exist. This will have the item "<id-1>" appear twice in the item group:
```
The content of "entries", "items" and "groups" are all added if those members exist. This will have the item `<id-1>` appear twice in the item group:
```json
{
"items": [ "<id-1>" ],
"entries": [ { "item": "<id-1>" } ]
}
```
Another example. The group "milk" spawns a container (taken from milk_containers) that contains milk (maximal amount that fits into the container, because there is no specific charges value defined).
```
```json
{
"type" : "item_group",
"id": "milk_containers",
@@ -168,15 +173,15 @@ Another example. The group "milk" spawns a container (taken from milk_containers
},
```
6. Inlined item groups
====
##Inlined item groups
In some places one can define an item group directly instead of giving the id of a group. One can not refer to that group as it has no visible id (it has an unspecific/random id internally). This is most useful when the group is very specific to the place it is used and wont ever appear anywhere else.
At some places one can define an item group directly instead of giving the id of a group. One can not refer to that group as it has no visible id (it has an unspecific/random id internally). This is most useful when the group is very specific to the place it is used and wont ever appear anywhere else.
As an example: monster death drops (`death_drops` entry in the `MONSTER` object, see [JSON_INFO.md](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/JSON_INFO.md)) can do this. If the monster is very specific (e.g. a special robot, a unique endgame monster), the item spawned upon its death won't (in that form) appear in any other group.
As an example: monster death drops ("death_drops" entry in the "MONSTER" object, see JSON_INFO.md) can do this. If the monster is very specific (e.g. a special robot, a unique endgame monster), the item spawned upon its death wont (in that form) appear in any other group.
Therefore, this snippet:
Therefor this snippet:
```JSON
```json
{
"type": "item_group",
"id": "specific_group_id",
@@ -187,9 +192,10 @@ Therefor this snippet:
"death_drops": "specific_group_id"
}
```
is equivalent to:
```JSON
```json
{
"death_drops": {
"subtype": "distribution",
@@ -198,10 +204,11 @@ is equivalent to:
}
```
The inline group is read like any other group and one can use all the properties mentioned above. Its "type" and its "id" members are always ignored.
The inline group is read like any other group and one can use all the properties mentioned above. Its `type` and its `id` members are always ignored.
Instead of a full JSON object, one can also write a JSON array. The default subtype is used and the array is read like the "entries" array (see above). Each entry of that array must be a JSON object. Example:
@@ -211,12 +218,19 @@ Instead of a full JSON object, one can also write a JSON array. The default subt
----
###Notes
You can test your item groups in the game:
- load a game and call the debug menu, (If a key isn't bound to the debug menu or you forgot it, use <ESC> -> '1')
- choose "Test Item Group".
- select the item group you want to debug. It will spawn items based on that 100 times and count the spawned items. They are displayed, sorted by their frequency.
- You can filter anything in the debug menu using '/'
----
1. Load a game and call the debug menu
>*TIP* (If a key isn't bound to the debug menu or you forgot it, use <kbd>ESC</kbd> > <kbd>1</kbd>)
2. Choose "Test Item Group".
3. Select the item group you want to debug.
The game will then spawn items in that group 100 times and count the spawned items. They'll then be displayed, sorted by their frequency.
>*TIP*: You can filter anything in the debug menu using <kbd>/</kbd>
You should not add items to the item group "EMPTY_GROUP". This group can be used when the game requires a group id, but you don't want to spawn any items there. The group will never spawn items.
You should not add items to the item group `EMPTY_GROUP`. This group can be used when the game requires a group id, but you don't want to spawn any items there. The group will never spawn items.
Certain features of the game can be modified without rebuilding the game from source code; you should be able to just modify the pertinent files and run the game to see your changes. This attempts to document these features.
An in-depth review of all json files and their appropriate fields is available in JSON_INFO.txt.
##Adding a profession.
Let's say we want to add a "survivalist" profession.
We'll say this profession starts with archery, survival, traps, beef jerky and a few survival items. We'll set the starting cost at 3 points since it modifies skills and items. We could do that with the following entries:
````json
{
"ident" : "survivalist",
"name": "Wilderness Survivalist",
"description": "You live off the wild and wander the world; you've never
had a place to live or items other than what you can
scavenge off the land. People called you crazy; now,
After adding this to the professions.json file, we should see the new profession show up in the character creation screen.
##Adding an item
1. Open the appropriate json in `data/json/items` and add your item near similar types.
>**NOTE:** See `JSON_INFO` for a more in-depth review of each individual item .json file/flags
2. Add the item to `data/json/itemgroups` to have it spawn in in-game locations
##Important note on json files
The following characters: `[ { , } ] : "` are *very* important when adding or modifying the JSON files for technical reasons. This means a single missing `,` or `[` or `}` can be the difference between a working file and a hanging game at startup.
Many editors have features that let you track `{ [` and `] }` to see if they're balanced (ie, have a matching opposite); [Notepad++](https://notepad-plus-plus.org/) is a popular, free editor on Windows that contains this feature. On Linux, there are a plethora of options, and you probably already have a preferred one 🙂
There are a number of test cases in `tests/`. The test framework is [Catch](https://github.com/philsquared/Catch). For tutorials, please visit [https://github.com/philsquared/Catch/blob/master/docs/tutorial.md](https://github.com/philsquared/Catch/blob/master/docs/tutorial.md).
Info on translating Cataclysm-DDA into another language.
#Translating Cataclysm-DDA
##Translators
TRANSLATORS
===========
The current official locations for translating Cataclysm-DDA are [Launchpad Translations](https://translations.launchpad.net/cdda) and [Transifex Translations](https://www.transifex.com/projects/p/cataclysm-dda).
The current official locations for translating Cataclysm-DDA is at
[Launchpad Translations](https://translations.launchpad.net/cdda) and [Transifex Translations](https://www.transifex.com/projects/p/cataclysm-dda).
You can join to your language translation project:
You can lend your support to a language translation project:
On [Transifex](https://www.transifex.com/projects/p/cataclysm-dda/):
* Argentinian
@@ -29,75 +26,44 @@ On [Launchpad](https://translations.launchpad.net/cdda):
* Serbian (inactive)
* Vietnamese (inactive)
If your language is not translated you can add it into any translation project on launchpad.net or transifex.com(prefered).
Using Launchpad Translations anyone can help translate.
All you need to do is set up a Launchpad account,
and tell it your preferred language.
After that, your language should show up for translation,
even if you are starting a new translation from scratch.
If you have any questions or comments about translation,
feel free to post in the "Translations Team Discussion" subforum of
(and some specific to translating computer programs in general,)
which translators should be aware of,
such as the use of terms like `%s` and `%3$d` (leave them as they are),
and the use of tags like `<name>` (don't translate the tags).
Information about these,
and any other issues specific to individual languages,
can be found in Cataclysm-DDA's `lang/notes/` folder.
General notes for all translators are in
`lang/notes/README_all_translators.txt`,
and notes specific to a language may be stored as `<lang_id>.txt`,
for example `lang/notes/de.txt` for German.
Cataclysm-DDA has more than 14,000 translatable strings,
but don't be discouraged.
The more translators there are,
the easier it becomes :).
MAINTAINERS
===========
Several steps need to be done in the correct order,
to correctly merge and maintain the translation files.
There are scripts available for these,
so usually the process will be as follows:
1. Download the translations in .po format.
2. Put them in `lang/incoming/`,
ensuring they are named consistently with the files in `lang/po/`.
Don't see your language in the list above? You can add it into any translation project on launchpad.net or transifex.com (prefered).
All you need to do is set up a Launchpad account, and tell it your preferred language. After that, your language should show up for translation - even if you are starting a new translation from scratch!
If you have any questions or comments about translation, feel free to post in the "Translations Team Discussion" subforum of [the Cataclysm-DDA forums](http://smf.cataclysmdda.com/).
###Tips
There are some issues specific to Cataclysm-DDA, (and some specific to translating computer programs in general) which translators should be aware of. These include the use of terms like `%s` and `%3$d` (leave them as they are), and the use of tags like `<name>` (don't translate the tags).
Information about these, and any other issues specific to individual languages, can be found in Cataclysm-DDA's `lang/notes/` folder.
General notes for all translators are in `lang/notes/README_all_translators.txt`, and notes specific to a language may be stored as `<lang_id>.txt`, for example `lang/notes/de.txt` for German.
Cataclysm-DDA has more than 14,000 translatable strings, but don't be discouraged. The more translators there are, the easier it becomes 😄
##Maintainers
Several steps need to be done in the correct order to correctly merge and maintain the translation files.
There are scripts available for these, so usually the process will be as follows:
1. Download the translations in `.po` format.
2. Put them in `lang/incoming/`, ensuring they are named consistently with the files in `lang/po/`.
3. Run `lang/update_pot.sh` to update `lang/po/cataclysm-dda.pot`.
4. Run `lang/merge_po.sh` to update `lang/po/*.po`.
This will also merge the translations from `lang/incoming/`.
This will also merge the translations from `lang/incoming/`.
These steps should be enough to keep the translation files up-to-date.
To compile the .po files into .mo files for use,
run `lang/compile_mo.sh`.
It will create a directory in `lang/mo/` for each language found.
Also note that both `lang/merge_po.sh` and `lang/compile_mo.sh`
accept arguments specifying which languages to merge or compile.
So to compile only the translation for, say, Traditional Chinese (zh_TW),
one would run `lang/compile_mo.sh zh_TW`.
After compiling the appropriate .mo file,
if your system is using that language,
the translations will be automatically used when you run cataclysm.
If your system locale is different from the one you want to test,
the easiest way to do so is to find out your locale identifier,
compile the translation you want to test,
then rename the directory in `lang/mo/` to your locale identifier.
So for example if your local language is New Zealand English (en_NZ),
and you want to test the Russian (ru) translation,
the steps would be `lang/compile_mo.sh ru`,
`mv lang/mo/ru lang/mo/en_NZ`,
`./cataclysm`.
To compile the .po files into `.mo` files for use, run `lang/compile_mo.sh`. It will create a directory in `lang/mo/` for each language found.
Also note that both `lang/merge_po.sh` and `lang/compile_mo.sh` accept arguments specifying which languages to merge or compile. So to compile only the translation for, say, Traditional Chinese (zh_TW), one would run `lang/compile_mo.sh zh_TW`.
After compiling the appropriate .mo file, if your system is using that language, the translations will be automatically used when you run cataclysm.
If your system locale is different from the one you want to test, the easiest way to do so is to find out your locale identifier, compile the translation you want to test, then rename the directory in `lang/mo/` to your locale identifier.
So for example if your local language is New Zealand English (en_NZ), and you want to test the Russian (ru) translation, the steps would be `lang/compile_mo.sh ru`, `mv lang/mo/ru lang/mo/en_NZ`, `./cataclysm`.
