OpShop 插件使用指南

简介
安装与配置
命令速查表
玩家指南：浏览与购买
打开商店
浏览商品与查看详情
购买商品
出售物品
公会商店
管理员指南：商品管理
编辑器概览
创建商品
编辑商品
删除商品
页面管理
公会商品管理
货币系统
货币类型
管理自定义货币
全局默认价格
特殊功能
Placeholder 系统
Trace ID 溯源系统
购买限制
交易日志
权限参考
配置文件参考
PlaceholderAPI 占位符

简介

OpShop 是一个为 Paper 1.20.6+ 服务器设计的商店插件。它提供了：

图形化商店界面 — 无需记命令，点击即可浏览和购买
多货币支持 — Vault 经济、PlayerPoints 点券、自定义物品货币
完整的编辑器 — 可视化创建和编辑商品，支持多管理员同时操作
多语言国际化(i18n) — 完整的中英文支持，所有提示信息均可配置
追溯系统 — 为商品生成唯一追踪 ID，防止物品复制/作弊
Placeholder 支持 — 购买时动态替换物品名称和 Lore 中的占位符
公会集成 — 支持 GuildPlugin，可为每个公会设置专属商店
购买限制 — 支持个人冷却、总限购、玩家限购、库存等多种限制方式
交易日志 — 完整的买卖记录，支持聊天查询和 GUI 浏览

安装与配置

前置插件

插件	必需	说明
Vault	✅	经济系统基础
PlayerPoints	❌	点券货币支持
PlaceholderAPI	❌	物品中的 Placeholder 替换
GuildPlugin	❌	公会商店功能

安装步骤

将 OpShop.jar 放入 plugins/ 目录
重启服务器，生成默认配置文件
编辑 plugins/OpShop/config.yml 配置数据库、货币等
使用 /oshop admin reload 重载配置（或重启服务器）

数据库

OpShop 默认使用 SQLite（plugins/OpShop/database.db），无需额外配置。如需使用 MySQL，修改 config.yml 中的 database 部分即可。

命令速查表

玩家命令

命令	说明
`/oshop`	打开主商店界面
`/oshop open [玩家名]`	为指定玩家打开商店（需管理员权限）
`/oshop guild [公会名]`	打开指定公会的专属商店
`/oshop guild-all`	浏览所有公会商店列表
`/oshop version`	查看插件版本

别名：/shop、/os

管理员命令

所有管理员命令均需要 opshop.admin 权限。

命令	说明
`/oshop admin editor`	打开商品编辑器（列表视图）
`/oshop admin guild [公会名]`	打开指定公会的编辑器
`/oshop admin add <ID>`	手持物品快速创建商品
`/oshop admin delete <ID>`	根据 ID 删除商品
`/oshop admin give <玩家> <ID> <数量>`	发放商品物品给玩家
`/oshop admin reload`	重载配置、语言文件和商品数据
`/oshop admin currency`	查看货币列表与全局默认价格
`/oshop admin currency add <ID>`	将手持物品注册为自定义货币
`/oshop admin currency delete <ID>`	删除自定义物品货币
`/oshop admin currency give <玩家> <ID> [数量]`	发放货币给玩家
`/oshop admin currency take <玩家> <ID> [数量]`	从玩家扣除货币
`/oshop admin currency setglobal <ID> <买价> <卖价>`	设置货币的全局默认价（仅 Vault/PlayerPoints）
`/oshop admin resetlimit <玩家> <ID>`	重置玩家的单商品购买次数限制
`/oshop admin log [player <名>\\|item <ID>] [页码]`	聊天框查看交易日志
`/oshop admin view [player <名>\\|item <ID>]`	GUI 查看交易日志
`/oshop admin trace list item\\|player <值> [页码]`	列出 Trace 记录
`/oshop admin trace log [ID]`	查看 Trace 记录详情（不指定 ID 时读取手持物品）
`/oshop admin trace view [ID]`	GUI 查看 Trace 记录详情

玩家指南：浏览与购买

打开商店

输入 /oshop 或 /shop 即可打开主商店界面：

┌──────────────────────────────────────────┐
│          OpShop - 第 1 页                │
│  ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ...   │
│  │  │ │  │ │  │ │  │ │  │ │  │         │
│  └──┘ └──┘ └──┘ └──┘ └──┘ └──┘         │
│   ...         ...          ...           │
│  [上一页]  [第 1 页]  [下一页]  [关闭]   │
└──────────────────────────────────────────┘

每个商品图标上会显示：

购买价格 — 绿色文字，显示可用的货币类型和单价
出售价格 — 红色文字（如果允许出售）
限购信息 — 剩余库存 / 个人限制 / 冷却时间
公会标记 — 如果是公会专属商品，会显示公会标签

💡 商品图标会实时应用 Placeholder 预览，让你在购买前看到物品名称和 Lore 的最终效果。

浏览商品与查看详情

翻页：点击底部导航栏的「上一页」「下一页」
关闭商店：点击 X 或按 ESC
查看详情：点击任意商品，进入详情界面

详情界面显示：

┌──────────────────────────────────────────┐
│          商品详情                        │
│                                          │
│  [×1]  [×8]  [×64]  ← 购买按钮         │
│                                          │
│       [商品预览图标]                     │
│                                          │
│  [×1]  [×8]  [×64]  ← 出售按钮         │
│                                          │
│  [切换货币]  [返回]  [关闭]             │
└──────────────────────────────────────────┘

左侧按钮：购买（x1 / x8 / x64 三种数量）
右侧按钮：出售（x1 / x8 / x64 三种数量）
底部：切换货币类型 / 返回商店 / 关闭

购买商品

在详情界面点击左侧的购买数量按钮（×1、×8 或 ×64）
系统会按顺序检查：
✅ 你是否有所需权限（如果商品设置了权限要求）
✅ 你是否属于要求的公会（如果是公会专属商品）
✅ 商品是否允许购买
✅ 库存是否充足
✅ 你是否在冷却时间内
✅ 是否达到总限购 / 个人限购
✅ 你的余额是否足够
✅ 你的背包是否有空位
检查通过后，扣除货币，发放物品
购买成功会播放经验球音效，并显示购买确认消息

🔍 Trace ID 商品：如果商品开启了"生成唯一 ID"，购买后物品的 Lore 中会显示一个 Trace ID: #数字 标签。管理员可通过此 ID 追溯到具体的交易记录。

出售物品

在详情界面点击右侧的出售数量按钮（×1、×8 或 ×64）
系统会自动检测你背包和副手中的符合条件物品
扣除物品后，按卖价发放货币
如果开启了"退还额度"（refundLimit），出售同时还会退还你的个人购买限额

⚠️ 注意：带 Placeholder 的自定义物品不可出售回商店，这是为了防止利用容器物品（如潜影盒）进行复制。

公会商店

如果你的服务器安装了 GuildPlugin：

/oshop guild — 打开你自己公会的专属商店
/oshop guild <公会名> — 查看指定公会的商店
/oshop guild-all — 浏览所有有商店的公会列表

公会商店只显示被标记为公会专属的商品，方便公会成员购买内部物品。

管理员指南：商品管理

编辑器概览

输入 /oshop admin editor 打开编辑器列表视图。编辑器支持多管理员同时操作——每个管理员拥有独立的编辑器实例，互不干扰。

┌──────────────────────────────────────────┐
│      商品编辑器 - 第 1 页               │
│  ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ...   │
│  │ A│ │ B│ │  │ │  │ │  │ │  │         │
│  └──┘ └──┘ └──┘ └──┘ └──┘ └──┘         │
│   ...         ...          ...           │
│  [上一页][前插页][后插页][重载][下一页]   │
│            [删除页面]  [退出]            │
└──────────────────────────────────────────┘

操作说明：

操作	方式
点击商品	进入编辑界面
Shift + 右键	快速删除商品
将物品拖放到空格	快速创建商品（自动以物品名称作为 ID）
底部导航	翻页、插入/删除页面、重载数据

创建商品

方法一：快速创建命令

手持你要上架的商品，执行：

/oshop admin add <商品ID>

商品会自动分配到第一个空位，并应用全局默认价格。

方法二：编辑器拖放

打开编辑器（/oshop admin editor）
将背包中的物品直接拖放到商店界面的空格中
系统自动以物品展示名称作为 ID（如有重名会追加 _2、_3...）

方法三：编辑器中替换

点击已有商品进入编辑界面
将新物品拖放到编辑界面的物品槽（第 13 格）
点击「保存」

编辑商品

在列表视图中点击任意商品，进入编辑界面：

┌──────────────────────────────────────────┐
│       编辑: 商品ID                       │
│                                          │
│  [物品]  ← 拖放替换                      │
│                                          │
│  买/卖: [✓] / [✓]  占位符: [ ]  溯源: [ ]│
│  退款: [✓]         权限: [无]            │
│                                          │
│  Vault购买价:  [L -1][100][R +1]         │
│  Vault出售价:  [L -1][50 ][R +1]         │
│  PP购买价:     [L -1][10 ][R +1]         │
│  PP出售价:     [L -1][5  ][R +1]         │
│  自定义购买价: [L -1][20 ][R +1]         │
│  自定义出售价: [L -1][10 ][R +1]         │
│  自定义货币:    [点击切换]               │
│                                          │
│  总限制:   [L -1][100][R +1] [Q=无限]    │
│  单人限制:[L -1][10 ][R +1] [Q=无限]     │
│  冷却:     [L -1][30s ][R +1]            │
│  库存:     [L -1][-1  ][R +1]            │
│                                          │
│  [获取物品][日志][保存][删除] [返回]      │
└──────────────────────────────────────────┘

价格调整快捷键：
  左键：±1    右键：Shift+左键？不，是 右键=-1
  Shift+左键：+10    Shift+右键：-10
  Q键：+100    Ctrl+Q：-100
  Q键(限制类)：设为无限/无限制

编辑选项说明

选项	说明
允许购买	玩家是否可以购买此商品
允许出售	玩家是否可以将物品卖回商店
Placeholder	开启后物品中的占位符会在购买时替换
溯源 ID	为每次购买生成唯一 Trace ID（开启后强制关闭出售）
退还额度	开启后玩家出售物品会退还购买限额
权限要求	设置购买此商品需要的权限节点
6 个价格字段	分别为 Vault 买/卖、PlayerPoints 买/卖、自定义货币买/卖
自定义货币	点击切换可用的自定义物品货币
总限制	此商品全局最多可被购买多少次（-1 = 无限）
单人限制	每个玩家最多购买多少次（-1 = 无限）
冷却时间	玩家两次购买之间的冷却秒数
库存	当前库存数量（-1 = 无限）

⚙️ 重要：开启 Placeholder 或溯源 ID 功能会强制关闭出售，因为自定物品无法匹配回购。

删除商品

快速删除：在列表视图中 Shift + 右键点击商品
编辑界面删除：点击「删除」按钮，需要再次点击确认（防误触）

页面管理

编辑器底部提供页面管理功能：

按钮	功能
前插页	在当前页之前插入一个空白页
后插页	在当前页之后插入一个空白页
删除页面	Shift + 点击确认删除当前页（该页商品会移到前一页）
重载	从数据库重新加载所有商品

每页最多 45 个商品（6 行 × 9 格，减去第 6 行导航栏占用的 9 格）。

公会商品管理

如果服务器安装了 GuildPlugin：

/oshop admin guild <公会名>

这会打开该公会的专属编辑器。在此模式下创建的商品会自动设置 guildRestrictionEnabled=true 并将该公会加入白名单。公会商品只在对应公会的商店中显示。

你也可以在普通编辑器中手动编辑商品的公会白名单，使其对多个公会可见。

货币系统

货币类型

OpShop 支持三种货币类型：

类型	标识	前置	说明
Vault 经济	`VAULT`	Vault	服务器经济货币（如金币）
PlayerPoints	`PLAYER_POINTS`	PlayerPoints	点券/积分系统
自定义物品	`CUSTOM_ITEM`	无	以特定物品作为交易媒介

管理自定义货币

注册自定义物品货币

手持你要用作货币的物品，执行：

/oshop admin currency add <货币ID>

物品会被序列化并存入数据库。以后玩家购买时，系统会检测背包中是否有完全匹配的物品。

💡 Tab 补全提示：注册货币时，tab 补全会自动读取手持物品的展示名称（或物品类型的格式化名称，如 diamond sword），方便快速输入 ID。

🔧 特殊物品兼容：如果货币物品带有 !minecraft:lore 数据组件（显式隐藏了 lore），插件在 GUI 中显示货币图标时会自动修复 lore 组件，确保价格标签正确显示。原始物品不会被修改，玩家仍可正常交易。

删除自定义货币

/oshop admin currency delete <货币ID>

查看货币

/oshop admin currency

显示所有已注册货币及其全局默认价格。

发放/扣除货币

/oshop admin currency give <玩家> <货币ID> [数量]
/oshop admin currency take <玩家> <货币ID> [数量]

此命令适用于所有货币类型（Vault、PlayerPoints、自定义物品均可）。

全局默认价格

你可以为 Vault 和 PlayerPoints 货币设置全局默认价格。新建商品时，这些价格会自动填写。

/oshop admin currency setglobal <货币ID> <买价> <卖价>

例如：

/oshop admin currency setglobal vault_main 100 50

这样所有新商品默认买价 100、卖价 50（均使用 Vault 货币）。

📝 自定义物品货币不支持全局默认价格，需在每个商品编辑界面中单独设置。

特殊功能

Placeholder 系统

开启 Placeholder 功能后，物品的名称和 Lore 中的占位符会在玩家购买时动态替换。

内置占位符

占位符	替换为
`%buyer_name%`	购买者名称
`%buyer_uuid%`	购买者 UUID
`%date%`	购买日期（yyyy-MM-dd）
`%time%`	购买时间（HHss）
`%player_level%`	购买者等级
`%player_world%`	购买者所在世界名
`%player_health%`	购买者生命值
`%player_food%`	购买者饥饿值
`%player_gamemode%`	购买者游戏模式
`%server_online%`	服务器在线人数
`%server_max%`	服务器最大人数
`%generated_id%`	Trace ID（需同时开启溯源功能）
`%guild_name%`	购买者公会名（需 GuildPlugin）
`%guild_tag%`	购买者公会标签（需 GuildPlugin）

PlaceholderAPI 扩展

如果安装了 PlaceholderAPI，可以使用 %papi_<扩展名>_<参数>% 格式，例如：

%papi_player_name%
%papi_server_tps%

使用方法

在编辑器中将物品的 Name 或 Lore 设为包含占位符，例如：
物品名称: &6专属剑 - %buyer_name%
Lore 第一行: &7购买日期: %date% %time%
Lore 第二行: &7购买者: %buyer_uuid%
编辑器中开启「Placeholder」开关
玩家购买后，占位符会被替换为实际值

✨ 编辑器会实时预览占位符替换效果（部分需要购买上下文的占位符显示为 ???）。

Trace ID 溯源系统

Trace ID 是 OpShop 的核心防作弊功能。开启后，每次购买都会在物品上烙下一个唯一的数字 ID。

开启溯源

在商品编辑界面中开启「溯源 ID」开关。此操作会： - 自动关闭「允许出售」（溯源物品不可卖回） - 限制玩家只能 x1 批量购买 - 购买时先生成交易记录，再将 ID 写入物品 PDC

查询溯源

按玩家或物品列出记录：

/oshop admin trace list player <玩家名> [页码]
/oshop admin trace list item <商品ID> [页码]

查看详情（聊天框）：

/oshop admin trace log [ID]

不指定 ID 时，自动读取手中物品的 Trace ID。

查看详情（GUI）：

/oshop admin trace view [ID]

每件溯源物品的 Lore 中也会显示 Trace ID: #数字，管理员可据此追踪物品来源。

购买限制

OpShop 支持多层级的购买限制，组合使用可实现丰富的经济玩法：

限制类型	配置项	说明
全局总限制	totalLimit	所有玩家对该商品的总购买次数上限
单人限制	playerLimit	每个玩家对该商品的购买次数上限
冷却时间	cooldown	玩家两次购买之间的间隔（秒）
库存	stock/maxStock	当前库存/最大库存，-1 为无限

重置单人限制

/oshop admin resetlimit <玩家名> <商品ID>

📝 支持离线玩家，同时会退还全局已售计数器。

交易日志

所有买卖交易都会被记录到数据库中。

聊天框查看

/oshop admin log                          # 查看全部日志，第 1 页
/oshop admin log 2                        # 第 2 页
/oshop admin log player Choo              # 按玩家筛选
/oshop admin log item diamond_sword       # 按商品筛选
/oshop admin log player Choo 2            # 按玩家筛选，第 2 页

每页显示 10 条记录，包含：时间、玩家、商品ID、交易类型(购买/出售)、货币、单价、数量、总价。

GUI 查看

/oshop admin view                          # GUI 查看全部日志
/oshop admin view player Choo              # GUI 按玩家筛选
/oshop admin view item diamond_sword       # GUI 按商品筛选

GUI 模式下支持翻页浏览，每条记录以图标形式展示，点击可查看包含物品截图的详细信息。

权限参考

权限节点	默认	说明
`opshop.use`	所有人	打开商店、查看、购买、出售
`opshop.admin`	OP	所有管理操作（继承 `opshop.use`）
`opshop.admin.editor`	OP	打开商品编辑器
`opshop.admin.currency`	OP	管理货币和全局默认价格
`opshop.admin.logs`	OP	查看交易日志和溯源记录

📝 每个商品还可以在编辑器中设置单独的 permission_required，用于 VIP 专属商品等场景。

配置文件参考

配置文件位于 plugins/OpShop/config.yml：

# 数据库配置
database:
  type: sqlite              # sqlite 或 mysql
  host: localhost           # MySQL 主机（仅 MySQL）
  port: 3306                # MySQL 端口
  database: opshop          # 数据库名
  user: root                # 用户名
  password: password        # 密码
  pool-size: 10             # HikariCP 连接池大小

# 全局默认价格（新建商品时自动填入）
global-defaults:
  prices:
    - currency: vault_main     # 货币 ID
      buy-price: 100.0         # 默认买价
      sell-price: 50.0         # 默认卖价
    - currency: pp_tokens
      buy-price: 10.0
      sell-price: 5.0

# 货币定义
currencies:
  vault_main:
    type: vault
  pp_tokens:
    type: player_points
  custom_gem:
    type: custom_item
    material: DIAMOND
    name: "&b宝石"
    lore:
      - "&7一种闪亮的货币"
    custom-model-data: 10001

# GUI 设置
gui:
  title: "&6服务器商店"
  rows: 6
  items-per-page: 45
  filler-material: GRAY_STAINED_GLASS_PANE

# 语言（支持 en / zh_CN，亦可在 plugins/OpShop/lang/ 目录放置自定义语言文件）
locale: zh_CN

# 调试
debug: false

PlaceholderAPI 占位符

如果安装了 PlaceholderAPI，以下占位符可用：

占位符	说明
`%opshop_currency_<货币ID>%`	玩家的该货币余额（格式化后）
`%opshop_currency_<货币ID>_name%`	货币的显示名称
`%opshop_item_count%`	商店中商品总数

示例：

你的金币余额: %opshop_currency_vault_main%
你的宝石数量: %opshop_currency_custom_gem%
商店共有 %opshop_item_count% 件商品

📖 本指南适用于 OpShop 插件。如有问题或建议，请联系插件作者。

最近更新 (v2.0)

🛡️ 数据安全修复

SQLite 兼容性修复：修复了出售启用 refundLimit 物品时 SQLite 数据库抛出异常的问题（MAX() 不兼容）。现在 MySQL 使用 GREATEST() 优化，SQLite 使用安全的应用层计算
删除清理：删除商品时会同时清理 shop_item_prices 和 player_purchases 关联数据，避免孤儿行积累
Trace ID 失败保护：如果 trace ID 插入数据库失败，交易会自动回滚并退还货币

🌐 国际化 (i18n) 完善

所有命令反馈消息（30+ 条）现在完整支持中英文，不再出现硬编码英文
所有编辑器操作提示（25+ 条）全部纳入 i18n 系统
出售界面数量标签修正：中文"包" → "个"
新增约 40 个翻译 key，覆盖全部界面反馈

✨ 功能改进

多管理员编辑器：编辑器从全局单例改为按玩家实例化，多个管理员可以同时打开编辑器互不干扰
货币名称 Tab 补全：/oshop admin currency add 的 tab 补全现在显示人类可读名称（diamond sword 而非 DIAMOND_SWORD）
!minecraft:lore 物品处理：带有 !minecraft:lore 数据组件（显式移除 lore）的物品作为货币时，GUI 中的价格标签和状态提示现在能正确显示，且不修改原始物品
内存优化：玩家退出时自动清理冷却缓存和编辑器实例

🔧 技术改进

交易日志：GUI 模式下内存限制从 500 条提升至 1000 条，带截断检测
编辑界面：返回按钮新增描述文字，操作更直观
ShopItem：补充了 getDisplayItem() 和 getProductItem() 的 Javadoc 说明