Recipe JSON Info

Recipes

Crafting recipes are defined as a JSON object with the following fields:

id fields

"result"

ID of resulting item. The thing the recipe creates.

    "result": "javelin",

"byproducts"

    "byproducts": [ [ "" ] ],    

Optional (default: empty). Additional items generated by crafting this recipe.

"category"

    "category": "CC_WEAPON",  

Category of crafting recipe. CC_NONCRAFT used for disassembly recipes

"subcategory"

for the player interface

    "subcategory": "CSC_WEAPON_PIERCING",

"id_suffix"

    "id_suffix": "",

Optional (default: empty string). Some suffix to make the ident of the recipe unique. The ident of the recipe is "<id-of-result><id_suffix>".

"override"

    "override": false,

Optional (default: false). If false and the ident of the recipe is already used by another recipe, loading of recipes fails. If true and a recipe with the ident is already defined, the existing recipe is replaced by the new recipe.

"delete_flags"

    "delete_flags": [ "CANNIBALISM" ], 

Optional (default: empty list). Flags specified here will be removed from the resultant item upon crafting. This will override flag inheritance, but *will not* delete flags that are part of the item type itself.

"flags"

A set of strings describing boolean features of the recipe

    "flags": [                   
      "BLIND_EASY",
      "ANOTHERFLAG"
    ],

"reversible"

Can be disassembled. Default is true?

    "reversible": false,

time fields

The preferred time to perform recipe specifies units in minutes (m), hours (h) etc. The deprecated time to perform recipe does not include unit (where 1000 ~= 10 turns ~= 10 seconds game time).

"time"

Preferred example:

    "time": "5 m",               

Deprecated example:

    "time": 5000,                

"batch_time_factors"

Optional factors for batch crafting time reduction. First number specifies maximum crafting time reduction as percentage, and the second number the minimal batch size to reach that number. In this example given batch size of 20 the last 6 crafts will take only 3750 time units.

    "batch_time_factors": [25, 15],

skill and learn fields

How the character acquires knowledge of the recipe and the ability to perform it.

"skill_used"

Skill trained and used for success checks

    "skill_used": "fabrication", 

"skills_required"

    "skills_required": [["survival", 1], ["throw", 2]], 

Skills required to unlock recipe

"difficulty"

Difficulty of success check (what is the mechanic here? is based upon the skill level?)

    "difficulty": 3,             

"book_learn"

(optional) An array of books that this recipe can be learned from.

ID of the book the recipe can be learned from

Skill level at which it can be learned

(optional) Name of the recipe as it should appear in the book's description (default is the name of resulting item of the recipe)

(optional) If set to true, recipe will not be shown in the description of the book

Additional book this recipe can be learnt from.

    "book_learn": {	             
        "textbook_anarch" : {    
            "skill_level" : 7,   
            "recipe_name" : "something", 
            "hidden" : true },   
        "textbook_gaswarfare" : { 
            "skill_level" : 8
        }
    },

"autolearn"

If set to true, automatically learned upon gaining required skills. If an array, learned upon gaining the skill levels indicated in the array.

Example 1:

    "autolearn": true,           

Example 2:

    "autolearn" : [              
        [ "survival", 2 ],
        [ "fabrication", 3 ]
    ],

"decomp_learn"

Can be singular or multiple, and the format varies depending upon if it is single or multiple.

Simple example of a recipe that can be learned by disassembling an item of same type as result at this level of the skill_used:

    "decomp_learn" : 4,        
 

Example of a recipe that can be learned by disassembling an item of same type as result at specified levels of skills:

    "decomp_learn" : [           
        [ "survival", 1 ],
        [ "fabrication", 2 ]
    ],

"proficiencies"

The proficiencies related to this recipe

First value "proficiency" is the id of a proficiency.

"Required" when set true is incompatible with time_multiplier; it indicates whether or not you must have the proficiency to craft it. If required is false, and you do not have this proficiency, The multiplier on time taken to craft this recipe is via time_multiplier.

The multiplier on failure chance when crafting without this proficiency. Defaults to 2.5. Multiple proficiencies will multiply this value. (if all have the default, it's fail_multiplier ^ n, where n is the number of proficiencies that are lacked). The multiplier on learning speed for this proficiency. By default, it's the time of the recipe, divded by the time multiplier, and by the number of proficiencies that can also be learned from it.

max_experience sets a limit on how far recipe raises your experience for that proficiency (above 15 minutes worth in the example below).

    "proficiencies" : [ 
        {
          "proficiency": "prof_knapping", 
          "required": false, 
          "time_multiplier": 2.0 
          "fail_multiplier": 2.5 
          "learning_time_multiplier": 1.2 
          "max_experience": "15 m" 
        }
    ]

faction camp fields

Optional fields relevant to faction camps

"construction_blueprint"

    "construction_blueprint": "camp", 

an optional string containing an update_mapgen_id. Used by faction camps to upgrade their buildings

"on_display"

    "on_display": false,         

this is a hidden construction item, used by faction camps to calculate construction times but not available to the player

ingredient fields

These are the fields that indicate what tools, materials, components, etc are needed to complete the recipe

"qualities"

Generic qualities of tools needed to craft

    "qualities": [               
      { "id": "CUT", "level": 1, "amount": 1 }
    ],

"tools"

ids of the specific tools needed to craft, followed by integer representing the charges consumed when tool is used. -1 means no charges are consumed

    "tools": [                   
    [
      [ "fire", -1 ]             
    ]],

"using"

Requirement IDs and multipliers of tools and materials used. Second number multiplies requirement materials by that amount

In the below example, Need 3x everything in req_a, 5x everything in req_b

    "using": [                   
      [ "req_a", 3 ],            
      [ "req_b", 5 ],            
    ],

"components"

Items (or item alternatives) required to craft this recipe

First ingredient: need 5 of item_a Also need 2 of item_b... OR 4 of item_c (but do not need both)

    "components": [              
      [
        [ "item_a", 5 ]          
      ],
      [
        [ "item_b", 2 ],         
        [ "item_c", 4 ]          
      ]
    ]

... any number of other component ingredients (see below)

Recipe requirements

The tool quality and component requirements for a recipe may be expressed in a combination of several ways, with these JSON fields:

• "qualities" defines tool qualities like CUT or HAMMER, and quality levels needed to craft
• "tools" lists item ids of tools (or several alternative tools) needed for crafting the recipe
• "components" lists item ids or requirement ids, intended mainly for material ingredients
• "using" gives requirement ids; the requirement may have nested tools, qualities, or components

These fields may be used similarly in uncrafting, constructions, vehicle parts, and vehicle faults. The first three fields are applicable to "requirement" definitions as well, and may be nested; see the requirements section.

A recipe's "components" lists all the required items or ingredients needed to craft the finished item from the recipe. Each component is given as an integer quantity of a specific item id or requirement id, or as a list of several alternative item/requirement quantities.

The syntax of a component in its simplest form is an item id and quantity. Continuing the "javelin" recipe, let's require a single "spear_wood" item:

    "components": [
      [ [ "spear_wood", 1 ] ]
    ]

A single component may also have substitutions; for instance, to allow crafting from one "spear_wood" or one "pointy_stick":

    "components": [
      [ [ "spear_wood", 1 ], [ "pointy_stick", 1 ] ]
    ]

Notice that the first example with only "spear_wood" was simply the degenerate case - a list of alternatives with only 1 alternative - which is why it was doubly nested in [ [ ... ] ].

The javelin would be better with some kind of leather or cloth grip. To require 2 rags, 1 leather, or 1 fur in addition to the wood spear or pointy stick:

    "components": [
      [ [ "spear_wood", 1 ], [ "pointy_stick", 1 ] ],
      [ [ "rag", 2 ], [ "leather", 1 ], [ "fur", 1 ] ]
    ]

And to bind the grip onto the javelin, some sinew or thread should be required, which can have the "NO_RECOVER" keyword to indicate they cannot be recovered if the item is deconstructed:

    "components": [
      [ [ "spear_wood", 1 ], [ "pointy_stick", 1 ] ],
      [ [ "rag", 2 ], [ "leather", 1 ], [ "fur", 1 ] ],
      [ [ "sinew", 20, "NO_RECOVER" ], [ "thread", 20, "NO_RECOVER" ] ]
    ]

Note: Related to "NO_RECOVER", some items such as "superglue" and "duct_tape" have an "UNRECOVERABLE" flag on the item itself, indicating they can never be reclaimed when disassembling. See JSON_FLAGS.md for how to use this and other item flags.

To avoid repeating commonly used sets of components, instead of an individual item id, provide the id of a "requirement" type, along with a quantity, and the "LIST" keyword. Typically these are defined within data/json/requirements.

For example if these "grip_patch" and "grip_wrap" requirements were defined:

    [
      {
        "id": "grip_patch",
        "type": "requirement",
        "components": [ [ [ "rag", 2 ], [ "leather", 1 ], [ "fur", 1 ] ] ]
      },
      {
        "id": "grip_wrap",
        "type": "requirement",
        "components": [ [ [ "sinew", 20, "NO_RECOVER" ], [ "thread", 20, "NO_RECOVER" ] ] ]
      }
    ]

Then javelin recipe components could use 1 grip and 1 wrap, for example:

    "result": "javelin",
    "components": [
      [ [ "spear_wood", 1 ], [ "pointy_stick", 1 ] ],
      [ [ "grip_patch", 1, "LIST" ] ],
      [ [ "grip_wrap", 1, "LIST" ] ]
    ]

And other recipes needing two such grips could simply require 2 of each:

    "result": "big_staff",
    "components": [
      [ [ "stick_long", 1 ] ],
      [ [ "grip_patch", 2, "LIST" ] ],
      [ [ "grip_wrap", 2, "LIST" ] ]
    ]

The "using" field in a recipe works similarly, but "using" may only refer to requirement ids, not specific items or tools. A requirement included with "using" must also give a multiplier, telling how many units of that requirement are needed. As with "components", the "using" list is formatted as a collection of alternatives, even if there is only one alternative.

For instance, this "uncraft" recipe for a motorbike alternator uses either 20 units of the "soldering_standard" requirement, or 5 units of the "welding_standard" requirement:

    {
      "type": "uncraft",
      "result": "alternator_motorbike",
      "qualities": [ { "id": "SCREW", "level": 1 } ],
      "using": [ [ "soldering_standard", 20 ], [ "welding_standard", 5 ] ],
      "components": [ [ [ "power_supply", 1 ] ], [ [ "cable", 20 ] ], [ [ "bearing", 5 ] ], [ [ "scrap", 2 ] ] ]
    }

Overlapping recipe component requirements

If recipes have requirements which overlap, this makes it more difficult for the game to calculate whether it is possible to craft a recipe at all.

For example, the survivor telescope recipe has the following requirements (amongst others):

    1 high-quality lens
    AND
    1 high-quality lens OR 1 small high-quality lens

These overlap because both list the high-quality lens.

A small amount of overlap (such as the above) can be handled, but if you have too many component lists which overlap in too many ways, then you may see an error during recipe finalization that your recipe is too complex. In this case, the game may not be able to correctly predict whether it can be crafted.

To work around this issue, if you do not wish to simplify the recipe requirements, then you can split your recipe into multiple steps. For example, if we wanted to simplify the above survivor telescope recipe we could introduce an intermediate item "survivor eyepiece", which requires one of either lens, and then the telescope would require a high-quality lens and an eyepiece. Overall, the requirements are the same, but neither recipe has any overlap.

Complete examples

wastebread recipe example

Below is the json for the Wastebread recipe.

  {
    "type": "recipe",
    "result": "wastebread",
    "category": "CC_FOOD",
    "subcategory": "CSC_FOOD_BREAD",
    "skill_used": "cooking",
    "skills_required": [ "survival", 1 ],
    "difficulty": 3,
    "time": "35 m",
    "charges": 3,
    "batch_time_factors": [ 50, 4 ],
    "autolearn": true,
    "qualities": [ { "id": "COOK", "level": 2 } ],
    "tools": [ [ [ "surface_heat", 10, "LIST" ] ] ],
    "components": [
      [ [ "flour", 1 ] ],
      [ [ "meal_bone", 3 ] ],
      [
        [ "meal_chitin_piece", 1 ],
        [ "cornmeal", 1 ],
        [ "oatmeal", 1 ],
        [ "powder_eggs", 2 ],
        [ "milk_powder", 2 ],
        [ "protein_powder", 1 ],
        [ "wild_herbs", 5 ]
      ],
      [ [ "water", 2 ], [ "water_clean", 2 ] ]
    ]
  },

minimal blank template recipe example

  {
    "type": "recipe",
    "result": "",
    "category": "",
    "subcategory": "",
    "skill_used": "",
    "skills_required": [ "", 1 ],
    "difficulty": 1,
    "time": "15 m",
    "autolearn": true,
    "components": [
      [ [ "", 1 ] ],
      [ [ "", 1 ] ]
    ]
  },

See Also

• Comestible JSON Info
• Official Doc: https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/JSON_INFO.md#recipes