GiftcodeX is a modern and flexible gift code management plugin for Minecraft servers, supporting Paper and Folia 1.21.+

Features

• Full GUI editor to create and manage codes in-game
• Edit commands, messages, item rewards, expiry, permissions and playtime requirements directly through inventory GUI
• Supports Paper Dialog API (1.21.6+) — automatically falls back to chat input for older clients via ViaVersion
• Multi-layer usage limits: global, per-player (player-max-uses), and per IP address (max-uses-per-ip)
• Detailed playtime requirements with full duration structure: years, months, weeks, days, hours, minutes, seconds, milliseconds
• Rewards include: console commands with %player% placeholder, colored messages, and item stacks
• Bulk random code generation with custom prefix and copy settings from a template code using the -c flag
• Built-in H2 embedded database requiring no setup, or MySQL with HikariCP connection pooling
• Automatically falls back to H2 in-memory if MySQL connection fails
• 16 PlaceholderAPI placeholders covering code status, usage counts, expiry, playtime and IP limits
• Folia compatible — tasks are scheduled correctly using region schedulers
• Automatic update checker via GitHub API with in-game notification for admins on join

Requirements

Requirement	Version
Java	21+
Paper / Folia	1.21.+
PlaceholderAPI	2.11+ (optional)
ViaVersion	Latest (optional)

Installation

1. Download the latest GiftcodeX-x.x.jar from Releases
2. Place the jar file into your server's plugins/ folder
3. Start or restart your server
4. Configuration files are generated automatically in plugins/GiftcodeX/
5. (Optional) Edit config.yml and messages.yml, then run /gcx reload

Commands
Admin — /giftcodex (aliases: /gcx, /gc)
All admin commands require the giftcodex.admin permission.

Command	Description
/gcx help	Show command list
/gcx create <code> [-g]	Create a new code, add -g to open the GUI editor immediately
/gcx delete <code>	Permanently delete a code and purge all player redemption records
/gcx enable <code>	Enable a code
/gcx disable <code>	Disable a code without deleting it
/gcx gui	Open the code list as a GUI (players) or text list (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> <permission|none>	Set or clear the required permission for a code
/gcx info <code>	Show detailed information about a code
/gcx random <prefix> [amount] [-c <template>]	Bulk generate random codes, use -c to copy settings from a template
/gcx reload	Reload config.yml, messages.yml and codes.yml

Player

Command	Description
/redeem <code>	Redeem a gift code and receive its rewards

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
codes.yml — 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 unlimited
expiry	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 object 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

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 by all players
%giftcodex_code_expiry_<code>%	Expiry date string or the configured infinity symbol
%giftcodex_code_permission_<code>%	Required permission node 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>%	Number of times this player has redeemed the code
%giftcodex_code_canuseip_<code>%	true / false — whether the player's IP is still within 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) automatically fall back to chat input mode

The GUI editor displays an input mode hint in the lore of each relevant item. No additional configuration is required.
Author

• Name: ihqqq
• Facebook: facebook.com/ihqqqq

Support

• Issues & bug reports: GitHub Issues
• Discord: discord.gg/YQtCC7BV