NexusContracts - Escrow Quest System v1.1.0

What is NexusContracts?

NexusContracts places a shared contract board on your server where two entirely different contract types coexist. Virtual factions — configurable guilds with no physical NPC entities — post ongoing system contracts for item delivery, mob hunting, and crafting. Players can also post their own requests, putting up a real Vault escrow that pays out automatically on delivery — as a fixed-reward contract, a live or sealed-bid auction, or a multi-stack bundle lot.

The reward is held the moment a player contract is posted. Nobody walks away empty-handed after a crash or a rage-quit: escrow is reconciled on every server startup, and cancelling a contract always refunds the poster. Abandoning an accepted contract triggers a configurable penalty — keeping the board honest. Around it all sits an append-only audit log, per-action rate limiting, and an anti-abuse pairing heuristic, so the market stays clean as it scales.

Result: a living economy layer where players have a reason to go mining, hunt mobs, fire up their crafting table, outbid a rival, or hunt a bounty every session — driven entirely by config, without writing a single line of code.


Dependency Stack

• Vault (optional — strongly recommended): enables all money-based escrow, auctions, bounties, insurance, payouts, and penalties. Without Vault, item- and command-reward contracts still work fully.
• PlaceholderAPI (optional): exposes %nexus_... placeholders — rank, per-faction rep, lifetime stats, active contract name, total earned, and the new leaderboard placeholders — to scoreboards, chat formatters, and any other PAPI-aware plugin.

NexusContracts starts and runs without either dependency — Vault and PAPI are detected at runtime and enabled automatically when present.


Main Feature Set

• Dual contract board: System Contracts (faction-issued, always restocked) and Player Contracts (player-posted, escrowed) live on one paginated GUI with separate tabs.
• Vault escrow engine: reward money is withdrawn from the poster on creation and held safely — crash-safe reconciliation on startup ensures nothing is ever lost or double-paid.
• Auction house: post a contract as a live auction, a sealed-bid auction (hidden bids, highest wins), or a multi-stack bundle — with an optional instant buyout price to end it early.
• PvP bounties: place a bounty on any player; multiple placements pool, and a single valid PvP kill pays the whole pool to the killer. Unclaimed bounties expire and refund.
• Insurance policies: players buy coverage against death or contract failure, paying premiums into a pool that pays out automatically when a trigger fires.
• GUI delivery: contractors deposit items into a submission GUI and confirm — no passive block or pickup tracking. Fully Folia-safe by design.
• Faction reputation system: each faction tracks reputation separately. Higher factions are reputation-gated; players must earn their way up.
• Faction diplomacy: factions form alliances (reputation spillover) or go to war (reputation penalty for working with the enemy), set in config or live by command.
• Global rank tiers: total reputation maps to a config-driven rank ladder (Novice → Grandmaster). Promotion fires a PlayerRankUpEvent and can run any console command.
• Leaderboards: ranked boards for per-faction reputation, contracts completed, and total trade volume, cached on a timer and exposed through PAPI.
• Mission chains: each faction can define sequential multi-step chains with requires-chain dependencies. Chain contracts are only visible to the qualifying player.
• Counter-offer system: when a player contract is posted, competitors can submit a counter-offer; the poster accepts or rejects via a one-click GUI.
• Group contracts: multiple players can join a single contract and split the reward automatically on completion.
• Watchlist: players subscribe to specific materials; they receive a notification the moment a matching contract appears on the board.
• Price suggestions: the PriceSuggestionService analyses recent contract history and surfaces a recommended price range when creating a player contract.
• Reputation decay: configurable linear or percentage decay for inactive players, with a grace period and a floor — keeps the leaderboard competitive without over-punishing.
• Audit log & anti-abuse: an append-only, exportable record of every money/admin action, plus per-action rate limiting and a suspicious-pairing review list.
• Schema-safe upgrades: the database is version-checked on startup and automatically backed up before any migration runs — a failed backup aborts rather than risking data.
• Pluggable persistence: SQLite (zero-config default), H2, MySQL, or MariaDB — switch with one config line. HikariCP handles connection pooling; all DB I/O is async.
• MiniMessage everywhere: every message, faction display name, and rank label uses full MiniMessage syntax — gradients, hex colours, hover events, all supported.
• Full localization: all player-facing text lives in messages_en.yml (or any language file you create). Hot-reloadable with /nexuscontracts reload.
• Discord webhooks: configurable embeds fire on high-value postings, completions, rank-ups, buyouts, bounties, insurance payouts, alliances, wars, and anti-abuse alerts — each individually toggleable.
• Public Java API: NexusContractsAPI exposes contract lookup, cancellation, stat snapshots, reputation reads, and rank resolution for other plugins to hook into.
• bStats metrics: anonymous usage statistics, opt-out anytime by disabling bStats globally.

Contract Types






Reward Grammar

All faction reward pools and step rewards use a simple string grammar:

• MONEY:RANGE:\<min\>:\<max\> — random amount between min and max, e.g. MONEY:RANGE:2000:6000.
• ITEM:\<material\>;\<custom-model-data\>;\<amount\> — gives a specific item; use 0 for no CMD.
• COMMAND:\<command\> — runs a console command; <player> is replaced with the contractor's name.

Commands & Permissions

• /contracts (aliases: /nc, /contract): open the contract board.
• /contracts create [material]: open the creation GUI; uses held item if material is omitted.
• /contracts deliver: open the submission GUI for your active contract.
• /contracts abandon: forfeit your active contract (penalty may apply).
• /contracts info: show progress and time remaining on your active contract.
• /contracts search: filter the board by keyword or material.
• /contracts history: view your completed and failed contract history.
• /contracts bounty \<place|list|cancel\>: place a PvP bounty, browse the active pool, or (admin) cancel one.
• /contracts insurance \<buy|list|cancel\>: buy a policy, list your active policies, or cancel one.
• /nexuscontracts reload (alias: /ncadmin): hot-reload config, language files, and faction definitions.
• /nexuscontracts version: print plugin version, DB backend, and scheduler platform.
• /nexuscontracts list: list all currently active contracts.
• /nexuscontracts force-complete \<id\> / force-expire \<id\>: admin-force a contract to completion or expiry.
• /nexuscontracts audit \<player|contract|export\>: query or export the audit log.
• /nexuscontracts antiabuse \<review|clear|exempt\>: manage the suspicious-pairing review list.
• /nexuscontracts schema \<version|backup-now\>: check the schema version or take a manual backup.
• /nexuscontracts faction relation \<set|list|clear\>: manage faction diplomacy.
• /nexuscontracts import \<file.csv\> [--commit]: import reputation from a CSV (dry-run by default).

Permissions: nexuscontracts.use (everyone) for board access and accepting; nexuscontracts.create (everyone) for posting player contracts; nexuscontracts.admin (op) for all administrative commands; nexuscontracts.ratelimit.bypass (staff) to skip anti-abuse rate limits. Posting tier caps are controlled by nexuscontracts.tier.default / .donor / .vip.


PlaceholderAPI Placeholders

• %nexus_rank%: the player's current rank key (e.g. expert), or none.
• %nexus_rank_display%: formatted rank name, deserialized to a legacy color string.
• %nexus_total_rep%: summed reputation across all factions.
• %nexus_rep_\<faction\>%: reputation with a single faction (e.g. %nexus_rep_miners_guild%).
• %nexus_active_contract%: name of the player's currently active contract, or None.
• %nexus_contracts_completed%: lifetime completed contracts.
• %nexus_contracts_failed%: lifetime failed/expired contracts.
• %nexus_contracts_posted%: lifetime posted player contracts.
• %nexus_total_earned%: lifetime money earned, formatted by your economy plugin.
• %nexus_lb_\<faction\>_\<rank\>_name% / _value%: the player name and reputation at a given leaderboard rank.
• %nexus_lb_global_\<category\>_\<rank\>_name% / _value%: server-wide boards for contracts_completed and trade_volume.

Why Choose NexusContracts?

• Crash-safe escrow: money is reconciled on every startup — no silent duplication, no lost funds, even after an unexpected shutdown.
• Schema-safe upgrades: the database backs itself up before every migration, and a failed backup aborts the upgrade instead of risking your data.
• Zero entity setup: factions are pure config — no spawning NPCs, no Citizens dependency, no region setup.
• Folia-native: declared folia-supported: true; all scheduling goes through a transparent abstraction that targets Folia region/async schedulers or falls back to the Bukkit scheduler automatically.
• One board, many markets: system quests, player trading, auctions, bounties, and insurance coexist without separate plugins or conflicting commands.
• Built to stay clean: rate limiting, an audit trail, and a pairing heuristic give you the tools to spot and stop market abuse before it spreads.
• Scales with your server: swap SQLite for MySQL/MariaDB in one config line. HikariCP pools connections; all DB I/O is fully async.
• No reloads needed for most changes: /nexuscontracts reload hot-swaps config, messages, factions, and chains without a restart.

FAQ

Do I need Vault?
No — but without Vault, money-based rewards, escrow, auctions, bounties, and insurance are disabled. Item and command rewards work fine without it.

Do the new systems require setup?
No. Auctions, bounties, insurance, diplomacy, leaderboards, and anti-abuse all ship disabled by default — enable and tune each in config.yml when you want it.

Is Folia supported?
Yes. NexusContracts declares folia-supported: true and routes all scheduling through an abstraction layer that works identically on Paper, Purpur, and Folia.

Which databases are supported?
SQLite (bundled, zero-config), H2 (bundled), MySQL, and MariaDB. Set database.type in config.yml. New tables and columns migrate automatically — with an automatic pre-migration backup.

Can I translate the plugin?
Yes. All messages live in messages_en.yml. Copy it, rename it (e.g. messages_de.yml), translate, and point language in config.yml at it.

What happens to escrow money if the server crashes?
On the next startup, the ContractManager runs a reconciliation pass that compares in-memory state to the database and corrects any discrepancy before the board opens.

Can other plugins hook into NexusContracts?
Yes. The NexusContractsAPI interface exposes contract lookup, stat snapshots, reputation reads, rank resolution, and contract cancellation. It is available via NexusContracts.getApi().




minecraft contracts plugin, quest plugin, economy plugin, auction house plugin, bounty plugin, insurance plugin, faction reputation, escrow plugin, folia plugin, vault economy, paper plugin, player contracts, delivery quest, contract board, leaderboard, nexuscontracts.