Skip to content
This repository has been archived by the owner on Aug 31, 2020. It is now read-only.

Mod Version Data Format

Jump to bottom
Andrew Miner edited this page Apr 11, 2016 · 11 revisions

The ModVersion file format is a very simple command-based language which is very similar to YAML. There are commands for entering all various kinds of data needed to describe the items and recipes for those items which belong to a specific version of a mod. Most commands are optional, and can be entered in any order. Anywhere this isn't true will be called out below.

ModVersion files are expected to be named mod-version.cg and appear within a directory named according to the specific version it represents (e.g., "6.2.6") which itself appears within a directory for the mod itself. See Mod Data Format for further details.

Example

schema: 1

group: Storage

    # This is a comment.
    item: 128³ Spatial Component
        recipe:
            input: Glowstone Dust, 16³ Spatial Component, Engineering Processor
            pattern: 010 121 010
            tools: Crafting Table

group: Cables

    item: Cable Anchor
        recipe:
            input: Iron Ingot
            pattern: ... .0. ...
            quantity: 3
            tools: Nether Quartz Cutting Knife
        recipe:
            input: Tin Ingot
            pattern: ... .0. ...
            quantity: 3
            tools: Nether Quartz Cutting Knife

group: Circuits

    item: Certus Quartz Crystal; gatherable: yes

    item: Printed Calculation Circuit
        recipe:
            input: Inscriber Calculation Press, Pure Certus Quartz Crystal
            pattern: 0.. .1. ...
            extras: Inscriber Calculation Press
            tools: Inscriber

Basics

Each line of the file should usually contain a single command. Each command has the format: <command>: <arg>, <arg>, .... All of the available commands are described below. Multiple commands may be listed on the same line by separating them with ; characters. Comments are entered using the # character, which can itself be escaped if you need to use it in an item name. Blank lines are ignored. Whitespace is generally irrelevant outside item names, but following the conventions described above makes things easier.

You can check your file for errors by running the grunt test command from the root of the crafting-guide-data directory. This examine all the various files and print out any errors. While working on a data file, it is often handy to use the grunt watch command to continuously run the tests after any changes.

You can pretty-print a data file using the ./scripts/reformat <file> (<output>|-)? command. This will correct indentation, alphabetize items, and generally clean things up. Omitting the second argument will reformat the given file in place. Providing a - as the second argument will print the reformatted file to stdout without actually modifying the original.

Please be sure to use these commands prior to submitting a pull request for a new data file!

Command Reference

  • schema: <version> (required)

    The data schema used by the file. The current version is: 1.

  • group: <group>

    Starts an item group. Groups are simply used to organize items on the mod detail page, and don't need to correspond to anything in-game. Any items declared before the first group declaration are not part of any group.

  • item: <item name>

    Starts an item declaration. The item name should exactly match the item's actual in-game name. Spelling, punctuation (if any), and spaces are relevant. Extended UTF-8 characters are permitted.

    This command should be used once for each item in the mod. You should avoid using it to declare any items from vanilla Minecraft, or from other mods as these will already be added by other files.

    Each item should have a related icon file at /data/<mod-slug>/items/<item-slug>/icon.png. The image should be 48x48px and be exported from NEI as described in Adding Support for a New Mod.

    After an item declaration, the following commands may be used to describe it: gatherable, recipe.

  • gatherable: [yes|no]

    Indicates whether an item may be gathered in-game without crafting (e.g., Iron Ore can be gathered, but Iron Ingots cannot). If an item is gatherable, then it will never be crafted, even if it has recipes listed (e.g., Diamonds will never be crafted, even though they could be made from Diamond Blocks).

  • recipe:

    Starts a recipe declaration. This should be repeated once for each unique way of making the given item. Due to limitations with the crafting algorithm, the following rules should be followed when entering recipes:

    1. Do not enter multiple recipes for alternate ingredients. For example, sticks can be made from any combination of any kind of planks (e.g., Oak Wood Planks, Spruce Planks). When entering a recipe for such an item, simply choose a variant of the ingredients and enter a single recipe using that variant (e.g., only use Oak Wood Planks).
    2. Break cycles using gatherable. For example, IndustrialCraft adds a recipe to make String from Wool. Minecraft, however, already has a recipe for making Wool from String. This creates a cycle which can cause an infinite loop in crafting. Avoid such loops by marking the appropriate item(s) as gatherable
    3. Put the most basic recipe first. For example, with Mekanism, Iron Ingots can be produced in many different ways, each yielding more and more iron. Recipes should be listed in order from least to most complex.
    4. Put the highest yielding recipe first. Where all recipes are of equivalent complexity (e.g., producing Rose Red from Poppies or Rose Bushes), place the recipe which produces the most first.

  • input: (<quantity>) <item name>, (<quantity>) <item name>, ... (required)

    Lists the items needed for the current recipe. The names here must match exactly with the name of the item listed else where in this (or another) file. Failure to do so will cause it to show up in the "Items You'll Need" section with a question mark icon.

    For recipes where an item is being smelted, the convention is to require a single "furnace fuel" item to represent the fuel used in the furnace for that single item.

    For recipes which require a stack of a certain item, enter the quantity required in front of that item. If the quantity is left out, it will be assumed to be 1.

    This command is required after each recipe command.

  • onlyif: (not) <kind> <name>

    Makes the current recipe only available if some condition is met (or isn't met). The possible kind attributes are: item and mod. In either case, the name attribute should then be the name of the item or mod which must be present (or not).

    For example, the Basic Capacitor from EnderIO uses an Iron Ingot by default, but if there is some other mod which adds a Copper Ingot, then it will use the copper instead. In order to make the extra recipe only appear when copper is available, use: onlyif: item Copper Ingot. Then, in order to make the default recipe disappear when copper is available, use: onlyif: not item Copper Ingot.

  • pattern: <pattern> (required)

    Describes the placement of each input item in the 3×3 crafting grid. A pattern is an 11 character string composed of numbers or periods composed into 3 groups of 3 by spaces. Each number refers to an item in the input list (starting from 0). A period refers to a spot on the grid which is left blank.

    Each item in the input list must appear in the pattern, and each number in the pattern must correspond to an item in the input list.

    For shapeless recipes, you place the items wherever you like, but be sure to include the correct number of each (e.g., you'll need to show 4 Snowballs in the pattern for a Snow block).

    For recipes which use tools other than a crafting table, try to create a pattern which most closely matches the in-game UI for that tool. For example, for a furnace, place the item to smelt in the top- center position, and the fuel in the bottom-center position.

    This command is required after each recipe command.

    Here are a few examples:

    Item Commands
    Iron Pickaxe input: Iron Ingot, Stick; pattern: 000 .1. .1.
    Stone Slab input: Stone; pattern: ... 000 ...
    Oak Wood Planks input: Oak Wood; pattern: ... .0. ...
    Cobblestone Stairs input: Cobblestone; pattern: 0.. 00. 000
    Piston input: Oak Wood Planks, Cobblestone, Iron Ingot, Redstone; pattern: 000 121 131
    Iron Ingot input: Iron Ore, furnace fuel; pattern: .0. ... .1.

  • quantity: <integer>

    Specifies how many of the output item are created by this recipe. For example, the recipe for Oak Wood Planks produces 4 items. By default, each recipe is assumed to produce a single item.

  • tools: <item name>, <item name>, ...

    Lists the tools required for making the recipe. Usually, these are like crafting tables and furnaces: blocks you right-click to bring up a UI in which to work. However, in some mods, this is more complex. For example, in Buildcraft, making a Redstone Chipset requires an Assembly Table and a Laser. While you right-click on the former, the latter is a necessary addition.

    For most recipes, the only tool required is a Crafting Table, but even this should only be listed for those recipes which cannot be crafted in 2×2 crafting grid in the player's inventory.

  • extras: (<quantity>)? <item name>, (<quantity>)? <item name>, ...

    Lists the extra items produced by the recipe. For example, creating a Cake requires three buckets of milk, and produces, in addition to the Cake itself, three empty buckets.

Clone this wiki locally