🎄 Advent Calendar / Daily Gifts

Give one reward per reset-day via a SmartInvs GUI. Reward selection order: (1) fixed calendar mapping for today’s slot, else (2) weighted random from the player’s group (or default).

⏰ claim — Reset time & timezone

claim:
  timezone: "Europe/Paris"
  reset-hour: 5

• timezone for boundary math and “time left”.
• reset-hour = new day boundary. At 05:00 local time, a new claim opens.

📅 calendar — Fixed advent season

calendar:
  start:
    date: "2025-12-01"
    timezone: "Europe/Paris"
    length: 25

  "1": "common_coal"
  "2": "rare_money"
  "3": "common_coal"
  "4": "rare_money"

  vip:
    "1": "rare_money"

• Slots are “1..length” since start.date (not literal month days).
• Group overrides (e.g., vip) take precedence over global mapping.

💬 messages

messages:
  already-claimed: "&cYou've already claimed today's reward. Next in &f%remaining%&c."
  claimed: "&aYou claimed today's reward! &7(Current streak: &f%streak%&7)"
  no-reward-config: "&cNo gifts configured."

🖼️ gui — Look & layout

gui:
  title: "&6&lDaily Gifts"
  rows: 6
  rewards_per_page: 21

  border:
    enabled: true
    material: GRAY_STAINED_GLASS_PANE

  reward_slots:
    - "1,1"
    - "1,2"
    - "3,7"

  prev: { material: ARROW }
  next: { material: ARROW }
  open: { material: LIME_WOOL }

States: Past (closed), Today (claimed), Today (available), Future (locked).

🎁 item — Physical gift (optional)

item:
  material: KNOWLEDGE_BOOK
  display_name: "&6&lDaily Christmas Gift"
  lore:
    - "&7Right-click to open and claim"
    - "&7your festive reward!"
    - " "
    - "&cWarning: May contain coal."

🧩 rewards — Actual grants

rewards:
  default:
    common_coal:
      chance: 50
      icon:
        material: COAL
        name: "&7common_coal"
        lore:
          - "&7Weight: 50"
          - "&7Commands: &f/give %player% coal 10"
      commands:
        - "give %player% coal 10"
      messages:
        - "&cSanta gave you a lump of coal..."
      event:
        firework: false
        sound: "ENTITY_WITCH_DRINK"

    rare_money:
      chance: 5
      icon:
        material: EMERALD
        name: "&arare_money"
        lore:
          - "&7Weight: 5"
          - "&7Commands: &f/eco give %player% 1000"
      commands:
        - "eco give %player% 1000"
        - "shards give %player% 50"
      messages:
        - "&aHO HO HO! You found a rare prize!"
      event:
        firework: true
        sound: "ENTITY_PLAYER_LEVELUP"

🔁 Claim rules

• One claim per reset-day; store tracks last claim epoch-day.
• Calendar mapping beats weighted random.
• Streak increments only if consecutive days were claimed.

✅ Best practices

• Define all slots 1..length to avoid unintended randomness.
• Pick a reset hour like 4–6 AM local.
• Use icon.lore for hints, not spoilers.
• Add group overrides for donor differentiation.
• Short, festive sounds; fireworks for rare wins.

🧪 Quick checklist

• Set calendar.start.date to your event start.
• Fill 1..length mappings.
• Define rewards.default and any group overrides.
• Open GUI via /advent and test claimed/available states.
• Test streak and “time to reset” messages.