VVoucher - 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"
  Random:
    Min: 20000
    Max: 50000
  Command: "eco give %player% %random-amount%"

Voucher Options

Option	Meaning
`Material`	Bukkit material name for the item.
`Material: HDB-12345`	Uses a HeadDatabase head id as the voucher item.
`Name`	Display name of the item.
`Texture`	Optional base64 texture. Only works with `Material: PLAYER_HEAD`.
`Lore`	Lore lines shown on the item.
`Unbreakable`	True or false.
`CustomModelData`	Set `-1` to disable.
`Glow`	True or false.
`Usage`	How many times the voucher can be used before it is removed.
`Enable`	Optional true or false. Defaults to true if missing.
`Action`	Required interaction type that triggers the voucher.
`Command`	Console command executed on use.
`Message-Chat`	Optional chat message on voucher use.
`Message-Title`	Optional title and subtitle on voucher use.
`Message-ActionBar`	Optional action bar message on voucher use.
`Random-Command`	Weighted random command list.
`Random.Min` / `Random.Max`	Voucher-level random range for `%random-amount%`.
`Attributes`	Optional item attributes.
`Enchantments`	Optional item enchantments.
`ItemFlags`	Optional item flags.
`Potion`	Optional potion effect applied to the player.

Supported Actions

RIGHT CLICK LEFT CLICK MIDDLE CLICK SHIFT + RIGHT CLICK SHIFT + LEFT CLICK SHIFT + MIDDLE CLICK HAND SWITCH SHIFT + HAND SWITCH

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.

Name and lore use the player who receives or views the item. Messages and commands use the player who actually used the voucher.

Voucher Use Messages

random-permission:
  Message-Chat: "{prefix} You opened a random permission voucher."
  Message-Title:
    Title: "&#1378FFRandom Permission"
    SubTitle: "&7Good luck!"
  Message-ActionBar: "{prefix}&7You opened your voucher."

Random-Command

random-permission:
  Material: FEATHER
  Name: "<gradient:#1378FF:#60BFFB>Random Permission</gradient>"
  Usage: 2
  Action: "SHIFT + RIGHT CLICK"
  Random-Command:
    Command1:
      Chance: 20
      Command: "lp user %player% permission settemp essentials.fly true %local-random%h"
      Message-Chat: "{prefix}&aYou got a Fly permission for %local-random% hour(s)!"
      Message-Title:
        Title: "&#1378FFFly"
        SubTitle: "&7Duration: &#1378FF%local-random%h"
      Message-ActionBar: "&7Reward: &#1378FFFly"
      Random:
        Min: 1
        Max: 3
    Command2:
      Chance: 20
      Command: "lp user %player% permission settemp essentials.repair true 1h"
      Message-Chat: "{prefix}&aYou got a Repair permission!"

Each entry id can be any name.
Chance is required.
Command is required.
Message fields are optional.
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.
%local-random% only exists inside the selected random reward entry.
%random-amount% still refers to the voucher-level random section.

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.

Items created by VVoucher no longer behave like their original Minecraft material. Block vouchers cannot be placed, ender pearls cannot be thrown normally, fireworks cannot be launched normally, and consumable materials cannot be consumed normally. They only work through the configured voucher action.

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