mCodes
适用于 Paper、Purpur 和 Folia 的交易型促销与推荐码,具备持久化的奖励机制。
mCodes 提供开箱即用的促销码和双向推荐奖励。限额、资格认定以及奖励记录均写入同一个 H2 事务中,从而防止并发兑换导致活动超发。
功能特性
- 创建不区分大小写的促销码,支持全局、单玩家及可选的网络级限额。
- 支持延迟激活、过期时间、权限要求及最低游戏时长。
- 为被推荐玩家和推荐码持有者分别发放独立的指令奖励。
- 防止自我推荐、重复使用推荐码,以及在不同推荐人之间复用网络身份。
- 仅存储地址的带密钥 HMAC 哈希值;原始地址和密钥绝不会写入数据库。
- 在运行任何指令前,先原子性地认领所有奖励交易,防止崩溃后自动重复发放。
- 列出未解决的奖励交易,供工作人员手动重试或对账。
- 异步执行数据库操作,并在 Paper、Purpur 和 Folia 上安全地调度 Bukkit 操作。
- 包含英文和俄文界面,支持自动配置迁移及可选的 bStats 指标上报。
快速开始
- 将
mCodes-1.1.1.jar 放入服务器的 plugins 目录并重启。
- 保持生成的
security.identity-secret 私密且不被修改。
- 调整
plugins/mCodes/config.yml 中的奖励指令。
- 使用
/code create WELCOME 100 1 168 创建一个活动。
- 玩家通过
/code redeem WELCOME 进行兑换。
内置配置可立即生效:示例中的 WELCOME 限制为总共可使用 100 次,每位玩家限用 1 次,且在 168 小时后过期。
指令
/code redeem <code> — 兑换促销码或推荐码。
/refer — 创建或查看您的个人推荐码。
/refer <code> — 兑换其他玩家的推荐码。
/code create <code> <global-limit> [per-player] [expires-hours] [permission|-] [starts-hours] — 创建促销活动。若无需全局限额或过期限制请输入 0,若无需权限限制请输入 -。
/code info <code> 和 /code list — 检查活动信息。
/code enable <code> 和 /code disable <code> — 更改可用性而不删除历史记录。
/code pending — 列出待处理或已认领的奖励交易。
/code retry <transaction-uuid> — 重试仍处于待处理状态的交易。
/code resolve <transaction-uuid> — 将已手动对账的已认领交易标记为已交付。
/code reload — 重新加载并验证配置。
玩家默认拥有 mcodes.use 权限。管理指令需要 mcodes.admin 权限,该权限默认赋予服务器操作员(OP)。
语言与配置
默认选择英文。设置 language: ru_RU 并运行 /code reload 即可将界面切换为俄语。
anti-abuse.identity-enabled 控制带密钥的网络身份检查。referral-per-identity 默认为 1,而促销网络限额在未增加 promo-per-identity 之前处于禁用状态。最低游戏时长及所有控制台奖励指令均在生成的配置文档中说明。支持的占位符包括 {player}、{referrer} 和 {redeemer}。
更改 security.identity-secret 会导致与之前存储的身份哈希值的比较失效。请将其与数据库一起备份,切勿公开。
奖励恢复
成功的兑换首先会创建一条 PENDING(待处理)的记录条目。在运行任何控制台指令之前,交付过程会原子性地将其认领为 CLAIMED(已认领),随后标记为 DELIVERED(已交付)。待处理的条目可以安全地重试。已认领的条目意味着进程可能在指令运行期间停止,因此 mCodes 会将其保留供工作人员审查,以避免风险导致的货币或物品重复发放。
尽管 Minecraft 指令无法参与数据库事务,但仍建议尽可能将奖励指令设计为幂等的。
环境要求
- Java 25
- Paper, Purpur 或 Folia 26.3
无需经济、权限或外部数据库插件。奖励指令可以调用服务器上已安装的任何插件。
存储与隐私
活动、兑换记录及恢复日志存储在 plugins/mCodes/codes.mv.db 中。架构升级会自动运行。当 metrics.enabled 为 true 时,mCodes 会使用匿名 bStats 指标;您可以在配置中或通过全局 bStats 设置禁用它。代码、UUID、玩家名称、地址、身份哈希值和奖励内容绝不会发送至 bStats。
构建
./gradlew clean build
发布的 JAR 文件会写入到 build/libs/mCodes-1.1.1.jar。
本软件依据 MIT 许可证授权。
mCodes
Transactional promo and referral codes with durable rewards for Paper, Purpur, and Folia.
mCodes provides ready-to-use promo codes and two-sided referral rewards. Limits, eligibility and the reward journal are committed in one H2 transaction so concurrent redemptions cannot overspend a campaign.
What it does
- Creates case-insensitive promo codes with global, per-player and optional network limits.
- Supports delayed activation, expiry, permission requirements and minimum playtime.
- Gives separate command rewards to a referred player and the referral-code owner.
- Prevents self-referrals, repeated referral use and reuse of a network identity across different referrers.
- Stores only a keyed HMAC of an address; raw addresses and the secret are never written to the database.
- Claims every reward transaction before commands run, preventing automatic duplicate delivery after a crash.
- Lists unresolved reward transactions for explicit staff retry or reconciliation.
- Runs database work asynchronously and schedules Bukkit operations safely on Paper, Purpur and Folia.
- Includes English and Russian interfaces, automatic config migration and optional bStats metrics.
Quick start
- Put
mCodes-1.1.1.jar in the server's plugins directory and restart.
- Keep the generated
security.identity-secret private and unchanged.
- Adjust the reward commands in
plugins/mCodes/config.yml.
- Create a campaign with
/code create WELCOME 100 1 168.
- Players redeem it with
/code redeem WELCOME.
The bundled configuration works immediately: WELCOME in the example is limited to 100 total uses, one use per player, and expires after 168 hours.
Commands
/code redeem <code> — redeem a promo or referral code.
/refer — create or show your personal referral code.
/refer <code> — redeem another player's referral code.
/code create <code> <global-limit> [per-player] [expires-hours] [permission|-] [starts-hours] — create a promo campaign. Use 0 for no global limit or expiry and - when no permission is required.
/code info <code> and /code list — inspect campaigns.
/code enable <code> and /code disable <code> — change availability without deleting history.
/code pending — list pending or claimed reward transactions.
/code retry <transaction-uuid> — retry a transaction that is still pending.
/code resolve <transaction-uuid> — mark a manually reconciled claimed transaction as delivered.
/code reload — reload and validate configuration.
Players receive mcodes.use by default. Administrative commands require mcodes.admin, which defaults to server operators.
Language and configuration
English is selected by default. Set language: ru_RU and run /code reload to switch the interface to Russian.
anti-abuse.identity-enabled controls keyed network-identity checks. referral-per-identity defaults to one, while promo network limits are disabled until promo-per-identity is increased. Minimum playtime and all console reward commands are documented in the generated configuration. Supported placeholders are {player}, {referrer} and {redeemer}.
Changing security.identity-secret invalidates comparisons with previously stored identity hashes. Back it up with the database and never publish it.
Reward recovery
A successful redemption first creates a PENDING journal entry. Delivery atomically claims it as CLAIMED before any console command runs and then marks it DELIVERED. Pending entries can be retried safely. A claimed entry means the process may have stopped while commands were running, so mCodes leaves it for staff review instead of risking duplicate currency or items.
Reward commands should still be designed to be idempotent where possible because Minecraft commands cannot participate in a database transaction.
Requirements
- Java 25
- Paper, Purpur or Folia 26.3
No economy, permissions or external database plugin is required. Reward commands may call any plugin already installed on the server.
Storage and privacy
Campaigns, redemptions and the recovery journal are stored in plugins/mCodes/codes.mv.db. Schema upgrades run automatically. mCodes uses anonymous bStats metrics when metrics.enabled is true; disable it in the configuration or through the global bStats setting. Codes, UUIDs, player names, addresses, identity hashes and reward contents are never sent to bStats.
Build
./gradlew clean build
The release JAR is written to build/libs/mCodes-1.1.1.jar.
Licensed under the MIT License.
评论 0
登录后参与评分
还没有评论,来抢沙发吧