MC Plugin FlameOrders - Server Sync & Folia V1.1.2

Server synchronized Orders & Deliveries with Folia support

What is FlameOrders?

FlameOrders is a buy-order marketplace for survival, SMP, economy, and Donut-style servers.

A buyer chooses an item, quantity, unit price, expiry, and matching rules. The total payment is reserved through Vault. Other players can then deliver valid items to the order. Sellers receive their payout, while the requested items are stored safely for the buyer to collect from the claim stash.

The workflow is menu-driven, searchable, configurable, Folia-aware, and suitable for both one-server setups and MySQL-backed networks.

Main Features

• Buy-order marketplace — players request items instead of waiting for sellers to list them.
• Full order editor — configure material, quantity, unit price, expiry, note, partial fills, minimum partial quantity, enchantments, and exact matching.
• Public and personal views — the public browser shows other players' active orders by default; My Orders shows your own active and expired orders.
• Advanced browser — text search, categories, vanilla/custom item scope, enchantment filter, expired-order filter, and minimum/maximum total price.
• Eight sort modes — newest, oldest, most paid, most delivered, highest unit price, lowest unit price, most remaining, and expiring soon.
• Safe fulfillment preview — accepted and rejected items are shown before submission; only accepted items are consumed.
• Partial fills — allow full-only orders or define a minimum partial delivery amount.
• Claim stash — purchased items and overflow deliveries remain stored until the receiving inventory has enough room.
• Order lifecycle — open, partially filled, filled, cancelled, and expired states with version-safe mutations.
• History, rankings, and audit tools — player history, top sellers, order timelines, and staff audit menus.

Item Matching and Fulfillment
FlameOrders does not match items by material name alone.

• Vanilla material matching with optional exact metadata matching.
• Required enchantments and levels through the order editor.
• Custom item identities for ItemsAdder and Nexo.
• EcoEnchants support for custom enchantment requirements.
• Metadata-aware matching for names, lore, enchants, unbreakable state, leather colors, written books, fireworks, potions, and stored enchanted-book data.
• Configurable scan modes — inventory only, hotbar only, or inventory/hotbar with shulker contents.
• Optional shulker inspection limits and nested-container control.
• Vanilla equivalence handling where supported by the fulfillment matcher.

Order owners cannot fulfill their own orders. Orders must still be active and unexpired when the fill is submitted.

Economy and Settlement Safety

• Vault economy — the buyer's full order reserve is withdrawn when the order is created.
• Seller payouts — successful deliveries create tracked money settlements.
• Cancellation and expiry refunds — unused reserve is returned through the settlement system.
• Offline payouts and refunds — enabled by default when the economy provider supports them.
• Idempotent mutations — duplicate create, fill, cancel, claim, and admin operations are guarded at storage level.
• Interaction locks — reduce duplicate-click and concurrent menu submission problems.
• Claim-before-delivery checks — Collect All only removes entries that can fully fit in the player's inventory.

Menus and Customization

• Orders browser and advanced filter menu.
• Order detail, timeline, editor, material selector, and enchantment selector.
• Fulfillment workspace with accepted/rejected preview.
• Claim stash with pagination and Collect All.
• Player history and top-fill rankings.
• Admin audit browser and order action menu.
• MiniMessage/Adventure titles, item names, lore, chat messages, sounds, and effects.
• Bundled presentation presets: Default Clean, Donut V1, and Flame Donut.
• Safe presentation reload without restarting the server.

Storage and Network Modes

• SQLite — default local storage with no external database setup.
• MySQL and MariaDB — shared SQL storage using HikariCP.
• LOCAL — single-server SQLite mode.
• MYSQL_TTL — MySQL/MariaDB with short-lived query caching and polling.
• MYSQL_REDIS — Redis pub/sub and SQL outbox coordination for real-time multi-server cache invalidation.
• Automatic schema management — idempotent table/index creation and legacy-state rebuilding.
• Async database work — SQL operations run through dedicated executors instead of the server thread.

For MYSQL_REDIS, every server sharing the database must use the same Redis instance, channel, and sequence key. Mixed Redis and non-Redis nodes can desynchronize the shared order-view cache.

Integrations

• Vault — required for live money operations with the default configuration.
• PlaceholderAPI — player order and ranking statistics.
• ItemsAdder — custom item identity matching and search tokens.
• Nexo — custom item identity matching and search tokens.
• EcoEnchants — strict custom enchantment matching.
• Discord webhooks — created, filled, completed, cancelled, expired, and admin-action events.
• Modrinth update checker — optional console and administrator notifications.

Commands
Main command aliases: /orders, /order, /market, /flameorders

• /orders — open the orders browser.
• /orders help — show command help.
• /orders browse — open the public orders browser.
• /orders search <query> — open the browser with a text search.
• /orders my — open your own orders.
• /orders create — open the order editor.
• /orders create <quantity> <unitPrice> [expiryHours] — create directly from the item in your main hand.
• /orders claim — open your claim stash.
• /orders history [filled|claimed|cancelled|expired] — open filtered player history.
• /orders top [cash|amount] — rank sellers by earned money or delivered quantity.
• /orders preset list — list bundled and installed presentation presets.
• /orders preset apply <id> — apply a preset and reload presentation files.
• /orders admin — open the audit browser.
• /orders admin audit — open the audit browser.
• /orders admin reload — reload presets and presentation configuration.
• /orders admin cancel <order-uuid> <reason...> — force-cancel the remaining order quantity.
• /orders admin expire <order-uuid> <reason...> — expire an order immediately.

Quantity and price inputs accept normal numbers and the suffixes k, m, and b. Example: 64, 2.5k, 1m.

Permissions

• flameorders.use — use the root command and marketplace. Default: true.
• flameorders.create — create orders. Default: true.
• flameorders.claim — declared claim-access node. Default: true.
• flameorders.top — declared top-statistics node. Default: true.
• flameorders.admin — full administration; grants audit and mutation children. Default: op.
• flameorders.admin.audit — view administrative audit data and order details. Default: false.
• flameorders.admin.mutate — reload presentation, apply presets, cancel orders, and expire orders. Default: false.
• flameorders.limit.<number> — set a player's maximum active-order limit. The highest granted number wins.
• flameorders.limit.unlimited — remove the active-order limit.

Operators and users with flameorders.admin receive an unlimited active-order limit. The current command routing uses flameorders.use as the effective root gate for /orders claim and /orders top; the dedicated claim/top nodes remain declared. Reload uses flameorders.admin.mutate—there is no separate flameorders.admin.reload permission in the current build.

PlaceholderAPI Placeholders

• %flameorders_active_orders% — active orders created by the player.
• %flameorders_claim_entries% — available claim-stash entries.
• %flameorders_filled_quantity% — total quantity delivered by the player.
• %flameorders_net_earned% — total net earnings.
• %flameorders_top_cash_position% — cash leaderboard position, blank when unranked.
• %flameorders_top_quantity_position% — quantity leaderboard position, blank when unranked.

Developer Events
FlameOrders exposes normal Bukkit events for custom integrations:

• FlameOrderCreatedEvent
• FlameOrderFilledEvent
• FlameOrderCancelledEvent
• FlameOrderClaimedEvent
• FlameOrderExpiredEvent
• FlameOrderAdminActionEvent

Important Setup Notes

• Install Vault and a compatible economy provider before opening the marketplace to players.
• SQLite is ready by default. Configure storage.yml for MySQL or MariaDB.
• Use MYSQL_TTL for database-backed polling without Redis.
• Use MYSQL_REDIS only when every connected server has matching Redis and database settings.
• Hold the intended item before creating an order. The direct command always builds the matcher from the main-hand item.
• Exact matching is stricter than material matching and may include item metadata and enchantment requirements.
• By default, the public browser excludes the viewer's own orders and My Orders includes expired entries.

FAQ

What type of server is FlameOrders for?
Survival, economy, SMP, competitive SMP, and Donut-style servers where players need a structured item-demand marketplace.

Does it support Folia?
Yes. Player, region, global, and asynchronous work is routed through Bukkit/Paper/Folia scheduler bridges.

Does it require MySQL or Redis?
No. SQLite and LOCAL mode are the defaults. MySQL, MariaDB, and Redis are optional network features.

Can players order custom items?
Yes. ItemsAdder and Nexo identities are supported, with optional EcoEnchants matching.

Can menus and messages be changed?
Yes. Menus, item definitions, filters, messages, sounds, effects, and presentation presets are stored in editable YAML files.