# ⚙️ Configuration

The `config.yml` file is the heart of VortexGens. It allows you to customize the core behavior of the plugin, from placement limits to stacking mechanics.

***

#### ⚒ Core Settings

| Key                                 | Default | Description                                                                                             |
| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `Settings.Limits Enabled`           | `true`  | When enabled, players are restricted by placement limits based on their group.                          |
| `Settings.Invalid Generator Action` | `SKIP`  | Action to take when invalid generator data is found in the database. Options: `SKIP`, `REMOVE`, `WARN`. |

***

#### 👥 Generator Limits (LuckPerms)

VortexGens integrates seamlessly with **LuckPerms** to handle generator placement limits. You can define how many generators each group can place.

```yaml
Groups:
  default: 10
  vip: 20
  admin: 999
```

{% hint style="info" %}
The plugin checks for the player's primary group in LuckPerms to determine their placement limit.
{% endhint %}

***

#### 📦 Stacking Mechanics

Stacking allows players to place multiple generators on the same block, saving space and increasing efficiency.

| Key                       | Default | Description                                                                    |
| ------------------------- | ------- | ------------------------------------------------------------------------------ |
| `Stacking.Enabled`        | `false` | Enables or disables the ability to stack generators.                           |
| `Stacking.Max Stack Size` | `64`    | The global maximum amount of generators that can be stacked on a single block. |

***

#### 💡 Advanced Logic & Cooldowns

VortexGens uses a sophisticated tick-based system to handle generator production.

* **Internal Cooldowns:** Each generator level can have its own cooldown period.
* **Ready vs. Regenerate:** Generators shift between a "Ready" state (where they can be harvested or auto-drop items) and a "Regenerate" state (cooldown period).
* **Upgrade Scalability:** Upgrade costs in the GUI are automatically multiplied by the current stack size of the generator.

{% hint style="success" %}
Configuration changes can be applied instantly using `/gens reload` without restarting your server!
{% endhint %}

***

#### 🖱 Accessing the Menu

To open the management menu, simply **Right-Click** on any placed generator that you own.

***

#### 💎 Management Actions

**🔼 Upgrading Your Generator**

If the generator has a next level defined, an upgrade item will appear in the menu.

* **Cost Calculation:** The upgrade price is based on the single-generator price multiplied by the current **Stack Size**.
* **Feedback:** Upon successful upgrade, you will hear a level-up sound and the generator block will update.

**📦 Stacking Generators**

To add to a stack:

1. Hold the generator item in your hand.
2. **Right-Click** the placed generator.
3. The stack size will increase, and one generator will be consumed from your inventory.

**🎒 Picking Up Generators**

You can collect your generators by clicking the removal icon (usually a Barrier or your generator item) in the GUI.

* **Normal:** Collects 1 generator from the stack.
* **Shift-Click:** (If configured) Collects the entire stack at once.

***

#### 📊 Dynamic Information

The GUI provides real-time data using the following placeholders:

| Placeholder                                                                                                       | Description                                     |
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `<generator-name>`                                                                                                | The custom display name of the generator.       |
| `<generator-owner>`                                                                                               | The name of the player who placed it.           |
| `<generator-level>`                                                                                               | The current level (1, 2, 3, etc.).              |
| `<generator-time>`                                                                                                | Time remaining until the next production cycle. |
| `<upgrade-price>`                                                                                                 | Total cost to upgrade the entire stack.         |
| ![Preview](https://via.placeholder.com/800x400.png?text=GIF+Preview:+Hovering+over+GUI+items+to+see+placeholders) |                                                 |
| *Caption: Real-time data updates within the item lore.*                                                           |                                                 |

***

{% hint style="info" %}
**Visual Customization:** The GUI layout, titles, and items are fully customizable in \`gui.yml\`. You can even use custom Oraxen or items for a truly premium feel.
{% endhint %}
