# BetterRewards Mod --- Have an idea for a future update? Submit your suggestion on our website and vote for your favorite ideas: https://modvotes.m4rios.dev/ A complete promotional code system for Minecraft servers. Server administrators can create custom codes that reward players with items, with full control over quantities, usage limits, and expiration dates. --- ## Overview BetterRewards adds an intuitive in-game interface for redeeming promotional codes. Perfect for: * 🎁 **Starter rewards** for new players * 🎉 **Event bonuses** for seasonal events and special occasions * 🏆 **Achievement rewards** for giveaways and contests * 👥 **Community perks** for Discord members, supporters, and more ## Key Features - ✅ **Simple GUI** — Players use `/promo` and enter a code - ✅ **Flexible rewards** — Add multiple items with custom quantities - ✅ **Admin controls** — Create and delete codes in-game using commands - ✅ **Usage limits** — Set maximum redemptions or expiration dates - ✅ **Anti-abuse** — Each player can claim each code only once - ✅ **Statistics** — Track total redemptions and unique players - ✅ **Offline-mode support** — Designed to work on offline-mode servers - ✅ **Online-mode support** — Works normally on online-mode servers - ✅ **Auto-save** — Redemption data is automatically persisted - ✅ **Multiple Minecraft versions** — Check the available files for supported versions ## Installation ### Server Administrators 1. Download the `.jar` file for your Minecraft version. 2. Place it inside your server's `mods/` folder. 3. Start the server. 4. Configuration files will be generated automatically. 5. Optionally edit `server_config/promocodemod-server.toml` to add default codes. 6. Restart the server after making configuration changes. > Make sure you download the correct BetterRewards build for your Minecraft and modloader version. ### Players BetterRewards is primarily designed for servers. Depending on the server configuration and Minecraft/modloader version, the mod may also be required on the client. Always follow the installation instructions provided by the server administrator. --- ## Quick Start ### Create Your First Code ```text /promocode create WELCOME minecraft:diamond 5 ``` Players can then use `/promo`, enter `WELCOME`, and receive 5 diamonds. ### Multiple Items ```text /promocode create STARTER minecraft:diamond 3 minecraft:iron_sword 1 minecraft:bread 10 0 0 ``` Rewards: * 3 Diamonds * 1 Iron Sword * 10 Bread * Unlimited total uses * No expiration ### Limited Event Code ```text /promocode createraw HALLOWEEN:minecraft:pumpkin,20;minecraft:orange_dye,10|50|0 ``` This code: * Gives 20 Pumpkins * Gives 10 Orange Dye * Allows 50 total redemptions * Never expires ### Delete a Code ```text /promocode delete WELCOME ``` --- ## Command Reference ### Player Commands | Command | Purpose | | ----------------- | ---------------------------------- | | `/promo` | Open the promo-code redemption GUI | | `/promocode help` | Display available commands | ### Administrator Commands Administrator commands require **OP Level 2+**. #### Create a Code ```text /promocode create

   [maxUses] [expiryEpoch]
```

Multiple rewards:

```text
/promocode create      [item3] [count3] [maxUses] [expiryEpoch]
```

Raw format:

```text
/promocode createraw 
```

#### Delete a Code

```text
/promocode delete 
```

#### Help

```text
/promocode help
```

---

## Parameters

| Parameter     | Value                      | Description                                  |
| ------------- | -------------------------- | -------------------------------------------- |
| `CODE`        | Letters, numbers, `_`, `-` | Example: `WELCOME`, `SUMMER2026`, `EVENT_01` |
| `item`        | Minecraft item ID          | Format: `namespace:name`                     |
| `count`       | `1–64`                     | Quantity of the item                         |
| `maxUses`     | `0–999`                    | `0` means unlimited                          |
| `expiryEpoch` | Unix timestamp             | `0` means the code never expires             |

### Example Item IDs

```text
minecraft:diamond
minecraft:emerald
minecraft:golden_apple
minecraft:enchanted_golden_apple
minecraft:netherite_sword
minecraft:diamond_pickaxe
minecraft:diamond_axe
minecraft:iron_sword
minecraft:bread
minecraft:coal
minecraft:iron_ingot
minecraft:oak_log
minecraft:obsidian
```

Additional items may be available depending on the Minecraft version you are running.

---

## Expiration Dates

Expiration dates use **Unix timestamps in seconds**.

Examples:

| Date           |        Epoch |
| -------------- | -----------: |
| 1 January 2025 | `1735689600` |
| 1 July 2025    | `1751328000` |
| 1 January 2026 | `1767225600` |

Use:

```text
0
```

for a code that never expires.

You can use a Unix timestamp converter to generate timestamps for other dates.

---

## Configuration

The server configuration can be found at:

```text
server_config/promocodemod-server.toml
```

Example:

```toml
[[promocodes]]
codes = [
    "EARLY_EASTER:minecraft:diamond,5;minecraft:golden_apple,3|100|0",
    "FREESTART:minecraft:iron_sword,1;minecraft:bread,10|200|0",
    "DIAMONDS4ALL:minecraft:diamond,64|10|0"
]
```

### Format

```text
CODE:item1,count1;item2,count2|maxUses|expiryEpoch
```

Restart the server after changing the configuration.

---

## How It Works

1. Player opens the GUI using `/promo`.
2. Player enters a promo code.
3. Player clicks **CONFIRM** or presses Enter.
4. BetterRewards validates the code.
5. If valid, the configured rewards are added to the player's inventory.

If the inventory is full, overflow items are dropped at the player's feet.

Invalid redemptions display an appropriate error, such as:

* Invalid code
* Code already redeemed
* Code expired
* Maximum uses reached

---

## Statistics

BetterRewards keeps track of promo-code usage.

The GUI can display information such as:

**Redeemed**

```text
25 / 100
```

Meaning 25 of the available 100 redemptions have been used.

**Players**

```text
10
```

Meaning 10 unique players have redeemed rewards.

---

## Anti-Abuse Protection

Each player can redeem each promotional code **only once**.

Redemption information is persisted between server restarts.

This helps prevent players from repeatedly claiming the same reward.

### Offline-Mode Servers

BetterRewards supports offline-mode servers.

However, offline-mode servers cannot provide the same identity guarantees as authenticated online-mode servers. Server administrators should monitor suspicious activity and disable or delete problematic codes if necessary.

---

## Data Storage

Redemption data is automatically saved to:

```text
world_folder/promocodes_data.json
```

The file contains information including:

* Codes redeemed by players
* Total redemptions for each code
* Custom codes created through commands

**Manual editing is not recommended.**

If you need to modify the file manually, create a backup first.

---

## Examples

### Welcome Bonus

```text
/promocode create WELCOME minecraft:diamond 5 minecraft:iron_sword 1 minecraft:bread 20 0 0
```

Rewards:

* 5 Diamonds
* 1 Iron Sword
* 20 Bread
* Unlimited uses
* No expiration

### Limited Anniversary Event

```text
/promocode create ANNIVERSARY minecraft:golden_apple 3 100 1767225600
```

Rewards 3 Golden Apples with a maximum of 100 total redemptions.

### Complex Reward

```text
/promocode createraw STARTER:minecraft:diamond,10;minecraft:emerald,5;minecraft:enchanted_golden_apple,2|50|0
```

Rewards:

* 10 Diamonds
* 5 Emeralds
* 2 Enchanted Golden Apples
* Maximum 50 redemptions
* No expiration

### Seasonal Giveaway

```text
/promocode create XMAS minecraft:red_concrete 20 minecraft:green_concrete 20 minecraft:gold_block 5 0 0
```

---

## Troubleshooting

### "Invalid item"

Check the exact Minecraft item ID.

Example:

```text
minecraft:acacia_log
```

not:

```text
acacia log
```

Item availability can also depend on your Minecraft version.

### "Code already exists"

Delete the existing code first:

```text
/promocode delete OLDCODE
```

Then create it again.

### Player Cannot Redeem a Valid Code

Check whether:

* The player already redeemed the code
* The code has expired
* The maximum number of redemptions has been reached

### Items Do Not Appear

Check the player's inventory.

If the inventory is full, overflow rewards are dropped at the player's feet.

### Server Error After Editing Configuration

Check:

```text
promocodemod-server.toml
```

for syntax errors and verify that all configured item IDs are valid for the Minecraft version being used.

---

## Compatibility

* **Minecraft:** Multiple versions supported
* **Modloader:** Check the individual download/file for compatibility
* **Server:** Supported
* **Client:** Depends on the selected version/build
* **Offline Mode:** Supported
* **Online Mode:** Supported

Always download the file that matches your exact **Minecraft version and modloader**.

---

## Known Limitations

* Maximum of 3 reward items through the standard `create` command
* Use `createraw` for more complex reward configurations
* Item quantities are limited to `1–64` per reward entry
* Administrator codes are created through commands or configuration files
* Codes are case-insensitive and stored internally in uppercase

---

## Licence

Redistribution without credit is not permitted.

M4riosDev