Kits and Daily Rewards

🎁 Kits and daily rewards

Kits and daily rewards share the same item format. Both are configured in YAML and can use MiniMessage names and lore.

Item format

material: DIAMOND_SWORD
amount: 1
name: "<aqua><bold>Explorer's Blade</bold></aqua>"
lore:
  - "<gray>A reward for setting out.</gray>"
enchantments:
  sharpness: 3
  unbreaking: 2

Field	Required?	Meaning
material	Yes	Bukkit material name, such as DIAMOND_SWORD
amount	No	Defaults to 1 and is clamped to the material's stack size
name	No	MiniMessage display name
lore	No	List of MiniMessage lore lines
enchantments	No	Minecraft enchantment key and positive level

Invalid materials are skipped. Unknown enchantments are skipped with a console warning. Enchantment levels use Paper's unsafe enchantment API, so levels may exceed vanilla limits if deliberately configured.

Kits

Kits live under kits: in settings/kits.yml.

kits:
  miner:
    cooldown-seconds: 43200
    items:
      - material: IRON_PICKAXE
        name: "<yellow>Miner's Pick</yellow>"
        enchantments:
          efficiency: 2
      - material: TORCH
        amount: 32
    armor:
      helmet:
        material: IRON_HELMET
    offhand:
      material: SHIELD

Supported equipment keys are:

armor.helmet
armor.chestplate
armor.leggings
armor.boots
offhand

When a kit equips a slot that is already occupied, Rivet moves the old item into the player's inventory first. Overflow drops safely at the player.

Kit permissions

Players need both the base command and the kit node:

rivet.kit
rivet.kit.<kit-name>

rivet.kit.* grants every configured kit. The default starter kit grants rivet.kit.starter to everyone.

/kit lists only kits the sender can claim. /kit <name> checks the per-kit permission and persistent cooldown.

Cooldowns

cooldown-seconds: 0 disables a kit's cooldown. Positive cooldowns are stored by player UUID and kit name in data/kits.yml.

Rivet saves the cooldown before granting items. If the save fails, the kit is not handed out, which prevents duplicate claims caused by a broken data file.

Daily rewards

Daily state uses server timestamps, not the player's local clock.

claim-period-hours: 24
streak-reset-hours: 48
cycle-rewards: true

• A player must wait the full claim period between rewards.
• Claim periods have a minimum of one minute.
• The reset window can never be shorter than the claim period.
• A first claim starts at streak 1.
• Claiming after the reset window starts the streak at 1 again.
• A server clock moving backwards also resets the streak safely.

Reward schedule

rewards:
  1:
    items:
      - material: DIAMOND
        amount: 1
  2:
    experience: 100
  3:
    items:
      - material: GOLDEN_APPLE
        amount: 2
  7:
    commands:
      - "give <player> diamond 5"

A reward day may combine all three reward types:

Field	Result
items	Uses the shared item format above
experience	Gives raw experience points, not levels
commands	Runs each line as the console

<player> in a command is replaced with the claimant's exact current name.

Cycling rewards

With cycle-rewards: true, a streak longer than the highest configured reward wraps back to day 1. The real streak number is retained for messages and milestones.

For example, a 7-day schedule gives reward day 1 on streak 8, reward day 2 on streak 9, and so on.

With cycling disabled, an unconfigured streak day is rejected and the configured unconfigured message is shown.

Milestones

Milestones are extra rewards attached to the real streak number:

milestones:
  14:
    items:
      - material: NETHERITE_SCRAP
  30:
    commands:
      - "give <player> diamond_block 1"

On streak 14, the player receives both the normal scheduled reward and the day-14 milestone. Milestones do not cycle.

Save safety

Rivet saves the new timestamp and streak before granting anything. If saving fails, it restores the old in-memory state and gives no reward. This prevents repeated claims after a storage error.