---

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.