🏗️ 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

Placeholder	Returns
%vshards_amount%	The requesting player's shard balance
%vshards_amount_<player>%	A named player's shard balance

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:

Raw Value	Displayed As
500	500
1,000	1K
10,000	10K
10,500	10.5K
1,000,000	1M
2,500,000	2.5M
1,000,000,000	1B

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

---

⌨️ Commands

Command	Permission	Description
/shards	vshards.balance	Check your balance
/shards <player>	vshards.balance.others	Check another player's balance
/shards pay <player> <amount>	vshards.pay	Send shards to another player
/shards give <player> <amount>	vshards.admin.give	Give shards to a player
/shards take <player> <amount>	vshards.admin.take	Remove shards from a player
/shards set <player> <amount>	vshards.admin.set	Set exact balance
/shards top [page]	vshards.top	View leaderboard
/shards shop	vshards.shop	Open shop GUI
/shards reload	vshards.admin.reload	Reload all configs

Aliases: /vs, /vshards

---

🔐 Permissions

Permission	Default	Description
vshards.balance	Everyone	Check own balance
vshards.pay	Everyone	Send shards to another player
vshards.top	Everyone	View leaderboard
vshards.shop	Everyone	Access shop GUI
vshards.balance.others	OP	Check others' balances
vshards.admin.*	OP	All admin commands

---

🛠️ shop.yml #preview

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

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&m                    '
      - '&l&8| &f1x ᴘɪɢ ꜱᴘᴀᴡɴᴇʀ'
      - '&l&8| &7ᴄᴏꜱᴛ: &d5,000 ꜱʜᴀʀᴅꜱ'
      - '&8&m                    '
      - '&l&8| &7ᴄʟɪᴄᴋ ᴛᴏ ʙᴜʏ!'

🛠️ 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.

---