MPromoCodes

Simple, powerful & Folia-ready promo code system for Minecraft servers

MPromoCodes is a lightweight yet flexible promo code plugin that allows players to redeem reward codes using a simple command. It supports fully configurable rewards, conditions, Discord webhook logs, separated promo code files and multiple storage types including YAML, SQLite and MySQL.

All rewards are executed safely on Bukkit, Spigot, Paper, Purpur and Folia servers.

---

✨ Features

• Redeem promo codes using /code
• Promo codes are stored in a separate codes.yml file
• Fully configurable rewards
• In-Game Admin Menu
• Supports console and player command execution
• Built-in message system using message:
• Optional Title & Subtitle messages after successful redemption
• Per-player code usage
• One-time codes and multi-use codes
• Global use limits
• Per-player use limits
• Code cooldown support
• 20+ Conditions for many different use cases
• Supports start-date and expiry-date codes
• Permission-based code access
• Configurable code input rules
• Case-insensitive code support
• Configurable minimum and maximum code length
• Anti-spam protection for failed redeem attempts
• Discord webhook integration
• Webhook logs for successful and failed redemptions
• /codes webhook test command
• Storage support:
  • YAML
  • SQLite
  • MySQL
• Automatic migration from old config.yml codes to codes.yml
• Automatic migration from YAML redeemed data to SQL storage
• Safe async execution using a custom TaskManager
• Folia-compatible execution
• Clean and organized configuration

---

🧾 Example Code Configuration

Promo codes are now stored in codes.yml.

codes:
  WELCOME:
    enabled: true
    once-per-player: true
    global-use: 3
    per-player-use-limit: -1
    cooldown: ""
    permission-required: ""
    start-date: "25/12/2025 00:00"
    expiry-date: "31/12/2025 23:59"

    title:
      enabled: true
      main: "&aCode Redeemed!"
      sub: "&7You used: &fWELCOME"
      fade-in: 10
      stay: 40
      fade-out: 10

    commands:
      - "console: give %player% diamond 2"
      - "message: &aYou have successfully redeemed the &fWELCOME &acode!"

---

⚙️ Example Plugin Settings

General plugin settings are stored in config.yml.

settings:
  enabled: true
  server-name: "survival"
  debug: false
  case-insensitive-codes: true
  trim-code-input: true
  min-code-length: 2
  max-code-length: 32
  use-permission: "mpromocodes.use"

anti-spam:
  enabled: true
  failed-attempt-cooldown: "3s"
  max-failed-attempts: 5
  block-time: "1m"
  reset-on-success: true
  webhook-log-blocked-attempts: true

storage:
  type: "SQLITE"
  auto-migrate-yaml: true

  sqlite:
    file: "storage.db"

  mysql:
    host: "localhost"
    port: 3306
    database: "mpromocodes"
    username: "root"
    password: "password"
    use-ssl: false
    table-prefix: "mpromocodes_"

---

🔗 Discord Webhook Integration

MPromoCodes can send detailed logs directly to your Discord staff channel.

Webhook logs can include:

• Successful code redemptions
• Failed redemption attempts
• Invalid codes
• Expired codes
• Already used codes
• Missing permissions
• Global limit reached
• Conditions not met

You can also test your webhook directly in-game:

/codes webhook test

Webhook embeds support configurable colors, username, avatar, footer and mention protection.

---

🗄 Storage System

MPromoCodes supports multiple storage backends:

• YAML — simple file-based storage
• SQLite — recommended for most single-server setups
• MySQL — recommended for larger setups and database-based storage

Existing redeemed.yml data can be automatically migrated to SQLite or MySQL when enabled.

storage:
  type: "SQLITE"
  auto-migrate-yaml: true

---

🔄 Automatic Migration

When updating from an older version, MPromoCodes can automatically move existing promo codes from config.yml to the new codes.yml file.

On first startup after updating:

• Existing codes: from config.yml are moved to codes.yml
• The old config is backed up as config-old.yml
• A fresh config.yml is generated
• Existing redeemed data can be migrated to SQLite or MySQL

This keeps old setups safe while allowing the plugin to use the new cleaner file structure.

---

🛡 Anti-Spam Protection

MPromoCodes includes built-in anti-spam protection for failed redeem attempts.

You can configure:

• Failed attempt cooldown
• Maximum failed attempts
• Temporary block time
• Reset on successful redeem

This helps protect your server and Discord webhook logs from spam.

---

🛠 Commands

• /code <code> - Redeem a promo code
• /codes reload - Reload configuration and code files
• /codes stats - Show information about your redeemed codes
• /codes menu - Opens the Admin Menu
• /codes webhook test - Sends a test Discord webhook

---

🔐 Permissions

• mpromocodes.use - Allows players to redeem codes
• mpromocodes.admin - Allows admin commands
• mpromocodes.admin.webhook - Allows testing Discord webhooks

The redeem permission can also be changed in config.yml:

settings:
  use-permission: "mpromocodes.use"

---

🧠 How It Works

Promo codes are defined in codes.yml.

Each code can:

• Run multiple rewards
• Execute console commands
• Execute player commands
• Send built-in plugin messages
• Be restricted by permission
• Have a start date
• Have an expiry date
• Be used once per player
• Be used multiple times
• Have global use limits
• Have per-player use limits
• Have cooldowns
• Display a title and subtitle
• Use advanced redeem conditions

Redeemed code data is safely stored using the selected storage type.

All actions are executed in a Folia-safe way using safe scheduling.

---

🚀 Server Compatibility

✅ Bukkit

✅ Spigot

✅ Paper

✅ Purpur

✅ Folia

✅ Java 17+

---

📦 File Size Notice

The plugin .jar file is larger in this version because MPromoCodes now includes built-in SQLite and MySQL database support.

To make setup easier for server owners, the required database drivers are included directly inside the plugin file. This means you do not need to download or install any extra libraries for SQLite or MySQL support.

The increased file size is expected and is caused by the bundled SQL database drivers, especially the SQLite driver, which contains native libraries for multiple operating systems.

In short:

• The larger file size is normal
• No extra installation is required
• SQLite and MySQL work out of the box
• YAML storage is still supported

---

💡 Why MPromoCodes?

Unlike simple command-based promo code plugins, MPromoCodes:

• Uses a clean separated codes.yml system
• Supports Discord webhook logging
• Supports YAML, SQLite and MySQL storage
• Can automatically migrate old configs and redeemed data
• Avoids vanilla command abuse
• Works with Folia-safe scheduling
• Keeps configuration readable and maintainable
• Is ideal for events, rewards, VIP promotions, giveaways and server launches

---

❤️ Final Words

MPromoCodes was built with performance, clarity and future compatibility in mind.

If you are looking for a clean promo code solution with modern storage, Discord logging and Folia-ready execution — this is it.

---

📊 Stats

https://bstats.org/plugin/bukkit/MPromoCodes