Pages

Drop file

This page explores the anatomy and syntax of the YML files which are used to specify custom drops (such files are called "drop files").

What is a YML file?

A YML file is a text file written according to YAML specifications and given a .yml file extension. Several of these files come bundled in the /OtherDrops/ folder, but you may create your own as well.

About YAML

In YAML, data can be stored either as a list (a simple series of values) or as a map (a series of key names, each associated with some value). Curiously, in YAML, any value of a list or map can itself be another list or map! When this occurs (and this will surely occur in a drop file), indentation becomes important (see below).

Warning:
In YAML, indentation must be done with spaces rather than tab characters or else the YML file will be considered invalid. Some advanced text editors allow you to specify that the Tab key generate a series of spaces automatically; if your text editor lacks this feature, stay away from the Tab key!

Lists and Maps

Let's begin with a basic YAML example:

fruits:
  - apple
  - banana
  - cherry

In the above example, we have a one-item map in which the key fruits is given a value of a three-item list (apple, banana, cherry). Note that if you see a hyphen and a space preceding a line's normal indentation, that's a list item. If you see a colon, that's a key/value separator within a map.

A more complex, OtherDrops-related example (note that the "#" sign begins a comment line):

    DIRT:
      # Dirt sometimes drops clayballs when using a spade.
      - tool: ANY_SPADE
        drop: CLAY_BALL
        chance: 2%
      # Tiny chance of finding seeds (any tool).
      - drop: SEEDS
        chance: 0.05%
    GLASS:
      # Reclaimable under all circumstances.
      - drop: GLASS

What's going on here:

  • We begin with two key/value pairs in a map: the keys DIRT and GLASS are each given some value (see below). OtherDrops understands these keys to be objects (things from which other things can drop).
  • The value given to DIRT is a two-item list: one item of the list establishes the dropping of clayballs (see below), while the other establishes the dropping of seeds (see below). OtherDrops understands each list item to be a "drop event" (which defines what drops and under what circumstances).
    • The clayball drop event is a map consisting of three keys. OtherDrops understands these keys to be parameters which together determine how the drop event works. A drop event can contain any number of parameters (often, these will specify a tool and/or a drop item).
    • The seeds drop event is a map consisting of two keys (parameters).
  • The value given to GLASS is a one-item list: the single item of the list is a self-drop event (see below).
    • The glass self-drop event is a map consisting of one key (parameter).

(A more complicated — but also more powerful — technique of defining drop events involves the use of drop groups, but those will not be discussed on this page.)

Flow Style

Lists and maps can be written in a more compact "flow" style:

  • Instead of writing list items as indented lines with dashes, they can be written inline if they are separated with commas and surrounded with square brackets [ ].
  • Instead of writing map key/value pairs as indented lines, they can be written inline if they are separated with commas and surrounded with curly braces { }.

Let's start with a traditionally-written example in which a pickaxe breaks a storage minecart into a regular minecart and a chest:

    STORAGE_MINECART:
      - tool: ANY_PICKAXE
        drop:
          - MINECART
          - CHEST

Consider what's going on here:

  • STORAGE_MINECART is a key whose value is a single-item list (one drop event).
  • The only item of that list consists of a map which contains two key/value pairs (tool and drop).
  • The drop key is given the value of a two-item list (MINECART and CHEST).

Thus, the above code could be rewritten in any of the following ways:

    # One way (allowed because MINECART and CHEST
    # are items in a list):

    STORAGE_MINECART:
      - tool: ANY_PICKAXE
        drop: [MINECART, CHEST]

    # Another way (allowed because parameters are simply
    # map key/value pairs within some drop event):

    STORAGE_MINECART:
      - {tool: ANY_PICKAXE, drop: [MINECART, CHEST]}

    # A third way (allowed because drop events are items
    # in a list which falls under some object key):

    STORAGE_MINECART: [{ tool: ANY_PICKAXE, drop: [MINECART, CHEST] }]

The style you use is a personal choice, but example drop files will often be written in the first of the three styles above (the one with only a single set of square brackets).

Note that the drops: parameter regards a normal list such as [MINECART, CHEST] as indicating that each drop item should be dropped. It also understands curly braces, however, such that {MINECART, CHEST} would drop one or the other randomly. The curly braces technically make this a map rather than a list (MINECART and CHEST would effectively become keys with null values), but rest assured that OtherDrops knows how to make sense of this scenario.

The parts of a drop file

You hopefully now understand the following:

  • Parameters are key/value pairs in a map.
  • That map is a drop event which may be one of many items in a list of drop events.
  • That list of drop events, together with an object, form one key/value pair among what may be many key/value pairs in a map which we might call a "definitions map."

Well, there's more to a drop file than that.

The very outermost data structure in a drop file (that is, the level at which no indentation is required) is a map which one could regard as dividing the file into different sections:

Include-files

If the include-files: key is present, its value should consist of a list of files. Each of these files will then be loaded in addition to the current file (otherdrops-drops.yml is the only drop file OtherDrops loads by default, but using include-files therein directs its attention to additional drop files).

Example:

include-files:
  - includes/od-dyewool.yml
  - includes/overhaul-zarius.yml
  - my_nether_overhaul.yml

Aliases

If the aliases: key is present, its value should consist of a list of alias definitions (each alias definition itself may be a list or a map). See the Aliases page for details.

Example:

aliases:
  - &DAMAGE_ENVIRON [DAMAGE_ENTITY_EXPLOSION, DAMAGE_FIRE, DAMAGE_CONTACT, DAMAGE_DROWNING, DAMAGE_FALL, DAMAGE_SUFFOCATION]
  - &ANY_TOOL_BUT_ENVIRON
    tool: ANY
    toolexcept: *DAMAGE_ENVIRON

Note that aliases may also be defined in the definitions map below; they aren't required to be placed in an aliases: section.

Defaults

If the defaults: key is present, its value should consist of a map of some number of parameters; these parameters will be applied throughout the definitions map below unless they are overridden.

Example:

# This drop file makes bad things happen at night.
defaults:
    time: NIGHT
    lightlevel: "<12"
    regionexcept: safehouse

Note: A common mistake is to include a hyphen in front of one or more lines in the defaults section. This is incorrect because OtherDrops is expecting a map here, not a list of maps. If your defaults aren't working, make sure they're hyphen-free!

Otherdrops

Finally, it's the otherdrops: key where your definitions map should be placed. This key is required for your drop file to actually do anything.

Example:

otherdrops:
    DIRT:
      - tool: ANY_SPADE
        drop: CLAY_BALL
        chance: 2%
    GLASS:
      - drop: GLASS

Additional Examples

otherdrops:

    # Players drop zombies on death half the time.
    PLAYER: [{drop: CREATURE_ZOMBIE, chance: 50%}]

    # Spiders killed with a sword at night drop 10% of
    # the time; otherwise their normal drop applies.
    SPIDER:
      - tool: ANY_SWORD
        time: NIGHT
        drop: WEB
        chance: 10%

    # Trees drop apples (or cocoa beans from birch trees).
    SPECIAL_LEAFDECAY@GENERIC:
      - drop: APPLE
        chance: 5%
    SPECIAL_LEAFDECAY@BIRCH:
      - drop: DYE@BROWN
        chance: 5%

Error-checking

If you get errors when OtherDrops tries to use your YML file, try running your code through a YAML parser (often, the problem is an unwelcome tab character).

Because the YAML functionality supported by Bukkit and OtherDrops is a subset of the full functionality of YAML, it's possible for code to be deemed valid by a YAML parser but invalid for the purposes of OtherDrops. (Some YAML parsers may also restrict themselves to some other subset of YAML, but in general, if a YAML parser rejects the code, it probably won't work in OtherDrops.)

Further Reading