Voucher System

Voucher Format

Each top-level key in a voucher YAML file is a voucher id.

money:
  Material: PAPER
  Name: "<gradient:#1378FF:#60BFFB>Money Voucher</gradient>"
  Usage: 1
  Action: "SHIFT + RIGHT CLICK"
  TooltipStyle: global:mythic
  Random:
    Min: 20000
    Max: 50000
  Command: "eco give %player% %random-amount%"

Voucher Options

Option Examples

Each option below includes a practical YAML snippet so you can see how it looks in a real voucher file.

fly-permission:
  Material: FEATHER

hdb-head-example:
  Material: HDB-13376

money:
  Name: "<gradient:#1378FF:#60BFFB>Money Voucher</gradient>"

texture-head-example:
  Material: PLAYER_HEAD
  Texture: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNzRlOGZmMzBlMzkzNzA5ODYzN2MwYWYwM2ExZjJhNmIxN2YwZTgyOGFiMmE1N2EyNjdhMDFkYTQ4NGJhMGM1NyJ9fX0="

money:
  Lore:
    - ""
    - "բFF????????????"
    - "  &8&l| &fMoney: <BFFB20,000-50,000"

fly-permission:
  Unbreakable: false

money:
  CustomModelData: -1

money:
  TooltipStyle: global:mythic

event-example:
  MaxStackSize: 64

fly-permission:
  Glow: true

fly-permission:
  Usage: 2

money:
  Enable: true

money:
  Action: "SHIFT + RIGHT CLICK"

money:
  Command: "eco give %player% %random-amount%"

random-permission:
  Message-Chat: "{prefix} You opened a random permission voucher."

random-permission:
  Message-Title:
    Title: "բFFRandom Permission"
    SubTitle: "&7Good luck!"

random-permission:
  Message-ActionBar: "{prefix}&7You opened your voucher."

random-permission:
  Random-Command:
    Command1:
      Chance: 20
      Command: "lp user %player% permission settemp essentials.fly true 1h"
    Command2:
      Chance: 80
      Command: "eco give %player% 500"

event-example:
  Random-Command:
    Command1:
      Chance: 50
      Event: "example-event"

money:
  Random:
    Min: 20000
    Max: 50000

tank-voucher:
  Attributes:
    GENERIC_ARMOR:
      Value: 20
      EquipmentSlot: HAND

enchanted-voucher:
  Enchantments:
    DURABILITY: 3

money:
  ItemFlags:
    - HIDE_ATTRIBUTES
    - HIDE_UNBREAKABLE

strength-voucher:
  Potion:
    Type: "STRENGTH"
    Level: 2
    Duration: 90

Supported Actions

Command Placeholders

• %player%
• %uuid%
• %random-amount%
• %local-random% inside random reward entries that define a local Random
• %current-usage%
• %max-usage%

PlaceholderAPI placeholders are also supported in voucher names, lore, messages, commands, and random reward commands or messages.

Voucher Use Messages

random-permission:
  Message-Chat: "{prefix} Nyitottál egy random permissiont."
  Message-Title:
    Title: "բFFRandom Permission"
    SubTitle: "&7Sok szerencsét!"
  Message-ActionBar: "{prefix}&7Megnyitottad a random permission voucheredet."

Random-Command

event-example:
  Material: IRON_INGOT
  Name: "<gradient:#1378FF:#60BFFB>Event Example Voucher</gradient>"
  Usage: 1
  Action: "SHIFT + RIGHT CLICK"
  MaxStackSize: 64
  Random-Command:
    Command1:
      Chance: 50
      Message-Chat: "{prefix} You got nothing!"
    Command2:
      Chance: 50
      Event: "example-event"

• Each entry id can be any name.
• Chance is required.
• Command is required unless the reward uses Event.
• Message fields are optional.
• Event is optional and can call a reusable reward table from events/*.yml.
• Random is optional and belongs only to that reward entry.
• Total chance does not need to equal 100.
• Higher Chance means higher selection weight.
• If Random-Command exists, it takes priority over normal Command.
• If a reward uses Event, VVoucher selects one reward from that external event table.
• %local-random% only exists inside the selected random reward entry.
• %random-amount% still refers to the voucher-level random section.

Events Folder

You can create reusable weighted reward tables inside plugins/VVoucher/events/.

example-event:
  reward-1:
    Chance: 20
    Command: "give %player% diamond 1"
    Message-Chat: "{prefix} You got a բFFdiamond&7!"
  reward-2:
    Chance: 10
    Command: "give %player% diamond 2"
  reward-3:
    Chance: 70
    Command: "give %player% iron_ingot 1"

• Each top-level key is an event id.
• Event rewards need Chance and normally Command.
• Event rewards support Message-Chat, Message-Title, Message-ActionBar, and local Random.
• Event rewards do not support nested Event calls.

HeadDatabase and Custom Heads

random-permission:
  Material: HDB-127387
  Name: "<gradient:#1378FF:#60BFFB>Random Permission</gradient>"

random-permission:
  Material: PLAYER_HEAD
  Texture: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZjYwY2Y0ZGJmY2NiODg1YTNkNmVkZGIwZDE3ZDFhMDMxNTkxOGUxZTcyYTJkZDg1Njk0OTE5MTNjOWI2MzUxZSJ9fX0="
  Name: "<gradient:#1378FF:#60BFFB>Random Permission</gradient>"

• HDB-<id> treats the material as a HeadDatabase head.
• Texture only works with Material: PLAYER_HEAD.
• If HeadDatabase is missing, HDB materials cannot be created correctly until it is installed.

Identification and Vanilla Blocking

Voucher items are identified with persistent data, not by display name or lore. Internal marker format:

vvouchers:%config-key%

This means the plugin can still recognize the voucher even if the item is renamed visually, as long as the stored metadata remains intact.

Language System and Error Handling

config.yml controls the active language. Example:

language: en

This loads plugins/VVoucher/lang/en.yml. You can switch to Hungarian with language: hu.

For normal configuration mistakes, the plugin tries to print a readable warning instead of a useless stack trace:

[Config Error] example.yml -> money.Material: Unknown material: PAPERR