# Custom currency

SporeCore has a **custom currency feature** that allows you to create an additional currency. This currency is slightly different from your main economy. While it can be used for general purposes, the main idea is to create a **premium currency**.

The only way to obtain a higher balance of this currency is by **purchasing it in the server store**. You may be familiar with examples like **Cubits (ManaCube)** or **Skyblock Gems (Hypixel)**. This feature is designed for that type of currency. You can create your own shop and manage the currency directly.

***

## 📚 Currency setup

You can configure the currency in the automatically generated `credits.yml` file. By default, the currency is called `credits`. You can rename it in `config.yml` by searching for the **currency section**. In this section, you can:

* Enable or disable the currency.
* Set the file YML name.

If the file does not exist, you can run `/sporecore reload` in-game or restart the server, and it will automatically generate a new file. Once the feature is enabled and the YML file is created, you can open the file and edit all the settings.

***

## 💵 Currency settings

Once you are in the currency file you can see at the top `currencySetting` . In there we can modify some settings.

```yaml
currencySettings:
  singularName: Credit
  pluralName: Credits
  currencyColor: '&#9C68D9&l'
  shopCommand:
  - creditshop
  symbol: ✦
  symbolBeforeAmount: true
  spaceAfterSymbol: true
  nameAfterAmount: true
  useThousandSeparator: true
  decimalDigits: 0
  balanceFormat: PLAIN
  startingBalance: 0.0
  shopName: Credit Shop
  shopEnabled: true
  broadcastStaff: true
  broadcastMessages:
  - '&c[CreditShop Alert!] &f%player% has bought the %package_name% &ffor &a%costs%'
```

### 🔹 Explanation of Key Settings

* **singularName / pluralName:** The display names for the currency.
* **currencyColor:** The color used for the symbol or currency name. Supports MiniMessages, RRGGBB, and standard Minecraft codes.
* **shopCommand:** Aliases for the in-game shop command.
* **symbol, symbolBeforeAmount, spaceAfterSymbol, nameAfterAmount:** How the currency is displayed to players.
* **useThousandSeparator:** Enables formatting for easier readability.
* **decimalDigits & balanceFormat:** Determines how balances are shown.
* **startingBalance:** Amount new players start with.
* **shopName & shopEnabled:** Configure and enable the in-game shop menu.
* **broadcastStaff & broadcastMessages:** Controls notifications when players buy currency packages.

***

## 🏪 Currency Shop

Once you have set up all the currency settings, you can start creating a **shop**. In the shop, you can create **categories**, and within each category, you can add **packages/items** that players can purchase.

***

### 📚 Configuration Overview

The shop configuration is in the `shop` section of the currency YML file. Each category can now have its **own menu settings**, allowing you to customize rows and placeholder items per category.

```yaml
shop:
  menuSettings:
    main:
      rows: 4
      fillItems: true
    categories:
      ranks:
        rows: 3
        fillItems: true
```

* **main / categories:** Number of rows and whether empty slots are filled with placeholder items.
* **category-specific menu settings:** Allows different categories to have different layouts.

#### 🔹 Menu Slot Coordinates

Instead of using slot numbers (0–53), items are placed using **row|column** coordinates.

* Format: `row|column`
* Example: `5|2` → Row 5, Column 2

> **Note:** Items cannot be placed in the bottom row (slots 45–54).

#### 🔹 Placeholders

You can use the following placeholders in all shop items:

| Placeholder           | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| `%player%`            | The name of the viewer.                                         |
| `%balance%`           | The viewer’s current balance.                                   |
| `%currency%`          | The plural currency name.                                       |
| `%singular_currency%` | The singular currency name.                                     |
| `%symbol%`            | The currency symbol.                                            |
| `%package_name%`      | The name of the purchased package (used in broadcast messages). |
| `%costs%`             | The cost of the package (used in broadcast messages).           |
| PlaceholderAPI        | All PlaceholderAPI placeholders are supported.                  |

### 🔹 Categories

Categories are the main sections of your shop. Each category must include:

* **name:** The display name of the category.
* **slot:** The menu position using row|column format.
* **displayItem:** The item that represents the category in the main menu.
  * **material:** The Minecraft item used as the icon.
  * **name:** The display name of the category item.
  * **description:** A list of text lines describing the category.

Example:

```yaml
categories:
  ranks:
    name: Ranks
    slot: 3|5
    displayItem:
      material: PAPER
      name: '&eRanks'
      description:
      - '&7Purchase your permanent ranks here!'
```

> To add a new category, simply copy the structure above and give it a unique key (e.g., `pets`, `gadgets`).

### 🔹 Items/Packages

Each category contains items/packages that players can purchase. Every item must include:

* **slot:** Menu position (row|column).
* **name:** Display name for the item.
* **description:** List of text lines describing perks or effects.
* **price:** Cost of the item in your custom currency.
* **material:** Minecraft item used as the display item.
* **higherRanks (optional):** List of rank permissions that must be purchased first.
* **purchaseCommands:** Commands executed when the item is bought. Use `%player%` to reference the buyer.

Example:

```yaml
items:
  0:
    slot: 2|2
    name: Bronze Rank
    description:
    - '&fReceive the &6[Bronze] &ftag!'
    - '&fPerks:'
    - '&e/bronze'
    price: 100.0
    material: PAPER
    higherRanks: []
    purchaseCommands:
    - /lp user %player% parent add bronze

```

To add a new item, create a new index (e.g., `2`) under the category and follow the same structure.

#### 🔹 Info Items

Info items are **global or category-specific items** that appear in menus. Each info item must include:

* **material:** Minecraft item used for the display.
* **menu:** Menu(s) where the item appears (`main` or category name).
* **slot:** Menu position (row|column).
* **name:** Display name of the item.
* **description:** List of lines for additional information.

Example:

```yaml
infoItems:
  1:
    material: BOOK
    menu: main
    slot: 2|5
    name: '&bInformation'
    description:
    - '&7Earn %currency% &7through &avoting &7or buying at &e/store!'
    - '&7Spend them here for awesome &e&lrewards!'
```

To add a new info item, add a new index under `infoItems` and follow the same format.

✅ **Summary of Required Fields**

| Type         | Required Fields                                                        |
| ------------ | ---------------------------------------------------------------------- |
| Category     | `name`, `slot`, `displayItem` (`material`, `name`, `description`)      |
| Item/Package | `slot`, `name`, `description`, `price`, `material`, `purchaseCommands` |
| Info Item    | `material`, `menu`, `slot`, `name`, `description`                      |
