SkullShop 🎭

A Paper plugin for buying player heads with multiple economy options — GUI-driven, lightweight, and fully customizable.

一款支持多种经济系统的 Paper 玩家头颅商店插件 — GUI 交互、轻量级、完全可定制。

---

Features / 功能

Feature	功能
3 Economy Types — Vault (coins), PlayerPoints (points), Custom NBT Items	3 种经济系统 — Vault 金币、PlayerPoints 点券、自定义 NBT 物品货币
Interactive GUI — Choose payment method, select quantity, preview head skin	交互式 GUI — 选择支付方式、数量，预览头颅皮肤
Direct Command Purchase — /hs buy <player> via <type> [amount]	命令直接购买 — 支持一键购买无需打开 GUI
Multi-Language — English & Simplified Chinese, easy to add more	多语言支持 — 英文 & 简体中文，易于扩展
Runtime Config — Hot-reload, toggle currencies, change prices without restart	热重载 — 重载配置、开关货币、修改价格无需重启
Async Skin Loading — Paper PlayerProfile API with Mojang fallback	异步皮肤加载 — Paper API + Mojang API 回退
Admin Controls — Allow/disallow buying other players' heads	管理员控制 — 可禁止购买他人头颅

---

Requirements / 环境要求

Requirement	要求
Paper 1.20.6+	Server / 服务端
Java 21+	Java
Vault (optional)	For coin economy / 金币经济
PlayerPoints (optional)	For points economy / 点券经济

---

Installation / 安装

1. Download SkullShop-1.0.0.jar from Releases. 从 Releases 下载最新版本。
2. Place it in your server's plugins/ folder. 放入服务器的 plugins/ 文件夹。
3. Restart the server (or run /reload confirm). 重启服务器（或执行 /reload confirm）。
4. Edit plugins/SkullShop/config.yml to configure prices and currencies. 编辑 plugins/SkullShop/config.yml 配置价格和货币。

---

Commands / 命令

All commands use /hs (alias: /skullshop). 所有命令使用 /hs（别名：/skullshop）。

Player Commands / 玩家命令 — skullshop.use

Command	Description
/hs buy	Open GUI to buy your own head / 打开 GUI 购买自己的头颅
/hs buy <player>	Open GUI to buy another player's head / 打开 GUI 购买其他玩家的头颅
/hs buy [player] via <vault|player_points|item> [1|8|64]	Direct purchase with quantity / 指定数量和货币直接购买
/hs price [vault|player_points|item]	View prices / 查看各货币价格
/hs help	Show help / 显示帮助

Admin Commands / 管理员命令 — skullshop.admin

Command	Description
/hs price <vault|player_points|item> <amount>	Set price / 设置价格
/hs currency <vault|player_points|item> <enable|disable>	Toggle currency / 开关货币类型
/hs allowother <on|off>	Allow/deny buying other players' heads / 允许/禁止购买他人头颅
/hs setitem	Set held item as currency reference (records full NBT) / 将手持物品设为货币参考物品
/hs reload	Reload config & messages / 重载配置和语言文件

---

Permissions / 权限

Permission	Scope	Default
skullshop.use	/hs buy, /hs price, /hs help	true (all players)
skullshop.admin	All admin subcommands	op

---

Economy Systems / 经济系统

1. Vault (金币)

Uses the server's Vault-compatible economy plugin (e.g., EssentialsX). Players pay in-game coins.

economy:
  vault:
    enabled: true
    price: 100.0
    display_name: "金币"

2. PlayerPoints (点券)

Uses the PlayerPoints plugin. Players pay with points.

economy:
  player_points:
    enabled: false
    price: 150
    display_name: "点券"

3. Custom Item (物品货币)

Any NBT item can serve as currency. Hold the item and run /hs setitem to configure. All NBT tags are recorded for exact matching.

economy:
  item:
    enabled: false
    price: 1
    display_name: "货币物品"
    reference_item: {}  # Set automatically by /hs setitem

---

Configuration / 配置

Config file: plugins/SkullShop/config.yml

# Whether players can buy other players' heads
allow_other_players: true

# Language: "zh" for Chinese, "en" for English
language: "zh"

# Economy systems — each independently toggleable
economy:
  vault:
    enabled: true
    price: 100.0
    display_name: "金币"
  player_points:
    enabled: false
    price: 150
    display_name: "点券"
  item:
    enabled: false
    price: 1
    display_name: "货币物品"
    reference_item: {}

Adding a New Language / 添加新语言

1. Copy plugins/SkullShop/messages_en.yml to messages_<lang>.yml
2. Translate all values (keep the YAML keys and & color codes)
3. Set language: "<lang>" in config.yml
4. Run /hs reload

---

GUI Preview / GUI 预览

┌──────────────────────────────┐
│    Select Payment Method      │
│                              │
│   [Player Head Preview]       │
│                              │
│  [💰 Vault]   Price: 100     │
│  [💎 Points]  Price: 150     │
│  [📦 Item]    Price: 1       │
│                              │
└──────────────────────────────┘

┌──────────────────────────────┐
│    Buy <Player>'s Head       │
│                              │
│   [Player Head Preview]       │
│                              │
│  [x1]  Total: 100  Balance   │
│  [x8]  Total: 800  Balance   │
│  [x64] Total: 6400 Balance   │
│                              │
│        [← Back]              │
└──────────────────────────────┘

---

FAQ / 常见问题

Q: Can players buy heads of offline players? A: Yes! The plugin uses Mojang API as fallback for players who have never joined the server.

Q: 能购买离线玩家的头颅吗？ A: 可以！插件会通过 Mojang API 异步获取从未上过线的玩家皮肤。

Q: How do I add more languages? A: Copy messages_en.yml, rename to messages_<lang>.yml, translate, and set language in config.

Q: 如何添加更多语言？ A: 复制 messages_en.yml，重命名为 messages_<语言>.yml，翻译后在配置中修改 language。

Q: Does it work on Spigot/Bukkit? A: It's built for Paper 1.20.6+. May work on Spigot but is untested.

Q: 支持 Spigot/Bukkit 吗？ A: 基于 Paper 1.20.6+ 构建，可能兼容 Spigot 但未测试。

---

Links / 链接

• Source Code / 源码: GitHub
• Issues / 问题反馈: GitHub Issues
• Releases / 下载: GitHub Releases

---

License / 许可证

MIT License — see LICENSE for details. 详见 LICENSE。