MPromoCodes v1.6 — Production, Monitoring & Localization Update

This is the largest MPromoCodes update so far. It combines a complete production-focused code rework with new health monitoring, optional spark integration, full localization support, safer storage operations, improved Folia compatibility, and many reliability improvements for large servers.

Requirements: Java 25 and Paper/Folia 26.1

Added

Health Check & Monitoring

• Added the new /codes health command.
• Added the new mpromocodes.admin.health permission.
• Added optional integration with the public spark API.
• When spark is installed, the health report includes:
  • TPS
  • Average and 95th percentile MSPT
  • Process CPU usage
  • System CPU usage
• Added automatic Paper/JVM fallback metrics when spark is not installed.
• Added MPromoCodes-specific performance metrics:
  • Recent redemption attempts
  • Successful redemptions
  • Rejected redemptions and errors
  • Average and 95th percentile redemption latency
  • Average and 95th percentile storage latency
  • Average and 95th percentile reward latency
  • Measured Paper/Folia server-thread time
  • MPromoCodes server-thread share percentage
• Added JVM heap memory usage to the health report.
• Added storage reachability and ping checks.
• Added SQL worker queue and HikariCP pool statistics.
• Added Discord webhook in-flight request and capacity statistics.
• Added loaded-code and pending-player statistics.
• Added configurable warning and critical thresholds for TPS, MSPT, CPU, plugin server-thread share, and storage latency.
• Health metrics are collected on demand. The monitoring system does not create a permanent polling task.

Localization

• Added complete English localization in lang/en_US.yml.
• Added complete Slovak localization in lang/sk_SK.yml.
• Added automatic language selection based on the player's Minecraft client locale.
• Added configurable default and fallback locales for the console and unsupported client languages.
• Added support for additional custom locale files in the lang directory.
• Moved all player-facing and administrator-facing UI text to localization files, including:
  • Redemption messages
  • Validation and error messages
  • Admin chat prompts
  • Inventory titles
  • Item names and lore
  • Update notifications
  • Health reports
  • Discord webhook text
• Preserved legacy & color and formatting codes.
• Added automatic merging of newly introduced language keys without overwriting existing customized values.
• Added a safe one-time migration of old config.yml messages into the configured default locale file.

Promo Code & Developer Features

• Added configurable per-player use limits.
• Added player use counts, last-use dates, and active cooldowns to /codes stats.
• Added PromoCodePreRedeemEvent for cancellable pre-redemption integrations.
• Added PromoCodeRedeemEvent after a successful atomic storage reservation.
• Added sequential reward execution with %player%, %uuid%, and %code% placeholders.
• Added stricter validation for dates, durations, conditions, materials, advancements, and statistics.

Changed

• Reworked the complete internal redemption flow for production use.
• Player data is now handled using UUID-based records instead of relying only on player names.
• Storage operations now reserve redemptions atomically before rewards are executed.
• Global and per-player limits are now safe during concurrent redemption attempts.
• Promo code definitions are parsed once into an immutable validated runtime registry.
• Invalid promo code definitions are rejected instead of becoming partially active.
• Reloads now validate and replace runtime definitions safely.
• Existing active definitions remain available when a reload fails.
• Reward entries now run sequentially on the correct Paper/Folia scheduler.
• Player operations, global console commands, callbacks, and GUI reopen operations now use Folia-aware scheduling.
• The admin GUI now uses typed inventory holders instead of identifying menus by inventory titles or item display names.
• Admin menus now read and write promo codes through the centralized codes.yml manager.
• Update notifications now use the player's selected language.
• Discord webhook labels, titles, reasons, and status text are now configurable through locale files.
• The plugin version has been updated to 1.6.

Improved

• Improved performance and safety for large servers.
• Improved MySQL concurrency using transactions and row locking.
• Improved MySQL connection management using HikariCP.
• Improved protection against database outages with bounded SQL worker queues.
• Improved SQLite performance and concurrency using WAL mode and a bounded asynchronous worker.
• Improved YAML storage with debounced saves, temporary files, and atomic file replacement where supported.
• Improved legacy player-data migration from lowercase names to UUID records.
• Improved fail-closed behavior when storage is unavailable.
• Improved Discord webhook delivery with request timeouts, bounded in-flight work, and retry handling for rate limits and server errors.
• Improved anti-spam protection and failed-attempt handling.
• Improved code organization by separating configuration, storage, services, menus, localization, monitoring, API events, and integrations.
• Improved Paper API compatibility by replacing old chat, title, and item metadata handling with Adventure components.
• Improved build reliability with Java/Maven version enforcement and stricter compiler warnings.
• Improved OneDrive compatibility for mvn clean on Windows.
• Preserved customized message colors and formatting during the localization rework.
• Removed unused utilities, old task code, obsolete configuration classes, and other dead code.

Fixed

• Fixed race conditions that could allow global or per-player limits to be overspent.
• Fixed stale in-memory storage state on larger or multi-instance setups.
• Fixed unbounded memory growth during SQL outages by using bounded queues.
• Fixed unsafe Bukkit API access from asynchronous threads.
• Fixed several Folia scheduler and player-region compatibility issues.
• Fixed invalid definitions being partially loaded after configuration errors.
• Fixed reload failures replacing valid active definitions.
• Fixed admin inventories depending on localized or customized inventory titles.
• Fixed menu actions depending on item display names.
• Fixed several mismatched advancement/statistic admin-menu slots.
• Fixed hardcoded admin, GUI, update, webhook, and player messages.
• Fixed Maven clean failures caused by locked/read-only OneDrive-generated directories where force cleanup is supported.

Commands & Permissions

• /code <code> — redeem a promo code (mpromocodes.use)
• /codes stats — view personal promo code statistics
• /codes menu — open the admin menu (mpromocodes.admin)
• /codes reload — reload and validate the plugin (mpromocodes.admin)
• /mpromocodes reload — reload and validate the plugin (mpromocodes.admin)
• /codes health — display the health report (mpromocodes.admin.health)
• /codes webhook test — send a Discord webhook test (mpromocodes.admin.webhook)

Migration Notes

• Back up the MPromoCodes data folder or database before updating.
• Replace the old plugin JAR with MPromoCodes-1.6.jar and restart the server.
• Existing codes.yml and redeemed-player data remain compatible.
• Existing YAML data can still be migrated automatically to SQLite or MySQL when storage.auto-migrate-yaml is enabled and the target database is empty.
• On the first start, existing custom messages from config.yml are copied into the configured default locale file.
• Existing customized locale values are preserved. Only missing bundled keys are added automatically.
• The old config.yml message section is no longer used after migration; messages should now be edited in plugins/MPromoCodes/lang.
• Legacy & colors continue to work exactly as before.
• spark is optional. If it is not installed, MPromoCodes automatically uses Paper/JVM fallback metrics.
• Servers sharing one MySQL database must use the same codes.yml definitions on every instance.

New Configuration Sections

localization:
  default-locale: "en_US"
  fallback-locale: "en_US"
  use-client-locale: true

monitoring:
  enabled: true
  spark-integration: true
  sample-window-seconds: 60

  thresholds:
    tps-warning: 18.0
    tps-critical: 15.0
    mspt-warning: 40.0
    mspt-critical: 50.0
    cpu-warning-percent: 80.0
    cpu-critical-percent: 95.0
    plugin-main-thread-warning-percent: 1.0
    plugin-main-thread-critical-percent: 3.0
    storage-p95-warning-ms: 50.0
    storage-p95-critical-ms: 200.0

Monitoring Notes

• CPU, TPS, and MSPT values use the public spark API when spark is available.
• The MPromoCodes server-thread percentage is measured directly by MPromoCodes and is separate from the percentage shown for a node in spark's sampling-profiler call tree.
• On Folia, the metric includes measured region-thread and global-region work performed by MPromoCodes.
• A low MPromoCodes percentage with high server MSPT usually means the lag is coming from another plugin, world activity, entities, chunks, or the server itself.

Why Is the Plugin File Still Large?

MPromoCodes includes the SQLite and MySQL database drivers directly inside the plugin JAR. This allows server owners to use SQL storage without installing additional libraries.

The native SQLite libraries support multiple operating systems and are responsible for most of the file size. This is expected and does not increase normal runtime memory usage by the full JAR size.