Rewards

This is the core file of CatzUtils where you define all possible rewards. This guide explains how to structure rewards for different actions and details every reward type available.

General Structure

The file is organized into main categories based on the action that triggers the reward. Each category holds specific triggers (like a mob name or a block type).

• reward-mobs: For rewards from killing mobs.

• reward-blocks: For rewards from breaking blocks.

• reward-fishing: For rewards from fishing.

• reward-player-kill: For rewards from killing other players.

Reward Group Breakdown

Under each category, you define a "reward group" for a specific trigger (e.g., zombie, diamond_ore). Each group contains a list of potential rewards and an optional list of effects.

Example:

zombie:
  rewards:
    - type: "money"
      amount: 25.50
      chance: 75.0
    - type: "item"
      identifier: "ROTTEN_FLESH"
      amount: 2
      chance: 100.0
  # (Optional) A list of visual/audio effects to play when ANY reward is given.
  effects:
    - "particle FLAME"
    - "sound ENTITY_ZOMBIE_DEATH"

Reward Types

This is the most powerful feature of rewards.yml. The type key determines what kind of reward is given.

Type	Required Keys	Description
money	amount, chance	Gives the player a specified amount of money. Requires Vault.
item	identifier, amount, chance	Gives a vanilla Minecraft item. The identifier must be a valid Material name (e.g., DIAMOND).
customitem	identifier, amount, chance	Gives a custom item defined in your items.yml file. The identifier is the key from that file (e.g., gold_coin).
itemsadder	identifier, amount, chance	Gives a custom item from ItemsAdder. The identifier is the item's ID from ItemsAdder.
oraxen	identifier, amount, chance	Gives a custom item from Oraxen. The identifier is the item's ID from Oraxen.
nexo	identifier, amount, chance	Gives a custom item from Nexo. The identifier is the item's ID from Nexo.
command	command, chance	Executes a console command. You can use placeholders like %player%, %mob%, %block%, etc..
exp	amount, chance	Gives the player a specified amount of experience points.
effect	effect, chance	Gives the player a potion effect. The format is "EFFECT_TYPE DURATION_SECONDS [AMPLIFIER]" (e.g., "REGENERATION 10 2").

Custom Reward Messages

You can add an optional message section inside any individual reward to override the default message for that specific reward.

Example:

- type: "customitem"
  identifier: "explosive_arrow"
  amount: 2
  chance: 15.0
  message:
    type: "TITLE" # Can be CHAT, ACTION_BAR, or TITLE
    text: "&c&lRARE ITEM!|&e+%amount% Explosive Arrows"
    sound: "UI_TOAST_CHALLENGE_COMPLETE"

Detailed Reward Examples

Below are examples for each reward type to help you understand how to configure them.

Money Reward (money)

Gives the player money via Vault.

stone:
  rewards:
    - type: "money"
      # The amount of money to give.
      amount: 10.50
      # The chance of this reward dropping (0.0 to 100.0).
      chance: 5.0

Vanilla Item Reward (item)

Gives the player a standard Minecraft item.

diamond_ore:
  rewards:
    - type: "item"
      # The item's Material ID (must be uppercase).
      identifier: "DIAMOND"
      # The number of items to give.
      amount: 1
      chance: 10.0

Custom Item Reward (customitem)

Gives a custom item that you have defined in items.yml.

emerald_ore:
  rewards:
    - type: "customitem"
      # The ID of your custom item from items.yml.
      identifier: "power_crystal"
      amount: 1
      chance: 1.5

Item Plugin Reward (itemsadder, oraxen, nexo)

Gives a custom item from a supported plugin.

pig:
  rewards:
    - type: "itemsadder"
      # The item's ID from ItemsAdder (namespace:id).
      identifier: "pig_feet"
      amount: 1
      chance: 5.0

Command Reward (command)

Executes a command from the console. Placeholders are very powerful here.

blaze:
  rewards:
    - type: "command"
      # The command to execute. Placeholders will be replaced.
      command: "broadcast %player% just defeated a powerful Blaze at %x%, %y%, %z%!"
      chance: 100.0

Experience Points Reward (exp)

Gives the player EXP points.

zombie:
  rewards:
    - type: "exp"
      # The amount of experience points to give.
      amount: 10
      chance: 50.0

Potion Effect Reward (effect)

Applies a potion effect to the player.

witch:
  rewards:
    - type: "effect"
      # Format: "EFFECT_TYPE DURATION_IN_SECONDS [AMPLIFIER]"
      # This gives Regeneration II for 10 seconds.
      effect: "REGENERATION 10 2"
      chance: 20.0

Complex Example (Multiple Rewards & Custom Message)

You can assign multiple, different reward types to a single action. Each reward is rolled independently based on its own chance.

creeper:
  rewards:
    # Reward 1: Money
    - type: "money"
      amount: 50.00
      chance: 70.0

    # Reward 2: Vanilla Item
    - type: "item"
      identifier: "GUNPOWDER"
      amount: 4
      chance: 100.0

    # Reward 3: A rare custom item with its own special message
    - type: "customitem"
      identifier: "explosive_arrow"
      amount: 2
      chance: 15.0
      message:
        type: "TITLE"
        text: "&c&lRARE ITEM!|&e+%amount% Explosive Arrows"
        sound: "UI_TOAST_CHALLENGE_COMPLETE"
  
  # Global effects that play if any of the rewards above are given
  effects:
    - "particle EXPLOSION_LARGE"
    - "sound ENTITY_CREEPER_DEATH"