Creating Gifts

Gifts are config, not commands. You add one by adding a section to gifts.yml, then reloading. You need optimalgifts.admin to reload.

1. Add a section to gifts.yml

Open plugins/OptimalGifts/gifts.yml. Every top-level key is one gift, and the key is its id. A gift needs a Slot, a Required-Playtime, an Icons block with all three states, and at least one reward. Name is optional but you almost always want it.

mythic-1:
  Enabled: true
  Slot: 24
  Required-Playtime: "4h"
  Name: "&#FF5C5C&lMythic Gift"
  Icons:
    Locked:
      Material: PLAYER_HEAD
      Base64: "e3RleHR1cmVzOntTS0lOOnt1cmw6..."
      Amount: 13
      Name: "&#FF5C5C&lMythic Gift"
      Lore:
        - "&7Play for &f{required-playtime} &7today"
        - "&7to unlock this gift."
        - " "
        - "&#FF5C5CInformation:"
        - "&#B33A3A - &7Available In: &f{unlocks-in}"
        - " "
        - "&c&lLOCKED"
    Claimable:
      Material: PLAYER_HEAD
      Base64: "e3RleHR1cmVzOntTS0lOOnt1cmw6..."
      Amount: 13
      Name: "&#FF5C5C&lMythic Gift"
      Lore:
        - "&7This gift is ready."
        - " "
        - "&e➥ Click to claim!"
    Claimed:
      Material: PLAYER_HEAD
      Base64: "e3RleHR1cmVzOntTS0lOOnt1cmw6..."
      Amount: 13
      Name: "&#FF5C5C&lMythic Gift"
      Lore:
        - "&7Come back tomorrow."
        - " "
        - "&6 - &7Refresh In: &f{refreshes-in}"
        - " "
        - "&a&lCLAIMED"
  Rewards:
    - Name: "&f1x Mythic Key"
      Chance: 80.0
      Commands:
        - "crates key give {player} mythic 1"
    - Name: "&f3x Mythic Key"
      Chance: 20.0
      Commands:
        - "crates key give {player} mythic 3"

Full field list: gifts.yml reference.

2. Pick a free slot

Slot is the raw inventory slot in the /gifts menu, counting from 0. It must be inside the menu Size set in guis/gifts-menu.yml and it must not collide with another enabled gift. Either mistake stops the load with an error naming the gift.

Gift slots are not listed in the menu file. Each gift carries its own slot, so the menu file only covers the background and the buttons around them. The default menu is 36 slots and leaves slot 24 covered only by a glass pane, which is where the example above goes.

Keep buttons off gift slots

Gift icons are drawn on top of the menu’s background, so a filler under a gift is fine. But if a menu item with Actions sits on a gift’s slot, clicking there runs the item’s actions instead of claiming the gift.

3. Reload and test

/giftsadmin reload

The gift appears in /gifts immediately. Test it with /giftsadmin addtime <you> 4h, claim it, then run /giftsadmin reset <you> to put yourself back.

If the reload fails, the console names the gift id or config path that is wrong and the old gifts stay loaded.

Weighted rewards

Rewards is a list. Each entry needs a Name (shown in the GIFT-CLAIMED message as {reward}), a Chance above 0, and a list of Commands run from console with {player} replaced.

Chances are weights, not percentages: the roll is bounded by their sum. These two are identical in effect:

Rewards:
  - { Name: "...", Chance: 70.0, Commands: [ ... ] }   # 70%
  - { Name: "...", Chance: 30.0, Commands: [ ... ] }   # 30%

Rewards:
  - { Name: "...", Chance: 7.0,  Commands: [ ... ] }   # still 70%
  - { Name: "...", Chance: 3.0,  Commands: [ ... ] }   # still 30%

Weights that add up to 100 are just the readable convention. A gift with no rewards, or a reward with a chance of 0 or less, fails the load.

The three state icons

All three are required and fully independent. Each one is a complete item with its own Material, Amount, Base64, Custom-Model-Data, Name, Lore, Glow and so on, so a gift can be a gray pane while locked, a glowing head while claimable and a barrier once claimed.

State	Shown when
Locked	Today’s playtime is below Required-Playtime.
Claimable	Playtime is met and the gift has not been claimed today.
Claimed	Already claimed today. Resets at midnight.

Tokens available in every state icon: {gift}, {number}, {required-playtime}, {playtime}, {unlocks-in} and {refreshes-in}. The menu re-renders once a second, so countdowns tick live.

Settings.Claimable-Glow: true (the default) adds a glint to every claimable icon without you setting Glow on it.

Ordering

{number} comes from sorting every gift by Required-Playtime, shortest first (ties broken by id). It has nothing to do with the slot, so a gift at slot 24 can still be Gift #1. Keep requirements and slots in step if you want the menu to read left to right.

Notes

• Disable without deleting: Enabled: false hides a gift from the menu, frees its slot and stops its unlock notification. It still keeps a position in the {number} order.
• Playtime is per day, not total. A gift requiring 3h needs three hours in the current day, not three hours since first join.
• Rewards are console commands. Nothing is given directly by the plugin, so anything you can do from console you can hand out.
• Removing a gift keeps no leftovers that matter: a claimed id that no longer exists is simply ignored, and all claims are wiped at the next daily reset anyway.