A chestsheet is made up of three main components: items, groups, and containers

items

Registers all the mod items that can be used in dungeon chests.

Simple items block:

"items": {
  "bread": {
    "name": "minecraft:bread",
    "damage": 0
  },
  "wool": {
    "name": "minecraft:wool",
    "damage": 0
  },
  "torch": {
    "name": "minecraft:torch",
    "damage": 0
  }
  "iron_chestplate": {
    "name": "minecraft:iron_chestplate",
    "damage": 0
  }
}

In this example, "bread", "wool", "torch", and "iron_chestplate" are the aliases for the items that will be used throughout in the file.

• "name" - the Minecraft name of the item or block.
• "type" - [optional] the type of the item. Used for special items that require extra data. Ex. potions - the item name minecraft:potion with a type of "luck".
• "damage" - the meta data of the item or block.

groups

Organizes items into "loot" groups that containers will randomly select from.

Simple groups block:

"groups": {
  "common_items": {
    "name": "common_items",
    "items": [
      {
        "ref": "bread",
        "chance": 80.0,
        "weight": 50.0,
        "num": {
          "min": 2.0,
          "max": 5.0
        },
        "order": 50.0
      },
      {
        "ref": "wool",
        "chance": 25.0,
        "weight": 25.0,
        "num": {
          "min": 1.0,
          "max": 3.0
        },
        "order": 51.0
      },
      {
        "ref": "torch",
        "chance": 90.0,
        "weight": 25.0,
        "num": {
          "min": 1.0,
          "max": 5.0
        },
        "order": 52.0
      }
    ]
  },
  "rare_items": {
    "name": "rare_items",
    "items": [
      {
        "ref": "iron_chestplate",
        "chance": 18.0,
        "weight": 18.0,
        "num": {
          "min": 1.0,
          "max": 1.0
        },
        "order": 35.0,
        "enchants": {
          "num": {
            "min": 1.0,
            "max": 2.0
          },
          "enchanments": []
        }
      }
    ]
  }
}

Here, the thee items - bread, wool, and torch - are grouped together in a "common_items" groups. A second group "rare_items" contains only one item - "iron_chestplate".

group properties

• "name" - the name of the group.
• "items" - a list of items in the group.

group > items properties

• "ref" - the alias of the item (set earlier in the items block).
• "chance" - the percent chance (probability) of the item being selected. Explanation how chance and weight are used below.
• "weight" - the weight of the item. Used with weighted randomness. Explanation how chance and weight are used below.
• "num" - the range of the stack size for this item.
• "order" - the order in which the items appear in the group.
• "enchants" - the enchantments an item may be given.

group > items > enchants

• "num" - the range of the number of enchantments
• "enchanments" - not implemented (I am aware of the spelling error). this property would give an item a specific list of enchantments.

containers

Defines containers and lists of groups and items that they can contain.

Simple containers block:

"containers": {
  "common_chest": {
    "name": "common_chest",
    "category": "common",
    "randomGroups": [
      {
        "ref": "common_items",
        "itemsFactor": 1.0,
        "chanceFactor": 1.0,
        "num": {
          "min": 3.0,
          "max": 5.0
        },
        "order": 100.0
      }
    ],
    "randomItems": [],
    "chance": 0.0,
    "weight": 50.0
  },
  "rare_chest": {
    "name": "rare_chest",
    "category": "rare",
    "randomGroups": [
      {
        "ref": "common_items",
        "itemsFactor": 2.0,
        "chanceFactor": 2.0,
        "num": {
          "min": 3.0,
          "max": 5.0
        },
        "order": 100.0
      },
      {
        "ref": "rare_items",
        "itemsFactor": 1.0,
        "chanceFactor": 1.0,
        "num": {
          "min": 1.0,
          "max": 1.0
        },
        "order": 100.0
      }
    ],
    "randomItems": [],
    "chance": 0.0,
    "weight": 50.0
  }
}

Here, two containers (or chests) are defined - "common_chest" and "rare_chest".

container properties

• "name" - the name of the container.
• "category" - the category of the container. Valid values are: common, uncommon, rare, boss, and epic.
• "randomGroups" - a list of groups from which items are selected from.
• "randomItems" - a list of individually specified items to select from.
• "chance" - not currently in use - the percent chance (probability) of the container being selected.
• "weight" - the weight of the container. Used with weighted randomness.

container > randomGroups properties

• "ref" - the alias/name of the group (set earlier in the groups block).
• "itemsFactor" - a modifier to the number of items to include.
• "chanceFactor" - a modifier to the chance of an item being selected.
• "num" - the range of the number of items to include from the group.
• "order" - not currenlty in use

container > randomItems properties

• see group > items properties

Chance and Weight

Chance is the probability that something will occur. Ex. If a group item has a chance value of 80.0, then it has an 80% chance of an be selected to appear in a chest. However, item selection is not that straight-forward. First an item has to be selected by weighted random distribution to be included in the set of items that get tested to be selected to appear in the chest.

Weight - see this link for an explanation of Weighted Random Distribution. A quick explanation is to use a simple example form the above chestsheet. If there are two items added to the list, bread with weight 80.0 and bread with weight 25.0, the weights are totaled and a random number is selected in the range of 0 to weight total. In this case, the weight total is 105.0. A random number is selected. If the number selected is < 80, then bread is chosen, else wool is chosen. So the item will a larger weight has a greater possibility of being chosen.

In summary, weight is used to determine which items are selected to attempt to be added to the chest and chance is then used to determine if the selected items actually make it into the chest.

Explanation of Example

In this example there are two chests defined - common and rare. They both have a weight of 50, therefor they have the same probability of being selected to appear in a room that has a chest. If the rare chest is selected, it has two groups of items to fill itself with. It has a common_items groups with a possible of 2.0 (itemsFactor) * (3.0 <--> 5.0), or 6.0 to 10.0 common items and 1.0 * (1.0 <--> 1.0), or 1.0 rare items. Of the common items, bread has the highest weight of 50.0, which makes it the most likely to be selected. If it is selected, it has a chance of 80.0, or an 80% chance of being placed in the chest. This process repeats until all 7.0 to 11.0 possible items have been tried.