Skip to main content

What is a treasure file?

Treasure files are what determine the loot tables for BetterStructures chests. They are usually assigned to [generators](../Better Structures/creating_generators.md#treasurefilename) but they can also be set at the level of an [individual build configuration](../Better Structures/creating_structures.md#treasurefile).

These loot tables are quite powerful, but also require knowledge of some basic statistics concepts to understand.

Read about those concepts here, the rest of the page assumes you understand them!

Weighted probability

BetterStructures and EliteMobs (another plugin by the same author) both use the concept of weighted probability in their loot systems. This is to solve a simple problem: how can you set the chance of picking one item from a list of potentially infinite items?

Weighted probability solves this issue by giving each item a weight. If you have 100 items and each has a weight of 1, then they all have an equal chance - 1% - of getting picked. If you add one more item, bringing the total to 101 items, you and give that last item a chance of 1, all items still have the same chance - ~0.99% - of getting picked. If you give the last item a weight of 2, the chance of it getting picked increases - the new total weight is 102, the last element has a weight of 2 and 100/102 = ~0.98% so 0.98%+0.98% = 1.96% chance of getting picked. If you give the last item a weight of 100, the new weight is 200, and since half of that weight is your new item, you new item has a 50% chance of getting picked.

As you can see, this is good to use when you might have lists of hundreds of things to randomize from.

Gaussian distribution

A gaussian distribution is a bell-shaped mathematical function.

You might be wondering how this is relevant to the loot system. One thing BetterStructures has to decide when setting loot in chests is just how much loot appears in those chests. The amount should be consistently around a specific number, but ideally not so predictable that opening a chest might become less exciting.

To achieve this semi-random effect, gaussian distribution is used to randomize how many items are picked. Once this amount is picked, the weighted probability picks one element from the rarity table at random and taking the weights into account.

So how does the gaussian distribution work?

Fortunately, you don't have to worry about how the math behind it works, and can instead focus on the two settings that modify it: mean and standard deviation.

Mean

To put it simply, mean sets the middle of the gaussian curve, which means it sets the most likely amount of items that will appear in a chest. Essentially, if you want your chests to usually have 5 items, set your mean to 5.

Standard deviation

Imagine the average number of items in a chest is 5. The standard deviation helps decide how much this number can change from one chest to another.

Small Standard Deviation (e.g., 1): This means most chests will have items very close to the average, like 4, 5, or 6 items. It's a more predictable experience. For example, if a chest has a standard deviation of 1, you can expect almost all chests to have between 4 to 6 items.

Medium Standard Deviation (e.g., 2): Here, there's more variety. Chests might have 3 to 7 items. While 5 items are still common, it's not unusual to find chests with a bit more or less. So, with a standard deviation of 2, you might occasionally find a chest with only 3 items, or if you're lucky, one with 7 items.

Large Standard Deviation (e.g., 3 or more): Now things get really surprising! Chests could have as few as 2 items or as many as 8 or more. It means you might find a chest with just a couple of items, but there's also a chance of finding a chest loaded with goodies. For instance, with a standard deviation of 3, a chest could have anywhere from 2 to 8 items, making each chest opening an exciting gamble.

The default mean is 4, and the default standard deviation is 3.

Implementation Details

Understanding how the treasure system works internally can help you configure it more effectively:

Guaranteed Minimum Items

The system guarantees that at least one item will always appear in a chest, even if the Gaussian distribution calculation would result in zero items. This prevents players from finding completely empty chests.

Random Slot Placement

Items are placed in random slots within the chest rather than filling sequentially from the first slot. This creates more natural-looking loot distribution that feels less artificial.

Error Handling

If an item material does not exist in your Minecraft version (for example, using an older config on a newer version where items were renamed), that item will be silently skipped rather than causing errors. Invalid enchantments will show a warning once in the console, then be suppressed on subsequent occurrences to avoid log spam.

Special format

Treasure files have a special format that looks like this:

isEnabled: true
mean: 4.0
standardDeviation: 3.0
items:
  common:
    weight: 60
    items:
    - amount: 1-1
      material: STONE_PICKAXE
      procedurallyGenerateEnchantments: true
      weight: 1.0
    - amount: 1-1
      material: STONE_SHOVEL
      procedurallyGenerateEnchantments: true
      weight: 1.0
  rare:
    weight: 30
    items:
    - amount: 1-1
      material: ANVIL
      weight: 6.0
    - amount: 1-6
      material: BEETROOT
      weight: 6.0
  epic:
    weight: 10
    items:
    - amount: 2-10
      material: DIAMOND
      weight: 1.0
    - amount: 1-1
      material: DIAMOND_AXE
      weight: 6.0
procedurallyGeneratedItemSettings:
  golden_sword:
    bane_of_arthropods:
      minlevel: 1
      maxlevel: 5
      chance: 0.2
    looting:
      minlevel: 1
      maxlevel: 3
      chance: 0.2

Note: this is a very trimmed down version. The full default treasure configuration, when exported to YAML, is approximately 2599 lines long as it covers extensive loot tables and every possible enchantment combination.

isEnabled

KeyValuesDefault
isEnabledBooleantrue

mean

KeyValuesDefault
meanDouble4

Set the mean. Read the details about that here.

standardDeviation

KeyValuesDefault
standardDeviationDouble3

Set the standardDeviation. Read the details about that here.

items

This is where it gets a tricky, as many of the options can be set by admins. Let's zoom in on the configuration file example from earlier.

items:
  common:
    weight: 60
    items:
    - amount: 1-1
      material: STONE_PICKAXE
      procedurallyGenerateEnchantments: true
      weight: 1.0
    - amount: 1-1
      material: STONE_SHOVEL
      procedurallyGenerateEnchantments: true
      weight: 1.0
  rare:
    weight: 30
    items:
    - amount: 1-1
      material: ANVIL
      weight: 6.0
    - amount: 1-6
      material: BEETROOT
      weight: 6.0

Here, you can see that under the items configuration key we have a map with common and rare. These are rarities!

rarities​

Rarities do not have a fixed name. You can add or remove them, and customize them as much as you want, as long as you use the same format.

Note that what makes these rarity tables more or less rare is the weight of the loot table!

By default:

  • common has a default weight of 60
  • rare has a default weight of 30
  • epic has a default weight of 10

Making common items 6x more likely to drop than epic items. You can read more about weights here!

Aside from the weight, each rarity table has its own list of items.

rarity items​

Rarity items are a map list which lists all the items that the rarity table has.

There items have the following settings:

KeyValuesDefault
amountmin-max Integervariable
materialMaterialvariable
procedurallyGenerateEnchantmentsBooleanvariable
weightDoublevariable

amount​

Sets the amount to drop. This can be expressed as a range amount: MIN-MAX or as a single value amount: VALUE for fixed amounts. Examples:

  • Variable amount: amount: 1-5 (drops between 1 and 5 items)
  • Fixed amount: amount: 3 (always drops exactly 3

material​

Sets the material using the Spigot API names of the item to potentially drop.

Special case - serialized​

When using the lootify command, instead of a material lootify will provide a serialized setting. This is automatically generated by the plugin and should not be manually generated. Is it in a format that is no human-readable.

mmoitem​

Sets a custom item from the MMOItems plugin. This is an alternative to the material field for using custom items instead of vanilla Minecraft materials.

The format is: mmoitem: TYPE@ITEMNAMEExample:yml- amount: 1-1 mmoitem: SWORD@Excalibur weight: 1.0Note: This requires the MMOItems plugin to be installed. If MMOItems is not available or the specified item does not exist, the entry will be skipped with a warning in the console logs.

info​

Optional field for adding notes or comments to item entries. This field is completely ignored by the plugin and exists solely for administrative documentation purposes. Use it to remind yourself why certain items are configured in specific ways.

Example:yml- amount: 1-1 material: DIAMOND_SWORD weight: 1.0 info: "Rare drop for completing the dungeon"***

weight​

Sets the weight for the weighted chance. More about that here.

procedurallyGenerateEnchantments​

Sets whether the item should be procedurally generated based on the settings in procedurallyGeneratedItemSettings. Note that based on the settings this might result in an item generating without enchantments regardless.

procedurallyGeneratedItemSettings

Let's take another look at our configuration file example:

procedurallyGeneratedItemSettings:
  golden_sword:
    bane_of_arthropods:
      minlevel: 1
      maxlevel: 5
      chance: 0.2
    looting:
      minlevel: 1
      maxlevel: 3
      chance: 0.2

As you can see, this file lists material types, followed by enchantments and then followed by minimum and maximum levels and a chance.

Note that you can not add custom materials from other plugins in these settings, and you are probably not able to add custom enchantments from other plugins unless their author explicitly say they have made their system compatible.

As for the enchantment settings:

KeyValuesDefault
minlevelIntegervariable
maxlevelIntegervariable
chanceChancevariable

minlevel​

Sets the minimum enchantment level.

maxlevel​

Sets the maximum enchantment level.

chance​

Sets the probability of the enchantment being applied, as a decimal value between 0.0 (never) and 1.0 (always). For example, a value of 0.2 means a 20% chance. This uses a simple probability check, not weighted probability like the item selection system.

Troubleshooting

Items not appearing in chests

  • Verify the treasure file has isEnabled: true
  • Check console for warnings about invalid materials or items
  • Ensure MMOItems is installed if using custom items
  • Materials must use exact Spigot API names

Enchantments not applying

  • Set procedurallyGenerateEnchantments: true on the item
  • Verify enchantment names match Minecraft's namespaced keys
  • Check that min/max levels are within valid ranges for that enchantment
  • Remember that chance values are probabilities (0.2 = 20%), not guarantees

Custom plugin enchantments not working

Only custom enchantments that explicitly support BetterStructures integration will work. Check with the enchantment plugin's author about compatibility. Invalid enchantments will show a warning in console suggesting this possibility.

Empty chests appearing

This should not happen as the system guarantees at least one item. If you are seeing empty chests, verify:

  • The chest is being populated by BetterStructures (not another plugin)
  • All items in your treasure file are valid (check console warnings)
  • The treasure file is actually being loaded (check startup logs)