New Contributor Guide Items

Adding a new items

Items are things in the game. They're usually easy to add, but there are some subtle bits.

Items are stored in data/json/items/. There are a lot of subfolders and subfiles, so try to pick the most appropriate one. Some guidelines:

• melee weapons go in melee.json
• guns go in the gun/ subfile for the gun's ammo, while new ammo goes in ammo/, gun magazines go in magazine/
• comestibles contains all food, drink, and medicine
• vehicle parts go in vehicle/ but are a separate, complicated topic.
• clothing and armor go in armor.json for the most part.

items have a lot of different fields in their objects, so I'm just going to highlight the most important ones. For everything else, read doc/JSON_INFO.md and doc/JSON_FLAGS.md

  {
    "id": "hide_bag",
    "copy-from": "raw_leather",
    "type": "COMESTIBLE",
    "category": "clothing",
    "name": "hide bag",
    "description": "The raw skin of an animal, quickly turned into a makeshift bag for storage.  It will still rot, and needs to be cured and tanned.",
    "symbol": "[",
    "color": "pink",
    "looks_like": "swag_bag",
    "armor_data": {
      "covers": [ "ARM_EITHER", "HAND_EITHER" ],
      "coverage": 5,
      "encumbrance": 100,
      "storage": 60,
      "material_thickness": 1,
      "flags": [ "OVERSIZE", "BELTED", "RESTRICT_HANDS", "WATER_FRIENDLY" ]
    }
  },

• "id" is the internal reference string for the item, and must be unique among all other items.
• "type" is the type of item. Items can have multiple types, like the hide_bag technically being edible (required so it will rot) but having armor data so you can wear it.
• "category" is the category the item will be sorted in for inventory lists. It is unrelated to the item's type - you can food in the clothing category, armor in the tool category, whatever makes sense.
• "copy-from" is a special field. It references another item's "id" and means use that item's values except where they differ from this item's. In general, you should use copy-from as much as possible because it reduces the number of things that future developers will need to change when making a change. For instance, almost all guns are copy-froms for a a single abstract gun, which means if there is a change made to how guns work, that single abstract gun gets changed and all the other guns get the change automatically.
• "looks_like" contains the "id" of another item that the item might look like. If a tileset doesn't have a tile for your new item, it will check if it has a tile for the looks_like and use that instead. looks_like is ignored if a tileset has a tile for an item, so it's always safe to include. looks_like automatically chain, so if a new item looks like an item that doesn't have a tile, but the second item looks like a third item that has a tile, the first item will look like the third item.

Special item considerations

• an entirely new gun will need a new item for the gun, a new item for the ammunition, and a new item for the detachable magazine, if any. You'll have to create all three. In general, please don't create new ammunition until you have a solid understanding of adding items, but its more acceptable to create new guns and new magazines.
• books with recipes don't define the recipes they contain. Instead, the recipes reference the books. So if you want to create a Tex-Mex cookbook, you have to create an item for the book and then go through the food recipes and references to the book in the recipe's "book_learn" fields.

Spawning items

Adding an item's definition just defines the item. It doesn't make it show up in the game. To do that, you'll need to add the item to one or more item_groups.

Item_groups mostly live in data/json/itemgroups/ and data/json/item_groups.json. There's an entire doc on item groups that explains it very well: doc/ITEM_SPAWN.md Some locations have their own item groups that are defined in the location's definition in data/json/mapgen/, so you may need to add stuff there, too.

Don't forget the recipes

If an item should be craftable, you should also add a recipe for it. See the section on adding recipes.

Sample process: Adding a new gun

1. Add the new gun to the gun's caliber JSON file in data/json/items/gun/
2. Add the new gun's new magazines (if any) to the gun's caliber JSON file in data/json/items/magazine/
3. Add the gun and magazine to one or more item groups in data/json/item_groups.json, data/json/itemgroups/, and/or data/json/mapgen/
4. If the gun or magazine can be crafted, add recipes for them in data/json/recipes/