Minecraft:Loot table

Loot tables are technical Minecraft:JSON files that are used to dictate what items should generate in various situations, such as what items should be in naturally generated containers, what items should drop when breaking a block or killing a mob, what items can be fished, and more. It does not affect dropped Minecraft:experience, or dropped non-item entities such as Minecraft:slimes from larger slimes or Minecraft:silverfish from infested blocks. In the Template:Cmd command, a loot table can be specified in Minecraft:SNBT format.

Definition

Loot tables are part of the data pack directory structure, highlighted below:

All loot tables are defined in data packs (vanilla data packs or custom data packs).

In the Template:Cmd command, a loot table can be specified in Minecraft:SNBT format.

Usage

Custom data packs use loot tables to change what loot can spawn in containers or drop by mobs. They can either modify existing loot tables or create new ones.

Vanilla usages

Vanilla loot tables are grouped into categories with some tables being in subfolders of those.

For example, the file for zombies would go in Template:File. Editing this file in a datapack would make every zombie in a Minecraft world use the modified datapack's loot table rather than the default zombie loot table.

To edit the loot tables of other entities, one would edit the entity's corresponding JSON file under the Template:File directory, which is typically said entity's name in the singular form (e.g. Template:File rather than Template:File).

The various subfolders and files include:

• Template:File: The items from brushing Minecraft:suspicious sand or Minecraft:suspicious gravel.
• Template:File: The items dropped when mining blocks.
• Template:File: Loot in various structures in chests or barrels.
• Template:File: The items inside dispensers in Minecraft:trial chambers.
• Template:File: The loot dropped by mobs when killed.
• Template:File: The equipment of mobs spawned by Minecraft:trial spawners in trial chambers.
• Template:File: Gameplay mechanics such as:
  • Template:File: Items obtained via Minecraft:fishing.
  • Template:File: Items gifted by Minecraft:cats after sleeping.
  • Template:File: Items obtained via Minecraft:bartering with Minecraft:piglins.
  • Template:File: Items dropped when a Minecraft:chicken periodically lays an egg.
  • Template:File: Items dropped when an Minecraft:armadillo sheds, either periodically or when Minecraft:brushed.
  • Template:File: Loot tables that may be chosen from when Minecraft:fishing.
    • Template:File: Valuable items that may be dropped when Minecraft:fishing.
    • Template:File: Junk items that may be dropped when Minecraft:fishing.
    • Template:File: Fish that may be caught when Minecraft:fishing.
  • Template:File: Items gifted by Minecraft:villagers to a player with the Minecraft:Hero of the Village effect.
    • Template:File: Gifts given by unemployed villagers.
    • Template:File: Gifts given by Minecraft:baby villagers.
• Template:File: The loot inside decorated pots in trial chambers.
• Template:File: The items dropped when shearing Minecraft:sheep, Minecraft:mooshrooms, Minecraft:snow golems, or Minecraft:bogged.
• Template:File: The reward after defeating trial spawners.

Some blocks, such as bedrock, end portals, and other blocks unbreakable in survival, do not have loot tables, some blocks share loot tables (namely wall and floor variants of blocks) and some drops, such as the Minecraft:wither's Minecraft:nether star, are not covered by loot tables.<ref>Template:Bug</ref>

NBT data

The loot tables are structured as a String tag that determines the table to use, and a Long tag determining the seed. Containers or mobs with the same seed and table drop the same items. Loot tables do not determine the container's slot to be used; that is randomly determined based on the seed. Once there is an interaction with the container (e.g. opening or destroying), the two tags are removed, and loots appear in the container.

For Minecraft:barrel, Minecraft:chest, Minecraft:trapped chest, Minecraft:hopper, Minecraft:minecart with chest, Minecraft:boat with chest, Minecraft:minecart with hopper, Minecraft:dispenser, Minecraft:dropper, Minecraft:shulker box, dyed shulker box, and Minecraft:decorated pot:

• Template:Nbt The root object.
  • Entity format/Lootable

For Minecraft:mobs:

• Template:Nbt The root object.
  • Entity format/DeathLootable

Minecraft:Vaults use loot tables in their config to determine the items to eject when unlocking the vault, and items to display in the vault.

Minecraft:Trial spawners use loot tables in their vault configs to determine the items to give as reward, and the items used by ominous item spawners spawned during the active phase when ominous.

Minecraft:Monster spawners and trial spawners use loot tables to determine what equipment the spawned mobs have.

Others

Loot tables can be invoked directly by the Template:Cmd command.

Loot tables can also be invoked in advancement rewards.

Format

Loot tables are defined using Minecraft:JSON files stored within a Minecraft:data pack in the path Template:Cd.

In the Template:Cmd command, a loot table can be specified in Minecraft:SNBT format.

• Template:Nbt The root.
  • Template:Nbt: (Optional. Defaults to generic) Specifies the Minecraft:loot context in which the loot table should be invoked. All item modifiers, predicates and number providers are then validated to ensure the parameters of the context type specified here cover all requirements, and prints a warning message in the output log if any modifier or predicate requires a context parameter that is not covered.
  • Template:Nbt: (Optional) Applies item modifiers in order, onto all item stacks dropped by this table.
    • Template:NbtTemplate:Nbt An Minecraft:item modifier.
  • Template:Nbt: (Optional) A list of all pools for this loot table. Pools are applied in order.
    • Template:Nbt A pool (see below).
  • Template:Nbt: (Optional) A Minecraft:resource location specifying the name of the random sequence that is used to generate loot from this loot table. If only one loot table uses a specific random sequence, the order of the randomized sets of items generated is the same for every world using the same world seed. If multiple loot tables use the same random sequence, the loot generated from any one of them changes depending on how many times and in what order any of the other loot tables were invoked.

Pool

There are several entries in a pool. The number of rolls of a pool is specified by Template:Nbt and Template:NbtTemplate:Nbt). In each roll of a pool, the pool draws one entry from all its entries. Each roll of a pool is independent.

• Template:Nbt The root.
  • Template:Nbt: (Optional) A list of predicates, that must all pass for this pool to be used.
    • Template:Nbt A Minecraft:predicate.
  • Template:Nbt: (Optional) Applies item modifiers in order, onto all item stacks dropped by this pool.
    • Template:NbtTemplate:Nbt An Minecraft:item modifier.
  • Template:NbtTemplate:Nbt: A number provider. Specifies the number of rolls on the pool.
  • Template:NbtTemplate:Nbt: (Optional. Defaults to 0.0) A number provider. Specifies the number of bonus rolls on the pool per level of luck (including luck attribute and fishing_luck_bonus on fishing tool). Rounded down after multiplying. Fishing_luck_bonus applies only to fishing. In vanilla games, luck attribute is from the Minecraft:Luck status effect, and fishing_luck_bonus is from the Minecraft:Luck of the Sea enchantment. This does not work in some context, due to bugs<ref name="luck">Template:Bug
    Template:Bug
    Template:Bug
    Template:Bug</ref>.
  • Template:Nbt: Defines the entries in this pool. One loot entry is chosen per roll as a weighted random selection from all loot entries in the pool. Each roll is independent (Sampling with replacement), so an entry can be chosen multiple times in multiple rolls. It is not the elements in this array that are rolled. Instead, composite entries first expand their children, and then singleton entries that do not meet their conditions are removed from the pool, then entries are rolled afterward.
    • Template:Nbt: An entry (see below).

Entry

There are two types of loot entry: Singleton Entry and Composite Entry.

A singleton entry defines an item generating behavior that may generate zero, one or more item stacks. Every singleton entry has a weight. Each roll selects a weighted singleton entry from the pool.

Composite entries are not weighted entries to be rolled. Instead, they are expanded/flattened before rolling, i.e., some children entries in it are extracted out. If an extracted children entry is also a composite entry, it is further expanded until there are only singleton entries. Then, these singleton entries are added into the pool.

Once all composite entries have been expanded, there're only singleton entries in the pool. Then, singleton entries that do not meet their conditions (Template:Nbt field) are removed from the pool. After that, in the pool are only singleton entries that meet their conditions. Each singleton entry has a weight (defined by the Template:Nbt and Template:Nbt fields). The game randomly selects one weighted singleton entry from the pool as the result of a roll.

The tag entry is a special entry. Whether it is a singleton or composite entry is determined by the Template:Nbt field. If Template:Nbt is Template:Cd, it is a composite entry that expands into multiple singleton entries like item but do not apply item modifiers due to a bug<ref name="MC212671">Template:Bug</ref>.

The format of an entry is:

• Template:Nbt The root.
  • Template:Nbt: Type of the entry as a Minecraft:resource location.
  • Extra fields of the entry, described below.

The possible values for Template:Nbt and associated extra fields are listed below.

Singleton entry

Fields common to all singleton entries:

• • Template:Nbt: (Optional) A list of predicates that must all pass for this singleton entry to be included into the pool. If any predicate is not satisfied, the singleton entry is removed from the pool before rolling.
    • Template:Nbt A Minecraft:predicate.
  • Template:Nbt: (Optional) Applies item modifiers in order, onto all item stacks dropped by this singleton entry.
    • Template:NbtTemplate:Nbt An Minecraft:item modifier.
  • Template:Nbt: (Optional. Defaults to 1) Determines how often this singleton entry is chosen out of all the singleton entries in the pool. Entries with higher weights are used more often. The chance of an entry being chosen is [this entry's weight ÷ total weight of all entries in the pool].
  • Template:Nbt: (Optional. Defaults to 0) Modifies this singleton entry's Template:Cd based on the level of luck (including luck attribute and fishing_luck_bonus on fishing tool). Formula is Template:Cd. Due to known bugs, this does not work in some contexts<ref name="luck"/>.
  • Even more extra fields of the entry, described below.

Possible singleton entries:

• item — Drops a single item stack. The default, if not changed by item modifiers, is a stack of 1 of the item with its default Minecraft:data components.
  • Template:Nbt: The Minecraft:resource location of the item, e.g. Template:Cd.

• loot_table — Drops the loot from another loot table.
  • Template:Nbt: Template:Json ref The loot table to be used. Cannot be the ID of the current loot table file. Recursive calling is not allowed.

• dynamic — Drops block-specific loot.
  • Template:Nbt: Can be Template:Cd which drops the items in a Minecraft:shulker box, or Template:Cd which drops the sherds of a Minecraft:decorated pot. Does not work for other blocks.

• empty — Drops nothing.

Tag entry

If Template:Nbt is Template:Cd, it is a singleton entry:

• When selected in a roll, generates item stacks for all items in the specified item Minecraft:tag. The default, if not changed by item modifiers, each item stack is 1 item with its default Minecraft:data components.

If Template:Nbt is Template:Cd, it is a composite entry:

• Expands into multiple singleton entries with the specified weight and conditions, for each item in the item Minecraft:tag. The item count of each item stack is 1, and each item is generated with its default Minecraft:data components. Item modifiers do not work<ref name="MC212671"/>.

• tag
  • Template:Nbt: The Minecraft:resource location of the item tag to query, e.g. Template:Cd.
  • Template:Nbt: If Template:Cd, provides one singleton entry per item in the tag with the same weight and conditions. If Template:Cd, it is a singleton entry that drops all items in the tag.
  • Template:Nbt: (Optional) A list of predicates that must all pass for this singleton entry to be included into the pool. If any predicate is not satisfied, the singleton entry is removed from the pool before rolling.
    • Template:Nbt A Minecraft:predicate.
  • Template:Nbt: (Optional) Applies item modifiers in order, onto all item stacks dropped by this singleton entry.
    • Template:NbtTemplate:Nbt An Minecraft:item modifier.
  • Template:Nbt: (Optional. Defaults to 1) Determines how often this singleton entry is chosen out of all the singleton entries in the pool. Entries with higher weights are used more often. The chance of an entry being chosen is [this entry's weight ÷ total weight of all entries in the pool].
  • Template:Nbt: (Optional. Defaults to 0) Modifies this singleton entry's Template:Cd based on the level of luck (including luck attribute and fishing_luck_bonus on fishing tool). Formula is Template:Cd. This does not work in some context, due to bugs<ref name="luck"/>.

Composite entry

Fields common to all composite entries:

• • Template:Nbt: (Optional) A list of predicates that must all pass for this composite entry to expand and its children to be added into the pool. If any predicate is not satisfied, the composite entry is ignored, so, no entry is added into the pool.
    • Template:Nbt A Minecraft:predicate.
  • Template:Nbt: (Optional) The list of entries. Both singleton and composite entry are allowed.
    • Template:Nbt An entry.

Possible composite entries:

• group — All entries in the Template:Nbt are extracted. Can be used for convenience, e.g. if one condition applies for multiple entries.

• alternatives — Extracts only the first successful (conditions are met) entry. Conditions are checked in order.

• sequence — Extracts the child entries in sequential order, continuing until an entry's conditions fail, then no more children are extracted.

Number provider

Template:Main Loot tables use number providers in some places that accept an Template:Nbt or Template:Nbt.

Loot context types

Template:Main The Template:Nbt field is used when loading the data pack to check whether the context parameters used by this loot table match the specified context type. The field makes it possible to check for errors in the loot table files without applying them in-game. If the loot table is used for a specific context, specifying the type field allows the game to check whether the loot table file uses parameters that are not provided in that context.

History

External links

• Loot Table Generator on misode.github.io