# 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
```
