GUIShop - 终极商店解决方案

GUIShop 是一款功能强大的 GUI 商店插件，让服务器主能够创建美观、可深度自定义的图形界面商店。它告别了繁琐的告示牌或箱子商店，为玩家提供直观的购物体验，同时赋予管理员对价格、物品和布局的完全控制权。

💡核心特性

• 易于使用的 GUI 系统 - 玩家通过清晰、有序的库存菜单浏览商店。
• 多页面商店 - 创建支持无限页面的商店，容纳海量商品。
• 动态定价系统 - 可选基于供需关系的价格浮动机制。
• 价值显示系统 - 直接在物品描述中显示出售价格（需要 PacketEvents）。
• 全 GUI 物品编辑器 - 通过直观的 GUI 界面编辑物品价格、名称、附魔等。
• 拖拽式商店搭建 - 通过简单的拖放操作来放置和重新排列商店物品。
• 命令物品 - 出售可执行命令的商品。
• 自定义物品 - 完整支持附魔、药水、烟花和自定义模型数据。
• 原生刷怪笼支持 - 配置并出售任何实体类型的刷怪笼。
• 原生玩家头颅支持 - 使用玩家 UUID 或 Base64 皮肤纹理来创建自定义头颅。
• PDC 支持 - 使用 Bukkit 的持久化数据容器 API 进行可靠的物品识别。
• 按物品设置权限 - 将特定物品限制给某些玩家组。
• PlaceholderAPI 支持 - 在商店名称和描述中使用占位符。
• Vault 集成 - 兼容任何支持 Vault 的经济插件。
• 内置经济系统 - 可选的内置经济系统（无需外部经济插件！）。
• 独立出售 GUI - 无需离开商店即可出售物品。
• 交易日志 - 追踪所有购买和出售记录。

🎮命令列表

玩家命令

• /shop, /buy - 打开商店菜单。
• /sell - 打开出售 GUI。
• /value, /val - 检查手持物品的买入/卖出价值。

管理员命令

• /gs reload - 重载所有配置文件。
• /gs edit - 进入主菜单的创造者模式。
• /gs edit menu - 进入主菜单的创造者模式。
• /gs edit transaction - 进入交易 GUI 的创造者模式。
• /gs edit [shop] - 进入指定商店的创造者模式。
• /gs edit [shop] [page] - 编辑商店的指定页面。
• /gs parsemob <type> - 验证用于刷怪笼的生物类型。
• /gs toggleworth - 为你自己切换价值显示（仅限当前会话）。
• /gs iteminfo - 显示手持物品的详细信息。

经济命令

（仅在内置经济启用时可用）

玩家命令：

• /bal, /balance, /money - 查看你的余额。
• /bal <player> - 查看其他玩家的余额。
• /pay <player> <amount> - 向玩家转账。
• /togglepay - 切换付款通知的开关。

管理员命令：

• /gs eco give <player> <amount> - 给予玩家金钱。
• /gs eco take <player> <amount> - 从玩家处扣除金钱。
• /gs eco set <player> <amount> - 设置玩家的余额。
• /gs eco balance <player> - 查看玩家的余额。
• /gs eco reset <player> - 重置为起始余额。

所有金额支持缩写：1k, 1.5M, 100B 等。

物品信息命令

/gs iteminfo 是一个强大的调试和配置辅助命令。手持任意物品并运行此命令，你将看到：

• 材料类型和显示名称。
• 所有描述行。
• 配置就绪格式的附魔（例如：SHARPNESS:5 UNBREAKING:3）。
• 配置就绪格式的药水信息（类型、喷溅、延长、升级）。
• 配置就绪格式的烟花信息（飞行、爆炸、颜色）。
• 所有 PDC（持久化数据容器）值。
• 自定义 NBT 数据。

这使得配置复杂物品变得非常容易——只需创建你想要的物品，然后使用 /gs iteminfo 获取 shops.yml 中所需的精确格式。

🔧权限列表

• guishop.use - 访问商店的权限（默认：op）。
• guishop.shop.* - 访问所有商店物品的权限（默认：op）。
• guishop.shop.<shop>.<item> - 访问特定物品的权限。
• guishop.reload - 重载插件的权限（默认：op）。
• guishop.creator - 访问游戏内商店编辑器的权限（默认：op）。
• guishop.value - 使用 /value 命令的权限（默认：true）。
• guishop.sell - 使用 /sell 命令的权限（默认：true）。
• guishop.admin - 完整的管理员访问权限（默认：op）。

✨配置说明

GUIShop 使用多个配置文件以实现最大灵活性：

• config.yml - 通用插件设置、命令、标题、按钮。
• shops.yml - 商店布局和物品定义。
• menu.yml - 主菜单配置。
• messages.yml - 所有插件消息（完全可自定义）。
• worth.yml - 价值显示系统配置。

示例商店物品配置

shops:
  Blocks:
    pages:
      Page0:
        '0':
          type: SHOP              # 物品类型 (SHOP, COMMAND, SHOP_SHORTCUT, DUMMY, BLANK)
          id: STONE               # 材料 ID
          buy-price: 10.0         # 购买价格（或 'false' 禁用）
          sell-price: 5.0         # 出售价格（或 'false' 禁用）
          shop-name: '&7Stone'    # 商店中的显示名称
          buy-name: '&7Stone'     # 购买后物品的名称
          shop-lore:              # 商店中显示的描述
            - '&fA basic building block'
          enchantments: 'DURA:1 SHARP:2'  # 附魔（空格分隔）
          quantity: 64            # 给予的堆叠数量
          permission: 'shop.vip'  # 所需权限（可选）

⭐GUI 物品编辑器

GUIShop 拥有一个功能强大、完全基于 GUI 的物品编辑器，无需手动编辑配置文件即可配置商店物品的每个方面。

工作原理

• 使用 /gs edit（针对菜单）或 /gs edit <shop>（针对商店）进入创造者模式。
• 左键点击拖拽物品——在商店内移动物品、重新排列位置，或将新物品从你的库存放入商店。
• 右键点击或 Shift+点击 任何物品以打开物品编辑器 GUI。
• 点击任何设置，通过聊天输入或嵌套的选择 GUI 进行修改。
• 关闭库存时，更改会自动保存。

创造者模式控制

• 左键点击 - 拾取/放置物品（可在商店和你的库存之间操作）。
• 右键点击 - 为点击的物品打开物品编辑器。
• Shift+点击 - 为点击的物品打开物品编辑器。
• 导航按钮（分页、返回、余额）：

- **左键点击** - 拾取并移动按钮。

- **右键点击** - 为按钮打开物品编辑器。

- **Shift+点击** - 激活按钮（翻页、返回等）。

物品编辑器功能

• 买入/卖出价格 - 设置价格，支持缩写格式（1k, 1.5M, 100B）。
• 物品类型 - 在 SHOP、COMMAND、SHOP_SHORTCUT 和 DUMMY 类型之间切换。
• 显示名称 - 设置商店显示名称和购买后的物品名称。
• 自定义描述 - 为物品添加描述性文本行。
• 附魔 - 通过可视化附魔选择器添加/移除附魔。
• 药水效果 - 通过 GUI 配置药水类型、持续时间和等级。
• 烟花属性 - 设置飞行时间、爆炸形状、颜色和效果。
• 刷怪笼生物类型 - 从可视化实体选择器中选择生物类型。
• 命令 - 配置购买时运行的命令。
• 权限 - 为每个物品设置所需权限。
• 数量 - 设置购买时给予的堆叠大小。

✨价值显示系统

GUIShop 包含一个强大的价值显示功能，可直接在物品描述中显示物品的出售价值。这使用数据包操作来仅在客户端显示价值，意味着你的实际物品永远不会被修改。

要求： PacketEvents 插件。

价值显示配置 (worth.yml)

enabled: true
format: "&7Worth: &a%worth%"
position: BOTTOM
add-blank-line: true
only-show-sellable: true
not-sellable-format: "&7Worth: &cNot sellable"
# 在特定库存中隐藏价值
blacklisted-inventories:
  - "Auction House"
  - "Crate Preview"
# 隐藏具有特定名称的物品的价值
blacklisted-item-names:
  - "Crate Key"
  - "Vote Token"
# 隐藏已装备盔甲的价值
hide-armor-slots: true

✨高级物品类型

命令物品

出售在购买时执行的命令。使用占位符如 {PLAYER_NAME}、{PLAYER_UUID}、{PLAYER_WORLD} 或任何 PlaceholderAPI 占位符：

'19':
  type: COMMAND
  id: NETHER_STAR
  shop-name: '&6VIP Rank'
  buy-price: 10000
  sudo: false          # 以控制台身份运行（默认）或以玩家身份运行（true）
  commands:
    - 'lp user {PLAYER_NAME} parent set vip'
    - 'broadcast {PLAYER_NAME} purchased VIP!'

可用占位符：

• {PLAYER_NAME} 或 %player_name% - 玩家名称。
• {PLAYER_UUID} 或 %player_uuid% - 玩家 UUID。
• {PLAYER_WORLD} 或 %player_world% - 当前世界。
• {PLAYER_BALANCE} 或 %player_balance% - 经济余额。
• 任何 PlaceholderAPI 占位符（如果安装了 PAPI）。

Sudo 模式： 设置 sudo: true 以玩家身份而非控制台运行命令。适用于需要检查玩家权限或仅限玩家的命令。

附魔书

'20':
  type: SHOP
  id: ENCHANTED_BOOK
  buy-price: 1000
  enchantments: 'SHARP:5 FIRE_ASPECT:2'

药水

使用 potion-info 部分配置药水。支持普通、喷溅和滞留药水。

# 普通药水（延长版速度）
'21':
  type: SHOP
  id: POTION
  buy-price: 500
  potion-info:
    type: SPEED
    splash: false
    lingering: false
    extended: true
    upgraded: false

# 喷溅药水（治疗 II）
'22':
  type: SHOP
  id: SPLASH_POTION
  buy-price: 600
  potion-info:
    type: HEALING
    splash: true
    lingering: false
    extended: false
    upgraded: true

# 滞留药水
'23':
  type: SHOP
  id: LINGERING_POTION
  buy-price: 700
  potion-info:
    type: POISON
    splash: false
    lingering: true
    extended: true
    upgraded: false

药水信息字段：

• type - 药水效果（SPEED, HEALING, STRENGTH, POISON 等）。
• splash - 喷溅药水（true/false）。
• lingering - 滞留药水（true/false）。
• extended - 延长持续时间（true/false）。
• upgraded - II 级/更强效果（true/false）。

刷怪笼

支持任何有效实体类型的原生刷怪笼（使用 /gs parsemob <type> 验证）：

'22':
  type: SHOP
  id: SPAWNER
  buy-price: 50000
  mob-type: ZOMBIE
  shop-name: '&6Zombie Spawner'

烟花

'23':
  type: SHOP
  id: FIREWORK_ROCKET
  buy-price: 100
  firework-info:
    flight: 2
    explosions:
      - shape: ball_large
        flicker: true
        trail: true
        colors: [11743532, 2437522]
        fade-colors: [1973019, 15790320]

玩家头颅

支持玩家 UUID 或 Base64 皮肤纹理

# 使用玩家 UUID
'24':
  type: SHOP
  id: PLAYER_HEAD
  buy-price: 1000
  skull-uuid: 'player-uuid-here'

# 使用 Base64 皮肤纹理（来自 minecraft-heads.com 等）
'25':
  type: SHOP
  id: PLAYER_HEAD
  buy-price: 500
  skull-uuid: 'eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYWJjMTIzIn19fQ=='

✨统计与 PlaceholderAPI

GUIShop 追踪玩家商店统计数据，并与 PlaceholderAPI 集成，可用于记分板、全息图和聊天。

追踪的统计数据

• 总花费金额（从商店购买）。
• 总收入金额（出售物品）。
• 总购买/出售物品数量。
• 每位玩家购买最多的前 3 种物品。
• 每位玩家出售最多的前 3 种物品。

可用占位符

• %guishop_total_spent% - 花费的金额（带逗号）。
• %guishop_total_spent_formatted% - 花费的金额（缩写：1.5M）。
• %guishop_total_earned% - 赚取的金额（带逗号）。
• %guishop_total_earned_formatted% - 赚取的金额（缩写）。
• %guishop_items_bought% - 购买的物品数量。
• %guishop_items_bought_formatted% - 购买的物品数量（缩写）。
• %guishop_items_sold% - 出售的物品数量。
• %guishop_items_sold_formatted% - 出售的物品数量（缩写）。
• %guishop_top_bought_1% - #1 购买最多的物品（材料：数量）。
• %guishop_top_sold_1% - #1 出售最多的物品（材料：数量）。

统计数据存储在 SQLite 数据库 (plugins/GUIShop/Data/player_statistics.db) 中。

✨动态定价系统

GUIShop 包含一个内置的供需经济系统，使物品价格根据交易活动而波动。

工作原理

• 当物品被购买时：供应减少 → 价格上涨。
• 当物品被出售时：供应增加 → 价格下跌。
• 随时间推移：价格逐渐恢复正常基准值。

配置

在 `config.yml` 中启用

dynamic-pricing: true

在 dynamicpricing.yml 中配置：

price-change-per-item: 0.01    # 每件物品 1% 的变化
max-price-multiplier: 2.0      # 最高可达基准价格的 200%
min-price-multiplier: 0.5      # 最低降至基准价格的 50%
normalization-rate: 0.001      # 价格恢复正常的速度
normalization-interval: 300    # 正常化周期之间的秒数

按物品覆盖

为特定物品配置不同的波动性

item-overrides:
  DIAMOND:
    price-change-per-item: 0.005  # 更稳定
    max-price-multiplier: 1.5
    min-price-multiplier: 0.75

关联定价（新功能！）

让物品影响其他物品的价格——非常适合合成关系

item-overrides:
  DIAMOND_BLOCK:
    affects:
      DIAMOND: 9.0           # 1 个方块 = 9 个钻石
      DIAMOND_ORE: 1.0       # 也影响矿石价格
  BREAD:
    affects:
      WHEAT: 3.0             # 1 个面包 = 3 个小麦（合成）

当玩家购买 1 个 DIAMOND_BLOCK 时，DIAMOND 的价格变化如同购买了 9 个钻石。这创造了真实的经济关系！

按物品控制

将特定物品排除在动态定价之外

'0':
  id: DIAMOND
  buy-price: 100
  sell-price: 50
  dynamic: false  # 使用静态定价

管理员命令

• /gs market status - 查看系统状态。
• /gs market info <item> - 检查物品的市场状态。
• /gs market reset <item> - 将物品重置为基准价格。
• /gs market resetall - 重置所有价格。

✨开发者 API

GUIShop 为开发者提供了全面的集成 API。

API 示例

## 简介
GUIShop 是一个强大的 Minecraft 插件，它允许服务器管理员通过一个直观的图形用户界面（GUI）来创建和管理商店。玩家可以轻松地浏览、购买和出售物品，而无需记忆复杂的命令。它支持经济系统（如 Vault）、多种物品类型，并提供了丰富的自定义选项。
## [!] 功能特性
- **直观的 GUI 商店**：玩家通过图形界面与商店交互，体验更佳。
- **购买与出售**：商店可以同时设置物品的购买价格和出售价格。
- **多种经济支持**：原生支持 Vault 经济，可轻松与 EssentialsX、CMI 等插件集成。
- **广泛的物品兼容性**：支持原版物品、自定义模型数据（CustomModelData）物品、头颅、药水、附魔书等。
- **强大的管理命令**：提供完整的命令集来创建、编辑、删除和管理商店。
- **多世界支持**：可以在不同的世界创建独立的商店。
- **自定义选项**：可配置商店标题、物品描述（Lore）、价格显示等。
- **权限控制**：为商店的使用和管理设置详细的权限节点。
- **多语言支持**：内置多种语言文件，方便本地化。
- **更新检查器**：插件会自动检查更新，确保你使用的是最新版本。
## [#] 命令与权限
### 玩家命令
- **`/shop`** - 打开主商店菜单。
- 权限: `guishop.shop`
- **`/shop `** - 直接打开指定的商店。
- 权限: `guishop.shop. `
### 管理员命令
- **`/shopadmin`** 或 **`/sa`** - 打开管理员管理菜单。
- 权限: `guishop.admin`
- **`/shopadmin create `** - 创建一个新的商店。
- **`/shopadmin delete `** - 删除一个商店。
- **`/shopadmin edit `** - 编辑一个商店的设置和物品。
- **`/shopadmin list`** - 列出所有已创建的商店。
- **`/shopadmin reload`** - 重载插件的配置和语言文件。
- 权限: `guishop.admin.reload`
- **`/shopadmin version`** - 检查插件版本。
- 权限: `guishop.admin.version`
## [>] 快速开始
### 安装步骤
1. 确保服务器已安装 **Java 8 或更高版本**。
2. 安装一个经济核心插件，推荐 **Vault** 以及一个与其兼容的经济插件（如 EssentialsX）。
3. 将下载的 `GUIShop.jar` 文件放入服务器的 `plugins` 文件夹。
4. 重启服务器。
5. 根据需要编辑 `plugins/GUIShop/config.yml` 和 `plugins/GUIShop/shops.yml` 文件。
### 创建你的第一个商店
1. 在游戏中，手持你想要在商店中出售的物品。
2. 执行命令 `/shopadmin create 我的商店`。
3. 然后执行 `/shopadmin edit 我的商店` 打开编辑界面。
4. 在编辑界面中，你可以：
- 点击界面中的物品槽位来设置要买卖的物品。
- 设置该物品的购买价和出售价。
- 配置商店的标题和其他选项。
5. 编辑完成后，关闭界面即可保存。玩家现在可以使用 `/shop 我的商店` 来访问它了。
## [+] 依赖
- **必需依赖**
- **[Vault](https://www.spigotmc.org/resources/vault.34315/)** - 用于经济系统和权限挂钩。
- **可选依赖（推荐）**
- 一个与 Vault 兼容的经济插件，例如：
- EssentialsX
- CMI
- Towny
- 一个权限管理插件（如 LuckPerms）以使用高级权限功能。
## [?] 常见问题
- **问：插件支持 1.20.x 版本吗？**
- 答：是的，GUIShop 支持 Minecraft 1.8 到最新版本（如 1.20.x）的 Spigot、Paper 及其衍生服务端。
- **问：如何让商店只对特定玩家组开放？**
- 答：你可以使用权限插件。为商店创建权限节点 `guishop.shop. `，然后只将该权限授予特定的组或玩家。
- **问：我可以出售 spawner（刷怪笼）或玩家头颅吗？**
- 答：是的，GUIShop 支持出售大多数原版和自定义物品。对于刷怪笼，请确保你的服务端版本支持相关物品ID或材质。
- **问：配置出错或商店不显示怎么办？**
- 答：首先尝试使用 `/shopadmin reload` 重载配置。如果问题依旧，请检查服务器日志是否有错误信息，并确保你的 `shops.yml` 文件格式正确。
- **问：如何更新插件？**
- 答：下载新版 JAR 文件，替换服务器 `plugins` 文件夹中的旧文件，然后重启服务器。建议在更新前备份你的 `shops.yml` 配置文件。
## [*] 提示与支持
- 在编辑商店时，你可...