GiftcodeX

Advanced gift code management plugin for Minecraft servers — GUI editor, PlaceholderAPI support, MySQL/H2 database, Folia compatible.

Table of Contents

• Requirements
• Installation
• Commands
• Permissions
• Configuration
  • config.yml
  • messages.yml
  • codes.yml
• PlaceholderAPI
• Author
• Support

Requirements

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

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

All admin commands require the giftcodex.admin permission. Players use /redeem to claim codes.

Admin — /giftcodex (aliases: /gcx, /gc)

Player

Permissions

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:

PlaceholderAPI

Install PlaceholderAPI to use the following placeholders anywhere on your server.

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