VoucherAddon

VoucherAddon is a powerful Minecraft plugin for Bukkit/Spigot servers that introduces a customizable voucher system. Server administrators can create and distribute special items (vouchers) that execute commands, grant rewards, assign ranks, or initiate interactive conversations when redeemed by players.

Getting Started

Basic Voucher

Advanced Voucher

General

Installation

1. Download the VoucherAddon.jar file

2. Place it in your server's plugins folder

3. Restart your server

4. Edit the configuration files to customize vouchers

Permissions

• therewards.voucher - Required to use voucher commands

Commands

The plugin uses the base command /rewards voucher with the following subcommands:

• /rewards voucher give <player> <type> [amount] - Give a specific voucher to a player

• /rewards voucher take <player> <type> [amount] - Remove a specific voucher from a player

• /rewards voucher giveall <type> [amount] - Give a voucher to all online players

• /rewards voucher takeall <type> [amount] - Remove a specific voucher from all online players

• /rewards voucher list - Display all available voucher types

• /rewards voucher openmenu [player] - Open the voucher menu for a player

• /rewards voucher playerinfo [player] - Show information about a player's vouchers

Configuration

Main Structure

Vouchers are configured in the vouchers.yml file. Each voucher has its own section with specific properties:

vouchers:
  example_voucher:
    item: PAPER
    model_data: 1001
    glow: true
    name: '&6Example Voucher'
    lore:
      - '&7Line 1 of description'
      - '&7Line 2 of description'
    # additional properties...

Basic Properties

Property	Description
item	Minecraft item type that represents the voucher
model_data	Custom model data for custom textures
glow	Whether the item should have an enchantment glow effect
name	Voucher display name (supports color codes)
lore	Description lines shown on the item (supports color codes)
cooldown	Cooldown time in seconds before the same voucher can be used again
permission_required	Whether a permission is required to use this voucher
worlds	List of allowed or blocked worlds (prefix with "!" to block a world)

Commands Section

The commands section defines the actions that will be executed when the voucher is used:

commands:
  - "[command] give {player} diamond 1"
  - "[command] tell {player} You've received a diamond!"

You can use variables:

• {player} - Player's name

• Custom variables defined in conversations

Conversation System

The conversation system allows interactive dialogues with players before activating a voucher, collecting information to customize the reward experience.

Basic Structure

conversations:
  conversation_id:
    steps:
      - id: first_step
        question: "What is your name?"
        type: text
        key: name
        defaultNextStep: second_step
      - id: second_step
        # More configuration...

Step Types

Text Input

Collects free text input from the player:

- id: player_name
  question: "What is your name?"
  type: text
  key: name
  minLength: 3
  maxLength: 16
  defaultNextStep: next_step

Numeric Range

Allows the player to select a numeric value:

- id: quantity
  question: "How many items do you want?"
  type: range
  key: amount
  min: 1
  max: 10
  defaultNextStep: next_step

Multiple Choice

Presents predefined options to the player:

- id: class_choice
  question: "Which class do you want to choose?"
  type: specific
  key: class
  options: warrior,mage,archer,thief
  conditionalSteps:
    warrior: warrior_weapon
    mage: mage_weapon
    # More conditional paths...

Confirmation

Asks for a yes/no confirmation:

- id: confirm
  question: "Are you sure you want to proceed?"
  type: confirm
  key: confirmation
  defaultNextStep: end

Regex Validation

Validates text input against a regular expression:

- id: email
  question: "Enter your email address:"
  type: regex
  key: email
  pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
  defaultNextStep: confirm

Material Selection

Allows selection of a valid Minecraft material:

- id: material
  question: "What material do you want?"
  type: material
  key: material
  defaultNextStep: next_step

Conversation Navigation

• defaultNextStep: The step to follow after the current one

• conditionalSteps: Different paths based on the player's response

When a conversation ends (defaultNextStep: end), the plugin executes the voucher's commands.

Example Configurations

Simple Voucher

simple_voucher:
  item: PAPER
  model_data: 1001
  glow: true
  name: '&6Simple Voucher'
  lore:
    - '&7Grants a diamond when activated'
    - '&eRight-click to activate'
  cooldown: 300
  commands:
    - "[command] give {player} diamond 1"

Welcome Voucher with Basic Conversation

welcome_voucher:
  item: BOOK
  model_data: 1002
  glow: true
  name: '&aWelcome Voucher'
  lore:
    - '&7Customize your welcome experience'
    - '&eRight-click to activate'
  commands:
    - "[command] give {player} bread {cantidad}"
    - "[command] tell {player} Welcome {nombre}!"
  conversations:
    welcome_conversation:
      steps:
        - id: nombre
          question: What is your name?
          type: text
          key: nombre
          minLength: 3
          maxLength: 16
          defaultNextStep: cantidad
        - id: cantidad
          question: How much bread do you want to receive?
          type: range
          key: cantidad
          min: 1
          max: 10
          defaultNextStep: confirmar
        - id: confirmar
          question: Are you sure you want to activate this voucher?
          type: confirm
          key: confirmacion
          defaultNextStep: end

Class Selection with Branching Paths

class_voucher:
  item: NETHER_STAR
  model_data: 1003
  glow: true
  name: '&bClass Selector'
  lore:
    - '&7Choose your character class'
    - '&7This choice is permanent'
    - '&eRight-click to activate'
  commands:
    - "[command] lp user {player} parent add {clase}"
    - '[command] tell {player} You have chosen the class: {clase}'
    - "[command] give {player} {arma} 1"
  conversations:
    class_selection:
      steps:
        - id: welcome
          question: Welcome to the class selector. Your choice will be permanent. Do you want to continue?
          type: confirm
          key: continuar
          defaultNextStep: clase
        - id: clase
          question: Which class do you want to choose?
          type: specific
          key: clase
          options: warrior,mage,archer,thief
          conditionalSteps:
            warrior: arma_warrior
            mage: arma_mage
            archer: arma_archer
            thief: arma_thief
        - id: arma_warrior
          question: You have chosen Warrior. Which weapon do you prefer?
          type: specific
          key: arma
          options: DIAMOND_SWORD,IRON_AXE
          defaultNextStep: confirmar
        # Additional weapon choice steps for other classes...
        - id: confirmar
          question: You have chosen the {clase} class with {arma}. This choice is permanent. Are you sure?
          type: confirm
          key: confirmacion_final
          defaultNextStep: end