# Creating a custom template

{% hint style="info" %}
This page is only shown you the way to create a template for a lootchest type, this mean if there is multiple lootchest type, there should be multiple template like this in 1 template file!
{% endhint %}

## I. OVERVIEW

Below is an example for you!

***

### **Template Structure**

A template consists of the following main sections:

* **`settings`** → General settings for the loot chest.
* **`buttons`** → Buttons for interaction and animations.
* **`rewards-location`** → Locations where rewards will appear.

***

{% hint style="info" %}
Material list: [here](https://github.com/CryptoMorin/XSeries/blob/master/src/main/java/com/cryptomorin/xseries/XMaterial.java)\
Sound list: [here](https://github.com/CryptoMorin/XSeries/blob/master/src/main/java/com/cryptomorin/xseries/XSound.java)\
Note: the usable part is the enum name (e.g. ACACIA\_BOAT)
{% endhint %}

***

### **1. General Settings** (`settings`)

```yaml
settings:
  player-location: world, 182.5, 70, 196.3, 180, 0
  location: world, 182.5, 73.2, 193.5
  rotations:
    '1':
      position: "HEAD"
      value: 0, 45, 0
  decoration:
    location: world, 182.21, 74.3, 193.570
    rotations:
      '1':
        position: "RIGHT_ARM"
        value: 90, 90, 0
  click-to-open: false
```

#### **Explanation:**

* **`player-location`** → The player's position when interacting with the loot chest. **(This will be the main position of this template for this lootchest type)**
* **`location`** → The main location of the loot chest.
* **`rotations`** → Defines how the chest rotates at specific positions
* **`decoration`** → Additional objects of this chest. (built-in objects)
* **`click-to-open`** → Determines if the chest opens when clicked.

***

### **2. Configuring Buttons** (`buttons`)

```yaml
buttons:
  '1':
    location: world, 181, 69.9, 194, 148.5, 0
    icon:
      material: PLAYER_HEAD
      data: 3 (This data value should be custom model data if you use 1.14+)
      head_value: <custom_texture>
    click-sound:
      sound: UI_BUTTON_CLICK
      yaw: 10
      pitch: 10
    hover-sound:
      sound: ENTITY_CHICKEN_EGG
      yaw: 5
      pitch: 5
    name:
      enable: true
      visible-mode: hover (There are 2 modes: "always" and "hover". You can delete this option to set it to "always")
      dynamic: true
      refresh-interval: 5
      display-name:
        - '<#FF6600>Close!</#9DFF8A>' (Hex & Gradient Support 1.17+, PlaceholderAPI Support)
    delay: 30
    permission: 'button.test'
    holding-icon: true
    rotate-on-spawn:
      enable: true
      final-yaw: -31.5
      reverse: true 
    actions:
      - '[close]'
```

#### **Explanation:**

* **`location`** → The button’s position.
* **`icon`** → Defines the material and texture for the button (e.g., PLAYER\_HEAD).
* **`click-sound` / `hover-sound`** → Sounds when clicking or hovering over the button.
* **`name`** → Defines the button's display name, with options for visibility, dynamic colors, and refresh interval.
* **`delay`** → Delay before the button would be spawned after the session start.
* **`permission`** → Required permission to interact with this button.
* **`holding-icon`**→ Set this to false to hide the icon of this button
* **`rotate-on-spawn`** → Determines if the button rotates when it spawns. **(if this option enable, the yaw above will be the initial yaw, and it will spin to the final yaw)**
* **`actions`** → Defines what happens when the button is clicked .

***

### **3. Adding Rewards Locations** (`rewards-location`)

```yaml
rewards-location:
  - world, 182.5, 71.1, 193.2, 0, 0
  - world, 180, 71.1, 194.5, -55, 0
  - world, 185, 71.1, 194.5, 55, 0
```

#### **Explanation:**

* Defines where rewards will appear when a player opens a loot chest.
* Each entry consists of a `world`, `x, y, z` coordinates, and optional rotation (`yaw, pitch`).

***

### **4. Additional Customization Options**

#### **Child Elements (Sub-Buttons)**

Child Elements add some **visual effects** to the button, it has no execution and always rely on its parent.\
Here is some available options for a sub-button:

* Location
* Name
* Icon
* Rotations

Example:

```yaml
buttons:
  '1':
    children:
      '1':
        location-offset: 0, -1.3, 0, 180, 0
        name:
          enable: true
          display-name: '&e&l%hlootchest_current_regular% Left!'
          refresh-interval: 20
      '2':
        location-offset: 0, 0, 0, 180, 0
        name:
          enable: true
          visible-mode: hover
          display-name: '&eClick to open!'
      ...
```

* **`location-offset`** → Defines the position relative to the parent button.
* **`display-name`** → The name of this child.

This is just the overview, if you want further information please go to next part!

## II. Details

***

### 1. Location

HLootChest provides 2 location modes: **`location`**  and **`location-offset`**

{% tabs %}
{% tab title="location" %}
You can set the exactly location using this mode.\
**Example:**\
`location: world, 182.5, 73.2, 193.5`
{% endtab %}

{% tab title="location-offset" %}
You can defines the position relative to the parent button. **(Note: this mode only works for child elements)**\
**Example:** \
`location-offset: 0.5, 0.5, 0.5, 90, 45` \
**Explaination:**\
If the button location is `0, 70, 0, 180, 0`\
This child will be summon at `0.5, 70.5, 0.5, -90, 45`

This location mode support math expression, but there just a few variable, custom variable coming soon!
{% endtab %}
{% endtabs %}

### 2. Rotations

With this option, you can determine the rotation of the **Armorstand**.

There are different rotation modes:

* HEAD
* BODY
* RIGHT\_ARM
* LEFT\_ARM
* RIGHT\_LEG
* LEFT\_LEG

You can set the rotation for almost all elements (box, buttons, sub-buttons)\
**Example:**

<pre><code>rotations:
<strong>  '1':
</strong>    position: "HEAD"
    value: 0, 45, 0 (This is X, Y, Z rotation respectively)
</code></pre>

### 3. Icon

HLootChest provides two icon displaying mode: **`static`** and **`dynamic`**&#x20;

{% tabs %}
{% tab title="static" %}
Use this option for performance purpose!\
**Example:**

<pre><code>  icon:
<strong>    material: PLAYER_HEAD
</strong>    data: 3
    head_value: &#x3C;custom_texture>
</code></pre>

{% endtab %}

{% tab title="dynamic" %}
Use this mode for more impressive buttons!\
**Example:**

<pre><code>  icon:
    dynamic: true (I said static and dynamic but it actually no option for static mode. Just turn off this)
    refresh-interval: 5
    dynamic-icons: (add more and more...!)
      '1':
<strong>        material: PLAYER_HEAD
</strong>        data: 3
        head_value: &#x3C;custom_texture>
</code></pre>

{% endtab %}
{% endtabs %}

### 4. Name

Same with **Icon,** HLootChest provides two name displaying mode: **`static`** and **`dynamic`**&#x20;

{% tabs %}
{% tab title="static" %}
Use this option for performance purpose!\
**Note: If you use this mode, it is necessary to put name in a line (not a list!)**\
**Example:**

```
  name:
    enable: true
    visible-mode: hover
    display-name: <#FF6600>Close!</#9DFF8A>
```

{% endtab %}

{% tab title="dynamic" %}
Use this mode for more impressive buttons!\
**Example:**

```
  name:
    enable: true
    visible-mode: hover
    dynamic: true
    refresh-interval: 5
    display-name:
      - '<#FF6600>Close!</#9DFF8A>'
      - ...
```

{% endtab %}
{% endtabs %}

### 5. Actions

With this option, you can set the actions will be called on button click

There are some action tags:

* **\[player]**: execute player's command (PlaceholderAPI Support!).
* **\[console]**: execute console command.
* \[**message]**: send message to player.
* **\[close]**: leave lootchest opening.

### 6. Requirements

Every button has 2 requirements: **spawn-requirements** and **click-requirements**

**Example:**

{% tabs %}
{% tab title="For has-permission" %}

```
  spawn-requirements:
    '1':
      type: has-permission
      value: hlc.test
```

{% endtab %}

{% tab title="Others" %}

```
  spawn-requirements:
    '1':
      type: string-equals
      input: %player_name%
      output: justAname
```

{% endtab %}
{% endtabs %}

There is 8 requirement types:

* has-permission
* string-equals
* \>=
* \>
* \==
* <
* <=
* !=