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)
findOrCreateSkinData(nick) — 或者当卖家为合成且设置了字段时使用 fake-seller-skin
findSkinData(fallback-skin) — 当配置了回退皮肤时
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 和标志位将立即生效。
SoulAuction
One auction house for the whole network: multiple storefronts, any economy, Folia, and trade protection — no fat-jar, no click dupes.
SoulAuction is an auction plugin for Paper 1.21+ and Folia, built for when economy logic must survive region threading and double-purchase on a proxy is unacceptable.
Single JAR: dependencies via Paper libraries, no shade. Fewer conflicts with other plugins and easier updates.
Why admins choose it
Multiple auction houses in one plugin — regular, VIP, event, donation-currency, and more. Each has its own economy (Vault, PlayerPoints, experience, CoinsEngine, items), permissions, and rules. Not three separate AH plugins and not a sync zoo.
Folia first-class — region-aware threading, no legacy scheduler on hot paths. For networks already on Folia or migrating, this is baseline, not a nice extra.
Multi-server — shared MySQL + Redis: one catalog across the network, distributed locks for buy/sell, atomic listing state transitions in the database. Pub/sub refreshes the storefront; SQL is the source of truth, not “whoever wrote the file last”.
Players get a proper AH: GUI, categories, sorting, search and filters, favorite sellers, hub for “my listings / claim / history”. Messages use MiniMessage, HEX, gradients; texts live in lang/messages_*.yml.
Economy under control: seller and buyer taxes, bypass/discount via permissions, slot limits by rank, cooldowns, blacklist, world bans, item whitelist/blacklist, rules for ItemsAdder / Oraxen / MMOItems. Listing TTL; if inventory is full, items go to claim, not the void.
Operations: deal history, audit log, admin GUI, purge, claim recovery, Discord/Telegram deal notifications (async HTTP, no bot on the Minecraft server). /ah reload reloads config and messages.
Built for: Paper/Folia networks with multiple game modes and currencies, a shared auction across proxies, where anti-dupe matters more than “one more GUI button”.
Network and anti-dupe (short)
| Mode |
Purpose |
JSON / YAML |
single server, quick start |
SQLITE / MYSQL |
persistence; MYSQL is the proxy foundation |
| Redis + pub/sub |
cross-instance locks + catalog cache invalidation |
On a proxy: MYSQL + redis.enabled. Buy/cancel/expiry go through listing claim (lock + Redis NX + UPDATE … WHERE status='ACTIVE'), rollback on payment failure or full inventory. Sell: item held in escrow in GUI; inventory listing uses strict removal before DB write (/ah sell, no clone-without-consume).
Features
- Multi-auction support, separate
open / buy / sell permissions.
- Currencies:
VAULT, PLAYER_POINTS, EXPERIENCE, COINS_ENGINE, ITEM.
- Storage:
JSON, YAML, SQLITE, MYSQL.
- Listing TTL (timed or unlimited), claim, seller notification on expiry, per-auction fees, sold/cancelled/expired history.
- Listing limits:
soulauction.<auctionId>.<N>, soulauction.all.<N>.
- Sort priority:
soulauction.priority.<N>.
- Large-sale broadcast, external notifications (Discord/Telegram).
- Sell GUI: amount ±1, pull matching items from inventory (up to max stack); comparison by full serialization (NBT, name, enchants), not “similar” stacks. Escrow until confirm — returned on cancel/close.
- Per-auction price display: custom currency symbol, before/after number, MiniMessage and optional PlaceholderAPI in the symbol (resource pack / ItemsAdder icons, etc.).
- Fake activity: synthetic listings from a nick/item pool, enabled per auction; timer refill, manual
/ah admin fake, toggle in admin GUI.
- Seller skins: heads in “Favorite sellers” via SkinsRestorer / Mojang; fallback and one shared skin for all fake sellers (server logo).
Price display (auctions/*.yml)
Each auction has its own fields (defaults in Java; after first start — plugins/SoulAuction/auctions/global.yml and others):
| Field |
Purpose |
currencySymbol |
Symbol or icon in GUI and chat. Empty — economy default (Vault $, PlayerPoints PP, items Nx MATERIAL). |
currencySymbolPosition |
BEFORE or AFTER the amount ($100 or 100 ₽). |
currencySymbolPlaceholderApi |
true — resolve %...% from PlaceholderAPI for the viewer (requires PlaceholderAPI). |
listingTtlSeconds |
Listing lifetime in seconds; 0 or less — no expiry. |
Listing TTL and claim
- While a listing is ACTIVE, the browser and “My listings” (if TTL enabled) show time left / expires at in lore; the open browser refreshes the timer every second.
- Expired, unsold: listing removed (
EXPIRED), item goes to claim once (claims.json), not the void.
- Seller: chat message (online immediately, offline on join) with expiry notice and [Claim in menu] →
/ah expired [auctionId]; item pickup — /ah claim (expired menu is view-only, slots are not editable).
- Listing success: multi-line chat — item, amount, price, auction; separate block for timed or unlimited expiry (
success-listed, success-listed-expiry-timed / success-listed-expiry-unlimited in lang/messages_*.yml).
- Single process: lock on
listingId + on SQL, ACTIVE → EXPIRED/SOLD/CANCELLED is atomic; claim is removed from buffer before inventory delivery.
currencySymbol examples:
- Text:
₽, coins, gems
- MiniMessage / glyph:
<glyph:coin> (ItemsAdder, Nexo, etc. — per pack docs)
- PAPI (with
currencySymbolPlaceholderApi: true): %img_economy%
Custom symbol prices appear everywhere: GUI listings, sell menu, price filter, purchase, history, chat (success-bought, announce, etc.).
Messages (plugins/SoulAuction/lang/)
prefix — prefix for all {prefix} strings.
- Keys use MiniMessage;
{price} is already formatted for the auction the player is viewing.
- Multi-line chat: key as a YAML list of strings — plugin sends each line separately (
MessageService.send). Single string — as before. Chat search, sell success, expiry, command usage — in this format.
- Listing lore placeholders in GUI:
{seller}, {price}, {id}, {auction}, {expires_in}, {expires_at} (last two when TTL enabled); optional listingLoreTemplate in auctions/*.yml.
PlaceholderAPI
Expansion registers automatically when PlaceholderAPI is present. Identifier — soulauction, i.e. %soulauction_<param>%. Numbers are formatted for the player's locale (thousands separators). Any placeholder also has a _raw suffix variant — unformatted value (1500000 instead of 1,500,000, enum key instead of lang name) for scoreboards and plugins that need raw numbers.
Counters
| Placeholder |
Value |
%soulauction_active_count% |
Player's active listings (aliases: sell_count, purchasable_count) |
%soulauction_expired_count% |
Player's expired items (claims with reason EXPIRED) |
%soulauction_total_active_count% |
All listings on the auction house |
%soulauction_sell_limit% |
Player's global listing limit (permissions + override) |
%soulauction_claims% |
All player items in claim |
%soulauction_listings_all% / %soulauction_listings_<auctionId>% |
Player's active listings (all / specific auction) |
%soulauction_listings_total% |
All listings (unformatted, legacy) |
Player settings
| Placeholder |
Value |
%soulauction_selected_sorting% |
Selected sort order |
%soulauction_selected_category% |
Selected category |
%soulauction_selected_currency% |
Currency of the last opened auction (currency-* from lang) |
%soulauction_categories_enabled%, %soulauction_expired_items_enabled%, %soulauction_auction_listing_confirmation_enabled% |
Always true — these systems cannot be disabled in SoulAuction |
Deal statistics
Persistent (data/stats.json); seeded once from existing history on first run. <currency> is economy type: vault, player_points, experience, coins_engine, item.
| Placeholder |
Value |
%soulauction_items_sold% |
Items sold by the player |
%soulauction_items_purchased% |
Items purchased by the player |
%soulauction_money_made% |
Money earned by the player (after tax) |
%soulauction_money_spent% |
Money spent by the player (with buyer tax) |
%soulauction_items_sold_<currency>% and similar |
Same, per currency |
%soulauction_total_items_sold%, %soulauction_total_money_made%, etc. |
Server-wide, including _<currency> |
Fake activity
Synthetic listings keep the storefront busy: random nick from the pool, random item, random price in range. These are not real players — purchases work like normal listings (money is consumed, item is delivered). After a fake listing is bought, the plugin may list another one after a delay.
Per-auction enable
There is no global on/off in config.yml — only per auction:
| Where |
Field / action |
auctions/<id>.yml |
fake-activity-enabled: true / false (default false) |
/ah admin → right-click an auction |
fake-activity menu |
| Menu → slot 22 |
toggle (LIME_DYE / RED_DYE) → auctions/<id>.yml |
| Menu → slot 49 |
pool, limits, tick (read-only) |
Example in auctions/global.yml:
fake-activity-enabled: true
Pool (plugins/SoulAuction/fake-activity/)
Path: config.yml → fake-activity.directory (default fake-activity). On first start three files are created:
| File |
Contents |
settings.yml |
timers, limits, default prices, admin-fake |
sellers.yml |
seller display names (max 16 chars) |
items.yml |
item pool with weights and price ranges |
Fresh install ships ~120 nicks and ~120 vanilla items (ores, food, tools, 1.21 rares) — edit in YAML anytime.
settings.yml (main fields)
| Field |
Purpose |
initial-fill-listings |
listings to create on startup (0 = up to max-total-listings) |
initial-delay-seconds |
delay before the first refill tick |
tick-interval-seconds |
how often to top up toward limits |
after-purchase-delay-seconds |
delay after a fake buy before the same seller lists again |
min-price / max-price |
default range when an item in items.yml has min/max = 0 |
price-variance-percent |
random ±% on the chosen price |
max-listings-per-auction |
fake cap per auctionId |
max-total-listings |
fake cap server-wide |
listing-age-spread-seconds |
random listing age on create (varied TTL timers) |
listings-per-tick |
listings to attempt per tick |
auction-ids |
only these auctions ([] = all with fake-activity-enabled) |
admin-fake.register-seller |
after /ah admin fake, append nick to sellers.yml |
admin-fake.register-item |
after /ah admin fake, append hand item to items.yml |
items.yml entry fields
id — label for yourself
material / amount — vanilla stack (ignored when item-base64 is set)
item-base64 — full item snapshot (NBT, custom items)
min-price / max-price — 0 = from settings.yml
auction-ids — empty = any auction; otherwise only listed ids
weight — relative pick chance (higher = more often)
Manual fake listing
/ah admin fake <nick> <auctionId> <price>
Item must be in the main hand. Listing is created as synthetic immediately. With admin-fake.* enabled, nick and/or item are appended to the pool async.
Behaviour
- Fakes appear in sorting, search, and filters like normal listings.
- Only an admin with
soulauction.command.cancel.any can /ah cancel them (seller is a synthetic UUID).
- On a proxy with MySQL+Redis, fakes sync like any other listing.
Seller skins (config.yml → seller-skins)
Textures for seller heads in the “Favorite sellers” GUI (hub → star). Browser listings show the item itself, not a head.
SkinsRestorer is a soft dependency; on offline/cracked servers Mojang lookup by nick often fails without it.
source
| Value |
Behaviour |
auto |
SkinsRestorer when installed; otherwise Mojang API |
skins-restorer |
SkinsRestorer only |
mojang |
Mojang only (online-mode, real nicks) |
off |
default Steve/Alex heads, no lookup |
fallback-skin and fake-seller-skin
seller-skins:
source: skins-restorer
fallback-skin: "DefaultHead"
fake-seller-skin: "ServerLogo"
| Field |
When |
fallback-skin |
seller nick lookup failed → SR resolves this custom skin / nick / URL |
fake-seller-skin |
all synthetic/fake sellers use this skin; nick is ignored |
Values are SkinsRestorer skin names (/sr set skin ServerLogo <url>, etc.).
Lookup chain (SkinsRestorer)
findOrCreateSkinData(nick) — or fake-seller-skin when the seller is synthetic and the field is set
findSkinData(fallback-skin) — when configured
getSkinForPlayer(uuid, nick) — SR defaultSkins from SkinsRestorer config
With source: mojang, fallback uses the Mojang API by name.
Startup warmup
Async prefetch into SkinsRestorer cache (~100 ms pause between requests):
- if
fake-seller-skin is set — warmup that skin (+ fallback-skin when set);
- otherwise — all fake pool nicks +
fallback-skin.
Console: SkinsRestorer — prefetched X/Y fake seller skins.
GUI lookup is async; the head updates when the texture arrives (no in-memory cache in SoulAuction).
Admin GUI
/ah admin or /ah admin gui [page] — requires soulauction.command.admin or OP.
| Action |
Result |
| Left-click an auction |
open storefront as a player |
| Right-click an auction |
fake-activity menu |
| Slot 22 |
toggle fake activity (wool) |
| Slot 49 |
pool, limits, tick (read-only) |
| Slot 45 |
back to auction list |
| Book in the bottom row |
create a new auction (chat wizard) |
Commands
Players
/ah — open the default auction.
/ah <auctionId> — open a specific auction.
/ah sell <price> — list the item in hand on the default auction.
/ah sell <auctionId> <price> — list on the chosen auction.
/ah sell <price> <auctionId> — alternative argument order.
/ah my [auctionId] — show your active listings.
/ah selling [auctionId] — active listings GUI.
/ah expired [auctionId] — expired items GUI (claim).
/ah purchased [auctionId] — purchase history GUI.
/ah history [auctionId] — sales history GUI.
/ah search <text> — search: closes GUI, prompt in chat (cancel button in message); after input — refreshed browser and result in chat.
/ah search <auctionId> <text> — same for a specific auction.
/ah search cancel — cancel search and return to the auction.
/ah page <number> [auctionId] — open a specific auction page.
/ah claim [all] — claim expired/cancelled items.
/ah cancel <id> — remove your listing and return the item.
- Command aliases are configured in
config.yml via commandAliases (e.g. ax, auction).
Admins
/ah reload — reload configs and messages.
/ah purge <days> — purge deal history older than N days.
/ah admin history <player> [limit] — player history in chat.
/ah admin selling <player> [auctionId] — player's active listings GUI.
/ah admin blacklist add|remove <player> — runtime sell blacklist.
/ah admin recover <claimId> — deliver claim to inventory.
/ah admin audit [limit] — recent audit entries.
/ah admin cache stats|rebuild|invalidate — catalog cache.
/ah admin sellfor <player> <auctionId> <price> — list on behalf of a player (item in hand).
/ah admin fake <nick> <auctionId> <price> — synthetic listing under the given nick (item in hand; see fake activity).
/ah admin gui [page] — auction list GUI (right-click an auction for fake activity).
/ah admin parse tags|nbt — parse NBT/tags of item in hand (custom items).
/ah view <player> [auctionId] — player's listings GUI.
Permissions
Basic
soulauction.command.ah — use /ah.
soulauction.command.sell — use /ah sell.
soulauction.command.reload — use /ah reload.
soulauction.command.admin — admin commands and purge.
soulauction.priority.10 — higher listing sort priority (any N).
soulauction.command.my — use /ah my.
soulauction.command.claim — use /ah claim.
soulauction.command.cancel.any — remove others' listings via /ah cancel.
Per-auction (set in config.yml)
Each auction has separate nodes:
openPermission — open this auction.
buyPermission — buy listings in this auction.
sellPermission — sell in this auction.
Example:
soulauction.open.vip
soulauction.buy.vip
soulauction.sell.vip
Dynamic listing limits
soulauction.<auctionId>.1 — limit 1 active listing in this auction.
soulauction.<auctionId>.5 — limit 5 active listings in this auction.
soulauction.all.1 — global limit 1 across all auctions.
soulauction.all.5 — global limit 5 across all auctions.
If multiple nodes are granted, the highest limit applies.
If none are granted, defaults from limits are used.
Taxes
soulauction.tax.bypass — no sale or purchase tax.
soulauction.tax.discount.<percent> — sale tax discount (highest wins).
In auctions/*.yml: saleTaxPercent (from seller), buyTaxPercent (from buyer).
Price bounds
- Global:
limits.minPrice, limits.maxPrice in config.yml.
- Per-auction:
minPrice, maxPrice (0 = use global).
soulauction.price.min.<price> — minimum listing price for a player.
soulauction.price.max.<price> — maximum listing price for a player.
Discord and Telegram
In config.yml → notifications section:
- Discord:
notifications.discord.enabled, webhookUrl (channel Incoming Webhook).
- Telegram:
notifications.telegram.enabled, botToken, chatId.
- Events:
notify-sold, notify-listed, notify-expired, min-price filter.
- Delivery is async (Java HTTP), no shade, no bot on the Minecraft server.
- Player avatars in Discord:
notifications.discord.show-player-avatars (seller head in author, buyer thumbnail on deals). CDN: avatar-provider = MINOTAR (default) or CRAFATAR.
After /ah reload, new URLs and flags are picked up.
评论 0
登录后参与评分
还没有评论,来抢沙发吧