# Home

Welcome at documentation of all plugins maintained by INNOUNIQ.

Place where you will understand whole configuration logic, so prepare some coffee and jump into integration of these amazing plugins to your server!

#### List of plugins

* [Advent Season](/plugins/advent-season) - Make pleasant time to players while waiting for Christmas.
* [Easter Season](/plugins/easter-season) - Enhance experience on the server with stunning addons.
* [Parkour](/plugins/parkour-dimension) - Let players show their jumping skills.
* [Lottery](/plugins/lottery) - Encourage players to bet money to be in with a chance of winning the pot.
* [Voting](/plugins/voting) - Keep players to determine various situations.
* [Promotional Activity](/plugins/promotional-activity) - Use your social networks for expanding your server.


# TheCore


# Installation

Plugin downloaded, what should I do next?

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run TheCore plugin on your server, there are a few requirements that you have to check.

* Ensure you are using Minecraft version <mark style="color:red;">**1.8.8**</mark> or <mark style="color:red;">**later**</mark>. (Versions below 1.8.8 are not supported!)
* Your server has installed <mark style="color:red;">**Java8**</mark> or later.

## Installation

1. Put `TheCore.jar` into plugins folder at your server.
2. Restart your server.&#x20;
   1. If you are using PlugMan, load it through it while server is running.
3. Done, jump into configuration and setting up.


# Commands & Permissions

Main commands to maintain core.

## Player commands

| Description                | Command                 | Permission          |
| -------------------------- | ----------------------- | ------------------- |
| Base command               | /TheCore                | TheCore.Help.Player |
| Player's help              | /TheCore Help \[Player] | TheCore.Help.Player |
| Player's info about plugin | /TheCore Info \[Player] | TheCore.Info.Player |

## Admin commands

| Description                | Command                                | Permission                |
| -------------------------- | -------------------------------------- | ------------------------- |
| Admin's help               | /TheCore Help Admin                    | TheCore.Help.Admin        |
| Advanced info about plugin | /TheCore Info Admin                    | TheCore.Info.Admin        |
| Reload whole plugin        | /TheCore Reload \[All]                 | TheCore.Reload.All        |
| Reload localization file   | /TheCore Reload Locale                 | TheCore.Reload.Locale     |
| Reload options file        | /TheCore Reload Options                | TheCore.Reload.Options    |
| Reward Repository          | /TheCore Reward Repository \[Category] | TheCore.Reward.Repository |
| Migrate Rewards            | /TheCore Migration Reward \[Module]    | TheCore.Migration.Reward  |

## Additional permissions

Collection of permissions not assigned to commands.

### Permissions

Highlighted permissions are considered as recommended

* Bold - Recommended to all players
* Italic - Recommended to only specific group of players

<table><thead><tr><th>Description</th><th>Permission</th><th data-hidden></th></tr></thead><tbody><tr><td>Base player's actions</td><td><strong>TheCore.Player</strong></td><td></td></tr><tr><td>Complete package of all permissions</td><td><em>TheCore.Admin</em></td><td></td></tr><tr><td>All reload commands</td><td>TheCore.Reload.*</td><td></td></tr><tr><td>All reward commands</td><td>TheCore.Reward.*</td><td></td></tr><tr><td>All migration commands</td><td>TheCore.Migration.*</td><td></td></tr></tbody></table>

## Explanatory notes

* **\[]** - **Square Brackets** - Optional argument. Command has the same effect, if that argument is not used.
* **<>** - **Less/More than signs** - Mandatory argument. It's a variable.
  * Example: **\<PlayerName>** will be replaced with **SobkySK**


# Configuration

Detailed explanation of variables at configuration files.

{% embed url="<https://youtu.be/FK_LnRMi-JA>" %}


# Base

Looking into config.yml

## Localization

Whole resource using English localization as default.&#x20;

To translate messages follow steps below:

* Move to **Locale** folder of **TheCore** plugin
* Just make duplicate of EN.yml file.&#x20;
* Rename it and write the name of the file into **config.yml**.

#### Example

```yaml
#LocaleFile: EN.yml
Prefix:
  Base: "&3&lTheCore &6\u2771"
  ...
```

```yaml
#LocaleFile: SK.yml (Slovak)
Prefix:
  Base: "&3&lQ &6\u2771"
  ...
```

```yaml
Locale:
  Primary: SK #Previously EN
```

### Multi localization

Plugin is able to hold different localisations at the same time. It’s up to player, which localisation wants to display.

{% hint style="info" %}
Secondary localizations do not have to contain all translations. In case of secondary translation does not contain requested path, the primary file is used to fetch data.
{% endhint %}

```yaml
#config.yml
Locale:
  Primary: EN
  Secondary:
  - SK
  - CZ
  ...
```

### Module localization

Plugins powered by TheCore uses the same Localization settings as TheCore. If you want to use another default language, you need to disable inheritance and set the right values.

```yaml
Locale:
  ...
  Module:
    Advent:
      Inherit: false
      Primary: EN
      Secondary: [ ]
```

## Storage

Space where to save required data.

Supported storages

* `MySQL`
* `SQLite`

If you prefer **MySQL** Storage before **SQLite**, you need to fill variables at **config.yml**.

```yaml
Storage:
  Type: "MySQL"
  Host: "IP"
  Port: 3306
  Database: "db"
  User: "name"
  Password: "*****"
```

## Placeholder API

By activating, plugin retrieves information about placeholders from PlaceholderAPI at translating the messages.

```yaml
PlaceholderAPI:
  Active: true
```

## Bedrock Edition

Enable if you are using **Geyser**.

```yaml
BedrockEdition:
  Active: true
```


# Options

Looking into Options.yml

## Format

### DateTime Pattern

All date-time data are parsed using this pattern. Wanna US style? Change it here.

{% hint style="danger" %}
This pattern is used across all plugins powered by TheCore.
{% endhint %}

```yaml
Options:
  Format:
    Pattern:
      DateTime: "dd.MM.yyyy HH:mm"
```

## Visual

Section represents components displayed at chat, boss bars and titles.

### Detailed Logging

Important messages are sent to console log

```yaml
Options:
  Visual:
    DetailedLogging:
      Active: true
```


# Centralized Reward Repository

System of rewarding players.

{% hint style="warning" %}
Please, keep on mind, that reward is **NOT** only one item in the game. It is a **collection** of commands and items, which will be given to player at claiming.
{% endhint %}

## What does reward consist of? <a href="#what-does-reward-consist-of" id="what-does-reward-consist-of"></a>

* `Key` - **Unique** name of the reward. It is used at assigment to the specific day.
* `Name` - Real, **human readable**, name of the reward. Visible after claiming at opened window.
* `Description` - Optional. Visible only for staff at Reward Repository for better orientation.
* `Icon` - Item representing reward. For example, **Diamond Pickaxe**.
* `Items` - **Collection** of items given to player at claiming the reward.
* `Commands` - **Collection** of commands executed to player at claiming the reward.

## How to create reward <a href="#how-to-create-reward" id="how-to-create-reward"></a>

There are two options how to create reward. By in-game **Reward UI** or **Manually** in the confiuration file. Both have some restrictions, so if you want use some advanced methods you will need to use combination of them.

### **Using in-game Reward UI**

{% hint style="info" %}
To open **Reward UI** type `/TheCore Reward Repository [Category]`
{% endhint %}

You can inspire with Reward tutorial.

{% embed url="<https://youtu.be/FK_LnRMi-JA>" %}

### **Manually in the file**

Configuration file `RewardRepository.yml` is located at folder `Reward`.

#### **Template for the one reward**

```yaml
UniqueRewardKey:
  Name: 
    EN: '&5Name of the reward using color codes!'
  Description: 
    EN: 'Optional Description'
  Icon:
    Material: STONE #Material of the Icon
    MaterialData: 0 #Used for items, where the plugin runs on the version from 1.8.8 to 1.12.X. Here you can specify color of the material.
    Enchantment: false #Flag if the enchantment is applied on the Icon
    Color: "255:255:255" #RGB Color format of leather armor
    ItemFlagList: #Flags applied on the Icon
    - HIDE_ENCHANTS
    - HIDE_ATTRIBUTES
    CustomModelData: 0 # Only versions 1.14 and above
  Reward:
    ItemList: [] #Cannot be configured here.
    CommandList: []
  CategoryList: []
```

#### List of commands example

```yaml
CommandList:
- "money give {player} 100"
- "set VIP {player} 30Day"
```

If you are familiar with percentage placeholders, you can also do it here!&#x20;

```yaml
CommandList:
- "money give %player% 100"
- "set VIP %player% 30Day"
```

### Testing the reward

At **detail** of the Reward, at **bottom** of the UI, there is a `Redstone Dust`. By click on it, you can **test** the reward. All Items and Commands will be given to you. (No Database query/update will be executed.)

{% hint style="info" %}
Available through **Settings** and **Reward Repository**.
{% endhint %}

## Finally

After successful setting up of the rewards, you need to reload the plugin to load new rewards.

{% hint style="info" %}
To reload the whole plugin type `/TheCore Reload`
{% endhint %}


# Command management

Ability to manage command name, aliases and localization.

If you are not familiar with current command names, you can easily change them in order to your requirements.

This means you can translate all commands into your required language. It is awesome, isn't it?

## Folder

Each command has separated file. Files are located in folder `Command`.

## Example

```yaml
#CommandConfigurationFile: Command/TheCore.yml
Base:
  Name: "TheCore"
  Alias: #List of aliases, each alias on new line.
    - "base"
  Description: "Base command to operate with TheCore."
Component:
  Reload:
    Base:
      Name: "Reload"
      Alias: #List of aliases, each alias on new line. Instead of `Reload`, you can use `Rl`
        - "Rl"
    Sub:
      All:
        Name: "All"
```


# Advent Season

Make pleasant time to players while waiting for Christmas.

Amazing Minecraft extension with **Advent thematic**. Collection of addons, that make atmosphere during advent season more enjoyable.

Resource consist of multiple modules which communicate with each other.&#x20;

The main attraction, **Advent Calendar**, which gained favor in previous years was continuously extended with **Christmas Mail**, **St. Nicholas, Carols** and **Grinch**, which makes the whole season more engaging.


# Modules

Plugins belonging to Advent Season.

Each plugin has own section how to install and configure it.


# Advent Calendar

Increase player’s activity during whole December using advanced rewarding system.

From the 1st of December to the 24th/25th of December, players open windows in Advent Calendar and receiving amazing rewards.

Module transforms the holiday season into an interactive treasure hunt, where players open a new window each day to reveal hidden rewards.

It’s a daily dash of excitement, culminating in a festive countdown that keeps the Christmas spirit alive and players engaged.

{% embed url="<https://youtu.be/qkVBlaHgFgQ>" %}


# Installation

Plugin downloaded, what should I do next?

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run Advent Calendar plugin on your server, there are a few requirements that you have to check.

* Ensure you are using Minecraft version <mark style="color:red;">**1.8.8**</mark> or <mark style="color:red;">**later**</mark>. (Versions below 1.8.8 are not supported!)
* Your server has installed <mark style="color:red;">**Java8**</mark> or later.
* Make sure that you have already installed plugins [**TheCore**](https://www.spigotmc.org/resources/thecore.84131/)

## Installation

1. Put `AdventCalendar.jar` into plugins folder at your server.
2. Restart your server.&#x20;
   1. If you are using PlugMan, load it through it while server is running.
3. Done, jump into configuration and setting up.


# Command & Permissions

Commands to operate with Advent Calendar.

## Player commands

| Description                | Command                        | Permission                                                                                      |
| -------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
| Open Calendar GUI          | /AdventCalendar \[Open]        | <p>AdventCalendar.Command.AdventCalendar.Open<br><br>AdventCalendar.GUI.AdventCalendar.Open</p> |
| Claim Benefit              | /AdventCalendar Benefit Claim  | AdventCalendar.Benefit.Claim                                                                    |
| Player's help              | /AdventCalendar Help \[Player] | AdventCalendar.Help.Player                                                                      |
| Player's info about plugin | /AdventCalendar Info \[Player] | AdventCalendar.Info.Player                                                                      |
| Player's preferences       | /AdventCalendar Profile        | AdventCalendar.Profile.Preference                                                               |

## Admin commands

| Description                 | Command                                                | Permission                              |
| --------------------------- | ------------------------------------------------------ | --------------------------------------- |
| Admin's help                | /AdventCalendar Help Admin                             | AdventCalendar.Help.Admin               |
| Advanced info about plugin  | /AdventCalendar Info Admin                             | AdventCalendar.Info.Admin               |
| Settings                    | /AdventCalendar Settings                               | AdventCalendar.GUI.Settings.Open        |
| Reload whole plugin         | /AdventCalendar Reload \[All]                          | AdventCalendar.Reload.All               |
| Reload localization file    | /AdventCalendar Reload Locale                          | AdventCalendar.Reload.Locale            |
| Reload options file         | /AdventCalendar Reload Options                         | AdventCalendar.Reload.Options           |
| Link Figure with ArmorStand | /AdventCalendar Figure Find                            | AdventCalendar.Figure.Find              |
| Place Figure                | /AdventCalendar Figure Place                           | AdventCalendar.Figure.Place             |
| Remove Figure               | /AdventCalendar Figure Remove                          | AdventCalendar.Figure.Remove            |
| Change Figure's mode        | /AdventCalendar Figure SetMode \<Mode>                 | AdventCalendar.Figure.Mode              |
| Remove all statistics       | /AdventCalendar Statistics Remove All                  | AdventCalendar.Statistics.Remove.All    |
| Remove player's statistics  | /AdventCalendar Statistics Remove Player \<PlayerName> | AdventCalendar.Statistics.Remove.Player |

## Additional permissions

Collection of permissions not assigned to commands.

### Permissions

Highlighted permissions are considered as recommended

* Bold - Recommended to all players
* Italic - Recommended to only specific group of players

<table><thead><tr><th>Description</th><th>Permission</th><th data-hidden></th></tr></thead><tbody><tr><td>Base player's actions</td><td><strong>AdventCalendar.Player</strong></td><td></td></tr><tr><td>Complete package of all permissions</td><td><em>AdventCalendar.Admin</em></td><td></td></tr><tr><td>All reload commands</td><td>AdventCalendar.Reload.*</td><td></td></tr><tr><td>All figure commands</td><td>AdventCalendar.Figure.*</td><td></td></tr><tr><td>All statistics commands</td><td>AdventCalendar.Staticists.Remove.*</td><td></td></tr><tr><td>Claim any window. (For testing)</td><td>AdventCalendar.Claim.ByPass</td><td></td></tr><tr><td>Claim previous windows. (VIP)</td><td>AdventCalendar.Claim.Benevolent</td><td></td></tr></tbody></table>

## Explanatory notes

* **\[]** - **Square Brackets** - Optional argument. Command has the same effect, if that argument is not used.
* **<>** - **Less/More than signs** - Mandatory argument. It's a variable.
  * Example: **\<PlayerName>** will be replaced with **SobkySK**


# Configuration

Detailed explanation of variables at configuration files.

{% embed url="<https://youtu.be/qkVBlaHgFgQ>" %}


# Options

Looking into Options.yml

## Season duration

Range of days, while module is active.

```yaml
Options:
  Season:
    StartDateTime: "01.12.2023 00:00" #The datetime when the season starts.
    EndDateTime: "24.12.2023 23:59" #The datetime when the season ends.
```

{% hint style="warning" %}
Before and after this season, players won't be able to interact with Figure.
{% endhint %}

### Window

Window at Calendar opens once a day at specified time.

```yaml
Options:
  Season:
    Window:
      OpeningTime: "00:00"
```

If player misses to claim the window for specific day, he won't able to open in next day!

This **strict** behaviour can be changed to **benevolent** and player is able to open any previous windows.

```yaml
Options:
  Season:
    Window:
      ClaimingType: "STRICT" #STRICT or BENEVOLENT
```

## Sound

Sounds make the game more attractive. Currently played at various situations while interacting with figure.

#### Actions, when the Sounds are played.

* **OpeningWindow** - Sound played when the new window has been opened.
* **ClaimingReward** - Sound played to player at claiming reward.
* **Spin Button** - Sound played at LuckyWheel at interacting with Spin button.
* **Spin Animation** - Sound played at LuckyWheel at spinning with rewards.
* **Closing Animation** - Sound played at LuckyWheel at closing spining field.

List of latest sounds are available at <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html>

```yaml
Options:
  Sound: #Sounds valid for 1.12.X.
    Window:
      Open: "UI_TOAST_CHALLENGE_COMPLETE"
      Claim: "ENTITY_FIREWORK_TWINKLE"
    LuckyWheel:
      Spin:
        Button: "UI_BUTTON_CLICK"
        Animation: "ITEM_FLINTANDSTEEL_USE"
      Closing:
        Animation: "ENTITY_CHICKEN_STEP"
```

## Reward

Choice Types:

* `QUICK_ALL` - All assigned rewards are given to player
* `QUICK_CHANCE` - One reward is selected from assigned list by probability
* `LUCKY_WHEEL` - After click, new GUI will be opened. There, **random** reward from list selected for that day will be claimed. It is the same option as `QUICK_CHANCE`, but here is an animation

Example for **probability**. `DiamondTools` has 90% chance, `MoneyPocket` has 10% chance to win.&#x20;

{% hint style="danger" %}
Summary of probability at assinged rewards has to be **100.0**! Otherwise, system won't work correctly!
{% endhint %}

```yaml
Options:
  Reward:
    DefaultChoiceType: QUICK_ALL
```

#### Benefit

By opening all windows in calendar, you can reward players with **extra** gift.

```yaml
Options:
  Reward:
    Benefit:
      Active: false
```

## PlayTime Restriction

To prevent abuse from fake accounts opening windows or to enhance the gameplay experience, you can require players to spend a specified amount of time on your server before being able to open a window.

{% hint style="warning" %}
These settings are applied on each window! If you want to have different settings per-window, please check [Calendar section](/plugins/advent-season/modules/advent-calendar/configuration/calendar#playtime-restriction).
{% endhint %}

Types of Restriction:

* `Total` - Total time spent on the server.
  * Example: Player has to play for at least 5 Days(7200 Minutes) to be able to open a window.
* `Today` - Today's time spent on the server. Probably most used
  * Example: Player has to play for at least 30 Minutes **that day** to be able to open a window.
* `Session` -  Time spent on the server since player logged in.
  * Example: Player has to be **online** for at least 30 Minutes to be able to open a window.

<pre class="language-yaml"><code class="lang-yaml"><strong>Options:
</strong>  DefaultPlayTime:
    TotalMinute: 0
    TodayMinute: 0
    SessionMinute: 0
</code></pre>

{% hint style="warning" %}
To disable PlayTime Restriction, keep all values to `0`.
{% endhint %}

## Visual

Section represents components displayed at chat, boss bars and titles.

### Boss Bar

Players are able to see current information about upcoming event.

```yaml
Options:
  Visual:
    BossBar:
      Active: true
      Color: "PURPLE"
      Style: "SEGMENTED_20"
```

#### Available colors

`PINK`, `BLUE`, `RED`, `GREEN`, `YELLOW`, `PURPLE`, `WHITE`

#### Available styles

`SOLID`, `SEGMENTED_6`, `SEGMENTED_10`, `SEGMENTED_12`, `SEGMENTED_20`

### Information intervals

Information can be displayed in specified **intervals** and these itervals are mainly associtated with **BossBar**.

Imagine interval in math, but reversed because of countdown which is decresing.

\
If we want to display BossBar since **30** seconds to **10** seconds, we use interval `30:11`(`FROM:TO+1`). Plus **1** because of we want to hide BossBar in 10 seconds. (If we keep 10 seconds in the interval, BossBar will be hidden in 9 seconds.)

```yaml
Options:
  Visual:
    Info:
      Active: true
      Interval:
       - "60:56"
       - "10:1"
```

## Restriction

You can disable performing some actions while using the resource.

Operate with modules such as AdventCalendar or ChristmasMail can be restricted in specified worlds. Each world name on the new line.

```yaml
Options:
  Restriction:
    World:
      - world_the_end
      - world_nether
      - SomeAnotherRestrictedWrold
```

If you want to allow all worlds, you need to set **Empty Collections(`[]`)** here!

```yaml
Options:
  Restriction:
    World: []
```

## Figure (Santa)

Via **Figure**, players are able to open Advent Calendar. Santa also displays current status of the season.

System offers pre-defined **Armor Stand**, with clothes and head. All values can be changed in the configuration file. System also supports **NPC**, you can aslo equip it with armor or items.

{% hint style="warning" %}
Warning at placing the Figure. Figure copies your locations and also facing direction!
{% endhint %}

{% hint style="info" %}
To place Assistant type: `/AdventCalendar Figure Place`
{% endhint %}

If you have own Armor Stand, you can link it with Advent Figure. It only creates Holograms above the Armor Stand.

{% hint style="info" %}
To link Figure with the nearest Armor Stand in your range type: `/AdventCalendar Figure Link`
{% endhint %}

### Mode

List of modes mentioned above:

* NONE
* ARMOR\_STAND
* PLAYER
* HOLOGRAM

```yaml
Options:
  Figure:
    Mode: "ARMOR_STAND"
```

### Particle

Particles are spawning around the spawned Figure. You can keep them active or disable them. Also you can change Effect, Color, Speed and Amount.

```yaml
Options:
  Figure:
    Particle:
      Active: true
      TickDelay: 13 #How fast particles are spawned. (20 ticks = 1 second)
      Data:
        Effect: SPELL_WITCH
        Amount: 35
        Speed: 1.0 #Optional, Default 1.0
        Color: "255:255:255" #Optional, Default White
        Offest: #Optional, Offset from Figures's location. (Vector)
          X: .5
          Y: .5
          Z: .5
```

## Calendar Interface (GUI)

Calendar interface is the main part of the whole module, that's the reason it must looks perfect. And you can configure it to your requirements.

### Slot

Slots are configured at Calendar.yml file.

### Order

Specify the order of the day assigned to slot of the window.

* `RANDOM` - Days are assigned to window in random order. Shuffle order is created after loading of the plugin.
* `STATIC` - Days are assigned to window in order specified in Calendar.yml file.

```yaml
Options:
  GUI:
    Base:
      AdventCalendarGUI:
        Window:
          OrderType: "RANDOM"
```

### Window's Icon

Claimed window has another visual icon as closed or missed window.

* `REWARD` - Icon of reward is used as opened window.
* `DEFAULT` - Item from configuration is used as opened window.

```yaml
Options:
  GUI:
    Base:
      AdventCalendarGUI:
        Window:
          ClaimedIconType: "REWARD"
```


# Calendar

The Core file of the plugin!

{% hint style="warning" %}
There is expected that rewards are created, yet! To create rewards, check this tutorial: [How to create Reward](/plugins/thecore/configuration/centralized-reward-repository)
{% endhint %}

## Reward assignment

Again, there are two options how to assign them. By in-game UI or Manually in the confiuration file.

### **Using in-game Reward UI**

{% hint style="info" %}
To open GUI type `/AdventCalendar Settings`
{% endhint %}

{% embed url="<https://youtu.be/qkVBlaHgFgQ>" %}

### **Manually in the file**

Configuration file `Calendar.yml` is located at main folder of Advent Calendar.

#### Template of the CalendarUnit

```yaml
DAY_1:
  Type: "WINDOW"
  Day: 1
  Slot: 0
  Grinch:
    Loot:
      Probability: 25.0
  Icon:
    Material: SKULL_ITEM
    MaterialData: 3
    SkullData: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZTllMzlkOTFjMDRjMzBjYzFmNTMwZmVlNzk4ZWVkMjc5ZGRlNjBmOTVjMmUxZDE1NWMwZmRkMzYxZDA5NjJlZCJ9fX0=
    CustomModelData: 0
    Enchantment: false
    Color: 255:255:255
    ItemFlagList:
    - HIDE_ENCHANTS
    - HIDE_ATTRIBUTES
  Reward:
    ChoiceType: "QUICK__ALL"
    List: []
  PlayTime:
    TotalMinute: 0
    TodayMinute: 0
    SessionMinute: 0
```

## Type

Defines type of CalendarUnit

Allowed types:

* `WINDOW`
* `BENEFIT`

## Day

Assigns day with window

## Slot

Defines, where the window is located in Calendar GUI.

{% hint style="info" %}
At `RANDOM` WindowOrderingType(See Options.yml, GUI section), these slots are also used, but random assigned to days.
{% endhint %}

#### Reward

Choice Types:

* `QUICK__ALL` - All assigned rewards are given to player
* `QUICK__CHANCE` - One reward is selected from assigned list by probability
* `LUCKY_WHEEL` - After click, new GUI will be opened. There, **random** reward from list selected for that day will be claimed. It is the same option as `QUICK__CHANCE`, but here is an animation

Example for **probability**. `DiamondTools` has 90% chance, `MoneyPocket` has 10% chance to win.&#x20;

{% hint style="danger" %}
Summary of probability at assinged rewards has to be **100.0**! Otherwise, system won't work correctly!
{% endhint %}

```yaml
Reward:
  List:
  - DiamondTools:90.0
  - MoneyPocket:10.0
  ChoiceType: QUICK__CHANCE
```

## Grinch

Set the probability of the Grinch swiping a present.

```yaml
Grinch:
  Loot:
    Probability: 35.0 #Percentage ratio. Allowed range <O;100>
```

{% hint style="danger" %}
Plugin **Grinch** must be installed on the server!
{% endhint %}

## Icon

This icon is optional and it's used at Locked windows.

I personally recommend to setup this icon through in-game GUI. It's much simple.

## PlayTime Restriction

To override Default PlayTime Restriction, you need to specify values in this confiugration file.

> **Example** As default, player has to play at least 30 Minutes that day, but I want that in 24th of December, player has to play at least 60 Minutes.&#x20;

Types of Restriction:

* `Total` - Total time spent on the server.
  * Example: Player has to play for at least 5 Days(7200 Minutes) to be able to open a window.
* `Today` - Today's time spent on the server. Probably most used
  * Example: Player has to play for at least 30 Minutes **that day** to be able to open a window.
* `Session` -  Time spent on the server since player logged in.
  * Example: Player has to be **online** for at least 30 Minutes to be able to open a window.

<pre class="language-yaml"><code class="lang-yaml"><strong>PlayTime:
</strong>  TotalMinute: 0
  TodayMinute: 0
  SessionMinute: 0
</code></pre>

## Benefit

By claiming all windows, player are able to claim one **extra** gift. SetUp is the same as above. Just Day and Slot are ignored, and type is required to change to `BENEFIT`


# GUI

Everything is easier with interactive inventory.

Manual, how to configure items at GUI.

## Locale/GUI.yml

Configuration file, where all data and translations about items are located.

```yaml
Count: #Item's key. Maintained by system, can't be changed.
   HeadName: 
    EN: "&2&lActivity"
   Lore:
    EN:
     - "&6\u25CF &3Active &6\u00BB &7{option__figure__particle__activity}"
     - ""
     - "&6\u25CF &7Click"
     - " &2\u2022 &7Toggle flag"
   Material: "CHEST" #Name of the material
   MaterialData: 0 #Metadata of the item. Especially color. Only for 1.8.8 - 1.12.X
   Slot: 3 #Slot number where item will be played in inventory
   SkullData: "textures" #Texture value of player's head. 
   ItemFlagList: #Flags applied to item.
   - HIDE_ENCHANTS
   CustomModelData: 0 #Is an integer that may be associated client side with a custom item model. Supported at 1.14.X and aboove.
```

### ItemFlags

* HIDE\_ENCHANTS
* HIDE\_ATTRIBUTES
* HIDE\_UNBREAKABLE
* HIDE\_DESTROYS
* HIDE\_PLACED\_ON
* HIDE\_POTION\_EFFECTS
* HIDE\_COLOR - 1.16.X and above

### Helpful stuff

Materials: <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>

Textures of player's head: <https://minecraft-heads.com>

Grid can help you to compute right slot index.

<figure><img src="/files/PefhBeDrIS77iuDUBmV3" alt=""><figcaption></figcaption></figure>


# Command management

Ability to manage command name, aliases and localization.

If you are not familiar with current command names, you can easily change them in order to your requirements.

This means you can translate all commands into your required language. It is awesome, isn't it?

## Folder

Each command has separated file. Files are located in folder `Command`.

## Example

```yaml
#CommandConfigurationFile: Command/AdventCalendar.yml
Base:
  Name: "AdventCalendar"
  Alias: []  #List of aliases, each alias on new line.
  Description: "Base command to operate with AdventCalendar."
Component:
  Reload:
    Base:
      Name: "Reload"
      Alias: #List of aliases, each alias on new line. Instead of `Reload`, you can use `Rl`
        - "Rl"
    Sub:
      All:
        Name: "All"
```


# Placeholder

Simply way to get data of plugin at various places around the server.

## PlaceholderAPI

If you are familiar with [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) resource, you can obtain data and display it at other plugin.

* %advent\_calendar\_remains\_parsed% - Remaining time to change season state. (In parsed format 11d 12h 13m 14s or 12:13:14)
* %advent\_calendar\_remains\_seconds% - Remaining time to change season state. (In seconds)
* %advent\_calendar\_window\_count\_personal% - Count of claimed windows
* %advent\_calendar\_window\_count\_total% - Count of all windows


# Christmas Mail

Unite players this Christmas: Keep them to exchange wishes and gifts with festive cheer!

Fosters a community of giving, letting players send and receive seasonal wishes and gifts, all wrapped up in festive cheer.

It's a heartwarming exchange that unites the gaming community, making the Christmas spirit truly interactive and fun.


# Installation

Plugin downloaded, what should I do next?

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run Christmas Mail plugin on your server, there are a few requirements that you have to check.

* Ensure you are using Minecraft version <mark style="color:red;">**1.8.8**</mark> or <mark style="color:red;">**later**</mark>. (Versions below 1.8.8 are not supported!)
* Your server has installed <mark style="color:red;">**Java8**</mark> or later.
* Make sure that you have already installed plugins [**TheCore**](https://www.spigotmc.org/resources/thecore.84131/)

## Installation

1. Put `ChristmasMail.jar` into plugins folder at your server.
2. Restart your server.&#x20;
   1. If you are using PlugMan, load it through it while server is running.
3. Done, jump into configuration and setting up.


# Command & Permissions

Commands to operate with Christmas Mail.

## Player commands

| Description                | Command                                          | Permission                           |
| -------------------------- | ------------------------------------------------ | ------------------------------------ |
| Open MailBox GUI           | /ChristmasMail \[Open]                           | ChristmasMail.GUI.ChristmasMail.Open |
| Player's help              | /ChristmasMail Help \[Player]                    | ChristmasMail.Help.Player            |
| Player's info about plugin | /ChristmasMail Info \[Player]                    | ChristmasMail.Info.Player            |
| Player's preferences       | /ChristmasMail Profile                           | ChristmasMail.Profile.Preference     |
| Create MailBox             | /ChristmasMail MailBox Create \<Player>          | ChristmasMail.MailBox.Create         |
| Send Wish                  | /ChristmasMail MailBox Wish \<Player> \<Message> | ChristmasMail.MailBox.Message        |
| Send Gift                  | /ChristmasMail MailBox Gift Send \<Player>       | ChristmasMail.MailBox.Gift           |
| Remove Gift                | /ChristmasMail MailBox Gift Remove \<Player>     | ChristmasMail.MailBox.Gift           |

## Admin commands

| Description                 | Command                                               | Permission                             |
| --------------------------- | ----------------------------------------------------- | -------------------------------------- |
| Admin's help                | /ChristmasMail Help Admin                             | ChristmasMail.Help.Admin               |
| Advanced info about plugin  | /ChristmasMail Info Admin                             | ChristmasMail.Info.Admin               |
| Settings                    | /ChristmasMail Settings                               | ChristmasMail.GUI.Settings.Open        |
| Reload whole plugin         | /ChristmasMail Reload \[All]                          | ChristmasMail.Reload.All               |
| Reload localization file    | /ChristmasMail Reload Locale                          | ChristmasMail.Reload.Locale            |
| Reload options file         | /ChristmasMail Reload Options                         | ChristmasMail.Reload.Options           |
| Link Figure with ArmorStand | /ChristmasMail Figure Find                            | ChristmasMail.Figure.Find              |
| Place Figure                | /ChristmasMail Figure Place                           | ChristmasMail.Figure.Place             |
| Remove Figure               | /ChristmasMail Figure Remove                          | ChristmasMail.Figure.Remove            |
| Change Figure's mode        | /ChristmasMail Figure SetMode \<Mode>                 | ChristmasMail.Figure.Mode              |
| Remove all statistics       | /ChristmasMail Statistics Remove All                  | ChristmasMail.Statistics.Remove.All    |
| Remove player's statistics  | /ChristmasMail Statistics Remove Player \<PlayerName> | ChristmasMail.Statistics.Remove.Player |

## Additional permissions

Collection of permissions not assigned to commands.

### Permissions

Highlighted permissions are considered as recommended

* Bold - Recommended to all players
* Italic - Recommended to only specific group of players

<table><thead><tr><th>Description</th><th>Permission</th><th data-hidden></th></tr></thead><tbody><tr><td>Base player's actions</td><td><strong>ChristmasMail.Player</strong></td><td></td></tr><tr><td>Complete package of all permissions</td><td><em>ChristmasMail.Admin</em></td><td></td></tr><tr><td>All reload commands</td><td>ChristmasMail.Reload.*</td><td></td></tr><tr><td>All figure commands</td><td>ChristmasMail.Figure.*</td><td></td></tr><tr><td>All statistics commands</td><td>ChristmasMail.Staticists.Remove.*</td><td></td></tr><tr><td>MailBox capacity extension</td><td>ChristmasMail.MailBox.Capacity.&#x3C;Key></td><td></td></tr></tbody></table>

## Explanatory notes

* **\[]** - **Square Brackets** - Optional argument. Command has the same effect, if that argument is not used.
* **<>** - **Less/More than signs** - Mandatory argument. It's a variable.
  * Example: **\<PlayerName>** will be replaced with **SobkySK**


# Configuration

Detailed explanation of variables at configuration files.


# Options

Looking into Options.yml

## Season duration

Range of days, while module is active.

```yaml
Options:
  Season:
    StartDateTime: "01.12.2023 00:00" #The datetime when the season starts.
    GapDateTime: "24.12.2023 00:00" #The datetime when the sending mode is turned to reading mode.
    EndDateTime: "31.12.2023 23:59" #The datetime when the season ends.
```

{% hint style="warning" %}
Before and after this season, players won't be able to interact with Figure.
{% endhint %}

## MailBox

When player wants to send a surprise to his friennd, he needs to create **MailBox**.

{% hint style="warning" %}
Capacity of MailBoxes is limited.
{% endhint %}

```yaml
Options:
  MailBox:
    Capacity:
      Default: 9
```

### Extend capacity

By permissions, you can extend capacity of MailBoxes for player.

Simply create `KEY` and assign it value.

```yaml
Options:
  MailBox:
    Capacity:
      Extension:
        PRINCE: 3
        KING: 9
```

{% hint style="info" %}
Default + Extension = Total Capacity
{% endhint %}

#### Example

Extension with key `VIP_GOLD` extends capacity by `5`. In configuration file, it will look like this:

<pre class="language-yaml"><code class="lang-yaml">Options:
<strong>  MailBox:
</strong>    Capacity:
      Extension:
        VIP_GOLD: 5
</code></pre>

Player with permission `ChristmasMail.MailBox.Capacity.VIP_GOLD` can create **14** MailBoxes. (9 as Default + 5 by extension)

{% hint style="warning" %}
At applying more permissions on the player, only permission with highest value will be used!
{% endhint %}

## Vulgarism filter <a href="#vulgarism-filter" id="vulgarism-filter"></a>

Christmas time is about **peace** and **calm**, why to send inappropriate messages in wishes?

To handle vulgarisms in wishes, you need to put inappropriate words into specific file. One word has to be on separated line.

{% hint style="info" %}
If file `InappropriateBehaviour.txt` does not exist, please create one in ChristmasMail folder.
{% endhint %}

## Restriction

You can disable performing some actions while using the resource.

```yaml
Options:
  Restriction:
    World:
      - world_the_end
      - world_nether
      - SomeAnotherRestrictedWrold
```

If you want to allow all worlds, you need to set **Empty Collections(`[]`)** here!

```yaml
Options:
  Restriction:
    World: []
```

## Figure (Elf)

Via **Figure**, players are able to open Christmas Mail. Elf also displays current status of the season.

System offers pre-defined **Armor Stand**, with clothes and head. All values can be changed in the configuration file. System also supports **NPC**, you can aslo equip it with armor or items.

{% hint style="warning" %}
Warning at placing the Figure. Figure copies your locations and also facing direction!
{% endhint %}

{% hint style="info" %}
To place Assistant type: `/ChristmasMail Figure Place`
{% endhint %}

If you have own Armor Stand, you can link it with Advent Figure. It only creates Holograms above the Armor Stand.

{% hint style="info" %}
To link Elf with the nearest Armor Stand in your range type: `/ChristmasMail Figure Link`
{% endhint %}

### Mode

List of modes mentioned above:

* NONE
* ARMOR\_STAND
* PLAYER
* HOLOGRAM

```yaml
Options:
  Figure:
    Mode: "ARMOR_STAND"
```

### Particle

Particles are spawning around the spawned Figure. You can keep them active or disable them. Also you can change Effect, Color, Speed and Amount.

```yaml
Options:
  Figure:
    Particle:
      Active: true
      TickDelay: 13 #How fast particles are spawned. (20 ticks = 1 second)
      Data:
        Effect: SPELL_WITCH
        Amount: 35
        Speed: 1.0 #Optional, Default 1.0
        Color: "255:255:255" #Optional, Default White
        Offest: #Optional, Offset from Figures's location. (Vector)
          X: .5
          Y: .5
          Z: .5
```


# GUI

Everything is easier with interactive inventory.

Manual, how to configure items at GUI.

## Locale/GUI.yml

Configuration file, where all data and translations about items are located.

```yaml
Count: #Item's key. Maintained by system, can't be changed.
   HeadName: 
    EN: "&2&lActivity"
   Lore:
    EN:
     - "&6\u25CF &3Active &6\u00BB &7{option__figure__particle__activity}"
     - ""
     - "&6\u25CF &7Click"
     - " &2\u2022 &7Toggle flag"
   Material: "CHEST" #Name of the material
   MaterialData: 0 #Metadata of the item. Especially color. Only for 1.8.8 - 1.12.X
   Slot: 3 #Slot number where item will be played in inventory
   SkullData: "textures" #Texture value of player's head. 
   ItemFlagList: #Flags applied to item.
   - HIDE_ENCHANTS
   CustomModelData: 0 #Is an integer that may be associated client side with a custom item model. Supported at 1.14.X and aboove.
```

### ItemFlags

* HIDE\_ENCHANTS
* HIDE\_ATTRIBUTES
* HIDE\_UNBREAKABLE
* HIDE\_DESTROYS
* HIDE\_PLACED\_ON
* HIDE\_POTION\_EFFECTS
* HIDE\_COLOR - 1.16.X and above

### Helpful stuff

Materials: <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>

Textures of player's head: <https://minecraft-heads.com>

Grid can help you to compute right slot index.

<figure><img src="/files/PefhBeDrIS77iuDUBmV3" alt=""><figcaption></figcaption></figure>


# Command management

Ability to manage command name, aliases and localization.

If you are not familiar with current command names, you can easily change them in order to your requirements.

This means you can translate all commands into your required language. It is awesome, isn't it?

## Folder

Each command has separated file. Files are located in folder `Command`.

## Example

```yaml
#CommandConfigurationFile: Command/ChristmasMail.yml
Base:
  Name: "ChristmasMail"
  Alias: []  #List of aliases, each alias on new line.
  Description: "Base command to operate with ChristmasMail."
Component:
  Reload:
    Base:
      Name: "Reload"
      Alias: #List of aliases, each alias on new line. Instead of `Reload`, you can use `Rl`
        - "Rl"
    Sub:
      All:
        Name: "All"
```


# Placeholder

Simply way to get data of plugin at various places around the server.

## PlaceholderAPI

If you are familiar with [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) resource, you can obtain data and display it at other plugin.

* %advent\_christmas\_mail\_remains\_parsed% - Remaining time to change season state. (In parsed format 11d 12h 13m 14s or 12:13:14)
* %advent\_christmas\_mail\_remains\_seconds% - Remaining time to change season state. (In seconds)
* %advent\_christmas\_mail\_capacity% - Capacity of MailBoxes for player
* %advent\_christmas\_mail\_statistic\_sent% - Count of sent MailBoxes
* %advent\_christmas\_mail\_statistic\_received% - Count of received MailBoxes


# Grinch

The ever-rude green figure steals rewards, only to realize later that it was a mistake.

Module adds a twist of mischief to your game by letting the iconic green prankster sneak away with players' rewards, only to return them all on Christmas Eve.

It’s a playful challenge that keeps everyone surprised at the end.

{% embed url="<https://youtu.be/wAk_UvOn5qE>" %}


# Installation

Plugin downloaded, what should I do next?

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run Grinch plugin on your server, there are a few requirements that you have to check.

* Ensure you are using Minecraft version <mark style="color:red;">**1.8.8**</mark> or <mark style="color:red;">**later**</mark>. (Versions below 1.8.8 are not supported!)
* Your server has installed <mark style="color:red;">**Java8**</mark> or later.
* Make sure that you have already installed plugins [**TheCore**](https://www.spigotmc.org/resources/thecore.84131/)

## Installation

1. Put `Grinch.jar` into plugins folder at your server.
2. Restart your server.&#x20;
   1. If you are using PlugMan, load it through it while server is running.
3. Done, jump into configuration and setting up.


# Command & Permissions

Commands to operate with Grinch.

## Player commands

| Description                | Command                | Permission                |
| -------------------------- | ---------------------- | ------------------------- |
| Open Loot GUI              | /Grinch \[Open]        | Grinch.GUI.Grinch.Open    |
| Player's help              | /Grinch Help \[Player] | Grinch.Help.Player        |
| Player's info about plugin | /Grinch Info \[Player] | Grinch.Info.Player        |
| Player's preferences       | /Grinch Profile        | Grinch.Profile.Preference |

## Admin commands

| Description                 | Command                                        | Permission                            |
| --------------------------- | ---------------------------------------------- | ------------------------------------- |
| Admin's help                | /Grinch Help Admin                             | Grinch.Help.Admin                     |
| Advanced info about plugin  | /Grinch Info Admin                             | Grinch.Info.Admin                     |
| Settings                    | /Grinch Settings                               | SaintNicGrinchholas.GUI.Settings.Open |
| Reload whole plugin         | /Grinch Reload \[All]                          | Grinch.Reload.All                     |
| Reload localization file    | /Grinch Reload Locale                          | Grinch.Reload.Locale                  |
| Reload options file         | /Grinch Reload Options                         | Grinch.Reload.Options                 |
| Link Figure with ArmorStand | /Grinch Figure Find                            | Grinch.Figure.Find                    |
| Place Figure                | /Grinch Figure Place                           | Grinch.Figure.Place                   |
| Remove Figure               | /Grinch Figure Remove                          | Grinch.Figure.Remove                  |
| Change Figure's mode        | /Grinch Figure SetMode \<Mode>                 | Grinch.Figure.Mode                    |
| Remove all statistics       | /Grinch Statistics Remove All                  | Grinch.Statistics.Remove.All          |
| Remove player's statistics  | /Grinch Statistics Remove Player \<PlayerName> | Grinch.Statistics.Remove.Player       |

## Additional permissions

Collection of permissions not assigned to commands.

### Permissions

Highlighted permissions are considered as recommended

* Bold - Recommended to all players
* Italic - Recommended to only specific group of players

<table><thead><tr><th>Description</th><th>Permission</th><th data-hidden></th></tr></thead><tbody><tr><td>Base player's actions</td><td><strong>Grinch.Player</strong></td><td></td></tr><tr><td>Complete package of all permissions</td><td><em>Grinch.Admin</em></td><td></td></tr><tr><td>All reload commands</td><td>Grinch.Reload.*</td><td></td></tr><tr><td>All figure commands</td><td>Grinch.Figure.*</td><td></td></tr><tr><td>All statistics commands</td><td>Grinch.Staticists.Remove.*</td><td></td></tr></tbody></table>

## Explanatory notes

* **\[]** - **Square Brackets** - Optional argument. Command has the same effect, if that argument is not used.
* **<>** - **Less/More than signs** - Mandatory argument. It's a variable.
  * Example: **\<PlayerName>** will be replaced with **SobkySK**


# Configuration

Detailed explanation of variables at configuration files.

{% embed url="<https://youtu.be/wAk_UvOn5qE>" %}


# Options

Looking into Options.yml

## Season duration

Range of days, while module is active.

```yaml
Options:
  Season:
    StartDateTime: "01.12.2023 00:00" #The datetime when the season starts.
    GapDateTime: "24.12.2023 00:00" #The datetime when the rude behaviour is changed to polite.
    EndDateTime: "31.12.2023 23:59" #The datetime when the season ends.
```

{% hint style="warning" %}
Before and after this season, players won't be able to interact with Figure.
{% endhint %}

## Sound

Sounds make the game more attractive. Currently played at various situations while interacting with figure.

#### Actions, when the Sounds are played.

* Rude Behaviour - Sound played when the player interact with figure while Grinch is rude.
* Create Loot - Sound played to player when Grinch steals rewards.

List of latest sounds are available at <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html>

```yaml
Options:
  Sound: #Sounds valid for 1.12.X.
    Behaviour:
      Rude: "ENTITY_SHULKER_AMBIENT"
    Loot:
      Creation: "ENTITY_EVOCATION_ILLAGER_PREPARE_WOLOLO"
```

## Loot

Default percentage to steal the reward.

```yaml
Options:
  Loot:
    DefaultProbability: 25.0 #Percentage ratio. Allowed range <O;100>
```

## Restriction

You can disable performing some actions while using the resource.

```yaml
Options:
  Restriction:
    World:
      - world_the_end
      - world_nether
      - SomeAnotherRestrictedWrold
```

If you want to allow all worlds, you need to set **Empty Collections(`[]`)** here!

```yaml
Options:
  Restriction:
    World: []
```

## Figure (Grinch)

Via **Figure**, players are able to open Grinch's chamber of stolen rewards. Grinch also displays current status of the season.

System offers pre-defined **Armor Stand**, with clothes and head. All values can be changed in the configuration file. System also supports **NPC**, you can aslo equip it with armor or items.

{% hint style="warning" %}
Warning at placing the Figure. Grinch copies your locations and also facing direction!
{% endhint %}

{% hint style="info" %}
To place Assistant type: `/Grinch Figure Place`
{% endhint %}

If you have own Armor Stand, you can link it with Advent Figure. It only creates Holograms above the Armor Stand.

{% hint style="info" %}
To link Grinch with the nearest Armor Stand in your range type: `/Grinch Figure Link`
{% endhint %}

### Mode

List of modes mentioned above:

* NONE
* ARMOR\_STAND
* PLAYER
* HOLOGRAM

```yaml
Options:
  Figure:
    Mode: "ARMOR_STAND"
```

### Particle

Particles are spawning around the spawned Figure. You can keep them active or disable them. Also you can change Effect, Color, Speed and Amount.

```yaml
Options:
  Figure:
    Particle:
      Active: true
      TickDelay: 13 #How fast particles are spawned. (20 ticks = 1 second)
      Data:
        Effect: SPELL_WITCH
        Amount: 35
        Speed: 1.0 #Optional, Default 1.0
        Color: "255:255:255" #Optional, Default White
        Offest: #Optional, Offset from Figures's location. (Vector)
          X: .5
          Y: .5
          Z: .5
```


# GUI

Everything is easier with interactive inventory.

Manual, how to configure items at GUI.

## Locale/GUI.yml

Configuration file, where all data and translations about items are located.

```yaml
Count: #Item's key. Maintained by system, can't be changed.
   HeadName: 
    EN: "&2&lActivity"
   Lore:
    EN:
     - "&6\u25CF &3Active &6\u00BB &7{option__figure__particle__activity}"
     - ""
     - "&6\u25CF &7Click"
     - " &2\u2022 &7Toggle flag"
   Material: "CHEST" #Name of the material
   MaterialData: 0 #Metadata of the item. Especially color. Only for 1.8.8 - 1.12.X
   Slot: 3 #Slot number where item will be played in inventory
   SkullData: "textures" #Texture value of player's head. 
   ItemFlagList: #Flags applied to item.
   - HIDE_ENCHANTS
   CustomModelData: 0 #Is an integer that may be associated client side with a custom item model. Supported at 1.14.X and aboove.
```

### ItemFlags

* HIDE\_ENCHANTS
* HIDE\_ATTRIBUTES
* HIDE\_UNBREAKABLE
* HIDE\_DESTROYS
* HIDE\_PLACED\_ON
* HIDE\_POTION\_EFFECTS
* HIDE\_COLOR - 1.16.X and above

### Helpful stuff

Materials: <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>

Textures of player's head: <https://minecraft-heads.com>

Grid can help you to compute right slot index.

<figure><img src="/files/PefhBeDrIS77iuDUBmV3" alt=""><figcaption></figcaption></figure>


# Command management

Ability to manage command name, aliases and localization.

If you are not familiar with current command names, you can easily change them in order to your requirements.

This means you can translate all commands into your required language. It is awesome, isn't it?

## Folder

Each command has separated file. Files are located in folder `Command`.

## Example

```yaml
#CommandConfigurationFile: Command/Grinch.yml
Base:
  Name: "Grinch"
  Alias: []  #List of aliases, each alias on new line.
  Description: "Base command to operate with Grinch."
Component:
  Reload:
    Base:
      Name: "Reload"
      Alias: #List of aliases, each alias on new line. Instead of `Reload`, you can use `Rl`
        - "Rl"
    Sub:
      All:
        Name: "All"
```


# Placeholder

Simply way to get data of plugin at various places around the server.

## PlaceholderAPI

If you are familiar with [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) resource, you can obtain data and display it at other plugin.

* %advent\_grinch\_loot\_count\_total% - Count of stolen rewards from player.
* %advent\_grinch\_loot\_count\_unclaimed% - Count of unclaimed loot.


# Saint Nicholas

Prepare a small present for players during the National Day of St. Nicholas.

Plugin captures the enchanting tradition by allowing players to leave their cleaned shoes overnight and awaken to find them filled with treats and sweets.

It's a delightful exchange that brings the charm of this beloved holiday to life within the game.

St. Nicholas is coming usually on 6th of the December and brings gifts everyone who cleaned their boots.

Players have to bring his Assistant cleaned boots(or other item) the day before his coming. The next day, players can claim gift from Assistant.

{% embed url="<https://youtu.be/baZ02ur6ERw>" %}


# Installation

Plugin downloaded, what should I do next?

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run Saint Nicholas plugin on your server, there are a few requirements that you have to check.

* Ensure you are using Minecraft version <mark style="color:red;">**1.8.8**</mark> or <mark style="color:red;">**later**</mark>. (Versions below 1.8.8 are not supported!)
* Your server has installed <mark style="color:red;">**Java8**</mark> or later.
* Make sure that you have already installed plugins [**TheCore**](https://www.spigotmc.org/resources/thecore.84131/)

## Installation

1. Put `SaintNicholas.jar` into plugins folder at your server.
2. Restart your server.&#x20;
   1. If you are using PlugMan, load it through it while server is running.
3. Done, jump into configuration and setting up.


# Command & Permissions

Commands to operate with Saint Nicholas.

## Player commands

| Description                | Command                       | Permission                       |
| -------------------------- | ----------------------------- | -------------------------------- |
| Player's help              | /SaintNicholas Help \[Player] | SaintNicholas.Help.Player        |
| Player's info about plugin | /SaintNicholas Info \[Player] | SaintNicholas.Info.Player        |
| Player's preferences       | /SaintNicholas Profile        | SaintNicholas.Profile.Preference |

## Admin commands

| Description                 | Command                                               | Permission                             |
| --------------------------- | ----------------------------------------------------- | -------------------------------------- |
| Admin's help                | /SaintNicholas Help Admin                             | SaintNicholas.Help.Admin               |
| Advanced info about plugin  | /SaintNicholas Info Admin                             | SaintNicholas.Info.Admin               |
| Settings                    | /SaintNicholas Settings                               | SaintNicholas.GUI.Settings.Open        |
| Reload whole plugin         | /SaintNicholas Reload \[All]                          | SaintNicholas.Reload.All               |
| Reload localization file    | /SaintNicholas Reload Locale                          | SaintNicholas.Reload.Locale            |
| Reload options file         | /SaintNicholas Reload Options                         | SaintNicholas.Reload.Options           |
| Link Figure with ArmorStand | /SaintNicholas Figure Find                            | SaintNicholas.Figure.Find              |
| Place Figure                | /SaintNicholas Figure Place                           | SaintNicholas.Figure.Place             |
| Remove Figure               | /SaintNicholas Figure Remove                          | SaintNicholas.Figure.Remove            |
| Change Figure's mode        | /SaintNicholas Figure SetMode \<Mode>                 | SaintNicholas.Figure.Mode              |
| Remove all statistics       | /SaintNicholas Statistics Remove All                  | SaintNicholas.Statistics.Remove.All    |
| Remove player's statistics  | /SaintNicholas Statistics Remove Player \<PlayerName> | SaintNicholas.Statistics.Remove.Player |

## Additional permissions

Collection of permissions not assigned to commands.

### Permissions

Highlighted permissions are considered as recommended

* Bold - Recommended to all players
* Italic - Recommended to only specific group of players

<table><thead><tr><th>Description</th><th>Permission</th><th data-hidden></th></tr></thead><tbody><tr><td>Base player's actions</td><td><strong>SaintNicholas.Player</strong></td><td></td></tr><tr><td>Complete package of all permissions</td><td><em>SaintNicholas.Admin</em></td><td></td></tr><tr><td>All reload commands</td><td>SaintNicholas.Reload.*</td><td></td></tr><tr><td>All figure commands</td><td>SaintNicholas.Figure.*</td><td></td></tr><tr><td>All statistics commands</td><td>SaintNicholas.Staticists.Remove.*</td><td></td></tr></tbody></table>

## Explanatory notes

* **\[]** - **Square Brackets** - Optional argument. Command has the same effect, if that argument is not used.
* **<>** - **Less/More than signs** - Mandatory argument. It's a variable.
  * Example: **\<PlayerName>** will be replaced with **SobkySK**


# Configuration

Detailed explanation of variables at configuration files.

{% embed url="<https://youtu.be/baZ02ur6ERw>" %}


# Options

Looking into Options.yml

## Season duration

Range of days, while module is active.

```yaml
Options:
  Season:
    StartDateTime: "05.12.2023 00:00" #The datetime when the season starts.
    GapDateTime: "06.12.2023 05:00" #The datetime when the cleaning mode is turned to claiming mode.
    EndDateTime: "06.12.2023 23:59" #The datetime when the season ends.
```

{% hint style="warning" %}
Before and after this season, players won't be able to interact with Figure.
{% endhint %}

## Sound

Sounds make the game more attractive. Currently played at various situations while interacting with figure.

#### Actions, when the Sounds are played.

* Consume - Sound played when the player hands over the item.
* Claim - Sound played to player when he claims the reward.

List of latest sounds are available at <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html>

```yaml
Options:
  Sound: #Sounds valid for 1.12.X.
    Consume: "BLOCK_PORTAL_TRAVEL"
    Claim: "ENTITY_FIREWORK_TWINKLE"
```

## Reward

{% hint style="warning" %}
There is expected that rewards are created, yet! To create rewards, check this tutorial: [How to create Reward](https://wiki.innouniq.com/plugins/thecore/configuration/centralized-reward-repository)
{% endhint %}

{% embed url="<https://youtu.be/FK_LnRMi-JA>" %}

Choice Types:

* `QUICK_ALL` - All assigned rewards are given to player
* `QUICK_CHANCE` - One reward is selected from assigned list by probability

Example for **probability**. `DiamondTools` has 90% chance, `MoneyPocket` has 10% chance to win.&#x20;

{% hint style="danger" %}
Summary of probability at assinged rewards has to be **100.0**! Otherwise, system won't work correctly!
{% endhint %}

```yaml
Options:
  Reward:
    List:
    - DiamondTools:90.0
    - MoneyPocket:10.0
    ChoiceType: QUICK_CHANCE
```

#### Grinch

Set the probability of the Grinch swiping a present.

```yaml
Options:
  Reward:
    Grinch:
      Loot:
        Probability: 35.0 #Percentage ration. Allowed range <O;100>
```

{% hint style="danger" %}
Plugin **Grinch** must be installed on the server!
{% endhint %}

## PlayTime Restriction

To prevent abuse from fake accounts opening windows or to enhance the gameplay experience, you can require players to spend a specified amount of time on your server before being able to leave cleaned shoes at St. Nicholas.

Types of Restriction:

* `Total` - Total time spent on the server.
  * Example: Player has to play for at least 5 Days(7200 Minutes) to be able to leave cleaned shoes at St. Nicholas.
* `Today` - Today's time spent on the server. Probably most used
  * Example: Player has to play for at least 30 Minutes **that day** to be able to leave cleaned shoes at St. Nicholas.
* `Session` -  Time spent on the server since player logged in.
  * Example: Player has to be **online** for at least 30 Minutes to be able to leave cleaned shoes at St. Nicholas.

<pre class="language-yaml"><code class="lang-yaml"><strong>Options:
</strong>  PlayTime:
    TotalMinute: 0
    TodayMinute: 0
    SessionMinute: 0
</code></pre>

{% hint style="warning" %}
To disable PlayTime Restriction, keep all values to `0`.
{% endhint %}

## Consumer

List of items that figure accept

```yaml
Options:
  Consumer:
    MaterialList:
      - LEATHER_BOOTS
```

## Visual

Section represents components displayed at chat, boss bars and titles.

### Boss Bar

Players are able to see current information about upcoming event.

```yaml
Options:
  Visual:
    BossBar:
      Active: true
      Color: "PURPLE"
      Style: "SEGMENTED_20"
```

#### Available colors

`PINK`, `BLUE`, `RED`, `GREEN`, `YELLOW`, `PURPLE`, `WHITE`

#### Available styles

`SOLID`, `SEGMENTED_6`, `SEGMENTED_10`, `SEGMENTED_12`, `SEGMENTED_20`

### Information intervals

Information can be displayed in specified **intervals** and these itervals are mainly associtated with **BossBar**.

Imagine interval in math, but reversed because of countdown which is decresing.

\
If we want to display BossBar since **30** seconds to **10** seconds, we use interval `30:11`(`FROM:TO+1`). Plus **1** because of we want to hide BossBar in 10 seconds. (If we keep 10 seconds in the interval, BossBar will be hidden in 9 seconds.)

```yaml
Options:
  Visual:
    Info:
      Active: true
      Interval:
       - "60:56"
       - "10:1"
```

## Restriction

You can disable performing some actions while using the resource.

```yaml
Options:
  Restriction:
    World:
      - world_the_end
      - world_nether
      - SomeAnotherRestrictedWrold
```

If you want to allow all worlds, you need to set **Empty Collections(`[]`)** here!

```yaml
Options:
  Restriction:
    World: []
```

## Figure (Assistant)

St. Nicholas cannot be everywhere, so you have to invite Assistant, who helps him to collect items. Assistant also displays current status of the season.

System offers pre-defined **Armor Stand**, with clothes and head. All values can be changed in the configuration file. System also supports **NPC**, you can aslo equip it with armor or items.

{% hint style="warning" %}
Warning at placing the Figure. Assistant copies your locations and also facing direction!
{% endhint %}

{% hint style="info" %}
To place Assistant type: `/SaintNicholas Figure Place`
{% endhint %}

If you have own Armor Stand, you can link it with Advent Figure. It only creates Holograms above the Armor Stand.

{% hint style="info" %}
To link Assistant with the nearest Armor Stand in your range type: `/SaintNicholas Figure Link`
{% endhint %}

### Mode

List of modes mentioned above:

* NONE
* ARMOR\_STAND
* PLAYER
* HOLOGRAM

```yaml
Options:
  Figure:
    Mode: "ARMOR_STAND"
```

### Particle

Particles are spawning around the spawned Figure. You can keep them active or disable them. Also you can change Effect, Color, Speed and Amount.

```yaml
Options:
  Figure:
    Particle:
      Active: true
      TickDelay: 13 #How fast particles are spawned. (20 ticks = 1 second)
      Data:
        Effect: SPELL_WITCH
        Amount: 35
        Speed: 1.0 #Optional, Default 1.0
        Color: "255:255:255" #Optional, Default White
        Offest: #Optional, Offset from Figures's location. (Vector)
          X: .5
          Y: .5
          Z: .5
```


# GUI

Everything is easier with interactive inventory.

Manual, how to configure items at GUI.

## Locale/GUI.yml

Configuration file, where all data and translations about items are located.

```yaml
Count: #Item's key. Maintained by system, can't be changed.
   HeadName: 
    EN: "&2&lActivity"
   Lore:
    EN:
     - "&6\u25CF &3Active &6\u00BB &7{option__figure__particle__activity}"
     - ""
     - "&6\u25CF &7Click"
     - " &2\u2022 &7Toggle flag"
   Material: "CHEST" #Name of the material
   MaterialData: 0 #Metadata of the item. Especially color. Only for 1.8.8 - 1.12.X
   Slot: 3 #Slot number where item will be played in inventory
   SkullData: "textures" #Texture value of player's head. 
   ItemFlagList: #Flags applied to item.
   - HIDE_ENCHANTS
   CustomModelData: 0 #Is an integer that may be associated client side with a custom item model. Supported at 1.14.X and aboove.
```

### ItemFlags

* HIDE\_ENCHANTS
* HIDE\_ATTRIBUTES
* HIDE\_UNBREAKABLE
* HIDE\_DESTROYS
* HIDE\_PLACED\_ON
* HIDE\_POTION\_EFFECTS
* HIDE\_COLOR - 1.16.X and above

### Helpful stuff

Materials: <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>

Textures of player's head: <https://minecraft-heads.com>

Grid can help you to compute right slot index.

<figure><img src="/files/PefhBeDrIS77iuDUBmV3" alt=""><figcaption></figcaption></figure>


# Command management

Ability to manage command name, aliases and localization.

If you are not familiar with current command names, you can easily change them in order to your requirements.

This means you can translate all commands into your required language. It is awesome, isn't it?

## Folder

Each command has separated file. Files are located in folder `Command`.

## Example

```yaml
#CommandConfigurationFile: Command/SaintNicholas.yml
Base:
  Name: "SaintNicholas"
  Alias: []  #List of aliases, each alias on new line.
  Description: "Base command to operate with SaintNicholas."
Component:
  Reload:
    Base:
      Name: "Reload"
      Alias: #List of aliases, each alias on new line. Instead of `Reload`, you can use `Rl`
        - "Rl"
    Sub:
      All:
        Name: "All"
```


# Scavenger Hunt

Hide presents to add a dash of adventure while waiting for Christmas!

Adventurous plugin invites players into a festive frolic as you seek hidden presents in a snow-dusted virtual wonderland.

Each found gift involve the challenge that test player's wit and reward their diligence.

Hide Presents at specific locations and keep players for hunting them. At looking for the Christmas Presents, players can visit various special places at your server. You can advertise at that locations and gain much more from players.

{% embed url="<https://youtu.be/MIaRfaPd66s>" %}


# Installation

Plugin downloaded, what should I do next?

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run Christmas Scaveneger Hunt plugin on your server, there are a few requirements that you have to check.

* Ensure you are using Minecraft version <mark style="color:red;">**1.8.8**</mark> or <mark style="color:red;">**later**</mark>. (Versions below 1.8.8 are not supported!)
* Your server has installed <mark style="color:red;">**Java8**</mark> or later.
* Make sure that you have already installed plugins [**TheCore**](https://www.spigotmc.org/resources/thecore.84131/)

## Installation

1. Put `ChristmasScavengerHunt.jar` into plugins folder at your server.
2. Restart your server.&#x20;
   1. If you are using PlugMan, load it through it while server is running.
3. Done, jump into configuration and setting up.


# Command & Permissions

Commands to operate with Christmas Scavenger Hunt.

## Player commands

| Description                | Command                       | Permission                                |
| -------------------------- | ----------------------------- | ----------------------------------------- |
| Open Album                 | /ScavengerHunt                | ChristmasScavengerHunt.Album.Open         |
| Open album                 | /ScavengerHunt Album \[Open]  | ChristmasScavengerHunt.Album.Open         |
| Player's help              | /ScavengerHunt Help \[Player] | ChristmasScavengerHunt.Help.Player        |
| Player's info about plugin | /ScavengerHunt Info \[Player] | ChristmasScavengerHunt.Info.Player        |
| Player's preferences       | /ScavengerHunt Profile        | ChristmasScavengerHunt.Profile.Preference |

## Admin commands

| Description                       | Command                                                                   | Permission                                      |
| --------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------- |
| Admin's help                      | /ScavengerHunt Help Admin                                                 | ChristmasScavengerHunt.Help.Admin               |
| Advanced info about plugin        | /ScavengerHunt Info Admin                                                 | ChristmasScavengerHunt.Info.Admin               |
| Settings                          | /ScavengerHunt Settings                                                   | ChristmasScavengerHunt.GUI.Settings.Open        |
| Enter Setup Mode                  | /ScavengerHunt SetUp \[Enter]                                             | ChristmasScavengerHunt.SetUp.Enter              |
| Exit Setup Mode                   | /ScavengerHunt SetUp Exit                                                 | ChristmasScavengerHunt.SetUp.Exit               |
| Reload whole plugin               | /ScavengerHunt Reload \[All]                                              | ChristmasScavengerHunt.Reload.All               |
| Reload localization file          | /ScavengerHunt Reload Locale                                              | ChristmasScavengerHunt.Reload.Locale            |
| Reload options file               | /ScavengerHunt Reload Options                                             | ChristmasScavengerHunt.Reload.Options           |
| Remove all statistics             | /ScavengerHunt Statistics Remove All                                      | ChristmasScavengerHunt.Statistics.Remove.All    |
| Remove player's statistics        | /ScavengerHunt Statistics Remove Player \<PlayerName>                     | ChristmasScavengerHunt.Statistics.Remove.Player |
| Remove player's Christmas Present | /ScavengerHunt Statistics Remove Player \<PlayerName> \<ChristmasPresent> | ChristmasScavengerHunt.Statistics.Remove.Player |

## Additional permissions

Collection of permissions not assigned to commands.

### Permissions

Highlighted permissions are considered as recommended

* Bold - Recommended to all players
* Italic - Recommended to only specific group of players

<table><thead><tr><th>Description</th><th>Permission</th><th data-hidden></th></tr></thead><tbody><tr><td>Base player's actions</td><td><strong>ChristmasScavengerHunt.Player</strong></td><td></td></tr><tr><td>Complete package of all permissions</td><td><em>ChristmasScavengerHunt.Admin</em></td><td></td></tr><tr><td>All reload commands</td><td>ChristmasScavengerHunt.Reload.*</td><td></td></tr><tr><td>All SetUp commands</td><td>ChristmasScavengerHunt.SetUp.*</td><td></td></tr><tr><td>All statistics commands</td><td>ChristmasScavengerHunt.Staticists.Remove.*</td><td></td></tr></tbody></table>

## Explanatory notes

* **\[]** - **Square Brackets** - Optional argument. Command has the same effect, if that argument is not used.
* **<>** - **Less/More than signs** - Mandatory argument. It's a variable.
  * Example: **\<PlayerName>** will be replaced with **SobkySK**


# Configuration

Detailed explanation of variables at configuration files.

{% embed url="<https://youtu.be/MIaRfaPd66s>" %}


# Options

Looking into Options.yml

## Sound

Sounds make the game more attractive. Currently played at various situations while hunting presents.

#### Actions, when the Sounds are played.

* Claim - Sound played when the player click on found present.
* Hint - Sound played to player when he asks for a hint.
* EnterZone - Sound played when player enters zone where the present is located. (E.g. 20 blocks from Presents's location)

List of latest sounds are available at <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html>

```yaml
Options:
  Sound: #Sounds valid for 1.12.X.
    ChristmasPresent:
      Claim: "ENTITY_FIREWORK_TWINKLE"
      Hint: "BLOCK_NOTE_PLING"
      EnterZone: "ENTITY_CHICKEN_EGG"
```


# Christmas Present

Manual to Christmas Presents.

{% hint style="warning" %}
There is expected that rewards are created, yet! To create rewards, check this tutorial: [How to create Reward](/plugins/thecore/configuration/centralized-reward-repository)
{% endhint %}

## How to create Christmas Present <a href="#how-to-create-reward" id="how-to-create-reward"></a>

There are two options how to create ChristmasPresent. By in-game **UI** or **Manually** in the confiuration file. Both have some restrictions, so if you want use some advanced methods you will need to use combination of them.

### **Using in-game UI**

I recommend to watch SettingUp Tutorial to ScavengerHunt.

{% embed url="<https://youtu.be/FK_LnRMi-JA>" %}

{% embed url="<https://youtu.be/MIaRfaPd66s>" %}

{% hint style="info" %}
To open **SetUp UI** type `/ScavengerHunt SetUp`
{% endhint %}

{% hint style="info" %}
To open **Settings UI** type `/ScavengerHunt Settings`
{% endhint %}

### **Manually in the file**

Configuration file `ChristmasPresent.yml` is located at main folder of ScavengerHunt plugin.

#### **Template for the one Christmas Present**

```yaml
PRESENT_1:
  Name:
    EN: Purple Present
  Description:
    EN: First present you need!
  Hint:
    EN: []
  Rarity: EPIC
  Icon:
    Material: SKULL_ITEM
    MaterialData: 3
    SkullData: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZTllMzlkOTFjMDRjMzBjYzFmNTMwZmVlNzk4ZWVkMjc5ZGRlNjBmOTVjMmUxZDE1NWMwZmRkMzYxZDA5NjJlZCJ9fX0=
    CustomModelData: 0
    Enchantment: false
    Color: 255:255:255
    ItemFlagList:
    - HIDE_ENCHANTS
    - HIDE_ATTRIBUTES
  Condition:
    DateTimeRange:
      Active: false
      Start: 01.12.2023 00:00
      End: 02.12.2023 00:00
  Reward:
    List:
    - RewardKey_1
    ChoiceType: QUICK__ALL
  VisibilityZone: 5
  Requirement:
    CollectedPresent:
      Count: 1
  Particle:
    Active: true
    TickDelay: 13
    Data:
      Effect: SPELL_WITCH
      Amount: 35
  Grinch:
    Loot:
      Probability: 35.0
```

### Explanation of variables

#### Name, Description and Hint support multi-localization

```yaml
Name:
  EN: "Purple present"
  SK: "Fialový darček"
```

#### Rarity

Rarity is not required to use, but you can differ what present has higher value. Also you can create requirements using Rarity. (E.g. Collect 3 EPIC Presents.)

If you want to change rarity names of create more/less rarities. Edit `CustomValue.yml` , `GUI.yml` and `Localization` file.

#### Icon

Setting up icon is recommended through in-game UI. It is used at Album, Locations and Admin UI for better recognition between each other presents.

#### Condition

To increase rarity and also activity on your server, you can place a condition when is able to find Christmas Present. Players have to visit server and find egg in specified date-time range. Before and after this range, Present won't be able to find.&#x20;

#### Requirements

Before finding that present, player has to meet requirements. If player meets requiremenets, present is spawned at location. You can combine these three requirements as you wish.

Examples:

Player has to find specified Egg.

```yaml
Requirement:
  CollectedPresent:
    Key: "PRESENT_1" #Key of the present.
```

Player has to find at least one Present.

```yaml
Requirement:
  CollectedPresent:
    Count: 1
```

Player has to find at least 2 presents from COMMON rarity and one EPIC.

```yaml
Requirement:
  CollectedPresent:
    RarityCount:
    - "COMMON:2"
    - "EPIC"
```

#### PlayTime Requirement

To prevent abuse from fake accounts claiming rewards from presents or to enhance the gameplay experience, you can require players to spend a specified amount of time on your server before being able to find Christmas present.

Types of Restriction:

* `Total` - Total time spent on the server.
  * Example: Player has to play for at least 5 Days(7200 Minutes) to be able to find present.
* `Today` - Today's time spent on the server. Probably most used
  * Example: Player has to play for at least 30 Minutes **that day** to be able to find present..
* `Session` -  Time spent on the server since player logged in.
  * Example: Player has to be **online** for at least 30 Minutes to be able to find present..

<pre class="language-yaml"><code class="lang-yaml"><strong>Requirement:
</strong>  PlayTime:
    TotalMinute: 0
    TodayMinute: 0
    SessionMinute: 0
</code></pre>

{% hint style="warning" %}
To disable PlayTime Requirement, keep all values to `0`.
{% endhint %}

#### VisibilityZone

How near(in blocks) has to be player to spawn present.

```yaml
VisibilityZone: 20
```

#### Particle

Particles are spawning around the spawned Christmas Present. You can keep them active or disable them. Also you can change Effect, Color, Speed and Amount.

```yaml
Particle:
  Active: true
  TickDelay: 13 #How fast particles are spawned. (20 ticks = 1 second)
  Data:
    Effect: SPELL_WITCH
    Amount: 35
    Speed: 1.0 #Optional, Default 1.0
    Color: "255:255:255" #Optional, Default White
    Offest: #Optional, Offset from Christmas Present's location. (Vector)
      X: .5
      Y: .5
      Z: .5
```

#### Reward

Choice Types:

* `NONE` - No reward is given to player at claiming the Present.
* `QUICK_ALL` - All assigned rewards are given to player
* `QUICK_CHANCE` - One reward is selected from assigned list by probability

Example for **probability**. `DiamondTools` has 90% chance, `MoneyPocket` has 10% chance to win.&#x20;

{% hint style="danger" %}
Summary of probability at assinged rewards has to be **100.0**! Otherwise, system won't work correctly!
{% endhint %}

```yaml
Reward:
  List:
  - DiamondTools:90.0
  - MoneyPocket:10.0
  ChoiceType: QUICK_CHANCE
```

#### Grinch

Set the probability of the Grinch swiping a present.

```yaml
Grinch:
  Loot:
    Probability: 35.0 #Percentage ratio. Allowed range <O;100>
```

{% hint style="danger" %}
Plugin **Grinch** must be installed on the server!
{% endhint %}

### Testing the Christmas Present

At **detail** of the Christmas Present, at **bottom** of the UI, there is a `Redstone Dust`. By clicking on it, you can **test** the claiming. All Rewards assigned to this present will be given to you. (No Database query/update will be executed.)

{% hint style="info" %}
Available through **Settings** and **Christmas Present Repository**.
{% endhint %}

## Finally

After successful setting up of the presents, you need to reload the plugin to load new rewards.

{% hint style="info" %}
To reload the whole plugin type `/ScavengerHunt Reload`
{% endhint %}


# GUI

Everything is easier with interactive inventory.

Manual, how to configure items at GUI.

## Locale/GUI.yml

Configuration file, where all data and translations about items are located.

```yaml
Count: #Item's key. Maintained by system, can't be changed.
   HeadName: 
    EN: "&2&lActivity"
   Lore:
    EN:
     - "&6\u25CF &3Active &6\u00BB &7{option__figure__particle__activity}"
     - ""
     - "&6\u25CF &7Click"
     - " &2\u2022 &7Toggle flag"
   Material: "CHEST" #Name of the material
   MaterialData: 0 #Metadata of the item. Especially color. Only for 1.8.8 - 1.12.X
   Slot: 3 #Slot number where item will be played in inventory
   SkullData: "textures" #Texture value of player's head. 
   ItemFlagList: #Flags applied to item.
   - HIDE_ENCHANTS
   CustomModelData: 0 #Is an integer that may be associated client side with a custom item model. Supported at 1.14.X and aboove.
```

### ItemFlags

* HIDE\_ENCHANTS
* HIDE\_ATTRIBUTES
* HIDE\_UNBREAKABLE
* HIDE\_DESTROYS
* HIDE\_PLACED\_ON
* HIDE\_POTION\_EFFECTS
* HIDE\_COLOR - 1.16.X and above

### Helpful stuff

Materials: <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>

Textures of player's head: <https://minecraft-heads.com>

Grid can help you to compute right slot index.

<figure><img src="/files/PefhBeDrIS77iuDUBmV3" alt=""><figcaption></figcaption></figure>


# Command management

Ability to manage command name, aliases and localization.

If you are not familiar with current command names, you can easily change them in order to your requirements.

This means you can translate all commands into your required language. It is awesome, isn't it?

## Folder

Each command has separated file. Files are located in folder `Command`.

## Example

```yaml
#CommandConfigurationFile: Command/ChristmasScavengerHunt.yml
Base:
  Name: "ChristmasScavengerHunt"
  Alias: []  #List of aliases, each alias on new line.
  Description: "Base command to operate with ChristmasScavengerHunt."
Component:
  Reload:
    Base:
      Name: "Reload"
      Alias: #List of aliases, each alias on new line. Instead of `Reload`, you can use `Rl`
        - "Rl"
    Sub:
      All:
        Name: "All"
```


# Placeholder

Simply way to get data of plugin at various places around the server.

## PlaceholderAPI

If you are familiar with [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) resource, you can obtain data and display it at other plugin.

* %advent\_christmas\_scavenger\_hunt\_christmas\_present\_count\_total% - Count of all Christmas Presents.
* %advent\_christmas\_scavenger\_hunt\_christmas\_present\_count\_found% - Count of found Christmas Presents.


# Advent Calendar

New generation of Advent Calendar?

Yes, that's also possible. Simply configure the presents to be searchable only from a specific date or for 24 hours. This way, a new present will spawn each day, and players will have the excitement of finding it.

### Small hints how to achieve this solution.

1. Prepare **24** presents.
2. Assign them **rewards**.
3. At each present activate **DateTimeRange Condition** and set time range.

Example of condition section in `ChristmasPresent.yml`

<pre class="language-yaml"><code class="lang-yaml">PRESENT_1: #DAY 1
  #Other stuff data
  Condition:
    DateTimeRange:
      Active: true
      Start: 01.12.2023 00:00
      End: 02.12.2023 00:00
PRESENT_2: #DAY 2
  Condition:
    DateTimeRange:
      Active: true
      Start: 02.12.2023 00:00
      End: 03.12.2023 00:00
PRESENT_3: #DAY 3
  Condition:
    DateTimeRange:
      Active: true
      Start: 03.12.2023 00:00
      End: 04.12.2023 00:00
<strong>#.
</strong>#.
#.
PRESENT_24: #DAY 24
  Condition:
    DateTimeRange:
      Active: true
      Start: 24.12.2023 00:00
      End: 25.12.2023 00:00
</code></pre>

#### Benevolent mode

To allow claim *"missed"* presents(windows), change **End Date** at all presents to last day of the Season.

```
End: 25.12.2023 00:00
```

### Benefit

To simulate Benefit from Advent Calendar, just create new extra present and set Requirement, that player has to find all previous 24 presents.

```yaml
BENEFIT:
  Requirement:
    CollectedPresent:
      Count: 24
```

It's all in your hands—how you configure this plugin is up to you. This was just my suggestion for maximizing its potential. Let your imagination lead the way! 😉


# FAQ

Frequently asked questions

> **Cannot load plugin. Plugin is not enabled on the server.**

* Please, make sure that you have already installed prerequisites [TheCore](https://www.spigotmc.org/resources/thecore.84131/)

> **How to SetUp rewards?**

* At first, please read [this Wiki section](/plugins/thecore/configuration/centralized-reward-repository), where you will find answers to your questions.
* At any problem, you can contact me.


# Summary

Hope, that this documentation helped you to configure the whole Advent Season.

At any questions, please visit our [Discord](https://discord.gg/vPHWEapDGR) server and create ticket. Support answers in a few hours, sometimes in a few minutes 😉

I wish you Merry Christmas, enjoy this beautiful season of the year 🎄


# Easter Season

Enhance experience on the server with stunning addons.

Collection of plugins with **Easter thematic**.

Before installing purchased plugin, you need to ensure, that `Easter Core` plugin is running on the server.


# Modules

Plugins belonging to Easter Season.

Each plugin has own section how to install and configure it.


# Egg Hunt

Adventurous Minecraft extension, where player has to explore the world to find all hidden Easter Eggs.

Hide Eggs at specific locations and keep players for hunting them. At looking for the Eggs, players can visit various special places at your server. You can advertise at that locations and gain much more from players.

{% embed url="<https://www.youtube.com/watch?v=YSCtwGplwdk>" %}


# Installation

Plugin downloaded, what should I do next?

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run Egg Hunt plugin on your server, there are a few requirements that you have to check.

* Ensure you are using Minecraft version <mark style="color:red;">**1.8.8**</mark> or <mark style="color:red;">**later**</mark>. (Versions below 1.8.8 are not supported!)
* Your server has installed <mark style="color:red;">**Java8**</mark> or later.
* Make sure that you have already installed plugins [**TheCore**](https://www.spigotmc.org/resources/thecore.84131/)

## Installation

1. Put `Egg Hunt.jar` into plugins folder at your server.
2. Restart your server.&#x20;
   1. If you are using PlugMan, load it through it while server is running.
3. Done, jump into configuration and setting up.


# Command & Permissions

Commands to operate with Egg Hunt.

## Player commands

| Description                | Command                 | Permission                 |
| -------------------------- | ----------------------- | -------------------------- |
| Open Album                 | /EggHunt                | EggHunt.Album.Open         |
| Open album                 | /EggHunt Album \[Open]  | EggHunt.Album.Open         |
| Player's help              | /EggHunt Help \[Player] | EggHunt.Help.Player        |
| Player's info about plugin | /EggHunt Info \[Player] | EggHunt.Info.Player        |
| Player's preferences       | /EggHunt Profile        | EggHunt.Profile.Preference |

## Admin commands

| Description                | Command                                                      | Permission                       |
| -------------------------- | ------------------------------------------------------------ | -------------------------------- |
| Admin's help               | /EggHunt Help Admin                                          | EggHunt.Help.Admin               |
| Advanced info about plugin | /EggHunt Info Admin                                          | EggHunt.Info.Admin               |
| Settings                   | /EggHunt Settings                                            | EggHunt.GUI.Settings.Open        |
| Enter Setup Mode           | /EggHunt SetUp \[Enter]                                      | EggHunt.SetUp.Enter              |
| Exit Setup Mode            | /EggHunt SetUp Exit                                          | EggHunt.SetUp.Exit               |
| Reload whole plugin        | /EggHunt Reload \[All]                                       | EggHunt.Reload.All               |
| Reload localization file   | /EggHunt Reload Locale                                       | EggHunt.Reload.Locale            |
| Reload options file        | /EggHunt Reload Options                                      | EggHunt.Reload.Options           |
| Remove all statistics      | /EggHunt Statistics Remove All                               | EggHunt.Statistics.Remove.All    |
| Remove player's statistics | /EggHunt Statistics Remove Player \<PlayerName>              | EggHunt.Statistics.Remove.Player |
| Remove player's Easter Egg | /EggHunt Statistics Remove Player \<PlayerName> \<EasterEgg> | EggHunt.Statistics.Remove.Player |

## Additional permissions

Collection of permissions not assigned to commands.

### Permissions

Highlighted permissions are considered as recommended

* Bold - Recommended to all players
* Italic - Recommended to only specific group of players

<table><thead><tr><th>Description</th><th>Permission</th><th data-hidden></th></tr></thead><tbody><tr><td>Base player's actions</td><td><strong>EggHunt.Player</strong></td><td></td></tr><tr><td>Complete package of all permissions</td><td><em>EggHunt.Admin</em></td><td></td></tr><tr><td>All reload commands</td><td>EggHunt.Reload.*</td><td></td></tr><tr><td>All SetUp commands</td><td>EggHunt.SetUp.*</td><td></td></tr><tr><td>All statistics commands</td><td>EggHunt.Staticists.Remove.*</td><td></td></tr></tbody></table>

## Explanatory notes

* **\[]** - **Square Brackets** - Optional argument. Command has the same effect, if that argument is not used.
* **<>** - **Less/More than signs** - Mandatory argument. It's a variable.
  * Example: **\<PlayerName>** will be replaced with **SobkySK**


# Configuration

Detailed explanation of variables at configuration files.


# Options

Looking into Options.yml

## Sound

Sounds make the game more attractive. Currently played at various situations while hunting eggs.

#### Actions, when the Sounds are played.

* Claim - Sound played when the player click on found egg.
* Hint - Sound played to player when he asks for a hint.
* EnterZone - Sound played when player enters zone where the egg is located. (E.g. 20 blocks from Egg's location)

List of latest sounds are available at <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html>

```yaml
Options:
  Sound: #Sounds valid for 1.12.X.
    EasterEgg:
      Claim: "ENTITY_FIREWORK_TWINKLE"
      Hint: "BLOCK_NOTE_PLING"
      EnterZone: "ENTITY_CHICKEN_EGG"
```


# Easter Egg

Manual to Easter Eggs.

{% hint style="warning" %}
There is expected that rewards are created, yet! To create rewards, check this tutorial: [How to create Reward](/plugins/thecore/configuration/centralized-reward-repository)
{% endhint %}

## How to create Easter Egg <a href="#how-to-create-reward" id="how-to-create-reward"></a>

There are two options how to create EasterEgg. By in-game **UI** or **Manually** in the confiuration file. Both have some restrictions, so if you want use some advanced methods you will need to use combination of them.

### **Using in-game UI**

I recommend to watch SettingUp Tutorial to EggHunt.

{% embed url="<https://www.youtube.com/watch?v=YSCtwGplwdk>" %}

{% hint style="info" %}
To open **SetUp UI** type `/Easter SetUp`
{% endhint %}

{% hint style="info" %}
To open **Settings UI** type `/Easter Settings`
{% endhint %}

### **Manually in the file**

Configuration file `EasterEgg.yml` is located at main folder of Egghunt plugin.

#### **Template for the one Easter Egg**

```yaml
EGG_1:
  Name:
    EN: Unicorn Egg
  Description:
    EN: Unicorn
  Hint:
    EN: []
  Rarity: EPIC
  Icon:
    Material: MONSTER_EGG
    MaterialData: 55
    CustomModelData: 0
    Enchantment: false
    Color: 255:255:255
    ItemFlagList:
    - HIDE_ENCHANTS
    - HIDE_ATTRIBUTES
  Condition:
    DateTimeRange:
      Active: false
      Start: 01.04.2023 00:00
      End: 02.04.2023 00:00
  Reward:
    List:
    - RewardKey_1
    ChoiceType: QUICK__ALL
  VisibilityZone: 5
  Requirement:
    CollectedEgg:
      Count: 1
  Particle:
    Active: true
    TickDelay: 13
    Data:
      Effect: SPELL_WITCH
      Amount: 35
```

### Explanation of variables

#### Name, Description and Hint support multi-localization

```yaml
Name:
  EN: "Unicorn Egg"
  SK: "Vajíčko Jednorožca"
```

#### Rarity

Rarity is not required to use, but you can differ what egg has higher value. Also you can create requirements using Rarity. (E.g. Collect 3 EPIC Eggs.)

If you want to change rarity names of create more/less rarities. Edit `CustomValue.yml` , `GUI.yml` and `Localization` file.

#### Icon

Setting up icon is recommended through in-game UI. It is used at Album, Locations and Admin UI for better recognition between each other eggs.

#### Condition

To increase rarity and also activity on your server, you can place a condition when is able to find Easter Egg. Players have to visit server and find egg in specified date-time range. Before and after this range, Egg won't be able to find.&#x20;

#### Requirements

Before finding that egg, player has to meet requirements. If player meets requiremenets, egg is spawned at location. You can combine these three requirements as you wish.

Examples:

Player has to find specified Egg.

```yaml
Requirement:
  CollectedEgg:
    Key: "EGG_1" #Key of the egg.
```

Player has to find at least one Egg.

```yaml
Requirement:
  CollectedEgg:
    Count: 1
```

Player has to find at least 2 eggs from COMMON rarity and one EPIC.

```yaml
Requirement:
  CollectedEgg:
    RarityCount:
    - "COMMON:2"
    - "EPIC"
```

#### PlayTime Requirement

To prevent abuse from fake accounts claiming rewards from eggs or to enhance the gameplay experience, you can require players to spend a specified amount of time on your server before being able to find Easter egg.

Types of Restriction:

* `Total` - Total time spent on the server.
  * Example: Player has to play for at least 5 Days(7200 Minutes) to be able to find egg.
* `Today` - Today's time spent on the server. Probably most used
  * Example: Player has to play for at least 30 Minutes **that day** to be able to find egg..
* `Session` -  Time spent on the server since player logged in.
  * Example: Player has to be **online** for at least 30 Minutes to be able to find egg..

<pre class="language-yaml"><code class="lang-yaml"><strong>Requirement:
</strong>  PlayTime:
    TotalMinute: 0
    TodayMinute: 0
    SessionMinute: 0
</code></pre>

{% hint style="warning" %}
To disable PlayTime Requirement, keep all values to `0`.
{% endhint %}

#### VisibilityZone

How near(in blocks) has to be player to spawn egg.

```yaml
VisibilityZone: 20
```

#### Particle

Particles are spawning around the spawned Easter Egg. You can keep them active or disable them. Also you can change Effect, Color, Speed and Amount.

```yaml
Particle:
  Active: true
  TickDelay: 13 #How fast particles are spawned. (20 ticks = 1 second)
  Data:
    Effect: SPELL_WITCH
    Amount: 35
    Speed: 1.0 #Optional, Default 1.0
    Color: "255:255:255" #Optional, Default White
    Offest: #Optional, Offset from EasterEgg's location. (Vector)
      X: .5
      Y: .5
      Z: .5
```

#### Reward

Choice Types:

* `NONE` - No reward is given to player at claiming the Egg.
* QUICK\_ALL - All assigned rewards are given to player
* QUICK\_CHANCE - One reward is selected from assigned list by probability

Example for **probability**. `DiamondTools` has 90% chance, `MoneyPocket` has 10% chance to win.&#x20;

{% hint style="danger" %}
Summary of probability at assinged rewards has to be **100.0**! Otherwise, system won't work correctly!
{% endhint %}

```yaml
Reward:
  List:
  - DiamondTools:90.0
  - MoneyPocket:10.0
  ChoiceType: QUICK_CHANCE
```

### Testing the Easter Egg

At **detail** of the Easter Egg, at **bottom** of the UI, there is a `Redstone Dust`. By click on it, you can **test** the claiming. All Rewards assigned to this egg will be given to you. (No Database query/update will be executed.)

{% hint style="info" %}
Available through **Settings** and **Easter Egg Repository**.
{% endhint %}

## Finally

After successful setting up of the eggs, you need to reload the plugin to load new rewards.

{% hint style="info" %}
To reload the whole plugin type `/EggHunt Reload`
{% endhint %}


# GUI

Everything is easier with interactive inventory.

Manual, how to configure items at GUI.

## Locale/GUI.yml

Configuration file, where all data and translations about items are located.

```yaml
Count: #Item's key. Maintained by system, can't be changed.
   HeadName: 
    EN: "&2&lActivity"
   Lore:
    EN:
     - "&6\u25CF &3Active &6\u00BB &7{option__figure__particle__activity}"
     - ""
     - "&6\u25CF &7Click"
     - " &2\u2022 &7Toggle flag"
   Material: "CHEST" #Name of the material
   MaterialData: 0 #Metadata of the item. Especially color. Only for 1.8.8 - 1.12.X
   Slot: 3 #Slot number where item will be played in inventory
   SkullData: "textures" #Texture value of player's head. 
   ItemFlagList: #Flags applied to item.
   - HIDE_ENCHANTS
   CustomModelData: 0 #Is an integer that may be associated client side with a custom item model. Supported at 1.14.X and aboove.
```

### ItemFlags

* HIDE\_ENCHANTS
* HIDE\_ATTRIBUTES
* HIDE\_UNBREAKABLE
* HIDE\_DESTROYS
* HIDE\_PLACED\_ON
* HIDE\_POTION\_EFFECTS
* HIDE\_COLOR - 1.16.X and above

### Helpful stuff

Materials: <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>

Textures of player's head: <https://minecraft-heads.com>

Grid can help you to compute right slot index.

<figure><img src="/files/PefhBeDrIS77iuDUBmV3" alt=""><figcaption></figcaption></figure>


# Command management

Ability to manage command name, aliases and localization.

If you are not familiar with current command names, you can easily change them in order to your requirements.

This means you can translate all commands into your required language. It is awesome, isn't it?

## Folder

Each command has separated file. Files are located in folder `Command`.

## Example

```yaml
#CommandConfigurationFile: Command/EggHunt.yml
Base:
  Name: "EggHunt"
  Alias: []  #List of aliases, each alias on new line.
  Description: "Base command to operate with EggHunt."
Component:
  Reload:
    Base:
      Name: "Reload"
      Alias: #List of aliases, each alias on new line. Instead of `Reload`, you can use `Rl`
        - "Rl"
    Sub:
      All:
        Name: "All"
```


# Placeholder

Simply way to get data of plugin at various places around the server.

## PlaceholderAPI

If you are familiar with [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) resource, you can obtain data and display it at other plugin.

* %easter\_egg\_hunt\_easter\_egg\_count\_total% - Count of all Easter Eggs.
* %easter\_egg\_hunt\_easter\_egg\_count\_found% - Count of found Easter Eggs.


# FAQ

Frequently asked questions

> **Cannot load plugin. Plugin is not enabled on the server.**

* Please, make sure that you have already installed prerequisites [TheCore](https://www.spigotmc.org/resources/thecore.84131/)

> **How to SetUp rewards?**

* At first, please read [this Wiki section](/plugins/thecore/configuration/centralized-reward-repository), where you will find answers to your questions.
* At any problem, you can contact me.


# Summary

Hope, that this documentation helped you to configure the whole Easter Season.

At any questions, please visit our [Discord](https://discord.gg/vPHWEapDGR) server and create ticket. Support answers in a few hours, sometimes in a few minutes 😉

Enjoy the season 🐣


# Melody Player

Allow players to enjoy famous songs on the server.

Enriches your gaming experience with a symphony of sounds, playing a diverse selection of songs and melodies that resonate with every action and event within the game.

It's an auditory journey that enhances gameplay, making every moment feel like its own unique score.

#### Perfectly fits with [**Advent Season**](/plugins/advent-season)

Musical delight, infusing the game with the joyous sounds of Christmas. It serenades players with an array of classic carols and festive songs, setting the perfect soundtrack for a holiday adventure.


# Installation

Plugin downloaded, what should I do next?

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run Melody Player plugin on your server, there are a few requirements that you have to check.

* Ensure you are using Minecraft version <mark style="color:red;">**1.8.8**</mark> or <mark style="color:red;">**later**</mark>. (Versions below 1.8.8 are not supported!)
* Your server has installed <mark style="color:red;">**Java8**</mark> or later.
* Make sure that you have already installed plugin [**TheCore**](https://www.spigotmc.org/resources/thecore.84131/) and [**NoteBlockAPI**](https://www.spigotmc.org/resources/noteblockapi.19287/)

## Installation

1. Put `MelodyPlayer.jar` into plugins folder at your server.
2. Restart your server.&#x20;
   1. If you are using PlugMan, load it through it while server is running.
3. Done, jump into configuration and setting up.


# Commands & Permissions

Commands to operate with Melody Player.

## Player commands

| Description                | Command                                        | Permission                      |
| -------------------------- | ---------------------------------------------- | ------------------------------- |
| Player's help              | /MelodyPlayer Help \[Player]                   | MelodyPlayer.Help.Player        |
| Player's info about plugin | /MelodyPlayer Info \[Player]                   | MelodyPlayer.Info.Player        |
| Player's preferences       | /MelodyPlayer Profile                          | MelodyPlayer.Profile.Preference |
| Listening melodies         | /MelodyPlayer Profile Listening Enable/Disable | MelodyPlayer.Profile.Preference |

## Admin commands

| Description                          | Command                                                  | Permission                       |
| ------------------------------------ | -------------------------------------------------------- | -------------------------------- |
| Admin's help                         | /MelodyPlayer Help Admin                                 | MelodyPlayer.Help.Admin          |
| Advanced info about plugin           | /MelodyPlayer Info Admin                                 | MelodyPlayer.Info.Admin          |
| Create MelodyPlayer                  | /MelodyPlayer Player Create \[MelodyPlayer]              | MelodyPlayer.Player.Create       |
| Set Location to MelodyPlayer         | /MelodyPlayer Player SetLocation \<MelodyPlayer>         | MelodyPlayer.Player.SetLocation  |
| Set HologramLocation to MelodyPlayer | /MelodyPlayer Player SetHologramLocation \<MelodyPlayer> | MelodyPlayer.Player.SetLocation  |
| MelodyPlayer Settings                | /MelodyPlayer Player Settings \<MelodyPlayer>            | MelodyPlayer.Player.Settings     |
| MelodyPlayer ControlPanel            | /MelodyPlayer Player ControlPanel \<MelodyPlayer>        | MelodyPlayer.Player.ControlPanel |
| Settings                             | /MelodyPlayer Settings                                   | MelodyPlayer.GUI.Settings.Open   |
| Reload whole plugin                  | /MelodyPlayer Reload \[All]                              | MelodyPlayer.Reload.All          |
| Reload localization file             | /MelodyPlayer Reload Locale                              | MelodyPlayer.Reload.Locale       |
| Reload options file                  | /MelodyPlayer Reload Options                             | MelodyPlayer.Reload.Options      |
| Reload MelodyPlayer                  | /MelodyPlayer Reload Player \<MelodyPlayer>              | MelodyPlayer.Reload.Player       |

## Additional permissions

Collection of permissions not assigned to commands.

### Permissions

Highlighted permissions are considered as recommended

* Bold - Recommended to all players
* Italic - Recommended to only specific group of players

<table><thead><tr><th>Description</th><th>Permission</th><th data-hidden></th></tr></thead><tbody><tr><td>Base player's actions</td><td><strong>MelodyPlayer.Player</strong></td><td></td></tr><tr><td>Complete package of all permissions</td><td><em>MelodyPlayer.Admin</em></td><td></td></tr><tr><td>All reload commands</td><td>MelodyPlayer.Reload.*</td><td></td></tr><tr><td>MelodyPlayer management</td><td>MelodyPlayer.Player.*</td><td></td></tr><tr><td>AuthorLimit ByPass</td><td>MelodyPlayer.Player.Author.ByPass</td><td></td></tr><tr><td>AuthorLimit extension</td><td>MelodyPlayer.Player.Author.Limit.&#x3C;Key></td><td></td></tr></tbody></table>

## Explanatory notes

* **\[]** - **Square Brackets** - Optional argument. Command has the same effect, if that argument is not used.
* **<>** - **Less/More than signs** - Mandatory argument. It's a variable.
  * Example: **\<PlayerName>** will be replaced with **SobkySK**


# Configuration

Detailed explanation of variables at configuration files.


# Options

Looking into Options.yml

## AuthorLimit

{% hint style="warning" %}
Limit of MelodyPlayer is limited per Author(player).
{% endhint %}

```yaml
Options:
  Player:
    AuthorLimit:
      Default: 9
```

### Extend limit

By permissions, you can extend limit of MelodyPlayers for player.&#x20;

Simply create `KEY` and assign it value.

```yaml
Options:
  Player:
    AuthorLimit:
      Extension:
        PRINCE: 3
        KING: 9
```

{% hint style="info" %}
Default + Extension = Total Limit
{% endhint %}

#### Example

Extension with key `VIP_GOLD` extends limit by `5`. In configuration file, it will look like this:

<pre class="language-yaml"><code class="lang-yaml">Options:
<strong>  Player:
</strong>    AuthorLimit:
      Extension:
        VIP_GOLD: 5
</code></pre>

Player with permission `MelodyPlayer.Player.Author.Limit.VIP_GOLD` can create **14** MelodyPlayers. (9 as Default + 5 by extension)

{% hint style="warning" %}
At applying more permissions on the player, only permission with highest value will be used!
{% endhint %}


# Melody Reposiotry

List of all available melodies

## Where to put downloaded `.nbs` files?

All song files have to be located in `Melody` folder of MelodyPlayer plugin.

## List

Some suggestion where to find music:

* <https://github.com/TheInfamousAlk/nbs>
* <https://github.com/nickg2/NBSsongs>
* <https://drive.google.com/drive/folders/1_ZTht_n1SkqgjkQLXYpBZ81pt3p_IB0t?usp=sharing>
* Carols - <https://drive.google.com/drive/folders/1hW2lUFu2Dw35V-yR7VLkOkymjCnkhXGk?usp=sharing>


# Player Repository

The Core file of the plugin!

## How to create melody player

There are two options how to create melody player. By in-game **Reward UI** or **Manually** in the confiuration file. Both have some restrictions, so if you want use some advanced methods you will need to use combination of them.

### **Using in-game UI**

{% hint style="info" %}
To open **UI** type `/MelodyPlayer Settings`
{% endhint %}

### **Manually in the file**

Configuration file `PlayerRepository.yml` is located at main folder of MelodyPlayer plugin.

#### **Template for the one melody player**

```yaml
MELODY_PLAYER_1:
  Management:
    Author:
      UUID: e2c593d6-f250-4e63-a26e-417650d0e77a
    Contributor:
      c96c68f3-7075-4503-b824-2752f86af0e9:
        AuthorizedActionList:
        - CONTROL_PANEL__OPEN
        - SETTINGS__OPEN
  Name:
   EN: Music Player
  Description:
    EN: Description
  Icon:
    CustomModelData: 0
    Enchantment: false
    Material: GREEN_RECORD
    MaterialData: 0
    Color: 255:255:255
    ItemFlagList:
    - HIDE_ENCHANTS
    - HIDE_ATTRIBUTES
    - HIDE_POTION_EFFECTS
  Active: false
  MelodyList:
  - Animals
  - The Legend of Zelda Theme
  - What is Love
  Volume: 100
  Range: 10
  Level: LOCATION
```

### Explanation of variables

#### Name and Description support multi-localization

```yaml
Name:
  EN: "Melody Player #1"
  SK: "Prehrávač #1"
```

#### Volume

Set the volume level for how loudly the songs are played."

#### Range

Determine the distance from the SpawnPoint within which music can be heard.

#### Melody

List of `melodies` assigned to this melody player.

{% hint style="warning" %}
Recommended to setup via in-game UI.
{% endhint %}

#### Level

Specify the locations where music will be played.

Allowed values:

* `LOCATION` - Around specific location in defined range.
* `WORLD` - Around whole world where the location is placed. - Only one per world can be active!
* `SERVER` - In all worlds on the server. - Only one melody player per server can be active!

#### Activity

Once the melody player has defined all required variables, it's ready to play mucis.

### Finally&#x20;

After successful setting up of the melody players, you need to reload the plugin/player to load new melody palyers.

{% hint style="info" %}
To reload the melody player type `/MelodyPlayer Reload Player <MelodyPlayer>`&#x20;
{% endhint %}

### Management

#### Author

Owner of the Melody Player.

Permissions to manipulate with the whole Melody Player.

#### Contributors

Players that are able to manipulate with MelodyPlayer based on authorized actions.

AuthorizedActions:

* `LOCATION__UPDATE` - Ability to place spawn point of MelodyPlayer
* `LOCATION__HOLOGRAM__UPDATE`  - Ability to place Hologram
* `SETTINGS__OPEN` - Ability to open Settings
  * ❗️Now player is able to change almost everything about MelodyPlayer!
* `CONTROL_PANEL__OPEN` - Ability to control MelodyPlayer - (Pause/Play/Previous/Next/Volume)
* `RELOAD` - Ability to reload MelodyPlayer&#x20;


# Command management

Ability to manage command name, aliases and localization.

If you are not familiar with current command names, you can easily change them in order to your requirements.

This means you can translate all commands into your required language. It is awesome, isn't it?

## Folder

Each command has separated file. Files are located in folder `Command`.

## Example

```yaml
#CommandConfigurationFile: Command/MelodyPlayer.yml
Base:
  Name: "MelodyPlayer"
  Alias: #List of aliases, each alias on new line.
    - "mp"
  Description: "Base command to operate with MelodyPlayer."
Component:
  Reload:
    Base:
      Name: "Reload"
      Alias: #List of aliases, each alias on new line. Instead of `Reload`, you can use `Rl`
        - "Rl"
    Sub:
      All:
        Name: "All"
```


# GUI

Everything is easier with interactive inventory.

Manual, how to configure items at GUI.

## Locale/GUI.yml

Configuration file, where all data and translations about items are located.

```yaml
Count: #Item's key. Maintained by system, can't be changed.
   HeadName: 
    EN: "&2&lActivity"
   Lore:
    EN:
     - "&6\u25CF &3Active &6\u00BB &7{option__figure__particle__activity}"
     - ""
     - "&6\u25CF &7Click"
     - " &2\u2022 &7Toggle flag"
   Material: "CHEST" #Name of the material
   MaterialData: 0 #Metadata of the item. Especially color. Only for 1.8.8 - 1.12.X
   Slot: 3 #Slot number where item will be played in inventory
   SkullData: "textures" #Texture value of player's head. 
   ItemFlagList: #Flags applied to item.
   - HIDE_ENCHANTS
   CustomModelData: 0 #Is an integer that may be associated client side with a custom item model. Supported at 1.14.X and aboove.
```

### ItemFlags

* HIDE\_ENCHANTS
* HIDE\_ATTRIBUTES
* HIDE\_UNBREAKABLE
* HIDE\_DESTROYS
* HIDE\_PLACED\_ON
* HIDE\_POTION\_EFFECTS
* HIDE\_COLOR - 1.16.X and above

### Helpful stuff

Materials: <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>

Textures of player's head: <https://minecraft-heads.com>

Grid can help you to compute right slot index.

<figure><img src="/files/PefhBeDrIS77iuDUBmV3" alt=""><figcaption></figcaption></figure>


# FAQ

Frequently asked questions

> **Cannot load plugin. Plugin is not enabled on the server.**

* Please, make sure that you have already installed prerequisites [TheCore](https://www.spigotmc.org/resources/thecore.84131/)


# Summary

Hope, that this documentation helped you to configure the whole MelodyPlayer plugin.

At any questions, please visit our [Discord](https://discord.gg/vPHWEapDGR) server and create ticket. Support answers in a few hours, sometimes in a few minutes 😉

Enjoy the plugin!


# Parkour Dimension

Let players show their jumping skills.

An extensive arcade game, where the player has to pass the map in following rules based on the type of module. During the journey, various obstacles are waiting for adventurers.

Rules based on the type of module:

* `BASIC` - Pass the map in the shortest time.


# Installation

Plugin downloaded, what should I do next?

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run Parkour Dimension plugin on your server, there are a few requirements that you have to check.

* Ensure you are using Minecraft version <mark style="color:red;">**1.20.X**</mark> or <mark style="color:red;">**later**</mark>. (Versions below 1.20 are not supported!)
* Your server has installed <mark style="color:red;">**Java8**</mark> or later.
* Make sure that you have already installed plugin [**TheCore**](https://www.spigotmc.org/resources/thecore.84131/)
* (Optional) To record and re-play leader's races, install an [**AdvancedReplays**](https://www.spigotmc.org/resources/advancedreplay-1-8-1-19.52849/) and also [**ProtocolLib**](https://www.spigotmc.org/resources/protocollib.1997/).

## Installation

1. Put `ParkourDimension.jar` into plugins folder at your server.
2. Restart your server.
   1. If you are using PlugMan, load it through it while server is running.
3. Done, jump into configuration and setting up.


# Commands & Permissions

Commands to operate with Parkour.

## Player commands

| Description                | Command                                                        | Permission                           |
| -------------------------- | -------------------------------------------------------------- | ------------------------------------ |
| Player's help              | /Parkour Help \[Player]                                        | Parkour.Help.Player                  |
| Player's info about plugin | /Parkour Info \[Player]                                        | Parkour.Info.Player                  |
| Player's profile           | /Parkour Profile                                               | Parkour.Profile                      |
| List of maps               | /Parkour Map List                                              | Parkour.Map.List.Command             |
| Start the race             | /Parkour Start \<MapName>                                      | Parkour.Map.Join.CommandInteraction  |
| Leave the race             | /Parkour Leave                                                 | Parkour.Map.Leave.CommandInteraction |
| Rate the map               | /Parkour Map Rate \<MapName> \<Rating>                         | Parkour.Map.Rate                     |
| Challenge player           | /Parkour Duel \<Target> \<MapName> \<BetAmount> \[BetCurrency] | Parkour.Duel.Create                  |
| Accept/Decilne Challenge   | /Parkour Duel Accept/Decline                                   | Parkour.Duel.Statement               |
| Spectate player            | /Parkour Spectate \[Target]                                    | Parkour.Spectate                     |
| Leave spectating mode      | /Parkour Spectate Leave                                        | Parkour.Spectate                     |
| Watch replays              | /Parkour Replay \<MapName>                                     | Parkour.Replay                       |
| Map statistics             | /Parkour Statistics Map \<MapName>                             | Parkour.Statistic.Map                |
| Summary statistics         | /Parkour Statistics Summary \<ComponentType>                   | Parkour.Statistic.Summary            |

## Admin commands

| Description                           | Command                                                       | Permission                                    |
| ------------------------------------- | ------------------------------------------------------------- | --------------------------------------------- |
| Admin's help                          | /Parkour Help Admin                                           | Parkour.Help.Admin                            |
| Advanced info about plugin            | /Parkour Info Admin                                           | Parkour.Info.Admin                            |
| Set Spawn Point                       | /Parkour GlobalLocation SetSpawnPoint                         | Parkour.GlobalLocation.SpawnPoint.Creation    |
| Set Leave Point                       | /Parkour GlobalLocation SetLeavePoint                         | Parkour.GlobalLocation.LeavePoint.Creation    |
| Create Map                            | /Parkour MapManagement Create \<MapName> \<Module>            | Parkour.MapManagement.Create                  |
| Remove Map                            | /Parkour MapManagement Remove \<MapName>                      | Parkour.MapManagement.Remove                  |
| Set Start of the map                  | /Parkour MapManagement SetStartPoint \<MapName>               | Parkour.MapManagement.Point.Start             |
| Add Finish to the map                 | /Parkour MapManagement AddFinishPoint \<MapName>              | Parkour.MapManagement.Point.Finish.Add        |
| Update Finish to the map              | /Parkour MapManagement UpdateFinishPoint \<MapName> \<Order>  | Parkour.MapManagement.Point.Finish.Set        |
| Remove Finish from the map            | /Parkour MapManagement RemoveFinishPoint \<MapName> \<Order>  | Parkour.MapManagement.Point.Finish.Remove     |
| Add CheckPoint to the map             | /Parkour MapManagement AddCheckPoint \<MapName>               | Parkour.MapManagement.Point.CheckPoint.Add    |
| Update CheckPoint of the map          | /Parkour MapManagement UpdateCheckPoint \<MapName> \<Order>   | Parkour.MapManagement.Point.CheckPoint.Set    |
| Remove CheckPoint from the map        | /Parkour MapManagement RemoveCheckPoint \<MapName> \<Order>   | Parkour.MapManagement.Point.CheckPoint.Remove |
| Set Leave action location of the map  | /Parkour MapManagement SetLeaveActionPoint \<MapName>         | Parkour.MapManagement.Point.Action.Leave      |
| Set Finish action location of the map | /Parkour MapManagement SetFinishActionPoint \<MapName>        | Parkour.MapManagement.Point.Action.Finish     |
| Place figure of the map               | /Parkour MapManagement Figure Place \<MapName>                | Parkour.MapManagement.Figure                  |
| Remove figure of the map              | /Parkour MapManagement Figure Remove \<MapName>               | Parkour.MapManagement.Figure                  |
| Change figure's mode                  | /Parkour MapManagement Figure Mode \<MapName> \<Mode>         | Parkour.MapManagement.Figure                  |
| SetUp Map                             | /Parkour MapManagement SetUp \<MapName>                       | Parkour.MapManagement.SetUp                   |
| Settings of the map                   | /Parkour MapManagement Settings \<MapName>                    | Parkour.MapManagement.Settings                |
| Reload the map                        | /Parkour MapManagement Reload \<MapName>                      | Parkour.MapManagement.Reload                  |
| Enable maintenance                    | /Parkour Maintenance Enable \<MapName>                        | Parkour.MapManagement.Maintenance.Enable      |
| Disable maintenance                   | /Parkour Maintenance Disable \<MapName>                       | Parkour.MapManagement.Maintenance.Disable     |
| Add SkillPoints to player             | /Parkour SkillPoint Add \<Player> \<Amount>                   | Parkour.SkillPoint.Add                        |
| Remove map statistics                 | /Parkour Statistic Map \<MapName> Remove                      | Parkour.Statistic.Map.Remove                  |
| Get statistics of player              | /Parkour Statistic Player \<Player>                           | Parkour.Statistic.Target                      |
| Remove all statistics of player       | /Parkour Statistic Player \<Player> Remove                    | Parkour.Statistic.Target.Remove.All           |
| Remove map statistics of player       | /Parkour Statistic Player \<Player> \<MapName> Remove         | Parkour.Statistic.Target.Remove.Map           |
| Remove profile statistics of player   | /Parkour Statistic Player \<Player> Profile Remove            | Parkour.Statistic.Target.Remove.Profile       |
| Remove store transactions of player   | /Parkour Statistic Player \<Player> Store Remove              | Parkour.Statistic.Target.Remove.Store         |
| Place personal board                  | /Parkour Board Personal Place                                 | Parkour.Board.Personal.Place                  |
| Remove personal board                 | /Parkour Board Personal Remove                                | Parkour.Board.Personal.Remove                 |
| Change type of personal board         | /Parkour Board Personal Type \<Type>                          | Parkour.Board.Personal.Type                   |
| Place map banner board                | /Parkour Board Map \<MapName> Place Banner                    | Parkour.Board.Map.Banner.Place                |
| Remove map banner board               | /Parkour Board Map \<MapName> Remove Banner                   | Parkour.Board.Map.Banner.Remove               |
| Place map podium board                | /Parkour Board Map \<MapName> Place Podium \<Order>           | Parkour.Board.Map.Podium.Place                |
| Remove map podium board               | /Parkour Board Map \<MapName> Remove Podium \<Order>          | Parkour.Board.Map.Podium.Remove               |
| Remove map sign board                 | /Parkour Board Map \<MapName> Remove Sign \<Order>            | Parkour.Board.Map.Sign.Remove                 |
| Place leader banner board             | /Parkour Board Leader Place Banner \<ComponentType>           | Parkour.Board.Leader.Banner.Place             |
| Remove leader banner board            | /Parkour Board Leader Remove Banner \<ComponentType>          | Parkour.Board.Leader.Banner.Remove            |
| Place leader podium board             | /Parkour Board Leader Place Podium \<ComponentType> \<Order>  | Parkour.Board.Leader.Podium.Place             |
| Remove leader podium board            | /Parkour Board Leader Remove Podium \<ComponentType> \<Order> | Parkour.Board.Leader.Podium.Remove            |
| Remove leader sign board              | /Parkour Board Leader Remove Sign \<ComponentType> \<Order>   | Parkour.Board.Leader.Sign.Remove              |
| Change type of leader boards          | /Parkour Board Leader Type \<Type>                            | Parkour.Board.Leader.Type                     |
| Create section                        | /Parkour Section Create \<CustomName>                         | Parkour.Section.Create                        |
| Delete section                        | /Parkour Section Delete \<CustomName>                         | Parkour.Section.Delete                        |
| Set section switch time               | /Parkour Section UpdateSwitchTime \<CustomName> \<Amount>     | Parkour.Section.SwitchTime                    |
| Add component to section              | /Parkour Section Component Add \<CustomName> \<Type>          | Parkour.Section.Component.Add                 |
| Remove component from section         | /Parkour Section Component Remove \<CustomName> \<Type>       | Parkour.Section.Component.Remove              |
| Settings                              | /Parkour Settings                                             | Parkour.GUI.Settings.Open                     |
| Reload whole plugin                   | /Parkour Reload \[All]                                        | Parkour.Reload.All                            |
| Reload localization file              | /Parkour Reload Locale                                        | Parkour.Reload.Locale                         |
| Reload options file                   | /Parkour Reload Options                                       | Parkour.Reload.Options                        |
| Reload Map                            | /Parkour Reload Map \<MapName>                                | Parkour.Reload.Map                            |
| Migrate Rewards from Legacy Parkour   | /Parkour Migration Reward                                     | Parkour.Migration.Reward                      |
| Migrate Maps from Legacy Parkour      | /Parkour Migration Map                                        | Parkour.Migration.Map                         |

## Additional permissions

Collection of permissions not assigned to commands.

### Permissions

Highlighted permissions are considered as recommended

* Bold – Recommended to all players
* Italic – Recommended to only a specific group of players

| Description                         | Permission                           |
| ----------------------------------- | ------------------------------------ |
| Base player's actions               | **Parkour.Player**                   |
| Player's map actions                | Parkour.Map.Player                   |
| Complete package of all permissions | *Parkour.Admin*                      |
| All reload commands                 | Parkour.Reload.\*                    |
| Duel actions                        | Parkour.Duel.\*                      |
| Board actions                       | Parkour.Board.\*                     |
| Board Section actions               | Parkour.Section.\*                   |
| Statistics removal actions          | Parkour.Statistic.Remove.\*          |
| Statistics removal actions          | Parkour.Statistic.Remove.\*          |
| Map's author actions                | Parkour.MapManagement.Author         |
| Maintenance actions                 | Parkour.MapManagement.Maintenance.\* |
| Place parkour sign                  | Parkour.Sign.Create                  |
| Destroy parkour sign                | Parkour.Sign.Destroy                 |
| ByPass to join any map              | Parkour.Map.Join.Bypass              |
| Single map join                     | Parkour.Map.Join.\<MapName>          |
| Join by figure interaction          | Parkour.Map.Join.FigureInteraction   |
| Join by sign interaction            | Parkour.Map.Join.SignInteraction     |
| Join by GUI interaction             | Parkour.Map.Join.GuiInteraction      |
| Join by QuickStep                   | Parkour.Map.Join.QuickStep           |

## Explanatory notes

* **\[]** - **Square Brackets** – Optional argument. Command has the same effect if that argument is not used.
* **<>** - **Less/More than signs** – Mandatory argument. It's a variable.
  * Example: **\<PlayerName>** will be replaced with **SobkySK**


# Configuration

Detailed explanation of variables at configuration files.


# Options

Looking into Options.yml

## Modules

Parkour offers a wide range of modules that can be used to enhance the gameplay. It's up to the administrator to decide which modules should be enabled.

#### BASIC

* Common mode of the Parkour.
* Pass the map in the shortest time.
* During the journey, various obstacles are waiting for adventurers.

```yaml
Options:
  Module:
    BASIC:
      Active: true
```

## BungeeCord

This mode is primarily determined for bigger server network, while Parkour is a separated server. In this section, you can specify the channel how to communicate with BungeeCord. Also, the name of lobbies, where the player is moved at leaving the server, is listed here.

```yaml
Options:
  BungeeCord:
    Active: false
    Channel: "BungeeCord" #Name of the channel BungeeCord communicates.
    LobbyList: #Name of lobbies where can be player moved at leaving a parkour lobby.
      - "Hub01"
      - "Hub02"
```

## Command

All about in-game commands that players can use.

```yaml
Options:
  Command:
    WhiteList: #Commands allowed to be executed while racing the map. Other commands are blocked.
      - "parkour"
      - "pa"
```

## Economy

Management of Economies used in Parkour.

Support of multiple currencies.

```yaml
Options:
  Economy:
    List:
      Vault:
        Currency:
          Type: "VAULT_WRAPPER"
          Sign: "$"
        Format:
          Decimal: true #Display decimal numbers
          PriceLabel: "{currency_sign}{product_price}" #Final formatting of the price used in the store.
```

#### Available currency types

* `VAULT_WRAPPER` - Use Vault API to get currency information.
* `PLAYER_POINTS`
* `EXPERIENCE`
* `TOKEN_MANAGER`
* `REV_ENCHANTS_C1`
* `REV_ENCHANTS_C2`

#### How to add a new currency type

```yaml
Options:
  Economy:
    List:
      Vault:
        Currency:
          Type: "VAULT_WRAPPER"
          Sign: "$"
        Format:
          Decimal: true #Display decimal numbers
          PriceLabel: "{currency_sign}{product_price}" #Final formatting of the price used in the store.
      Experience:
        Currency:
          Type: "EXPERIENCE"
          Sign: "XP"
        Format:
          Decimal: false #Display decimal numbers
          PriceLabel: "{product_price}{currency_sign}" #Final formatting of the price used in the store.
```

## Store

Through the store, players can unlock maps and other stuff from Parkour Dimension.

{% hint style="warning" %}
Only currencies supported from [the Economy](https://github.com/INNOUNIQ-Plugin-Development/WIKI/blob/main/plugins/parkour-dimension/configuration/economy.md) section are allowed to be used in the store.
{% endhint %}

```yaml
Options:
  Store:
    SupportedCurrencyList: #Currencies allowed to be used in the store.
      - "VAULT_WRAPPER"
    Confirmation: #Requirement of extra confirmation of the purchase.
      Active: true
```

## Duel

To enhance the experience, players can compete against other players. Challenger and challenging player has to bet some amount of currency. Winner takes the whole bet.

```yaml
Options:
  Duel:
    Active: true #Flag if duels are allowed on the server.
    PendingDuration: 30 #Duration remaining the player to make a decision about joining the duel.
    Bet: #Currencies and their amounts supported by the duel system.
      DefaultCurrency: "VAULT_WRAPPER" #Currency used by default if no one is specified while creating a duel.
      CurrencyList: #Currencies supported by the duel system.
        VAULT_WRAPPER:
          Default: 10 #Amount of currency used by default.
          Minimum: 5 #Minimal amount of currency allowed to bet.
```

## Rating

To get feedback from players, Parkour offers a rating system that can help other players decide whether to join the race or not.

When a player completes the map, he is asked for a rating of it.

```yaml
Options:
  Rating:
    Active: true
    Range: 5 #Maximal rating value.
    CooldownDuration: 5 #How long(minutes) after completing the race is able to rate the map.
    Sign: #Symbols representing rating value.
      EMPTY: "\u25CB"
      HALF: "\u25D0"
      FULL: "\u25CF"
```

## Perks

Useful addons are making the player's experience even more enjoyable during the race.

```yaml
Options:
  Perk:
    CompassNavigation: #Perk shows the direction to the finish.
      Active: true
    FakeContactDamage: #This perk allows a player to receive damage without taking his health.
      Active: false
    InteractiveItemList: [ ] #While racing the map, players can interact with selected items.
```

## Replay

Replays of the leaders are available for watching. Also, the personal best race is watchable.

If enabled, each race is recorded.

{% hint style="warning" %}
There is required to have [AdvancedReplays](https://www.spigotmc.org/resources/advancedreplay-1-8-1-21.52849/) and [ProtocolLib](https://www.spigotmc.org/resources/protocollib.1997/) plugins installed.
{% endhint %}

```yaml
Options:
  Replay:
    Active: false
    NamePattern: "M_{map}-P_{player}-ID_{id}" #File Name Pattern
```

## Board

Personal and leading statistics are displayed on the leaderboards. Various modes of the leaderboard are available.

{% hint style="info" %}
Colors are in RGB format, separated by colon(`:`).
{% endhint %}

```yaml
Options:
  Board:
    Personal:
      Type: "NONE"
      Dress:
        Color: "127:255:212"
    Leader:
      Type: "NONE"
      Dress:
        FIRST:
          Color: "255:215:0"
        SECOND:
          Color: "211:211:211"
        THIRD:
          Color: "177:86:15"
        OTHER:
          Color: "183:146:104"
    Section:
      DefaultSwitchTime: 10
    DefaultData:
      Texture: "ewogICJ0aW1lc3RhbXAiIDogMTYwMjUzMzgzNjA0NywKICAicHJvZmlsZUlkIiA6ICI4NjY3YmE3MWI4NWE0MDA0YWY1NDQ1N2E5NzM0ZWVkNyIsCiAgInByb2ZpbGVOYW1lIiA6ICJTdGV2ZSIsCiAgInNpZ25hdHVyZVJlcXVpcmVkIiA6IHRydWUsCiAgInRleHR1cmVzIiA6IHsKICAgICJTS0lOIiA6IHsKICAgICAgInVybCIgOiAiaHR0cDovL25vdmFzay5pbi80Njc1MDk3LnBuZyIKICAgIH0sCiAgICAiQ0FQRSIgOiB7CiAgICAgICJ1cmwiIDogImh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvOTUzY2FjOGI3NzlmZTQxMzgzZTY3NWVlMmI4NjA3MWE3MTY1OGYyMTgwZjU2ZmJjZThhYTMxNWVhNzBlMmVkNiIKICAgIH0KICB9Cn0="
      TextureSignature: "Ri+gD6opLkTsZQuGpSzm3mT8K7s7n1fylC+3Opt/4CW+VTaBhRV8swJVVkqzvAW5N+FxRVLqjM2LYyKNoNfOHTg5UOTmO+Iel5B6mEZWTxRedUETj/M399GPwlv/Kn75KzN/SAMIQJ/2JLUF9Rr4iwQUaFkeT2aCK+4GHGsTKwQhE0GNRCZeKbiQQDBHg94CM+yFpG30IRcgZipBIYiYsLlFyDJXOU28tb+v99Io51QKPKa4uaSTx/M5FeVEBBBAFOG5VPnSy6Y7PLZRPUk7FkXFKsBjrrZnWTLNzevPjwvTT0W7BEdglXaNAYqx9EH1PpnEbu/HI4wz71V7BDwMKs6RAOAfCJm57gAz31yobCr6MhAcdrIvKqC7GQ9vL6qZms1+cZtLvSBtmXtKt69zSeC4lT2FyTiPFN1o69cWNa0atOz1QDRtU+MsOx9sQevtdJM9344+AcKPoxKZC0tXTJ4exP+Hud+eml7PyNPh5hQJ1KeKlALY9hTeeqHLlPlaUOtOOVOV7d54i4rVgAlOj7wloZ2Gt7k5WvPSExzFPN5P7P0lmTjhrwJvhBfV54w4jKe+l24GlsJrDYwqA2JooYGr+NA8D9UsCWk+LFWJ0lGKcYqdF1nBMqfnvwXE9wOqn0udJN3U7tcgrEE1/KM4fFByqIBas9778TzgiIyTgOU="
```

#### Supported Board Types

* `BANNER` - Hologram as a leaderboard.
* `PODIUM_ARMOR_STAND` - ArmorStand Figures are placed on the podium.
* `PODIUM_PLAYER` - NPC Figures are placed on the podium.
* `SIGN` - Signs used as a leaderboard.

#### Creating Boards

**Personal Board**

1. Find suitable place for the board and execute command `/Parkour Board Personal Place`
2. (Optional) To change a type of the board, execute command `/Parkour Board Personal Type <Type>`

**Map Board**

As default top 3 players of each map can be displayed at LeaderBoards.

(Optional) To change a type of the board, execute command `/Parkour Board Leader Type <Type>`

**Banner**

1. Find suitable place for the board and execute command `/Parkour Board Map <MapName> Place Banner`

**Podium**

1. Find suitable place for the best(first) player, fix your position and execute command `/Parkour Board Map <MapName> Place Podium 1`
2. Repeat for the next two podiums, just find new place and change the last argumennt from `1` to `2` and `3`.

**Sign**

1. Find a suitable place for the best(first) player, place sign and type
   * \*\*Parkour\*\*
   * MapName
   * Order(Position)
2. Repeat for the next two signs, just find new place and change the position from `1` to `2` and `3`.
3. (Optional) Place the head (skull item) above the sign to see textures of the player.

**Summary Board**

There are collected more types of statistics. To display them at podiums/banner can take too much place at the server. Instead of that, you can create just one place and let a system change boards with statistics in defined intervals.

(Optional) To change a type of the board, execute command `/Parkour Board Leader Type <Type>`

**Board Sections**

At first, we need to create a section, which ensures changing stat components in defined intervals.

1. Create a section by executing command `/Parkour Section Create <CustomName>`
2. Add a stat component to the section using command `/Parkour Section Component Add <CustomName> <Type>`
3. (Optional) Change default switch time by executing command `/Parkour Section UpdateSwitchTime <CustomName> <Time>`

**Available Component types:**

* `THE_HIGHEST_RANK`

**Banner**

1. Find suitable place for the board and execute command `/Parkour Board Leader Place Banner <ComponentType>`

**Podium**

1. Find suitable place for the best(first) player, fix your position and execute command `/Parkour Board Leader Place Podium <ComponentType> 1`
2. Repeat for the next two podiums, just find new place and change the last argumennt from `1` to `2` and `3`.

**Sign**

1. Find a suitable place for the best(first) player, place sign and type
   * \*\*Parkour\*\*
   * ComponentType
   * Order(Position)
2. Repeat for the next two signs, just find new place and change the position from `1` to `2` and `3`.
3. (Optional) Place the head (skull item) above the sign to see textures of the player.

## Statistics

Properties about statistics.

```yaml
Options:
  Statistic:
    LeaderCount: 3 #How many top players are shown in the leaderboard.
    PreferredModule: "BASIC" #At some places, only statistics from preferred modules are shown.
```

## Visual

All about the visual part of Parkour system.

#### BroadCast Messages

Messages sent to all players can be disabled or restricted in specific worlds.

```yaml
Options:
  Visual:
    BroadCastMessage:
      RACE__COMPLETION:
        Active: true
        WorldRestriction: [ ] #List of world names, where the message will NOT be sent.
```

#### Map Timer

Timer is displayed at the action bar while racing the map or at leaderboard.

{% hint style="info" %}
To display hours, change FormatPattern to: `HH:mm:ss.SSS`.
{% endhint %}

```yaml
Options:
  Visual:
    Map:
      Timer:
        Active: true
        FormatPattern: "mm:ss.SSS"
```

## HotBar

Management of HotBars used in Parkour.

**Exploring HotBar** used when the player is exploring. By exploring, it's meant that the player is in a Parkour lobby.

```yaml
Options:
  HotBar:
    EXPLORING:
      Active: false
```

## Split

While the player is racing the map, we collect his current time. When he reaches CheckPoint, we show him the current situation compared to the best time of the map using BossBar.

```yaml
Options:
  Split:
    Active: true
    LeaderThreshold: 2 #How many seconds can be player slower than the map best time to show a still reachable state.
    BossBar: #Visual indicator of the current split status.
      RACE_LEADER:
        Color: "GREEN"
        Style: "SOLID"
      BEHIND_RACE_LEADER:
        Color: "YELLOW"
        Style: "SOLID"
      PERSONAL_BEST:
        Color: "BLUE"
        Style: "SOLID"
      OUT_OF_CONTENTION:
        Color: "RED"
        Style: "SOLID"
```

#### Available BossBar colors

`PINK`, `BLUE`, `RED`, `GREEN`, `YELLOW`, `PURPLE`, `WHITE`

#### Available BossBar styles

`SOLID`, `SEGMENTED_6`, `SEGMENTED_10`, `SEGMENTED_12`, `SEGMENTED_20`

## PredefinedMapData

Base map data used at initialization of the new map. These predefined data are copied into the new map's configuration.

More about Map properties at [Map Configuration](/plugins/parkour-dimension/configuration/map/map).

```yaml
Options:
  PredefinedMapData:
    Management:
      AuthorLimit: 1 #Count of maps that can be created by the one player.
```


# Map

Detailed explanation of variables at map files.


# Options

Looking into map files.

## Base

Base information about the map.

{% hint style="warning" %}
Do not change the identifier! It can cause issues.
{% endhint %}

```yaml
Base:
  Identifier: 8b2d5e6a-7a98-4cf9-af33-927db2de003f
  Name: Welcome #Name of the map, supports UTF-8 characters.
  State: ACCESSIBLE
  CreatedDate: '2025-10-05T20:26:54.651899'
```

#### Available states:

* `MAINTENANCE` - Map is in maintenance mode. No one can join.
* `ACCESSIBLE` - Map is accessible.
* `LOCKED_BY_ADMINISTRATOR` - Map is locked by an administrator.

## Management

Transferring ownership to another player.

Invite contributors to help the author with the management of the map. Contributors have restricted access based on authorized actions by the author.

```yaml
Management:
  Author:
    UUID: e2c593d6-f250-4e63-a26e-417650d0e77a #UUID of the owner of the map.
  Contributor:
    39b1f5c2-3d9f-4d31-a219-2cf28f878ee0: #UUID of the contributor.
      AuthorizedActionList:
        - SET_UP
```

#### Available Actions:

* `MAINTENANCE__ENABLE` - Ability to enable maintenance mode
* `MAINTENANCE__DISABLE` - Ability to disable maintenance mode
* `SET_UP` - Ability to manage with a map
* `REMOVE` - Ability to remove map
* `POINT__START` - Ability to set start point
* `POINT__FINISH` - Ability to set finish point
* `POINT__CHECK_POINT` - Ability to set checkpoint
* `POINT__ACTION__LEAVE` - Ability to set action leave point
* `POINT__ACTION__FINISH` - Ability to set action finish point
* `FIGURE` - Ability to manipulate with a figure
* `RELOAD` - Ability to reload map

## Options

#### Base

Base properties, no need to explain.

```yaml
Option:
  Capacity: 16
  Speed: 0.2
  Difficulty: NONE
  Category:
    - NONE
  Potion:
    List: [ ]
```

#### Quick Start

Allows starting the race by step on the start location.

Hologram at the start will be displayed.

```yaml
Option:
  QuickStart:
    Active: true
```

#### Teleport

Rules, where to move player after completing the race.

**MapLeave** By disabling this option, players are not moved from the finish line after completing the race. Otherwise, they are teleported to a specified location.

**LastLocation** Player is moved to the last location, where he stood before the race.

```yaml
Option:
  Teleport:
    MapLeave: true
    LastLocation: false
```

#### Prologue

To add more adventure, the player does not see the surroundings after joining the map for a specified amount of time.

```yaml
Option:
  Prologue:
    Active: false
    Duration: 3
```

#### SuspiciousBehavior

Some players are trying to beat the record with illegal techniques!

System is able to detect this behaviour and kick them out of map.

```yaml
Option:
  SuspiciousBehavior:
    Air: #Staying in the air for too long can be considered as an illegal technique.
      Active: true
      Duration: 2.0
    PassAllPoints: #Requirement to pass all checkpoints to be able to complete the race.
      Active: false
```

#### Requirements

To be able to start the race, the player has to meet all requirements assigned to this map.

This allows you to create a whole story on your server when players have to complete the races in a specified order.

**Required Rank**

Rank required to access the Parkour Map.

```yaml
Option:
  Requirement:
    Rank: FLEA
```

**Previous Map**

Player has to complete a specified map before accessing this map.

Additionally, you can specify the limit of the previous map.

E.g. Player has to complete a map below 25 seconds.

```yaml
Option:
  Requirement:
    PreviousMap:
      Id: 8b2d5e6a-7a98-4cf9-af33-927db2de4325 #ID of the previous map. There is a recommendation to use in-game GUI to set up these values.
      DecisiveValueLimit: 25000 #Value is in milliseconds.
```

**Lock**

To unlock the map, the player must purchase it in the store.

```yaml
Option:
  Requirement:
    Lock:
      Active: true
      Currency: "VAULT_WRAPPER"
      Price: 10
```

**PlayTime**

Played timed required to enter the map.

* `Total` - Total time spent on the server.
  * Example: Player has to play for at least 5 Days(7200 Minutes) to be able to join the map.
* `Today` - Today's time spent on the server. Probably most used
  * Example: Player has to play for at least 30 Minutes **that day** to be able to join the map.
* `Session` - Time spent on the server since player logged in.
  * Example: Player has to be **online** for at least 30 Minutes to be able to join the map.

```yaml
Option:
  Requirement:
    PlayTime:
      TotalMinute: 0
      TodayMinute: 0
      SessionMinute: 0
```

{% hint style="warning" %}
To disable PlayTime Requirement, keep all values to `0`.
{% endhint %}

## Exclusive Blocks

Exclusive Blocks act as dynamic triggers that execute unique actions a player makes contact.

#### Bottom Border

Stepping on the specified block or reaching below the Y-Coordinate is considered as fall.

```yaml
ExclusiveBlock:
  BottomBorder:
    Coordination: 0.0
    Material:
      - BARRIER
```

#### Jump Simulation

Stepping on the specified block lifts the player up with the specified power.

```yaml
ExclusiveBlock:
  JumpSimulation:
    Power: 1.0
    Material:
      - DIAMOND_BLOCK
```

## Sounds

Sounds improve the player's experience while racing the map. These spatial cues enhance player immersion and clearly signal success or mistakes throughout the course.

{% hint style="info" %}
There is recommended to use in-game GUI to set up these values.
{% endhint %}

## Figure

Via **Figure**, players are able to join the map. This figure also displays the current status of the map.

System offers pre-defined **Armor Stand**, with clothes and head. All values can be changed in the configuration file. System also supports **NPC**, you can aslo equip it with armor or items.

{% hint style="warning" %}
Warning at placing the Figure. Figure copies your locations and also facing direction!
{% endhint %}

{% hint style="info" %}
To place a figure type: `/Parkour MapManagement Figure Place <MapName>`
{% endhint %}

### Mode

List of modes mentioned above:

* `NONE`
* `ARMOR_STAND`
* `PLAYER`
* `HOLOGRAM`

```yaml
Figure:
  Mode: PLAYER
```

### Particle

Particles are spawning around the spawned Figure. You can keep them active or disable them. Also, you can change Effect, Color, Speed and Amount.

```yaml
Figure:
  Particle:
    Active: true
    TickDelay: 13 #How fast particles are spawned. (20 ticks = 1 second)
    Data:
      Effect: SPELL_WITCH
      Amount: 35
      Speed: 1.0 #Optional, Default 1.0
      Color: "255:255:255" #Optional, Default White
      Offest: #Optional, Offset from Figures's location. (Vector)
        X: .5
        Y: .5
        Z: .5
```

## Reward

Rewarding system for completing the race.

{% hint style="warning" %}
There is expected that rewards are created, yet! To create rewards, check this tutorial: [How to create Reward](/plugins/thecore/configuration/centralized-reward-repository)
{% endhint %}

{% hint style="info" %}
To allow players to increase their rank, assign SkillPoint Reward for each type of completion.
{% endhint %}

{% hint style="info" %}
There is recommended to use in-game GUI to set up these values.
{% endhint %}

```yaml
Reward:
  Daily:
    Active: true #By enabling this option, the reward for completing the race for the first time in a day is higher as common rewards.
  ChoiceType: QUICK__ALL #Method of rewarding players for completing the race.
  List:
    First:
      Overall:
        - P_SP_5
      Day:
        - P_SP_1
    Repeat:
      - P_SP_1
```

**Choice Types:**

* `QUICK__ALL` - All assigned rewards are given to player
* `QUICK__CHANCE` - One reward is selected from an assigned list by probability

Example for **probability**. `DiamondTools` has 90% chance, `MoneyPocket` has 10% chance to win.

{% hint style="danger" %}
Summary of probability at assinged rewards has to be **100.0**! Otherwise, system won't work correctly!
{% endhint %}

```yaml
Reward:
  ChoiceType: QUICK__CHANCE
  List:
    First:
      Overall:
      - DiamondTools:90.0
      - MoneyPocket:10.0
```


# Setting up the first Map

First steps after installing Parkour Dimension.

{% hint style="info" %}
Use `Tab` at completing commands.
{% endhint %}

## Global Location

1. Create a **Lobby point**. Find a suitable place, fix your position and type `/Parkour GlobalLocation SetSpawnPoint`
2. (Optional) Create a **Leave point**. Find a suitable place, fix your position and type `/Parkour GlobalLocation SetLeavePoint`
   * If no **Leave Point** is set, **Lobby point** will be used.

## Building the Map

1. Build the whole map. Prepare obstacles and other things.

## Creating map

1. Choose the **Module** you want to use.
2. Type command `/Parkour MapManagement Create <MapName> <Module>`
3. Join the SetUp mode using `/Parkour MapManagement SetUp <MapName>`
   * Also, you can use commands to save locations, but there is much more simple.
4. Set the Start point. Scroll your hotbar to Start item. Find a suitable place, your position and right-click with item (into the air).
5. Repeat the same for finish and checkpoints and action points.
6. Reload the map using `/Parkour Reload Map <MapName>` or `/Parkour MapManagement Reload <MapName>`
7. Enable the map. Each map's modification requires Maintenance mode, so we need to quit it using `/Parkour Maintenance Disable <MapName>`
8. Enjoy!


# Command management

Ability to manage command name, aliases and localization.

If you are not familiar with current command names, you can easily change them in order to your requirements.

This means you can translate all commands into your required language. It is awesome, isn't it?

## Folder

Each command has a separated file. Files are located in folder `Command`.

## Example

```yaml
#CommandConfigurationFile: Command/ParkourDimension.yml
Base:
  Name: "Parkour"
  Alias: []  #List of aliases, each alias on new line.
  Description: "Base command to operate with ParkourDimension."
Component:
  Reload:
    Base:
      Name: "Reload"
      Alias: #List of aliases, each alias on new line. Instead of `Reload`, you can use `Rl`
        - "Rl"
    Sub:
      All:
        Name: "All"
```


# GUI

Everything is easier with interactive inventory.

Manual, how to configure items at GUI.

## Locale/GUI.yml

Configuration file, where all data and translations about items are located.

```yaml
Count: #Item's key. Maintained by system, can't be changed.
   HeadName: 
    EN: "&2&lActivity"
   Lore:
    EN:
     - "&6\u25CF &3Active &6\u00BB &7{option__figure__particle__activity}"
     - ""
     - "&6\u25CF &7Click"
     - " &2\u2022 &7Toggle flag"
   Material: "CHEST" #Name of the material
   MaterialData: 0 #Metadata of the item. Especially color. Only for 1.8.8 - 1.12.X
   Slot: 3 #Slot number where item will be played in inventory
   SkullData: "textures" #Texture value of player's head. 
   ItemFlagList: #Flags applied to item.
   - HIDE_ENCHANTS
   CustomModelData: 0 #Is an integer that may be associated client side with a custom item model. Supported at 1.14.X and aboove.
```

### ItemFlags

* HIDE\_ENCHANTS
* HIDE\_ATTRIBUTES
* HIDE\_UNBREAKABLE
* HIDE\_DESTROYS
* HIDE\_PLACED\_ON
* HIDE\_POTION\_EFFECTS
* HIDE\_COLOR - 1.16.X and above

### Helpful stuff

Materials: <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>

Textures of player's head: <https://minecraft-heads.com>

Grid can help you to compute right slot index.

<figure><img src="/files/PefhBeDrIS77iuDUBmV3" alt=""><figcaption></figcaption></figure>


# Placeholder

Simply way to get data of plugin at various places around the server.

## PlaceholderAPI

If you are familiar with [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) resource, you can obtain data and display it at another plugin.

**Player's Profile:**

* %parkour\_profile\_rank% - Player's rank
* %parkour\_profile\_rank\_skill\_point\_amount% - Current skill point amount
* %parkour\_profile\_rank\_next% - Next rank
* %parkour\_profile\_rank\_next\_skill\_point\_amount% - Required skill point amount to next rank

**Personal Statistics:**

* %parkour\_statistic\_personal\_map\_\<MapName>\_decisive\_value% - Parsed decisive value of the map
* %parkour\_statistic\_personal\_map\_\<MapName>\_decisive\_value\_raw% - Raw decisive value of the map
* %parkour\_statistic\_personal\_map\_\<MapName>\_position% - Position at map
* %parkour\_statistic\_personal\_map\_\<MapName>\_position\_raw% - Position at map(If it does not exist, max int value)

**Map Statistics:**

* %parkour\_statistic\_leader\_map\_\<MapName>\_decisive\_value\_\<Order>% - Parsed decisive value of player at requested position
* %parkour\_statistic\_leader\_map\_\<MapName>\_name\_\<Order>% - Name(Nick) of the player at the requested position

**Map Count:**

* %parkour\_map\_count\_all% - Count of maps
* %parkour\_map\_count\_accessible% - Count of accessible maps
* %parkour\_map\_count\_maintenance% - Count of maps in maintenance
* %parkour\_map\_count\_locked% - Count of locked maps
* %parkour\_map\_count\_c\_\<Category>% - Count of maps in the selected category
* %parkour\_map\_count\_d\_\<Difficulty>% - Count of maps in the selected difficulty

**Miscellaneous:**

* %parkour\_version% - Version of Parkour plugin


# FAQ

Frequently asked questions

> **Cannot load plugin. Plugin is not enabled on the server.**

* Please, make sure that you have already installed prerequisites [TheCore](https://www.spigotmc.org/resources/thecore.84131/)


# Summary

Hope, that this documentation helped you to configure the whole Parkour plugin.

At any questions, please visit our [Discord](https://discord.gg/vPHWEapDGR) server and create ticket. Support answers in a few hours, sometimes in a few minutes 😉

Enjoy the plugin!


# Lottery

Encourage players to bet money to be in with a chance of winning the pot.

{% hint style="info" %}
New documentation for this resource under construction.
{% endhint %}

## Description <a href="#description" id="description"></a>

Encourage players to bet money to be in with a chance of winning the pot.

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run Lottery plugin on your server, there are a few requirements that you should check.

* Ensure you are using Minecraft version **1.8.8** or **later**. (Versions below 1.8.8 are not supported!)
* Your server has installed **Java8** or later.
* Make sure that you have already installed plugins [**TheCore**](https://www.spigotmc.org/resources/thecore.84131/)
* Your server has installed **Economy** plugin, which supports Vault, PlayerPoints or TokenManager.

## Installation <a href="#installation" id="installation"></a>

1. Put `Lottery.jar` into plugins folder at your server.

> Downloaded .zip file contains more .jar file depending on the server version. Choose the one that fits your server.

1. Restart your server.
2. Done

[![discord-banner\_e1\_1200.png](https://wiki.innouniq.com/discord-banner_e1_1200.png)](https://discord.gg/vPHWEapDGR)

## Commands & Permissions <a href="#commands-permissions" id="commands-permissions"></a>

| Command Description           | Command                                                   | Permission                         |
| ----------------------------- | --------------------------------------------------------- | ---------------------------------- |
| Player section                |                                                           |                                    |
| Open LotteryGUI               | /Lottery                                                  | Lottery.GUI.Overview\.Open         |
| Purchase tickets              | /Lottery Purchase \[Count]                                | Lottery.Pot.Purchase               |
| Help                          | /Lottery Help \[Player]                                   | Lottery.Help.Player                |
| Information about Lottery     | /Lottery Info \[Player]                                   | Lottery.Info.Player                |
| Personal Stats                | /Lottery Stats Personal                                   | Lottery.Stats.Personal.Own         |
| Summary Stats                 | /Lottery Stats Summary \<Type>                            | Lottery.Stats.Summary              |
| Change locale                 | /Lottery Profile SetLocale \<Locale>                      | Lottery.Profile.Preference.Locale  |
| Admin section                 |                                                           |                                    |
| Advanced Help                 | /Lottery Help Admin                                       | Lottery.Help.Admin                 |
| Advanced Information          | /Lottery Info Admin                                       | Lottery.Info.Admin                 |
| Enable Maintenance            | /Lottery Maintenance Enable                               | Lottery.Maintenance.Enable         |
| Disable Maintenance           | /Lottery Maintenance Disable                              | Lottery.Maintenance.Disable        |
| Create Figure                 | /Lottery Figure Set                                       | Lottery.Figure.Place               |
| Link/Find nearby Figure       | /Lottery Figure Find                                      | Lottery.Figure.Find                |
| Unlink/Remove Figure          | /Lottery Figure Remove                                    | Lottery.Figure.Remove              |
| Increase bonus                | /Lottery Bonus Increase \<Amount>                         | Lottery.Pot.Bonus.Increase         |
| Force end of running round    | /Lottery ForceDraw                                        | Lottery.Round.Draw\.Forced         |
|                               |                                                           |                                    |
| Reload plugin                 | /Lottery Reload \[All]                                    | Lottery.Reload.All                 |
| Reload locale                 | /Lottery Reload Locale                                    | Lottery.Reload.Locale              |
| Reload options                | /Lottery Reload Options                                   | Lottery.Reload.Options             |
|                               |                                                           |                                    |
| Place Personal Board          | /Lottery Board Personal Place                             | Lottery.Board.Personal.Place       |
| Remove Personal Board         | /Lottery Board Personal Remove                            | Lottery.Board.Personal.Remove      |
| Place Leader Board (Banner)   | /Lottery Board Summary Place Banner \<Type>               | Lottery.Board.Leader.Banner.Place  |
| Remove Leader Board (Banner)  | /Lottery Board Summary Remove Banner \<Type>              | Lottery.Board.Leader.Banner.Remove |
| Place Leader Board (Podium)   | /Lottery Board Summary Place Podium \<Type> \<Order>      | Lottery.Board.Leader.Podium.Place  |
| Remove Leader Board (Podium)  | /Lottery Board Summary Remove Podium \<Type> \<Order>     | Lottery.Board.Leader.Podium.Remove |
| Remove Leader Board (Sign)    | /Lottery Board Summary Remove Sign \<Type> \<Order>       | Lottery.Board.Leader.Sign.Remove   |
|                               |                                                           |                                    |
| Create section                | /Lottery Section Create \<CustomName>                     | Lottery.Section.Create             |
| Delete section                | /Lottery Section Delete \<CustomName>                     | Lottery.Section.Delete             |
| Add component to section      | /Lottery Section Component Add \<CustomName> \<Type>      | Lottery.Section.Component.Add      |
| Remove component from section | /Lottery Section Component Add \<CustomName> \<Type>      | Lottery.Section.Component.Remove   |
| Set section switch time       | /Lottery Section UpdateSwitchTime \<CustomName> \<Amount> | Lottery.Section.SwitchTime         |
|                               |                                                           |                                    |
| Open Settings                 | /Lottery Settings                                         | Lottery.GUI.Settings.Open          |

### Additional Permissions <a href="#additional-permissions" id="additional-permissions"></a>

| Description    | Permission             | Covers                              |
| -------------- | ---------------------- | ----------------------------------- |
| Player         | Lottery.Player         | Base player's actions               |
| Admin          | Lottery.Admin          | Complete package of all permissions |
| Figure         | Lottery.Figure.\*      | Permissions of Figure               |
| Maintenance    | Lottery.Maintenance.\* | Permissions of Maintenance          |
| Board          | Lottery.Board.\*       | Permissions of Board                |
| Board Sections | Lottery.Section.\*     | Permissions of Board Sections       |
| Reload         | Lottery.Reload.\*      | Permissions of Reload               |

## Configuration <a href="#configuration" id="configuration"></a>

Detailed explanation of variables at configuration files.

### Config <a href="#config" id="config"></a>

#### Automatic Updates <a href="#automatic-updates" id="automatic-updates"></a>

Resource supports **automatic** (startup) **updates**. You can enable or disable them. If disabled, you will only receive message about new version.

#### Localization <a href="#localization" id="localization"></a>

Fully customizable localized messages. Just make duplicate of EN.yml file(In the same folder!). Rename it and write the name of the file into **config.yml**.

Example of the Locale file:

```yaml
#LocaleFile: EN.yml
Prefix:
  Base: "&3&lLottery &6\u2771"
  ...
```

Copy

```yaml
#LocaleFile: SK.yml (Slovak)
Prefix:
  Base: "&3&lLotéria &6\u2771"
  ...
```

Copy

#### Multi Localization <a href="#multi-localization" id="multi-localization"></a>

Plugin is able to hold different localisations at the same time. It’s up to player, which localisation wants to display.

> Secondary localizations do not have to contain all translations. In case of secondary translation does not contain requested path, the primary file is used to fetch data.

```yaml
#Config:
Locale:
  Primary: EN
  Secondary:
  - SK
  - CZ
  ...
```

Copy

#### Storage <a href="#storage" id="storage"></a>

Space where to save required data. Supported storages: `MySQL` and `SQLite`

If you prefer MySQL Storage before SQLite, you need to fill variables at **config.yml**.

> There is required that ProfileStorage and this plugin is using the same source of storage!

#### Analytics <a href="#analytics" id="analytics"></a>

Plugin sends anonymous data such as version of this resource, your server version and addition data of configuration. These data will help me in future development.\
All requests are asynchronous, so it has no impact on server's performance.

If you don't want to share these data, you can easily disable it.

```yaml
Analytics:
  Active: false
```

Copy

**Data collected from your server about Voting**

Example:

* Base

```
Versions:
    Plugin: 5.0.0
    Server: 1.19.X
```

Copy

* AdditionalData

```json
{
   "Options":{
      "Economy":{
         "Type":"VAULT_WRAPPER"
      },
      "Board":{
         "Personal":{
            "Type":"DAIS"
         },
         "Leader":{
            "Type":"DAIS"
         }
      },
      "Pot":{
         "ServerParticipation":false,
         "MinPlayers":1
      },
      "Stats":{
         "Limit":3
      },
      "Round":{
         "Duration":180,
         "Mode":"SIMPLE"
      },
      "GUI":{
         "FastPurchase":true
      },
      "Visual":{
         "BroadCast":{
            "Bonus":true,
            "Win":true,
            "Purchase":true
         },
         "BossBar":{
            "Activity":true
         },
         "DecimalFormat":false
      },
      "Figure":{
         "Mode":"FIGURE_AND_HOLOGRAM"
      }
   }
}
```

Copy

### Options <a href="#options" id="options"></a>

Options file is divided to sections.

#### Command <a href="#command" id="command"></a>

Plugin manages main command `Lottery`, which can have aliases.

> Alias is a command, which invokes the same action as the main command.

#### Economy <a href="#economy" id="economy"></a>

Plugin supports **3** Economy providers `Vault`, `PlayerPoints`, `Experiences` and `TokenManager`.

> Experiences does not require any additional plugin! Player's current experiences are used here.

**Types used in configuration file**

* `VAULT_WRAPPER`
* `PLAYER_POINTS`
* `EXPERIENCE`
* `TOKEN_MANAGER`

#### Round <a href="#round" id="round"></a>

In this section you can configure core of the plugin. **Duration** of the round and it's **Mode** with additional features.

**Mode**

Plugin offers **4** types, which specifies when the round is created or ended.

**Types of modes**

* `SIMPLE` - Round is created at first purchase of tickets
* `AUTOMATIC` - Round is created at start of the server and next round is created after the end of the previous round
* `REALTIME_START` - Round is created at specific time. E.g. At 12:00
* `REALTIME_DRAW` - The draw of the round is at specific time(Duration value is ignored!). E.g. At 07:00

At using last two options, you need to specify time, when to create/draw the round.

Example shows that round is created/drawn at 12:00 and 18:00 each day.

```yaml
RealTimeMode:
  Timestamps:
    - "12:00"
    - "18:00"
```

Copy

#### Pot <a href="#pot" id="pot"></a>

Every money from purchased tickets is put into pot.

At beggining of the round, some bonus money can be added to the pot....

To make lottery more interesting, you can enable that round won't have winner and amount of the pot will be moved to the next round.

```yaml
ServerParticipation:
  Enable: true
```

Copy

#### Purchase <a href="#purchase" id="purchase"></a>

In this section you can change price of the one ticket and amount, how much tickets can player purchase.

#### Visual <a href="#visual" id="visual"></a>

Section represents components displayed at chats and boss bars.

**Decimals**

If you are using economy without decimals you can change variable `UseDecimalFormat` to `false`

**BroadCast**

Each purchase is broadcasted to all players. You can disable it, or you can define variable `SleepTime` which creates countdown so messages of player's activity will be sent only once in specified range.

**BossBar**

Via **BossBar** players are able to see current information about running round.

**Available color values**

`PINK`, `BLUE`, `RED`, `GREEN`, `YELLOW`, `PURPLE`, `WHITE`

**Available style values**

`SOLID`, `SEGMENTED_6`, `SEGMENTED_10`, `SEGMENTED_12`, `SEGMENTED_20`

**Intervals**

These information can be displayed in specified **intervals** and these itervals are mainly associtated with **BossBar**.

Imagine interval in math, but reversed because of countdown which is decresing.\
If we want to display BossBar since **30** seconds to **10** seconds, we use interval `30:11`(`FROM:TO+1`). Plus **1** because of we want to hide BossBar in 10 seconds. (If we keep 10 seconds in the iterval, BossBar will be hidden in 9 seconds.)

#### Figure <a href="#figure" id="figure"></a>

By interacting with figure, players are able to see current state of the round or can purchase tickets.

You can create whole figure with hologram or only hologram and use your own ArmorStant or NPC.

Types of figure's mode:

* `FIGURE_AND_HOLOGRAM`
* `ONLY_HOLOGRAM`

#### Board <a href="#board" id="board"></a>

Boards or LeaderBoards are used to display personal or summary stats. Nicely fit the server lobby scene.

There are three types of boards:

* `BANNER` - One leader-one line.
* `PODIUM_ARMOR_STAND` - Each leader(place) has own location. Colored ArmorStand with player's head.
* `PODIUM_PLAYER` - Each leader(place) has own location. NPC with leader's skin.
* `SIGN` - Each leader(place) has own location. Skull placed above the sign.

## PlaceholderAPI <a href="#placeholderapi" id="placeholderapi"></a>

Plugin offers ability to obtain data via placeholderAPI.

**Round**

* **%lottery\_round\_draw\_in%** - Parsed time to round evaluation. (00:04:59)

**Pot**

* **%lottery\_pot\_bonus%** - Bonus in pot.
* **%lottery\_pot\_ticket\_count\_summary%** - Total count of tickets in pot.
* **%lottery\_pot\_ticket\_count\_personal%** - Count of player's tickets in pot.
* **%lottery\_pot\_cash\_amount%** - Cash amount in pot.

**Personal stats**

* **%lottery\_stats\_personal\_round\_participated%** - Count of participated rounds.
* **%lottery\_stats\_personal\_round\_won%** - Count of won rounds.
* **%lottery\_stats\_personal\_round\_last\_when%** - Date of last win.
* **%lottery\_stats\_personal\_round\_last\_amount%** - Cash amount at last win.
* **%lottery\_stats\_personal\_cash\_total\_won\_amount%** - Total won cash amount.
* **%lottery\_stats\_personal\_cash\_highest\_won\_amount%** - Highest won cash amount.
* **%lottery\_stats\_personal\_transaction\_spent\_amount%** - Spent cash amount.
* **%lottery\_stats\_personal\_transaction\_purchased\_ticket%** - Amount of purchased tickets.

**Summary stats**

* **%lottery\_stats\_summary\_\<ComponentType>\_order\_\<Order>\_value\_\<Value>%** - Summary stats in order to requested ComponentType, Order and Value.

**ComponentTypes and Values**

* **LastRound**
  * when
  * winner
  * cash\_total\_amount
  * cash\_amount
  * cash\_bonus
  * currency\_sign
* **TheBiggestExpenditure**
  * order
  * suffix
  * who
  * cash\_total\_amount
  * tickets
  * declension\_ticket
  * currency\_sign
* **TheHighestWonAmount**
  * order
  * suffix
  * who
  * cash\_total\_amount
  * cash\_amount
  * cash\_bonus
  * when
  * currency\_sign
* **TheLuckiestPerson**
  * order
  * suffix
  * who
  * cash\_total\_amount
  * cash\_amount
  * cash\_bonus
  * rounds
  * declension\_round
  * currency\_sign
* **TheMostActivePerson**
  * order
  * suffix
  * who
  * rounds
  * declension\_round
  * currency\_sign

**Example:**

* **%lottery\_stats\_summary\_TheLuckiestPerson\_order\_1\_value\_who%** - Returns Nick of the LuckiestPerson who is at 1st place at ranking.

**Miscellaneous**

* **%lottery\_version%** - Version of the plugin


# Voting

Keep players to determine various situations.


# Installation

Plugin downloaded, what should I do next?

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you run Melody Player plugin on your server, there are a few requirements that you have to check.

* Ensure you are using Minecraft version <mark style="color:red;">**1.8.8**</mark> or <mark style="color:red;">**later**</mark>. (Versions below 1.8.8 are not supported!)
* Your server has installed <mark style="color:red;">**Java8**</mark> or later.
* Make sure that you have already installed plugin [**TheCore**](https://www.spigotmc.org/resources/thecore.84131/)

## Installation

1. Put `Voting.jar` into plugins folder at your server.
2. Restart your server.&#x20;
   1. If you are using PlugMan, load it through it while server is running.
3. Done, jump into configuration and setting up.


# Commands & Permissions

Commands to operate with Voting.

## Player commands

| Command Description | Command                       | Permission                 |
| ------------------- | ----------------------------- | -------------------------- |
| **Player section**  |                               |                            |
| Open Voting GUI     | /Voting \[Open]               | Voting.GUI.Open            |
| Start a round       | /Voting \<Unit> \[Parameters] | Voting.Round.Start.\<Unit> |
| Place a vote        | /Voting \<Agree/Disagree>     | Voting.Vote.Place          |
| Help                | /Voting Help \[Player]        | Voting.Help.Player         |
| Information         | /Voting Info \[Player]        | Voting.Info.Player         |

## Admin commands

| Command Description      | Command                                     | Permission                                   |
| ------------------------ | ------------------------------------------- | -------------------------------------------- |
| Advanced Help            | /VotingAdmin Help Admin                     | Voting.Help.Admin                            |
| Advanced Information     | /VotingAdmin Info Admin                     | Voting.Info.Admin                            |
| Set world's alias        | /VotingAdmin Alias Set \<World> \<Alias>    | Voting.Administration.Alias                  |
| Remove world's alias     | /VotingAdmin Alias Remove \<World> \<Alias> | Voting.Administration.Alias                  |
| Reload plugin            | /VotingAdmin Reload \[All]                  | Voting.Administration.Reload.All             |
| Reload locale            | /VotingAdmin Reload Locale                  | Voting.Administration.Reload.Locale          |
| Reload options           | /VotingAdmin Reload Options                 | Voting.Administration.Reload.Options         |
| Reload units             | /VotingAdmin Reload Units                   | Voting.Administration.Reload.Units           |
| Migrate GUI Localization | /VotingAdmin Migration Localization         | Voting.Administration.Migration.Localization |

## Additional permissions

Collection of permissions not assigned to commands.

### Permissions

Highlighted permissions are considered as recommended

* Bold - Recommended to all players
* Italic - Recommended to only specific group of players

| Description      | Permission                         |
| ---------------- | ---------------------------------- |
| Player           | **Voting.Player**                  |
| Admin            | *Voting.Administration*            |
| Reload           | Voting.Administration.Reload.\*    |
| Migration        | Voting.Administration.Migration.\* |
| Create sign      | Voting.Sign.Create                 |
| Destroy sign     | Voting.Sign.Destroy                |
| Start any round  | Voting.Round.Start.\*              |
| See result ratio | Voting.Round.ResultRatio           |

## Explanatory notes

* **\[]** - **Square Brackets** - Optional argument. Command has the same effect, if that argument is not used.
* **<>** - **Less/More than signs** - Mandatory argument. It's a variable.
  * Example: **\<PlayerName>** will be replaced with **SobkySK**


# Configuration

Detailed explanation of variables at configuration files.


# Options

Looking into Options.yml

## Command

Plugin manages **2** main commands `Voting` and `VotingAdmin`. Each command can have aliases.

{% hint style="info" %}
Alias is a command, which invokes the same action as the main command.
{% endhint %}

TabCompletion

* Include parameter name(in format \<parameter\_name>) at tab completing for custom VotingUnits.

```yaml
Options:
  Command:
    Voting:
      Aliases:
        - "vot"
    VotingAdmin:
      Aliases:
        - "votadmin"
    TabCompletion:
      IncludeParameterFormat: true
```

## Economy

By enabling economy, you can charge players for placing a vote or starting a voting round.

Plugin supports **more** Economy providers e.g. `Vault`, `PlayerPoints` and `Experiences`.\
If you want to use any one of it, at first, you need to enable it!

{% hint style="warning" %}
There is required that enabled providers are also installed on the server!
{% endhint %}

{% hint style="info" %}
Experiences does not require any additional plugin! Player's current experiences are used here.
{% endhint %}

### **Types used in configuration file**

* `VAULT_WRAPPER`
* `PLAYER_POINTS`
* `EXPERIENCE`
* `TOKEN_MANAGER`

```yaml
Options:
  Economy:
    Active: false
    Type: "NONE"
```

## Round

In this section you can configure core of the plugin. **Duration** of the round, **minimum count of players** required to start the round. And much more.

```yaml
Options:
  Round:
    Duration: 60
    MinPlayers: 2
```

### **Pause**

There are **2** types of pauses, which prevents to start next round immediately after one round has ended.

**Explanation of types**

* **Global** - No one will be able to start a round until pause ends.
* **Personal** - In short, you can configure, that player will be able to start round only once in a 15 minutes.

{% hint style="info" %}
**Personal pause** is not applied when player wants to place a vote!
{% endhint %}

```yaml
Options:
  Round:
    Pause:
      Global:
        Active: true
        Duration: 10
        CategoryList:
          DAY_LIGHT:
            Duration: 300
          CLIMATE:
            Duration: 10
      Personal:
        Active: true
        Duration: 300
```

#### **Independent Pause**

VotingUnit can be assigned to pause category, if so, pause is applied only to group of VotingUnits with the same category, while another voting round can be started.

{% hint style="warning" %}
Assignment of category to VotingUnit is performed in VotingUnits.yml file.
{% endhint %}

**Example**

VotingUnits DAY and NIGHT are assigned to PauseCategory DAY\_LIGHT, where duration of pause is set to 300 seconds.

Other VotingUnits(SUN/STORM/RAIN) are not assigned to any PauseCategory, that means, they inherit default global pause duration, 10 seconds.

While pause from DAY\_LIGHT category is running I am not able to start next DAY/NIGHT voting round. But I can start SUN/STORM/RAIN voting round, because the are assigned to default/other category.

### **Animation**

At changing **time** in a world you can use smoothy animation. Sun or Moon is moving across the sky so it looks like it has speed up the time.

You can specify speed of the animation. Available range is **<50;750>**

{% hint style="info" %}
Speed **100** means that time change from **0** to **23999** takes **12** seconds.
{% endhint %}

```yaml
Options:
  Round:
    TimeChangeAnimation:
      Speed: 100
```

{% hint style="warning" %}
This feature is only available for **Weather** units.
{% endhint %}

### **Confirmation**

You can require additional confirmation that the round will start. Special GUI is opened.

```yaml
Options:
  Round:
    Confirmation:
      Active: false
```

## Visual

Section represents components displayed at chat, boss bars and titles.

### Boss Bar

Players are able to see current information about running round.

```yaml
Options:
  Visual:
    BossBar:
      Active: true
      Color: "PURPLE"
      Style: "SEGMENTED_20"
```

#### Available colors

`PINK`, `BLUE`, `RED`, `GREEN`, `YELLOW`, `PURPLE`, `WHITE`

#### Available styles

`SOLID`, `SEGMENTED_6`, `SEGMENTED_10`, `SEGMENTED_12`, `SEGMENTED_20`

### **ActionBar**

Via **ActionBar** players are able to see current result of running round.\
Result is shown in percentual ratio and you can define colors of its possitive, resp. negative part. Also you can define **char** and **count** of these chars shown in ratio.

```yaml
Options:
  Visual:
    ActionBar:
      Active: true
      Progress:
        Char: "\u25CF"
        Count: 10
        Color:
          Positive: "&a"
          Negative: "&c"
```

### Information intervals

Information can be displayed in specified **intervals** and these itervals are mainly associtated with **BossBar** and **ActionBar**.

Imagine interval in math, but reversed because of countdown which is decresing.

\
If we want to display BossBar since **30** seconds to **10** seconds, we use interval `30:11`(`FROM:TO+1`). Plus **1** because of we want to hide BossBar in 10 seconds. (If we keep 10 seconds in the interval, BossBar will be hidden in 9 seconds.)

```yaml
Options:
  Visual:
    Info:
      Active: true
      Interval:
       - "60:56"
       - "10:1"
```


# Voting Unit

Looking into VotingUnits.yml

Voting Unit, later only ***VU***, is a core of the resource. You can also name it **Voting Situation**. Players place votes about these units.

{% hint style="info" %}
Plugin offers **7** predefined VU and you can easily extend or reduce this set.
{% endhint %}

## Creating VotingUnit in the configuration file <a href="#creating-votingunit-in-the-configuration-file" id="creating-votingunit-in-the-configuration-file"></a>

Configuration file `VotingUnits.yml` is located at main folder of the resource.

**Types**

* `GLOBAL` - Only one round can run at one moment.
* `LOCAL` - In each world, round can run independently on round in another world.

> At **Local** type, there is able to run more than one voting round at the same time. E.g. *Day* for Survival world and *Night* for SkyBlock world.

{% hint style="warning" %}
**Global** and **Local** round cannot run at the same time!
{% endhint %}

**Categories**

* `WEATHER` - Allows to change weather using built-in methods. Time change animation is available at this category.
* `CUSTOM` - VotingUnit that fits right for your server.

**PauseCategory**

VotingUnit can be assigned to pause category, if so, pause is applied only to group of VotingUnits with the same category, while another voting round can be started.

More info at <https://wiki.innouniq.com/plugins/voting/configuration/options#pause>

**Immediate initiator's vote**

This flag indicates, that player, initiator, places vote immediately at starting a round.

**Price**

We mentioned above that you can chagre players for placing a vote or starting a voting round.\
Price for *placing a vote* can be different like for *starting* a voting round.

**Required Participation**

Value in percentage range.

* Allowed range: `0 - 100`
* Default value: `100`

Required percentage of participated online players to stop and evaluate the current voting round.

Example: If there are 10 players online and the value is set to 80, then 8 players are required to participate in the current voting round.

**World Restriction**

You can restrict in which world will **not** be able to start voting round.

**Result Commands**

After the end of the round, you can specify commands, which will be invoked.

**Types of commands**

* `Global` - Commands are performed only once. Especially used at custom units.
* `Participant` - Commands are performed for each player separately
  * `Success` - Commands performed when round success
    * `All` - Commands executed for all players. (At Local round, under 'All players' is meant players in that world.)
    * `Voters` - Commands executed only for players which placed a *positive* vote
  * `Failure` - Commands performed when round fails
    * `All` - Commands executed for all players. (At Local round, under 'All players' is meant players in that world.)
    * `Voters` - Commands executed only for players which placed a *negative* vote

**Example of commands**

```yaml
Result:
  Command:
    Global:
      - "kick {target}"
    Participant:
      Success:
        All:
          - "tell {player} Round has succeed."
        Voter:
          - "karma give {player} 5"
      Failure:
        All:
          - "tell {player} Round has failed."
        Voter:
          - "karma take {player} 5"
```

> These commands do not have to be used all. You can choose only that types, which fits your expectations.\
> **E.g.,** If you want to use only global commands, you do not have to use Participant section!

***

### **Weather Category**

At first, let's clarify basic information.

* **1 Minecraft Day = 24000 Ticks = 20 Minutes**
* Tick **0** reprecents **06:00** and tick **13000** reprecents **19:00**
* More information about daylight cycle is avaialable [**here**](https://minecraft.gamepedia.com/Daylight_cycle#24-hour_Minecraft_day)

When round with weather category success, these values are applied:

```yaml
Result:
  Time: <Value> #Value indicates time in a day. Range <0;23999>
  Rain: <Flag> #Flag indicates rainy weather
  Lighting: <Flag> #Flag indicates stormy weather
  Duration: <Value> #Value indicates how long takes result.
```

> These **4** values can be used separately.\
> **E.g.,** In one VU you will use only *Time* value and in another VU, you will use *Rain*, *Lighting* and *Duration* value.

**Example of Weather VU**

```yaml
DAY: #Key of the unit. Used in intern methods, localizations file.
  Name: Day #Readable name of the unit. Used in tab-completer.
  Type: GLOBAL
  Category: WEATHER
  PauseCategory: DAY_LIGHT #Optional
  ImmediateInitiatorVote:
    Active: true
  Price:
    Start: 0
    Vote: 0
  RequiredParticipation: 100
  Restriction:
    World: [ ]
  Result:
    Time: 0 #Sets time to 6 o'clock
```

{% hint style="warning" %}
Do not forget to create new records into localization file!

Path `Alias.Unit.Weather.<VU-Key>`
{% endhint %}

### **Custom Category**

Via this category you can create own situations, which perfectly fits your server.

There is better to explain the whole mechanism with an example. We will create VU which **kicks** player from the server, if round success.

> This category works with parameters typed in command located behind *Name* of the VU.

We need to define **2** parameters. First parameters represents whom to kick and second is a reason.

> Our final command for start this round is **/Voting Kick \<Player> \<Reason>**

**Types of parameters**

* `PLAYER` - Accepts only online player as a parameter.
* `WORLD` - Accepts only name of world.
* `PAYLOAD` - Accepts more than one word. Sentence.
* `WORD` - Accepts one word.
* `INTEGER` - Accepts only Integers from allowed range.
* `DOUBLE` - Accepts only Doubles from allowed range.
* `BOOLEAN` - Accepts only predicate. `true/false`

Our first parameter is named **player**, or target for better meaning.

> Each parameter has to have its name. This name is used as a replacement at localization file and at executed commands after the end of the round.

There can occur situation, you want to **protect** yourself as an initiator of the round or you want to **protect** some players before kicking out from the server at this situation. The whole list can be specified in **Resistance** section.

> The same mechanism is at parameter of type **World**! Except initiator's protection.

Our second parameter is the **reason**, why we want to kick the player.\
Here is the best opportunnity to use type **PAYLOAD**. It allows us to read the whole sentence until the end of input line.

{% hint style="warning" %}
Type **PAYLOAD** has to be the last parameter of the sequence!
{% endhint %}

If you want to make this parameter optional, no problem, set flag Optional to true.

> Then, you need to define **default value**, which will be used instead of missing parameter.

{% hint style="warning" %}
Missing variable **Optional** in the configuration file means that parameter is **Required**!
{% endhint %}

At Number(Integer/Double) Parameters we can restrict allowed range of values.

> Use `MinValue` or `MaxValue` to specify range.

> Also, you can allow only limited values using list of strings `AllowedValueList`.

> Cou can predefine values using list of strings `PredefinedValueList`. These values will be offered at tab completing.

At the end we need to specify command, which will be executed after successful round.

Also, we need to map our values from parameters to command. It's simple, each parameter has name as mentoined above.

We create replacement. It starts with prefix **p\_**. After that prefix we will write **name** of the parameter.

> If we had name of the parameter **player** our final replacement is **p\_player**.\
> The same for the second parameter.

**Our final command**

`kick {p_player} {p_reason}`

**Our created VU for kicking the player**

```yaml
KICK:
  Name: Kick
  Type: GLOBAL
  Category: CUSTOM
  ImmediateInitiatorVote:
    Active: true
  Price:
    Start: 0
    Vote: 0
  RequiredParticipation: 100
  Restriction:
    World: [ ]
  Parameter:
    Target:
      Name: player
      Type: PLAYER
      Resistance:
        Initiator:
          Active: true
        Collection:
          - "player_name"
    Reason:
      Name: reason
      Type: PAYLOAD
      Optional: true
      DefaultValue: "Unknown"
      PredefinedValueList:
        - Spamming
        - Inappropriate behavior
        - Hacking
  Result:
    Command:
      Global:
        - "kick {p_player} {p_reason}"
```

{% hint style="warning" %}
Do not forget to create new records into localization file!
{% endhint %}


# GUI

Everything is easier with interactive inventory.

Manual, how to configure items at GUI.

## Locale/GUI.ym

Configuration file, where all data about items are located.

```yaml
DAY: #Item's key. Maintained by system, can't be changed.
   HeadName: 
     EN: "&2&lRound information"
   Lore:
     EN:
       - "&6\u25CF &7For &6\u00BB &3{state}"
       - "&6\u25CF &7World &6\u00BB &3{world}"
       - ""
       - "&6\u25CF &7Remains &6\u00BB &3{time}s"
   Material: "PAPER" #Name of the material
   MaterialData: 0 #Metadata of the item. Especially color. Only for 1.8.8 - 1.12.X
   Slot: 3 #Slot number where item will be played in inventory
   SkullData: "textures" #Texture value of player's head. 
   ItemFlags: #Flags applied to item.
   - HIDE_ENCHANTS
   CustomModelData: 0 #Is an integer that may be associated client side with a custom item model. Supported at 1.14.X and aboove.
```

### ItemFlags

* HIDE\_ENCHANTS
* HIDE\_ATTRIBUTES
* HIDE\_UNBREAKABLE
* HIDE\_DESTROYS
* HIDE\_PLACED\_ON
* HIDE\_POTION\_EFFECTS
* HIDE\_COLOR - 1.16.X and above

### Helpful stuff

Materials: <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>

Textures of player's head: <https://minecraft-heads.com>

Grid can help you to compute right slot index.

<figure><img src="/files/PefhBeDrIS77iuDUBmV3" alt=""><figcaption></figcaption></figure>




---

[Next Page](/llms-full.txt/1)