# 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 [amount]` - Give a specific voucher to a player
* `/rewards voucher take [amount]` - Remove a specific voucher from a player
* `/rewards voucher giveall [amount]` - Give a voucher to all online players
* `/rewards voucher takeall [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:
```yaml
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:
```yaml
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
```yaml
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:
```yaml
- 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:
```yaml
- 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:
```yaml
- 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:
```yaml
- 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:
```yaml
- 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:
```yaml
- 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
```yaml
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
```yaml
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
```yaml
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
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.xshyo.us/free-plugins/therewards/addons/voucheraddon.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.