1# JSON Inheritance
2To reduce duplication in the JSON data it is possible for some types to inherit from an existing type.  Some restraint should be used, see guidelines section below.
3
4## Examples
5In the following condensed example ```556``` ammo is derived from ```223``` ammo via ```copy-from```:
6```
7"id": "556",
8"copy-from": "223",
9"type": "AMMO",
10"name": "5.56 NATO M855A1",
11"description": "5.56x45mm ammunition with a 62gr FMJ bullet...",
12"price": 3500,
13"relative": {
14    "damage": -2,
15    "pierce": 4,
16},
17"extend": { "effects": [ "NEVER_MISFIRES" ] }
18```
19The following rules apply to the above example:
20
21* Missing fields have the same value as the parent
22
23* Fields explicitly specified replace those of the parent type. The above example replaces ```name```, ```description``` and ```price```.
24
25* Numeric values may be specified ```relative``` to the parent. For example ```556``` has less ```damage``` but more ```pierce``` than ```223``` and will maintain this relationship if the definition for ```223``` is changed.
26
27* Flags can be added via ```extend```. For example ```556``` is military ammo and gains the ```NEVER_MISFIRES``` ammo effect. Any existing flags specified from ```223``` are preserved.
28
29* The entry you copied from must be of the same ```type``` as the item you added or changed (not all types are supported, see 'support' below)
30
31Reloaded ammo is derived from the factory equivalent but with a 10% penalty to ```damage``` and ```dispersion``` and a chance to misfire:
32
33```
34"id": "reloaded_556",
35"copy-from": "556",
36"type": "AMMO",
37"name": "reloaded 5.56 NATO",
38"proportional": {
39    "damage": 0.9,
40    "dispersion": 1.1
41},
42"extend": { "effects": [ "RECYCLED" ] },
43"delete": { "effects": [ "NEVER_MISFIRES" ] }
44```
45The following additional rules apply to the above example:
46
47Chained inheritance is possible; for example ```reloaded_556``` inherits from ```556``` which is itself derived from ```223```
48
49Numeric values may be specified ```proportional``` to the parent by via a decimal factor where ```0.5``` is 50% and ```2.0``` is 200%.
50
51Flags can be deleted via ```delete```. It is not an error if the deleted flag does not exist in the parent.
52
53It is possible to define an ```abstract``` type that exists only for other types to inherit from and cannot itself be used in game. In the following condensed example ```magazine_belt``` provides values common to all implemented ammo belts:
54```
55"abstract": "magazine_belt",
56"type": "MAGAZINE",
57"name": "Ammo belt",
58"description": "An ammo belt consisting of metal linkages which disintegrate upon firing.",
59"rigid": false,
60"armor_data": {
61    "covers": [ "TORSO" ],
62    ...
63},
64"flags": [ "MAG_BELT", "MAG_DESTROY" ]
65```
66The following additional rules apply to the above example:
67
68Missing mandatory fields do not result in errors as the ```abstract``` type is discarded after JSON loading completes
69
70Missing optional fields are set to the usual defaults for that type
71
72## Support
73The following types currently support inheritance:
74```
75GENERIC
76AMMO
77ARMOR
78BOOK
79COMESTIBLE
80ENGINE
81GUN
82GUNMOD
83MAGAZINE
84MATERIAL
85MONSTER
86MONSTER_FACTION
87mutation
88overmap_terrain
89recipe
90terrain
91TOOL
92uncraft
93vehicle_part
94```
95
96To find out if a type supports copy-from, you need to know if it has implemented generic_factory. To find out if this is the case, do the following:
97* Open [init.cpp](https://github.com/CleverRaven/Cataclysm-DDA/tree/master/src/init.cpp)
98* Find the line that mentions your type, for example `add( "gate", &gates::load );`
99* Copy the load function, in this case it would be *gates::load*
100* Use this in [the search bar on github](https://github.com/CleverRaven/Cataclysm-DDA/search?q=%22gates%3A%3Aload%22&unscoped_q=%22gates%3A%3Aload%22&type=Code) to find the file that contains *gates::load* (Note, you cannot search for ":" in file finder.  The search will simply ignore this symbol.)
101* In the search results you find [gates.cpp](https://github.com/CleverRaven/Cataclysm-DDA/tree/master/src/gates.cpp). open it.
102* In gates.cpp, find the generic_factory line, it looks like this: `generic_factory<gate_data> gates_data( "gate type", "handle", "other_handles" );`
103* Since the generic_factory line is present, you can now conclude that it supports copy-from.
104* If you don't find generic_factory present, it does not support copy-from, as is the case for type vitamin (repeat the above steps and find that [vitamin.cpp](https://github.com/CleverRaven/Cataclysm-DDA/tree/master/src/vitamin.cpp) does not contain generic_factory)
105
106## Guidelines
107
108Contributors are encouraged to not overuse copy-from, as it can decrease the human readability of the JSON.  Chained inheritance is especially likely to become unwieldy, essentially recreating the level of redundancy we'd like to eliminate.
109
110In general, there are two situations where copy-from should be used in the core game:
111
112- Two things are nearly identical variants of each other.
113- A group of entities always (not almost always, always) shares some set of properties, then one or two levels of abstracts can set up a very shallow and narrow hierarchy.
114