# Custom Setup & Configuration

### Installation

1. Download the latest release
2. Place the `.jar` file in your server's `plugins` folder
3. Restart your server
4. Configuration files will be generated in `plugins/XianVouchers/`

***

#### Configuration Files

| File           | Purpose                                |
| -------------- | -------------------------------------- |
| `vouchers.yml` | Define voucher items and their rewards |
| `messages.yml` | Customize all plugin messages          |
| `sounds.yml`   | Configure sound effects                |
| `redeem.yml`   | Customize the redemption GUI           |

***

### Step 1: Understanding the Voucher Structure

Before creating vouchers, let's understand what each part does:<br>

```
vouchers:
  your-voucher-id:        ← 1. Voucher ID (unique name)
    item: PAPER           ← 2. What item the voucher looks like
    glow: false           ← 3. Glowing effect (true/false)
    titel: "..."          ← 4. Display name on the item
    lore:                 ← 5. Description text
      - "..."
    message-receive:      ← 6. Message when player gets the voucher
      ...
    on-redeem:            ← 7. What happens when voucher is used
```

***

### Step 2: Choose a Voucher ID

The voucher ID is how you identify your voucher. It should be:

* Unique (❌ two vouchers with the same ID)
* Easy to remember
* Without spaces (use hyphens or underscores instead)

**Good Examples:**

* `gold-voucher`
* `diamond_reward`
* `vip-week`

**Bad examples:**

* `gold voucher` (has space)
* `item_reward_from_event_2024_summer_special` (overly descriptive, messy)
* `voucherthatgivesgoldanddiamondandems` (way too long)

***

### Step 3: Choose Your Item Material

The `item` option determines what voucher look like in the player's inventory.

**Suggested materials:**

* `PAPER` - Classic voucher look
* `BOOK` - For story/reward vouchers
* `NETHER_STAR` - For rare/special rewards
* `GOLD_INGOT` - For currency vouchers

**Full list:** Visit [Minecraft Wiki - Materials](https://minecraft.wiki/w/Java_Edition_data_values#Blocks)

***

### Step 4: Add Glow Effects (Optional)

The `glow` option adds an enchanted effect to your voucher item.

```yaml
glow: true   # Voucher will sparkle like enchanted items
glow: false  # No glow effect
```

***

### Step 5: Set the Display Name

The `titel` option sets the item's name shown when hovering over it.

**Examples:**

* `&#FFD700Gᴏʟᴅ Vᴏᴜᴄʜᴇʀ`
* `&#FFAA00`ᴠɪᴘ ᴠᴏᴜᴄʜᴇʀ

**Color Code List:** [Minecraft Wiki - Formatting codes](https://minecraft.wiki/w/Formatting_codes)

Color Code Generator: [RGB Birdflop - Minecraft RGB Gradient Creator](https://minecraft.wiki/w/Formatting_codes)

***

### Step 6: Add Description (Lore)

The `lore` section adds description text below the item name.

```yaml
lore:
  - "&#F2F4FFRɪɢʜᴛ-Cʟɪᴄᴋ ᴛᴏ Rᴇᴅᴇᴇᴍ"
  - ""
  - "&#AAAAAARᴇᴡᴀʀᴅ: 10 Gᴏʟᴅ"
```

* Each line is a separate lore entry
* Creates gaps/empty lines by ""

***

### Step 7: Set the Receive Message (Optional)

When a player receives the voucher, they see this message.

```yaml
message-receive:
  module:
    chat:
      enabled: true
      message:
        - "&#FFD700Vᴏᴜᴄʜᴇʀ | Yᴏᴜ ɢᴏᴛ ᴀ Gᴏʟᴅ Vᴏᴜᴄʜᴇʀ!"
```

***

### Step 8: Set the Reward (What Happens on Redeem)

The `on-redeem` section defines what players get when they use the voucher.

#### Give Commands

```yaml
on-redeem:
  commands:
    - "give %player% gold_ingot 10"
    - "eco give %player% 500"
```

#### Give Permissions

<sub><mark style="color:$info;">If you have Luckperms you can use it's command to give/remove permission<mark style="color:$info;"></sub>

```yaml
on-redeem:
  permissions:
    - "essentials.fly"
    - "group.vip"
```

#### Full Example

```yaml
on-redeem:
  commands:
    - "give %player% gold_ingot 10"
    - "eco give %player% 1000"
  permissions:
    - "essentials.fly"
```

**Placeholders you can use:**

| Placeholder | Gets replaced with |
| ----------- | ------------------ |
| `%player%`  | Player's username  |

***

### Adding Your Voucher to vouchers.yml

1. Open `plugins/XianVouchers/vouchers.yml`
2. Copy your voucher code under the `vouchers:` section
3. Make sure indentation is correct (use spaces, not tabs)
4. Save the file
5. Run `/vouchers reload` to apply changes

***

### Testing Your Voucher

Give yourself the voucher to test it:

```bash
/vouchers give <yourname> gold-voucher 1
```

Or for a specific player:

```bash
/vouchers give PlayerName gold-voucher 5
```


---

# 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://xianstudio.gitbook.io/xianstudio-docs/xianvoucher/custom-setup-and-configuration.md?ask=<question>
```

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.