Collection configuration

Under the collections folder you can create or edit your collections. Every collection has to be in the folder of its category, like collections/mining/diamond.yml, where the folder name is a category id from categories.yml. The name of the yml file will be the id of the collection. Use only English letters, numbers, underscores and hyphens in the file name (dots are not allowed).

Collections are shown in the menus ordered by their file names. This is why the default fishing collections are named like 0001_cod.yml.

Here is an example default configuration:

triggers: [ block_loot ]
types:
  - "minecraft:diamond"
  - "minecraft:diamond_ore"
  - "minecraft:deepslate_diamond_ore"

name: "Diamond"

menu-item:
  material: DIAMOND

requirements:
  - 50
  - 100
  - 250
  - 1000
  - 2500
  - 5000
  - 10000

use-global-level-matchers: true

This is the most basic configuration. Let's break this down:

triggers - defines what action should trigger the collection to progress. In this case if someone breaks a block, then the collection will progress with dropped items. Here are the available triggers:

block_loot - triggered with the items when the player breaks a block. Blocks placed by players and containers (chests, furnaces, etc.) don't count. (also supports Oraxen 2.0, Nexo, MMOItems and MMOCore custom block drops). Item API can be used here to check for other plugins' custom items. (MythicMobs, Eco plugins, MMOItems, ExecutableItems, CustomFishing, Oraxen and many other plugins are supported for this)
player_kill - triggered when a player kills another player. types are not checked for this trigger.
entity_kill - triggered when a player kills an entity, eg a mob. (it supports MythicMobs with: mythicmobs:mobname and EcoMobs with: ecomobs:mob_id)
entity_loot - triggered with the items the killed entity will drop. (this also supports MythicMobs/MMOItems/Oraxen/CustomFishing item loot when a mythic mob dies)
entity_damage - triggered when a player damages a non-player entity (mob/animal) with the amount of damage being dealt. Note that the damage is floored to the nearest integer. The types field supports MythicMobs with: mythicmobs:mobname and EcoMobs with: ecomobs:mob_id
harvest - this is block loot but better for farming, since it has every right click harvestable crop and sugarcane/cactus etc also calculated properly. It would be best if you used this for every crop, like seeds, wheat, carrot, potato, pumpkin, melon, nether wart, cocoa, sugar cane, cactus, bamboo, kelp, mushrooms etc. Planted crops only count when they are fully grown.
fish - triggered with the caught items when a player successfully catches something with a fishing rod (supports CustomFishing loot with customfishing:itemname and PyroFishingPro with pyrofishing:tier:fish_number, also supports every other item plugin mentioned above)
shear_loot - triggered when a player shears an entity
block_shear_loot - triggered when a player shears a block
villager_trade - triggered with the result item when trading with villagers
minion_loot - triggered when a player takes items out of a minion. Currently only for BeeMinions, BeeMinionsRework and TopMinions integration.

types - These are the types that are makes sense for the used triggers. Here we use bukkit material names with the minecraft namespace since these are vanilla items. Every supported plugin items can be used here with the proper namespace. (MythicMobs, Eco plugins, MMOItems, ExecutableItems, CustomFishing, Oraxen and many other plugins are supported for this)

name - Name of the collection. Will be used in menus.

menu-item - This defines what the collection should look like in the menus. By default, in the other menu configuration file you can specify item templates that will be used here if enabled. Otherwise, you can use everything from Item config.

requirements - Defines how many levels are there in the collection and what are the requirements for it. Here we have 7 levels. The first level will achieved when a user reaches 50 amount, the second when reaches 100, and so on.

use-global-level-matchers - Whether to use the global level matchers defined in the main configuration or not. Default is false if omitted, so make sure to set it to true if your collection doesn't define its own level-matchers.

Optional options (see the complex example below):

permission - lock the collection behind a permission. Players without it won't progress the collection and can't open it in the menus.
multipliers - count certain item types more than once for the given triggers.
menu-title - override the title of the collection progression menu (available as {collection_title}).
custom-menu-items - extra items added to the progression menu of this collection only.
level-matchers - interval based level matchers just like the global ones in the main configuration.
custom-levels - rewards (and menu items) for specific levels.

Complex example with custom rewards

triggers: [ block_loot, minion_loot ]
types:
  - "minecraft:diamond"
  - "minecraft:diamond_ore"
  - "minecraft:deepslate_diamond_ore"
  - "eco:ecoitems:enchanted_diamond"

# You can lock the collection behind a permission
# making it not progressable until the player have the permission.
permission: "my.permission"

# Since this is a diamond collection, but enchanted diamonds is actually
# made from 160 diamonds (5x32) you can set a multipler for it.
# This means when a collection would progress with 1 enchanted diamond
# it will count as 160.
multipliers:
  - types: [ "eco:ecoitems:enchanted_diamond" ]
    triggers: [ minion_loot ]
    value: 160
  - types: [ "eco:ecoitems:enchanted_diamond_block" ]
    triggers: [ minion_loot ]
    value: 320

name: "Diamond"

# To override menu title in the collection progression menu
menu-title: "Diamond menu title"

menu-item:
  material: diamond

# These menu items will be added to the collection own menu
# where you see the levels.
custom-menu-items:
  test:
    material: cactus
    name: "&aI'm an impostor"
    slot: 1

requirements:
  - 50
  - 100
  - 250
  - 1000
  - 2500
  - 5000
  - 10000

# If you set this to true then your global matchers
# will merge with the ones here.
# The ones here will override global ones if they
# have the same key
use-global-level-matchers: true

level-matchers:
  # Override the default global matcher
  default:
    interval: 1
    priority: 0
    rewards:
      my-money-reward:
        type: money
        formula: "1000 * {level_raw}^2 - 1000 * {level_raw} + 2000"
        display: "&8+&a{value_formatted}$"
      my-xp-reward:
        type: levels_xp
        formula: "ceil(5 + 5 * ({level_raw} - 1) * (log(1 + {level_raw}) / log(2)))"
        display: "&8+&b{value_formatted} Global XP"
    # You can also override/merge menu items here for the level when this is
    # the best matcher (highest priority)
    # This is optional
    item:
      completed-level:
        material: green_stained_glass
        on-click:
          - "[console] say hi {player}"
      locked-level:
        on-click:
          - "[console] say hi {player}"
      next-level:
        on-click:
          - "[console] say hi {player}"

custom-levels:
  my-custom-level:
    level: 4
    # Optional inheritance for rewards
    inherits-from: [ default ]
    rewards: 
      my-command-reward:
        type: command
        command: "give {player} someitem"
        display: "&fYou will get some items"
  my-other-custom-level:
    level: 7
    # Optional inheritance for rewards
    inherits-from: [ default ]
    rewards: 
      my-command-reward:
        type: command
        command: "give {player} someitem"
        display: "&fYou will get some items"
    # You can override/merge the menu item shown to run commands or
    # actions when players click on it.
    # You can also override the material here or anything.
    # This is optional
    item:
      # generic level will be merged before the 3 other ones below to apply things
      # to every variant. (NOTE: list type fields are using overrides instead of merge)
      generic-level:
        on-click:
          - "[recipe] enchanted_carrot --- [player] collection progression farming carrot"
      completed-level:
        on-click:
          - "[console] say hi {player}"
      locked-level:
        on-click:
          - "[console] say hi {player}"
      next-level:
        on-click:
          - "[console] say hi {player}"