现金返还
适用于 Paper 1.20.6–26.3 和 Purpur 1.21.11 / 26.3 的金库(Vault)现金返还周期 · Java 21+
玩家在你的商店消费以填充进度条。当进度条满时,现金返还将处于激活状态,系统会通过 Vault 自动退还他们下一次购买金额的一定比例。当配额耗尽后,周期重置并重新开始填充。
周期工作原理
- FILL(填充) — 消费为进度条增加数值。这些消费不会触发现金返还。
- ACTIVATE(激活) — 达到 100% 时,进度条解锁现金返还配额。
- PAYOUT(支付) — 在激活状态下进行的每次购买都会按配置的比例(默认为 30%)进行返还。
- RESET(重置) — 当配额降至零时,周期重新开始。
功能特性
- 无需优惠券、等级或手动发放奖励即可重复激励消费。
- 防崩溃支付 — 每次支付都在数据库中标记为已领取,然后再执行 Vault 存款,从而防止崩溃后出现重复支付。使用
/cb admin recover 结算遗留款项。可能已经支付的款项将被阻止,直到你使用 force 确认它们。
- 无重复计数 — 一次购买对应一次支付,即使商店插件触发了多个事件也是如此。
- 大额消费全额计入 — 价值超过多个周期的购买会被精确计算,不会被截断。
- 通过权限节点实现按等级的目标和现金返还率,支持 LuckPerms。
- 可选的结转功能 — 超出阶段限制的数值可以延续到下一阶段,而不是被丢弃。
- 管理员诊断 —
/cb admin health 显示金库提供商、商店适配器、待处理支付、周期设置、等级、存储以及服务器/Java 信息;/cb admin history <player> 列出最近 10 笔交易及其商店来源。
- 重置保留终身累计 —
/cb admin reset 仅清除当前周期。
要求
平台支持: 这是一个 Paper 插件。由于它使用 Paper API 和 plugin.yml 库加载器,因此不能在 Spigot 或 CraftBukkit 上运行。不支持 Folia。
安装
- 将
Cashback.jar 放入服务器的 /plugins 文件夹并重启服务器。
- 确保已安装 Vault 和一个经济插件。
- 如果需要更改目标值或返还率,请编辑
plugins/Cashback/config.yml。
- 运行
/cb admin health,它将一次性检查金库、商店适配器、待处理支付、周期和存储的状态。
- 在你的商店购买一些物品,然后检查
/cb status。
命令
| 命令 |
描述 |
/cb |
显示你的现金返还进度条。 |
/cb status |
显示带有配额详情的进度条。 |
/cb history |
显示你最近的 5 次支付记录。 |
/cb version |
显示插件版本、服务器、Java 版本、适配器和存储信息。 |
/cb admin health |
显示商店适配器的状态。 |
/cb admin inspect <player> |
检查玩家的周期状态和等级。 |
/cb admin reset <player> |
重置玩家的周期。 |
/cb admin recover [force] |
结算因崩溃而挂起的支付。 |
/cb admin reload |
重新加载配置文件和语言文件。 |
/cb admin history <player> |
查看最近交易,包括商店来源 |
权限
| 权限 |
默认值 |
描述 |
cashback.use |
true |
使用 /cb、/cb status 和 /cb history。 |
cashback.admin |
op |
访问所有管理员命令。 |
cashback.admin.help |
— |
访问 /cb help。 |
cashback.admin.version |
— |
访问 /cb version。 |
cashback.admin.reload |
— |
访问 /cb admin reload。 |
cashback.admin.history |
— |
访问 /cb admin history <player>。 |
cashback.admin.health |
— |
访问 /cb admin health。 |
cashback.admin.inspect |
— |
访问 /cb admin inspect <player>。 |
cashback.admin.reset |
— |
访问 /cb admin reset <player>。 |
cashback.admin.recover |
— |
访问 /cb admin recover [force]。 |
cashback.rank.<name> |
— |
设置特定等级的目标和现金返还率。在 ranks.groups 下配置等级。 |
商店集成
- EconomyShopGUI — 支持免费版和高级版。
- UltimateShop — 版本 3.6.3 或更高。只有价格中的 Vault 部分会计入现金返还。
- 使用物品、经验值、PlayerPoints 或其他经济方式支付的消费不会产生现金返还。
- 如果检测到未知的商店插件,Cashback 将保持空闲状态,而不是猜测其行为。
配置示例
config.yml
config-version: 5
language:
default: en
fallback: en
directory: lang
cycle:
fill-target: 500000.0 # 达到 100% 所需的商店消费金额
cashback-target: 500000.0 # 在 ACTIVE 状态下赚取现金返还所需的消费金额
cashback-rate: 30.0 # 返还百分比 (0-100)
carry-over: false # true: 超出阶段限制的数值将延续到下一阶段
ranks:
enabled: false
groups:
vip:
permission: cashback.rank.vip
priority: 10
cashback-rate: 35.0
mvp:
permission: cashback.rank.mvp
priority: 20
cashback-rate: 40.0
fill-target: 400000.0
cashback-target: 600000.0
notifications:
activated:
action-bar: true
chat: true
sound:
enabled: true
name: "minecraft:block.beacon.activate"
volume: 1.0
pitch: 1.2
deactivated:
action-bar: true
chat: true
sound:
enabled: true
name: "minecraft:block.beacon.deactivate"
volume: 1.0
pitch: 1.0
earned:
chat: true
integrations: # 修改这些配置需要重启服务器
economyshopgui:
enabled: true
ultimateshop:
enabled: true
history:
retention-days: 365 # 超过此天数的已完成条目会每天被删除;0 = 永久保留
metrics:
enabled: true
故障排除
常见问题
“No Vault economy provider registered yet”(尚未注册任何 Vault 经济提供商)
已安装 Vault,但没有经济插件注册提供商。请安装一个经济插件,例如 EssentialsX 或 CMI,或者检查它是否在 Cashback 之前加载。
未支付返利
运行 /cb admin health 查看适配器名称。如果显示 none,可能是商店插件缺失或其 API 类未被找到。同时确认购买是使用 Vault 货币支付的,而不是物品或经验值。
崩溃后出现重复或缺失的支付记录
运行 /cb admin recover 并将其结果与经济日志进行对比。可能已经支付的行会被报告为已阻止(blocked)。仅在检查经济日志后使用 /cb admin recover force。
玩家进度持续但收到无支付
这是设计上的 FILLING(积累)阶段。只有在周期处于 ACTIVE(活跃)状态时才会支付返利。
在旧版 EconomyShopGUI 上更新至 1.3.3 后返利停止
不暴露经济类型的旧版本不再自动支付。如果所有商店价格都使用 Vault,请设置 integrations.economyshopgui.allow-legacy-pricing: true,然后运行 /cb admin reload。
/cb admin health 提示 ATTENTION(注意)
阅读其下方的内容:没有 Vault 经济提供商、没有商店适配器,或有待处理的支付记录。每一行都指出了需要修复的部分。
语言
包含英文和印尼语。语言文件位于 plugins/Cashback/lang,且永远不会被覆盖。当插件更新时,会自动添加新的键。
支持
请在讨论区发帖并提供以下信息:
- 服务器软件及版本
- 通过
/cb version 获取的 Cashback 版本
- 商店插件及版本
- 相关的控制台输出
Cashback
Vault cashback cycles for Paper 1.20.6–26.3 and Purpur 1.21.11 / 26.3 · Java 21+
Players spend money at your shop to fill a progress bar. When the bar is full, cashback becomes ACTIVE, and a percentage of their next purchases is automatically paid back through Vault. When the quota runs out, the cycle resets and filling starts again.
How a Cycle Works
- FILL — Purchases add value to the progress bar. These purchases do not pay cashback.
- ACTIVATE — At 100%, the progress bar unlocks a cashback quota.
- PAYOUT — Every purchase while ACTIVE pays back the configured percentage, 30% by default.
- RESET — When the quota reaches zero, the cycle starts again.
Features
- Rewards repeat purchases without coupons, ranks or manual giveaways.
- Crash-safe payouts — Every payout is claimed in the database before the Vault deposit, preventing duplicate payments after a crash. Use
/cb admin recover to settle anything left over. Payouts that may already have been paid are blocked until you confirm them with force.
- No double counting — One purchase equals one payout, even if a shop plugin fires several events.
- Large purchases count in full — A purchase worth several cycles is calculated exactly and is never truncated.
- Per-rank targets and cashback rates through permission nodes, with LuckPerms support.
- Optional carry-over — Value that passes a stage limit can continue into the next stage instead of being discarded.
- Admin diagnostics —
/cb admin health shows the Vault provider, shop adapters, pending payouts, cycle settings, ranks, storage and server/Java; /cb admin history <player> lists the last 10 transactions with the shop source.
- Reset keeps lifetime earned —
/cb admin reset clears the cycle only.
Requirements
Platform support: This is a Paper plugin. It does not run on Spigot or CraftBukkit because it uses the Paper API and the plugin.yml libraries loader. Folia is not supported.
Installation
- Drop
Cashback.jar into the server's /plugins folder and restart the server.
- Make sure Vault and an economy plugin are installed.
- Edit
plugins/Cashback/config.yml if you want to use different targets or rates.
- Run
/cb admin health it checks Vault, shop adapters, pending payouts, cycle and storage in one place.
- Buy something in your shop and check
/cb status.
Commands
| Command |
Description |
/cb |
Show your cashback progress bar. |
/cb status |
Show your progress bar with quota details. |
/cb history |
Show your last 5 payouts. |
/cb version |
Show the plugin version, server, Java version, adapters, and storage. |
/cb admin health |
Show the status of shop adapters. |
/cb admin inspect <player> |
Inspect a player's cycle state and rank. |
/cb admin reset <player> |
Reset a player's cycle. |
/cb admin recover [force] |
Settle payouts left pending by a crash. |
/cb admin reload |
Reload the configuration and language files. |
/cb admin history <player> |
last transactions, including shop source |
Permissions
| Permission |
Default |
Description |
cashback.use |
true |
Use /cb, /cb status, and /cb history. |
cashback.admin |
op |
Access all admin commands. |
cashback.admin.help |
— |
Access /cb help. |
cashback.admin.version |
— |
Access /cb version. |
cashback.admin.reload |
— |
Access /cb admin reload. |
cashback.admin.history |
— |
Access /cb admin history <player>. |
cashback.admin.health |
— |
Access /cb admin health. |
cashback.admin.inspect |
— |
Access /cb admin inspect <player>. |
cashback.admin.reset |
— |
Access /cb admin reset <player>. |
cashback.admin.recover |
— |
Access /cb admin recover [force]. |
cashback.rank.<name> |
— |
Set the target and cashback rate for a rank. Configure ranks under ranks.groups. |
Shop Integrations
- EconomyShopGUI — Free and Premium versions are supported.
- UltimateShop — Version 3.6.3 or newer. Only the Vault portion of a price counts toward cashback.
- Purchases paid with items, EXP, PlayerPoints, or other economies do not produce cashback.
- If an unknown shop plugin is detected, Cashback remains idle instead of guessing.
Configuration Example
config.yml
config-version: 5
language:
default: en
fallback: en
directory: lang
cycle:
fill-target: 500000.0 # shop purchases needed to reach 100%
cashback-target: 500000.0 # purchase value that earns cashback while ACTIVE
cashback-rate: 30.0 # percent paid back (0-100)
carry-over: false # true: value beyond a stage limit continues into the next stage
ranks:
enabled: false
groups:
vip:
permission: cashback.rank.vip
priority: 10
cashback-rate: 35.0
mvp:
permission: cashback.rank.mvp
priority: 20
cashback-rate: 40.0
fill-target: 400000.0
cashback-target: 600000.0
notifications:
activated:
action-bar: true
chat: true
sound:
enabled: true
name: "minecraft:block.beacon.activate"
volume: 1.0
pitch: 1.2
deactivated:
action-bar: true
chat: true
sound:
enabled: true
name: "minecraft:block.beacon.deactivate"
volume: 1.0
pitch: 1.0
earned:
chat: true
integrations: # changing these needs a restart
economyshopgui:
enabled: true
ultimateshop:
enabled: true
history:
retention-days: 365 # finished entries older than this are deleted daily; 0 = keep forever
metrics:
enabled: true
Troubleshooting
Common issues
“No Vault economy provider registered yet”
Vault is installed, but no economy plugin has registered a provider. Install an economy plugin such as EssentialsX or CMI, or check that it loaded before Cashback.
Cashback is not paid
Check /cb admin health for the adapter names. If it shows none, the shop plugin may be missing or its API class may not have been found. Also confirm that the purchase was paid with Vault money, not items or EXP.
Duplicate or missing payouts after a crash
Run /cb admin recover and compare the result with your economy log. Rows that may already have been paid are reported as blocked. Only use /cb admin recover force after checking the economy log.
Players keep progress but receive no payout
This is the FILLING phase by design. Cashback is paid only while the cycle is ACTIVE.
Cashback stopped after updating to 1.3.3 on an old EconomyShopGUI
Old versions that do not expose an economy type no longer pay automatically. If every shop price uses Vault, set integrations.economyshopgui.allow-legacy-pricing: true, then run /cb admin reload.
/cb admin health says ATTENTION
Read the lines below it: no Vault economy provider, no shop adapter, or pending payouts. Each line names the part to fix.
Languages
English and Indonesian are included. Language files are located in plugins/Cashback/lang and are never overwritten. New keys are added automatically when the plugin is updated.
Support
Please post in the discussion tab with the following information:
- Server software and version
- Cashback version from
/cb version
- Shop plugin and version
- Relevant console lines
评论 0
登录后参与评分
还没有评论,来抢沙发吧