# PromoCode 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. Edit `server_config/promocodemod-server.toml` to add default codes (optional) 5. 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

   [maxUses] [expiryEpoch]
/promo create      [item3] [count3] [maxUses] [expiryEpoch]
/promo createraw 
```

**Delete Code:**
```
/promo delete 
```

**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](https://www.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

Edit `server_config/promocodemod-server.toml`:

```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:** `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
- **Solution:** Check `promocodemod-server.toml` for syntax errors. Item IDs must be valid.

---

## 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.

---

M4riosDev

M4riosDev

Roleplay Chats

BetterRewards