New contributor Guide abstracts

CDDA has a special json field "copy-from" which tells the JSON loader that a new item or monster is the same as an old item or monster except for a few differences. This is extremely useful for cutting down on the amount of repetitive data that needs to be organized and kept up to date: if all pistols are copies of a particular pistol and you need to add a new flag that applies to all pistols, you can just edit the base pistol and then all the other pistols have the flag.

This is such a useful feature that CDDA has a special class of objects called "abstracts" that are base items that can be used in copy-from. Here's some examples of how copy-from and abstract work:

  {
    "abstract": "gun_base",
    "type": "GUN",
    "reload_noise_volume": 10,
    "name": { "str": "base gun" },
    "symbol": "(",
    "color": "light_gray",
    "faults": [ "fault_gun_blackpowder", "fault_gun_dirt", "fault_gun_chamber_spent" ],
    "ranged_damage": { "damage_type": "bullet", "amount": 0 }
  },
  {
    "abstract": "pistol_base",
    "copy-from": "gun_base",
    "type": "GUN",
    "name": { "str": "base pistol" },
    "skill": "pistol",
    "valid_mod_locations": [
      [ "accessories", 2 ],
      [ "barrel", 1 ],
      [ "bore", 1 ],
      [ "brass catcher", 1 ],
      [ "grip", 1 ],
      [ "mechanism", 4 ],
      [ "magazine", 1 ],
      [ "muzzle", 1 ],
      [ "rail", 1 ],
      [ "sights", 1 ],
      [ "stock", 1 ],
      [ "underbarrel", 1 ]
    ]
  },
  {
    "id": "glock_19",
    "copy-from": "pistol_base",
    "looks_like": "glock_17",
    "type": "GUN",
    "name": { "str": "Glock 19" },
    "description": "Possibly the most popular pistol in existence.  The Glock 19 is often derided for its plastic construction, but it is easy to shoot.",
    "ascii_picture": "glock_19",
    "weight": "600 g",
    "volume": "386 ml",
    "longest_side": "211 mm",
    "price": 69000,
    "price_postapoc": 2500,
    "to_hit": -2,
    "bashing": 8,
    "material": [ "plastic", "steel" ],
    "symbol": "(",
    "color": "dark_gray",
    "ammo": [ "9mm" ],
    "ranged_damage": { "damage_type": "bullet", "amount": -1 },
    "dispersion": 480,
    "durability": 6,
    "blackpowder_tolerance": 48,
    "min_cycle_recoil": 380,
    "pocket_data": [
      {
        "magazine_well": "250 ml",
        "pocket_type": "MAGAZINE_WELL",
        "holster": true,
        "max_contains_volume": "20 L",
        "max_contains_weight": "20 kg",
        "item_restriction": [ "glockmag", "glockbigmag", "glock17_17", "glock17_22", "glock_drum_50rd", "glock_drum_100rd" ]
      }
    ]
  },

Neither "gun_base" or "pistol_base" are actual items that can exist in the game - they are just abstract concepts. All guns have the "(" ascii symbol and a light gray color. Almost all pistols use the "pistol" skill and have the standard pistol mod locations. A Glock 19 is a specific pistol item that can exist in the game, and has damage values, recoil, weight, etc. Abstract items can be as detailed or as minimal as makes sense and have no restrictions on what fields they can have. copy-from'd abstracts and items keep all the defined fields of whatever they've copied, but can add new fields or overwrite existing fields.

A couple of key fields here:

• "abstract" replaces "id" for abstracts, and means that the JSON describes something that doesn't actually exist in the game, but can be used items or monsters with "copy-from"
• "copy-from" always has an "id" or "abstract" value after it, and means that the JSON describes a copy of the item or abstract.
• "extend" is a special field that allows you to add a value to an existing list. If you wanted to create a gold plated version of the Glock 19, the following definition would add the gold material to the new Glock's materials:

{
  "id": "gold_glock_19",
  "copy-from": "glock_19",
  extend: { "material": "gold" }
}

• "delete" is a special field that allows you to add a value to an existing list. If you wanted to create a all steel version of the Glock 19, the following definition would remove the plastic material to the new Glock's materials:

{
  "id": "steel_glock_19",
  "copy-from": "glock_19",
  delete: { "material": "plastic" }
}

• "extend" and "delete" can be present in the same copy-from.

Although "copy-from" and "abstract" are extremely useful for simplifying CDDA's data, support for them is a bit inconsistent. Monsters, items, spells, vehicle parts all completely support them. Other things, such as mapgen and recipes, may or may not support them fully. Vehicles don't support copy-from at all. There is a slow effort going underway on the C++ side to replace a hodge-podge of loaders with the generic_factory loader, but it's a lot of work. You may need to experiment with copy-from, and don't be surprised if "extend" or "delete" don't always work if you're not working with a monster, item, spell, or vehicle part.