RedemptionCodeFabric
概览
RedemptionCodeFabric 是一款适用于 Minecraft Fabric 服务器(1.20.1)的兑换码模组。它允许服务器管理员生成并分发兑换码,玩家可使用这些兑换码获取物品、经验值或权限等级。该模组支持七种不同的代码类型,涵盖广泛的使用场景——从一次性赠品到定期每日奖励。
仅需服务器端安装此模组;客户端无需安装即可连接。但如果客户端也安装了该模组,消息将通过 Minecraft 内置的翻译系统显示,从而提供更好的体验。
功能特性
七种代码类型 — ONCE、PERMANENT、PERSONAL、GLOBAL_UNLIMITED、GLOBAL_LIMIT、TIMED 和 CYCLE,覆盖从单次使用代码到周期性奖励的所有需求。
灵活的奖励内容 — 可发放物品(包含 NBT 数据)、经验值/等级,或临时权限等级。你甚至可以将当前手持的物品作为奖励捕获。
三种存储后端 — 将数据持久化到本地 JSON 文件、MySQL 数据库或 Redis。如果配置的存储后端不可用,会自动回退到文件存储。
内置 Web 管理面板 — 基于浏览器的管理界面,支持登录认证。你可以直接从浏览器创建、查看和删除代码;浏览操作日志;检查服务器状态;以及查看配置信息。
生产级连接池 — 自定义 SQL 连接池,参考 HikariCP 设计,具备弹性池大小调整、连接生命周期管理、空闲超时驱逐、泄漏检测、保活心跳以及优雅关闭等功能。
异步 I/O 架构 — 所有阻塞式 I/O 操作(SQL、Redis、文件、Web)均在专用线程池中运行,确保 Minecraft 主服务器线程永远不会被阻塞。
热重载配置 — 通过 /rcode reload 命令或在 Web 面板中更改设置并实时重载。Web 服务器、SQL 连接池和 Redis 连接池均会动态重新初始化。
国际化 (i18n) 支持 — 服务端消息适应系统区域设置(中文和英文)。当模组安装在客户端时,客户端消息使用 Minecraft 的翻译系统。
详细的操作日志记录 — 每次生成、兑换和删除操作都会记录时间戳、执行者信息和详细信息,便于审计。
代码类型
| 类型 |
描述 |
ONCE |
任何单个玩家只能兑换一次。 |
PERMANENT |
总使用次数无限;每个玩家可以任意次数兑换。 |
PERSONAL |
仅限特定玩家(通过 UUID、名称或 @selector);每人仅可兑换一次。 |
GLOBAL_UNLIMITED |
每位玩家均可兑换一次;无全局上限。 |
GLOBAL_LIMIT |
共享的全局使用限制。可选择性地限制为匹配特定标签或记分板排名的玩家(前 N 名或后 N 名)。 |
TIMED |
仅在指定的时间窗口内有效;每位玩家仅可兑换一次。 |
CYCLE |
重复的时间窗口(例如每日)。每位玩家在每个周期内仅可兑换一次。 |
奖励类型
| 格式 |
描述 |
示例 |
item@<id>{nbt} |
给予一个物品,可选地包含 NBT 数据。 |
item@minecraft:diamond_sword{Enchantments:[{id:"sharpness",lvl:5}]} |
[hand] |
捕获你在生成代码时主手所持的物品。 |
[hand] |
exp@<amount>P |
给予经验 点数。 |
exp@100P |
exp@<amount>L |
给予经验 等级。 |
exp@5L |
permissions@<level> |
授予临时权限等级(需联系管理员)。 |
permissions@2 |
如果未指定后缀,则默认为经验点数。
命令
所有命令均通过 CommandRegistrationCallback 在服务端注册。基础命令为 /rcode。
玩家命令
/rcode redeem <code>
兑换一个代码。所有玩家均可使用。
操作员命令(权限等级 2+)
/rcode generate <type> [options] <reward>
生成新代码。如果未指定自定义代码字符串,将生成一个随机的 16 位字母数字代码。
示例:
# 自动生成 ID 的一次性代码
/rcode generate once item@minecraft:diamond 64
# 带有自定义 ID 的永久代码
/rcode generate permanent code MYCODE exp@10L
# 针对特定玩家的个人代码
/rcode generate personal Steve item@minecraft:netherite_sword
# 全局限制代码(按标签 "vip" 排名前 3)
/rcode generate global_limit tag vip 3 item@minecraft:elytra
# 全局限制代码(按记分板 "score" 排名后 5)
/rcode generate global_limit scoreboard score -5 item@minecraft:gold_ingot 32
# 定时代码(活跃时间从 2025-01-01 到 2025-12-31)
/rcode generate timed 2025-01-01_00-00-00 2025-12-31_23-59-59 exp@100P
# 循环代码(每日,从现在开始)
/rcode generate cycle 0-0-0_0-0-0 86400 item@minecraft:golden_apple
在生成命令末尾追加 cover 以覆盖现有代码:
/rcode generate once code MYCODE item@minecraft:diamond cover
时间格式: yyyy-MM-dd_HH-mm-ss。使用 0-0-0_0-0-0 或 0 表示“立即开始”。
删除一个代码。
/rcode delete <code>
显示代码的详细信息,包括类型、奖励、使用统计以及谁已兑换它。在线玩家按名称显示;离线玩家按 UUID 显示。
/rcode info <code>
管理员命令(权限等级 4)
/rcode reload
热重载配置文件并重新初始化所有 I/O 资源(SQL 连接池、Redis 连接池、Web 服务器)。
Web 管理面板
在配置文件中启用 Web 面板:
web.enabled=true
web.port=8080
该面板提供:
- 登录页面 (
index.html) — 使用用户名/密码进行身份验证(在配置文件中设置)。
- 管理面板(自定义路径,首次运行时自动生成)— 包含完整的管理功能:
- 服务器状态概览(在线玩家、代码总数、存储后端、模组版本)
- 代码管理(列表、创建、查看详情、删除)
- 带分页的操作日志浏览器
- 在线玩家列表(含 UUID、延迟、IP 和标签)
- 记分板目标查看器
- 配置文件查看器(敏感值已掩码处理)
- 热重载按钮
管理面板路径在首次启动时随机生成以确保安全。请在配置文件的 web.adminPath 下找到该路径。密码也会自动生成并存储在 web.password 中。
当 web.sendUrlToOP=true 时,管理员(OP)加入服务器后会在聊天栏收到面板链接。
存储后端
在 redemptioncodefabric.properties 中配置存储后端:
# 选项:file, sql, redis
datastore.type=file
文件(默认)— 将代码和日志作为 JSON 文件存储在模组的配置目录中。无需任何额外设置。
SQL (MySQL) — 需要运行中的 MySQL 服务器。表(redemption_codes、operation_logs)将在首次连接时自动创建。连接参数如下:
sql.host=localhost
sql.port=3306
sql.user=admin
sql.password=
sql.database=redemptioncode
Redis — 需要运行中的 Redis 服务器。代码以 Redis Hash 形式存储,并使用基于集合的索引。如果 Redis 不可用,则回退到文件存储。
redis.host=localhost
redis.port=6379
redis.password=
redis.database=0
SQL 和 Redis 连接均使用重试逻辑(最多尝试 3 次,每次间隔 2 秒)。如果所有尝试均失败,模组将自动回退到文件存储,并向在线管理员发出警报。
连接池
使用 SQL 后端时,Simple 连接池提供生产级别的连接管理:
| 功能 |
描述 |
| 弹性池大小调整 |
根据需求在 minIdle 和 maxPoolSize 之间进行扩展 |
| 连接生命周期 |
超过 maxLifetime 的连接将在释放时退役 |
| 空闲超时驱逐 |
超过 idleTimeout 的空闲连接将被驱逐(尊重 minIdle) |
| 泄漏检测 |
当连接持有时间超过 leakDetectionThreshold 时会发出警告 |
| 保活心跳 |
定期通过 isValid() 验证空闲连接 |
| 借用验证 |
每次发放连接前都会进行验证 |
| 获取超时 |
当池满时最多等待 connectionTimeout 毫秒 |
| 优雅关闭 |
停止维护、排空空闲连接、等待正在使用的连接,然后强制关闭 |
| 初始化 SQL |
在每个新连接上执行 connectionInitSql |
所有池参数均可在 pool.* 命名空间下的属性文件中进行配置。
配置
配置文件位于 config/redemptioncodefabric/redemptioncodefabric.properties。首次启动时会自动创建该文件,包含结构化的部分和注释。
# ── 数据存储 ───────────────────────────────────────────
datastore.type=file
# ── 日志记录 ─────────────────────────────────────────────
log.redemption.history=true
log.max.entries=20000
── Web 服务器 ─────────────────────────────────────────
web.enabled=false
web.url=
web.port=8080
web.user=admin
web.password=<自动生成>
web.adminPath=<自动生成>
web.sendUrlToOP=true
── SQL (MySQL) ────────────────────────────────────────
sql.host=localhost
sql.port=3306
sql.user=admin
sql.password=
sql.database=redemptioncode
sql.url=jdbc:mysql://localhost:3306/redemptioncode?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
── Redis ──────────────────────────────────────────────
redis.host=localhost
redis.port=6379
redis.password=
redis.database=0
── 连接池 ────────────────────────────────────
pool.maxPoolSize=10
pool.minIdle=2
pool.connectionTimeout=30000
pool.idleTimeout=600000
pool.maxLifetime=1800000
pool.leakDetectionThreshold=60000
pool.keepaliveTime=300000
pool.validationTimeout=5000
pool.connectionInitSql=
依赖
- Minecraft 1.20.1
- Fabric Loader >= 0.18.4
- Fabric API
- Java >= 17
- MySQL Connector/J 9.7.0(已捆绑,已重定位)
- Jedis 5.2.0(已捆绑,已重定位)
许可证
本项目根据 GNU 通用公共许可证 v3.0 进行许可。
第三方依赖的许可证请参阅 CREDITS.md。
链接
RedemptionCodeFabric
Overview
RedemptionCodeFabric is a redemption code mod for Minecraft Fabric servers (1.20.1). It allows server operators to generate and distribute codes that players can redeem for items, experience, or permission levels. The mod supports seven different code types to cover a wide range of use cases — from one-time giveaways to recurring daily rewards.
Only the server needs to install the mod; clients can connect without it. However, when clients also have the mod installed, messages are displayed using Minecraft's built-in translation system for a better experience.
Features
Seven Code Types — ONCE, PERMANENT, PERSONAL, GLOBAL_UNLIMITED, GLOBAL_LIMIT, TIMED, and CYCLE, covering everything from single-use codes to recurring rewards.
Flexible Rewards — Give items (with NBT data), experience points/levels, or temporary permission levels. You can even capture the item in your hand as a reward.
Three Storage Backends — Persist data to local JSON files, MySQL databases, or Redis. Automatic fallback to file storage if the configured backend is unreachable.
Built-in Web Management Panel — A browser-based admin UI with login authentication. Create, view, and delete codes; browse operation logs; check server status; and view configuration — all from your browser.
Production-grade Connection Pool — A custom SQL connection pool modeled after HikariCP, with elastic pool sizing, connection lifecycle management, idle timeout eviction, leak detection, keepalive heartbeats, and graceful shutdown.
Async I/O Architecture — All blocking I/O (SQL, Redis, file, web) runs on a dedicated thread pool, ensuring the Minecraft server thread is never blocked.
Hot Configuration Reload — Change settings and reload them at runtime with /rcode reload or via the web panel. The Web server, SQL pool, and Redis pool are all re-initialized dynamically.
i18n Support — Server-side messages adapt to the system locale (Chinese and English). Client-side messages use Minecraft's translation system when the mod is installed.
Detailed Operation Logging — Every generate, redeem, and delete action is logged with timestamps, executor info, and details for auditing.
Code Types
| Type |
Description |
ONCE |
Can be redeemed exactly once by any single player. |
PERMANENT |
Unlimited total uses; each player can redeem it any number of times. |
PERSONAL |
Restricted to a specific player (by UUID, name, or @selector); can be redeemed once. |
GLOBAL_UNLIMITED |
Every player can redeem it once; no global cap. |
GLOBAL_LIMIT |
Shared global usage limit. Optionally restricted to players matching a Tag or Scoreboard ranking (top N or bottom N). |
TIMED |
Only active within a specified time window; each player can redeem once. |
CYCLE |
Repeating time windows (e.g., daily). Each player can redeem once per cycle. |
Reward Types
| Format |
Description |
Example |
item@<id>{nbt} |
Gives an item, optionally with NBT data. |
item@minecraft:diamond_sword{Enchantments:[{id:"sharpness",lvl:5}]} |
[hand] |
Captures the item currently held in your main hand (at generation time). |
[hand] |
exp@<amount>P |
Gives experience points. |
exp@100P |
exp@<amount>L |
Gives experience levels. |
exp@5L |
permissions@<level> |
Grants a temporary permission level (admin contact required). |
permissions@2 |
If no suffix is specified, experience points are assumed (default = points).
Commands
All commands are registered server-side via CommandRegistrationCallback. The base command is /rcode.
Player Command
/rcode redeem <code>
Redeems a code. Available to all players.
Operator Commands (Permission Level 2+)
/rcode generate <type> [options] <reward>
Generates a new code. If no custom code string is specified, a random 16-character alphanumeric code is generated.
Examples:
# One-time code with auto-generated ID
/rcode generate once item@minecraft:diamond 64
# Permanent code with custom ID
/rcode generate permanent code MYCODE exp@10L
# Personal code for a specific player
/rcode generate personal Steve item@minecraft:netherite_sword
# Global limited code (top 3 by tag "vip")
/rcode generate global_limit tag vip 3 item@minecraft:elytra
# Global limited code (bottom 5 by scoreboard "score")
/rcode generate global_limit scoreboard score -5 item@minecraft:gold_ingot 32
# Timed code (active from 2025-01-01 to 2025-12-31)
/rcode generate timed 2025-01-01_00-00-00 2025-12-31_23-59-59 exp@100P
# Cycle code (daily, starting now)
/rcode generate cycle 0-0-0_0-0-0 86400 item@minecraft:golden_apple
Append cover to the end of a generate command to overwrite an existing code:
/rcode generate once code MYCODE item@minecraft:diamond cover
Time format: yyyy-MM-dd_HH-mm-ss. Use 0-0-0_0-0-0 or 0 for "start now".
Deletes a code.
/rcode delete <code>
Shows detailed information about a code, including type, reward, usage statistics, and who has redeemed it. Online players are shown by name; offline players are shown by UUID.
/rcode info <code>
Admin Command (Permission Level 4)
/rcode reload
Hot-reloads the configuration file and re-initializes all I/O resources (SQL pool, Redis pool, Web server).
Web Management Panel
Enable the web panel in the configuration file:
web.enabled=true
web.port=8080
The panel provides:
- Login Page (
index.html) — Authentication with username/password (configured in properties).
- Admin Dashboard (custom path, auto-generated on first run) — Full management interface including:
- Server status overview (online players, total codes, storage backend, mod version)
- Code management (list, create, view details, delete)
- Operation log browser with pagination
- Online player list with UUID, ping, IP, and tags
- Scoreboard objectives viewer
- Configuration viewer (sensitive values masked)
- Hot reload button
The admin panel path is randomly generated on first launch for security. Find it in your config file under web.adminPath. A password is also auto-generated and stored in web.password.
When web.sendUrlToOP=true, operators receive the panel URL in chat upon joining the server.
Storage Backends
Configure the storage backend in redemptioncodefabric.properties:
# Options: file, sql, redis
datastore.type=file
File (default) — Stores codes and logs as JSON files in the mod's config directory. Zero setup required.
SQL (MySQL) — Requires a running MySQL server. Tables (redemption_codes, operation_logs) are auto-created on first connection. Connection parameters:
sql.host=localhost
sql.port=3306
sql.user=admin
sql.password=
sql.database=redemptioncode
Redis — Requires a running Redis server. Codes are stored as Redis hashes with a set-based index. Falls back to file storage if Redis is unavailable.
redis.host=localhost
redis.port=6379
redis.password=
redis.database=0
Both SQL and Redis connections use retry logic (3 attempts with 2-second delays). If all attempts fail, the mod automatically falls back to file storage and alerts online operators.
Connection Pool
When using the SQL backend, a Simple connection pool provides production-grade connection management:
| Feature |
Description |
| Elastic pool sizing |
Scales between minIdle and maxPoolSize on demand |
| Connection lifecycle |
Connections exceeding maxLifetime are retired on release |
| Idle timeout eviction |
Idle connections exceeding idleTimeout are evicted (respects minIdle) |
| Leak detection |
Warns when connections are held longer than leakDetectionThreshold |
| Keepalive heartbeat |
Periodically validates idle connections with isValid() |
| Borrow validation |
Every connection is verified before being handed out |
| Acquisition timeout |
Waits up to connectionTimeout ms when the pool is full |
| Graceful shutdown |
Stops maintenance, drains idle, waits for in-use, then force-closes |
| Init SQL |
Executes connectionInitSql on every new connection |
All pool parameters are configurable in the properties file under the pool.* namespace.
Configuration
The configuration file is located at config/redemptioncodefabric/redemptioncodefabric.properties. It is auto-created on first launch with organized sections and comments.
# ── Datastore ──────────────────────────────────────────
datastore.type=file
# ── Logging ────────────────────────────────────────────
log.redemption.history=true
log.max.entries=20000
# ── Web Server ─────────────────────────────────────────
web.enabled=false
web.url=http://localhost
web.port=8080
web.user=admin
web.password=<auto-generated>
web.adminPath=<auto-generated>
web.sendUrlToOP=true
# ── SQL (MySQL) ────────────────────────────────────────
sql.host=localhost
sql.port=3306
sql.user=admin
sql.password=
sql.database=redemptioncode
sql.url=jdbc:mysql://localhost:3306/redemptioncode?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
# ── Redis ──────────────────────────────────────────────
redis.host=localhost
redis.port=6379
redis.password=
redis.database=0
# ── Connection Pool ────────────────────────────────────
pool.maxPoolSize=10
pool.minIdle=2
pool.connectionTimeout=30000
pool.idleTimeout=600000
pool.maxLifetime=1800000
pool.leakDetectionThreshold=60000
pool.keepaliveTime=300000
pool.validationTimeout=5000
pool.connectionInitSql=
Dependencies
- Minecraft 1.20.1
- Fabric Loader >= 0.18.4
- Fabric API
- Java >= 17
- MySQL Connector/J 9.7.0 (bundled, shadowed)
- Jedis 5.2.0 (bundled, shadowed)
License
This project is licensed under the GNU General Public License v3.0.
See CREDITS.md for third-party dependency licenses.
Links
评论 0
登录后参与评分
还没有评论,来抢沙发吧