Creating Tokens

Here you will learn how to create tokens that can be exchanged for cosmetics, as well as how to configure item distribution filtering and the rarity system.

Token Configuration (tokens.yml)

In the tokens.yml file, you configure the token item itself and its rules.

Below are three examples:

1. Simple Token: Gives a specific item.
2. Winter Token (Whitelist): Gives only items with the "winter" tag.
3. Normal Token (Blacklist): Gives any items EXCEPT seasonal ones.

tokens:
  # Example 1: Token for specific cosmetic
  simple_token:
    item:
      display: '&6Simple Token'
      amount: 1
      material: LEATHER_HORSE_ARMOR # nexo/item-adder/craft-engine can also be used
      lore:
        - ''
        - '&9Exchange simple token!'
        - ''
      unbreakable: true
      glow: false
      hide-attributes: true
      modeldata: 10006
    cosmetic: cosmetic-id # Cosmetic ID that the player is guaranteed to receive.
    exchangeable: true # If true, the cosmetic can be converted back into a token via the menu.

  # Example 2: Winter Token (Only winter items)
  winter_lootbox:
    item:
      display: '&bWinter Voucher'
      amount: 1
      material: SNOWBALL
      lore:
        - '&7Right-Click to get'
        - '&7a random winter hat!'
      unbreakable: true
      glow: true
      hide-attributes: true
      modeldata: 0
    type: HAT # Cosmetic type for randomization.
    cosmetic: santa_hat # The icon of this cosmetic will be shown in the exchange menu as the "Result".
    exchangeable: false
    
    # Filtering System
    filter:
      mode: WHITELIST # Whitelist: give ONLY items with these tags
      tags:
        - "winter"
        - "christmas"

  # Example 3: Normal Token (Excludes seasonal items)
  normal_hat_token:
    item:
      display: '&eRandom Hat'
      amount: 1
      material: PAPER
      lore:
        - '&7Gives any hat,'
        - '&7except for seasonal events.'
      unbreakable: true
      glow: false
      hide-attributes: true
      modeldata: 101
    type: HAT
    cosmetic: fedora_hat
    exchangeable: false
    
    # Filtering System
    filter:
      mode: BLACKLIST # Blacklist: DO NOT give items with these tags
      tags:
        - "winter"
        - "halloween"
        - "summer"

Cosmetic Configuration (cosmetics.yml)

To make the filtering and rarity system work, you need to add the corresponding parameters (tags and rarity) to the cosmetic config itself.

Here is a full example of cosmetic configuration with the new parameters:

cosmetics:
  # Example of seasonal cosmetic (Drops from winter_lootbox)
  santa_hat:
    type: HAT
    permission: "ecosmetics.hat.santa"
    colored: true
    item:
      display: "&cSanta Hat"
      material: LEATHER_HORSE_ARMOR
      lore:
        - "&7Merry Christmas!"
        - ""
        - "&eRarity: Legendary"
      unbreakable: true
      glow: false
      hide-attributes: true
      modeldata: 10005
      texture: ""
      color: "#FF0000"
    
    # Drop chance (Weight).
    # 10 is rare compared to normal items (100).
    rarity: 10
    
    # Tags for token filtering
    tags: 
      - "winter"
      - "christmas"

  # Example of normal cosmetic (Drops from normal_hat_token)
  fedora_hat:
    type: HAT
    permission: "ecosmetics.hat.fedora"
    colored: true
    item:
      display: "&7Fedora"
      material: LEATHER_HORSE_ARMOR
      lore:
        - "&7Classic hat."
        - ""
        - "&eRarity: Common"
      unbreakable: true
      glow: false
      hide-attributes: true
      modeldata: 10008
      texture: ""
      color: "#333333"
    
    # High weight = drops often
    rarity: 100
    
    # No tags (or you can add "common")
    tags: []

How does the type work?

The following types are available:

• HAT
• BAG (Backpacks)
• WALKING_STICK
• BALLOON
• SPRAY
• ALL (Selects from all categories at once)

If you specified type in the token config, it turns into a Voucher (Lootbox). When used, it will give a random cosmetic of the specified type that the player does not yet have.

Filtering System (Filter)

You can limit the list of items dropped from a random token using tags. This is useful for creating seasonal tokens or separating cosmetics.

Available modes (mode):

1. WHITELIST:

   • The token will give a cosmetic that has at least one tag from the tags list.
   • Example: If you specify the winter tag, the token will only give cosmetics that also have the winter tag in their config.

2. BLACKLIST:

   • The token will give any cosmetic that has NO tags from the tags list.
   • Example: If you specify the winter tag, the token will give all hats EXCEPT winter ones.

3. NONE (or if the filter section is missing):

   • Filtering is disabled, absolutely all items of the selected type drop (except those the player already has).

Rarity System (Rarity)

When giving a random cosmetic, the plugin considers the rarity parameter specified in cosmetics.yml. This works on a Weighted Random system:

• An item with rarity: 100 will drop 10 times more often than an item with rarity: 10.
• If rarity is not specified, it defaults to 100.

Configuration recommendation:

• Common: 100
• Rare: 50
• Epic: 25
• Legendary: 10

Important Notes

• Priority: If a specific cosmetic: id is specified in the token (and type is not specified), filtering and rarity parameters are ignored - the token will give this specific item.
• Icon in Menu: If you use a random token (type), make sure to specify the ID of any existing cosmetic in the cosmetic field (e.g., the simplest hat). Its icon will be used in the exchange menu (in the result slot) so the player understands they will receive a cosmetic, not nothing.
• Exchange (Refund): If exchangeable: true, the player can return an already unlocked cosmetic and get this token back in their inventory. This is done via the cosmetics menu by pressing Shift + Left Click on an already owned item. It only works if there is space in the inventory.