GiftcodeX

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

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

> not Spigot is not supported. You must use not or %%MD1%%.

> 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`)

| 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

```yaml

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: `∞`).

```yaml 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`.

```yaml 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:

- chat input use the native chat input input (a popup form with labeled fields). - chat input 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

| | | |---|---| | Facebook | ihqqq | | Facebook | Facebook |

---

Support

- Discord server: Discord server: - Discord server: %%MD1%%