Skip to content
BattleStudio Wiki

Information

BattleStudio Plugin

OptimalGifts

Daily gifts players unlock with playtime and claim once a day for a weighted random reward.

  • Paper / Folia
  • MC 1.20+
  • Java 21+
  • SQLite
Buy on BuiltByBitDiscord

OptimalGifts gives players a menu of daily gifts. Each gift has a Required-Playtime; once the player has been online that long today, the gift unlocks and can be claimed once for a weighted random reward. Everything resets at midnight in your configured timezone and the whole cycle starts again.

Gifts live in one file (gifts.yml) and each one carries its own Locked / Claimable / Claimed icon, so a gift can look completely different in each state. There is no global rarity table - the colors and lore are per gift.

The daily cycle

Section titled “The daily cycle”
  • Playtime counts only while online. A player’s daily playtime is banked + current session.
  • The day is the epoch day in Settings.Timezone. When it flips, today’s playtime and every claim are wiped. There is no midnight task - the reset is detected the next time the player’s profile is touched.
  • Unlock happens when today’s playtime reaches the gift’s Required-Playtime. A global one-second timer fires the GIFT-UNLOCKED message (and its title) the moment a gift crosses its requirement.
  • Claim once per day. The claim is written to the database immediately, so a crash can never re-grant a gift.
  • The reward is one weighted pick from the gift’s Rewards list; its Commands run from console with {player} substituted.

The unlock notification set is not persisted. It is pre-filled on join with anything already claimable, so relogging never re-spams old unlocks.

Features

Section titled “Features”
  • Any number of daily gifts, each at its own menu slot with its own playtime requirement
  • Fully independent Locked / Claimable / Claimed icons per gift (material, amount, head, name, lore, glow)
  • Weighted reward rolls: each reward is a Chance and a list of console commands
  • Live menu: countdowns and states re-render every second while the menu is open
  • Unlock notifications with an optional screen title
  • Daily reset at midnight in any timezone
  • Optional glow on claimable gifts
  • Temporary feedback icons on blocked clicks
  • SQLite storage, write-behind flushed on a configurable interval
  • Folia-ready (region schedulers throughout)

Commands

Section titled “Commands”

Player - /gifts (aliases /gift, /dailygifts):

  • /gifts - open the daily gifts menu · optimalgifts.use

Admin - /giftsadmin (alias /giftadmin) · all optimalgifts.admin:

  • /giftsadmin reset <player> - clear today’s claims and playtime. Works on offline players (their database row is deleted).
  • /giftsadmin addtime <player> <duration> - add playtime to a player’s current day. Online players only. <duration> is a token string like 10m, 1h 30m, 2h, 90s.
  • /giftsadmin reload - reload every config file.

Permissions

Section titled “Permissions”
  • optimalgifts.use - /gifts and the menu (default: everyone)
  • optimalgifts.admin - every /giftsadmin command (default: op)

Gifts themselves have no permission nodes. Every player sees every enabled gift; playtime is the only gate.

Placeholders

Section titled “Placeholders”

OptimalGifts does not register a PlaceholderAPI expansion - there are no %optimalgifts_...% placeholders.

PlaceholderAPI is still a useful soft dependency: when it is installed, %...% placeholders from other plugins are resolved inside messages, message titles and menu action arguments.

Tokens

Section titled “Tokens”

These are the plugin’s own {...} tokens. They resolve in gift icon names and lore, in messages and in message titles.

Token Value
{gift} The gift’s Name.
{number} The gift’s 1-based position in the daily order (sorted by required playtime).
{required-playtime} The gift’s Required-Playtime, formatted (1h 30m 0s).
{playtime} The player’s playtime today.
{unlocks-in} Playtime still needed. 0s once unlocked.
{refreshes-in} Countdown to the next midnight in Settings.Timezone.
{reward} The reward’s Name. Claim message only.
{player}, {duration}, {ms} Admin command messages only. In PLAYTIME-ADDED, {playtime} is the amount that was added, not the day’s total.

Durations

Section titled “Durations”

Required-Playtime and /giftsadmin addtime accept the same syntax: one or more <number><unit> tokens, optionally spaced. Units are d, h, m, s.

"10m"        →  10 minutes
"1h 30m"     →  90 minutes
"2h"         →  2 hours
"1d 6h 30m"  →  30 hours 30 minutes

Durations are printed back as 1h 12m 53s (the hours and minutes parts are dropped when zero).

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient:a,b,c>, <rainbow>, <bold>, <#RRGGBB>, <solid:HEX>, …) and, with PlaceholderAPI installed, %...% in messages and action arguments. <gradient> accepts comma-separated hex stops.

Reference

Section titled “Reference”