gifts.yml

Every gift lives in gifts.yml. Each top-level key is a gift, and the key is its id. After editing, run /giftsadmin reload.

Twelve gifts ship by default. A walkthrough of adding one is in Creating Gifts; this page is the full field reference.

Gift fields

common-1:
  Enabled: true
  Slot: 10
  Required-Playtime: "10m"
  Name: "&a&lCommon Gift"
  Icons:
    Locked: { … }
    Claimable: { … }
    Claimed: { … }
  Rewards:
    - Name: "&f250 Money"
      Chance: 70.0
      Commands:
        - "eco give {player} 250"
    - Name: "&f500 Money"
      Chance: 30.0
      Commands:
        - "eco give {player} 500"

Key	Required	Description
Enabled	no (true)	false hides the gift from the menu and frees its slot. Its id still occupies a place in the daily numbering.
Slot	yes	Raw menu slot, from 0. Must be inside the menu Size and unique across enabled gifts.
Required-Playtime	yes	Playtime needed today to unlock. Token syntax, see durations.
Name	no (id)	Display name used in chat messages and the {gift} token. Not the icon name - each state icon has its own.
Icons	yes	Locked, Claimable and Claimed. All three required.
Rewards	yes	At least one weighted reward.

Gifts are sorted by Required-Playtime ascending (ties broken by id, case-insensitive). That order is what {number} reports.

Durations

Required-Playtime is one or more <number><unit> tokens, optionally spaced. Units: d, h, m, s. Anything else in the string is ignored, but a value with no valid token at all fails the load.

Required-Playtime: "45s"
Required-Playtime: "10m"
Required-Playtime: "1h 30m"
Required-Playtime: "1d 6h"

Icons

Icons must contain all three states. Each is a self-contained item - they share nothing, so a gift can look completely different in each one.

  Icons:
    Locked:
      Material: PLAYER_HEAD
      Base64: "e3RleHR1cmVzOntTS0lOOnt1cmw6..."
      Amount: 1
      Custom-Model-Data: 0
      Glow: false
      Name: "&a&lCommon Gift"
      Lore:
        - "&7Complete the required playtime"
        - "&7to unlock and claim this gift."
        - " "
        - "&aInformation:"
        - "&2 - &7Available In: &f{unlocks-in}"
        - "&2 - &7Status: &fLocked"
        - " "
        - "&c&lLOCKED"

State	Shown when
Locked	Today’s playtime is below Required-Playtime.
Claimable	Playtime met, not claimed today. Gets an extra glint if Claimable-Glow is on.
Claimed	Already claimed today.

Icon fields

The same shape is used by the temporary icons and the menu items.

Field	Default	Description
Material	required	Any material name; resolved through XSeries, so legacy and modern names both work. An unknown name fails the load.
Amount	1	Stack size shown on the icon. The default gifts use this to number them 1-12.
Base64	""	Head texture value. Only applied when Material is PLAYER_HEAD.
Custom-Model-Data	0	0 leaves it unset.
Name	""	Item display name. Blank leaves the vanilla name.
Lore	[]	The complete lore for that state.
Glow	false	Adds an enchant glint.

Italics are stripped from names and lore automatically. Temporary icons and menu items accept one extra field, Item-Flags (a list of Bukkit item flags such as HIDE_ATTRIBUTES); gift state icons do not.

Icon tokens

Token	Value
{gift}	The gift’s Name.
{number}	1-based position in the daily order.
{required-playtime}	The requirement, formatted (1h 30m 0s).
{playtime}	The player’s playtime today.
{unlocks-in}	Playtime still needed; 0s once unlocked.
{refreshes-in}	Countdown to the next reset.

Icons are rebuilt once a second while the menu is open, so {unlocks-in} and {refreshes-in} tick live.

Rewards

A list of weighted entries. One is rolled when the gift is claimed.

  Rewards:
    - Name: "&f2500 Money"
      Chance: 70.0
      Commands:
        - "eco give {player} 2500"
    - Name: "&f5000 Money &7+ &f1x Key"
      Chance: 30.0
      Commands:
        - "eco give {player} 5000"
        - "crates key give {player} rare 1"

Key	Description
Name	Shown in the GIFT-CLAIMED message as {reward}. Supports colors and MiniMessage.
Chance	The weight. Must be above 0. The roll is bounded by the sum of every chance, so weights that add up to 100 read as percentages but any scale works.
Commands	Console commands run on claim. {player} is replaced with the player’s name.

An entry missing Name, Chance or Commands, a chance of 0 or lower, or an empty Rewards list all fail the load with the path printed to console.

Validation

The whole file is validated on load and on /giftsadmin reload. These fail loudly rather than being skipped:

• Duplicate gift id (two identical top-level keys)
• Duplicate Slot between two enabled gifts
• Missing Icons section, or a missing Locked / Claimable / Claimed entry
• An invalid Material anywhere
• An unparseable Required-Playtime
• An empty or malformed Rewards list

If a reload fails, the console shows the offending gift id or config path.