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.

Unlike the other files, gifts.yml is read exactly as written. A key you delete from a shipped gift does not come back from the defaults.

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	Default	Description
Enabled	true	false hides the gift from the menu, frees its slot and skips its unlock notification. It still keeps a place in the {number} order.
Slot	0	Raw menu slot, from 0. For enabled gifts it must be inside the menu Size and unique. Always set it.
Required-Playtime	required	Playtime needed today to unlock. See durations.
Name	the gift id	Display name used in chat messages and the {gift} token. Not the icon name: each state icon has its own.
Icons	required	Locked, Claimable and Claimed. All three required.
Rewards	required	At least one weighted reward.

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

Durations

Required-Playtime is one or more <number><unit> parts. Units: w, d, h, m, s. Spaces are ignored, and spelled-out units (1 hour 30 minutes, 45 secs) are shortened automatically.

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

"0s" makes a gift claimable as soon as the day starts. A bare number ("90"), a trailing number with no unit ("1h30") or any other character fails the load.

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
      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 item format is used by the menu items and temporary icons. The common fields:

Field	Default	Description
Material	required	Any material name. Modern and legacy names both resolve. An unknown name fails the load.
Amount	1	Stack size shown on the icon. The default gifts use it to number themselves 1 to 12.
Base64	none	Head texture value (Texture is accepted as an alias). Only allowed on PLAYER_HEAD; on any other material it fails the load. "{player}" shows the viewer’s own head.
Custom-Model-Data	0	0 leaves it unset.
Item-Model	none	An item model key, for resource packs.
Name	none	Item display name.
Lore	[]	The complete lore for that state.
Glow	false	Adds an enchant glint.
Item-Flags	[]	Bukkit item flags such as HIDE_ATTRIBUTES.
Hide-Tooltip	false	Hides the whole tooltip.

Other OptimalLibrary item keys (Enchantments, Hide, Attributes, Unbreakable, Damage, Color, Item-Name, Components, Custom-Item) are accepted as well, but icons rarely need them.

Italics are removed from names and lore automatically.

Icon tokens

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

PlaceholderAPI placeholders are resolved for the viewer too. 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, a number 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, in order. {player} is replaced with the player’s name. An empty list is allowed (the claim then only sends the message).

Validation

The whole file is checked on startup and on /giftsadmin reload. These stop the load with an error naming the gift or path instead of being skipped:

• A duplicate Slot between two enabled gifts
• An enabled gift whose Slot is outside the menu Size
• A missing Icons section, or a missing Locked / Claimable / Claimed entry
• An invalid item anywhere (unknown Material, Base64 on a non-head, …)
• A missing or unparseable Required-Playtime
• An empty Rewards list, a reward missing Name, Chance or Commands, or a chance of 0 or lower

When a reload fails, the gifts that were loaded before stay active until the file is fixed.