Custom Drops

The Custom Drops lets you decide which block, mob or even fishing drops what. There are three configuration files for this feature:

blocksdrops.conf for blocks;
mobsdrops.conf for mobs;
fishingdrops.conf for fishing.

By default, Custom Drops are disabled (like all this plugin’s features). To enable it, go into the plugin’s configuration directory and open the configuration file of the wanted feature, then set enabled on true; that’s it!

Now that you have enabled this feature, you can start configuring it.

From now on, we will only talk about the blocks, but everything also applies to mobs (the options are the same), so instead of blocks, you would use mobs.

Fishing is a bit different and directly takes a list of loots.

Defining Custom Drops

Now, make a new category called blocks, inside it you can put any category you want as long as the key is a full or partial ID, e.g. "minecraft:iron_ore" (be sure to include the quotes!).

The file should look like this:

enabled=true
blocks {
  "minecraft:iron_ore" {
  }
}

Then, we can define a custom drop inside the drops array. Since this is an array, we can put as many objects as we want:

enabled=true
blocks {
  "minecraft:iron_ore" {
    drops=[
    ]
  }
}

Inside the drops array we create an object (category) with the property type (the Minecraft item ID of the item to drop).

We can also add a chance, which will define the chance of dropping this item, but this is optional.

enabled=true
blocks {
  "minecraft:iron_ore" {
    drops=[
      {
        type="minecraft:cobblestone"
        chance=25
      }
    ]
  }
}

You can stop here if you only want to drop a cobblestone 25% of the time we break an iron ore, but we can go further by giving experience for breaking the ore:

enabled=true
blocks {
  "minecraft:iron_ore" {
    experience=5
    drops=[
      {
        type="minecraft:cobblestone"
        chance=25
      }
    ]
  }
}

You can also totally replace all the drops from a block by using overwrite:

enabled=true
blocks {
  "minecraft:iron_ore" {
    experience=5
    overwrite=true
    drops=[
      {
        type="minecraft:cobblestone"
        chance=25
      }
      {
        type="minecraft:ingot"
      }
    ]
  }
}

The same goes for experience with exp-overwrite.

You can also define the quantity of one loot to drop with quantity by using a min-max syntax:

enabled=true
blocks {
  "minecraft:iron_ore" {
    experience=5
    overwrite=true
    drops=[
      {
        type="minecraft:cobblestone"
        chance=25
      }
      {
        type="minecraft:ingot"
        quantity=2-4
      }
    ]
  }
}

One last thing, you can set the loot’s displayname, with & color codes support. You can have a reference of all available color codes here and formatting codes here.

You will just have to replace § by &:

enabled=true
blocks {
  "minecraft:iron_ore" {
    experience=5
    overwrite=true
    drops=[
      {
        type="minecraft:cobblestone"
        chance=25
      }
      {
        type="minecraft:ingot"
        displayname="&7&oSilver"
        quantity=2-4
      }
    ]
  }
}

Note: if you place a color code after a formatting code, the formatting will be reset.

It is also possible to execute commands:

blocks {
  "minecraft:iron_ore" {
    # For a single command you can write
    commands="say {player.name} just mined an iron ore."
    # For several commands
    commands=[
      "say {player.name} just mined an iron ore."
      "give {player.name} minecraft:wool"
    ]
    # You can also decide what sends the command and apply requirements
    commands {
      command="help"
      # Can be either SERVER or PLAYER. Default is SERVER
      as=PLAYER
      # This will only send this command if the player is in MyRegion
      requirements {
        griefprevention {
          list-type=WHITELIST
          regions=[
            "MyRegion"
          ]
        }
      }
    }
    # You can put as many as you want
    commands=[
      {
        command="help"
        as=PLAYER
      }
      {
        command="list"
        as=PLAYER
      }
    ]
  }
}

If you need a single type of block to have different loots you can use a list instead of a category.

All items of the list whose requirements are fulfilled are processed.

enabled=true
blocks {
  "minecraft:iron_ore"=[
    {
      requirements.worlds="world1"
      drops="minecraft:stone"
    }
    {
      requirements.worlds="world2"
      drops="minecraft:dirt"
    }
  ]
}

Requirements

Requirements are conditions that must be fulfilled for a CustomLoot or a reuse to be processed.

They are usually put in a property named requirements, and each requirement is a property where the key is the id of the requirement and the value its configuration, which can be anything and depends on the requirement.

A typical requirement would look like this:

blocks {
  "minecraft:stone" {
    requirements {
      # There can be as much requirements as you want
      # All of them must be fulfilled for the loot to be processed
      a_requirement {
        config-key="value"
      }
    }
  }
}

You can make several requirement groups. In this case only one of the group needs to be fulfilled for the processing to take place.

blocks {
  "minecraft:stone" {
    requirements=[
      # This block is a group, all its requirements needs to be fulfilled for it to be fulfilled
      # If this group is fulfilled then the loot is processed without testing the next group
      {
        a_requirement {
          config-key="a possible value"
        }
        b_requirement="required value"
      }
      # If the previous group was not fulfilled then this one is tested and if fulfilled, the loot will be processed
      {
        a_requirement {
          config-key="another possible value"
        }
      }
    ]
  }
}

The following are available out of the box:

Biomes

Restricts a loot to specific biomes.

For example, to limit iron_ore custom loot to plains and oceans:

blocks {
  "minecraft:iron_ore" {
    requirements {
      biomes=["minecraft:plains", "minecraft:ocean"]
    }
  }
}

Data

Checks data (e.g. skull type can be of a player, skeleton, zombie…) present on some game objects (blocks and entities are supported).

The id will depend on the CustomLoot source:

for MobsDrops it will be entity_data
for BlocksDrops it will be block_data

You can have something like this:

blocks {
  "minecraft:skull" {
    requirements {
      block_data {
        "skull_type"="minecraft:ender_dragon"
      }
    }
  }
}

Enchantments

Checks if the used item enchantments respects configured constraints:

blocks {
  "minecraft:iron_ore" {
    requirements {
      enchantments {
        # The items must have the efficiency enchantment
        "minecraft:efficiency"=any
        # The items must have efficiency 5
        "minecraft:efficiency"=5
        # The items must have efficiency 1 or 3
        "minecraft:efficiency"=1;3
        # The item must NOT have efficiency
        "minecraft:efficiency"=disallow
        # The item must not have efficiency 1, 2 or 3 
        "minecraft:efficiency".disallow=1-3
      }
    }
  }
}

Permissions

Checks if the player that caused the loot to drop has the configured permission.

This configuration accepts a string or an array of string which are the permissions.

The player only needs to have one of the configured permissions to fulfill the requirement.

It looks like this:

blocks {
  "minecraft:iron_ore" {
    requirements {
      permissions="a_permission"
      # OR
      permissions=[
        "some_permission"
        "another_permission"
      ]
    }
  }
}

Worlds

Checks if the player that caused the loot to drop is in a configured world.

This configuration accepts a string or an array of string which can be the world name or the world unique id (can be mixed in the same array).

The player must be in one of the configured worlds to fulfill the requirement.

It looks like this:

blocks {
  "minecraft:iron_ore" {
    requirements {
      # vanilla overworld
      worlds="world"
      # OR
      worlds=[
        "world"
        # Another world unique id
        "dd944dc4-c21f-4093-a25f-2a52849be551"
      ]
    }
  }
}

Protected regions

Checks if the broken block or killed mob is within specified regions.

For now, GriefPrevention claims and UniverseGuard regions are supported.

Reuse

What if you want to reuse drops ? Well, you can !

The reuse category lets you decide what to do with original drops while keeping the items properties intact.

Note that if overwrite is set to true (see above), items will not be reused.

enabled=true
blocks {
  "minecraft:iron_ore" {
    experience=5
    # If 'true' we would not be able to reuse drops
    # You can omit this property since its default value is 'false'
    overwrite=false
    reuse {
      # Fallback multiplier used for all drops not covered in 'items', optional
      multiplier=2
      items {
        "minecraft:iron_ore".quantity=1-3
        # OR you can set a multiplier
        "minecraft:iron_ore".multiplier=3
      }
    }
  }
}

Reuses can also have requirements.

It would look like this:

# In this example, players can be miners
blocks {
  "minecraft:iron_ore" {
    reuse {
      requirements {
        # Miners have the permission jobs.miner
        permissions="jobs.miner"
      }
      # Iron ore blocks will drop 2 ores only if the player is a miner (has the permission jobs.miner)
      multiplier=2
    }
  }
}

Recipient

The recipient is what receives drops, two are built-in:

context-location: the default one, drops will be spawned in the world where the triggering action took place
player-inventory: will place drops in the inventory of the player that did the action
- if no player is responsible for the loot then it will be dropped in the world like context-location

If a loot does not use context-location, it will also redirect base drops to this recipient. This behaviour can be disabled by setting base-drops-to-recipient to false.

enabled=true
blocks {
  "minecraft:iron_ore" {
    recipient=player-inventory
    base-drops-to-recipient=false
    # An alternative form for defining a recipient, can be used to configure it
    recipient {
      id=some-recipient
      some-config="a value"
    }
  }
}

Economy support

You can set a given amount of money to give to players when breaking a block or killing an entity.

Let’s reuse the previous example:

enabled=true
blocks {
  "minecraft:iron_ore" {
  }
}

Now you can add the money category with the amount property to the block’s property:

enabled=true
blocks {
  "minecraft:iron_ore" {
    money {
      amount=5-15
    }
  }
}

The plugin also supports multiple currencies, you can use the currency property. The value is an ID in the format pluginid:singular_currency_name and must be surrounded with quotes, if not set it will use the default currency:

enabled=true
blocks {
  "minecraft:iron_ore" {
    money {
      amount=5-15
      currency = "economylite:coin"
    }
  }
}

This will add between 5 or 15 of the default currency to the player’s account.

You can also set a chance to give the previously configured amount of money, and a message to display when it has been successfully given:

enabled=true
blocks {
  "minecraft:iron_ore" {
    money {
      amount=5-15
      currency = "economylite:coin"
      chance=50
      message="&aYou earned {money_amount}"
    }
  }
}

Integrations

Some plugins allows you to store snapshots of items and clone them as much as you want.

Box O’ Utils can use saved items of such plugins as drops, right now two plugins are supported: FileInventories and ByteItems.

To use one of these plugins you have to add a provider besides a type.

FileInventories

Ore Page

Provider: provider = "file-inv"

type is the ID of the FileItem.

ByteItems