💎 V-Shards

Simple vertical transportation for Paper 1.21.1+ servers

✨ Features

• 🏦 UUID-based economy — Balances survive name changes
• 🛒 GUI Shop System — Fully customizable buy/sell interface
• 🎯 PlaceholderAPI Support — Display balances anywhere
• 📊 Leaderboards — Top shard holders with pagination
• ⚡ Zero Lag Design — Dirty-tracking saves only modified data
• 🎨 MiniMessage Formatting — Modern color gradients & styling
• 🔒 Secure — Locked GUI prevents item manipulation
• ⬆️ Auto-save — Configurable intervals (default: 5 min)

📦 Installation

1. Download V-Shards.jar
2. Drop into plugins/ folder
3. Restart server
4. Edit plugins/V-Shards/config.yml to customize

PlaceholderAPI

Balances are formatted using the same K / M / B abbreviation system as in-game (e.g. 10K, 2.5M, 1B).

Number Formatting

All balance and price values across commands, messages, and placeholders are automatically abbreviated:

Whole numbers never show a decimal (e.g. 10K not 10.0K). Decimals only appear when meaningful (e.g. 10.5K).

⌨️ Commands

Aliases: /shard

🔐 Permissions

🛠️ shop.yml #preview

Defines the GUI layout and all shop items. Reloads with /shards reload — no restart needed.

# =============================================
#         V-Shards - Shop Configuration
# =============================================
# Supports & legacy color codes in display_name, lore, and menu_title.
#
# Item types:
#   buy        deducts shards, then gives the item or runs commands
#   sell       takes the item, then gives shards
#   close      closes the GUI
#   decoration non-interactive filler item
#
# Slot formats:
#   slot: 13
#   slot: 0, 1, 2, 3, 4, 5
#   slot: [0, 1, 2, 3, 4, 5]
#
# Optional command fields:
#   command-console: runs as CONSOLE, supports %player%
#   command-player:  runs as the PLAYER
#   If commands are defined, no item is given/taken - commands handle the action.
#   Set amount: 0 when using commands.
# =============================================

menu_title: '&dꜱʜᴀʀᴅꜱ ꜱʜᴏᴘ' size: 27

items:

Top decorative border

border: material: GRAY_STAINED_GLASS_PANE slot: 18, 19, 20, 21, 22, 23, 24, 25, 26 type: decoration display_name: '&r' lore: []

Shop items

pig_spawner_buy: material: SPAWNER slot: 0 type: buy price: 5000 amount: 1 display_name: '&d&lᴘɪɢ ꜱᴘᴀᴡɴᴇʀ' lore: - '&8 ' - '&l&8| &f1x ᴘɪɢ ꜱᴘᴀᴡɴᴇʀ' - '&l&8| &7ᴄᴏꜱᴛ: &d5,000 ꜱʜᴀʀᴅꜱ' - '&8 ' - '&l&8| &7ᴄʟɪᴄᴋ ᴛᴏ ʙᴜʏ!'

pig_spawner_sell: material: SPAWNER slot: 1 type: sell price: 2500 amount: 1 display_name: '&c&lꜱᴇʟʟ ᴘɪɢ ꜱᴘᴀᴡɴᴇʀ' lore: - '&8 ' - '&l&8| &f1x ᴘɪɢ ꜱᴘᴀᴡɴᴇʀ' - '&l&8| &7ᴇᴀʀɴ: &62,500 ꜱʜᴀʀᴅꜱ' - '&8 ' - '&l&8| &7ᴄʟɪᴄᴋ ᴛᴏ ꜱᴇʟʟ!'

diamond_buy: material: DIAMOND slot: 2 type: buy price: 300 amount: 1 display_name: '&b&lᴅɪᴀᴍᴏɴᴅ' lore: - '&8 ' - '&l&8| &f1x ᴅɪᴀᴍᴏɴᴅ' - '&l&8| &7ᴄᴏꜱᴛ: &b300 ꜱʜᴀʀᴅꜱ' - '&8 ' - '&l&8| &7ᴄʟɪᴄᴋ ᴛᴏ ʙᴜʏ!'

diamond_sell: material: DIAMOND slot: 3 type: sell price: 150 amount: 1 display_name: '&c&lꜱᴇʟʟ ᴅɪᴀᴍᴏɴᴅ' lore: - '&8 ' - '&l&8| &f1x ᴅɪᴀᴍᴏɴᴅ' - '&l&8| &7ᴇᴀʀɴ: &6150 ꜱʜᴀʀᴅꜱ' - '&8 ' - '&l&8| &7ᴄʟɪᴄᴋ ᴛᴏ ꜱᴇʟʟ!'

── Example command-based buy (no item given — command does it) ────────────

vip_rank:

material: NETHER_STAR

slot: 16

type: buy

price: 50000

amount: 0

command-console:

- 'lp user %player% parent set vip'

command-player:

- 'me just bought VIP!'

display_name: '&6&lᴠɪᴘ ʀᴀɴᴋ'

lore:

- '&8 '

- '&l&8| &7ᴄᴏꜱᴛ: &650,000 ꜱʜᴀʀᴅꜱ'

- '&8 '

- '&l&8| &7ᴄʟɪᴄᴋ ᴛᴏ ʙᴜʏ!'

── Bottom bar ─────────────────────────────────────────────────────────────

close: material: RED_STAINED_GLASS_PANE slot: 22 type: close display_name: '&c&lᴄʟᴏꜱᴇ' lore: - '&7ᴄʟɪᴄᴋ ᴛᴏ ᴄʟᴏꜱᴇ.'

</details>

#### 🛠️ Item field reference

| Field | Required | Notes |
|---|---|---|
| `material` | ✅ | Any valid Bukkit `Material` name (e.g. `DIAMOND`, `SPAWNER`) |
| `slot` | ✅ | Inventory slot index, `0` to `size - 1` |
| `type` | ✅ | `buy`, `sell`, `close`, or `decoration` |
| `price` | buy / sell | Shards deducted (buy) or rewarded (sell) |
| `amount` | buy / sell | Items given/taken. Use `0` alongside `command-console` / `command-player` |
| `command-console` | optional | List of commands run as console. Supports `%player%` |
| `command-player` | optional | List of commands run as the player. Supports `%player%` |
| `display_name` | ✅ | Supports `&` color codes |
| `lore` | optional | List of lore lines. Supports `&` color codes |

> **Tip:** Slots are 0-indexed. For a 54-slot inventory (6 rows), valid slots are `0`–`53`. Two items sharing the same slot will cause one to silently overwrite the other.

---