# ⚙️ 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 %}


---

# 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://wiki.vortexdevelopment.net/projects/vortexgens/configuration.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.