Gemengine

# GemEngine – Plugin Description

GemEngine is a Minecraft plugin for Paper servers that provides a flexible multi-economy system. It allows you to manage multiple independent currencies per player, accessible via commands and PlaceholderAPI.

## ⚙️ Requirements

| Plugin | Required? | Purpose | |---|---|---| | (https://modrinth.com/plugin/placeholderapi/) | ❌ Optional | Provides the `%gemengine_...%` placeholders | | (https://www.spigotmc.org/resources/vault. 34315/) | ❌ Optional | Automatic detection of installed economies (e.g. Essentials) |

## 📂 Files

### `config.yml` – Configure Economies This is where all currencies managed by the plugin are defined.

```yaml economies: gems: name: "Gems" # Display name of the currency allow-pay: true # Can players transfer to each other? coins: name: "Coins" allow-pay: false ```

> Tip: If Vault + Essentials are installed, an entry for the Essentials economy will be generated automatically on server start — no manual setup required.

### `data.yml` – Player Data All player balances are stored here. This file is managed automatically and should not be edited manually.

```yaml #Example 550e8400-e29b-41d4-a716-446655440000: gems: 150. 0 coins: 320. 50 ``` 📢 This was replaced by a database in version 4. 0. 0 or higher.

## 💬 Commands

### `/gpay ` Transfers an amount of a specific currency to another player.

| Argument | Description | |---|---| | `` | The economy key from config.yml (e.g. `gems`) | | `` | Name of the target player (must be online) | | `` | The amount to transfer (must be positive) |

Example: ``` /gpay gems Steve 50 ``` > ⚠️ Transfers must be enabled per economy in config.yml via `allow-pay: true`. The sender also needs a sufficient balance.

### `/gemengine eco ` Admin command for manually managing player balances.

| Action | Description | |---|---| | `set` | Sets the balance to a specific value | | `add` | Adds an amount to the balance | | `remove` | Deducts an amount from the balance (minimum 0, no negative balance) |

Examples: ``` /gemengine eco set gems Steve 500 /gemengine eco add coins Steve 100 /gemengine eco remove gems Steve 25 ```

## 🔑 Permissions

| Permission | Description | |---|---| | `gemengine.admin` | Access to `/gemengine eco` |

## 📊 Placeholders (PlaceholderAPI)

The placeholder format is: ``` %gemengine_% ```

The `` part corresponds to the key defined in `config.yml`.

Examples:

| Placeholder | Returns | |---|---| | `%gemengine_gems%` | The player's balance in the "gems" economy | | `%gemengine_coins%` | The player's balance in the "coins" economy |

> Values are always returned with 2 decimal places, e.g. `150. 00`

## 🔗 Vault Integration

If Vault is installed alongside an economy plugin such as EssentialsX, GemEngine will automatically detect it on startup and add a matching entry to `config.yml`.

Example: EssentialsX is installed and uses `Dollars` as its currency.

On the first server start, the following will appear in the console: ``` Vault Economy 'Essentials Economy' detected! Entry 'essentials_economy' has been automatically added to config.yml. Placeholder: %gemengine_essentials_economy% ```

The `config.yml` will then be automatically updated with this entry: ```yaml economies: essentials_economy: name: "Dollars" allow-pay: false ```

> Note: `allow-pay` is intentionally set to `false` to prevent accidental transfers from being enabled. This can be changed manually in `config.yml`. For more help and explanations look in the `config.yml` and `message.yml`.

## 💻 Installation

1. Drop `GemEngine.jar` into your server's `plugins/` folder 2. Make sure PlaceholderAPI is installed as well 3. Start the server 4. Add your own economies in `plugins/GemEngine/config.yml` 5. Restart the server or reload the plugin.