How to Make a Reward

Rewards are what players win from crates. A reward defines the effects that fire when it's won, its weight (how likely it is), and its display in previews and roll animations. This page covers making one from scratch.

Quick start

  1. Open the /rewards/ folder inside the EcoCrates plugin folder.

  2. Copy _example.yml and rename it to your reward's ID, e.g. diamond_sword.yml.

  3. Set the win-effects for what the player gets, and tune the weight.

  4. Set the display item and lore that show in the preview GUI.

  5. Add the reward's ID to a crate's rewards list, then run /ecocrates reload.

  6. Force-open the crate with /ecocrates forceopen <crate> a few times to confirm the reward can be won.

Naming and IDs

The file name without .yml is the reward's ID. This is what you list in crate configs and preview layouts. The display item and any give_item effect use the Item Lookup System format.

The structure of a reward

PartWhat it controls
BasicsThe reward name and the effects that run on win
WeightHow likely the reward is and how many times it can be won
Multiple rewardsOptional. How the reward behaves when a crate gives several rewards per open
DisplayThe item shown in the preview GUI and roll animation
# === Basics: name and what the player wins ===
name: "&bDiamond Sword" # The name of the reward
win-effects: # The effects to run when the reward is won
  - id: give_item
    args:
      item: diamond_sword sharpness:5 unbreaking:3
  - id: send_message
    args:
      message: "&fYou won the %reward% &fin %crate%&f!"

# === Weight: chance and win limits ===
weight:
  permission-multipliers: true # If permission multipliers affect this reward's chance
  value: 1 # The chance weight; supports maths and placeholders, e.g. %player_y% * 25
max-wins: -1 # Max times any player can win this reward; -1 for unlimited
max-per-open: -1 # Optional. The most times this reward can be won in one open. -1 or missing means no limit.
bonus-eligible: true # Optional. If false, this reward can only be the first reward of an open, never a bonus reward.
rerollable: true # Optional. If false, winning this reward skips the reroll offer for that pick.

# === Display: how it looks in the preview ===
display:
  name: "&bDiamond Sword" # The item name
  item: diamond_sword sharpness:5 unbreaking:3 # The shown item
  dont-keep-lore: false # Optional; true shows only the custom lore below
  lore: # Supports %chance% and %weight% placeholders
    - "&fChance: &a%chance%%"
    - "&fWeight: &b%weight%"

Basics

The reward's name and the effects that run the moment it is won.

name: "&bDiamond Sword" # The name of the reward
win-effects: # The effects to run when the reward is won
  - id: give_item
    args:
      item: diamond_sword sharpness:5 unbreaking:3
  - id: send_message
    args:
      message: "&fYou won the %reward% &fin %crate%&f!"

Weight

How likely the reward is to be picked, and a cap on how many times it can be won.

weight:
  permission-multipliers: true # If permission multipliers affect this reward's chance
  value: 1 # The chance weight; supports maths and placeholders, e.g. %player_y% * 25
max-wins: -1 # Max times any player can win this reward; -1 for unlimited

Display

The item shown for this reward in the preview GUI and roll animation.

display:
  name: "&bDiamond Sword" # The item name
  item: diamond_sword sharpness:5 unbreaking:3 # The shown item
  dont-keep-lore: false # Optional; true shows only the custom lore below
  lore: # Supports %chance% and %weight% placeholders
    - "&fChance: &a%chance%%"
    - "&fWeight: &b%weight%"

Multiple rewards

These optional keys only matter for crates and pouches that give several rewards per open with bonus-chances; see How to Make a Crate. Each reward in an open is independent, so these keys apply to every pick on its own.

max-per-open: -1 # Optional. The most times this reward can be won in one open. -1 or missing means no limit.
bonus-eligible: true # Optional. If false, this reward can only be the first reward of an open, never a bonus reward.
rerollable: true # Optional. If false, winning this reward skips the reroll offer for that pick.

Internal placeholders

PlaceholderValue
%chance%Calculated chance of this reward in the crate.
%weight%Raw weight value of this reward.
%reward%The reward display name.
%crate%The crate display name.
%bonus_chance_<n>%The chance of the n-th bonus-chances entry of the crate, for the player viewing. Reward lore only.
%max_rewards%The most rewards one open of the crate can give. Reward lore only.

Win effects can also use %reward_number%, the 1-based number of the reward within the open, and %reward_amount%, how many rewards the open gives.

Reward lore also reads other plugin placeholders, for example In existence: %ecocrates_<reward>_total% to show how many times a reward has been won. See PlaceholderAPI.


Where to go next

  • Crates: add this reward to a crate in How to Make a Crate.

  • Permissions: gate rewards with ecocrates.rewards.<reward>, see Commands and Permissions.

  • Defaults: browse the shipped example configs here.