Chest Settings Documentation

The ChestSettings.yml file is the heart of the plugin’s configuration. It controls how items are chosen and placed into chests across your server. The plugin uses a weight-based random selection system to fill empty chest slots and supports two configuration styles:

This documentation covers every aspect of the configuration—from the basic mechanics to advanced customization options—and provides links to external resources so you can learn more about the valid IDs and properties.

1. How the Plugin Works

A. Overview of the Process

  1. Chest Detection:
    When the plugin is triggered (for example, when a chest is generated), it first determines which chest configuration to use:

    • The chest’s block is examined and its biome is identified.
    • The plugin then checks each chest configuration (found under ChestSettings) to see if the chest’s biome is listed in its Biomes section.
      For a complete list of valid biome names, see the Bukkit Biome documentation.

  2. Item Selection:

    • The plugin scans the chest’s inventory for empty slots.
    • For each empty slot, it uses a weighted random selection:
      • Weight: Each item’s weight determines how likely it is to be chosen relative to the others.
      • MaxAmount: An item is only added until its configured maximum number is reached.
    • A random quantity (from 1 up to the remaining allowed amount) is selected and the item is placed in that slot.

  3. Item Customization:

    • Custom Names:
      Items may have a custom display name with Minecraft color codes (see section 3).
    • Enchantments:
      If enchantments are defined, each empty slot may have enchantments applied to the item based on their individual weight and level ranges.
    • Item-wide LevelType:
      A single LevelType (defined at the item level) sets how all enchantments on that item are displayed:
      • Standard: Enchantment levels are displayed as numbers prefixed with lvl_ (e.g., "lvl_1").
      • Roman: Enchantment levels are displayed as Roman numerals (e.g., "I"), but only supports values up to 3999.
      • If no LevelType is specified, the plugin defaults to Roman.

B. How Weight and Probability Work

2. YAML Formatting Options

The plugin supports two configuration styles: the Legacy Format and the New Expanded Format.

A. Legacy Format

This simple format defines items as strings with the syntax:

MATERIAL_NAME:weight:maxAmount

Example:

ChestSettings:
  Chest1:
    Items:
      - MYCELIUM:30:5
      - RED_MUSHROOM:20:5
      - BROWN_MUSHROOM:20:5
    Biomes:
      - MUSHROOM_FIELDS

B. New Expanded Format

This format uses a nested structure to provide advanced customization.

Item Properties

For each item (using the material name as the key), you can specify a list of properties:

Example:

ChestSettings:
  Chest1:
    Items:
      - MYCELIUM:
        - Weight: 30
        - MaxAmount: 5
        - CustomName: §6HolyDirt
        - LevelType: Standard
        - Enchantments:
          - FORTUNE:
            - Weight: 100
            - MinLevel: 1
            - MaxLevel: 4
            - LoreColor: RED
          - LOOTING:
            - Weight: 30
            - MinLevel: 0
            - MaxLevel: 3
            - LoreColor: BLUE
      - RED_MUSHROOM:
        - Weight: 20
        - MaxAmount: 5
      - BROWN_MUSHROOM:
        - Weight: 20
        - MaxAmount: 5
      - RED_MUSHROOM_BLOCK:
        - Weight: 10
        - MaxAmount: 5
      - BROWN_MUSHROOM_BLOCK:
        - Weight: 10
        - MaxAmount: 5
      - MUSHROOM_STEM:
        - Weight: 10
        - MaxAmount: 5
    Biomes:
      - MUSHROOM_FIELDS

In this configuration:

3. Minecraft Color Codes

A. Custom Item Names (Titles)

When setting a custom name via CustomName, you can include Minecraft color codes using the section sign (§). Below is a table of available color codes:

Color Name Minecraft Code Example Usage
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

B. Enchantment Lore Colors

For each enchantment’s LoreColor, you can use any of the above color names (e.g., RED, BLUE, GREEN). If an invalid or unrecognized color is provided, it will default to GRAY.

4. LevelType: Standard vs. Roman

The LevelType setting, defined at the item level, controls how enchantment levels are displayed in the item’s lore.

Standard Level Type:

Roman Level Type:

5. Advanced Weighting: Filler Items & Rare Items

The weight-based system allows you to fine-tune the odds of specific items appearing in a chest. This is particularly useful for making rare items even rarer.

Using Filler Items

Practical Tips

6. Additional Resources and References

For further details, refer to these resources:

7. Summary

This comprehensive guide covers all aspects of the plugin’s functionality—from the basic legacy configuration to advanced features like filler items and detailed loot odds customization. With detailed examples, resource links, and clear explanations for each option, this document should help even beginners fully understand and utilize the plugin. Happy configuring!