> For the complete documentation index, see [llms.txt](https://docs.xshyo.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xshyo.us/premium-plugins/namegradient/format-gradient.md).

# 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.