Creating Gifts

Gifts are config, not commands. You add one by adding a section to gifts.yml. 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 five things: a Slot, a Required-Playtime, a Name, an Icons block with all three states, and at least one reward.

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 - a duplicate slot fails the load loudly.

Gift slots are not listed in the menu file. Each gift carries its own slot, so the menu file only needs to cover the background and the buttons around them.

3. Reload

/giftsadmin reload

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

Weighted rewards

Rewards is a list. Each entry needs a Name (shown in the GIFT-CLAIMED message via {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 three 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%

Percentages 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 sets its own Material, Amount, Base64, Custom-Model-Data, Name, Lore and Glow, 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}, {refreshes-in}. The menu re-renders once a second, so countdowns tick live.

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

Ordering

{number} and the daily order come from sorting every gift by Required-Playtime ascending (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 and frees its slot. Its id keeps a position in the daily numbering.
• Duplicate ids or slots fail loudly at load. So does a missing Icons section, a missing state icon, an invalid material or an empty Rewards list - check the console after a reload.
• 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.