BetterRewards Mod — Minecraft Forge 1.16.5

A complete promotional code system for Minecraft servers. Server administrators can create codes that reward players with items, with full control over quantities, limits, and expiration dates.

---

Overview

PromoCode Mod adds an intuitive in-game interface for redeeming promotional codes. Perfect for:

• 🎁 Starter rewards for new players
• 🎉 Event bonuses (seasonal, special occasions)
• 🏆 Achievement rewards (giveaways, contests)
• 👥 Community perks (Discord members, supporters)

---

Key Features

✅ Simple GUI — Players press /promo and enter a code
✅ Flexible rewards — Multiple items per code, customisable quantities
✅ Admin controls — Create/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 items distributed and unique players
✅ Offline-friendly — Works perfectly on offline-mode servers
✅ Auto-saves — All data persisted to promocodes_data.json

---

Installation

For Server Administrators

1. Download the .jar file from ModRinth or CurseForge

2. Place it in your Forge 1.16.5 mods/ folder

3. Start the server — configuration files generate automatically

4. Restart the server

For Players

The mod is server-side, so you only need it if your server uses it. It'll be on the server's mod list.

---

Quick Start — Creating Your First Code

Via In-Game Command (Easiest)

/promo create WELCOME minecraft:diamond 5

Now players can type /promo, enter WELCOME, and get 5 diamonds!

Advanced: Multiple Items

/promo create STARTER minecraft:diamond 3 minecraft:iron_sword 1 minecraft:bread 10 0 0

Players get: 3 diamonds, 1 iron sword, 10 bread. Unlimited uses, never expires.

Advanced: Limited Time Event

/promo createraw HALLOWEEN:minecraft:pumpkin,20;minecraft:orange_dye,10|50|0

Only 50 total redemptions, never expires, includes 20 pumpkins and 10 orange dye.

Delete Old Codes

/promo delete WELCOME

---

Complete Command Reference

Player Commands

Command	Purpose
/promo	Open the redemption GUI
/promocode	Same as /promo
/promo help	Display all available commands

Administrator Commands (Op Level 2+)

Create Code:

/promo create <CODE> <item> <count> [maxUses] [expiryEpoch]
/promo create <CODE> <item1> <count1> <item2> <count2> [item3] [count3] [maxUses] [expiryEpoch]
/promo createraw <CODE:item1,count1;item2,count2|maxUses|expiryEpoch>

Delete Code:

/promo delete <CODE>

Show Help:

/promo help

---

Parameters Explained

Parameter	Value	Notes
CODE	Letters, numbers, underscores, hyphens	WELCOME, SUMMER2024, EVENT_01
item	Minecraft item ID	Format: namespace:name (e.g., minecraft:diamond)
count	1–64	Quantity per item in the reward
maxUses	0–999	0 = unlimited redemptions
expiryEpoch	Unix timestamp (seconds)	0 = never expires; see below for examples

Expiry Date Examples

Convert to Unix epoch using unixtimestamp.com:

Date	Epoch
1 January 2025	1735689600
1 July 2025	1751500800
31 December 2025	1767225600

Set to 0 for no expiration.

---

Common 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:respawn_anchor       minecraft:bread
minecraft:coal                 minecraft:iron_ingot
minecraft:oak_log              minecraft:obsidian
minecraft:amethyst_block       minecraft:copper_ore

Tip: Hover over items in Minecraft's creative inventory to see their exact ID.

---

Configuration File

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

Changes take effect on server restart.

---

How It Works

1. Player opens the GUI: /promo
2. Types the code name: WELCOME
3. Clicks "CONFIRM" (or presses Enter key)
4. If valid: items appear in inventory
   • Overflow drops at feet if inventory full
5. If invalid: error message displayed
   • Already used, expired, max uses reached, invalid code

Statistics shown in the GUI:

• Redeemed: 25/100 (25 of 100 available items claimed)
• Players: 10 (10 unique players have redeemed something)

---

Anti-Abuse Protection

Each player can redeem each code exactly once. This protection persists across:

• Name changes
• Multiple accounts on the same computer
• Server restarts
• Reinstalling the game

⚠️ Note: On offline-mode servers, users could theoretically use modified clients to bypass this. Server administrators should monitor usage and delete problematic codes if needed.

---

Data Storage

Redemption data is automatically saved to:

world_folder/promocodes_data.json

Contents:

• Which codes each player has redeemed
• Total redemptions per code
• Custom codes created via commands

Do not edit manually unless backing up. The mod manages this file automatically.

---

Real-World Examples

Example 1: Welcome Bonus

/promo create WELCOME minecraft:diamond,5 minecraft:iron_sword,1 minecraft:bread,20 0 0

• Unlimited uses
• Never expires
• Rewards: 5 diamonds, iron sword, 20 bread

Example 2: Anniversary Event (100 uses, expires 1 January 2026)

/promo create ANNIVERSARY minecraft:golden_apple,3 100 1735689600

Example 3: Complex Reward (3 items, 50 uses, never expires)

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

Example 4: Seasonal Giveaway (expires 31 December 2025)

/promo create XMAS minecraft:red_concrete,20 minecraft:green_concrete,20 minecraft:gold_block,5 0 1767225600

---

Troubleshooting

Issue: "Invalid item" error when creating a code

• Solution: Check the item ID spelling (e.g. minecraft:acacia_log not acacia log)

Issue: "Code already exists" when creating

• Solution: Delete the old code first: /promo delete OLDCODE

Issue: Player can't redeem, but code looks valid

• Solution: Check if:
  • Player already redeemed it (1 per player)
  • Code has expired (check expiryEpoch)
  • Max uses reached (check redemption count in /promo GUI stats)

Issue: Items aren't appearing in inventory

• Solution: Check inventory space. Overflow items drop at feet.

Issue: Server crashed after changing config

---

Compatibility

• Minecraft Version: 1.16.5
• Modloader: Forge
• Client/Server: Can be server and client (recommended)
• Offline Mode:
• Online Mode:

---

Known Limitations

• Maximum 3 items per code via simple command (use createraw for more)
• Item count limited to 1–64 per item
• No GUI for admins to create codes (use commands or config file)
• Codes are case-insensitive but stored in uppercase

---

Licence

Redistribution without credit is not permitted.

---