SoulAuction

插件

· 作者 b0b0b0

全服统一拍卖行:多店铺、任意经济系统、支持 Folia,并提供交易保护。

0 本站下载 0 关注 更新于 2 周前

最新 2.3.0 · 26.3 · Folia

一键开服(送7天)

SoulAuction

全服统一的拍卖行:多商店、任意经济系统、支持 Folia 以及交易保护 —— 无 Fat-jar,杜绝点击复制漏洞。

SoulAuction 是一款适用于 Paper 1.21+ 和 Folia 的拍卖插件,专为需要确保经济逻辑在区域线程隔离下正常运行、且无法容忍代理层重复购买的网络而设计。

单个 JAR 文件:依赖项通过 Paper libraries 加载,无需阴影打包(shade)。与其他插件冲突更少,更新更便捷。

管理员为何选择它

一个插件内集成多个拍卖行 —— 普通、VIP、活动、捐赠货币等均可独立设置。每个拍卖行拥有独立的经济学派(Vault、PlayerPoints、经验值、CoinsEngine、物品)、权限组和规则。无需部署三个单独的 AH 插件,也无需维护复杂的同步集群。

原生支持 Folia —— 感知区域的线程处理,热点路径上不使用旧版调度器。对于已经使用 Folia 或正在迁移的网络而言,这是基础要求,而非锦上添花的功能。

跨服务器支持 —— 共享 MySQL + Redis:全服目录统一,买卖操作采用分布式锁,数据库中的列表状态转换保证原子性。发布/订阅机制刷新商店界面;SQL 才是唯一真理来源,而非“最后写入文件者”。

为玩家提供完善的拍卖体验: GUI 界面、分类、排序、搜索与筛选、收藏卖家、“我的列表 / 领取 / 历史”中心。消息使用 MiniMessage 格式,支持 HEX 颜色和渐变;文本存储在 lang/messages_*.yml 中。

经济系统受控: 卖家和买家税费、通过权限绕过或享受折扣、按等级限制槽位、冷却时间、黑名单、世界禁令、物品白名单/黑名单、针对 ItemsAdder / Oraxen / MMOItems 的规则。列表有效期(TTL);如果背包已满,物品将转入待领取状态,而非直接消失。

运维功能: 交易历史、审计日志、管理员 GUI、清理数据、领取恢复、Discord/Telegram 交易通知(异步 HTTP,无需在 Minecraft 服务器上运行机器人)。/ah reload 命令可重新加载配置和消息文件。

适用场景: 具有多种游戏模式和货币的 Paper/Folia 网络、跨代理共享拍卖、对防复制有较高要求的网络。

网络与反复制(简略说明)

模式 用途
JSON / YAML 单服务器,快速启动
SQLITE / MYSQL 持久化存储;MYSQL 是代理层的基础
Redis + pub/sub 跨实例锁 + 目录缓存失效

在代理环境下:必须启用 MYSQL + redis.enabled。买入/取消/过期等操作均通过列表认领机制进行(锁 + Redis NX + UPDATE … WHERE status='ACTIVE'),若支付失败或背包满则回滚。卖出: 物品在 GUI 中以托管形式暂存;库存列表在写入数据库前执行严格移除(使用 /ah sell,禁止不消耗物品的克隆行为)。

功能特性

  • 多拍卖行支持,分别设置 open / buy / sell 权限。
  • 经济系统支持:VAULT、PLAYER_POINTS、EXPERIENCE、COINS_ENGINE、ITEM。
  • 存储方式:JSON、YAML、SQLITE、MYSQL。
  • 列表有效期(TTL,定时或无限期)、认领机制、到期时通知卖家、各拍卖行独立手续费、已售/已取消/已过期历史记录。
  • 列表数量限制:soulauction.<auctionId>.<N>、soulauction.all.<N>。
  • 排序优先级:soulauction.priority.<N>。
  • 大额交易广播、外部通知(Discord/Telegram)。
  • 卖出 GUI: 数量 ±1,从库存中提取匹配的物品(最多至最大堆叠数);通过完整序列化(NBT、名称、附魔)进行比较,而非简单的“相似”堆叠。确认前物品处于托管状态 —— 取消或关闭时返还。
  • 各拍卖行独立的价格显示: 自定义货币符号,支持前置/后置数字,MiniMessage 格式及可选的 PlaceholderAPI 支持(用于资源包 / ItemsAdder 图标等)。
  • 虚假活跃度: 基于昵称/物品池生成合成列表,可按拍卖行启用;定时器补充、手动执行 /ah admin fake、在管理员 GUI 中切换开关。
  • 卖家皮肤: 通过 SkinsRestorer / Mojang 在“收藏卖家”中显示头像;支持 fallback 机制,并为所有虚假卖家提供统一皮肤(服务器 Logo)。

价格显示(auctions/*.yml)

每个拍卖行都有各自的字段(默认值位于 Java 代码中;首次启动后生成于 plugins/SoulAuction/auctions/global.yml 及其他文件中):

字段 用途
currencySymbol GUI 和聊天中显示的符号或图标。留空则使用经济系统默认值(Vault $、PlayerPoints PP、物品 Nx MATERIAL)。
currencySymbolPosition 符号相对于金额的位置:BEFORE 或 AFTER(例如 $100 或 100 ₽)。
currencySymbolPlaceholderApi true —— 为查看者解析 PlaceholderAPI 的 %...% 变量(需安装 PlaceholderAPI)。
listingTtlSeconds 列表有效期(秒);0 或负数表示永不过期。

列表有效期与认领机制

  • 当列表状态为 ACTIVE 时,浏览器和“我的列表”(若启用了 TTL)会在描述 lore 中显示剩余时间 / 到期时间;打开的浏览器每秒刷新一次计时器。
  • 已过期未售出: 列表被移除(状态变为 EXPIRED),物品进入待领取队列(仅一次,写入 claims.json),不会凭空消失。
  • 卖家通知: 在线时立即发送聊天消息,离线时在登录时发送,包含到期提示及 [在菜单中领取] → /ah expired [auctionId];物品领取指令为 /ah claim(过期菜单仅可查看,槽位不可编辑)。
  • 列表成功上架: 多行聊天消息 —— 显示物品、数量、价格、所属拍卖行;定时与无限期上架分别对应不同的消息块(success-listed、success-listed-expiry-timed / success-listed-expiry-unlimited,位于 lang/messages_*.yml 中)。
  • 单进程模式下:锁定 listingId 及 SQL 操作,ACTIVE → EXPIRED/SOLD/CANCELLED 的状态转换是原子的;在物品交付到库存之前,先从缓冲区移除认领记录。

currencySymbol 示例:

  • 文本:₽、coins、gems
  • MiniMessage / 字形:<glyph:coin>(ItemsAdder、Nexo 等 —— 具体请参考各资源包文档)
  • PAPI(需配合 currencySymbolPlaceholderApi: true):%img_economy%

自定义符号价格会出现在所有位置:GUI 列表、卖出菜单、价格过滤器、购买界面、历史记录、聊天消息(如 success-bought、公告等)。

消息文件(plugins/SoulAuction/lang/)

  • prefix — 所有 {prefix} 字符串的前缀。
  • 键使用 MiniMessage;{price} 已针对玩家正在查看的拍卖进行了格式化。
  • 多行聊天: 键作为字符串的 YAML 列表 —— 插件会单独发送每一行(MessageService.send)。单个字符串则如前所述。聊天搜索、出售成功、过期、命令用法 —— 均使用此格式。
  • GUI 中的商品描述占位符:{seller}、{price}、{id}、{auction}、{expires_in}、{expires_at}(启用 TTL 时);可在 auctions/*.yml 中使用可选的 listingLoreTemplate。

PlaceholderAPI

当存在 PlaceholderAPI 时,扩展会自动注册。标识符为 soulauction,即 %soulauction_<param>%。数字会根据玩家的区域设置进行格式化(千位分隔符)。任何占位符都有一个 _raw 后缀变体 —— 未格式化的值(例如 1500000 而不是 1,500,000,枚举键而不是语言名称),用于记分板和需要原始数字的插件。

计数器

占位符 值
%soulauction_active_count% 玩家的活动商品数量(别名:sell_count、purchasable_count)
%soulauction_expired_count% 玩家已过期的物品(原因标记为 EXPIRED 的认领记录)
%soulauction_total_active_count% 拍卖行中的所有商品
%soulauction_sell_limit% 玩家的全球上架限制(权限 + 覆盖)
%soulauction_claims% 领地中所有属于玩家的物品
%soulauction_listings_all% / %soulauction_listings_<auctionId>% 玩家的活动商品(全部 / 特定拍卖行)
%soulauction_listings_total% 所有商品(未格式化,遗留功能)

玩家设置

占位符 值
%soulauction_selected_sorting% 选定的排序方式
%soulauction_selected_category% 选定的分类
%soulauction_selected_currency% 上次打开的拍卖行的货币(来自语言的 currency-*)
%soulauction_categories_enabled%、%soulauction_expired_items_enabled%、%soulauction_auction_listing_confirmation_enabled% 始终为 true —— SoulAuction 中无法禁用这些系统

交易统计

持久化存储于 (data/stats.json);首次运行时从现有历史记录播种一次。<currency> 是经济类型:vault、player_points、experience、coins_engine、item。

占位符 值
%soulauction_items_sold% 玩家售出的物品
%soulauction_items_purchased% 玩家购买的物品
%soulauction_money_made% 玩家赚取的资金(税后)
%soulauction_money_spent% 玩家花费的资金(含买家税)
%soulauction_items_sold_<currency>% 及类似项 同上,按货币分类
%soulauction_total_items_sold%、%soulauction_total_money_made% 等 全服务器范围,包括 _<currency>

虚假活动

合成商品使商店保持繁忙状态:从池中随机选取昵称、随机物品、范围内的随机价格。这些不是真实玩家 —— 购买行为如同正常商品一样运作(消耗资金,交付物品)。在虚假商品被购买后,插件可能会在延迟后列出另一个商品。

按拍卖行启用

config.yml 中没有全局开关 —— 仅支持按拍卖行配置:

位置 字段 / 操作
auctions/<id>.yml fake-activity-enabled: true / false(默认 false)
/ah admin → 右键点击某个拍卖行 虚假活动菜单
菜单 → 槽位 22 切换(LIME_DYE / RED_DYE)→ auctions/<id>.yml
菜单 → 槽位 49 池、限制、计时器(只读)

auctions/global.yml 中的示例:

fake-activity-enabled: true

池 (plugins/SoulAuction/fake-activity/)

路径:config.yml → fake-activity.directory(默认 fake-activity)。首次启动时会创建三个文件:

文件 内容
settings.yml 计时器、限制、默认价格、admin-fake
sellers.yml 卖家显示名称(最多 16 个字符)
items.yml 物品池,包含权重和价格范围

全新安装自带约 120 个昵称和约 120 种原版物品(矿石、食物、工具、1.21 稀有物品)—— 可随时在 YAML 中编辑。

settings.yml(主要字段)

字段 用途
initial-fill-listings 启动时创建的商品数量(0 = 达到 max-total-listings)
initial-delay-seconds 第一次补充计时器之前的延迟
tick-interval-seconds 多久向上限补充一次
after-purchase-delay-seconds 虚假购买后,同一卖家再次上架前的延迟
min-price / max-price 当 items.yml 中的物品 min/max = 0 时的默认范围
price-variance-percent 选定价格的随机 ±% 波动
max-listings-per-auction 每个 auctionId 的虚假上限
max-total-listings 全服务器的虚假上限
listing-age-spread-seconds 创建时的随机商品年龄(变化的 TTL 计时器)
listings-per-tick 每次计时器尝试创建的商品数量
auction-ids 仅限这些拍卖行([] = 所有带有 fake-activity-enabled 的拍卖行)
admin-fake.register-seller 执行 /ah admin fake 后,将昵称追加到 sellers.yml
admin-fake.register-item 执行 /ah admin fake 后,将手持物品追加到 items.yml

items.yml 条目字段

  • id — 供您自己识别的标签
  • material / amount — 原版堆叠(设置 item-base64 时忽略)
  • item-base64 — 完整的物品快照(NBT、自定义物品)
  • min-price / max-price — 0 = 取自 settings.yml
  • auction-ids — 空 = 任意拍卖行;否则仅限列出的 ID
  • weight — 相对抽取几率(越高越常出现)

手动虚假上架

/ah admin fake <nick> <auctionId> <price>

物品必须位于主手。商品会立即作为合成商品创建。启用 admin-fake.* 后,昵称和/或物品会异步追加到池中。

行为

  • 伪造条目在排序、搜索和过滤器中会像正常条目一样显示。
  • 只有拥有 soulauction.command.cancel.any 权限的管理员才能使用 /ah cancel 取消它们(卖家是合成 UUID)。
  • 在使用 MySQL+Redis 的代理服务器上,伪造条目会像其他任何条目一样同步。

卖家皮肤 (config.yml → seller-skins)

“喜爱卖家” GUI(大厅 → 星标)中卖家头颅的材质贴图。浏览器列表页显示的是物品本身,而非头颅。

SkinsRestorer 是一个软依赖;在离线/破解服务器上,如果没有它,通过昵称查找 Mojang 资料通常会失败。

source

值 行为
auto 如果安装了 SkinsRestorer 则使用它;否则使用 Mojang API
skins-restorer 仅使用 SkinsRestorer
mojang 仅使用 Mojang(在线模式,真实昵称)
off 默认使用 Steve/Alex 头颅,不执行查找

fallback-skin 和 fake-seller-skin

seller-skins:
  source: skins-restorer
  fallback-skin: "DefaultHead"
  fake-seller-skin: "ServerLogo"
字段 适用场景
fallback-skin 当卖家昵称查找失败时 → SR 解析此自定义皮肤 / 昵称 / URL
fake-seller-skin 所有合成/伪造卖家均使用此皮肤;忽略昵称

值为 SkinsRestorer 的皮肤名称(例如 /sr set skin ServerLogo <url> 等)。

查找链 (SkinsRestorer)

  1. findOrCreateSkinData(nick) — 或者当卖家为合成且设置了字段时使用 fake-seller-skin
  2. findSkinData(fallback-skin) — 当配置了回退皮肤时
  3. getSkinForPlayer(uuid, nick) — 来自 SkinsRestorer 配置的 SR defaultSkins

当 source: mojang 时,回退机制通过名称使用 Mojang API。

启动预热

异步预取至 SkinsRestorer 缓存(请求间约暂停 100 毫秒):

  • 如果设置了 fake-seller-skin — 预热该皮肤(以及设置了时的 fallback-skin);
  • 否则 — 预热所有假池昵称 + fallback-skin。

控制台输出:SkinsRestorer — prefetched X/Y fake seller skins。

GUI 查找是异步的;当材质到达时头颅会更新(SoulAuction 中没有内存缓存)。

管理员 GUI

/ah admin 或 /ah admin gui [page] — 需要 soulauction.command.admin 权限或 OP。

操作 结果
左键点击拍卖 以玩家身份打开商店页面
右键点击拍卖 打开伪造活动菜单
第 22 槽位 切换伪造活动(羊毛)
第 49 槽位 池、限制、刻数(只读)
第 45 槽位 返回拍卖列表
底行的书 创建新拍卖(聊天向导)

命令

玩家

  • /ah — 打开默认拍卖行。
  • /ah <auctionId> — 打开特定拍卖行。
  • /ah sell <price> — 将手中的物品列在默认拍卖行。
  • /ah sell <auctionId> <price> — 将物品列在选定的拍卖行。
  • /ah sell <price> <auctionId> — 另一种参数顺序。
  • /ah my [auctionId] — 显示你当前的在售商品。
  • /ah selling [auctionId] — 当前在售商品 GUI。
  • /ah expired [auctionId] — 过期物品 GUI(领取)。
  • /ah purchased [auctionId] — 购买历史 GUI。
  • /ah history [auctionId] — 销售历史 GUI。
  • /ah search <text> — 搜索:关闭 GUI,在聊天中提示输入(消息中包含取消按钮);输入后 — 刷新浏览器并在聊天中显示结果。
  • /ah search <auctionId> <text> — 针对特定拍卖行的相同功能。
  • /ah search cancel — 取消搜索并返回拍卖行。
  • /ah page <number> [auctionId] — 打开特定拍卖行的第几页。
  • /ah claim [all] — 领取过期/已取消的物品。
  • /ah cancel <id> — 移除你的出售记录并归还物品。
  • 命令别名在 config.yml 中通过 commandAliases 配置(例如 ax、auction)。

管理员

  • /ah reload — 重新加载配置和消息文件。
  • /ah purge <days> — 清理 N 天前的交易历史记录。
  • /ah admin history <player> [limit] — 在聊天中显示玩家历史。
  • /ah admin selling <player> [auctionId] — 玩家的当前在售商品 GUI。
  • /ah admin blacklist add|remove <player> — 运行时出售黑名单。
  • /ah admin recover <claimId> — 将领取权交付到背包。
  • /ah admin audit [limit] — 最近的审计条目。
  • /ah admin cache stats|rebuild|invalidate — 目录缓存。
  • /ah admin sellfor <player> <auctionId> <price> — 代替玩家上架物品(手中物品)。
  • /ah admin fake <nick> <auctionId> <price> — 以给定昵称为名的合成上架记录(手中物品;参见伪造活动)。
  • /ah admin gui [page] — 拍卖列表 GUI(右键点击拍卖可查看伪造活动)。
  • /ah admin parse tags|nbt — 解析手中物品的 NBT/标签(自定义物品)。
  • /ah view <player> [auctionId] — 玩家的出售记录 GUI。

权限

基本权限

  • soulauction.command.ah — 使用 /ah。
  • soulauction.command.sell — 使用 /ah sell。
  • soulauction.command.reload — 使用 /ah reload。
  • soulauction.command.admin — 管理员命令及清理功能。
  • soulauction.priority.10 — 更高的上架排序优先级(任意 N)。
  • soulauction.command.my — 使用 /ah my。
  • soulauction.command.claim — 使用 /ah claim。
  • soulauction.command.cancel.any — 通过 /ah cancel 移除他人的上架记录。

按拍卖行设置(在 config.yml 中)

每个拍卖行都有独立的节点:

  • openPermission — 打开此拍卖行。
  • buyPermission — 购买此拍卖行中的上架记录。
  • sellPermission — 在此拍卖行中出售。

示例:

  • soulauction.open.vip
  • soulauction.buy.vip
  • soulauction.sell.vip

动态上架限制

  • soulauction.<auctionId>.1 — 此拍卖行限制 1 个活跃上架记录。
  • soulauction.<auctionId>.5 — 此拍卖行限制 5 个活跃上架记录。
  • soulauction.all.1 — 跨所有拍卖行的全局限制为 1。
  • soulauction.all.5 — 跨所有拍卖行的全局限制为 5。

如果授予多个节点,则应用最高的限制。 如果未授予任何节点,则使用 limits 中的默认值。

税费

  • soulauction.tax.bypass — 无销售或购买税。
  • soulauction.tax.discount.<percent> — 销售税折扣(取最高者)。

在 auctions/*.yml 中:saleTaxPercent(来自卖家),buyTaxPercent(来自买家)。

价格界限

  • 全局设置:config.yml 中的 limits.minPrice 和 limits.maxPrice。
  • 每个拍卖独立设置:minPrice、maxPrice(设为 0 则使用全局设置)。
  • soulauction.price.min.<price> —— 玩家上架的最低价格权限。
  • soulauction.price.max.<price> —— 玩家上架的最高价格权限。

Discord 和 Telegram

在 config.yml 的 notifications 部分中配置:

  • Discord: notifications.discord.enabled、webhookUrl(频道 Incoming Webhook)。
  • Telegram: notifications.telegram.enabled、botToken、chatId。
  • 事件类型:notify-sold(售出通知)、notify-listed(上架通知)、notify-expired(过期通知)、min-price(最低价过滤)。
  • 消息发送为异步执行(基于 Java HTTP),无需 Shade 打包,也不需要在 Minecraft 服务器端运行机器人。
  • Discord 中的玩家头像: 通过 notifications.discord.show-player-avatars 控制(卖家头像显示在作者栏,买家缩略图显示在交易详情中)。CDN 头像源由 avatar-provider 指定,默认为 MINOTAR,也可设置为 CRAFATAR。

执行 /ah reload 后,新的 URL 和标志位将立即生效。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源