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 / 安装

Download SkullShop-1.0.0.jar from Releases. 从 Releases 下载最新版本。
Place it in your server's plugins/ folder. 放入服务器的 plugins/ 文件夹。
Restart the server (or run /reload confirm). 重启服务器（或执行 /reload confirm）。
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 / 添加新语言

Copy plugins/SkullShop/messages_en.yml to messages_<lang>.yml
Translate all values (keep the YAML keys and & color codes)
Set language: "<lang>" in config.yml
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。

Skull Shop