# Format Gradient

### 🎨 Gradient Configuration Guide

This section explains how to define gradients in your menu, using either the **basic** or **advanced** format. Gradients allow you to create visually appealing colored text and items with optional requirements for unlocking them.

***

## 🔹 Basic Format

The basic format is simple and requires only the essential fields. You can use it to quickly set up a gradient display.

```yaml
colors:
  - id: 1
    display_name: ⬛⬛⬛⬛⬛⬛⬛⬛⬛
    gradient: true
    permission: gradient.name
    patterns:
      - '#F2709C'
      - '#FF5733'
    style:
      - "STRIKETHROUGH"
```

**Basic Field Descriptions:**

* `id`: A unique identifier for this color/gradient entry.
* `display_name`: The text shown in the GUI. You can use placeholders like `%player_name%` or symbols.
* `gradient`: Set to `true` to apply a gradient effect to the `display_name`.
* `permission`: The permission required to unlock this gradient. Use `none` for free access.
* `patterns`: List of hexadecimal colors (e.g., `#F2709C`) that define the gradient.
* `style`: Optional. You can apply chat styles like `BOLD`, `ITALIC`, `UNDERLINE`, or `STRIKETHROUGH`.

***

## ⚙️ Advanced Format

Use this format to customize item visuals further with materials, glowing effects, model data, amount, and hidden attributes.

```yaml
colors:
  - id: 1
    display_name: ⬛⬛⬛⬛⬛⬛⬛⬛⬛
    gradient: true
    permission: gradient.name
    material: BEDROCK
    glowing: true
    model_data: 0
    hide_attributes: true
    amount: 3
    patterns:
      - '#F2709C'
    style:
      - "STRIKETHROUGH"
```

**Additional Fields:**

* `material`: Sets the item material (e.g., `BEDROCK`).
* `glowing`: Makes the item glow if `true`.
* `model_data`: Custom model data ID for resource pack support.
* `hide_attributes`: Hides attributes like damage or armor.
* `amount`: Sets the item amount shown in the menu.

***

### ✅ Requirements (Conditions)

Requirements define whether the player can claim the reward. All comparisons are done using PlaceholderAPI values.

#### 📌 Available Conditions

| Condition | Description                         | Example                               |
| --------- | ----------------------------------- | ------------------------------------- |
| `==`      | Equals (number only)                | `"%vault_eco_balance%" == 1000`       |
| `!=`      | Not equal (number only)             | `"%player_name%" != "Steve"`          |
| `>=`      | Greater than or equal (number only) | `"%statistic_hours_played%" >= 10`    |
| `>`       | Greater than (number only)          | `"%player_level%" > 30`               |
| `<=`      | Less than or equal (number only)    | `"%player_level%" <= 5`               |
| `<`       | Less than (number only)             | `"%vault_eco_balance%" < 100`         |
| `=`       | Equals (text only)                  | `"%luckperms_primary_group%" = "vip"` |
| `<-`      | Contains (text only)                | `"%player_name%" <- "xShyo"`          |
| `\|-`     | Starts with (text only)             | `%player_name%" \|- "B_"`             |
| `-\|`     | Ends with (text only)               | `%player_name%" -\| "_"`              |

***

## 💡 Example with Multiple Requirements

```yaml
requirements:
  - placeholder: "%vault_eco_balance%"
    condition: ">="
    value: "1000"
    success: "#4FFD4A ✔ Enough money. &7[Completed]"
    fail: "#FC3A3A ✖ You need at least $1000. &7[Not Completed]"

  - placeholder: "%statistic_hours_played%"
    condition: ">="
    value: "5"
    success: "#4FFD4A ✔ Enough playtime. &7[Completed]"
    fail: "#FC3A3A ✖ You need to play at least 5 hours. &7[Not Completed]"
```

> The gradient will only be available to players with **at least $1000** and **5 hours of playtime**.

***

## 🧠 Tips

* Make sure to install PlaceholderAPI and the required expansions (`/papi ecloud`).
* You can stack multiple conditions to create exclusive or achievement-based gradients.
* Use emojis and color codes to make lore messages more engaging.


---

# Agent Instructions: Querying This Documentation

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

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

```
GET https://docs.xshyo.us/premium-plugins/namegradient/format-gradient.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.