SoulBuyer
Russian version
适用于 Paper 1.21+ 和 Folia 的高级资源购买器: 实时 GUI、动态市场、目录轮换、强化商店、三种模式的自动出售、PlayerPoints 集成(单独的捐赠购买器或全额以点数支付)、玩家进度以及多种存储后端——从单服务器上的 YAML 到跨网络的 MySQL + Redis。
概述
SoulBuyer 不是“把物品放入槽位然后等待”。玩家打开菜单,看到的是一个可购买资源的网格,显示当前价格、点数和市场系数。左键点击物品 — 出售库存中该资源的所有数量;右键点击 — 在单独的子菜单中选择数量。包含类别过滤器、排序、分页和“全部出售”按钮。
服务器上某种资源卖出的越多,其市场系数就越低(具有可配置的下限和逐渐恢复机制)。销售会授予进度点数和类别经验值(矿石、生物、植物、方块、其他);点数可以在强化商店中兑换临时增益效果。 payout 通过 Vault 或 PlayerPoints 进行(参见 PlayerPoints 和捐赠购买器)。
自动出售是一个单独的捐赠特权:玩家可以选择何时提交资源——拾取时、打开购买器菜单时,或打开容器时的箱子内容。类别、通知和最低价格均可配置。
目录不会停滞:定时器会更改可购买物品的集合,重置市场系数,并向玩家发送聊天通知。菜单底部有一个实时统计面板:距离轮换的时间、今日已售出数量、当前轮换中的资源数量。
功能
为什么要将其放在你的服务器上:
- 开箱即用 — ~380 种物品、GUI、轮换、市场和语言支持(ru/en/fi),首次启动即可使用;无需手动调整配置
- 完全可配置 — 价格、目录、GUI 槽位、权限、市场限制、轮换、自动出售、经济系统;文本位于
lang/,数值位于 config.yml / items.yml
- GUI 覆盖命令 — 出售、过滤器、排序、数量、自动出售;命令仅为别名
- 动态市场 — 大量提交导致价格下降,衰减后恢复正常;玩家在物品描述中可以看到系数
- 目录轮换 — 定时器从池中选取新的一组物品;聊天通知;打开的菜单就地刷新
- 捐赠购买器 — Vault + PlayerPoints:两个菜单(
/buyer 和 /donbuyer)或一个完全以点数支付的购买器;配置中有两个标志
- 自动出售 — 捐赠特权:拾取 / 菜单 / 箱子;类别、最低价格、通知;双模式下可选择 payout(金币或点数)
- 强化道具 — 购买器菜单中的临时增益商店;可使用进度点数、Vault 或 PlayerPoints 支付(可配置)
- 个人出售限制 — 每个 item-id 的每日上限(防止倾销);LuckPerms 节点和限制强化道具
- 进度系统 — 点数、类别 XP、通过 LuckPerms 的 VIP 乘数;激励玩家去耕作,而不仅仅是拾取战利品
- 实时统计 — 距离轮换的时间、“今日已售出”、菜单中的商品种类大小(+ PlaceholderAPI)
- 类别动画 — 过滤器图标循环显示来自当前轮换的真实物品
- 优化 — 所有数据库 I/O 异步进行;主线程永不阻塞;HikariCP;仅在需要网络时使用 Redis
- 存储选择 —
flat / sqlite / mysql + Redis,用于共享一个市场的多个 Paper 服务器
- Folia 就绪 — 热路径上使用区域感知调度器;同步逻辑不使用旧的
BukkitScheduler
- 安全销售 — 每笔交易都有安全的存储;出错或断开连接时物品会被返还
- 供其他插件使用的 API —
SoulBuyerApi:菜单、报价、从你自己的 GUI 出售、物品类别、进度
- 自动检测玩家语言(配置中的 CLIENT/SERVER 区域设置)— v1.4.0
- 可选的 bStats 指标(可在配置中退出)— v1.4.0
购买器 GUI
| 区域 |
功能 |
| 顶行 |
类别过滤器 + “你的进度”区块(点数、倍率) |
| 21 格网格 |
可购买物品图标:价格、点数、市场系数、库存数量。鼠标左键 (LMB) — 全部出售,鼠标右键 (RMB) — 数量子菜单 |
| ← → 箭头 |
分页(第 4 行,位于网格两侧) |
| 底行 |
排序(单个切换按钮)、“全部出售”、强化道具、自动出售、“距离轮换”面板 |
| 类别 |
“全部” — Vault 图标(存储);其他 — 实时动画:图标更改并显示该类别当前商品组合中的真实物品 |
排序(比较器,点击切换下一模式):最高价格 → 最低价格 → 最多点数 → 最少点数。
强化道具(底行的下界之星):鼠标左键 (LMB) — 临时增益商店。可从普通和捐赠菜单中使用。详情见 强化道具。
自动出售(底行的绿宝石):鼠标左键 (LMB) — 设置屏幕,鼠标右键 (RMB) — 开启/关闭。详情见 自动出售。
文本和颜色 — 位于 lang/ru.yml、lang/en.yml、lang/fi.yml。十六进制颜色、渐变标题、类别和物品的描述 — 全部无需重新构建 JAR。
菜单图标(锻造模板、盔甲纹饰)
在 gui/buyer.yml → hideVanillaItemTooltip: true(默认):工具提示仅显示 SoulBuyer 的描述 — 没有原版“锻造模板”、“应用于”、属性等。
| 物品类型 |
在槽位中的显示方式 |
| 常规资源 |
物品图标 + 你的描述 |
| 盔甲纹饰(螺栓、流动、海岸…) |
带有纹饰图案的铁胸甲 |
| 下界合金升级 |
下界合金锭 |
更新后的验证方法
- 构建 JAR,替换到服务器,重启。
- 打开
/buyer → “Misc” 类别(或者纹饰在轮换中的位置)。
- 槽位应显示带纹饰的胸甲,而不是没有图案的普通灰色胸甲。
- 悬停 — 只显示 SoulBuyer 名称和价格,没有原版的杂乱信息。
- 自动出售中同样适用:绿宝石 → 鼠标右键 (RMB) 点击类别 → 带图案的纹饰。
如果图标仍然错误
plugins/SoulBuyer/gui/buyer.yml 必须包含 hideVanillaItemTooltip: true。
- 客户端版本 1.21+;关闭 F3+H(高级物品提示会干扰显示)。
- 管理员操作:
config.yml → debug-tooltip: true → /soulbuyer admin reload → /soulbuyer admin debug-tooltip → /buyer。生产环境请保持为 false(默认值)。
自动出售 (Autosell)
独立的捐赠机制(权限节点 soulbuyer.autosell,默认 OP 拥有)。玩家可自行配置行为模式——设置按玩家独立保存(YAML 文件或 MySQL 数据库)。
触发时机
三种模式之一(在设置菜单中通过按钮切换):
| 模式 |
图标 |
触发条件 |
| 拾取时 (On pickup) |
漏斗 |
物品从地面或钓鱼进入背包 |
| 打开菜单时 (On menu open) |
绿宝石 |
打开买家 GUI —— 出售来自玩家背包的所有匹配物品 |
| 打开箱子时 (On chest open) |
箱子 |
打开容器 —— 出售来自箱子格子的所有匹配物品。玩家背包不受影响 |
支持箱子、 barrels(桶)、潜影盒、末影箱、漏斗、发射器、投掷器及矿车中的箱子。遵循启用的类别、物品选择、最低价格以及当前轮换列表(仅出售当前买家列表中存在的物品 ID)。
其他设置
| 选项 |
含义 |
| 开/关 (On/off) |
总开关(位于菜单中心或通过右键买家中的绿宝石) |
| 类别 (Categories) |
矿石、生物、植物、方块、杂项 —— 左键点击可切换整个类别的启用状态 |
| 类别内的物品 (Items in category) |
在类别图标上右键 → 进入选择界面:选择该类别中哪些物品 ID 需要自动出售 |
| 通知 (Notifications) |
动作栏 / 聊天消息 / 关闭 |
| 最低价格 (Min price) |
低于此阈值(计算市场和倍率后)的物品不予出售 |
| 支付目标 (Payout target) |
仅限双买家模式:普通买家(Vault 货币)或捐赠买家(PlayerPoints)。点击第 4 行中间的锭即可切换 |
类别内单项选择
启用某个类别后,默认情况下当前轮换列表中该类别的所有物品都会自动出售。若只想保留“生物”类别中的骨头或“矿石”类别中的钻石:
- 进入自动出售菜单 → 对类别图标执行 右键。
- 打开网格界面,其中仅显示当前有效的物品 ID(与
/buyer 命令中一致)。
- 点击物品 —— 切换其自动出售状态(高亮表示已启用)。
- 无法禁用活动类别中最后一个已启用的物品。
如果某物品退出轮换列表——它将不会出现在选择界面中,且不会自动出售,即使之前已启用。当它重新回到轮换列表时,玩家的设置将被保留(除非该 ID 被列入禁用列表)。
示例: 启用“Mobs”类别 → 右键 → 除 bone 外禁用所有物品 → 仅在拾取/箱子/菜单模式下出售生物骨头(且仅在骨头处于轮换期间有效)。
玩家设置存储
按玩家存储在 data/autosell/{uuid}.yml(扁平格式)或表 soulbuyer_autosell 的 settings 列中(MySQL)。文本格式如下:
enabled=true
trigger=pickup
notify=actionbar
min-unit-price=0
payout=vault
categories=ores,mobs,plants,blocks,misc
disabled-items=bone,rotten_flesh
| 键名 |
含义 |
categories |
启用的类别(逗号分隔) |
disabled-items |
在启用类别中排除自动出售的物品 ID。为空 = 所有活动类别中的物品 |
其他键 — 触发模式、通知方式、最低价格、支付目标。
书本槽位 — 简短的游戏内帮助。如果背包中没有可出售物品,则不发送额外的聊天刷屏信息。
在两个买家菜单(普通和 /donbuyer)中,自动出售按钮均显示当前的支付模式;无论从哪里进入,配置均在同一个自动出售屏幕中进行。
服务器为何使用此功能
- 捐赠特权且不造成 Pay-to-Win:相同的定价和市场,减少肝度。
- 基地整理:“箱子”模式 —— 打开储物箱,里面的杂物立即出售,有用的东西留在箱子里。
- 挂机农场:“拾取”模式 —— 拾取到的资源已被自动出售。
- 休闲玩家:“菜单”模式 —— 打开
/buyer,多余物品自动出售。
在 config.yml → autosell 部分:可在服务器范围内启用/禁用该功能,设置新玩家的默认值、最低价格步长以及拾取后的延迟时间。
增益道具 (Boosters)
用于购买临时增益效果的商店 —— 可从普通 (/buyer) 和捐赠 (/donbuyer) 菜单中打开:点击 “Boosters” 按钮(下界之星)→ 进入包含三个优惠方案的单独屏幕。
购买将从 config.yml → boosters.currency 指定的货币中扣除:
| 值 |
扣款来源 |
progression_points |
SoulBuyer 点数(默认 —— 通过出售获得,此前无处消费) |
vault |
通过 Vault 插件提供的金币 |
playerpoints |
PlayerPoints |
三种增益道具(默认配置,均在 config 中)
| ID |
效果 |
持续时间 |
价格(默认) |
multiplier |
个人收入倍率 +0.5 |
1 小时 |
125 点数 |
money |
出售获得的金币/点数 ×1.25 |
1 小时 |
175 点数 |
limit |
每个物品 ID 的个人每日上限 ×2 |
30 分钟 |
75 点数 |
价格、持续时间、效果强度、材料和 GUI 槽位 —— 位于 config.yml → boosters.offers 和 gui/boosters.yml。
每个增益道具按钮的描述 lore 显示:效果、价格、持续时间、当前是否激活以及剩余时间。重复购买会刷新该类型增益的计时器。
出售限制(与 limit 增益关联)
平行的防倾销机制 —— config.yml 中的 sell-limits 部分:
- 每位玩家每个
item-id 有每日上限(默认 64/天)。
- LuckPerms 节点
soulbuyer.limit.vip / soulbuyer.limit.premium 可提高上限(128 / 256)。
- 限制类增益将乘以最终上限。
sell-limits.enabled: false —— 完全禁用所有限制。
当超出限制时,出售量会被修剪至允许的数量;超额部分退回背包。
权限与新安装
| 节点 |
访问权限 |
soulbuyer.boosters |
增益道具商店(默认:true) |
Java 端默认设置:增益道具启用,货币类型为 progression points,首次启动后所有三个优惠方案及 GUI 均已就位。活跃的增益道具按玩家保存(data/boosters/ 目录或表 soulbuyer_boosters)。
PlayerPoints 与捐赠买家
SoulBuyer 并非仅支持 Vault。当服务器安装了 PlayerPoints 时,该插件将使用 捐赠点数 支付资源费用——无需修改、独立的命令、相同的商店、轮换机制和进度系统。
一个目录 items.yml、一套价格和系数——仅 支付货币 不同(服务器金币或 PlayerPoints)。
三种模式(config.yml 中的 economy 部分)
player-points-enabled |
donate-buyer-enabled |
玩家所见内容 |
false |
— |
经典模式:/buyer → 使用 Vault 支付 |
true |
false |
单一 购买界面:/buyer → 全部使用 PlayerPoints 支付(无需 Vault) |
true |
true |
两个 购买界面:常规模式用于金币 + 捐赠 模式用于点数 |
economy:
player-points-enabled: false # 启用 PlayerPoints
donate-buyer-enabled: false # true = 第二个菜单仅接受点数支付
在 没有 Vault 的 Folia 上,安装 PlayerPoints 并设置 player-points-enabled: true;或者如果缺少 Vault 但存在 PlayerPoints,插件会自动切换。
双购买界面——为何重要
捐赠服务器通常会将经济系统分开:刷取 → 金币,捐赠内容 → 点数。SoulBuyer 用一个 JAR 包覆盖这两种情况:
| 菜单 |
命令 |
支付方式 |
适用人群 |
| 常规 |
/buyer, /sell, /soulbuyer |
Vault (金币) |
拥有 soulbuyer.use 权限的所有人 |
| 捐赠 |
/donbuyer, /dbuyer, /ppbuyer |
PlayerPoints |
拥有 soulbuyer.donate 权限的人 |
- 相同的商品种类和 实时市场 —— 大量出售会导致两个菜单中的价格均下降。
- 进度点数 和分类经验值照常累积(这是元进度,而非支付货币)。
- 捐赠菜单有单独的 标题和描述 —— 玩家会立即看到点数支付信息。
- 自动出售 跟随玩家设置:在双模式下为 Vault 或 PlayerPoints;仅在 PlayerPoints 模式下始终为点数。
全新安装
Java 默认设置:PlayerPoints 关闭,仅支持 Vault——与之前相同。在 config.yml 中添加两行即可启用,然后重启服务器。/donbuyer 及其别名位于 plugin.yml 中;如果捐赠模式未开启,执行 /donbuyer 会提示该功能不可用。
依赖项
| 插件 |
何时需要 |
| Vault + 经济系统 |
默认情况;双模式和经典模式必需 |
| PlayerPoints |
player-points-enabled: true 时 |
两者均在 plugin.yml 中标记为 softdepend:插件启动后会等待所需的经济系统加载,然后再打开 GUI。
动态市场
- 每种资源都有 基础价格 和 市场系数(初始值为 1.0)。
- 大量出售会 降低 系数至配置的最小值。
- 如果资源停止出售,衰减 机制会逐渐将价格恢复到 1.0。
- 在 mysql + 网络 模式下,系数通过 Redis pub/sub 同步。
玩家在 GUI 的物品描述中可以看到市场乘数。
目录轮换
完整目录(items.yml 中约 380 种原版资源)作为 池子。购买界面同时显示 随机子集(默认为 48 个物品,每个类别至少包含最小数量)。
| 参数 |
默认值 |
含义 |
catalog-rotation.enabled |
true |
轮换开启/关闭 |
interval-seconds |
3600 |
更换间隔(1 小时) |
active-item-count |
48 |
菜单中的物品数量 |
reset-market-on-rotation |
true |
更换时重置市场系数 |
notify.enabled |
true |
更新时在聊天中发送消息 |
轮换状态保存在 data/rotation.yml 中。打开菜单时会 刷新而不关闭。
统计面板(底部居中)
不再是“第 1/3 页”,而是带有 实时计时器 的时钟(每秒更新一次):
- 距离下次轮换 —— 距离下一次轮换的剩余时间
- 今日售出 —— 金币、点数、组数
- 在售数量 —— 当前轮换中有多少种资源
语言文件中的 Lore 占位符:
| 占位符 |
描述 |
{rotation_left} |
距离轮换的计时器,或显示“disabled” / “soon” |
{sold_today_money} |
今日金币 |
{sold_today_points} |
今日点数 |
{sold_today_stacks} |
今日售出的组数 |
{sold_alltime_money} |
历史总金币 |
{sold_alltime_points} |
历史总点数 |
{sold_alltime_stacks} |
历史总组数 |
{active_items} |
当前在售物品数量 |
进度系统
- 点数 每次出售获得(来自物品的
base-points + 基于基础价格 × points-per-currency 的奖励)。
- 分类经验值 —— 由获得的点数增长;金钱 奖励来自 经验等级(而非原始数值),上限由
max-category-bonus 限制。
- 权限乘数 —— VIP、Premium 等(授予的最高权限生效)。
- 主导分类加成 —— 来自主分类经验等级的额外收入(
category-xp-per-level,dominant-category-bonus-per-level)。
- 点数可以在强化商店中使用(如果
boosters.currency: progression_points)。
- 防作弊:
max-unit-price,每笔交易的 max-payout-per-sale。
安全性和可靠性
- 安全存储 交易期间的物品——即使卡顿或出错也不会丢失。
- 退出/失败时 —— 返还 未售出的物品到背包。
- 销售记录(
sales.log 或表 soulbuyer_sales)—— 作为“今日售出”统计的基础。
- 所有数据库 I/O 异步,主线程永不阻塞。
数据存储
| 模式 |
使用场景 |
flat |
单服务器,YAML + 销售日志(默认) |
sqlite |
单服务器,文件 data/data.db |
mysql |
服务器网络,共享数据库 + Redis 用于市场数据 |
玩家进度、市场系数、轮换、销售日志——所有数据在重启后都会保留。
命令
主命令:/soulbuyer。菜单别名(可配置):/buyer, /sell, /sb, /rbuyer, /bs.
捐赠购买界面(仅在 economy.donate-buyer-enabled: true 时可用):/donbuyer。别名:/dbuyer, /ppbuyer, /donatesell.
| 命令 |
操作 |
/soulbuyer |
打开买家 GUI(Vault 或 PlayerPoints — 取决于 economy 模式) |
/buyer, /sell, … |
相同(别名) |
/donbuyer, /dbuyer, … |
捐赠菜单 — 支付使用 PlayerPoints(双模式) |
/soulbuyer admin reload |
重新加载配置、GUI 和语言文件 |
别名继承子命令:/buyer admin reload = /soulbuyer admin reload.
权限
| 节点 |
访问权限 |
soulbuyer.use |
GUI 和出售功能(常规买家) |
soulbuyer.donate |
捐赠菜单 /donbuyer(PlayerPoints,双模式) |
soulbuyer.admin |
/soulbuyer admin reload |
soulbuyer.autosell |
自动出售(捐赠模式下默认 OP 拥有) |
soulbuyer.boosters |
加速道具商店(默认:开启) |
soulbuyer.limit.vip |
每日出售限制 128/物品ID |
soulbuyer.limit.premium |
每日出售限制 256/物品ID |
soulbuyer.multiplier.vip |
倍率 ×1.1(默认) |
soulbuyer.multiplier.premium |
倍率 ×1.25(默认) |
当存在多个倍率节点时,应用最高倍率。
PlaceholderAPI
softdepend — 如果服务器安装了 PAPI,扩展 soulbuyer 将会注册。
| 占位符 |
描述 |
%soulbuyer_rotation_left% |
轮换剩余时间(文本格式) |
%soulbuyer_rotation_seconds% |
轮换剩余秒数(数字格式) |
%soulbuyer_sold_today_money% |
今日出售获得的金币 |
%soulbuyer_sold_today_points% |
今日出售获得的点数 |
%soulbuyer_sold_today_stacks% |
今日出售的组数 |
%soulbuyer_sold_alltime_money% |
历史累计出售获得的金币 |
%soulbuyer_sold_alltime_points% |
历史累计出售获得的点数 |
%soulbuyer_sold_alltime_stacks% |
历史累计出售的组数 |
%soulbuyer_active_items% |
当前商品目录中的物品数量 |
PAPI 占位符可以放置在 lang/*.yml 的字符串中 —— 它们在渲染 GUI 时解析。
配置
| 文件 |
内容 |
config.yml |
存储、市场、轮换、进度、加速道具、出售限制、权限、分类图标动画、语言环境、检查更新、bstats |
items.yml |
目录:id、材质、分类、基础价格、基础点数 |
gui/general.yml, gui/buyer.yml, gui/quantity.yml, gui/autosell.yml, gui/boosters.yml |
槽位、按钮材质、动作类型 |
lang/en.yml, lang/ru.yml, lang/fi.yml |
内置语言包:标题、背景故事、消息、十六进制颜色 |
lang/*.yml (磁盘上) |
自定义语言包 — 复制内置文件或添加例如 lang/de.yml; lang/ 下的任何 *.yml 文件在启动和重载时加载 |
data/rotation.yml |
当前轮换内容及下次变更时间 |
data/market.yml |
市场系数(扁平模式) |
data/players/ |
玩家进度(扁平模式) |
data/boosters/ |
玩家激活的加速道具(扁平模式) |
data/sell-limits/ |
今日各物品ID的销售量(扁平模式) |
默认值位于 Java 代码中 —— 首次启动后一切即可开箱即用:约 380 种物品、轮换、GUI、目录和统计功能。
语言设置 (config.yml → locale)
| 键 |
用途 |
locale-mode |
CLIENT(默认)—— 每位玩家的 Minecraft 客户端语言;SERVER —— 所有人使用统一语言 |
server-locale |
仅在 locale-mode: SERVER 时使用(例如 ru, en, fi,或与 lang/<code>.yml 匹配的任何自定义代码) |
fallback-locale |
缺失键值以及 CLIENT 模式下的回退语言(通常设为 en) |
内置文件:lang/en.yml, lang/ru.yml, lang/fi.yml。可在 plugins/SoulBuyer/lang/ 下添加自定义文件;通过 /soulbuyer admin reload 重载。
其他 config.yml 键值
| 键 |
用途 |
check-for-updates |
当有新插件版本可用时通知控制台(默认:true) |
bstats.enabled |
向 bStats 发送匿名指标数据(默认:true;设置为 false 以退出) |
主要部分:
storage-type: flat # flat | sqlite | mysql
economy: # Vault / PlayerPoints / 双模式买家
catalog-rotation: # 定时商品目录更换
category-icon-animation: # 实时分类图标轮换
market: # 衰减、最低系数、刷新
progression: # 倍率、点数、分类经验、 payout 上限
boosters: # 购买货币、优惠信息(价格、效果、持续时间)
sell-limits: # 每日限制、权限层级
locale: # locale-mode, server-locale, fallback-locale
bstats: # enabled
check-for-updates: true
路线图
依赖要求
| 组件 |
必需 |
| Paper 1.21+ (支持 Folia) |
是 |
| Java 21 |
是 |
| Vault + 经济系统 |
默认需要;如果仅使用 PlayerPoints 则不需要(player-points-enabled: true, donate-buyer-enabled: false) |
| PlayerPoints |
可选;当 player-points-enabled: true 时必须安装 |
| MySQL + Redis |
仅在 storage-type: mysql 且处于网络环境中时需要 |
| PlaceholderAPI |
可选 |
公共 API
接口 SoulBuyerApi 在 Bukkit ServicesManager 中注册。另一个插件可通过 depend 或 softdepend: [SoulBuyer] 进行连接。
获取 API
import bm.b0b0b0.soulBuyer.api.SoulBuyerApi;
import bm.b0b0b0.soulBuyer.api.SoulBuyerApiProvider;
import bm.b0b0b0.soulBuyer.api.SoulBuyerSellDelivery;
import bm.b0b0b0.soulBuyer.api.SoulBuyerSellReturnPolicy;
import org.bukkit.Bukkit;
SoulBuyerApi api = SoulBuyerApiProvider.get();
// 或者:Bukkit.getServicesManager().load(SoulBuyerApi.class)
if (!api.isReady()) {
return;
}
SoulBuyerApiProvider.get() 始终返回一个对象:如果 SoulBuyer 尚未准备好 —— 则返回一个带有 isReady() == false 和无操作方法存根。
方法参考
| 方法 |
返回值 |
描述 |
isReady() |
boolean |
插件已加载,目录和经济系统就绪 |
openBuyerMenu(Player) |
— |
打开标准买家 GUI |
quoteItem(Player, itemId) |
Optional<ItemUnitQuote> |
1 单位的单价和积分(含市场系数、乘数、库存数量) |
quoteStack(Player, ItemStack) |
Optional<ItemUnitQuote> |
手持物品/槽位中物品的同上信息 |
marketCoefficient(itemId) |
double |
当前市场系数(1.0 = 基础值) |
cachedPoints(Player) |
double |
来自缓存的进度积分 |
cachedMultiplier(Player) |
double |
总个人乘数(权限 × 分类 + 增益道具) |
cachedCategoryXp(Player, categoryId) |
double |
来自缓存的分类经验值 |
fetchProgress(UUID) |
CompletableFuture<PlayerProgress> |
异步从存储加载进度;更新缓存 |
isSellable(itemId) |
boolean |
物品是否在 items.yml 池中 |
isInActiveCatalog(itemId) |
boolean |
物品是否在当前轮换列表中 |
activeCatalogSize() |
int |
当前轮换中的物品数量 |
categoryId(itemId) |
Optional<String> |
来自 items.yml 的分类(ores, mobs, plants, blocks, misc 等) |
categoryId(ItemStack) |
Optional<String> |
通过材质和自定义模型数据获取分类 |
isAutosellFeatureEnabled() |
boolean |
全局启用自动出售功能 |
canUseAutosell(Player) |
boolean |
玩家拥有自动出售权限 |
isAutosellEnabled(Player) |
boolean |
玩家主自动出售开关(非分类/物品详情级别) |
isSaleInProgress(Player) |
boolean |
出售交易正在进行中(安全存储忙碌) |
sellAll(Player) |
boolean |
出售库存中所有可卖物品 |
sellAll(Player, Runnable) |
boolean |
同上 + 完成时回调 |
sellAll(Player, SoulBuyerSellDelivery, Runnable) |
boolean |
带通知渠道选择的出售 |
sellItem(Player, itemId) |
boolean |
出售库存中指定 ID 的所有物品 |
sellItem(Player, itemId, Runnable) |
boolean |
同上 + 回调 |
sellItemAmount(Player, itemId, amount, Runnable) |
boolean |
从库存中出售指定数量的物品 |
sellStacks(Player, stacks) |
boolean |
出售给定的物品组(见下文) |
sellStacks(Player, stacks, Runnable) |
boolean |
同上 + 回调 |
sellStacks(Player, stacks, returnPolicy, delivery, Runnable) |
boolean |
完全控制退货策略和通知 |
如果 API 未就绪、玩家为空、列表为空或另一笔出售正在进行,出售方法将返回 false。返回 true 表示交易已接受;请检查回调和玩家消息以确认结果。
模型
ItemUnitQuote — unitPrice(单价)、unitPoints(单位积分)、marketCoefficient(市场系数)、playerMultiplier(玩家乘数)、inventoryAmount(库存数量)。
PlayerProgress — playerId(玩家 ID)、points(积分)、categoryXp(分类经验值映射,key 为 categoryId → XP)。
从库存出售
sellAll、sellItem、sellItemAmount 的行为类似于 SoulBuyer GUI 按钮:从玩家库存中取出物品,应用限制、增益道具、市场系数和进度加成,然后支付(根据配置使用 Vault 或 PlayerPoints)。发生错误时,未售出的物品将返回到库存。
if (api.isSaleInProgress(player)) {
return;
}
api.sellAll(player, SoulBuyerSellDelivery.ACTION_BAR, () -> {
// 主线程,交易完成后执行
player.sendMessage("Done!");
});
从自定义 GUI 出售 — sellStacks
对于带有“全部出售”按钮的自定义菜单:
- 从你的 GUI 槽位构建
List<ItemStack>。
- 如有需要,通过
categoryId 按分类进行过滤。
- 在调用前从 GUI 中移除物品堆(使用
CALLER_OWNS_ITEMS 策略)。
- 调用
sellStacks。
SoulBuyer 会计算价格、限制、增益道具、积分、分类经验值并支付给玩家。一次调用中包含多个物品堆 — 视为一笔交易。
List<ItemStack> toSell = new ArrayList<>();
for (ItemStack stack : guiSlots) {
if (stack == null || stack.isEmpty()) {
continue;
}
api.categoryId(stack).filter("ores"::equals).ifPresent(category -> toSell.add(stack.clone()));
}
if (toSell.isEmpty() || api.isSaleInProgress(player)) {
return;
}
// 在调用前从你的 GUI 中移除 toSell
boolean started = api.sellStacks(
player,
toSell,
SoulBuyerSellReturnPolicy.CALLER_OWNS_ITEMS,
SoulBuyerSellDelivery.SILENT,
() -> refreshMyGui(player)
);
if (!started) {
// 手动将物品返回到 GUI
}
SoulBuyerSellReturnPolicy |
取消/出错时的行为 |
RETURN_TO_PLAYER |
默认。未售出物品返回到玩家库存 |
CALLER_OWNS_ITEMS |
SoulBuyer 不触碰物品 — 由你的插件回滚 GUI |
SoulBuyerSellDelivery |
玩家通知方式 |
CHAT |
聊天消息(默认) |
ACTION_BAR |
动作栏 |
SILENT |
无 SoulBuyer 消息 |
由于每日限制,部分物品堆可能无法出售 — 超出部分将返回给玩家(或在 CALLER_OWNS_ITEMS 策略下保留在调用者手中)。
分类 — categoryId
分类来自每个 item-id 在 items.yml 中的 category 字段。常见值包括:ores、mobs、plants、blocks、misc。自定义 ID 也是允许的 — 必须与 GUI 过滤器和自动出售保持一致。
api.categoryId("raw_iron"); // Optional["ores"]
api.categoryId(player.getInventory().getItemInMainHand()); // 通过材质和 CMD
api.isSellable("raw_iron"); // 如果 ID 在池中则返回 true
api.isInActiveCatalog("raw_iron"); // 如果当前在轮换中则返回 true
进度缓存
cachedPoints / cachedMultiplier / cachedCategoryXp 读取内存数据。加入服务器后数据会异步加载;如果在打开菜单前需要确切数值,请调用 fetchProgress(uuid).join() 或等待回调。
fetchProgress 支持异步线程调用;仅通过 runTask 在其回调中修改 Bukkit API。
自动出售与 API: 分类和单件商品的设置仅通过 SoulBuyer GUI(gui/autosell.yml)进行配置。SoulBuyerApi 中不存在 toggleAutosellItem / getDisabledItems —— 对于自定义菜单,请使用 sellStacks 并通过 categoryId / isInActiveCatalog 自行实现过滤。
plugin.yml 中的依赖
softdepend: [SoulBuyer]
或者如果你的插件无法在缺少购买者插件的情况下运行,则使用 depend: [SoulBuyer]。
SoulBuyer
Russian version
Advanced resource buyer for Paper 1.21+ and Folia: live GUI, dynamic market, catalog rotation, booster shop, autosell with three modes, PlayerPoints integration (separate donate buyer or full payout in points), player progression, and multiple storage backends — from YAML on a single server to MySQL + Redis across a network.
Overview
SoulBuyer is not “drop an item in a slot and wait.” The player opens a menu and sees a grid of buyable resources with current prices, points, and market coefficient. Left-click on an item — sell all of that resource from inventory; right-click — pick quantity in a separate submenu. Category filters, sorting, pagination, and a “sell all” button are included.
The more one resource is sold on the server, the lower its market coefficient (with a configurable floor and gradual recovery). Sales grant progression points and category XP (ores, mobs, plants, blocks, misc); points can be spent in the booster shop for temporary buffs. Payout goes through Vault or PlayerPoints (see PlayerPoints and donate buyer).
Autosell is a separate donate perk: the player chooses when to turn in resources — on pickup, when opening the buyer menu, or chest contents when opening a container. Categories, notifications, and minimum price are configurable.
The catalog does not stagnate: on a timer the set of buyable items changes, market coefficients reset, and players get a chat notification. At the bottom of the menu — a live stats panel: time until rotation, sold today, how many resources are currently in rotation.
Features
Why put it on your server:
- Out of the box — ~380 items, GUI, rotation, market, and lang (ru/en/fi) from first start; no manual config wrangling
- Everything configurable — prices, catalog, GUI slots, permissions, market limits, rotation, autosell, economy; texts in
lang/, numbers in config.yml / items.yml
- GUI over commands — selling, filters, sorting, quantity, autosell; commands are aliases only
- Live market — price drops from mass turn-ins, decay returns to normal; player sees the coefficient in lore
- Catalog rotation — timer picks a new set from the pool; chat notification; open menus refresh in place
- Donate buyer — Vault + PlayerPoints: two menus (
/buyer and /donbuyer) or one buyer paid entirely in points; two flags in config
- Autosell — donate perk: pickup / menu / chest; categories, min price, notifications; in dual mode — choose payout (coins or points)
- Boosters — temporary buff shop in the buyer menu; paid with progression points, Vault, or PlayerPoints (configurable)
- Personal sell limits — daily cap per item-id (anti-dumping); LuckPerms nodes and limit booster
- Progression — points, category XP, VIP multipliers via LuckPerms; incentive to farm, not just loot
- Live stats — timer until rotation, “sold today”, assortment size right in the menu (+ PlaceholderAPI)
- Category animation — filter icons cycle real items from the current rotation
- Optimized — all DB I/O async; main thread never blocked; HikariCP; Redis only when the network needs it
- Storage choice —
flat / sqlite / mysql + Redis for multiple Paper servers sharing one market
- Folia-ready — region-aware schedulers on hot paths; no legacy
BukkitScheduler for sync logic
- Safe sales — secure storage per transaction; on error or disconnect items are returned
- API for other plugins —
SoulBuyerApi: menus, quotes, selling from your own GUI, item categories, progress
- Automatic player language detection (CLIENT/SERVER locale in config) — v1.4.0
- Optional bStats metrics (opt-out in config) — v1.4.0
Buyer GUI
| Zone |
What it does |
| Top row |
Category filters + “Your progress” block (points, multiplier) |
| 21-slot grid |
Buyable item icons: price, points, market, amount in inventory. LMB — sell all, RMB — quantity submenu |
| ← → arrows |
Pagination (4th row, on the sides of the grid) |
| Bottom row |
Sort (single toggle button), “sell all”, boosters, autosell, “Until rotation” panel |
| Categories |
“All” — Vault icon (storage); others — live animation: icon changes and shows a real item from that category’s current assortment |
Sorting (comparator, click — next mode): highest price → lowest → most points → least points.
Boosters (nether star in bottom row): LMB — temporary buff shop. Available from regular and donate menus. Details in Boosters.
Autosell (emerald in bottom row): LMB — settings screen, RMB — on/off. Details in Autosell.
Texts and colors — in lang/ru.yml, lang/en.yml, lang/fi.yml. Hex colors, gradient title, lore for categories and items — all without rebuilding the JAR.
Menu icons (smithing templates, armor trims)
In gui/buyer.yml → hideVanillaItemTooltip: true (default): tooltip shows only SoulBuyer lore — no vanilla “Smithing Template”, “Applies to”, attributes, etc.
| Item type |
How it appears in the slot |
| Regular resources |
Item icon + your lore |
| Armor trims (bolt, flow, coast…) |
Iron chestplate with trim pattern |
| Netherite Upgrade |
Netherite ingot |
How to verify after an update
- Build the JAR, replace on the server, restart.
- Open
/buyer → “Misc” category (or wherever trims are in rotation).
- Slot should show trim on chestplate, not a plain gray chestplate without pattern.
- Hover — only SoulBuyer name and price, no vanilla clutter.
- Same in autosell: emerald → RMB on category → trims with pattern.
If the icon is still wrong
plugins/SoulBuyer/gui/buyer.yml must have hideVanillaItemTooltip: true.
- Client 1.21+; turn off F3+H (advanced tooltips confuse things).
- Admin:
config.yml → debug-tooltip: true → /soulbuyer admin reload → /soulbuyer admin debug-tooltip → /buyer. Keep false on production (default).
Autosell
Separate donate mechanic (soulbuyer.autosell, OP by default). The player configures behavior — settings are saved per-player (YAML or MySQL).
When to sell
One of three modes (toggle button in settings menu):
| Mode |
Icon |
When it triggers |
| On pickup |
Hopper |
Item enters inventory from the ground or fishing |
| On menu open |
Emerald |
Buyer GUI opens — sells everything matching from player inventory |
| On chest open |
Chest |
Container opens — sells everything matching from chest slots. Player inventory untouched |
Works with chest, barrel, shulker, ender chest, hopper, dispenser, dropper, minecart with chest. Respects enabled categories, item selection, min price, and current rotation (only item-ids currently in the buyer are sold).
Other settings
| Option |
Meaning |
| On/off |
Master switch (center of menu or RMB on emerald in buyer) |
| Categories |
Ores, mobs, plants, blocks, misc — LMB toggles whole category |
| Items in category |
RMB on category icon → selection screen: which item-ids from that category to autosell |
| Notifications |
Action bar / chat / off |
| Min price |
Do not sell items below threshold (after market and multipliers) |
| Payout target |
Dual buyer only: regular buyer (Vault) or donate (PlayerPoints). Click ingot in center of row 4 |
Per-item selection in a category
After enabling a category, all items in that category from the current rotation autosell by default. To keep only bones from “Mobs” or only diamonds from “Ores”:
- Autosell menu → RMB on the category.
- Grid opens with only active item-ids (as in
/buyer now).
- Click item — toggle autosell for it (highlight = enabled).
- Cannot disable the last enabled item in an active category.
If an item drops out of rotation — it is not shown in selection and is not autosold, even if it was enabled before. After it returns to rotation, the player’s setting is preserved (unless the id is in the disabled list).
Example: “Mobs” enabled → RMB → disable everything except bone → on pickup/chest/menu only mob bones sell (and only while bones are in rotation).
Player settings storage
Per-player in data/autosell/{uuid}.yml (flat) or column settings in table soulbuyer_autosell (MySQL). Text format:
enabled=true
trigger=pickup
notify=actionbar
min-unit-price=0
payout=vault
categories=ores,mobs,plants,blocks,misc
disabled-items=bone,rotten_flesh
| Key |
Meaning |
categories |
Enabled categories (comma-separated) |
disabled-items |
Item-ids excluded from autosell within enabled categories. Empty = all active category items |
Other keys — trigger mode, notifications, min price, payout.
Book slot — short in-game help. If nothing to sell in inventory, no extra chat spam.
In both buyer menus (regular and /donbuyer) the autosell button shows current payout mode; configuration is in the same autosell screen whether entered from either menu.
Why servers use it
- Donate perk without pay-to-win: same prices and market, less grind.
- Base sorting: “chest” mode — open storage, junk inside sells instantly, useful stuff stays in the chest.
- AFK farm: “pickup” mode — picked up resource is already sold.
- Casual players: “menu” mode — opened
/buyer, excess sold automatically.
In config.yml → autosell section: enable/disable feature server-wide, defaults for new players, min price steps, delay after pickup.
Boosters
Shop for temporary buffs — opened from regular (/buyer) and donate (/donbuyer) menus: “Boosters” button (nether star) → separate screen with three offers.
Purchase debits currency from config.yml → boosters.currency:
| Value |
Debit |
progression_points |
SoulBuyer points (default — earned from sales, previously had nowhere to spend) |
vault |
Coins via Vault |
playerpoints |
PlayerPoints |
Three boosters (defaults, all in config)
| ID |
Effect |
Duration |
Price (default) |
multiplier |
+0.5 to personal income multiplier |
1 h |
125 points |
money |
×1.25 to coins/points from sale |
1 h |
175 points |
limit |
×2 to personal daily limit per item-id |
30 min |
75 points |
Prices, duration, effect strength, materials and GUI slots — in config.yml → boosters.offers and gui/boosters.yml.
Each booster button lore shows: effect, price, duration, whether active now and time left. Re-buying refreshes the timer for that type.
Sell limits (linked to limit booster)
Parallel anti-dumping mechanic — sell-limits section in config.yml:
- Each player has a daily limit per
item-id (default 64/day).
- LuckPerms nodes
soulbuyer.limit.vip / soulbuyer.limit.premium raise cap (128 / 256).
- Limit booster multiplies the final limit.
sell-limits.enabled: false — limits fully disabled.
When limit exceeded, sale is trimmed to allowed amount; excess returns to inventory.
Permissions and fresh install
| Node |
Access |
soulbuyer.boosters |
Booster shop (default: true) |
Java defaults: boosters enabled, currency — progression points, all three offers and GUI in place after first start. Active boosters saved per-player (data/boosters/ or table soulbuyer_boosters).
PlayerPoints and donate buyer
SoulBuyer is not Vault-only. With PlayerPoints on the server, the plugin pays for resources in donate points — no hacks, separate commands, same market, rotation, and progression.
One catalog items.yml, one set of prices and coefficients — only payout currency changes (server coins or PlayerPoints).
Three modes (economy section in config.yml)
player-points-enabled |
donate-buyer-enabled |
What the player sees |
false |
— |
Classic: /buyer → payout in Vault |
true |
false |
One buyer: /buyer → everything in PlayerPoints (Vault not required) |
true |
true |
Two buyers: regular for coins + donate for points |
economy:
player-points-enabled: false # enable PlayerPoints
donate-buyer-enabled: false # true = second menu paid only in points
On Folia without Vault, install PlayerPoints and set player-points-enabled: true, or the plugin auto-switches if Vault is missing but PlayerPoints is present.
Two buyers — why it matters
Donate servers often split economy: farm → coins, donate content → points. SoulBuyer covers both with one JAR:
| Menu |
Command |
Payout |
Who |
| Regular |
/buyer, /sell, /soulbuyer |
Vault (coins) |
Everyone with soulbuyer.use |
| Donate |
/donbuyer, /dbuyer, /ppbuyer |
PlayerPoints |
With soulbuyer.donate |
- Same assortment and live market — price drops from mass sales in both menus.
- Progression points and category XP accrue as usual (meta-progress, not payout currency).
- Separate title and lore on donate menu — player sees points payout immediately.
- Autosell follows player setting: in dual mode — Vault or PlayerPoints; PlayerPoints-only mode — always points.
Fresh install
Java defaults: PlayerPoints off, Vault only — as before. Enable with two lines in config.yml, restart. /donbuyer and aliases are in plugin.yml; if donate mode is off, /donbuyer replies that the feature is unavailable.
Dependencies
| Plugin |
When needed |
| Vault + economy |
Default; required in dual mode and classic mode |
| PlayerPoints |
player-points-enabled: true |
Both are softdepend in plugin.yml: plugin starts, waits for the needed economy, then opens GUI.
Dynamic market
- Each resource has a base price and market coefficient (starts at 1.0).
- Mass sales lower the coefficient down to configured minimum.
- Decay gradually returns price to 1.0 if the resource stops being sold.
- In mysql + network mode, coefficients sync via Redis pub/sub.
Player sees market multiplier in item lore in the GUI.
Catalog rotation
Full catalog (~380 vanilla resources in items.yml) is the pool. The buyer shows a random subset at once (default 48 items, minimum from each category).
| Parameter |
Default |
Meaning |
catalog-rotation.enabled |
true |
Rotation on/off |
interval-seconds |
3600 |
Change interval (1 hour) |
active-item-count |
48 |
Items in menu |
reset-market-on-rotation |
true |
Reset market coefficients on change |
notify.enabled |
true |
Chat message on update |
Rotation state in data/rotation.yml. Open menus refresh without closing.
Stats panel (bottom center)
Instead of “Page 1/3” — clock with live timer (updates every second):
- Until rotation — time left until next rotation
- Sold today — coins, points, stacks
- In assortment — how many resources are in rotation now
Lore placeholders in lang:
| Placeholder |
Description |
{rotation_left} |
Timer until rotation or “disabled” / “soon” |
{sold_today_money} |
Coins today |
{sold_today_points} |
Points today |
{sold_today_stacks} |
Stacks sold |
{sold_alltime_money} |
Coins all time |
{sold_alltime_points} |
Points all time |
{sold_alltime_stacks} |
Stacks all time |
{active_items} |
Items in current assortment |
Progression
- Points per sale (from item
base-points + bonus from base price × points-per-currency).
- Category XP — grows from points earned; money bonus from XP levels (not raw number), capped by
max-category-bonus.
- Permission multipliers — VIP, Premium, etc. (highest granted wins).
- Dominant category bonus — extra income from main category XP level (
category-xp-per-level, dominant-category-bonus-per-level).
- Points can be spent in booster shop (if
boosters.currency: progression_points).
- Anti-exploit:
max-unit-price, max-payout-per-sale per transaction.
Safety and reliability
- Secure storage for transaction duration — items not lost on lag or error.
- On quit / failure — return unsold items to inventory.
- Sales logged (
sales.log or table soulbuyer_sales) — basis for “sold today” stats.
- All DB I/O async, main thread never blocked.
Data storage
| Mode |
When to use |
flat |
Single server, YAML + sales log (default) |
sqlite |
Single server, file data/data.db |
mysql |
Server network, shared DB + Redis for market |
Player progress, market coefficients, rotation, sales log — all survive restart.
Commands
Main: /soulbuyer. Menu aliases (configurable): /buyer, /sell, /sb, /rbuyer, /bs.
Donate buyer (only when economy.donate-buyer-enabled: true): /donbuyer. Aliases: /dbuyer, /ppbuyer, /donatesell.
| Command |
Action |
/soulbuyer |
Open buyer GUI (Vault or PlayerPoints — per economy mode) |
/buyer, /sell, … |
Same (aliases) |
/donbuyer, /dbuyer, … |
Donate menu — payout in PlayerPoints (dual mode) |
/soulbuyer admin reload |
Reload config, gui, lang |
Aliases inherit subcommands: /buyer admin reload = /soulbuyer admin reload.
Permissions
| Node |
Access |
soulbuyer.use |
GUI and selling (regular buyer) |
soulbuyer.donate |
Donate menu /donbuyer (PlayerPoints, dual mode) |
soulbuyer.admin |
/soulbuyer admin reload |
soulbuyer.autosell |
Autosell (donate, OP by default) |
soulbuyer.boosters |
Booster shop (default: true) |
soulbuyer.limit.vip |
Daily sell limit 128/item-id |
soulbuyer.limit.premium |
Daily sell limit 256/item-id |
soulbuyer.multiplier.vip |
Multiplier ×1.1 (default) |
soulbuyer.multiplier.premium |
Multiplier ×1.25 (default) |
With multiple multiplier nodes, the highest multiplier applies.
PlaceholderAPI
softdepend — if PAPI is on the server, expansion soulbuyer registers.
| Placeholder |
Description |
%soulbuyer_rotation_left% |
Timer until rotation (text) |
%soulbuyer_rotation_seconds% |
Seconds until rotation (number) |
%soulbuyer_sold_today_money% |
Coins sold today |
%soulbuyer_sold_today_points% |
Points today |
%soulbuyer_sold_today_stacks% |
Stacks sold today |
%soulbuyer_sold_alltime_money% |
Coins sold all time |
%soulbuyer_sold_alltime_points% |
Points all time |
%soulbuyer_sold_alltime_stacks% |
Stacks sold all time |
%soulbuyer_active_items% |
Items in current assortment |
PAPI placeholders can go in lang/*.yml strings — they resolve when rendering the GUI.
Configuration
| File |
Contents |
config.yml |
Storage, market, rotation, progression, boosters, sell limits, permissions, category icon animation, locale, check-for-updates, bstats |
items.yml |
Catalog: id, material, category, base-price, base-points |
gui/general.yml, gui/buyer.yml, gui/quantity.yml, gui/autosell.yml, gui/boosters.yml |
Slots, button materials, action types |
lang/en.yml, lang/ru.yml, lang/fi.yml |
Bundled locales: titles, lore, messages, hex colors |
lang/*.yml (on disk) |
Custom locales — copy bundled file or add e.g. lang/de.yml; any *.yml in lang/ loads on startup and reload |
data/rotation.yml |
Current rotation and next change time |
data/market.yml |
Market coefficients (flat mode) |
data/players/ |
Player progress (flat mode) |
data/boosters/ |
Active player boosters (flat mode) |
data/sell-limits/ |
Today’s sales per item-id (flat mode) |
Defaults are in Java — after first start everything works out of the box: ~380 items, rotation, GUI, catalog, stats.
Language (config.yml → locale)
| Key |
Purpose |
locale-mode |
CLIENT (default) — each player’s Minecraft language; SERVER — one language for everyone |
server-locale |
Used only when locale-mode: SERVER (e.g. ru, en, fi, or custom code matching lang/<code>.yml) |
fallback-locale |
Missing keys and CLIENT fallback when no matching file (usually en) |
Bundled: lang/en.yml, lang/ru.yml, lang/fi.yml. Add custom files under plugins/SoulBuyer/lang/; reload with /soulbuyer admin reload.
Other config.yml keys
| Key |
Purpose |
check-for-updates |
Notify console when a new plugin version is available (default: true) |
bstats.enabled |
Anonymous metrics to bStats (default: true; set false to opt out) |
Key sections:
storage-type: flat # flat | sqlite | mysql
economy: # Vault / PlayerPoints / dual buyer
catalog-rotation: # timed assortment change
category-icon-animation: # live category icon rotation
market: # decay, min-coefficient, flush
progression: # multipliers, points, category XP, payout caps
boosters: # purchase currency, offers (price, effect, duration)
sell-limits: # daily limits, permission tiers
locale: # locale-mode, server-locale, fallback-locale
bstats: # enabled
check-for-updates: true
Roadmap
Requirements
| Component |
Required |
| Paper 1.21+ (Folia supported) |
yes |
| Java 21 |
yes |
| Vault + economy |
default; not needed if PlayerPoints only (player-points-enabled: true, donate-buyer-enabled: false) |
| PlayerPoints |
optional; required when player-points-enabled: true |
| MySQL + Redis |
only storage-type: mysql on a network |
| PlaceholderAPI |
optional |
Public API
Interface SoulBuyerApi registers in Bukkit ServicesManager. Another plugin connects via depend or softdepend: [SoulBuyer].
Getting the API
import bm.b0b0b0.soulBuyer.api.SoulBuyerApi;
import bm.b0b0b0.soulBuyer.api.SoulBuyerApiProvider;
import bm.b0b0b0.soulBuyer.api.SoulBuyerSellDelivery;
import bm.b0b0b0.soulBuyer.api.SoulBuyerSellReturnPolicy;
import org.bukkit.Bukkit;
SoulBuyerApi api = SoulBuyerApiProvider.get();
// or: Bukkit.getServicesManager().load(SoulBuyerApi.class)
if (!api.isReady()) {
return;
}
SoulBuyerApiProvider.get() always returns an object: if SoulBuyer is not ready yet — stub with isReady() == false and no-op methods.
Method reference
| Method |
Returns |
Description |
isReady() |
boolean |
Plugin loaded, catalog and economy ready |
openBuyerMenu(Player) |
— |
Open standard buyer GUI |
quoteItem(Player, itemId) |
Optional<ItemUnitQuote> |
Price and points for 1 unit with market, multipliers, inventory amount |
quoteStack(Player, ItemStack) |
Optional<ItemUnitQuote> |
Same for item in hand / slot |
marketCoefficient(itemId) |
double |
Current market coefficient (1.0 = base) |
cachedPoints(Player) |
double |
Progression points from cache |
cachedMultiplier(Player) |
double |
Total personal multiplier (permission × category + boosters) |
cachedCategoryXp(Player, categoryId) |
double |
Category XP from cache |
fetchProgress(UUID) |
CompletableFuture<PlayerProgress> |
Async load progress from storage; updates cache |
isSellable(itemId) |
boolean |
Item in items.yml pool |
isInActiveCatalog(itemId) |
boolean |
Item in current rotation |
activeCatalogSize() |
int |
Items in rotation now |
categoryId(itemId) |
Optional<String> |
Category from items.yml (ores, mobs, plants, blocks, misc, …) |
categoryId(ItemStack) |
Optional<String> |
Category by material + custom model data |
isAutosellFeatureEnabled() |
boolean |
Autosell enabled server-wide |
canUseAutosell(Player) |
boolean |
Player has autosell permission |
isAutosellEnabled(Player) |
boolean |
Player master autosell switch (not category/item details) |
isSaleInProgress(Player) |
boolean |
Sale transaction in progress (secure storage busy) |
sellAll(Player) |
boolean |
Sell all buyable from inventory |
sellAll(Player, Runnable) |
boolean |
Same + callback on completion |
sellAll(Player, SoulBuyerSellDelivery, Runnable) |
boolean |
Sale with notification channel choice |
sellItem(Player, itemId) |
boolean |
Sell all of item-id from inventory |
sellItem(Player, itemId, Runnable) |
boolean |
Same + callback |
sellItemAmount(Player, itemId, amount, Runnable) |
boolean |
Sell specified amount from inventory |
sellStacks(Player, stacks) |
boolean |
Sell given stacks (see below) |
sellStacks(Player, stacks, Runnable) |
boolean |
Same + callback |
sellStacks(Player, stacks, returnPolicy, delivery, Runnable) |
boolean |
Full control of return policy and notifications |
Sell methods return false if API not ready, player null, list empty, or another sale in progress. true — transaction accepted; check callback and player messages for result.
Models
ItemUnitQuote — unitPrice, unitPoints, marketCoefficient, playerMultiplier, inventoryAmount.
PlayerProgress — playerId, points, categoryXp (map categoryId → XP).
Selling from inventory
sellAll, sellItem, sellItemAmount work like SoulBuyer GUI buttons: take items from player inventory, apply limits, boosters, market, progression, payout (Vault / PlayerPoints per config). On error, unsold items return to inventory.
if (api.isSaleInProgress(player)) {
return;
}
api.sellAll(player, SoulBuyerSellDelivery.ACTION_BAR, () -> {
// main thread, after transaction completes
player.sendMessage("Done!");
});
Selling from your GUI — sellStacks
For a custom menu with “Sell all” button:
- Build
List<ItemStack> from your GUI slots.
- Filter by category via
categoryId if needed.
- Remove stacks from GUI before call (with
CALLER_OWNS_ITEMS).
- Call
sellStacks.
SoulBuyer calculates price, limits, boosters, points, category XP and pays the player. Multiple stacks in one call — one transaction.
List<ItemStack> toSell = new ArrayList<>();
for (ItemStack stack : guiSlots) {
if (stack == null || stack.isEmpty()) {
continue;
}
api.categoryId(stack).filter("ores"::equals).ifPresent(category -> toSell.add(stack.clone()));
}
if (toSell.isEmpty() || api.isSaleInProgress(player)) {
return;
}
// remove toSell from your GUI before call
boolean started = api.sellStacks(
player,
toSell,
SoulBuyerSellReturnPolicy.CALLER_OWNS_ITEMS,
SoulBuyerSellDelivery.SILENT,
() -> refreshMyGui(player)
);
if (!started) {
// return items to GUI manually
}
SoulBuyerSellReturnPolicy |
Behavior on cancel / error |
RETURN_TO_PLAYER |
Default. Unsold returned to player inventory |
CALLER_OWNS_ITEMS |
SoulBuyer does not touch items — your plugin rolls back GUI |
SoulBuyerSellDelivery |
Player notification |
CHAT |
Chat message (default) |
ACTION_BAR |
Action bar |
SILENT |
No SoulBuyer messages |
Some stacks may not sell due to daily limit — excess returns to player (or stays with caller under CALLER_OWNS_ITEMS).
Categories — categoryId
Category comes from category field in items.yml for each item-id. Typical values: ores, mobs, plants, blocks, misc. Custom ids are fine — must match GUI filters and autosell.
api.categoryId("raw_iron"); // Optional["ores"]
api.categoryId(player.getInventory().getItemInMainHand()); // by material + CMD
api.isSellable("raw_iron"); // true if id in pool
api.isInActiveCatalog("raw_iron"); // true if currently in rotation
Progress cache
cachedPoints / cachedMultiplier / cachedCategoryXp read memory. After join data loads async; for exact values before opening menu call fetchProgress(uuid).join() or wait for callback.
fetchProgress is safe from async threads; mutate Bukkit API from its callback only via runTask.
Autosell and API: category and per-item selection is configured only through SoulBuyer GUI (gui/autosell.yml). No toggleAutosellItem / getDisabledItems in SoulBuyerApi — for custom menus use sellStacks and your own filtering via categoryId / isInActiveCatalog.
Dependency in plugin.yml
softdepend: [SoulBuyer]
or depend: [SoulBuyer] if your plugin cannot work without the buyer.
评论 0
登录后参与评分
还没有评论,来抢沙发吧