Chest Settings Documentation

This page explains how to use the ChestSettings.yml file for full control over chest loot on your server, for all skill levels.
It covers what each feature does, why you'd use it, YAML basics, all options (old and new), copy-paste examples, common errors, and troubleshooting.
By the end, you'll know how to make any chest you want.

1. What Is ChestSettings.yml?

This file tells the plugin what to put in every chest on your server.
You can:

You set everything in this YAML file, if you mess up the YAML, the plugin might not load, so follow the formatting!

Location:
File can be found here:
plugins/SkyGrid/SkygridBlocks/ChestSettings.yml

2. How Chests Get Filled (The Basics)

When the plugin wants to fill a chest:

  1. Find the right config.
    • Looks at the biome where the chest is.
    • Finds all configs in ChestSettings with a matching biome in their Biomes list.
    • Picks one (random if multiple; you can weight them).
  2. Decide how to fill it.
    • If it uses Items, it's a custom loot chest.
    • If it uses LootTables, it's a vanilla loot chest (or a mix).
  3. Fill the chest.
    • For custom loot, each empty slot is filled by picking a random item, using weights.
    • Each item's MaxAmount and MinAmount control the total for that chest.
    • You can set up per-chest chances (so some items only appear sometimes).
    • If using vanilla loot tables, the chest uses Minecraft's normal loot rules for that table.

3. YAML Basics (Don't Skip!)

YAML is super picky!
If you make a mistake (wrong indent, use of tabs, missing quotes), the plugin may not load your config.

4. Where To Find Item/Biome/Enchantment Names

ALWAYS use exact names as found here:

Names are in ALL_CAPS, with underscores for spaces.
Examples: DIAMOND_SWORD, DARK_OAK_FOREST, FORTUNE, SIMPLE_DUNGEON

5. Top-Level Option: MaxItemsPerSlot

This goes at the very top of your file.
It controls the most of one item that can go in a single chest slot.
It only works with custom loot (not vanilla loot tables).

Example: MaxItemsPerSlot: 3

6. Custom Loot Tables (Custom Items)

You have two ways to write custom loot:

A. Compact Format (Simple, Quick)

Each item is written as a string.
Format:

What do the parts mean?

Examples:

ChestSettings:
  BasicChest:
    Items:
      - DIAMOND:10:1-3        # 10 weight, 1-3 diamonds total
      - STICK:50:5            # 50 weight, 1-5 sticks total
      - APPLE:2p:1-4          # 2% per-chest chance for 1-4 apples
      - AIR:100:1             # AIR (filler), makes rare stuff rarer
    Biomes: [FOREST, PLAINS]

Why use AIR as filler?
Adding AIR with a high weight makes your rare items even rarer.
If most picks land on AIR, the other stuff will show up less often.

B. Expanded Format (Advanced, All Options)

You can set weights, per-chest chances, custom names, enchantments, level type, and more.

Structure: Each item gets a block under Items.
You set as many options as you need.
Here are all options, with explanations:

Example (all features):

ChestSettings:
  FancyChest:
    Items:
      - GOLDEN_APPLE:
          - Weight: 5
          - MinAmount: 1
          - MaxAmount: 2
          - CustomName: "§6Golden Snack"
      - ENCHANTED_BOOK:
          - Weight: 2
          - Enchantments:
              - SHARPNESS:
                  - Weight: 100
                  - MinLevel: 3
                  - MaxLevel: 5
              - FORTUNE:
                  - Weight: 50
                  - MinLevel: 1
                  - MaxLevel: 2
      - IRON_SWORD:
          - ChancePerChest: 3     # Only a 3% chance this chest has a sword!
          - MaxAmount: 1
          - CustomName: "§fKnight's Blade"
          - LevelType: Roman
          - Enchantments:
              - FIRE_ASPECT:
                  - Weight: 70
                  - MinLevel: 1
                  - MaxLevel: 2
                  - LoreColor: RED
      - BREAD:
          - Weight: 30
          - MinAmount: 1
          - MaxAmount: 5
      - AIR:
          - Weight: 120
    Biomes: [FOREST, PLAINS, LUSH_CAVES]

You can mix compact and expanded items in the same list.

If both Weight and ChancePerChest are set, ChancePerChest takes priority.

7. Vanilla Loot Tables (Minecraft Built-In Loot)

Want to use Minecraft's own loot instead of picking every item yourself?
Just use the LootTables section.

Each entry is a map of the loot table name (from Bukkit's LootTables) to a list with a Weight field.
This lets you randomize between different vanilla loot tables, or mix with custom chests (see next section).

Example:

ChestSettings:
  VanillaCaveChest:
    LootTables:
      - ABANDONED_MINESHAFT:
          - Weight: 100
      - BASTION_TREASURE:
          - Weight: 10
    Biomes: [DRIPSTONE_CAVES, DEEP_DARK]

Notes:

8. Mixed Pools (Combining Custom and Vanilla)

You can combine vanilla loot tables and your own custom loot tables in one chest config.
The plugin randomly picks one from the pool, based on weights.

Example:

ChestSettings:
  MixedLoot:
    LootTables:
      - SIMPLE_DUNGEON:
          - Weight: 70
      - FancyChest:          # Refers to custom chest defined elsewhere
          - Weight: 30
    Biomes: [BIRCH_FOREST]

How it works:

9. More Details & How Stuff Works

A. How Item Selection Works (Weights and ChancePerChest)

Formula:
If you have 4 items with weights 10, 10, 20, 60, the chance to pick the one with 60 is 60/100 (or 60%).

B. MinAmount and MaxAmount

C. Enchantments

D. LevelType

E. Using Filler Items (Like AIR)

Why use AIR or junk with a big weight?

10. Color Codes Table (For CustomName and LoreColor)

Use these in CustomName or LoreColor.
Put quotes around CustomName if you use §.

Color Name Code Example
BLACK §0 §0Black
DARK_BLUE §1 §1Dark Blue
DARK_GREEN §2 §2Dark Green
DARK_AQUA §3 §3Dark Aqua
DARK_RED §4 §4Dark Red
DARK_PURPLE §5 §5Dark Purple
GOLD §6 §6Gold
GRAY §7 §7Gray
DARK_GRAY §8 §8Dark Gray
BLUE §9 §9Blue
GREEN §a §aGreen
AQUA §b §bAqua
RED §c §cRed
LIGHT_PURPLE §d §dLight Purple
YELLOW §e §eYellow
WHITE §f §fWhite

11. Example: Minimum, Expanded, and Everything-On

Minimal (custom)

MaxItemsPerSlot: 3

ChestSettings:
  SimpleChest:
    Items:
      - STONE:10:1-3
    Biomes: [PLAINS]

Vanilla Loot Table

ChestSettings:
  VanillaOnly:
    LootTables:
      - ABANDONED_MINESHAFT:
          - Weight: 100
    Biomes: [LUSH_CAVES]

Everything On (full features, mix of all options)

MaxItemsPerSlot: 5

ChestSettings:
  GodChest:
    Items:
      - DIAMOND_SWORD:
          - Weight: 5
          - MinAmount: 1
          - MaxAmount: 1
          - CustomName: "§bGod Sword"
          - LevelType: Standard
          - Enchantments:
              - SHARPNESS:
                  - Weight: 100
                  - MinLevel: 4
                  - MaxLevel: 5
                  - LoreColor: RED
              - LOOTING:
                  - Weight: 60
                  - MinLevel: 1
                  - MaxLevel: 3
                  - LoreColor: GREEN
      - GOLDEN_APPLE:
          - ChancePerChest: 10
          - MinAmount: 2
          - MaxAmount: 5
          - CustomName: "§6Epic Apple"
      - AIR:
          - Weight: 100
    Biomes: [PLAINS, DESERT, FOREST]

  DungeonChest:
    LootTables:
      - SIMPLE_DUNGEON:
          - Weight: 70
      - GodChest:
          - Weight: 30
    Biomes: [LUSH_CAVES]

12. Tips, Common Mistakes, and Troubleshooting

Need more help or real-world configs? Ask on the plugin's GitHub. Screenshots, questions, and errors all help!