GiftcodeX
适用于 Minecraft 服务器的先进礼包码管理插件 —— 支持 GUI 编辑器、PlaceholderAPI 兼容、MySQL/H2 数据库以及 Folia。
目录
需求
| 需求项 |
版本 |
| Java |
21+ |
| Paper / Folia |
1.21+ |
| PlaceholderAPI |
2.11+ (可选) |
| ViaVersion |
最新版 (可选) |
注意: 不支持 Spigot。你必须使用 Paper 或 Folia。
ViaVersion: 可选安装 ViaVersion 以支持旧版客户端(低于 1.21.6)的玩家加入服务器。插件会自动检测旧版客户端,并将输入方式从对话框切换为聊天栏模式。
安装
- 从 Releases 下载最新的
GiftcodeX-x.x.jar。
- 将
.jar 文件放入服务器的 plugins/ 文件夹中。
- 启动或重启服务器。
- 配置文件将在
plugins/GiftcodeX/ 目录下自动生成。
- (可选) 编辑
config.yml 和 messages.yml,然后运行 /gcx reload。
命令
所有管理员命令均需 giftcodex.admin 权限。玩家使用 /redeem 领取礼包码。
管理员 — /giftcodex (别名: /gcx, /gc)
| 命令 |
描述 |
/gcx help |
显示命令帮助 |
/gcx create <code> [-g] |
创建礼包码。添加 -g 可立即打开 GUI 编辑器 |
/gcx delete <code> |
永久删除一个礼包码并清除所有玩家的使用记录 |
/gcx enable <code> |
启用已禁用的礼包码 |
/gcx disable <code> |
禁用一个礼包码而不将其删除 |
/gcx gui |
列出所有礼包码(对玩家打开 GUI,对控制台显示文本列表) |
/gcx edit <code> |
打开某个礼包码的 GUI 设置编辑器 |
/gcx items <code> |
打开某个礼包码的物品奖励编辑器 |
/gcx assign <code> <player> |
直接将礼包码奖励发放给指定玩家 |
/gcx setperm <code> <perm|none> |
设置或清除使用该礼包码所需的权限 |
/gcx info <code> |
打印有关该礼包码的详细信息 |
/gcx random <prefix> [amount] [-c <template>] |
批量生成随机礼包码。使用 -c <template> 可从现有礼包码复制设置 |
/gcx reload |
无需重启即可重新加载 config.yml、messages.yml 和 codes.yml |
玩家
| 命令 |
描述 |
/redeem <code> |
兑换礼包码 |
权限
| 权限 |
默认值 |
描述 |
giftcodex.admin |
OP |
完全访问所有管理员命令 |
giftcodex.player |
Everyone |
允许使用 /redeem |
giftcodex.vip |
OP |
示例:用于限制 VIP 专属礼包码的自定义权限 |
配置
config.yml
# 数据库类型:H2(内置,无需设置)或 MYSQL
database:
type: H2
mysql:
host: localhost
port: 3306
database: giftcodex
username: root
password: ""
# 检查 GitHub 上的新版本(会在 OP 加入时通知)
check-update: true
# GUI 设置
gui:
reward-color: "&a" # 应用于奖励消息的颜色前缀
# 创建新礼包码时应用的默认值
defaults:
expiry: "2099-12-31T23:59:59" # 留空表示永不过期
max-uses: 100 # 全局使用次数限制
player-max-uses: 1 # 每位玩家的使用限制(-1 = 无限制)
max-uses-per-ip: 1 # 每个 IP 的限制(0 = 禁用)
required-playtime: 0 # 所需游戏时长(分钟)(0 = 无要求)
messages.yml
所有消息均支持 & 颜色代码。infinity-symbol 字段控制无限/永不过期值的显示内容(默认为 ∞)。
prefix: "&8[&bGiftcodeX&8] "
# 用于显示无限或永不过期值的符号
infinity-symbol: "∞"
redeemed: "&a礼包码兑换成功!"
invalid-code: "&c该礼包码不存在。"
code-disabled: "&c该礼包码当前已被禁用。"
code-expired: "&c该礼包码已过期。"
max-uses-reached: "&c该礼包码已达到全局使用上限。"
already-redeemed: "&c你已达到该礼包码的最大使用次数。"
ip-limit-reached: "&c你的 IP 地址使用该礼包码的次数过多。"
not-enough-playtime: "&c你需要至少 &e{required} &c的游戏时长才能使用此礼包码。&7(当前拥有: &e{current}&7)"
no-permission: "&c你没有权限使用此礼包码。"
编辑 messages.yml 后请运行 /gcx reload —— 无需重启服务器。
codes.yml
礼包码由系统自动存储和管理。你也可以手动编辑此文件,然后运行 /gcx reload。
SUMMER24:
commands:
- "give %player% diamond 3"
- "give %player% golden_apple 1"
messages:
- "&aYou received &e3 Diamonds &aand a &eGolden Apple&a!"
max-uses: 1000 # 剩余的全局使用次数(设置为 999999999 即为无限)
expiry: "2024-08-31T23:59:59"
enabled: true
player-max-uses: 1 # -1 = 每个玩家无限次
max-uses-per-ip: 2 # 0 = 禁用
required-playtime: # 完整时长模型(从纯整数自动迁移)
years: 0
months: 0
weeks: 0
days: 0
hours: 0
minutes: 0
seconds: 0
milliseconds: 0
permission: "" # 留空表示无需权限
items: [] # 通过 /gcx items <code> 设置物品奖励
字段参考:
| 字段 |
描述 |
commands |
兑换时执行的控制台命令。使用 %player% 作为玩家名称占位符 |
messages |
发送给玩家的提示信息。支持 & 颜色代码 |
max-uses |
剩余全局使用次数。设置为 999999999 即视为无限 |
expiry |
ISO-8601 格式的过期时间 (yyyy-MM-dd'T'HH:mm:ss)。留空表示永不过期 |
enabled |
true / false |
player-max-uses |
单个玩家的兑换上限。-1 = 无限 |
max-uses-per-ip |
单个 IP 的兑换上限。0 = 禁用 |
required-playtime |
包含以下字段的时长模型:years、months、weeks、days、hours、minutes、seconds、milliseconds。旧的纯整数值(分钟数)将在重载时自动迁移 |
permission |
所需的权限节点。留空表示无要求 |
items |
ItemStack 序列化的物品奖励 — 通过 /gcx items <code> 管理 |
PlaceholderAPI
安装 PlaceholderAPI 即可在服务器任意位置使用以下占位符。
| 占位符 |
描述 |
%giftcodex_total_codes% |
已注册礼包码的总数 |
%giftcodex_player_totalused% |
该玩家已兑换的礼包码数量 |
%giftcodex_code_exists_<code>% |
true / false — 该礼包码是否存在 |
%giftcodex_code_enabled_<code>% |
true / false — 该礼包码是否启用 |
%giftcodex_code_expired_<code>% |
true / false — 该礼包码是否已过期 |
%giftcodex_code_maxuses_<code>% |
剩余全局使用次数 |
%giftcodex_code_used_<code>% |
该礼包码被兑换的总次数(所有玩家) |
%giftcodex_code_expiry_<code>% |
过期日期字符串,或配置的无限符号 |
%giftcodex_code_permission_<code>% |
所需权限,或 None |
%giftcodex_code_playtime_<code>% |
以人类可读格式显示的所需游戏时长(例如 1d 2h 30m) |
%giftcodex_code_playtime_minutes_<code>% |
转换为总分钟数的所需游戏时长 |
%giftcodex_code_playtime_ms_<code>% |
以毫秒为单位的所需游戏时长 |
%giftcodex_code_playeruses_<code>% |
该玩家 兑换此礼包码的次数 |
%giftcodex_code_canuseip_<code>% |
true / false — 该玩家的 IP 是否仍在限制范围内 |
%giftcodex_code_playerlimit_<code>% |
单个玩家的使用上限,若为无限则显示无限符号 |
%giftcodex_code_iplimit_<code>% |
单个 IP 的使用上限,若已禁用则显示无限符号 |
ViaVersion 支持
当安装 ViaVersion 时,GiftcodeX 会自动检测每位管理员客户端的版本:
- 1.21.6+ 客户端 使用原生的 Dialog 输入方式(带有标签字段的弹出式表单)。
- 旧版客户端(低于 1.21.6) 将自动回退到 聊天输入 模式。
GUI 编辑器会在每个物品的 lore(描述)中显示提示,指明当前查看者处于哪种输入模式(dialog input 或 chat input)。无需进行任何配置。
作者
支持
GiftcodeX
Advanced gift code management plugin for Minecraft servers — GUI editor, PlaceholderAPI support, MySQL/H2 database, Folia compatible.
Table of Contents
Requirements
| Requirement |
Version |
| Java |
21+ |
| Paper / Folia |
1.21+ |
| PlaceholderAPI |
2.11+ (optional) |
| ViaVersion |
Latest (optional) |
Note: Spigot is not supported. You must use Paper or Folia.
ViaVersion: Optionally install ViaVersion to support players joining on older clients (below 1.21.6). The plugin automatically detects legacy clients and switches from Dialog input to chat input mode.
Installation
- Download the latest
GiftcodeX-x.x.jar from Releases.
- Place the
.jar file into your server's plugins/ folder.
- Start or restart your server.
- Configuration files are generated automatically in
plugins/GiftcodeX/.
- (Optional) Edit
config.yml and messages.yml, then run /gcx reload.
Commands
All admin commands require the giftcodex.admin permission. Players use /redeem to claim codes.
Admin — /giftcodex (aliases: /gcx, /gc)
| Command |
Description |
/gcx help |
Show command help |
/gcx create <code> [-g] |
Create a gift code. Add -g to open the GUI editor immediately |
/gcx delete <code> |
Permanently delete a code and purge all player records |
/gcx enable <code> |
Enable a disabled code |
/gcx disable <code> |
Disable a code without deleting it |
/gcx gui |
List all codes (opens GUI for players, text list for console) |
/gcx edit <code> |
Open the GUI settings editor for a code |
/gcx items <code> |
Open the GUI item reward editor for a code |
/gcx assign <code> <player> |
Give a code's rewards directly to a player |
/gcx setperm <code> <perm|none> |
Set or clear the required permission for a code |
/gcx info <code> |
Print detailed information about a code |
/gcx random <prefix> [amount] [-c <template>] |
Bulk-generate random codes. Use -c <template> to copy settings from an existing code |
/gcx reload |
Reload config.yml, messages.yml, and codes.yml without restarting |
Player
| Command |
Description |
/redeem <code> |
Redeem a gift code |
Permissions
| Permission |
Default |
Description |
giftcodex.admin |
OP |
Full access to all admin commands |
giftcodex.player |
Everyone |
Allows use of /redeem |
giftcodex.vip |
OP |
Example custom permission for VIP-restricted codes |
Configuration
config.yml
# Database type: H2 (embedded, no setup needed) or MYSQL
database:
type: H2
mysql:
host: localhost
port: 3306
database: giftcodex
username: root
password: ""
# Check for new releases on GitHub (notifies OPs on join)
check-update: true
# GUI settings
gui:
reward-color: "&a" # Colour prefix applied to reward messages
# Default values applied when creating a new code
defaults:
expiry: "2099-12-31T23:59:59" # Leave blank for no expiry
max-uses: 100 # Global use limit
player-max-uses: 1 # Per-player limit (-1 = unlimited)
max-uses-per-ip: 1 # Per-IP limit (0 = disabled)
required-playtime: 0 # Minutes of playtime required (0 = none)
messages.yml
All messages support & colour codes. The infinity-symbol field controls what is displayed for unlimited/no-expiry values (default: ∞).
prefix: "&8[&bGiftcodeX&8] "
# Symbol displayed for unlimited or no-expiry values
infinity-symbol: "∞"
redeemed: "&aCode redeemed successfully!"
invalid-code: "&cThis gift code does not exist."
code-disabled: "&cThis gift code is currently disabled."
code-expired: "&cThis gift code has expired."
max-uses-reached: "&cThis gift code has reached its global usage limit."
already-redeemed: "&cYou have already used this code the maximum allowed number of times."
ip-limit-reached: "&cThis gift code has been used too many times from your IP address."
not-enough-playtime: "&cYou need at least &e{required} &cof playtime to use this code. &7(You have: &e{current}&7)"
no-permission: "&cYou do not have permission to use this gift code."
Run /gcx reload after editing messages.yml — no restart needed.
codes.yml
Codes are stored and managed automatically. You can also edit this file manually, then run /gcx reload.
SUMMER24:
commands:
- "give %player% diamond 3"
- "give %player% golden_apple 1"
messages:
- "&aYou received &e3 Diamonds &aand a &eGolden Apple&a!"
max-uses: 1000 # Remaining global uses (set to 999999999 for unlimited)
expiry: "2024-08-31T23:59:59"
enabled: true
player-max-uses: 1 # -1 = unlimited per player
max-uses-per-ip: 2 # 0 = disabled
required-playtime: # Full duration model (auto-migrated from plain integer)
years: 0
months: 0
weeks: 0
days: 0
hours: 0
minutes: 0
seconds: 0
milliseconds: 0
permission: "" # Leave blank for no permission required
items: [] # Set item rewards via /gcx items <code>
Field reference:
| Field |
Description |
commands |
Console commands run on redemption. Use %player% as the player name placeholder |
messages |
Messages sent to the player. Supports & colour codes |
max-uses |
Remaining global uses. Set to 999999999 for effectively unlimited |
expiry |
ISO-8601 expiry datetime (yyyy-MM-dd'T'HH:mm:ss). Leave empty for no expiry |
enabled |
true / false |
player-max-uses |
Per-player redemption limit. -1 = unlimited |
max-uses-per-ip |
Per-IP redemption limit. 0 = disabled |
required-playtime |
Duration model with fields: years, months, weeks, days, hours, minutes, seconds, milliseconds. Old plain-integer values (minutes) are auto-migrated on reload |
permission |
Required permission node. Leave empty for none |
items |
ItemStack-serialized item rewards — managed via /gcx items <code> |
PlaceholderAPI
Install PlaceholderAPI to use the following placeholders anywhere on your server.
| Placeholder |
Description |
%giftcodex_total_codes% |
Total number of registered gift codes |
%giftcodex_player_totalused% |
Number of codes the player has redeemed |
%giftcodex_code_exists_<code>% |
true / false — whether the code exists |
%giftcodex_code_enabled_<code>% |
true / false — whether the code is enabled |
%giftcodex_code_expired_<code>% |
true / false — whether the code has expired |
%giftcodex_code_maxuses_<code>% |
Remaining global uses |
%giftcodex_code_used_<code>% |
Total times the code has been redeemed (all players) |
%giftcodex_code_expiry_<code>% |
Expiry date string, or the configured infinity symbol |
%giftcodex_code_permission_<code>% |
Required permission, or None |
%giftcodex_code_playtime_<code>% |
Required playtime as a human-readable string (e.g. 1d 2h 30m) |
%giftcodex_code_playtime_minutes_<code>% |
Required playtime converted to total minutes |
%giftcodex_code_playtime_ms_<code>% |
Required playtime in milliseconds |
%giftcodex_code_playeruses_<code>% |
Times this player has redeemed the code |
%giftcodex_code_canuseip_<code>% |
true / false — whether the player's IP is still under the limit |
%giftcodex_code_playerlimit_<code>% |
Per-player use limit, or the infinity symbol if unlimited |
%giftcodex_code_iplimit_<code>% |
Per-IP use limit, or the infinity symbol if disabled |
ViaVersion Support
When ViaVersion is installed, GiftcodeX automatically detects each admin's client version:
- 1.21.6+ clients use the native Dialog input (a popup form with labeled fields).
- Legacy clients (below 1.21.6) fall back to chat input mode automatically.
The GUI editor displays a hint in each item's lore indicating which input mode is active for the current viewer (dialog input or chat input). No configuration is required.
Author
Support
- Issues & bug reports: GitHub Issues
- Discord server: discord.gg/YQtCC7BV
评论 0
登录后参与评分
还没有评论,来抢沙发吧