> For the complete documentation index, see [llms.txt](https://twightlight.gitbook.io/hlootchest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://twightlight.gitbook.io/hlootchest/configurations/creating-a-custom-template.md).

# 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
* \>=
* \>
* \==
* <
* <=
* !=


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://twightlight.gitbook.io/hlootchest/configurations/creating-a-custom-template.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.