Loot table

This article describes only the loot table in Java Edition.
See the official docs for the loot table in Bedrock Edition.
 

Loot tables are technical 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 experience, or dropped non-item entities such as slimes from larger slimes or silverfish from infested blocks. In /loot command, a loot table can be specified in 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 /loot command, a loot table can be specified in SNBT format.

Usage

Custom data packs use loot tables to change what loot can spawn in containers or drop by mobs. They can either change 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 File file.png: Sprite image for file in Minecraft <data pack name>/data/minecraft/loot_table/entities/zombie.json. This makes every zombie in that world use the datapack's loot table rather than the default zombie loot table.

  • File directory.png: Sprite image for directory in Minecraft archaeology: The items from brushing suspicious sand or suspicious gravel.
  • File directory.png: Sprite image for directory in Minecraft blocks: The items dropped when mining blocks.
  • File directory.png: Sprite image for directory in Minecraft chests: Loot in various structures in chests or barrels.
  • File directory.png: Sprite image for directory in Minecraft dispensers: The items inside dispensers in trial chambers.
  • File directory.png: Sprite image for directory in Minecraft entities: The loot dropped by mobs when killed.
  • File directory.png: Sprite image for directory in Minecraft equipment: The equipment of mobs spawned by trial spawner in trial chambers.
  • File directory.png: Sprite image for directory in Minecraft gameplay: Fishing, cat morning gift, piglin bartering.
  • File directory.png: Sprite image for directory in Minecraft pots: The loot inside decorated pots in trial chambers.
  • File directory.png: Sprite image for directory in Minecraft shearing: The items dropped when shearing sheep, mooshrooms or snow golems
  • File directory.png: Sprite image for directory in Minecraft spawners: 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 that certain drops, namely head drops from charged creepers and the wither's nether star, are currently not covered by loot tables.[1]

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 barrel, chest, trapped chest, hopper, minecart with chest, boat with chest, minecart with hopper, dispenser, dropper, shulker box, dyed shulker box, and decorated pot:

  • [NBT Compound / JSON Object] The root object.
    • [String] LootTable: Optional. Name of the loot table to use. If this is used in a chest-like container, the loot table generates its content when it is opened. Generating the items in the container removes both loot table tags ([String] LootTable and [Long] LootTableSeed). Is not preserved when removed.
    • [Long] LootTableSeed: Optional. Seed for generating the loot table. The default value works similarly to the seeds for worlds, where value of 0 or an omitted value causes the game to use a random seed.

For mobs:

  • [NBT Compound / JSON Object] The root object.
    • [String] DeathLootTable: Name of the loot table to be used when the mob dies. One batch of loot is generated, as defined by the loot table, and the mob drops the generated loot. Works just like [String] LootTable from Chunk format/Lootable.
    • [Long] DeathLootTableSeed: Seed for generating the loot table when the mob dies. Works just like [Long] LootTableSeed from Chunk format/Lootable.

Vault uses loot table in its config to determine the items to eject when unlocking the vault, and items to display in the vault.

Trial spawner uses loot table in its 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.

Monster spawner and trial spawner uses loot table to determine equipment the spawned mobs have.

Others

Loot table can be invoked directly by /loot command.

Loot table can also be invoked in advancement rewards.

Format

Loot tables are defined using JSON files stored within a data pack in the path data/<namespace>/loot_table.

In /loot command, a loot table can be specified in SNBT format.

  • [NBT Compound / JSON Object] The root.
    • [String] type: (Optional. Defaults to generic) Specifies the 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.
    • [NBT List / JSON Array] functions: (Optional) Applies item modifiers in order, onto all item stacks dropped by this table.
      • [NBT Compound / JSON Object][NBT List / JSON Array] An item modifier.
    • [NBT List / JSON Array] pools: (Optional) A list of all pools for this loot table. Pools are applied in order.
      • [NBT Compound / JSON Object] A pool (see below).
    • [String] random_sequence: (Optional) A 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 [NBT Compound / JSON Object] rolls and [Float][NBT Compound / JSON Object] bonus_rolls). In each roll of a pool, the pool draws one entry from all its entries. Each roll of a pool is independent.

  • [NBT Compound / JSON Object] The root.
    • [NBT List / JSON Array] conditions: (Optional) A list of predicates, that must all pass for this pool to be used.
    • [NBT List / JSON Array] functions: (Optional) Applies item modifiers in order, onto all item stacks dropped by this pool.
      • [NBT Compound / JSON Object][NBT List / JSON Array] An item modifier.
    • [Int][NBT Compound / JSON Object] rolls: A number provider. Specifies the number of rolls on the pool.
    • [Float][NBT Compound / JSON Object] bonus_rolls: (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 Luck status effect, and fishing_luck_bonus is from the Luck of the Sea enchantment. This does not work in some context, due to bugs[2].
    • [NBT List / JSON Array] entries: 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.
      • [NBT Compound / JSON Object]: 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. Singleton entries have their weight. Each roll selects a weighted singleton entries 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 ([NBT List / JSON Array] conditions 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 [Int] weight and [Int] quality 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 [Boolean] expand field. If [Boolean] expand is true, it is a composite entry that expands into multiple singleton entries like item but do not apply item modifiers due to a bug[3].

The format of an entry is:

  • [NBT Compound / JSON Object] The root.
    • [String] type: Type of the entry as a resource location.
    • Extra fields of the entry, described below.

The possible values for [String] type and associated extra fields are listed below.

Singleton entry

Fields common to all singleton entry:

    • [NBT List / JSON Array] conditions: (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.
    • [NBT List / JSON Array] functions: (Optional) Applies item modifiers in order, onto all item stacks dropped by this singleton entry.
      • [NBT Compound / JSON Object][NBT List / JSON Array] An item modifier.
    • [Int] weight: (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].
    • [Int] quality: (Optional. Defaults to 0) Modifies this singleton entry's weight based on the level of luck (including luck attribute and fishing_luck_bonus on fishing tool). Formula is max(floor(weight + (quality × luck)),0). This does not work in some context, due to bugs[2].
    • 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 data components.
  • loot_table — Drops the loot from another loot table.
    • [String] value: One (an [String] ID, or a new [NBT Compound / JSON Object] loot table definition) 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.
    • [String] name: Can be contents which drops the items in a shulker box, or sherds which drops the sherds of a decorated pot. Does not work for other blocks.
  • empty — Drops nothing.

Tag entry

If [Boolean] expand is false, it is a singleton entry:

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

If [Boolean] expand is true, it is a composite entry:

  • Expands into multiple singleton entries with the specified weight and conditions, for each item in the item tag. The item count of each item stack is 1, and each item is generated with its default data components. Item modifiers do not work[3].
  • tag
    • [String] name: The resource location of the item tag to query, e.g. minecraft:arrows.
    • [Boolean] expand: If true, provides one singleton entry per item in the tag with the same weight and conditions. If false, it is a singleton entry that drops all items in the tag.
    • [NBT List / JSON Array] conditions: (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.
    • [NBT List / JSON Array] functions: (Optional) Applies item modifiers in order, onto all item stacks dropped by this singleton entry.
      • [NBT Compound / JSON Object][NBT List / JSON Array] An item modifier.
    • [Int] weight: (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].
    • [Int] quality: (Optional. Defaults to 0) Modifies this singleton entry's weight based on the level of luck (including luck attribute and fishing_luck_bonus on fishing tool). Formula is max(floor(weight + (quality × luck)),0). This does not work in some context, due to bugs[2].

Composite entry

Fields common to all composite entry:

    • [NBT List / JSON Array] conditions: (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.
    • [NBT List / JSON Array] children: (Optional) The list of entries. Both singleton and composite entry are allowed.
      • [NBT Compound / JSON Object] An entry.

Possible composite entries:

  • group — All entries in the [NBT List / JSON Array] children 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

Loot tables use number providers in some places that accept an [Int] or [Float]. They can either be defined as a constant value or as an object.

  • [Int][Float]: Constant number provider.

Or:

  • [NBT Compound / JSON Object]: The root tag. Shorthand for a uniform distribution.
    • [Int][Float][NBT Compound / JSON Object] min: Number provider. The minimum value.
    • [Int][Float][NBT Compound / JSON Object] max: Number provider. The maximum value.

Or:

  • [NBT Compound / JSON Object]: The root tag.
    • [String] type: The number provider type as a resource location.
    • Extra fields of the number provider, described below.

The possible values for [String] type and associated extra contents:

  • constant — A constant value.
    • [Int][Float] value: The exact value.
  • uniform — A random number following a uniform distribution between two values (inclusive).
    • [Int][Float][NBT Compound / JSON Object] min: Number provider. The minimum value.
    • [Int][Float][NBT Compound / JSON Object] max: Number provider. The maximum value.
  • binomial — A random number following a binomial distribution.
    • [Int][NBT Compound / JSON Object] n: Number provider. The amount of trials.
    • [Float][NBT Compound / JSON Object] p: Number provider. The probability of success on an individual trial.
  • score — To query and use a scoreboard value.
    • [NBT Compound / JSON Object] target: To choose which player name or entity UUID to query.
      • [String] type: Set to fixed to manually specify a player name or UUID. Set to context to use an entity from loot context.
      • [String] name: Included only if [String] type is set to fixed. Specifies the name of the player, or the entity's UUID (in hypenated hexadecimal format) whose score to query.
      • [String] target: Included only if [String] type is set to context. Specifies an entity from loot context to query the score of. Can be this, attacker, direct_attacker, or attacking_player.
    • [String] score: The scoreboard objective to query on the selected player name or UUID.
    • [Float] scale: Optional. Scale to multiply the score before returning it.
  • storage — A value in command storage.
  • enchantment_level — A value dependent on the level of the loot context enchantment

Loot context types

Main article: Loot context

The [String] type 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

Java Edition
1.9October 19, 2015Dinnerbone announces loot tables.
15w43aAdded loot tables.
15w43bAdded condition entity_scores.
15w43cRenamed "villager_golem.json" to "iron_golem.json"
Added fishing loot tables, sheep without wool, and zombie and skeleton horses.
Renamed the tag [String] item: to [String] name:, and the tag [NBT Compound / JSON Object] items: to [NBT Compound / JSON Object] entries:
Added the tag [String] type: and support to load a loot table instead of an item.
Added the tag [Int] luck: to default files, though it currently does nothing in the code.
Added the function set_damage.
15w44aAdded the function enchant_randomly and set_attributes.
15w44bAdded the [Int] quality tag.
Removed [Int] luck and [Float] luck_multiplier tags.
Added the [NBT Compound / JSON Object] bonus_rolls tag.
15w51aA player in spectator mode no longer triggers a container to use its loot table to generate loot.
1.9.1pre1Loot tables now work with dispensers and droppers.
Added default table chests/jungle_temple_dispenser.
1.1116w32aDonkeys, mules, husks and zombie villagers now each draw from their own loot tables, rather than drawing from the horse and zombie loot tables, respectively
16w43aVillagers, vexes and ender dragons are now able to draw from their own loot tables.
1.1317w43aCustom loot tables have been moved into data packs.
1.1318w01aAdded the function set_name.
1.1418w43aBlock drops have been changed to use loot tables too.
Loot tables received a bunch of new options.
Setting entity to "this" now refers to the player in chest and block loot tables.
18w44aAdded loot tables for cats, cat_morning_gift, players and withers.
Added loot tables for new blocks.
Added the function set_lore.
18w46aAdded loot table for illusioners.
18w48aAdded more loot tables for villages, some of which are currently unused.
Removed loot table: village_blacksmith.
18w49avillage_savanna_house and village_snowy_house loot tables are now used.
Added more loot tables for villages.
18w50avillage_desert_house and village_taiga_house loot tables are now used, making all previously unused loot tables no longer unused.
?Empty loot table is now hardcoded.
1.1519w34aAdded the function copy_state.
1.1620w12aAdded fishing_hook sub-predicate to check properties of the fishing hook.
1.2023w12aAdded the shards dynamic drop.
23w14aAdded the function reference.
23w17aRenamed the shards dynamic drop to sherds.
23w17aAdded the loot table sniffer_digging.
pre1Made random sequences for loot tables deterministic.
Added random_sequence field.
pre6The ID of the random sequence is now an optional field.
1.20.223w32aAdded sequence loot function.
all_of predicates in loot tables can now be declared implicitly as an inline array without a type.
1.20.524w07aAdded gameplay/panda_sneeze loot table for drops when pandas sneeze.
24w09aThe name field for entry type loot_table has been renamed to value and now also accepts inline loot tables.
24w12aAdded storage loot number provider to access values from command storage.
1.2124w18aScore context target entities killer, direct_killer, killer_player were renamed to attacker, direct_attacker, attacking_player
Added enchantment_level number provider
24w21aMoved loot tables from File directory.png: Sprite image for directory in Minecraft loot_tables to File directory.png: Sprite image for directory in Minecraft loot_table
1.21.224w33aSheep shearing is now controlled by loot tables found as shearing/sheep/<color>.
Mooshroom shearing is now controlled by loot tables found as shearing/mooshroom/<variant>.
Snow golem shearing is now controlled by a loot table found as shearing/snow_golem.
24w35aSpecial loot table empty has been removed and is no longer defined in vanilla data pack.
Sheep now always uses a single loot table entities/sheep.
Wool drops are still defined in sub-tables in entities/sheep/<color>, but they are now just dispatched from the main table.
Sheep shearing is now controlled by loot table found as shearing/sheep.
Mooshroom shearing is now controlled by loot table found as shearing/mooshroom.
24w37aChickens laying eggs is now controlled by a loot table found at gameplay/chicken_lay.
Armadillos randomly dropping scutes is now controlled by a loot table found at gameplay/armadillo_shed.
The loot given by Villagers is now controlled by two additional loot tables: gameplay/hero_of_the_village/unemployed_gift and gameplay/hero_of_the_village/baby_gift.
The tool value (used for functions like match_tool) is now available for some additional loot table types.

Issues

Issues relating to "Loot" are maintained on the bug tracker. Issues should be reported and viewed there.

External links

References

  1. ↑ MC-94610
  2. ↑ a b c MC-184348
    MC-120523
    MC-262347
    MC-110336
    MC-184348
  3. ↑ a b MC-212671

Navigation

  • v
  • t
  • e
Java Edition technical
Data pack
Components
Tag
GameTest
World generation
Noise settings
Structures
Data packs
Tutorials
Content
World generation
This article is issued from Minecraft Wiki. The text is available under CC BY-NC-SA 3.0 unless otherwise noted. Additional terms may apply for the media files.