Better Rewards

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

/promocode create WELCOME minecraft:diamond 5

Players can then use /promo, enter WELCOME, and receive 5 diamonds.

Multiple Items

/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

/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

/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

/promocode create <CODE> <item> <count> [maxUses] [expiryEpoch]

Multiple rewards:

/promocode create <CODE> <item1> <count1> <item2> <count2> [item3] [count3] [maxUses] [expiryEpoch]

Raw format:

/promocode createraw <CODE:item1,count1;item2,count2|maxUses|expiryEpoch>

Delete a Code

/promocode delete <CODE>

Help

/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

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:

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:

server_config/promocodemod-server.toml

Example:

[[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

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

25 / 100

Meaning 25 of the available 100 redemptions have been used.

Players

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:

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

/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

/promocode create ANNIVERSARY minecraft:golden_apple 3 100 1767225600

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

Complex Reward

/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

/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:

minecraft:acacia_log

not:

acacia log

Item availability can also depend on your Minecraft version.

“Code already exists”

Delete the existing code first:

/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:

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.