SoulBuyer

插件

· 作者 b0b0b0

具有动态价格、图形用户界面(GUI)、自动出售和增益效果的资源购买器。

0 本站下载 0 关注 更新于 4 天前

最新 1.4.5 · 26.3 · Folia / Paper

一键开服(送7天)

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 的描述 — 没有原版“锻造模板”、“应用于”、属性等。

物品类型 在槽位中的显示方式
常规资源 物品图标 + 你的描述
盔甲纹饰(螺栓、流动、海岸…) 带有纹饰图案的铁胸甲
下界合金升级 下界合金锭

更新后的验证方法

  1. 构建 JAR,替换到服务器,重启。
  2. 打开 /buyer → “Misc” 类别(或者纹饰在轮换中的位置)。
  3. 槽位应显示带纹饰的胸甲,而不是没有图案的普通灰色胸甲。
  4. 悬停 — 只显示 SoulBuyer 名称和价格,没有原版的杂乱信息。
  5. 自动出售中同样适用:绿宝石 → 鼠标右键 (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 行中间的锭即可切换

类别内单项选择

启用某个类别后,默认情况下当前轮换列表中该类别的所有物品都会自动出售。若只想保留“生物”类别中的骨头或“矿石”类别中的钻石:

  1. 进入自动出售菜单 → 对类别图标执行 右键。
  2. 打开网格界面,其中仅显示当前有效的物品 ID(与 /buyer 命令中一致)。
  3. 点击物品 —— 切换其自动出售状态(高亮表示已启用)。
  4. 无法禁用活动类别中最后一个已启用的物品。

如果某物品退出轮换列表——它将不会出现在选择界面中,且不会自动出售,即使之前已启用。当它重新回到轮换列表时,玩家的设置将被保留(除非该 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

对于带有“全部出售”按钮的自定义菜单:

  1. 从你的 GUI 槽位构建 List<ItemStack>。
  2. 如有需要,通过 categoryId 按分类进行过滤。
  3. 在调用前从 GUI 中移除物品堆(使用 CALLER_OWNS_ITEMS 策略)。
  4. 调用 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]。

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源