Overview

CodeClaim lets server administrators create redeemable codes that reward players with any server command — give items, Pokemon, broadcast titles, and more. Each player can only redeem each code once, and each code can have a global usage limit. All data is stored in simple JSON files with no external database setup required.

Features

• Any player can use /claim without operator permissions
• Each player can only redeem each code once, enforced by UUID
• Per-code global usage limit via max_uses
• Set max_uses: -1 for unlimited redemptions
• Execute any server command as a reward using %player% as a placeholder
• All data auto-saves to a local JSON file
• Hot-reload config and data without restarting the server
• Server-side only — players do not need to install anything

Requirements

• Minecraft 1.21.1
• Fabric Loader 0.15.0 or later
• Fabric API 0.102.0+1.21.1
• Java 21

Installation

1. Download codeclaim-1.0.0.jar from the Releases page
2. Download all required dependencies: Fabric Language Kotlin, Fabric API
3. Place the file in your server's mods/ folder alongside Fabric API
4. Start the server — the config file will be automatically generated at config/codeclaim.json
5. Edit the config to define your codes and rewards
6. Use /claimadmin reload to apply any changes without restarting

Commands

| Command | Permission | Description |
|---------|------------|-------------|
| /claim <code> | All players | Redeem a code and receive its reward |
| /claimadmin reload | OP level 2 | Reload config and player data from disk |
| /claimadmin info <code> | OP level 2 | View usage statistics for a code |

Configuration

Config file location: config/codeclaim.json

{
  "messages": {
    "invalid_code":    "&cCode '&4{code}&c' does not exist!",
    "already_claimed": "&cYou have already redeemed '&4{code}&c'!",
    "max_uses":        "&cCode '&4{code}&c' has reached its usage limit!",
    "success":         "&aSuccessfully redeemed code '&2{code}&a'!",
    "reloaded":        "&aCodeClaim config reloaded!"
  },
  "codes": {
    "WELCOME2024": {
      "max_uses": -1,
      "commands": [
        "give %player% minecraft:bread 16"
      ]
    },
    "SHINY_EVENT": {
      "max_uses": 100,
      "commands": [
        "givepokemonother %player% moltres form=galarian",
        "title @a title {\"text\":\"A player claimed SHINY_EVENT!\",\"color\":\"gold\"}"
      ]
    },
    "GRAND_PRIZE": {
      "max_uses": 1,
      "commands": [
        "give %player% minecraft:netherite_ingot 3",
        "say %player% claimed the Grand Prize!"
      ]
    }
  }
}

Field Reference

| Field | Description |
|-------|-------------|
| max_uses | Maximum total redemptions across all players. -1 means unlimited. |
| commands | List of server commands to execute when the code is successfully redeemed. |
| %player% | Placeholder replaced with the redeeming player's username at runtime. |
| {code} | Placeholder replaced with the entered code in message strings. |
| &a, &c | Standard Minecraft color codes supported in all message fields. |

Data Storage

Player redemption history is automatically saved to:

data/codeclaim_data.json

This file tracks which players have redeemed which codes, and the total usage count per code. Back up this file regularly to preserve redemption history across server migrations.

Building from Source

Requirements: JDK 21, Gradle 8.8 or later

git clone https://github.com/YOUR_USERNAME/codeclaim
cd codeclaim

# Linux / macOS
./gradlew build

# Windows
gradlew.bat build

The compiled jar will be output to build/libs/codeclaim-1.0.0.jar.

Compatibility

| Mod | Status |
|-----|--------|
| Cobblemon | Compatible — use givepokemonother %player% |
| LuckPerms | Compatible |
| Any server-side command mod | Compatible |

License

This project is licensed under the MIT License. See LICENSE for details.