> ## Documentation Index
> Fetch the complete documentation index at: https://pumpkings.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# NxShards Shop: GUI Items, Prices, and Leaderboard

> Open the NxShards shop with /shards shop, sell items for Shards through a GUI, and track top players on the /shards top leaderboard.

NxShards ships with two player-facing features beyond AFK earning: an **interactive GUI shop** where players spend Shards, and a **server-wide leaderboard** that ranks the wealthiest accounts.

## The Shop

Open the shop with:

```text theme={null}
/shards shop
```

The shop is defined in its own `shop.yml` file inside `plugins/NxShards/`. Each item declares its icon, lore, slot, and a list of **actions** that execute in order when a player clicks it. The `[shards]` action charges the buyer; the rest of the actions handle item delivery, feedback, and effects.

```yaml theme={null}
shop:
  title: "&8Tienda de Shards"
  rows: 3
  items:
    example_item:
      material: DIAMOND
      name: "&bDiamante Gratis"
      lore:
        - "&7Costo: &b5 Shards"
        - "&7"
        - "&eClick para comprar"
      slot: 13
      actions:
        - "[shards] 5"
        - "[console] give %player% diamond 1"
        - "[message] &aHas comprado un diamante!"
        - "[title] &a¡Compra Exitosa!;&b1x Diamante"
        - "[sound] ENTITY_PLAYER_LEVELUP"
```

<Tip>
  Reload the shop after editing `shop.yml`:

  ```text theme={null}
  /shards reload
  ```
</Tip>

### Item Fields

| Field      | Description                                                |
| ---------- | ---------------------------------------------------------- |
| `material` | Any valid Bukkit material name (e.g. `DIAMOND`, `ELYTRA`). |
| `name`     | Display name shown in the GUI. Supports `&` color codes.   |
| `lore`     | List of lore lines shown under the item name.              |
| `slot`     | Inventory slot index inside the shop GUI.                  |
| `actions`  | Ordered list of actions executed on click (see below).     |

### Available Actions

| Action                       | Description                                                                                     |
| ---------------------------- | ----------------------------------------------------------------------------------------------- |
| `[shards] <amount>`          | Charges the player the given number of Shards. Aborts the chain if the balance is insufficient. |
| `[console] <command>`        | Runs a command from the console. `%player%` is replaced with the buyer's name.                  |
| `[player] <command>`         | Forces the player to run a command.                                                             |
| `[message] <text>`           | Sends a chat message to the buyer. Supports `&` color codes.                                    |
| `[title] <title>;<subtitle>` | Shows a title and subtitle, separated by `;`.                                                   |
| `[sound] <SOUND_NAME>`       | Plays a Bukkit sound to the buyer.                                                              |

### Purchase Flow

1. Player runs `/shards shop`.
2. The GUI opens with each item placed in its configured slot.
3. Clicking an item runs its `actions` list in order — `[shards]` first deducts the price, then the remaining actions deliver the reward and feedback.
4. If the balance is insufficient at the `[shards]` step, the action chain is aborted and the buyer is notified.

## Leaderboard

Display the top earners with:

```text theme={null}
/shards top
```

The command lists players ranked by their current Shards balance. The same data is exposed to PlaceholderAPI so you can render the leaderboard in scoreboards, tab lists, or holograms — see [Placeholders](/shards/placeholders) for the variable names.

## Player Transfers

Players move Shards between accounts with:

```text theme={null}
/shards pay <player> <amount>
```

Transfers respect the `transfer.max-amount` cap in `config.yml`, blocking abuse and protecting the economy. Both sender and receiver get a confirmation message defined under `messages.pay-sent` and `messages.pay-received`.